satteri 0.10.4 → 0.11.1

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

@@ -0,0 +1,13 @@
+import { LazyChildResolver, type EpochCache } from "../lazy-child-resolver.js";
+import type { MdastNode } from "../types.js";
+import { type NodeRefs } from "../visitor-shared.js";
+import { MdastReader } from "./mdast-reader.js";
+export declare function getNodeId(node: MdastNode, refs: NodeRefs): number | undefined;
+export declare class MdastLazyChildResolver extends LazyChildResolver<MdastReader, MdastNode> {
+    protected cacheSlot(): WeakMap<globalThis.AnyHandle, EpochCache<MdastReader>>;
+    protected createReader(wire: Uint8Array): MdastReader;
+    protected materializeNode(reader: MdastReader, nodeId: number, refs: NodeRefs): MdastNode;
+    protected readParentId(reader: MdastReader, nodeId: number): number;
+    protected readChildIds(reader: MdastReader, nodeId: number): number[];
+}
+export declare function readMdastMatchedNode(view: DataView, buf: Uint8Array, dataOffset: number, nodeId: number, nodeType: number, resolver: MdastLazyChildResolver): MdastNode;

package/dist/mdast/mdast-walk.js

@@ -0,0 +1,144 @@
+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, ru32 } from "../wire-read.js";
+import { MdastChildStub } from "./child-stub.js";
+import { decodeMdastTypeData } from "./generated/layout.js";
+import { NAME_TO_TYPE, TYPE_NAMES } from "./generated/node-types.js";
+import { isCustomLeaf, LEAF_TYPES, materializeNode } from "./mdast-materializer.js";
+import { MdastReader } from "./mdast-reader.js";
+const MDAST_CUSTOM = NAME_TO_TYPE.custom;
+export function getNodeId(node, refs) {
+    // Spread copies must be treated as new content, not as references to the original arena node.
+    if (node instanceof MdastChildStub)
+        return node._refs === refs ? node._id : FOREIGN_REF;
+    const id = VisitorNode.getNodeId(node, refs) ?? refs.get(node);
+    if (id !== undefined)
+        return id;
+    // An unregistered non-enumerable ID belongs to a different tree; enumerable copies carry no identity.
+    const d = Object.getOwnPropertyDescriptor(node, "_nodeId");
+    if (d !== undefined && !d.enumerable)
+        return FOREIGN_REF;
+    return crossPipelineForeign(node);
+}
+const MDAST_EPOCH_CACHE = registerEpochCacheSlot(new WeakMap());
+export class MdastLazyChildResolver extends LazyChildResolver {
+    cacheSlot() {
+        return MDAST_EPOCH_CACHE;
+    }
+    createReader(wire) {
+        return new MdastReader(wire);
+    }
+    materializeNode(reader, nodeId, refs) {
+        return materializeNode(reader, nodeId, true, refs);
+    }
+    readParentId(reader, nodeId) {
+        return reader.getParentId(nodeId);
+    }
+    readChildIds(reader, nodeId) {
+        return reader.getChildIds(nodeId);
+    }
+}
+function readMdastChildStubs(view, buf, idsPos, typesPos, count, resolver) {
+    // With a hot snapshot a stub's deferral buys nothing; real nodes skip its per-field getters.
+    if (resolver.hasHotSnapshot()) {
+        const nodes = new Array(count);
+        for (let i = 0; i < count; i++) {
+            nodes[i] = resolver.materializeOne(ru32(view, idsPos + i * 4));
+        }
+        return nodes;
+    }
+    const stubs = new Array(count);
+    for (let i = 0; i < count; i++) {
+        stubs[i] = new MdastChildStub(resolver, ru32(view, idsPos + i * 4), buf[typesPos + i]);
+    }
+    return stubs;
+}
+// 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 = readMdastChildStubs(view, buf, childIdsPos, childTypesPos, childCount, resolver);
+            Object.defineProperty(this, "children", {
+                value: val,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+            return val;
+        },
+        enumerable: true,
+        configurable: true,
+    });
+}
+export function readMdastMatchedNode(view, buf, dataOffset, nodeId, nodeType, resolver) {
+    let pos = dataOffset;
+    const dataJsonLen = ru32(view, pos);
+    pos += 4;
+    let initialData = null;
+    if (dataJsonLen > 0) {
+        const jsonStr = rstr(buf, pos, dataJsonLen);
+        try {
+            initialData = JSON.parse(jsonStr);
+        }
+        catch (err) {
+            if (process.env.NODE_ENV !== "production") {
+                console.warn(`readMdastMatchedNode: malformed node_data for nodeId=${nodeId}`, err);
+            }
+        }
+        pos += dataJsonLen;
+    }
+    const position = readPosition(view, pos);
+    pos += 24;
+    const childCount = ru32(view, pos);
+    pos += 4;
+    // Most visitors never read children, so defer decoding their IDs and types.
+    const childIdsPos = pos;
+    pos += childCount * 4;
+    const childTypesPos = pos;
+    pos += childCount;
+    const typeName = TYPE_NAMES[nodeType] ?? `unknown(${nodeType})`;
+    const node = new VisitorNode(typeName, resolver.refs, nodeId);
+    if (position !== undefined)
+        node.position = position;
+    if (childCount > 0) {
+        makeLazyChildren(node, view, buf, childIdsPos, childTypesPos, childCount, resolver);
+    }
+    if (!decodeMdastTypeData(view, buf, pos, nodeType, node)) {
+        switch (nodeType) {
+            case 5: {
+                node.start = ru32(view, pos);
+                node.ordered = buf[pos + 4] !== 0;
+                node.spread = buf[pos + 5] !== 0;
+                if (!node.ordered)
+                    node.start = null;
+                break;
+            }
+            case 6: {
+                const checked = buf[pos];
+                node.checked = checked === 2 ? null : checked === 1;
+                node.spread = buf[pos + 1] !== 0;
+                break;
+            }
+            case 37: {
+                node.spread = buf[pos] !== 0;
+                break;
+            }
+        }
+    }
+    // Custom nodes expose name as type; an empty value must not make a parent look like a text leaf.
+    if (nodeType === MDAST_CUSTOM) {
+        node.type = node.name;
+        delete node.name;
+        if (node.value === "")
+            delete node.value;
+    }
+    const leafCustom = nodeType === MDAST_CUSTOM && isCustomLeaf({ value: node.value, data: initialData }, childCount);
+    if (childCount === 0 && !LEAF_TYPES.has(nodeType) && !leafCustom) {
+        node.children = [];
+    }
+    if (initialData) {
+        node.data = initialData;
+    }
+    return node;
+}

package/dist/mdx-attr.js

@@ -1,6 +1,3 @@
-/** Decode an MDX JSX attribute from its wire `(kind, name, value)` — shared by
- *  the generated mdast tail decoder and the hast path so the kind dispatch lives
- *  once. Expression/spread values carry phantom-space sentinels, restored here. */
 import { restorePhantomSpaces } from "./phantom.js";
 export function decodeMdxJsxAttr(kind, name, value) {
     switch (kind) {

package/dist/mdx-types.js

@@ -1,7 +1,2 @@
-// Manually-defined MDX AST node types.
-//
-// These replicate the type definitions from mdast-util-mdx-jsx,
-// mdast-util-mdx-expression, and mdast-util-mdxjs-esm so we can avoid
-// pulling in those packages (and their massive transitive dependency trees)
-// just for a handful of interfaces.
+// Local MDX interfaces avoid dependencies on packages needed only for their type definitions.
 export {};

package/dist/op-stream.d.ts

@@ -1,16 +1,5 @@
-/**
- * Low-level op-stream writer shared by the MDAST/HAST declarative compilers.
- *
- * Emits the compact OPEN/CLOSE/field/REF/KEEP_CHILDREN/PROP stream that Rust
- * replays straight into the arena (`replay_opstream` in js_commands.rs; byte
- * values in generated/wire-constants.ts) — the only structural encoding for
- * plugin-built content. Strings ride ByteWriter's zero-alloc path (inline
- * char codes when short ASCII, `encodeInto` otherwise). `CommandBuffer`
- * extends this class so payloads are emitted directly into the command
- * bytes, with no intermediate opstream buffer or copy.
- */
 import { ByteWriter } from "./byte-writer.js";
-export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_INT, PROP_NULL, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
+export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_INT, PROP_NULL, PROP_TOKEN_LIST, } from "./generated/wire-constants.js";
 export declare class OpWriter extends ByteWriter {
     constructor(initialSize?: number);
     open(type: number): void;
@@ -22,10 +11,7 @@ export declare class OpWriter extends ByteWriter {
     data(value: unknown): void;
     prop(name: string, kind: number, value: string): void;
     ref(id: number): void;
-    /** Table column-alignment codes (0=none, 1=left, 2=right, 3=center). */
     align(codes: readonly number[]): void;
     keepChildren(): void;
 }
-/** Emit one MDX JSX attribute as an OP_PROP, mirroring `encode_js_jsx_attrs`:
- *  null→boolean, string→literal, `{ value }` object→expression, else→boolean. */
 export declare function emitMdxAttr(w: OpWriter, a: Record<string, unknown>): void;

package/dist/op-stream.js

@@ -1,18 +1,7 @@
-/**
- * Low-level op-stream writer shared by the MDAST/HAST declarative compilers.
- *
- * Emits the compact OPEN/CLOSE/field/REF/KEEP_CHILDREN/PROP stream that Rust
- * replays straight into the arena (`replay_opstream` in js_commands.rs; byte
- * values in generated/wire-constants.ts) — the only structural encoding for
- * plugin-built content. Strings ride ByteWriter's zero-alloc path (inline
- * char codes when short ASCII, `encodeInto` otherwise). `CommandBuffer`
- * extends this class so payloads are emitted directly into the command
- * bytes, with no intermediate opstream buffer or copy.
- */
+// Writing directly into CommandBuffer avoids an intermediate op-stream allocation and copy.
 import { ByteWriter } from "./byte-writer.js";
 import { OP_OPEN, OP_CLOSE, OP_REF, OP_KEEP_CHILDREN, OP_STR, OP_U8, OP_U32, OP_BOOL, OP_DATA, OP_PROP, OP_ALIGN, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
-// Re-exported so visitors/readers keep importing wire constants from here.
-export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_INT, PROP_NULL, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
+export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_INT, PROP_NULL, PROP_TOKEN_LIST, } from "./generated/wire-constants.js";
 export class OpWriter extends ByteWriter {
     constructor(initialSize = 512) {
         super(initialSize);
@@ -52,9 +41,7 @@ export class OpWriter extends ByteWriter {
     }
     data(value) {
         const json = JSON.stringify(value);
-        // `JSON.stringify` yields undefined for a function or a `toJSON`
-        // returning undefined; a clear error beats a TypeError deep in the
-        // string encoder.
+        // JSON.stringify can return undefined for functions and custom toJSON methods.
         if (typeof json !== "string") {
             throw new Error("node `data` is not JSON-serializable");
         }
@@ -75,7 +62,6 @@ export class OpWriter extends ByteWriter {
         this.buf[this.n++] = OP_REF;
         this.writeU32(id);
     }
-    /** Table column-alignment codes (0=none, 1=left, 2=right, 3=center). */
     align(codes) {
         this.ensure(5 + codes.length);
         this.buf[this.n++] = OP_ALIGN;
@@ -88,8 +74,6 @@ export class OpWriter extends ByteWriter {
         this.buf[this.n++] = OP_KEEP_CHILDREN;
     }
 }
-/** Emit one MDX JSX attribute as an OP_PROP, mirroring `encode_js_jsx_attrs`:
- *  null→boolean, string→literal, `{ value }` object→expression, else→boolean. */
 export function emitMdxAttr(w, a) {
     if (a.type === "mdxJsxExpressionAttribute") {
         w.prop("", MDX_ATTR_SPREAD, typeof a.value === "string" ? a.value : "");

package/dist/phantom.d.ts

@@ -1,2 +1 @@
-/** Restore phantom-space sentinels to real spaces, allocating only when present. */
 export declare function restorePhantomSpaces(value: string): string;

package/dist/phantom.js

@@ -1,13 +1,5 @@
-/**
- * Sentinel the MDX parser substitutes for spaces inside expression and JSX
- * attribute-expression values (see `PHANTOM_SPACE` in
- * satteri-pulldown-cmark/src/mdx.rs). mdast and hast keep the sentinel in the
- * stored value; readers and visitors restore the real space on the way out.
- * Both plugin-facing paths (direct walk match and materialized child) must
- * restore it so a node's `value` reads the same regardless of how it's reached.
- */
+// Rust uses this sentinel for spaces inside MDX expressions; every JS read path must restore them.
 const PHANTOM_SPACE = "\uF002";
-/** Restore phantom-space sentinels to real spaces, allocating only when present. */
 export function restorePhantomSpaces(value) {
     return value.includes(PHANTOM_SPACE) ? value.replaceAll(PHANTOM_SPACE, " ") : value;
 }

package/dist/plugin-pipeline.d.ts

@@ -0,0 +1,32 @@
+import type { NativeConvertOptions } from "./compile-options.js";
+import type { Frontmatter } from "./compile-types.js";
+import type { AnyHandle } from "./handles.js";
+import { type HastHandle } from "./hast/hast-visitor.js";
+import { type MdastHandle } from "./mdast/mdast-visitor.js";
+import type { HastPluginDefinition, MdastPluginDefinition } from "./plugin.js";
+import type { Data, SourceFormat } from "./types.js";
+export type MdastPipelineResult = {
+    handle: MdastHandle;
+    pendingCommands?: Uint8Array;
+    lastPlugin?: {
+        name?: string;
+    };
+};
+export declare function releaseHandle(handle: AnyHandle, invalidateStubs: boolean): void;
+export declare function warnIfDroppedTransforms(dropped: number | undefined, plugin: {
+    name?: string;
+} | null | undefined, kind: "mdast" | "hast"): void;
+export declare function runMdastPluginsOnHandle(handle: MdastHandle, plugins: MdastPluginDefinition[], fileURL: URL | undefined, data: Data, sourceFormat: SourceFormat, collectLast?: boolean): MdastPipelineResult | Promise<MdastPipelineResult>;
+export declare const EMPTY_COMMAND_BUFFER: Uint8Array<ArrayBuffer>;
+export type CollectedHastCommands = {
+    commands: Uint8Array;
+    lastPlugin: {
+        name?: string;
+    } | null;
+};
+export declare function runHastPluginsCollectLast(handle: HastHandle, plugins: HastPluginDefinition[], source: string, fileURL: URL | undefined, data: Data, sourceFormat: SourceFormat): CollectedHastCommands | Promise<CollectedHastCommands>;
+export type HastWithFrontmatter = {
+    hastHandle: HastHandle;
+    frontmatter: Frontmatter | null;
+};
+export declare function createHastHandleFromMdast(source: string, mdastPlugins: MdastPluginDefinition[], mdx: boolean, fileURL: URL | undefined, parseOptions: number, nativeConvertOptions: NativeConvertOptions | undefined, data: Data, trackPositions: boolean): HastWithFrontmatter | Promise<HastWithFrontmatter>;

package/dist/plugin-pipeline.js

@@ -0,0 +1,177 @@
+import { applyCommandsToHandle, applyCommandsToMdastHandle, convertMdastToHastHandle, createHastHandleWithFrontmatter, createMdastHandle, createMdxHastHandleWithFrontmatter, createMdxMdastHandle, dropHandle, getHandleSource, getMdastFrontmatter, } from "#binding";
+import { resolveSubscriptions, visitHastHandleCollect, visitHastHookCollect, } from "./hast/hast-visitor.js";
+import { markHandleMutated, releaseHandleReferences } from "./lazy-child-resolver.js";
+import { resolveMdastSubscriptions, visitMdastHandle, visitMdastHook, } from "./mdast/mdast-visitor.js";
+// Invalidate retained child stubs before their arena is freed.
+export function releaseHandle(handle, invalidateStubs) {
+    if (invalidateStubs)
+        releaseHandleReferences(handle);
+    dropHandle(handle);
+}
+export function warnIfDroppedTransforms(dropped, plugin, kind) {
+    if (!dropped || !plugin)
+        return;
+    const name = plugin.name ?? "<anonymous>";
+    const noun = dropped === 1 ? "transform" : "transforms";
+    console.warn(`satteri: plugin "${name}" queued ${dropped} ${kind} ${noun} on node(s) that a plugin had ` +
+        `already removed or replaced; ${dropped === 1 ? "it was" : "they were"} dropped.`);
+}
+function settle(value, fn) {
+    if (value instanceof Promise)
+        return value.then(fn);
+    fn(value);
+    return undefined;
+}
+// Keep synchronous pipelines synchronous even when later steps can return promises.
+function sequence(steps) {
+    let pending;
+    for (const step of steps) {
+        if (step === undefined)
+            continue;
+        pending = pending === undefined ? step() : pending.then(step);
+    }
+    return pending;
+}
+export function runMdastPluginsOnHandle(handle, plugins, fileURL, data, sourceFormat, collectLast = false) {
+    const out = { handle };
+    const getSource = () => getHandleSource(handle);
+    const runPlugin = (plugin, isLastPlugin) => {
+        const subs = resolveMdastSubscriptions(plugin);
+        const apply = (r, isFinalPass) => {
+            if (!r.hasMutations)
+                return;
+            if (collectLast && isLastPlugin && isFinalPass) {
+                out.pendingCommands = r.commandBuffer;
+                out.lastPlugin = plugin;
+                return;
+            }
+            markHandleMutated(handle);
+            const dropped = applyCommandsToMdastHandle(handle, r.commandBuffer);
+            warnIfDroppedTransforms(dropped, plugin, "mdast");
+        };
+        const before = typeof plugin.before === "function" ? plugin.before : undefined;
+        const after = typeof plugin.after === "function" ? plugin.after : undefined;
+        const hasVisitors = subs.length > 0;
+        // Resolvers are epoch-bound, so each pass needs its own context.
+        const diagnostics = [];
+        const runHook = (hook, isFinalPass) => () => settle(visitMdastHook(handle, plugin, hook, getSource, fileURL, data, sourceFormat, diagnostics), (r) => apply(r, isFinalPass));
+        const runVisitors = (isFinalPass) => () => settle(visitMdastHandle(handle, plugin, subs, getSource, fileURL, data, sourceFormat, diagnostics), (r) => apply(r, isFinalPass));
+        return sequence([
+            before ? runHook(before, !hasVisitors && after === undefined) : undefined,
+            hasVisitors ? runVisitors(after === undefined) : undefined,
+            after ? runHook(after, true) : undefined,
+        ]);
+    };
+    let i = 0;
+    const runNext = () => {
+        for (;;) {
+            const plugin = plugins[i];
+            if (plugin === undefined)
+                break;
+            i++;
+            const r = runPlugin(plugin, i === plugins.length);
+            if (r instanceof Promise)
+                return r.then(runNext);
+        }
+        return out;
+    };
+    return runNext();
+}
+export const EMPTY_COMMAND_BUFFER = new Uint8Array(0);
+const NO_HAST_COMMANDS = {
+    commands: EMPTY_COMMAND_BUFFER,
+    lastPlugin: null,
+};
+// Fuse the last apply with rendering or compilation to save a NAPI roundtrip.
+export function runHastPluginsCollectLast(handle, plugins, source, fileURL, data, sourceFormat) {
+    let i = 0;
+    const runNext = () => {
+        for (;;) {
+            const plugin = plugins[i];
+            if (plugin === undefined)
+                break;
+            const isLastPlugin = i === plugins.length - 1;
+            i++;
+            const subs = resolveSubscriptions(plugin);
+            const { before, after } = plugin;
+            const passes = [];
+            if (typeof before === "function")
+                passes.push(before);
+            if (subs.length > 0)
+                passes.push("visitors");
+            if (typeof after === "function")
+                passes.push(after);
+            if (passes.length === 0)
+                continue;
+            let collected = NO_HAST_COMMANDS;
+            // Resolvers are epoch-bound, so each pass needs its own context.
+            const diagnostics = [];
+            const runPass = (pass, passIndex) => () => settle(pass === "visitors"
+                ? visitHastHandleCollect(handle, plugin, subs, source, fileURL, data, sourceFormat, diagnostics)
+                : visitHastHookCollect(handle, plugin, pass, source, fileURL, data, sourceFormat, diagnostics), (commands) => {
+                if (isLastPlugin && passIndex === passes.length - 1) {
+                    collected = { commands, lastPlugin: plugin };
+                }
+                else if (commands.length > 0) {
+                    markHandleMutated(handle);
+                    const dropped = applyCommandsToHandle(handle, commands);
+                    warnIfDroppedTransforms(dropped, plugin, "hast");
+                }
+            });
+            const pending = sequence(passes.map(runPass));
+            if (isLastPlugin)
+                return pending instanceof Promise ? pending.then(() => collected) : collected;
+            if (pending instanceof Promise)
+                return pending.then(runNext);
+        }
+        return NO_HAST_COMMANDS;
+    };
+    return runNext();
+}
+function readFrontmatter(handle) {
+    const raw = getMdastFrontmatter(handle);
+    return raw ? { kind: raw.kind === "toml" ? "toml" : "yaml", value: raw.value } : null;
+}
+// Read frontmatter after plugins so their YAML/TOML edits reach the result.
+export function createHastHandleFromMdast(source, mdastPlugins, mdx, fileURL, parseOptions, nativeConvertOptions, data, trackPositions) {
+    if (mdastPlugins.length === 0) {
+        const [hastHandle, raw] = mdx
+            ? createMdxHastHandleWithFrontmatter(source, parseOptions, nativeConvertOptions, trackPositions)
+            : createHastHandleWithFrontmatter(source, parseOptions, nativeConvertOptions, trackPositions);
+        return {
+            hastHandle,
+            frontmatter: raw ? { kind: raw.kind === "toml" ? "toml" : "yaml", value: raw.value } : null,
+        };
+    }
+    const mdastHandle = mdx
+        ? createMdxMdastHandle(source, parseOptions, trackPositions)
+        : createMdastHandle(source, parseOptions, trackPositions);
+    const sourceFormat = mdx ? "mdx" : "markdown";
+    // Conversion empties the arena on success; finally also releases it on failure.
+    const finalize = (r) => {
+        try {
+            const frontmatter = readFrontmatter(r.handle);
+            // Conversion empties the MDAST arena, invalidating retained child stubs.
+            markHandleMutated(r.handle);
+            const hastHandle = convertMdastToHastHandle(r.handle, nativeConvertOptions);
+            return { hastHandle, frontmatter };
+        }
+        finally {
+            releaseHandle(r.handle, true);
+        }
+    };
+    try {
+        const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, fileURL, data, sourceFormat);
+        if (mdastResult instanceof Promise) {
+            return mdastResult.then(finalize, (err) => {
+                releaseHandle(mdastHandle, true);
+                throw err;
+            });
+        }
+        return finalize(mdastResult);
+    }
+    catch (err) {
+        releaseHandle(mdastHandle, true);
+        throw err;
+    }
+}

package/dist/plugin.d.ts

@@ -18,10 +18,13 @@ export interface PluginFactoryContext {
     /** The document-level data bag, before any plugin has run. */
     readonly data: Data;
 }
-export type MdastPluginDefinition = MdastPluginInstance & {
+type RequireAtLeastOne<T, K extends keyof T> = Omit<T, K> & {
+    [P in K]-?: Required<Pick<T, P>> & Partial<Pick<T, Exclude<K, P>>>;
+}[K];
+export type MdastPluginDefinition = RequireAtLeastOne<MdastPluginInstance, Exclude<keyof MdastPluginInstance, "options">> & {
     name: string;
 };
-export type HastPluginDefinition = HastVisitorInstance & {
+export type HastPluginDefinition = RequireAtLeastOne<HastVisitorInstance, Exclude<keyof HastVisitorInstance, "options">> & {
     name: string;
 };
 type PluginEntry<D> = D | ((ctx: PluginFactoryContext) => PluginEntry<D>) | readonly PluginEntry<D>[] | null | undefined | false;
@@ -33,13 +36,11 @@ export type HastPluginEntry = PluginEntry<HastPluginDefinition>;
 export type MdastPluginList = readonly MdastPluginEntry[];
 /** Value accepted by the `hastPlugins` option. */
 export type HastPluginList = readonly HastPluginEntry[];
-/** Older name for {@link MdastPluginEntry}. */
+/** Alias for {@link MdastPluginEntry}. */
 export type MdastPluginInput = MdastPluginEntry;
-/** Older name for {@link HastPluginEntry}. */
+/** Alias for {@link HastPluginEntry}. */
 export type HastPluginInput = HastPluginEntry;
-/** The one place a plugin option becomes the definition array the pipeline
- *  runs. Factories resolve here and nowhere else, so each is called once per
- *  compile no matter how deeply it is nested. */
+/** Resolve nested entries and invoke each factory once per compile. */
 export declare function normalizePlugins<D>(entries: readonly PluginEntry<D>[], option: string, source: string, fileURL: URL | undefined, sourceFormat: SourceFormat, data: Data): D[];
 export declare function defineMdastPlugin<P extends MdastPluginDefinition>(definition: P): P;
 export declare function defineHastPlugin<P extends HastPluginDefinition>(definition: P): P;

package/dist/plugin.js

@@ -1,10 +1,6 @@
-/** Bounds factory-in-factory nesting. Real presets nest one level; anything
- *  deeper is a factory that leads back to itself, which would otherwise recurse
- *  until the stack overflows. */
+// Bound recursive factories so a self-referential preset cannot overflow the stack.
 const MAX_FACTORY_DEPTH = 10;
-/** The one place a plugin option becomes the definition array the pipeline
- *  runs. Factories resolve here and nowhere else, so each is called once per
- *  compile no matter how deeply it is nested. */
+/** Resolve nested entries and invoke each factory once per compile. */
 export function normalizePlugins(entries, option, source, fileURL, sourceFormat, data) {
     const out = [];
     // Built lazily so a list with no factories allocates no context.
@@ -46,9 +42,7 @@ export function normalizePlugins(entries, option, source, fileURL, sourceFormat,
         walk(entry, MAX_FACTORY_DEPTH);
     return out;
 }
-// Generic so the inferred plugin type preserves each visitor's *actual* return
-// type. That lets the compile entry points distinguish sync plugins from async
-// ones in their conditional return type.
+// Preserve each visitor’s inferred return type so compile results can distinguish sync from async plugins.
 export function defineMdastPlugin(definition) {
     if (!definition.name) {
         throw new Error("Plugin definition must have a name");

package/dist/types.d.ts

@@ -154,7 +154,6 @@ export interface BufferHeader {
     typeDataOffset: number;
     stringPoolLen: number;
     stringPoolOffset: number;
-    /** Number of nodes that carry an extra JSON `data` blob. */
     nodeDataCount: number;
     /** Offset of the node-data section: `[id u32][len u32][bytes...]` repeated. */
     nodeDataOffset: number;

package/dist/visitor-node.d.ts

@@ -0,0 +1,12 @@
+import { type NodeRefs } from "./visitor-shared.js";
+declare class PlainNode {
+    type: string;
+    constructor(type: string);
+}
+export declare class VisitorNode extends PlainNode {
+    #private;
+    [key: string]: unknown;
+    constructor(type: string, refs: NodeRefs, id: number);
+    static getNodeId(node: object, refs: NodeRefs): number | undefined;
+}
+export {};

package/dist/visitor-node.js

@@ -0,0 +1,23 @@
+import { FOREIGN_REF } from "./visitor-shared.js";
+class PlainNode {
+    constructor(type) {
+        return { type };
+    }
+}
+// Private identity avoids a WeakMap insertion for every matched node. A derived constructor
+// installs its fields on the plain object returned by super(), preserving plain-node consumers
+// without a costly prototype change. Spreads and structured clones never copy this identity.
+export class VisitorNode extends PlainNode {
+    #refs;
+    #id;
+    constructor(type, refs, id) {
+        super(type);
+        this.#refs = refs;
+        this.#id = id;
+    }
+    static getNodeId(node, refs) {
+        if (!(#refs in node))
+            return undefined;
+        return node.#refs === refs ? node.#id : FOREIGN_REF;
+    }
+}