satteri 0.9.4 → 0.10.0

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-export { markdownToHtml, mdxToJs, evaluate, markdownToMdast, mdxToMdast, markdownToHast, mdxToHast, } from "./compile.js";
-export type { CompileOptions, MdxCompileOptions, MdxOnlyOptions, EvaluateOptions, OptimizeStaticConfig, Features, SmartPunctuationOptions, Frontmatter, MarkdownToHtmlResult, MdxToJsResult, } from "./compile.js";
+export { markdownToHtml, markdownToJs, mdxToJs, evaluate, markdownToMdast, mdxToMdast, markdownToHast, mdxToHast, htmlToHast, } from "./compile.js";
+export type { CompileOptions, MdxCompileOptions, MdxOnlyOptions, MarkdownToJsOptions, EvaluateOptions, OptimizeStaticConfig, Features, TreeOptions, SmartPunctuationOptions, Frontmatter, MarkdownToHtmlResult, MarkdownToJsResult, MdxToJsResult, } from "./compile.js";
 export { defineMdastPlugin, defineHastPlugin } from "./plugin.js";
-export type { MdastPluginDefinition, HastPluginDefinition, MdastPluginInput, HastPluginInput, } from "./plugin.js";
-export type { HastVisitorInstance, HastVisitorContext, HastFilteredVisitor, HastContent, EstreeProgram, } from "./hast/hast-visitor.js";
-export type { MdastNode, HastNode, DataMap, Data, Position, Point, MdxJsxAttributeNode, MdxJsxExpressionAttributeNode, MdxJsxAttributeValueExpressionNode, MdxJsxAttributeUnion, MdxJsxFlowElement, MdxJsxTextElement, MdxFlowExpression, MdxTextExpression, MdxjsEsm, MdxJsxFlowElementHast, MdxJsxTextElementHast, MdxFlowExpressionHast, MdxTextExpressionHast, MdxjsEsmHast, } from "./types.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 { visitMdastHandle, resolveMdastSubscriptions } from "./mdast/mdast-visitor.js";
-export type { MdastPluginInstance, MdastVisitorContext, MdastContent, } from "./mdast/mdast-visitor.js";
+export type { MdastPluginInstance, MdastVisitorContext, MdastContent, MdastTarget, MdastParentContent, RawMdastContent, RawHtmlMdastContent, } from "./mdast/mdast-visitor.js";
 export { visitHastHandle, resolveSubscriptions as resolveHastSubscriptions, } from "./hast/hast-visitor.js";
 export { MdastReader } from "./mdast/mdast-reader.js";
 export { materializeMdastTree } from "./mdast/mdast-materializer.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 // Public API: compile functions
-export { markdownToHtml, mdxToJs, evaluate, markdownToMdast, mdxToMdast, markdownToHast, mdxToHast, } from "./compile.js";
+export { markdownToHtml, markdownToJs, mdxToJs, evaluate, markdownToMdast, mdxToMdast, markdownToHast, mdxToHast, htmlToHast, } from "./compile.js";
 // Plugin definitions
 export { defineMdastPlugin, defineHastPlugin } from "./plugin.js";
 // Visitor pipeline (for manual plugin execution)

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

@@ -1,7 +1,17 @@
+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 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
@@ -10,23 +20,20 @@ export declare function markHandleMutated(handle: AnyHandle): void;
  */
 export declare abstract class LazyChildResolver<TReader, TNode> {
     #private;
+    readonly refs: NodeRefs;
     constructor(handle: AnyHandle);
     protected abstract createReader(wire: Uint8Array): TReader;
-    protected abstract materializeNode(reader: TReader, nodeId: number): 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[];
-    /**
-     * Mark the visitor pass over. Child ids were captured at match time; once
-     * the pass's mutations land the arena is rebuilt and ids renumbered, so a
-     * later snapshot would map those stale ids onto the wrong nodes (or out of
-     * range). Failing loudly here beats silently wrong children.
-     */
-    seal(): void;
-    /** Guards the `.children` getters: a first read after the pass is refused
-     *  outright, even when no mutation landed — match-time ids cannot be trusted
-     *  once the plugin no longer controls the tree. */
-    assertUnsealed(): void;
-    /** Materialize one node for a child stub's first real-field read. */
+    /** 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;

package/dist/lazy-child-resolver.js

@@ -2,10 +2,30 @@ import { serializeHandle } from "#binding";
 /** Rebuild count per handle: bumped whenever a command buffer lands and
  *  renumbers the arena, invalidating ids captured before it. */
 const HANDLE_EPOCHS = new WeakMap();
+/** Per-flavor `(handle → cache)` slots, registered so a mutation can evict a snapshot the handle would otherwise pin. */
+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. */
+const HANDLE_NODE_REFS = new WeakMap();
+function nodeRefsOfHandle(handle) {
+    let refs = HANDLE_NODE_REFS.get(handle);
+    if (refs === undefined) {
+        refs = new WeakMap();
+        HANDLE_NODE_REFS.set(handle, refs);
+    }
+    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. */
 const NO_PARENT = 0xffffffff;
@@ -17,57 +37,66 @@ const NO_PARENT = 0xffffffff;
  */
 export class LazyChildResolver {
     #handle;
-    #reader = null;
-    #sealed = false;
     #epoch;
+    refs;
+    /** Strong pin: retained nodes keep their pass snapshot alive after later epochs evict the slot. */
+    #cache;
     constructor(handle) {
         this.#handle = handle;
         this.#epoch = HANDLE_EPOCHS.get(handle) ?? 0;
+        this.refs = nodeRefsOfHandle(handle);
     }
-    /**
-     * Mark the visitor pass over. Child ids were captured at match time; once
-     * the pass's mutations land the arena is rebuilt and ids renumbered, so a
-     * later snapshot would map those stale ids onto the wrong nodes (or out of
-     * range). Failing loudly here beats silently wrong children.
-     */
-    seal() {
-        this.#sealed = true;
-    }
-    /** Guards the `.children` getters: a first read after the pass is refused
-     *  outright, even when no mutation landed — match-time ids cannot be trusted
-     *  once the plugin no longer controls the tree. */
-    assertUnsealed() {
-        if (this.#sealed) {
+    #ensureCache() {
+        let cache = this.#cache;
+        if (cache !== undefined)
+            return cache;
+        const slot = this.cacheSlot();
+        cache = slot.get(this.#handle);
+        if (cache !== undefined && cache.epoch === this.#epoch) {
+            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.
+        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 may have changed since; read it inside the visitor.");
+                "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)),
+        };
+        this.#cache = cache;
+        slot.set(this.#handle, cache);
+        return cache;
     }
     #ensureReader() {
-        if (this.#reader === null) {
-            // A node id proves the tree was read in-pass, so a deferred snapshot is
-            // still faithful as long as no command buffer rebuilt the arena since
-            // match time (ids renumber on rebuild). An existing reader is always
-            // safe: the snapshot is an immutable pre-mutation copy.
-            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; read it inside the visitor.");
-            }
-            // 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).
-            this.#reader = this.createReader(serializeHandle(this.#handle));
-        }
-        return this.#reader;
+        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. */
+    /** 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.#ensureReader(), 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) {
-        this.assertUnsealed();
         const parentId = this.readParentId(this.#ensureReader(), nodeId);
         return parentId === NO_PARENT ? undefined : parentId;
     }
@@ -77,7 +106,6 @@ export class LazyChildResolver {
     /** Index of `nodeId` within its parent's children in the pass snapshot,
      *  or undefined at the root. */
     indexInParent(nodeId) {
-        this.assertUnsealed();
         const reader = this.#ensureReader();
         const parentId = this.readParentId(reader, nodeId);
         if (parentId === NO_PARENT)

package/dist/materializer-cache.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 { 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;
+    getNodeData(nodeId: number): string | null;
+}
+export interface MaterializerSpec<TReader extends MaterializerReader, TNode extends object> {
+    /** Function name used in error/warning messages (e.g. "materializeHastNode"). */
+    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>): {
+    node: (reader: TReader, nodeId: number, frozen?: boolean, refs?: NodeRefs) => TNode;
+    tree: (reader: TReader, rootId: number) => TNode;
+};

package/dist/materializer-cache.js

@@ -0,0 +1,192 @@
+/**
+ * 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 { deepFreeze } from "./freeze.js";
+/**
+ * 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 function createMaterializer(spec) {
+    const readerCaches = new WeakMap();
+    function materialize(reader, nodeId, frozen = false, refs) {
+        const cache = readerCache(reader, frozen, refs);
+        let node = cache.nodes.get(nodeId);
+        if (node === undefined) {
+            node = buildNode(reader, cache, nodeId, reader.getNodeType(nodeId));
+            cache.nodes.set(nodeId, node);
+        }
+        return node;
+    }
+    /** Frozen-mode `children`: memoized in `cache.childLists` because the node
+     *  is frozen, so the accessor cannot self-replace with a data property. */
+    function frozenChildrenDescriptor(reader, cache) {
+        return {
+            get() {
+                const nodeId = this._nodeId;
+                let value = cache.childLists.get(nodeId);
+                if (value === undefined) {
+                    const ids = reader.getChildIds(nodeId);
+                    const built = new Array(ids.length);
+                    let i = 0;
+                    for (const childId of ids)
+                        built[i++] = materialize(reader, childId, true);
+                    value = Object.freeze(built);
+                    cache.childLists.set(nodeId, value);
+                }
+                return value;
+            },
+            configurable: true,
+            enumerable: true,
+        };
+    }
+    /** Mutable-mode `children`: self-replacing with a plain writable array on
+     *  first read. The id is captured rather than stored on the node, so a
+     *  materialized tree carries no marker for `toEqual` or a spread to find. */
+    function mutableChildrenDescriptor(reader, nodeId) {
+        return {
+            get() {
+                const ids = reader.getChildIds(nodeId);
+                const value = new Array(ids.length);
+                let i = 0;
+                for (const childId of ids)
+                    value[i++] = materialize(reader, childId);
+                Object.defineProperty(this, "children", {
+                    value,
+                    writable: true,
+                    configurable: true,
+                    enumerable: true,
+                });
+                return value;
+            },
+            configurable: true,
+            enumerable: true,
+        };
+    }
+    function readerCache(reader, frozen, refs) {
+        let cache = readerCaches.get(reader);
+        if (cache === undefined) {
+            cache = {
+                nodes: new Map(),
+                childLists: new Map(),
+                children: undefined,
+                frozen,
+                refs,
+            };
+            if (frozen)
+                cache.children = frozenChildrenDescriptor(reader, cache);
+            readerCaches.set(reader, cache);
+        }
+        if (cache.frozen !== frozen) {
+            throw new Error(`${spec.label}: a reader cannot mix frozen and mutable materialization`);
+        }
+        return cache;
+    }
+    function buildNode(reader, cache, nodeId, nodeType, eager = false) {
+        const typeName = spec.typeNames[nodeType] ?? `unknown(${nodeType})`;
+        // Plain object, not a class: unified's `assertNode` rejects any other prototype.
+        const node = { type: typeName };
+        const position = reader.getPosition(nodeId);
+        if (position !== undefined) {
+            node.position = position;
+        }
+        if (cache.frozen) {
+            // Non-enumerable so `nid()` never trusts an id that a spread copied.
+            cache.refs?.set(node, nodeId);
+            Object.defineProperty(node, "_nodeId", {
+                value: nodeId,
+                writable: false,
+                configurable: true,
+                enumerable: false,
+            });
+        }
+        spec.populate(node, reader, nodeId, nodeType);
+        // Plugins can set `data` on any node type, so rehydrate generically
+        // (see website/content/docs/divergences.md for the code-block case).
+        const rawData = reader.getNodeData(nodeId);
+        if (rawData !== null) {
+            try {
+                const parsed = JSON.parse(rawData);
+                if (parsed && typeof parsed === "object" && Object.keys(parsed).length > 0) {
+                    Object.defineProperty(node, "data", {
+                        value: parsed,
+                        writable: true,
+                        configurable: true,
+                        enumerable: true,
+                    });
+                }
+            }
+            catch (err) {
+                if (process.env.NODE_ENV !== "production") {
+                    console.warn(`${spec.label}: malformed node_data for nodeId=${nodeId}`, err);
+                }
+            }
+        }
+        if (!eager && spec.hasChildren(nodeType, node, reader, nodeId)) {
+            Object.defineProperty(node, "children", cache.children ?? mutableChildrenDescriptor(reader, nodeId));
+        }
+        if (cache.frozen) {
+            // Deep-freeze the eager own values but not the lazy `children` accessor;
+            // freeze eagerly even for containers so nothing is writable while cached.
+            const descriptors = Object.getOwnPropertyDescriptors(node);
+            for (const key of Object.keys(descriptors)) {
+                const desc = descriptors[key];
+                if (desc !== undefined && "value" in desc) {
+                    deepFreeze(desc.value);
+                }
+            }
+            Object.freeze(node);
+        }
+        return node;
+    }
+    /**
+     * Iterative on purpose: recursing to full document depth overflows on deeply
+     * nested input, and nothing else here descends more than one level.
+     *
+     * Breadth-first over the parents still to fill, so every node is built and
+     * every child list decoded exactly once, and a child is wired into its
+     * parent's array as it is built rather than in a second pass.
+     */
+    function fillTree(reader, cache, rootId) {
+        const rootType = reader.getNodeType(rootId);
+        const root = buildNode(reader, cache, rootId, rootType, true);
+        if (!spec.hasChildren(rootType, root, reader, rootId))
+            return root;
+        const parents = [root];
+        const parentIds = [rootId];
+        for (let p = 0; p < parentIds.length; p++) {
+            const parent = parents[p];
+            const parentId = parentIds[p];
+            if (parent === undefined || parentId === undefined)
+                continue;
+            const ids = reader.getChildIds(parentId);
+            const kids = new Array(ids.length);
+            for (let i = 0; i < ids.length; i++) {
+                const childId = ids[i];
+                if (childId === undefined)
+                    continue;
+                const childType = reader.getNodeType(childId);
+                const child = buildNode(reader, cache, childId, childType, true);
+                kids[i] = child;
+                if (spec.hasChildren(childType, child, reader, childId)) {
+                    parents.push(child);
+                    parentIds.push(childId);
+                }
+            }
+            // Assignment beats defineProperty here; `eager` left `children` uninstalled.
+            parent.children = kids;
+        }
+        return root;
+    }
+    /** Whole tree at once: the caller will walk it, so lazy accessors cost more than they defer. */
+    function materializeTree(reader, rootId) {
+        return fillTree(reader, readerCache(reader, false, undefined), rootId);
+    }
+    return { node: materialize, tree: materializeTree };
+}

package/dist/mdast/child-stub.d.ts

@@ -5,9 +5,12 @@ type MdastResolver = LazyChildResolver<MdastReader, MdastNode>;
 /**
  * Walk-path child stub: arena id + `type` eagerly, every other field a lazy
  * forward to the materialized node (first read snapshots the arena via
- * `materializeOne`, which enforces the handle epoch — the pass seal is checked
- * where the stubs are built). Spread/identity rules are enforced by `nid()`
- * (authoritative doc in hast-visitor.ts).
+ * `materializeOne`, which enforces the handle epoch). Spread/identity rules
+ * are enforced by `nid()` (authoritative doc in hast-visitor.ts).
+ *
+ * A user-defined node's `type` is the one exception: it lives in the arena,
+ * not the tag, so it joins the lazy fields rather than making every sibling
+ * list snapshot the arena up front.
  */
 export declare class MdastChildStub {
     _resolver: MdastResolver;

package/dist/mdast/child-stub.js

@@ -1,4 +1,4 @@
-import { flatByTag, stubDescriptors } from "../child-stub.js";
+import { flatByTag, installStubDescriptors, stubDescriptors, } from "../child-stub.js";
 import { MDAST_LAYOUT_KEYS } from "./generated/layout.js";
 import { NAME_TO_TYPE, TYPE_NAMES } from "./generated/node-types.js";
 import { LEAF_TYPES } from "./mdast-materializer.js";
@@ -8,6 +8,7 @@ const N = NAME_TO_TYPE;
 const HAND_WRITTEN_FIELDS = {
     [N.list]: ["ordered", "start", "spread"],
     [N.listItem]: ["spread", "checked"],
+    [N.descriptionDetails]: ["spread"],
     [N.table]: ["align"],
     [N.containerDirective]: ["name", "attributes"],
     [N.leafDirective]: ["name", "attributes"],
@@ -16,11 +17,18 @@ const HAND_WRITTEN_FIELDS = {
     [N.mdxJsxTextElement]: ["name", "attributes"],
 };
 const TYPE_NAME_BY_TAG = flatByTag(TYPE_NAMES);
+/** Internal tag for user-defined nodes; its stored `name` field is folded into
+ *  the open `node.type`, so the stub exposes `value` (leaf content) but no
+ *  separate `name`. */
+const MDAST_CUSTOM = NAME_TO_TYPE.custom;
 const MDAST_STUB_DESCRIPTORS = [];
 for (const tag of Object.keys(TYPE_NAMES)) {
     const nodeType = Number(tag);
-    const fields = [...(MDAST_LAYOUT_KEYS[nodeType] ?? HAND_WRITTEN_FIELDS[nodeType] ?? [])];
-    if (!LEAF_TYPES.has(nodeType))
+    const fields = nodeType === MDAST_CUSTOM
+        ? ["value"]
+        : [...(MDAST_LAYOUT_KEYS[nodeType] ?? HAND_WRITTEN_FIELDS[nodeType] ?? [])];
+    // `custom` gets its own `children` getter: leafness is per node, not per type.
+    if (nodeType !== MDAST_CUSTOM && !LEAF_TYPES.has(nodeType))
         fields.push("children");
     MDAST_STUB_DESCRIPTORS[nodeType] = stubDescriptors(fields);
 }
@@ -29,9 +37,12 @@ const FALLBACK_DESCRIPTORS = stubDescriptors([]);
 /**
  * Walk-path child stub: arena id + `type` eagerly, every other field a lazy
  * forward to the materialized node (first read snapshots the arena via
- * `materializeOne`, which enforces the handle epoch — the pass seal is checked
- * where the stubs are built). Spread/identity rules are enforced by `nid()`
- * (authoritative doc in hast-visitor.ts).
+ * `materializeOne`, which enforces the handle epoch). Spread/identity rules
+ * are enforced by `nid()` (authoritative doc in hast-visitor.ts).
+ *
+ * A user-defined node's `type` is the one exception: it lives in the arena,
+ * not the tag, so it joins the lazy fields rather than making every sibling
+ * list snapshot the arena up front.
  */
 export class MdastChildStub {
     _resolver;
@@ -40,7 +51,59 @@ export class MdastChildStub {
     constructor(resolver, id, nodeType) {
         this._resolver = resolver;
         this._id = id;
-        this.type = TYPE_NAME_BY_TAG[nodeType] ?? `unknown(${nodeType})`;
-        Object.defineProperties(this, MDAST_STUB_DESCRIPTORS[nodeType] ?? FALLBACK_DESCRIPTORS);
+        if (nodeType === MDAST_CUSTOM) {
+            installLazyCustomType(this);
+            installLazyCustomChildren(this);
+        }
+        else {
+            this.type = TYPE_NAME_BY_TAG[nodeType] ?? `unknown(${nodeType})`;
+        }
+        installStubDescriptors(this, MDAST_STUB_DESCRIPTORS[nodeType] ?? FALLBACK_DESCRIPTORS);
     }
+    /** @internal */
+    get _refs() {
+        return this._resolver.refs;
+    }
+}
+/** `children` as a self-replacing accessor, and self-*removing* for a leaf: the
+ *  stub only knows the tag, so it cannot tell a leaf from a parent until the
+ *  arena snapshot says which shape this node has. */
+function installLazyCustomChildren(stub) {
+    Object.defineProperty(stub, "children", {
+        get() {
+            const real = this._resolver.materializeOne(this._id);
+            const value = real.children;
+            if (value === undefined) {
+                delete this.children;
+                return undefined;
+            }
+            Object.defineProperty(this, "children", {
+                value,
+                writable: false,
+                enumerable: true,
+                configurable: false,
+            });
+            return value;
+        },
+        enumerable: true,
+        configurable: true,
+    });
+}
+/** `type` as a self-replacing accessor: the materialized node folds the stored
+ *  name into `type`. Enumerable so a spread copy still carries it. */
+function installLazyCustomType(stub) {
+    Object.defineProperty(stub, "type", {
+        get() {
+            const value = this._resolver.materializeOne(this._id).type;
+            Object.defineProperty(this, "type", {
+                value,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+            return value;
+        },
+        enumerable: true,
+        configurable: true,
+    });
 }

package/dist/mdast/generated/layout.d.ts

@@ -1,7 +1,6 @@
 import type { MdastReader } from "../mdast-reader.js";
 /** Materialized property names per tag (the non-skip `js` names above),
- *  precomputed so `materializeMdastFields` doesn't rebuild them per node.
- *  Exported for the child-stub field tables. */
+ *  exported for the child-stub field tables. */
 export declare const MDAST_LAYOUT_KEYS: Readonly<Record<number, readonly string[]>>;
 /**
  * Decode a node's type-specific `type_data` from the walk buffer onto `node`,
@@ -14,6 +13,6 @@ export declare function decodeMdastTypeData(view: DataView, buf: Uint8Array, sta
  * Attach a node's fixed `type_data` fields, materialized from the arena
  * snapshot, driven by `MDAST_LAYOUTS`. Returns `false` for tags with no entry,
  * so the materializer falls through to its hand-written cases (list, table,
- * directives, MDX JSX). Fields resolve lazily on first access.
+ * directives, MDX JSX). Fields are eager plain stores.
  */
 export declare function materializeMdastFields(reader: MdastReader, node: object, nodeId: number, nodeType: number): boolean;