satteri 0.9.5 → 0.10.0

package/dist/compile.js

@@ -1,6 +1,7 @@
-import { visitHastHandle, resolveSubscriptions } from "./hast/hast-visitor.js";
-import { visitMdastHandle, resolveMdastSubscriptions, } from "./mdast/mdast-visitor.js";
-import { createHastHandle, createMdxHastHandle, renderHandle, compileHandle, dropHandle, createMdastHandle, createMdxMdastHandle, applyCommandsToMdastHandle, convertMdastToHastHandle, getHandleSource, getMdastFrontmatter, serializeHandle, } from "#binding";
+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 { MdastReader } from "./mdast/mdast-reader.js";
 import { materializeMdastTree } from "./mdast/mdast-materializer.js";
 import { markHandleMutated } from "./lazy-child-resolver.js";
@@ -65,6 +66,8 @@ function featuresToNative(features) {
         result.subscript = features.subscript;
     if (features.wikilinks !== undefined)
         result.wikilinks = features.wikilinks;
+    if (features.definitionList !== undefined)
+        result.definitionList = features.definitionList;
     if (features.smartPunctuation !== undefined) {
         if (typeof features.smartPunctuation === "object") {
             result.smartPunctuationOptions = features.smartPunctuation;
@@ -73,6 +76,12 @@ function featuresToNative(features) {
             result.smartPunctuation = features.smartPunctuation;
         }
     }
+    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 { features: result, convertOptions };
 }
 /** Free a handle's arena. A plugin's visitor can hand child stubs to user code;
@@ -86,64 +95,131 @@ function releaseHandle(handle, invalidateStubs) {
 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 were removed or ` +
-        `replaced earlier in the same pass; ${dropped === 1 ? "it was" : "they were"} dropped.`);
+    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;
 }
-function runMdastPluginsOnHandle(handle, plugins, fileURL, data, sourceFormat) {
-    // Each plugin runs once over the tree. A transform that passes a child
+/** 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. A plugin's own freshly-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) => {
+    // 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 result = visitMdastHandle(handle, plugin, subs, () => getHandleSource(handle), fileURL, data, sourceFormat);
-        const apply = (r) => {
+        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");
         };
-        return result instanceof Promise ? result.then(apply) : apply(result);
+        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 = () => {
-        while (i < plugins.length) {
-            const raw = plugins[i++];
-            const plugin = typeof raw === "function" ? raw() : raw;
-            const r = runPlugin(plugin);
+        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 { handle };
+        return out;
     };
     return runNext();
 }
-function runHastPluginsOnHandle(handle, plugins, source, fileURL, data, sourceFormat) {
-    if (plugins.length === 0)
-        return;
+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 = () => {
-        while (i < plugins.length) {
-            const raw = plugins[i];
+        for (;;) {
+            const plugin = plugins[i];
+            if (plugin === undefined)
+                break;
+            const isLastPlugin = i === plugins.length - 1;
             i++;
-            const plugin = typeof raw === "function" ? raw() : raw;
             const subs = resolveSubscriptions(plugin);
-            const result = visitHastHandle(handle, plugin, subs, source, fileURL, data, sourceFormat);
+            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");
             };
-            if (result instanceof Promise) {
-                return result.then((dropped) => {
-                    warnIfDropped(dropped);
-                    return runNext();
-                });
+            // 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();
             }
-            warnIfDropped(result);
+            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();
 }
@@ -191,71 +267,200 @@ function mdxOptionsToNative(opts) {
     return result;
 }
 export function markdownToHtml(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], features, fileURL, data = {} } = 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 { features: nativeFeatures, convertOptions: nativeConvertOptions } = featuresToNative(features);
-    const result = createHastHandleFromMdast(source, mdastPlugins, false, fileURL, nativeFeatures, nativeConvertOptions, data);
-    const renderAndDrop = (h, frontmatter) => {
+    // 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.
+    if (mdastPlugins.length === 0 && hastPlugins.length === 0) {
+        const { html, frontmatter } = markdownToHtmlFast(source, nativeFeatures, 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.
+    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.
+    if (hastPlugins.length === 0) {
+        const mdastHandle = createMdastHandle(source, nativeFeatures, trackPositions);
         try {
-            const html = renderHandle(h);
-            return { html, frontmatter, data };
+            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");
+                    return {
+                        html,
+                        frontmatter: frontmatter ?? null,
+                        data,
+                    };
+                }
+                finally {
+                    releaseHandle(r.handle, true);
+                }
+            };
+            if (mdastResult instanceof Promise) {
+                return mdastResult.then(finishMdast, (err) => {
+                    releaseHandle(mdastHandle, true);
+                    throw err;
+                });
+            }
+            return finishMdast(mdastResult);
         }
-        finally {
-            releaseHandle(h, hastMayHaveStubs);
+        catch (err) {
+            releaseHandle(mdastHandle, true);
+            throw err;
         }
-    };
+    }
+    const result = createHastHandleFromMdast(source, mdastPlugins, false, fileURL, nativeFeatures, nativeConvertOptions, data, trackPositions);
     const runHastThenRender = (r) => {
-        let hastResult;
+        // 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 {
-            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL, data, "markdown");
+            collected = runHastPluginsCollectLast(r.hastHandle, hastPlugins, source, fileURL, data, "markdown");
         }
         catch (err) {
             releaseHandle(r.hastHandle, hastMayHaveStubs);
             throw err;
         }
-        if (hastResult instanceof Promise) {
-            return hastResult.then(() => renderAndDrop(r.hastHandle, r.frontmatter), (err) => {
+        if (collected instanceof Promise) {
+            return collected.then((c) => finishHastRender(r.hastHandle, c, r.frontmatter), (err) => {
                 releaseHandle(r.hastHandle, hastMayHaveStubs);
                 throw err;
             });
         }
-        return renderAndDrop(r.hastHandle, r.frontmatter);
+        return finishHastRender(r.hastHandle, collected, r.frontmatter);
+    };
+    const finishHastRender = (h, collected, frontmatter) => {
+        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;
+            }
+            else {
+                html = renderHandle(h);
+            }
+            return { html, frontmatter, data };
+        }
+        finally {
+            releaseHandle(h, hastMayHaveStubs);
+        }
     };
     if (result instanceof Promise)
         return result.then(runHastThenRender);
     return runHastThenRender(result);
 }
 export function mdxToJs(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], features, fileURL, data = {}, ...mdxFields } = options;
+    return toJsImpl(source, options, true);
+}
+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";
+    const mdastPlugins = normalizePlugins(mdastInput, "mdastPlugins", source, fileURL, sourceFormat, data);
+    const hastPlugins = normalizePlugins(hastInput, "hastPlugins", source, fileURL, sourceFormat, data);
     const hastMayHaveStubs = hastPlugins.length > 0;
     const mdxOptions = mdxOptionsToNative(mdxFields);
     const { features: nativeFeatures, convertOptions: nativeConvertOptions } = featuresToNative(features);
-    const result = createHastHandleFromMdast(source, mdastPlugins, true, fileURL, nativeFeatures, nativeConvertOptions, data);
-    const compileAndDrop = (h, frontmatter) => {
+    // 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.
+    if (mdastPlugins.length === 0 && hastPlugins.length === 0) {
+        const { code, frontmatter } = (mdx ? mdxToJsFast : markdownToJsFast)(source, nativeFeatures, 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.
+    if (hastPlugins.length === 0) {
+        const mdastHandle = mdx
+            ? createMdxMdastHandle(source, nativeFeatures, trackPositions)
+            : createMdastHandle(source, nativeFeatures, trackPositions);
         try {
-            const code = compileHandle(h, mdxOptions);
-            return { code, frontmatter, data };
+            const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, fileURL, data, mdx ? "mdx" : "markdown", true);
+            const finishMdast = (r) => {
+                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");
+                    return {
+                        code,
+                        frontmatter: frontmatter ?? null,
+                        data,
+                    };
+                }
+                finally {
+                    releaseHandle(r.handle, true);
+                }
+            };
+            if (mdastResult instanceof Promise) {
+                return mdastResult.then(finishMdast, (err) => {
+                    releaseHandle(mdastHandle, true);
+                    throw err;
+                });
+            }
+            return finishMdast(mdastResult);
         }
-        finally {
-            releaseHandle(h, hastMayHaveStubs);
+        catch (err) {
+            releaseHandle(mdastHandle, true);
+            throw err;
         }
-    };
+    }
+    const result = createHastHandleFromMdast(source, mdastPlugins, mdx, fileURL, nativeFeatures, nativeConvertOptions, data, trackPositions);
     const runHastThenCompile = (r) => {
-        let hastResult;
+        let collected;
         try {
-            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL, data, "mdx");
+            collected = runHastPluginsCollectLast(r.hastHandle, hastPlugins, source, fileURL, data, mdx ? "mdx" : "markdown");
         }
         catch (err) {
             releaseHandle(r.hastHandle, hastMayHaveStubs);
             throw err;
         }
-        if (hastResult instanceof Promise) {
-            return hastResult.then(() => compileAndDrop(r.hastHandle, r.frontmatter), (err) => {
+        if (collected instanceof Promise) {
+            return collected.then((c) => finishHastCompile(r.hastHandle, c, r.frontmatter), (err) => {
                 releaseHandle(r.hastHandle, hastMayHaveStubs);
                 throw err;
             });
         }
-        return compileAndDrop(r.hastHandle, r.frontmatter);
+        return finishHastCompile(r.hastHandle, collected, r.frontmatter);
+    };
+    const finishHastCompile = (h, collected, frontmatter) => {
+        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;
+            }
+            else {
+                code = compileHandle(h, mdxOptions);
+            }
+            return { code, frontmatter, data };
+        }
+        finally {
+            releaseHandle(h, hastMayHaveStubs);
+        }
     };
     if (result instanceof Promise)
         return result.then(runHastThenCompile);
@@ -292,10 +497,19 @@ function createHastHandleFromMdast(source, mdastPlugins, mdx, fileURL,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 nativeFeatures, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-nativeConvertOptions, data) {
+nativeConvertOptions, data, trackPositions) {
+    if (mdastPlugins.length === 0) {
+        const [hastHandle, raw] = mdx
+            ? createMdxHastHandleWithFrontmatter(source, nativeFeatures, nativeConvertOptions, trackPositions)
+            : createHastHandleWithFrontmatter(source, nativeFeatures, nativeConvertOptions, trackPositions);
+        return {
+            hastHandle,
+            frontmatter: raw ? { kind: raw.kind === "toml" ? "toml" : "yaml", value: raw.value } : null,
+        };
+    }
     const mdastHandle = mdx
-        ? createMdxMdastHandle(source, nativeFeatures)
-        : createMdastHandle(source, nativeFeatures);
+        ? createMdxMdastHandle(source, nativeFeatures, trackPositions)
+        : createMdastHandle(source, nativeFeatures, trackPositions);
     const sourceFormat = mdx ? "mdx" : "markdown";
     const mdastMayHaveStubs = mdastPlugins.length > 0;
     // finally{release} is intentional: convertMdastToHastHandle empties the arena
@@ -314,9 +528,6 @@ nativeConvertOptions, data) {
         }
     };
     try {
-        if (mdastPlugins.length === 0) {
-            return finalize({ handle: mdastHandle });
-        }
         const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, fileURL, data, sourceFormat);
         if (mdastResult instanceof Promise) {
             return mdastResult.then(finalize, (err) => {
@@ -331,10 +542,9 @@ nativeConvertOptions, data) {
         throw err;
     }
 }
-// Step-by-step API: individual pipeline stages with materialized trees
 /** Parse Markdown source into a materialized mdast tree. */
 export function markdownToMdast(source, options = {}) {
-    const handle = createMdastHandle(source, featuresToNative(options.features).features);
+    const handle = createMdastHandle(source, featuresToNative(options.features).features, options.position);
     try {
         return materializeMdastTree(new MdastReader(serializeHandle(handle)));
     }
@@ -344,7 +554,7 @@ export function markdownToMdast(source, options = {}) {
 }
 /** Parse MDX source into a materialized mdast tree. */
 export function mdxToMdast(source, options = {}) {
-    const handle = createMdxMdastHandle(source, featuresToNative(options.features).features);
+    const handle = createMdxMdastHandle(source, featuresToNative(options.features).features, options.position);
     try {
         return materializeMdastTree(new MdastReader(serializeHandle(handle)));
     }
@@ -355,7 +565,7 @@ export function mdxToMdast(source, options = {}) {
 /** Convert Markdown source to a materialized hast tree. */
 export function markdownToHast(source, options = {}) {
     const { features: nativeFeatures, convertOptions } = featuresToNative(options.features);
-    const handle = createHastHandle(source, nativeFeatures, convertOptions);
+    const handle = createHastHandle(source, nativeFeatures, convertOptions, options.position);
     try {
         return materializeHastTree(new HastReader(serializeHandle(handle)));
     }
@@ -366,7 +576,21 @@ export function markdownToHast(source, options = {}) {
 /** Convert MDX source to a materialized hast tree. */
 export function mdxToHast(source, options = {}) {
     const { features: nativeFeatures, convertOptions } = featuresToNative(options.features);
-    const handle = createMdxHastHandle(source, nativeFeatures, convertOptions);
+    const handle = createMdxHastHandle(source, nativeFeatures, convertOptions, options.position);
+    try {
+        return materializeHastTree(new HastReader(serializeHandle(handle)));
+    }
+    finally {
+        releaseHandle(handle, true);
+    }
+}
+/**
+ * Parse an HTML string into a materialized hast tree: a `root` whose children
+ * are the doctype (if any) and the implied `<html>` subtree. Only available
+ * in builds that include the `from-html` feature.
+ */
+export function htmlToHast(html) {
+    const handle = createHastHandleFromHtml(html);
     try {
         return materializeHastTree(new HastReader(serializeHandle(handle)));
     }

package/dist/freeze.d.ts

@@ -0,0 +1,2 @@
+/** Freeze JSON-shaped data recursively; never call on objects with lazy getters. */
+export declare function deepFreeze<T>(value: T): T;

package/dist/freeze.js

@@ -0,0 +1,10 @@
+/** Freeze JSON-shaped data recursively; never call on objects with lazy getters. */
+export function deepFreeze(value) {
+    if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const key of Object.keys(value)) {
+            deepFreeze(value[key]);
+        }
+    }
+    return value;
+}

package/dist/generated/wire-constants.d.ts

@@ -35,9 +35,9 @@ export declare const CMD_WRAP = 9;
 export declare const CMD_REPLACE = 11;
 export declare const CMD_SET_PROPERTY = 12;
 export declare const CMD_SET_CHILDREN = 13;
-export declare const PAYLOAD_RAW_MARKDOWN = 16;
-export declare const PAYLOAD_RAW_HTML = 17;
+export declare const PAYLOAD_RAW = 16;
 export declare const PAYLOAD_OPSTREAM = 20;
+export declare const RAW_LITERAL_BRACES = 1;
 export declare const PROP_STRING = 0;
 export declare const PROP_BOOL_TRUE = 1;
 export declare const PROP_BOOL_FALSE = 2;
@@ -45,6 +45,7 @@ export declare const PROP_SPACE_SEP = 3;
 export declare const PROP_COMMA_SEP = 4;
 export declare const PROP_INT = 5;
 export declare const PROP_NULL = 6;
+export declare const PROP_COMMA_SEP_NUM = 7;
 export declare const MDX_ATTR_BOOLEAN_PROP = 0;
 export declare const MDX_ATTR_LITERAL_PROP = 1;
 export declare const MDX_ATTR_EXPRESSION_PROP = 2;

package/dist/generated/wire-constants.js

@@ -45,9 +45,10 @@ export const CMD_REPLACE = 0x0b;
 export const CMD_SET_PROPERTY = 0x0c; // [valueType: u8][name str][value str], PROP_* value kinds
 export const CMD_SET_CHILDREN = 0x0d; // payload is a Root-wrapped child list
 // Structural-command payload types (0x10+, a range distinct from commands).
-export const PAYLOAD_RAW_MARKDOWN = 0x10; // [len: u32 LE][utf8] — re-parsed as markdown
-export const PAYLOAD_RAW_HTML = 0x11; // [len: u32 LE][utf8] — re-parsed as HTML/MDX
+export const PAYLOAD_RAW = 0x10; // [flags: u8][len: u32 LE][utf8] — re-parsed as markdown; see RAW_* flags
 export const PAYLOAD_OPSTREAM = 0x14; // [len: u32 LE][op bytes] — replayed straight into the arena
+// Flag bits for the `PAYLOAD_RAW` payload.
+export const RAW_LITERAL_BRACES = 0x01; // keep MDX `{…}` as literal text (only affects MDX output)
 // Property value kinds (HAST element properties and SET_PROPERTY commands).
 export const PROP_STRING = 0; // UTF-8 value
 export const PROP_BOOL_TRUE = 1; // no value bytes
@@ -56,6 +57,7 @@ export const PROP_SPACE_SEP = 3; // space-separated list (UTF-8)
 export const PROP_COMMA_SEP = 4; // comma-separated list (UTF-8)
 export const PROP_INT = 5; // decimal string, parsed to i64
 export const PROP_NULL = 6; // no value bytes
+export const PROP_COMMA_SEP_NUM = 7; // comma-separated list, numeric items parsed to numbers
 // MDX JSX attribute kinds (MDAST and HAST MDX JSX element type_data).
 export const MDX_ATTR_BOOLEAN_PROP = 0; // name only, no value
 export const MDX_ATTR_LITERAL_PROP = 1; // name="literal"

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

@@ -5,9 +5,8 @@ type HastResolver = LazyChildResolver<HastReader, HastNode>;
 /**
  * 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()`
- * in hast-visitor.ts.
+ * `materializeOne`, which enforces the handle epoch). Spread/identity rules
+ * are enforced by `nid()` in hast-visitor.ts.
  */
 export declare class HastChildStub {
     _resolver: HastResolver;

package/dist/hast/child-stub.js

@@ -1,16 +1,17 @@
-import { flatByTag, stubDescriptors } from "../child-stub.js";
+import { flatByTag, installStubDescriptors, stubDescriptors, } from "../child-stub.js";
 import { NAME_TO_TYPE, TYPE_NAMES } from "./generated/node-types.js";
+import { HAST_CONTAINER_TYPES } from "./hast-materializer.js";
 const N = NAME_TO_TYPE;
-/** Per-type stub fields, mirroring `materializeHastNode`'s switch. */
+/** Per-type stub fields; must mirror `materializeHastNode`'s populate switch. */
 const HAST_STUB_FIELDS = {
-    [N.root]: ["children"],
-    [N.element]: ["tagName", "properties", "children"],
+    [N.root]: [],
+    [N.element]: ["tagName", "properties"],
     [N.text]: ["value"],
     [N.comment]: ["value"],
     [N.doctype]: [],
     [N.raw]: ["value"],
-    [N.mdxJsxFlowElement]: ["name", "attributes", "children"],
-    [N.mdxJsxTextElement]: ["name", "attributes", "children"],
+    [N.mdxJsxFlowElement]: ["name", "attributes"],
+    [N.mdxJsxTextElement]: ["name", "attributes"],
     [N.mdxFlowExpression]: ["value"],
     [N.mdxTextExpression]: ["value"],
     [N.mdxjsEsm]: ["value"],
@@ -19,16 +20,18 @@ const TYPE_NAME_BY_TAG = flatByTag(TYPE_NAMES);
 const HAST_STUB_DESCRIPTORS = [];
 for (const tag of Object.keys(HAST_STUB_FIELDS)) {
     const nodeType = Number(tag);
-    HAST_STUB_DESCRIPTORS[nodeType] = stubDescriptors(HAST_STUB_FIELDS[nodeType]);
+    const fields = [...HAST_STUB_FIELDS[nodeType]];
+    if (HAST_CONTAINER_TYPES.has(nodeType))
+        fields.push("children");
+    HAST_STUB_DESCRIPTORS[nodeType] = stubDescriptors(fields);
 }
 /** Unknown node types still expose the prelude-backed lazy fields. */
 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()`
- * in hast-visitor.ts.
+ * `materializeOne`, which enforces the handle epoch). Spread/identity rules
+ * are enforced by `nid()` in hast-visitor.ts.
  */
 export class HastChildStub {
     _resolver;
@@ -38,6 +41,10 @@ export class HastChildStub {
         this._resolver = resolver;
         this._id = id;
         this.type = TYPE_NAME_BY_TAG[nodeType] ?? `unknown(${nodeType})`;
-        Object.defineProperties(this, HAST_STUB_DESCRIPTORS[nodeType] ?? FALLBACK_DESCRIPTORS);
+        installStubDescriptors(this, HAST_STUB_DESCRIPTORS[nodeType] ?? FALLBACK_DESCRIPTORS);
+    }
+    /** @internal */
+    get _refs() {
+        return this._resolver.refs;
     }
 }

package/dist/hast/element-props.d.ts

@@ -1,2 +1,2 @@
-export type HastPropertyValue = string | number | boolean | string[];
+export type HastPropertyValue = string | number | boolean | (string | number)[];
 export declare function decodeElementProp(kind: number, value: string): HastPropertyValue;