satteri 0.1.1 → 0.2.0

package/README.md

@@ -1,7 +1,303 @@
 # satteri
 
-TypeScript layer with readers, visitors, materializers, and plugin system for Sätteri, a high-performance Markdown and MDX processor.
+Native-enhanced Markdown parsing and processing for JavaScript. Parse and compile in Rust, create flexible plugins in JavaScript.
 
-> [!NOTE]
-> **Work in progress** — this package is under active development.
-> See the [Contributing Guide](../../CONTRIBUTING.md) if you want to get involved!
+## Install
+
+```sh
+npm install satteri
+yarn add satteri
+pnpm add satteri
+```
+
+## Usage
+
+### Markdown to HTML
+
+```ts
+import { markdownToHtml } from "satteri";
+
+const html = markdownToHtml("# Hello\n\nWorld");
+// <h1>Hello</h1>\n<p>World</p>
+```
+
+### MDX to JS
+
+```ts
+import { mdxToJs } from "satteri";
+
+const js = mdxToJs("# Hello\n\n<MyComponent />");
+```
+
+### With plugins
+
+Both functions accept `mdastPlugins` (operate on the Markdown AST before conversion to HAST) and `hastPlugins` (operate on the HAST before output).
+
+```ts
+import { markdownToHtml } from "satteri";
+import { removeHeadings } from "./my-mdast-plugins.js";
+import { addLinkClasses } from "./my-hast-plugins.js";
+
+const html = markdownToHtml("# Hello\n\n[link](https://example.com)", {
+  mdastPlugins: [removeHeadings],
+  hastPlugins: [addLinkClasses],
+});
+```
+
+If you're familiar with the unified ecosystem, mdast and hast plugins would be similar to remark and rehype plugins, respectively, and re-uses the same AST shape for both. This project does not currently have an equivalent of micromark or recma plugins.
+
+## Plugins
+
+### MDAST plugins
+
+MDAST plugins run on the Markdown syntax tree, allowing you to do things like replace emoji shortcodes, unwrap images from paragraphs, or collect headings for a table of contents before Markdown is transformed to HTML / JS. Define visitor methods named after node types (`heading`, `code`, `link`, `image`, etc.). Each visitor receives the node and a context object for mutations.
+
+```ts
+const emojis = defineMdastPlugin({
+  name: "emojis",
+  text(node, ctx) {
+    if (node.value.includes(":wave:")) {
+      ctx.setProperty(node, "value", node.value.replaceAll(":wave:", "\u{1F44B}"));
+    }
+  },
+});
+```
+
+Visitors can alternatively return a replacement node, raw Markdown, or raw HTML. This is useful when the replacement can't be expressed as property changes on the original node:
+
+```ts
+const highlightCode = defineMdastPlugin({
+  name: "highlight-code",
+  code(node) {
+    return { rawHtml: `<pre class="highlighted">${escape(node.value)}</pre>` };
+  },
+});
+```
+
+All standard mdast node types are supported, plus GFM extensions (`table`, `tableRow`, `tableCell`, `delete`, `footnoteDefinition`, `footnoteReference`) and MDX nodes (`mdxJsxFlowElement`, `mdxJsxTextElement`, `mdxFlowExpression`, `mdxTextExpression`, `mdxjsEsm`) if enabled. For more information on the AST shape and node types, see the [mdast spec](https://github.com/syntax-tree/mdast).
+
+### HAST plugins
+
+HAST plugins run on the HTML syntax tree after mdast-to-hast conversion, allowing you to do things like add classes to elements, set attributes on links, or wrap HTML elements with other elements, etc. Element visitors use a `filter` array to specify which tag names (or component names for MDX) to match.
+
+```ts
+const addLinkClasses = defineHastPlugin({
+  name: "add-link-classes",
+  element: {
+    filter: ["a"],
+    visit(node, ctx) {
+      ctx.setProperty(node, "class", "link");
+      ctx.setProperty(node, "target", "_blank");
+    },
+  },
+});
+```
+
+Multiple filter groups on the same node type:
+
+```ts
+const multiFilter = defineHastPlugin({
+  name: "multi-filter",
+  element: [
+    {
+      filter: ["h1", "h2", "h3"],
+      visit(node, ctx) {
+        ctx.setProperty(node, "class", "heading");
+      },
+    },
+    {
+      filter: ["a"],
+      visit(node, ctx) {
+        ctx.setProperty(node, "target", "_blank");
+      },
+    },
+  ],
+});
+```
+
+An empty filter matches all elements, but can quickly become expensive when used on large documents, so use with caution:
+
+```ts
+const allElements = defineHastPlugin({
+  name: "all-elements",
+  element: {
+    filter: [],
+    visit(node, ctx) {
+      ctx.setProperty(node, "data-visited", "true");
+    },
+  },
+});
+```
+
+Non-element visitors (`text`, `comment`, `raw`, `doctype`, MDX expression types) use bare functions instead of filter objects:
+
+```ts
+const uppercaseText = defineHastPlugin({
+  name: "uppercase-text",
+  text(node, ctx) {
+    ctx.setProperty(node, "value", node.value.toUpperCase());
+  },
+});
+```
+
+For more information on the AST shape and node types, see the [hast spec](https://github.com/syntax-tree/hast).
+
+### Mutating nodes
+
+Unlike remark and rehype plugins, nodes in Sätteri inside plugins are read-only. The AST lives in Rust memory and JavaScript only has a "view" over the different nodes, so direct mutations like `node.value = "new text"` have no effect. Use the context methods (`ctx.setProperty`, `ctx.removeNode`, `ctx.replaceNode`, etc.) instead, which send changes back to Rust in an efficient way.
+
+```ts
+// Won't work
+heading(node, ctx) {
+  node.depth = 2; // no effect, TypeScript will also complain that the node is readonly
+}
+
+// Do this instead
+heading(node, ctx) {
+  ctx.setProperty(node, "depth", 2);
+}
+
+// Or return a new node to replace it entirely, but this is less efficient and generally not recommended
+heading(node) {
+  return { ..node, depth: 2 };
+}
+```
+
+### Async plugins
+
+Visitors can optionally be async. When any visitor is async, `markdownToHtml` and `mdxToJs` return a `Promise<string>` instead of `string`. For performance reasons, it is typically best to avoid async visitors, especially if your visitor matches a large number of nodes.
+
+````ts
+const highlighter = await createHighlighter({ themes: ["github-dark"], langs: ["js", "ts"] });
+
+const asyncHighlight = defineMdastPlugin({
+  name: "async-highlight",
+  async code(node) {
+    const html = await highlighter.codeToHtml(node.value, {
+      lang: node.lang,
+      theme: "github-dark",
+    });
+    return { rawHtml: html };
+  },
+});
+
+// Returns Promise<string> when async plugins are used
+const html = await markdownToHtml("```js\ncode\n```", {
+  mdastPlugins: [asyncHighlight],
+});
+````
+
+## API
+
+### `markdownToHtml(source: string, options?: CompileOptions)`
+
+Parse Markdown and compile to HTML. Returns `string` if all plugins are sync, `Promise<string>` if any are async.
+
+```ts
+const html = markdownToHtml("# Hello\n\nWorld");
+// <h1>Hello</h1>\n<p>World</p>
+```
+
+### `mdxToJs(source: string, options?: MdxCompileOptions)`
+
+Parse MDX and compile to JavaScript module code. Same sync/async return behavior.
+
+```ts
+const js = mdxToJs("# Hello\n\n<MyComponent />");
+```
+
+#### Static optimization
+
+The `optimizeStatic` option for MDX collapses static subtrees into pre-rendered HTML strings, reducing the number of JSX element calls in the output and increasing rendering performance. Dynamic content (JSX components, expressions) is preserved as normal JSX calls.
+
+```ts
+// Astro-style: wraps static HTML in <Fragment set:html="...">
+const js = mdxToJs("# Hello\n\nWorld", {
+  optimizeStatic: {
+    component: "Fragment",
+    prop: "set:html",
+  },
+});
+
+// React-style: wraps in <div dangerouslySetInnerHTML={{ __html: "..." }}>
+const js = mdxToJs("# Hello\n\nWorld", {
+  optimizeStatic: {
+    component: "div",
+    prop: "dangerouslySetInnerHTML",
+    wrapPropValue: true,
+  },
+});
+```
+
+The `ignoreElements` option can be used to exclude specific elements from collapsing.
+
+Shoutout to [Bjorn Lu](https://bjornlu.com) for originally developing this optimization for [Astro](https://astro.build/).
+
+### `markdownToMdast(source: string)`
+
+Parse Markdown and return a complete mdast tree. This can be useful if you wanted to benefit from the fast native parsing of Sätteri, but ultimately wanted another pipeline to handle transformations and compilation, e.g. using remark plugins and `remark-stringify` to convert back to Markdown after processing.
+
+```ts
+import { markdownToMdast } from "satteri";
+
+const tree = markdownToMdast("# Hello\n\nWorld");
+// tree.children[0].type === "heading"
+// tree.children[0].depth === 1
+```
+
+### `mdxToMdast(source: string)`
+
+Parse MDX and return a complete mdast tree.
+
+```ts
+const tree = mdxToMdast('<Component foo="bar" />');
+// tree.children[0].type === "mdxJsxFlowElement"
+// tree.children[0].name === "Component"
+```
+
+### `markdownToHast(source: string)`
+
+Parse Markdown, convert to hast, and return a complete hast tree.
+
+```ts
+const tree = markdownToHast("# Hello\n\nWorld");
+// tree.children[0].type === "element"
+// tree.children[0].tagName === "h1"
+```
+
+### `mdxToHast(source: string)`
+
+Parse MDX, convert to hast, and return a complete hast tree.
+
+```ts
+const tree = mdxToHast("<MyComponent />");
+// tree.children[0].type === "mdxJsxFlowElement"
+// tree.children[0].name === "MyComponent"
+```
+
+### `defineMdastPlugin(definition: MdastPluginDefinition)`
+
+Type-safe wrapper for MDAST plugin definitions.
+
+### `defineHastPlugin(definition: HastPluginDefinition)`
+
+Type-safe wrapper for HAST plugin definitions.
+
+### `CompileOptions`
+
+```ts
+interface CompileOptions {
+  mdastPlugins?: MdastPluginDefinition[];
+  hastPlugins?: HastPluginDefinition[];
+  filename?: string;
+}
+
+// mdxToJs accepts MdxCompileOptions, which extends CompileOptions
+interface MdxCompileOptions extends CompileOptions {
+  optimizeStatic?: OptimizeStaticConfig;
+}
+```
+
+## License
+
+MIT

package/dist/binding.browser.d.ts

@@ -0,0 +1 @@
+export { applyCommandsAndConvertToHastHandle, applyCommandsToHandle, applyCommandsToMdastHandle, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createMdastHandle, createMdxHastHandle, createMdxMdastHandle, dropHandle, getHandleSource, getNodeData, mdastTextContentHandle, parseExpression, parseToHtml, renderHandle, serializeHandle, serializeMdastHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../satteri_napi.wasi-browser.js";

package/dist/binding.browser.js

@@ -0,0 +1,2 @@
+// @ts-nocheck — WASM browser binding has no type declarations
+export { applyCommandsAndConvertToHastHandle, applyCommandsToHandle, applyCommandsToMdastHandle, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createMdastHandle, createMdxHastHandle, createMdxMdastHandle, dropHandle, getHandleSource, getNodeData, mdastTextContentHandle, parseExpression, parseToHtml, renderHandle, serializeHandle, serializeMdastHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../satteri_napi.wasi-browser.js";

package/dist/binding.d.ts

@@ -0,0 +1 @@
+export { applyCommandsAndConvertToHastHandle, applyCommandsToHandle, applyCommandsToMdastHandle, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createMdastHandle, createMdxHastHandle, createMdxMdastHandle, dropHandle, getHandleSource, getNodeData, mdastTextContentHandle, parseExpression, parseToHtml, renderHandle, serializeHandle, serializeMdastHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../index.js";

package/dist/binding.js

@@ -0,0 +1 @@
+export { applyCommandsAndConvertToHastHandle, applyCommandsToHandle, applyCommandsToMdastHandle, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createMdastHandle, createMdxHastHandle, createMdxMdastHandle, dropHandle, getHandleSource, getNodeData, mdastTextContentHandle, parseExpression, parseToHtml, renderHandle, serializeHandle, serializeMdastHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../index.js";

package/dist/command-buffer.js

@@ -40,7 +40,6 @@ export function classifyReturn(value) {
         return "structured_node";
     throw new Error("Invalid return value from visitor: must have raw, rawHtml, or type");
 }
-// CommandBuffer
 const INITIAL_SIZE = 4096;
 const encoder = new TextEncoder();
 const EMPTY_U8 = new Uint8Array(0);

package/dist/compile.d.ts

@@ -1,10 +1,5 @@
-/**
- * Top-level compile functions, the primary public API.
- *
- * Both MDAST and HAST arenas stay in Rust memory via opaque handles.
- * Only matched nodes and mutation commands cross the NAPI boundary.
- */
 import type { MdastPluginDefinition, HastPluginDefinition } from "./plugin.js";
+import type { MdastNode, HastNode } from "./types.js";
 /** Configuration for static subtree collapsing during MDX compilation. */
 export interface OptimizeStaticConfig {
     component: string;
@@ -12,11 +7,69 @@ export interface OptimizeStaticConfig {
     wrapPropValue?: boolean;
     ignoreElements?: string[];
 }
+/** Parser feature toggles. All default to their documented value when omitted. */
+export interface Features {
+    /** GFM: tables, footnotes, strikethrough, task lists, blockquote tags. Default: true. */
+    gfm?: boolean;
+    /** Frontmatter: YAML (`--- ... ---`) and TOML (`+++ ... +++`). Default: true. */
+    frontmatter?: boolean;
+    /** Math blocks and inline math. Default: true. */
+    math?: boolean;
+    /** Heading attributes (`# text { #id .class }`). Default: true. */
+    headingAttributes?: boolean;
+    /** Colon-delimited container directive blocks (`:::`). Default: false. */
+    directive?: boolean;
+    /** Superscript (`^super^`). Default: false. */
+    superscript?: boolean;
+    /** Subscript (`~sub~`). Default: false. */
+    subscript?: boolean;
+    /** Obsidian-style wikilinks (`[[link]]`). Default: false. */
+    wikilinks?: boolean;
+    /** Smart punctuation à la SmartyPants. Default: false. */
+    smartPunctuation?: boolean;
+    /** Definition lists. Default: false. */
+    definitionList?: boolean;
+}
 export interface CompileOptions {
     mdastPlugins?: MdastPluginDefinition[];
     hastPlugins?: HastPluginDefinition[];
-    optimizeStatic?: OptimizeStaticConfig;
+    features?: Features;
     filename?: string;
 }
-export declare function compileMarkdownToHtml(source: string, options?: CompileOptions): string | Promise<string>;
-export declare function compileMdxToJs(source: string, options?: CompileOptions): string | Promise<string>;
+export interface MdxCompileOptions extends CompileOptions {
+    optimizeStatic?: OptimizeStaticConfig;
+    /** Place to import automatic JSX runtimes from (e.g. "react", "preact"). Default: "react". */
+    jsxImportSource?: string;
+    /** Whether to keep JSX instead of compiling it to functions. Default: false. */
+    jsx?: boolean;
+    /** JSX runtime: "automatic" (default) or "classic". */
+    jsxRuntime?: "automatic" | "classic";
+    /** Enable development mode. Default: false. */
+    development?: boolean;
+    /** Place to import the component provider from. */
+    providerImportSource?: string;
+    /** Pragma for JSX in classic runtime (default: "React.createElement"). */
+    pragma?: string;
+    /** Pragma for JSX fragments in classic runtime (default: "React.Fragment"). */
+    pragmaFrag?: string;
+    /** Where to import the pragma from in classic runtime (default: "react"). */
+    pragmaImportSource?: string;
+}
+export declare function markdownToHtml(source: string, options?: CompileOptions): string | Promise<string>;
+export declare function mdxToJs(source: string, options?: MdxCompileOptions): string | Promise<string>;
+/** Parse Markdown source into a materialized mdast tree. */
+export declare function markdownToMdast(source: string, options?: {
+    features?: Features;
+}): MdastNode;
+/** Parse MDX source into a materialized mdast tree. */
+export declare function mdxToMdast(source: string, options?: {
+    features?: Features;
+}): MdastNode;
+/** Convert Markdown source to a materialized hast tree. */
+export declare function markdownToHast(source: string, options?: {
+    features?: Features;
+}): HastNode;
+/** Convert MDX source to a materialized hast tree. */
+export declare function mdxToHast(source: string, options?: {
+    features?: Features;
+}): HastNode;

package/dist/compile.js

@@ -1,37 +1,54 @@
-/**
- * Top-level compile functions, the primary public API.
- *
- * Both MDAST and HAST arenas stay in Rust memory via opaque handles.
- * Only matched nodes and mutation commands cross the NAPI boundary.
- */
 import { visitHastHandle, resolveSubscriptions } from "./hast/hast-visitor.js";
 import { visitMdastHandle, resolveMdastSubscriptions, } from "./mdast/mdast-visitor.js";
-import { parseToHtml, compileMdx, createHastHandle, createMdxHastHandle, renderHandle, compileHandle, applyCommandsToHandle, dropHandle, createMdastHandle, createMdxMdastHandle, applyCommandsToMdastHandle, convertMdastToHastHandle, applyCommandsAndConvertToHastHandle, getHandleSource, } from "../index.js";
-// Helpers
-function initPlugins(plugins) {
-    return plugins.map((def) => ({
-        instance: def.createOnce(),
-        name: def.name,
-    }));
+import { parseToHtml, compileMdx, createHastHandle, createMdxHastHandle, renderHandle, compileHandle, applyCommandsToHandle, dropHandle, createMdastHandle, createMdxMdastHandle, applyCommandsToMdastHandle, convertMdastToHastHandle, applyCommandsAndConvertToHastHandle, getHandleSource, serializeHandle, serializeMdastHandle, } from "#binding";
+import { MdastReader } from "./mdast/mdast-reader.js";
+import { materializeMdastTree } from "./mdast/mdast-materializer.js";
+import { HastReader } from "./hast/hast-reader.js";
+import { materializeHastTree } from "./hast/hast-materializer.js";
+function featuresToNative(features) {
+    if (!features)
+        return undefined;
+    // Build object with only defined keys to satisfy exactOptionalPropertyTypes
+    const result = {};
+    if (features.gfm !== undefined)
+        result.gfm = features.gfm;
+    if (features.frontmatter !== undefined)
+        result.frontmatter = features.frontmatter;
+    if (features.math !== undefined)
+        result.math = features.math;
+    if (features.headingAttributes !== undefined)
+        result.headingAttributes = features.headingAttributes;
+    if (features.directive !== undefined)
+        result.directive = features.directive;
+    if (features.superscript !== undefined)
+        result.superscript = features.superscript;
+    if (features.subscript !== undefined)
+        result.subscript = features.subscript;
+    if (features.wikilinks !== undefined)
+        result.wikilinks = features.wikilinks;
+    if (features.smartPunctuation !== undefined)
+        result.smartPunctuation = features.smartPunctuation;
+    if (features.definitionList !== undefined)
+        result.definitionList = features.definitionList;
+    return result;
 }
 function runMdastPluginsOnHandle(handle, plugins, filename) {
-    const instances = initPlugins(plugins);
     let pendingCommands = null;
     const source = getHandleSource(handle);
     let i = 0;
     const runNext = () => {
-        while (i < instances.length) {
+        while (i < plugins.length) {
             const idx = i++;
-            const { instance } = instances[idx];
-            const subs = resolveMdastSubscriptions(instance);
-            const result = visitMdastHandle(handle, instance, subs, source, filename);
+            const plugin = plugins[idx];
+            const subs = resolveMdastSubscriptions(plugin);
+            const result = visitMdastHandle(handle, plugin, subs, source, filename);
             if (result instanceof Promise) {
                 return result.then((r) => {
-                    applyMdastResult(r, idx, instances.length, handle);
+                    applyMdastResult(r, idx, plugins.length, handle);
                     return runNext();
                 });
             }
-            applyMdastResult(result, idx, instances.length, handle);
+            applyMdastResult(result, idx, plugins.length, handle);
         }
         return { handle, pendingCommands };
     };
@@ -47,18 +64,16 @@ function runMdastPluginsOnHandle(handle, plugins, filename) {
     }
     return runNext();
 }
-// HAST plugin runner (handle-based)
 function runHastPluginsOnHandle(handle, plugins, source, filename) {
     if (plugins.length === 0)
         return;
-    const instances = initPlugins(plugins);
     let i = 0;
     const runNext = () => {
-        while (i < instances.length) {
-            const { instance } = instances[i];
+        while (i < plugins.length) {
+            const plugin = plugins[i];
             i++;
-            const subs = resolveSubscriptions(instance);
-            const result = visitHastHandle(handle, instance, subs, source, filename);
+            const subs = resolveSubscriptions(plugin);
+            const result = visitHastHandle(handle, plugin, subs, source, filename);
             if (result instanceof Promise) {
                 return result.then(runNext);
             }
@@ -66,12 +81,47 @@ function runHastPluginsOnHandle(handle, plugins, source, filename) {
     };
     return runNext();
 }
-export function compileMarkdownToHtml(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], filename = "<unknown>" } = options;
+// 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;
+    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;
+    return result;
+}
+export function markdownToHtml(source, options = {}) {
+    const { mdastPlugins = [], hastPlugins = [], features, filename = "<unknown>" } = options;
+    const nativeFeatures = featuresToNative(features);
     if (mdastPlugins.length === 0 && hastPlugins.length === 0) {
-        return parseToHtml(source);
+        return parseToHtml(source, nativeFeatures);
     }
-    const handleResult = createHastHandleFromMdast(source, mdastPlugins, false, filename);
+    const handleResult = createHastHandleFromMdast(source, mdastPlugins, false, filename, nativeFeatures);
     const finish = (hastHandle) => {
         const asyncResult = runHastPluginsOnHandle(hastHandle, hastPlugins, source, filename);
         if (asyncResult instanceof Promise) {
@@ -90,13 +140,14 @@ export function compileMarkdownToHtml(source, options = {}) {
     }
     return finish(handleResult);
 }
-export function compileMdxToJs(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], optimizeStatic, filename = "<unknown>" } = options;
-    const mdxOptions = optimizeStatic ? { optimizeStatic } : undefined;
+export function mdxToJs(source, options = {}) {
+    const { mdastPlugins = [], hastPlugins = [], features, filename = "<unknown>", ...mdxFields } = options;
+    const mdxOptions = mdxOptionsToNative(mdxFields);
+    const nativeFeatures = featuresToNative(features);
     if (mdastPlugins.length === 0 && hastPlugins.length === 0) {
-        return compileMdx(source, mdxOptions);
+        return compileMdx(source, mdxOptions, nativeFeatures);
     }
-    const handleResult = createHastHandleFromMdast(source, mdastPlugins, true, filename);
+    const handleResult = createHastHandleFromMdast(source, mdastPlugins, true, filename, nativeFeatures);
     const finish = (hastHandle) => {
         const asyncResult = runHastPluginsOnHandle(hastHandle, hastPlugins, source, filename);
         if (asyncResult instanceof Promise) {
@@ -118,11 +169,17 @@ export function compileMdxToJs(source, options = {}) {
 // Pipeline: parse → mdast plugins → hast conversion → hast plugins
 // All arenas stay in Rust. No intermediate buffer copies to JS.
 /** Parse + mdast plugins + convert to HAST handle. */
-function createHastHandleFromMdast(source, mdastPlugins, mdx, filename) {
+function createHastHandleFromMdast(source, mdastPlugins, mdx, filename, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+nativeFeatures) {
     if (mdastPlugins.length === 0) {
-        return mdx ? createMdxHastHandle(source) : createHastHandle(source);
+        return mdx
+            ? createMdxHastHandle(source, nativeFeatures)
+            : createHastHandle(source, nativeFeatures);
     }
-    const mdastHandle = mdx ? createMdxMdastHandle(source) : createMdastHandle(source);
+    const mdastHandle = mdx
+        ? createMdxMdastHandle(source, nativeFeatures)
+        : createMdastHandle(source, nativeFeatures);
     const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, filename);
     const convert = (r) => {
         if (r.pendingCommands) {
@@ -135,3 +192,30 @@ function createHastHandleFromMdast(source, mdastPlugins, mdx, filename) {
     }
     return convert(mdastResult);
 }
+// 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));
+    const buf = serializeMdastHandle(handle);
+    return materializeMdastTree(new MdastReader(buf));
+}
+/** Parse MDX source into a materialized mdast tree. */
+export function mdxToMdast(source, options = {}) {
+    const handle = createMdxMdastHandle(source, featuresToNative(options.features));
+    const buf = serializeMdastHandle(handle);
+    return materializeMdastTree(new MdastReader(buf));
+}
+/** Convert Markdown source to a materialized hast tree. */
+export function markdownToHast(source, options = {}) {
+    const handle = createHastHandle(source, featuresToNative(options.features));
+    const buf = serializeHandle(handle);
+    dropHandle(handle);
+    return materializeHastTree(new HastReader(buf));
+}
+/** Convert MDX source to a materialized hast tree. */
+export function mdxToHast(source, options = {}) {
+    const handle = createMdxHastHandle(source, featuresToNative(options.features));
+    const buf = serializeHandle(handle);
+    dropHandle(handle);
+    return materializeHastTree(new HastReader(buf));
+}

package/dist/hast/hast-materializer.js

@@ -51,7 +51,8 @@ export function materializeHastNode(reader, nodeId) {
             typeName = `unknown(${nodeType})`;
             break;
     }
-    const node = { type: typeName };
+    const position = reader.getPosition(nodeId);
+    const node = (position ? { type: typeName, position } : { type: typeName });
     // _nodeId: non-enumerable internal reference
     Object.defineProperty(node, "_nodeId", {
         value: nodeId,

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

@@ -25,6 +25,19 @@ export declare class HastReader {
     getSource(): string;
     /** Read a substring from the string pool by byte offset and length. */
     getString(offset: number, len: number): string;
+    /** Get position data for a node. */
+    getPosition(nodeId: number): {
+        start: {
+            offset: number;
+            line: number;
+            column: number;
+        };
+        end: {
+            offset: number;
+            line: number;
+            column: number;
+        };
+    } | undefined;
     /** Get the node_type byte for a given node ID. */
     getNodeType(nodeId: number): number;
     /** Get child node IDs for a given node. */