satteri 0.10.5 → 0.11.1

package/dist/compile.js

@@ -1,310 +1,36 @@
-import { visitHastHandle, visitHastHandleCollect, visitHastHook, visitHastHookCollect, resolveSubscriptions, } from "./hast/hast-visitor.js";
-import { visitMdastHandle, visitMdastHook, resolveMdastSubscriptions, } from "./mdast/mdast-visitor.js";
-import { normalizePlugins } from "./plugin.js";
-import { applyCommandsAndCompileHandle, applyCommandsAndRenderHandle, applyCommandsToMdastHandle, applyMdastCommandsAndConvertAndCompile, applyMdastCommandsAndConvertAndRender, compileHandle, convertMdastToHastHandle, createHastHandle, createHastHandleFromHtml, createMdastHandle, createMdxHastHandle, createMdxMdastHandle, dropHandle, getHandleSource, createHastHandleWithFrontmatter, createMdxHastHandleWithFrontmatter, getMdastFrontmatter, markdownToHtmlFast, markdownToJsFast, mdxToJsFast, renderHandle, serializeHandle, } from "#binding";
-import { ENABLE_DEFINITION_LIST, ENABLE_DIRECTIVE, ENABLE_FOOTNOTES, ENABLE_GFM, ENABLE_HEADING_ATTRIBUTES, ENABLE_MATH, ENABLE_MATH_MULTI_DOLLAR, ENABLE_PLUSES_DELIMITED_METADATA_BLOCKS, ENABLE_SMART_DASHES, ENABLE_SMART_ELLIPSES, ENABLE_SMART_PUNCTUATION, ENABLE_SMART_QUOTES, ENABLE_STRIKETHROUGH, ENABLE_SUBSCRIPT, ENABLE_SUPERSCRIPT, ENABLE_TABLES, ENABLE_TASKLISTS, ENABLE_WIKILINKS, ENABLE_YAML_STYLE_METADATA_BLOCKS, } from "./generated/parse-options.js";
-import { MdastReader } from "./mdast/mdast-reader.js";
-import { materializeMdastTree } from "./mdast/mdast-materializer.js";
-import { markHandleMutated } from "./lazy-child-resolver.js";
-import { HastReader } from "./hast/hast-reader.js";
+import { encodeHastDocument } from "./hast/hast-visitor.js";
+import { featuresToNative, mdxOptionsToNative } from "./compile-options.js";
+import { createHastHandleFromMdast, EMPTY_COMMAND_BUFFER, releaseHandle, runHastPluginsCollectLast, runMdastPluginsOnHandle, warnIfDroppedTransforms, } from "./plugin-pipeline.js";
+export { DEFAULT_PARSE_OPTIONS, featuresToNative } from "./compile-options.js";
+import { applyCommandsAndCompileHandle, applyCommandsAndRenderHandle, applyCommandsToHandle, applyMdastCommandsAndConvertAndCompile, applyMdastCommandsAndConvertAndRender, compileHandle, createHastHandleFromHtml, createMdastHandle, createMdxMdastHandle, markdownToHtmlFast, markdownToJsFast, mdxToJsFast, parseHastWire, parseMdastWire, renderHandle, renderHastOpstream, serializeHandle, } from "#binding";
 import { materializeHastTree } from "./hast/hast-materializer.js";
-const GFM_PARSE_OPTIONS = ENABLE_TABLES | ENABLE_STRIKETHROUGH | ENABLE_TASKLISTS | ENABLE_GFM;
-const FRONTMATTER_PARSE_OPTIONS = ENABLE_YAML_STYLE_METADATA_BLOCKS | ENABLE_PLUSES_DELIMITED_METADATA_BLOCKS;
-export const DEFAULT_PARSE_OPTIONS = GFM_PARSE_OPTIONS | ENABLE_FOOTNOTES | FRONTMATTER_PARSE_OPTIONS;
-/** Packs into the bit set napi reads straight back as `satteri_pulldown_cmark::Options`. */
-function featuresToParseOptions(features) {
-    let options = 0;
-    const { gfm } = features;
-    if (typeof gfm === "object") {
-        options |= GFM_PARSE_OPTIONS;
-        if (gfm.footnotes !== false)
-            options |= ENABLE_FOOTNOTES;
-    }
-    else if (gfm ?? true) {
-        options |= GFM_PARSE_OPTIONS | ENABLE_FOOTNOTES;
-    }
-    if (features.frontmatter ?? true)
-        options |= FRONTMATTER_PARSE_OPTIONS;
-    // Opting out of single-dollar math sets the multi-dollar sub-flag so the parser skips lone `$`.
-    const { math } = features;
-    if (typeof math === "object") {
-        options |= math.singleDollarTextMath === false ? ENABLE_MATH_MULTI_DOLLAR : ENABLE_MATH;
-    }
-    else if (math) {
-        options |= ENABLE_MATH;
-    }
-    if (features.headingAttributes)
-        options |= ENABLE_HEADING_ATTRIBUTES;
-    if (features.directive)
-        options |= ENABLE_DIRECTIVE;
-    if (features.superscript)
-        options |= ENABLE_SUPERSCRIPT;
-    if (features.subscript)
-        options |= ENABLE_SUBSCRIPT;
-    if (features.wikilinks)
-        options |= ENABLE_WIKILINKS;
-    if (features.definitionList)
-        options |= ENABLE_DEFINITION_LIST;
-    const smartPunctuation = features.smartPunctuation;
-    if (typeof smartPunctuation === "object") {
-        if (smartPunctuation.quotes ?? true)
-            options |= ENABLE_SMART_QUOTES;
-        if (smartPunctuation.dashes ?? true)
-            options |= ENABLE_SMART_DASHES;
-        if (smartPunctuation.ellipses ?? true)
-            options |= ENABLE_SMART_ELLIPSES;
-    }
-    else if (smartPunctuation) {
-        options |= ENABLE_SMART_PUNCTUATION;
-    }
-    return options;
-}
-/**
- * Split the user-facing `Features` into the packed parser options plus the
- * conversion-side `JsConvertOptions` carrying the footnote i18n strings and the
- * raw-HTML reparse. The public API only exposes `features`; both halves are
- * routed to napi internally.
- */
-export function featuresToNative(features) {
-    if (!features)
-        return { parseOptions: DEFAULT_PARSE_OPTIONS, convertOptions: undefined };
-    let convertOptions;
-    const { gfm } = features;
-    if (typeof gfm === "object" && typeof gfm.footnotes === "object") {
-        const { label, backContent, backLabel, clobberPrefix } = gfm.footnotes;
-        convertOptions = {};
-        if (label !== undefined)
-            convertOptions.footnoteLabel = label;
-        if (backContent !== undefined)
-            convertOptions.footnoteBackContent = backContent;
-        if (backLabel !== undefined)
-            convertOptions.footnoteBackLabel = backLabel;
-        if (clobberPrefix !== undefined)
-            convertOptions.clobberPrefix = clobberPrefix;
-    }
-    if (features.rawHtml !== undefined) {
-        // Routed to convert options so every pipeline (fast paths, plugin paths,
-        // *ToHast) applies the reparse.
-        convertOptions = convertOptions ?? {};
-        convertOptions.rawHtml = features.rawHtml;
-    }
-    return { parseOptions: featuresToParseOptions(features), convertOptions };
-}
-/** Free a handle's arena. A plugin's visitor can hand child stubs to user code;
- *  pass `invalidateStubs` so the epoch bump makes any stub retained past this
- *  point hit the designed retention error instead of snapshotting the freed arena. */
-function releaseHandle(handle, invalidateStubs) {
-    if (invalidateStubs)
-        markHandleMutated(handle);
-    dropHandle(handle);
-}
-function warnDroppedTransforms(plugin, dropped, kind) {
-    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;
-}
-/** Stays synchronous until a step actually returns a promise. */
-function sequence(steps) {
-    let pending;
-    for (const step of steps) {
-        if (step === undefined)
-            continue;
-        pending = pending === undefined ? step() : pending.then(step);
-    }
-    return pending;
-}
-function runMdastPluginsOnHandle(handle, plugins, fileURL, data, sourceFormat, collectLast = false) {
-    const out = { handle };
-    // A plugin's visitors run once over the tree. A transform that passes a child
-    // through (returning it inside the replacement) keeps that child's identity,
-    // so a patch the same pass queued on it still applies: nesting composes in
-    // one pass. Visitor-built nodes are not re-walked; transform them up front,
-    // or hand off to a later plugin that sees the materialized tree.
-    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);
-            if (dropped)
-                warnDroppedTransforms(plugin, dropped, "mdast");
-        };
-        const before = typeof plugin.before === "function" ? plugin.before : undefined;
-        const after = typeof plugin.after === "function" ? plugin.after : undefined;
-        const hasVisitors = subs.length > 0;
-        // Threaded like `data`: one context per pass, since a resolver is epoch-bound.
-        const diagnostics = [];
-        const runHook = (hook, isFinalPass) => () => settle(visitMdastHook(handle, plugin, hook, () => getHandleSource(handle), fileURL, data, sourceFormat, diagnostics), (r) => apply(r, isFinalPass));
-        const runVisitors = (isFinalPass) => () => settle(visitMdastHandle(handle, plugin, subs, () => getHandleSource(handle), 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();
-}
-const EMPTY_COMMAND_BUFFER = new Uint8Array(0);
-const NO_HAST_COMMANDS = {
-    commands: EMPTY_COMMAND_BUFFER,
-    lastPlugin: null,
-};
-/** Run every HAST plugin except the last one normally (each applies its
- *  commands inline), then return the last plugin's commands without applying.
- *  Lets the caller fuse the final apply with the downstream NAPI step
- *  (`render` or `compile`), saving one NAPI roundtrip per compile. */
-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);
-            const finalPass = passes.pop();
-            if (finalPass === undefined)
-                continue;
-            const warnIfDropped = (dropped) => {
-                if (dropped)
-                    warnDroppedTransforms(plugin, dropped, "hast");
-            };
-            // Threaded like `data`: one context per pass, since a resolver is epoch-bound.
-            const diagnostics = [];
-            const runApplied = (pass) => () => settle(pass === "visitors"
-                ? visitHastHandle(handle, plugin, subs, source, fileURL, data, sourceFormat, diagnostics)
-                : visitHastHook(handle, plugin, pass, source, fileURL, data, sourceFormat, diagnostics), warnIfDropped);
-            const collectFinal = () => {
-                const collected = finalPass === "visitors"
-                    ? visitHastHandleCollect(handle, plugin, subs, source, fileURL, data, sourceFormat, diagnostics)
-                    : visitHastHookCollect(handle, plugin, finalPass, source, fileURL, data, sourceFormat, diagnostics);
-                return collected instanceof Promise
-                    ? collected.then((commands) => ({ commands, lastPlugin: plugin }))
-                    : { commands: collected, lastPlugin: plugin };
-            };
-            const head = sequence(passes.map(runApplied));
-            if (isLastPlugin) {
-                return head instanceof Promise ? head.then(collectFinal) : collectFinal();
-            }
-            const tail = head instanceof Promise ? head.then(runApplied(finalPass)) : runApplied(finalPass)();
-            if (tail instanceof Promise)
-                return tail.then(runNext);
-        }
-        return NO_HAST_COMMANDS;
-    };
-    return runNext();
-}
-// Public API
-function mdxOptionsToNative(opts) {
-    const hasAny = opts.optimizeStatic ||
-        opts.jsxImportSource !== undefined ||
-        opts.jsx !== undefined ||
-        opts.jsxRuntime !== undefined ||
-        opts.development !== undefined ||
-        opts.providerImportSource !== undefined ||
-        opts.pragma !== undefined ||
-        opts.pragmaFrag !== undefined ||
-        opts.pragmaImportSource !== undefined ||
-        opts.outputFormat !== undefined ||
-        opts.elementAttributeNameCase !== undefined ||
-        opts.stylePropertyNameCase !== undefined;
-    if (!hasAny)
-        return undefined;
-    const result = {};
-    if (opts.optimizeStatic)
-        result.optimizeStatic = opts.optimizeStatic;
-    if (opts.jsxImportSource !== undefined)
-        result.jsxImportSource = opts.jsxImportSource;
-    if (opts.jsx !== undefined)
-        result.jsx = opts.jsx;
-    if (opts.jsxRuntime !== undefined)
-        result.jsxRuntime = opts.jsxRuntime;
-    if (opts.development !== undefined)
-        result.development = opts.development;
-    if (opts.providerImportSource !== undefined)
-        result.providerImportSource = opts.providerImportSource;
-    if (opts.pragma !== undefined)
-        result.pragma = opts.pragma;
-    if (opts.pragmaFrag !== undefined)
-        result.pragmaFrag = opts.pragmaFrag;
-    if (opts.pragmaImportSource !== undefined)
-        result.pragmaImportSource = opts.pragmaImportSource;
-    if (opts.outputFormat !== undefined)
-        result.outputFormat = opts.outputFormat;
-    if (opts.elementAttributeNameCase !== undefined)
-        result.elementAttributeNameCase = opts.elementAttributeNameCase;
-    if (opts.stylePropertyNameCase !== undefined)
-        result.stylePropertyNameCase = opts.stylePropertyNameCase;
-    return result;
-}
+import { HastReader } from "./hast/hast-reader.js";
+import { materializeMdastTree } from "./mdast/mdast-materializer.js";
+import { MdastReader } from "./mdast/mdast-reader.js";
+import { normalizePlugins } from "./plugin.js";
 export function markdownToHtml(source, options = {}) {
     const { features, fileURL, data = {} } = options;
     const mdastPlugins = normalizePlugins(options.mdastPlugins ?? [], "mdastPlugins", source, fileURL, "markdown", data);
     const hastPlugins = normalizePlugins(options.hastPlugins ?? [], "hastPlugins", source, fileURL, "markdown", data);
     const hastMayHaveStubs = hastPlugins.length > 0;
     const { parseOptions, convertOptions: nativeConvertOptions } = featuresToNative(features);
-    // Fast path: no plugins → parse, convert, render, and frontmatter all happen
-    // inside a single NAPI call. Skips 5 handle-NAPI roundtrips that the
-    // plugin-capable path needs to keep the arena live across passes.
+    // Without plugins, one NAPI call avoids the handle lifecycle’s extra boundary crossings.
     if (mdastPlugins.length === 0 && hastPlugins.length === 0) {
         const { html, frontmatter } = markdownToHtmlFast(source, parseOptions, nativeConvertOptions);
         return { html, frontmatter: frontmatter ?? null, data };
     }
-    // Track source positions only when some plugin opts in with `position: true`;
-    // otherwise the parse skips the LineIndex build and per-node line/column lookups.
+    // Skip position tracking unless requested to avoid line-index construction and per-node lookups.
     const trackPositions = mdastPlugins.some((p) => p.options?.position) || hastPlugins.some((p) => p.options?.position);
-    // Fused tail for MDAST-plugins-only (no HAST plugins): after the MDAST
-    // plugin pass returns its pending commands, apply + convert + render all
-    // happen inside a single NAPI roundtrip. Saves the convert-to-hast handle
-    // create + render + drop crossings the generic path makes separately.
+    // Without HAST plugins, fuse apply, conversion, and rendering to avoid extra NAPI crossings.
     if (hastPlugins.length === 0) {
         const mdastHandle = createMdastHandle(source, parseOptions, trackPositions);
         try {
             const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, fileURL, data, "markdown", true);
             const finishMdast = (r) => {
                 try {
-                    // Fused tail: apply pending commands (empty buffer is a Rust no-op),
-                    // extract frontmatter post-mutation, convert, render, all in one
-                    // NAPI roundtrip.
                     const commands = r.pendingCommands ?? EMPTY_COMMAND_BUFFER;
                     const { html, frontmatter, droppedTransforms } = applyMdastCommandsAndConvertAndRender(r.handle, commands, nativeConvertOptions);
-                    if (droppedTransforms && r.lastPlugin)
-                        warnDroppedTransforms(r.lastPlugin, droppedTransforms, "mdast");
+                    warnIfDroppedTransforms(droppedTransforms, r.lastPlugin, "mdast");
                     return {
                         html,
                         frontmatter: frontmatter ?? null,
@@ -330,9 +56,6 @@ export function markdownToHtml(source, options = {}) {
     }
     const result = createHastHandleFromMdast(source, mdastPlugins, false, fileURL, parseOptions, nativeConvertOptions, data, trackPositions);
     const runHastThenRender = (r) => {
-        // Run all but the last HAST plugin normally (each one applies its
-        // commands inline); collect the last plugin's commands and fuse apply +
-        // render + handle-drop into one NAPI call.
         let collected;
         try {
             collected = runHastPluginsCollectLast(r.hastHandle, hastPlugins, source, fileURL, data, "markdown");
@@ -353,10 +76,9 @@ export function markdownToHtml(source, options = {}) {
         try {
             let html;
             if (collected.commands.length > 0) {
-                const result = applyCommandsAndRenderHandle(h, collected.commands);
-                if (result.droppedTransforms && collected.lastPlugin)
-                    warnDroppedTransforms(collected.lastPlugin, result.droppedTransforms, "hast");
-                html = result.html;
+                const transformed = applyCommandsAndRenderHandle(h, collected.commands);
+                warnIfDroppedTransforms(transformed.droppedTransforms, collected.lastPlugin, "hast");
+                html = transformed.html;
             }
             else {
                 html = renderHandle(h);
@@ -377,7 +99,6 @@ export function mdxToJs(source, options = {}) {
 export function markdownToJs(source, options = {}) {
     return toJsImpl(source, options, false);
 }
-/** `mdx` picks the parser; the pipeline is identical from MDAST on. */
 function toJsImpl(source, options, mdx) {
     const { mdastPlugins: mdastInput = [], hastPlugins: hastInput = [], features, fileURL, data = {}, ...mdxFields } = options;
     const sourceFormat = mdx ? "mdx" : "markdown";
@@ -386,17 +107,13 @@ function toJsImpl(source, options, mdx) {
     const hastMayHaveStubs = hastPlugins.length > 0;
     const mdxOptions = mdxOptionsToNative(mdxFields);
     const { parseOptions, convertOptions: nativeConvertOptions } = featuresToNative(features);
-    // Fast path: same trick as `markdownToHtml`. Parse → MDAST → HAST → JS plus
-    // frontmatter extraction all happen inside a single NAPI call. Skips 5 of
-    // the 6 handle-based crossings the plugin-capable path needs.
+    // Without plugins, one NAPI call avoids the handle lifecycle’s extra boundary crossings.
     if (mdastPlugins.length === 0 && hastPlugins.length === 0) {
         const { code, frontmatter } = (mdx ? mdxToJsFast : markdownToJsFast)(source, parseOptions, mdxOptions, nativeConvertOptions);
         return { code, frontmatter: frontmatter ?? null, data };
     }
-    // Track positions only when a plugin opts in (see `markdownToHtml`).
     const trackPositions = mdastPlugins.some((p) => p.options?.position) || hastPlugins.some((p) => p.options?.position);
-    // MDAST-plugins-only fused tail (no HAST plugins): apply + extract
-    // frontmatter + convert + simplify + compile happen in one NAPI call.
+    // Without HAST plugins, fuse apply, conversion, and compilation to avoid extra NAPI crossings.
     if (hastPlugins.length === 0) {
         const mdastHandle = mdx
             ? createMdxMdastHandle(source, parseOptions, trackPositions)
@@ -407,8 +124,7 @@ function toJsImpl(source, options, mdx) {
                 try {
                     const commands = r.pendingCommands ?? EMPTY_COMMAND_BUFFER;
                     const { code, frontmatter, droppedTransforms } = applyMdastCommandsAndConvertAndCompile(r.handle, commands, mdxOptions, nativeConvertOptions);
-                    if (droppedTransforms && r.lastPlugin)
-                        warnDroppedTransforms(r.lastPlugin, droppedTransforms, "mdast");
+                    warnIfDroppedTransforms(droppedTransforms, r.lastPlugin, "mdast");
                     return {
                         code,
                         frontmatter: frontmatter ?? null,
@@ -454,10 +170,9 @@ function toJsImpl(source, options, mdx) {
         try {
             let code;
             if (collected.commands.length > 0) {
-                const result = applyCommandsAndCompileHandle(h, collected.commands, mdxOptions);
-                if (result.droppedTransforms && collected.lastPlugin)
-                    warnDroppedTransforms(collected.lastPlugin, result.droppedTransforms, "hast");
-                code = result.code;
+                const transformed = applyCommandsAndCompileHandle(h, collected.commands, mdxOptions);
+                warnIfDroppedTransforms(transformed.droppedTransforms, collected.lastPlugin, "hast");
+                code = transformed.code;
             }
             else {
                 code = compileHandle(h, mdxOptions);
@@ -492,99 +207,111 @@ export function evaluate(source, options) {
     }
     return new Function(result.code)(runtime);
 }
-function readFrontmatter(handle) {
-    const raw = getMdastFrontmatter(handle);
-    return raw ? { kind: raw.kind === "toml" ? "toml" : "yaml", value: raw.value } : null;
+function materializeMdastHandle(handle) {
+    try {
+        return materializeMdastTree(new MdastReader(serializeHandle(handle)));
+    }
+    finally {
+        releaseHandle(handle, true);
+    }
 }
-/** Parse, run mdast plugins, capture frontmatter, then convert to HAST.
- *  Frontmatter is read from the post-plugin MDAST so visitor mutations to
- *  the yaml/toml node are reflected in the returned value. */
-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,
-        };
+function materializeHastHandle(handle, invalidateStubs) {
+    try {
+        return materializeHastTree(new HastReader(serializeHandle(handle)));
     }
-    const mdastHandle = mdx
-        ? createMdxMdastHandle(source, parseOptions, trackPositions)
-        : createMdastHandle(source, parseOptions, trackPositions);
-    const sourceFormat = mdx ? "mdx" : "markdown";
-    const mdastMayHaveStubs = mdastPlugins.length > 0;
-    // finally{release} is intentional: convertMdastToHastHandle empties the arena
-    // on success, but if any step here throws the handle would otherwise leak.
-    const finalize = (r) => {
+    finally {
+        releaseHandle(handle, invalidateStubs);
+    }
+}
+function applyCollectedHastCommands(handle, collected, invalidateStubs) {
+    if (collected.commands.length > 0) {
         try {
-            const frontmatter = readFrontmatter(r.handle);
-            // convert empties the mdast arena, so invalidate any stub held past this point.
-            if (mdastMayHaveStubs)
-                markHandleMutated(r.handle);
-            const hastHandle = convertMdastToHastHandle(r.handle, nativeConvertOptions);
-            return { hastHandle, frontmatter };
+            const dropped = applyCommandsToHandle(handle, collected.commands);
+            warnIfDroppedTransforms(dropped, collected.lastPlugin, "hast");
         }
-        finally {
-            releaseHandle(r.handle, mdastMayHaveStubs);
+        catch (err) {
+            releaseHandle(handle, invalidateStubs);
+            throw err;
         }
-    };
+    }
+    return materializeHastHandle(handle, invalidateStubs);
+}
+function toMdastImpl(source, options, mdx) {
+    const { features, fileURL, data = {} } = options;
+    const sourceFormat = mdx ? "mdx" : "markdown";
+    const mdastPlugins = normalizePlugins(options.mdastPlugins ?? [], "mdastPlugins", source, fileURL, sourceFormat, data);
+    const { parseOptions } = featuresToNative(features);
+    if (mdastPlugins.length === 0) {
+        const wire = parseMdastWire(source, parseOptions, mdx, options.position);
+        return materializeMdastTree(new MdastReader(wire));
+    }
+    // Tree callers control positions independently of plugin requirements.
+    const trackPositions = options.position ?? true;
+    const handle = mdx
+        ? createMdxMdastHandle(source, parseOptions, trackPositions)
+        : createMdastHandle(source, parseOptions, trackPositions);
     try {
-        const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, fileURL, data, sourceFormat);
-        if (mdastResult instanceof Promise) {
-            return mdastResult.then(finalize, (err) => {
-                releaseHandle(mdastHandle, mdastMayHaveStubs);
+        const result = runMdastPluginsOnHandle(handle, mdastPlugins, fileURL, data, sourceFormat);
+        if (result instanceof Promise) {
+            return result.then((r) => materializeMdastHandle(r.handle), (err) => {
+                releaseHandle(handle, true);
                 throw err;
             });
         }
-        return finalize(mdastResult);
+        return materializeMdastHandle(result.handle);
     }
     catch (err) {
-        releaseHandle(mdastHandle, mdastMayHaveStubs);
+        releaseHandle(handle, true);
         throw err;
     }
 }
-/** Parse Markdown source into a materialized mdast tree. */
-export function markdownToMdast(source, options = {}) {
-    const handle = createMdastHandle(source, featuresToNative(options.features).parseOptions, options.position);
-    try {
-        return materializeMdastTree(new MdastReader(serializeHandle(handle)));
-    }
-    finally {
-        releaseHandle(handle, true);
+function toHastImpl(source, options, mdx) {
+    const { features, fileURL, data = {} } = options;
+    const sourceFormat = mdx ? "mdx" : "markdown";
+    const mdastPlugins = normalizePlugins(options.mdastPlugins ?? [], "mdastPlugins", source, fileURL, sourceFormat, data);
+    const hastPlugins = normalizePlugins(options.hastPlugins ?? [], "hastPlugins", source, fileURL, sourceFormat, data);
+    const { parseOptions, convertOptions } = featuresToNative(features);
+    if (mdastPlugins.length === 0 && hastPlugins.length === 0) {
+        const wire = parseHastWire(source, parseOptions, convertOptions, mdx, options.position);
+        return materializeHastTree(new HastReader(wire));
     }
+    const trackPositions = options.position ?? true;
+    const hastMayHaveStubs = hastPlugins.length > 0;
+    const runHastPluginsAndMaterialize = (handle) => {
+        if (hastPlugins.length === 0)
+            return materializeHastHandle(handle, hastMayHaveStubs);
+        let collected;
+        try {
+            collected = runHastPluginsCollectLast(handle, hastPlugins, source, fileURL, data, sourceFormat);
+        }
+        catch (err) {
+            releaseHandle(handle, hastMayHaveStubs);
+            throw err;
+        }
+        if (collected instanceof Promise) {
+            return collected.then((c) => applyCollectedHastCommands(handle, c, hastMayHaveStubs), (err) => {
+                releaseHandle(handle, hastMayHaveStubs);
+                throw err;
+            });
+        }
+        return applyCollectedHastCommands(handle, collected, hastMayHaveStubs);
+    };
+    const result = createHastHandleFromMdast(source, mdastPlugins, mdx, fileURL, parseOptions, convertOptions, data, trackPositions);
+    if (result instanceof Promise)
+        return result.then((r) => runHastPluginsAndMaterialize(r.hastHandle));
+    return runHastPluginsAndMaterialize(result.hastHandle);
+}
+export function markdownToMdast(source, options = {}) {
+    return toMdastImpl(source, options, false);
 }
-/** Parse MDX source into a materialized mdast tree. */
 export function mdxToMdast(source, options = {}) {
-    const handle = createMdxMdastHandle(source, featuresToNative(options.features).parseOptions, options.position);
-    try {
-        return materializeMdastTree(new MdastReader(serializeHandle(handle)));
-    }
-    finally {
-        releaseHandle(handle, true);
-    }
+    return toMdastImpl(source, options, true);
 }
-/** Convert Markdown source to a materialized hast tree. */
 export function markdownToHast(source, options = {}) {
-    const { parseOptions, convertOptions } = featuresToNative(options.features);
-    const handle = createHastHandle(source, parseOptions, convertOptions, options.position);
-    try {
-        return materializeHastTree(new HastReader(serializeHandle(handle)));
-    }
-    finally {
-        releaseHandle(handle, true);
-    }
+    return toHastImpl(source, options, false);
 }
-/** Convert MDX source to a materialized hast tree. */
 export function mdxToHast(source, options = {}) {
-    const { parseOptions, convertOptions } = featuresToNative(options.features);
-    const handle = createMdxHastHandle(source, parseOptions, convertOptions, options.position);
-    try {
-        return materializeHastTree(new HastReader(serializeHandle(handle)));
-    }
-    finally {
-        releaseHandle(handle, true);
-    }
+    return toHastImpl(source, options, true);
 }
 /**
  * Parse an HTML string into a materialized hast tree: a `root` whose children
@@ -601,3 +328,26 @@ export function htmlToHast(html, options = {}) {
         releaseHandle(handle, true);
     }
 }
+/**
+ * Serialize a HAST tree to an HTML string: a `root` renders its children, any
+ * other node renders itself, and a list renders in order. MDX nodes have no
+ * HTML representation and are skipped; `raw` nodes are emitted verbatim.
+ *
+ * The result is the tree's exact serialization, with no trailing newline (the
+ * one `markdownToHtml` ends its document with).
+ */
+export function hastToHtml(tree) {
+    return encodeHastDocument(documentNodes(tree), renderHastOpstream);
+}
+/** A `root` contributes its children, wherever it sits, so a list of trees
+ *  serializes as the concatenation of what each renders alone. */
+function documentNodes(tree) {
+    if (!Array.isArray(tree)) {
+        const node = tree;
+        return node.type === "root" ? (node.children ?? []) : [node];
+    }
+    const nodes = tree;
+    return nodes.some((node) => node.type === "root")
+        ? nodes.flatMap((node) => (node.type === "root" ? (node.children ?? []) : [node]))
+        : nodes;
+}

package/dist/directive-types.d.ts

@@ -33,6 +33,7 @@ declare module "mdast" {
         leafDirective: LeafDirective;
     }
     interface ParagraphData {
+        /** Marks a container directive’s label paragraph (`:::note[label]`). */
         directiveLabel?: boolean | null | undefined;
     }
     interface PhrasingContentMap {

package/dist/directive-types.js

@@ -1,7 +1,2 @@
-// Manually-defined directive AST node types.
-//
-// These replicate the type definitions from mdast-util-directive so we can
-// avoid pulling in that package (and its transitive deps) just for the
-// node interfaces. The shapes match what `getDirectiveData` returns from
-// the Rust arena: `name: string`, `attributes: Record<string, string>`.
+// Local interfaces avoid a runtime dependency on mdast-util-directive.
 export {};

package/dist/generated/arena-layout.d.ts

@@ -1,9 +1,6 @@
-/** `b"MDAR"` magic, read as a little-endian u32. */
 export declare const ARENA_MAGIC = 1380009037;
-/** `Arena<K>` kind tags carried in the header's `kind` field. */
 export declare const KIND_MDAST = 1;
 export declare const KIND_HAST = 2;
-/** `ArenaNode` `#[repr(C)]` field byte offsets (u32 fields; `node_type` is a u8). */
 export declare const FIELD: {
     readonly id: 0;
     readonly node_type: 4;
@@ -19,7 +16,12 @@ export declare const FIELD: {
     readonly data_offset: 44;
     readonly data_len: 48;
 };
-/** Raw-buffer header byte offsets (4-byte fields, u32 LE). */
+export declare const W_PARENT = 2;
+export declare const W_START_OFFSET = 3;
+export declare const W_CHILDREN_START = 9;
+export declare const W_CHILDREN_COUNT = 10;
+export declare const W_DATA_OFFSET = 11;
+export declare const W_DATA_LEN = 12;
 export declare const HEADER: {
     readonly magic: 0;
     readonly kind: 4;