satteri 0.10.5 → 0.11.3

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

@@ -0,0 +1,18 @@
+import { LazyChildResolver, type EpochCache } from "../lazy-child-resolver.js";
+import { type NodeRefs } from "../visitor-shared.js";
+import { type HastNode } from "./hast-materializer.js";
+import { HastReader } from "./hast-reader.js";
+export declare function getNodeId(node: HastNode, refs: NodeRefs): number | undefined;
+export interface WalkWire {
+    view: DataView;
+    buf: Uint8Array;
+    resolver: HastLazyChildResolver;
+}
+export declare function readMatchedNode(wire: WalkWire, offset: number, nodeId: number, nodeType: number): HastNode;
+export declare class HastLazyChildResolver extends LazyChildResolver<HastReader, HastNode> {
+    protected cacheSlot(): WeakMap<globalThis.AnyHandle, EpochCache<HastReader>>;
+    protected createReader(wire: Uint8Array): HastReader;
+    protected materializeNode(reader: HastReader, nodeId: number, refs: NodeRefs): HastNode;
+    protected readParentId(reader: HastReader, nodeId: number): number;
+    protected readChildIds(reader: HastReader, nodeId: number): number[];
+}

package/dist/hast/hast-walk.js

@@ -0,0 +1,264 @@
+import { parseEsm as napiParseEsm, parseExpression as napiParseExpression } from "#binding";
+import { LazyChildResolver, registerEpochCacheSlot, } from "../lazy-child-resolver.js";
+import { VisitorNode } from "../visitor-node.js";
+import { crossPipelineForeign, FOREIGN_REF } from "../visitor-shared.js";
+import { readPosition, rstr } from "../wire-read.js";
+import { HastChildStub } from "./child-stub.js";
+import { TYPE_NAMES } from "./generated/node-types.js";
+import { decodeWalkElementProps, readWalkElementTag, readWalkHastValue, readWalkMdxJsx, walkElementPropCount, walkElementPropsAt, } from "./generated/walk-decode.js";
+import { materializeHastNode } from "./hast-materializer.js";
+import { HAST_COMMENT, HAST_ELEMENT, HAST_MDX_ESM, HAST_MDX_FLOW_EXPRESSION, HAST_MDX_JSX_ELEMENT, HAST_MDX_JSX_TEXT_ELEMENT, HAST_MDX_TEXT_EXPRESSION, HAST_RAW, HAST_ROOT, HAST_TEXT, HastReader, } from "./hast-reader.js";
+function attachParseExpression(node, parseFn) {
+    Object.defineProperty(node, "parseExpression", {
+        value() {
+            const value = this.value;
+            if (typeof value !== "string")
+                return null;
+            const json = parseFn(value);
+            if (json == null)
+                return null;
+            return JSON.parse(json);
+        },
+        writable: false,
+        enumerable: false,
+        configurable: true,
+    });
+}
+// Spread copies must be treated as new content, not as references to the original arena node.
+export function getNodeId(node, refs) {
+    if (node instanceof WalkElement)
+        return node._refs === refs ? node._nid : FOREIGN_REF;
+    if (node instanceof HastChildStub)
+        return node._refs === refs ? node._id : FOREIGN_REF;
+    const id = VisitorNode.getNodeId(node, refs) ?? refs.get(node);
+    if (id !== undefined)
+        return id;
+    const d = Object.getOwnPropertyDescriptor(node, "_nodeId");
+    if (d !== undefined && !d.enumerable)
+        return FOREIGN_REF;
+    return crossPipelineForeign(node);
+}
+function readChildStubs(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(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]);
+    }
+    return stubs;
+}
+// Shared getters need a static block to access private wire fields.
+let WALK_PROPS_DESC;
+let WALK_CHILDREN_DESC;
+// Private wire fields preserve spread identity without the GC cost of a WeakMap entry per element.
+class WalkElement {
+    type = "element";
+    tagName;
+    #nodeId;
+    #wire;
+    #propsPos;
+    #childIdsPos;
+    #childTypesPos;
+    #childCount;
+    constructor(tagName, nodeId, wire, propsPos, propCount, childIdsPos, childTypesPos, childCount) {
+        this.tagName = tagName;
+        this.#nodeId = nodeId;
+        this.#wire = wire;
+        this.#propsPos = propsPos;
+        this.#childIdsPos = childIdsPos;
+        this.#childTypesPos = childTypesPos;
+        this.#childCount = childCount;
+        if (propCount === 0) {
+            this.properties = {};
+        }
+        else {
+            Object.defineProperty(this, "properties", WALK_PROPS_DESC);
+        }
+        if (childCount === 0) {
+            this.children = [];
+        }
+        else {
+            Object.defineProperty(this, "children", WALK_CHILDREN_DESC);
+        }
+    }
+    /** @internal */
+    get _nid() {
+        return this.#nodeId;
+    }
+    /** @internal */
+    get _refs() {
+        return this.#wire.resolver.refs;
+    }
+    static {
+        WALK_PROPS_DESC = {
+            enumerable: true,
+            configurable: true,
+            get() {
+                const w = this.#wire;
+                const val = decodeWalkElementProps(w.view, w.buf, this.#propsPos);
+                Object.defineProperty(this, "properties", {
+                    value: val,
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                });
+                return val;
+            },
+        };
+        WALK_CHILDREN_DESC = {
+            enumerable: true,
+            configurable: true,
+            get() {
+                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,
+                    enumerable: true,
+                    configurable: true,
+                });
+                return val;
+            },
+        };
+    }
+}
+function readElementFromBinary(wire, offset, nodeId, position, childIdsPos, childTypesPos, childCount, data) {
+    // Visitors almost always read tagName, so decode it eagerly.
+    const tagName = readWalkElementTag(wire.view, wire.buf, offset);
+    const pos = walkElementPropsAt(wire.view, offset);
+    const propCount = walkElementPropCount(wire.view, pos);
+    const node = new WalkElement(tagName, nodeId, wire, pos, propCount, childIdsPos, childTypesPos, childCount);
+    if (position !== undefined)
+        node.position = position;
+    if (data !== null)
+        node.data = data;
+    return node;
+}
+function readTextFromBinary(view, buf, offset, nodeId, nodeType, position, data, refs) {
+    const value = readWalkHastValue(view, buf, offset, nodeType);
+    const base = new VisitorNode(TYPE_NAMES[nodeType] ?? `unknown(${nodeType})`, refs, nodeId);
+    base.value = value;
+    if (position !== undefined)
+        base.position = position;
+    if (data !== null)
+        base.data = data;
+    const node = base;
+    if (nodeType === HAST_MDX_FLOW_EXPRESSION || nodeType === HAST_MDX_TEXT_EXPRESSION) {
+        attachParseExpression(node, napiParseExpression);
+    }
+    else if (nodeType === HAST_MDX_ESM) {
+        attachParseExpression(node, napiParseEsm);
+    }
+    return node;
+}
+function readMdxJsxFromBinary(view, buf, offset, nodeId, nodeType, resolver, position, childIdsPos, childTypesPos, childCount, data) {
+    const { name, attributes } = readWalkMdxJsx(view, buf, offset);
+    const typeName = nodeType === HAST_MDX_JSX_ELEMENT ? "mdxJsxFlowElement" : "mdxJsxTextElement";
+    const base = new VisitorNode(typeName, resolver.refs, nodeId);
+    base.name = name;
+    base.attributes = attributes;
+    if (position !== undefined)
+        base.position = position;
+    if (data !== null)
+        base.data = data;
+    makeLazyChildren(base, view, buf, childIdsPos, childTypesPos, childCount, resolver);
+    return base;
+}
+export function readMatchedNode(wire, offset, nodeId, nodeType) {
+    const { view, buf, resolver } = wire;
+    let pos = offset;
+    const dataLen = view.getUint32(pos, true);
+    pos += 4;
+    let data = null;
+    if (dataLen > 0) {
+        const jsonStr = rstr(buf, pos, dataLen);
+        try {
+            data = JSON.parse(jsonStr);
+        }
+        catch (err) {
+            if (process.env.NODE_ENV !== "production") {
+                console.warn(`readMatchedNode: malformed node_data for nodeId=${nodeId}`, err);
+            }
+        }
+        pos += dataLen;
+    }
+    const position = readPosition(view, pos);
+    pos += 24;
+    const childCount = view.getUint32(pos, true);
+    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;
+    if (nodeType === HAST_ELEMENT) {
+        return readElementFromBinary(wire, pos, nodeId, position, childIdsPos, childTypesPos, childCount, data);
+    }
+    else if (nodeType === HAST_TEXT ||
+        nodeType === HAST_COMMENT ||
+        nodeType === HAST_RAW ||
+        nodeType === HAST_MDX_FLOW_EXPRESSION ||
+        nodeType === HAST_MDX_TEXT_EXPRESSION ||
+        nodeType === HAST_MDX_ESM) {
+        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);
+    }
+    const base = new VisitorNode(TYPE_NAMES[nodeType] ?? `unknown(${nodeType})`, resolver.refs, nodeId);
+    if (position !== undefined)
+        base.position = position;
+    if (data !== null)
+        base.data = data;
+    if (nodeType === HAST_ROOT) {
+        if (childCount > 0) {
+            makeLazyChildren(base, view, buf, childIdsPos, childTypesPos, childCount, resolver);
+        }
+        else {
+            base.children = [];
+        }
+    }
+    const node = base;
+    return node;
+}
+const HAST_EPOCH_CACHE = registerEpochCacheSlot(new WeakMap());
+export class HastLazyChildResolver extends LazyChildResolver {
+    cacheSlot() {
+        return HAST_EPOCH_CACHE;
+    }
+    createReader(wire) {
+        return new HastReader(wire);
+    }
+    materializeNode(reader, nodeId, refs) {
+        return materializeHastNode(reader, nodeId, true, refs);
+    }
+    readParentId(reader, nodeId) {
+        return reader.getParentId(nodeId);
+    }
+    readChildIds(reader, nodeId) {
+        return reader.getChildIds(nodeId);
+    }
+}
+// Own enumerable getters preserve children in spreads; closures avoid costly per-node wire slots.
+function makeLazyChildren(node, view, buf, childIdsPos, childTypesPos, childCount, resolver) {
+    Object.defineProperty(node, "children", {
+        get() {
+            const val = readChildStubs(view, buf, childIdsPos, childTypesPos, childCount, resolver);
+            Object.defineProperty(this, "children", {
+                value: val,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+            return val;
+        },
+        enumerable: true,
+        configurable: true,
+    });
+}

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-export { markdownToHtml, markdownToJs, mdxToJs, evaluate, markdownToMdast, mdxToMdast, markdownToHast, mdxToHast, htmlToHast, } from "./compile.js";
-export type { CompileOptions, MdxCompileOptions, MdxOnlyOptions, MarkdownToJsOptions, EvaluateOptions, OptimizeStaticConfig, Features, TreeOptions, HtmlToHastOptions, SmartPunctuationOptions, Frontmatter, MarkdownToHtmlResult, MarkdownToJsResult, MdxToJsResult, } from "./compile.js";
+export { markdownToHtml, markdownToJs, mdxToJs, evaluate, markdownToMdast, mdxToMdast, markdownToHast, mdxToHast, htmlToHast, hastToHtml, } from "./compile.js";
+export type { CompileOptions, MdxCompileOptions, MdxOnlyOptions, MarkdownToJsOptions, EvaluateOptions, OptimizeStaticConfig, Features, TreeOptions, MdastTreeOptions, HastTreeOptions, HtmlToHastOptions, SmartPunctuationOptions, Frontmatter, MarkdownToHtmlResult, MarkdownToJsResult, MdxToJsResult, } from "./compile.js";
 export { defineMdastPlugin, defineHastPlugin } from "./plugin.js";
 export type { MdastPluginDefinition, HastPluginDefinition, MdastPluginInput, HastPluginInput, MdastPluginEntry, HastPluginEntry, MdastPluginList, HastPluginList, PluginFactoryContext, } from "./plugin.js";
-export type { HastVisitorInstance, HastVisitorContext, HastFilteredVisitor, HastContent, HastParentContent, RawHastContent, RawHtmlHastContent, EstreeProgram, } from "./hast/hast-visitor.js";
-export type { MdastNode, HastNode, Custom, DataMap, Data, SourceFormat, Position, Point, MdxJsxAttributeNode, MdxJsxExpressionAttributeNode, MdxJsxAttributeValueExpressionNode, MdxJsxAttributeUnion, MdxJsxFlowElement, MdxJsxTextElement, MdxFlowExpression, MdxTextExpression, MdxjsEsm, MdxJsxFlowElementHast, MdxJsxTextElementHast, MdxFlowExpressionHast, MdxTextExpressionHast, MdxjsEsmHast, } from "./types.js";
+export type { HastVisitorInstance, HastVisitorContext, HastFilteredVisitor, HastVisitorFn, HastContent, HastParentContent, RawHastContent, RawHtmlHastContent, EstreeProgram, } from "./hast/hast-visitor.js";
+export type { MdastNode, HastNode, Custom, DataMap, Data, SourceFormat, Position, Point, MdxJsxAttributeNode, MdxJsxExpressionAttributeNode, MdxJsxAttributeValueExpressionNode, MdxJsxAttributeUnion, MdxJsxFlowElement, MdxJsxTextElement, MdxFlowExpression, MdxTextExpression, MdxjsEsm, MdxJsxFlowElementHast, MdxJsxTextElementHast, MdxFlowExpressionHast, MdxTextExpressionHast, MdxjsEsmHast, ContainerDirective, LeafDirective, TextDirective, DirectiveAttributes, Toml, MathNode, InlineMath, Superscript, Subscript, DescriptionList, DescriptionTerm, DescriptionDetails, HastRaw, } from "./types.js";
 export { normalizePlugins } from "./plugin.js";
 export { visitMdastHandle, visitMdastHook, resolveMdastSubscriptions, } from "./mdast/mdast-visitor.js";
-export type { MdastPluginInstance, MdastVisitorContext, MdastContent, MdastTarget, MdastParentContent, MdastDiagnostic, MdastHookFn, RawMdastContent, RawHtmlMdastContent, } from "./mdast/mdast-visitor.js";
+export type { MdastPluginInstance, MdastVisitorContext, MdastVisitorFn, MdastContent, MdastTarget, MdastParentContent, MdastDiagnostic, MdastHookFn, RawMdastContent, RawHtmlMdastContent, } from "./mdast/mdast-visitor.js";
 export { visitHastHandle, visitHastHook, resolveSubscriptions as resolveHastSubscriptions, } from "./hast/hast-visitor.js";
 export type { HastDiagnostic, HastHookFn } from "./hast/hast-visitor.js";
 export { MdastReader } from "./mdast/mdast-reader.js";

package/dist/index.js

@@ -1,12 +1,8 @@
-// Public API: compile functions
-export { markdownToHtml, markdownToJs, mdxToJs, evaluate, markdownToMdast, mdxToMdast, markdownToHast, mdxToHast, htmlToHast, } from "./compile.js";
-// Plugin definitions
+export { markdownToHtml, markdownToJs, mdxToJs, evaluate, markdownToMdast, mdxToMdast, markdownToHast, mdxToHast, htmlToHast, hastToHtml, } from "./compile.js";
 export { defineMdastPlugin, defineHastPlugin } from "./plugin.js";
-// Visitor pipeline (for manual plugin execution)
 export { normalizePlugins } from "./plugin.js";
 export { visitMdastHandle, visitMdastHook, resolveMdastSubscriptions, } from "./mdast/mdast-visitor.js";
 export { visitHastHandle, visitHastHook, resolveSubscriptions as resolveHastSubscriptions, } from "./hast/hast-visitor.js";
-// Step-by-step API: readers, materializers, and handle functions
 export { MdastReader } from "./mdast/mdast-reader.js";
 export { materializeMdastTree } from "./mdast/mdast-materializer.js";
 export { HastReader } from "./hast/hast-reader.js";
@@ -14,8 +10,7 @@ export { materializeHastTree } from "./hast/hast-materializer.js";
 export { serializeHandle, renderHandle, compileHandle, getHandleSource } from "#binding";
 import { applyCommandsToMdastHandle as napiApplyCommandsToMdastHandle, applyCommandsAndConvertToHastHandle as napiApplyCommandsAndConvertToHastHandle, convertMdastToHastHandle as napiConvertMdastToHastHandle, createHastHandle as napiCreateHastHandle, createMdastHandle as napiCreateMdastHandle, createMdxHastHandle as napiCreateMdxHastHandle, createMdxMdastHandle as napiCreateMdxMdastHandle, dropHandle as napiDropHandle, } from "#binding";
 import { featuresToNative } from "./compile.js";
-import { markHandleMutated } from "./lazy-child-resolver.js";
-// The napi creators take pre-packed parser bits; these keep `Features` the public shape.
+import { markHandleMutated, releaseHandleReferences } from "./lazy-child-resolver.js";
 export function createMdastHandle(source, features, trackPositions) {
     return napiCreateMdastHandle(source, featuresToNative(features).parseOptions, trackPositions);
 }
@@ -37,10 +32,7 @@ function mergeConvertOptions(fromFeatures, explicit) {
         return fromFeatures;
     return { ...fromFeatures, ...explicit };
 }
-// The raw NAPI mutators renumber or empty the arena; without the epoch bump a
-// child stub retained past a manual-pipeline pass would silently snapshot the
-// changed arena (or die with an opaque RangeError) instead of hitting the
-// retention error.
+// Arena mutations invalidate retained child stubs because node IDs can be reassigned or freed.
 export function applyCommandsToMdastHandle(handle, commandBuf) {
     markHandleMutated(handle);
     return napiApplyCommandsToMdastHandle(handle, commandBuf);
@@ -50,7 +42,7 @@ export function convertMdastToHastHandle(handle, convertOptions) {
     return napiConvertMdastToHastHandle(handle, convertOptions);
 }
 export function dropHandle(handle) {
-    markHandleMutated(handle);
+    releaseHandleReferences(handle);
     napiDropHandle(handle);
 }
 export function applyCommandsAndConvertToHastHandle(handle, commandBuf, convertOptions) {

package/dist/lazy-child-resolver.d.ts

@@ -1,23 +1,12 @@
 import type { NodeRefs } from "./visitor-shared.js";
 import type { AnyHandle } from "./handles.js";
 export declare function registerEpochCacheSlot<T extends object>(slot: WeakMap<AnyHandle, T>): WeakMap<AnyHandle, T>;
-/** Record that `handle`'s arena was rebuilt. Resolvers created before the bump
- *  refuse to take a fresh snapshot afterwards (their ids are stale). */
 export declare function markHandleMutated(handle: AnyHandle): void;
-/** Snapshot for one `(handle, epoch)`. Immutable once built, so it is shared
- *  by every resolver of the same pass chain: nested matched containers dedup
- *  by id, and later read-only passes reuse the whole cache instead of
- *  re-serializing and re-materializing. */
+export declare function releaseHandleReferences(handle: AnyHandle): void;
 export interface EpochCache<TReader> {
     epoch: number;
     reader: TReader;
 }
-/**
- * Lazy node materializer for the walk paths: serializes the handle's arena
- * once, on the first stub materialization, then materializes nodes from that
- * snapshot. Subclasses supply reader construction and per-node materialization
- * so the hot path stays free of per-node closures.
- */
 export declare abstract class LazyChildResolver<TReader, TNode> {
     #private;
     readonly refs: NodeRefs;
@@ -26,18 +15,9 @@ export declare abstract class LazyChildResolver<TReader, TNode> {
     protected abstract materializeNode(reader: TReader, nodeId: number, refs: NodeRefs): TNode;
     protected abstract readParentId(reader: TReader, nodeId: number): number;
     protected abstract readChildIds(reader: TReader, nodeId: number): number[];
-    /** Kind-specific `(handle → cache)` slot, supplied as a module-level WeakMap
-     *  by each subclass so MDAST and HAST snapshots never collide. */
     protected abstract cacheSlot(): WeakMap<AnyHandle, EpochCache<TReader>>;
-    /** Whether this pass's snapshot already exists; never takes one itself. */
     hasHotSnapshot(): boolean;
-    /** Materialize one node for a child stub's first real-field read. The
-     *  materializers memoize per `(reader, id)`, so overlapping subtrees and
-     *  later passes share the same materialized objects. */
     materializeOne(nodeId: number): TNode;
-    /** Arena id of `nodeId`'s parent in the pass snapshot, or undefined at the root. */
     parentIdOf(nodeId: number): number | undefined;
-    /** Index of `nodeId` within its parent's children in the pass snapshot,
-     *  or undefined at the root. */
     indexInParent(nodeId: number): number | undefined;
 }

package/dist/lazy-child-resolver.js

@@ -1,14 +1,13 @@
 import { serializeHandle } from "#binding";
-/** Rebuild count per handle: bumped whenever a command buffer lands and
- *  renumbers the arena, invalidating ids captured before it. */
+// Arena rebuilds can renumber nodes, invalidating IDs captured by earlier passes.
 const HANDLE_EPOCHS = new WeakMap();
-/** Per-flavor `(handle → cache)` slots, registered so a mutation can evict a snapshot the handle would otherwise pin. */
+// Registered cache slots let mutations evict snapshots that handles would otherwise retain.
 const EPOCH_CACHE_SLOTS = [];
 export function registerEpochCacheSlot(slot) {
     EPOCH_CACHE_SLOTS.push(slot);
     return slot;
 }
-/** Per handle, not per epoch: an id stale within its own handle is the epoch machinery's to drop with a warning. */
+// Ownership is per handle; epoch checks separately reject stale IDs within the same handle.
 const HANDLE_NODE_REFS = new WeakMap();
 function nodeRefsOfHandle(handle) {
     let refs = HANDLE_NODE_REFS.get(handle);
@@ -18,23 +17,19 @@ function nodeRefsOfHandle(handle) {
     }
     return refs;
 }
-/** Record that `handle`'s arena was rebuilt. Resolvers created before the bump
- *  refuse to take a fresh snapshot afterwards (their ids are stale). */
 export function markHandleMutated(handle) {
     HANDLE_EPOCHS.set(handle, (HANDLE_EPOCHS.get(handle) ?? 0) + 1);
-    // Safe to evict: a stale-epoch entry can never be adopted, only pinned by existing resolvers
     for (const slot of EPOCH_CACHE_SLOTS) {
         slot.delete(handle);
     }
 }
-/** Arena sentinel in the node struct's parent field: the node has no parent. */
+export function releaseHandleReferences(handle) {
+    markHandleMutated(handle);
+    // Retained contexts keep their own refs; do not keep the table alive until native handle GC.
+    HANDLE_NODE_REFS.delete(handle);
+}
 const NO_PARENT = 0xffffffff;
-/**
- * Lazy node materializer for the walk paths: serializes the handle's arena
- * once, on the first stub materialization, then materializes nodes from that
- * snapshot. Subclasses supply reader construction and per-node materialization
- * so the hot path stays free of per-node closures.
- */
+// Subclasses keep the per-node materialization path free of closures.
 export class LazyChildResolver {
     #handle;
     #epoch;
@@ -56,21 +51,13 @@ export class LazyChildResolver {
             this.#cache = cache;
             return cache;
         }
-        // A node id proves the tree was read in-pass, so a deferred snapshot is
-        // still faithful as long as no command buffer mutated the arena since
-        // match time. An existing same-epoch cache is always safe: the snapshot
-        // is an immutable copy.
+        // Snapshot only within the captured epoch; later arenas may assign these IDs to different nodes.
         if ((HANDLE_EPOCHS.get(this.#handle) ?? 0) !== this.#epoch) {
             throw new Error("Cannot read node content: this node was retained past its visitor pass " +
                 "and the tree has changed since. Reading a child node's field (or calling " +
                 "ctx.parent()) during the pass pins the pass snapshot; eager fields like " +
                 "tagName or properties do not. Or copy the data you need before the pass ends.");
         }
-        // The serialized buffer already carries each node's `data` blob (read
-        // eagerly by the materializer), and the arena isn't mutated mid-visit,
-        // so no separate lazy NAPI fetch is needed. This also keeps walk-path
-        // children consistent with the fully materialized tree (no `data` key
-        // when a node has none).
         cache = {
             epoch: this.#epoch,
             reader: this.createReader(serializeHandle(this.#handle)),
@@ -82,29 +69,21 @@ export class LazyChildResolver {
     #ensureReader() {
         return this.#ensureCache().reader;
     }
-    /** Whether this pass's snapshot already exists; never takes one itself. */
     hasHotSnapshot() {
         if (this.#cache !== undefined)
             return true;
         const cache = this.cacheSlot().get(this.#handle);
         return cache !== undefined && cache.epoch === this.#epoch;
     }
-    /** Materialize one node for a child stub's first real-field read. The
-     *  materializers memoize per `(reader, id)`, so overlapping subtrees and
-     *  later passes share the same materialized objects. */
     materializeOne(nodeId) {
         return this.materializeNode(this.#ensureCache().reader, nodeId, this.refs);
     }
-    /** Arena id of `nodeId`'s parent in the pass snapshot, or undefined at the root. */
     parentIdOf(nodeId) {
         const parentId = this.readParentId(this.#ensureReader(), nodeId);
         return parentId === NO_PARENT ? undefined : parentId;
     }
-    /** Per-parent child-id→index maps, built lazily: null until a plugin calls
-     *  `indexInParent` (most never do). Cache-safe because the snapshot is immutable. */
+    // Immutable snapshots make cached child indices safe across repeated parent lookups.
     #childIndexByParent = null;
-    /** Index of `nodeId` within its parent's children in the pass snapshot,
-     *  or undefined at the root. */
     indexInParent(nodeId) {
         const reader = this.#ensureReader();
         const parentId = this.readParentId(reader, nodeId);

package/dist/materializer-cache.d.ts

@@ -1,42 +1,18 @@
-/**
- * Shared materializer machinery for the HAST and MDAST flavors: per-reader
- * node memo, lazy `children` descriptors, and the frozen-mode (plugin walk
- * path) freeze rules.
- */
-import type { Position } from "unist";
+import type { Node } from "unist";
 import type { NodeRefs } from "./visitor-shared.js";
-/** The reader surface the shared machinery needs; both `HastReader` and `MdastReader` satisfy it. */
 export interface MaterializerReader {
     getNodeType(nodeId: number): number;
     getChildIds(nodeId: number): number[];
-    getPosition(nodeId: number): Position | undefined;
+    getChildrenCount(nodeId: number): number;
     getNodeData(nodeId: number): string | null;
 }
-export interface MaterializerSpec<TReader extends MaterializerReader, TNode extends object> {
-    /** Function name used in error/warning messages (e.g. "materializeHastNode"). */
+export interface MaterializerSpec<TReader extends MaterializerReader, TNode extends Node> {
     label: string;
-    /** Node-type tag -> canonical AST name (the generated `TYPE_NAMES`). */
     typeNames: Readonly<Record<number, string>>;
-    /** Whether `node` carries `children`. Takes the built node because mdast
-     *  `custom` decides leafness per node rather than per type. */
     hasChildren(nodeType: number, node: TNode, reader: TReader, nodeId: number): boolean;
-    /**
-     * Install the type-specific eager fields on `node`. Must not install
-     * `children`, `position`, `data`, or `_nodeId`, and must not freeze:
-     * the shared machinery owns all of those.
-     */
     populate(node: TNode, reader: TReader, nodeId: number, nodeType: number): void;
 }
-/**
- * Build a memoizing materializer, memoized per `(reader, id)`.
- *
- * `node` materializes one node with lazy `children`; `frozen` (the plugin walk
- * path) deep-freezes every node at construction so plugins cannot corrupt the
- * shared cache. `tree` materializes a whole tree eagerly, which is what the
- * step-by-step API wants: it asked for the tree, so laziness would only add
- * per-node accessor overhead.
- */
-export declare function createMaterializer<TReader extends MaterializerReader, TNode extends object>(spec: MaterializerSpec<TReader, TNode>): {
+export declare function installNodeData(node: Node, rawData: string | null, label: string, nodeId: number): void;
+export declare function createMaterializer<TReader extends MaterializerReader, TNode extends Node>(spec: MaterializerSpec<TReader, TNode>): {
     node: (reader: TReader, nodeId: number, frozen?: boolean, refs?: NodeRefs) => TNode;
-    tree: (reader: TReader, rootId: number) => TNode;
 };