satteri 0.1.0 → 0.1.3

package/README.md

@@ -1,7 +1,301 @@
 # 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.
+
+### `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/command-buffer.js

@@ -8,9 +8,7 @@
  * All multi-byte integers are little-endian to match native x86/ARM layout and
  * avoid byte-swapping on the Rust side.
  */
-// ---------------------------------------------------------------------------
 // Command bytes (0x01–0x0F)
-// ---------------------------------------------------------------------------
 const CMD_REMOVE = 0x01;
 const CMD_INSERT_BEFORE = 0x05;
 const CMD_INSERT_AFTER = 0x06;
@@ -19,15 +17,11 @@ const CMD_APPEND_CHILD = 0x08;
 const CMD_WRAP = 0x09;
 const CMD_REPLACE = 0x0b;
 const CMD_SET_PROPERTY = 0x0c;
-// ---------------------------------------------------------------------------
 // Payload types (0x10+, distinct range from commands)
-// ---------------------------------------------------------------------------
 const PAYLOAD_RAW_MARKDOWN = 0x10;
 const PAYLOAD_RAW_HTML = 0x11;
 const PAYLOAD_SERDE_JSON = 0x12;
-// ---------------------------------------------------------------------------
 // Value types for CMD_SET_PROPERTY (must match commands.rs PROP_* constants)
-// ---------------------------------------------------------------------------
 const PROP_STRING = 0;
 const PROP_BOOL_TRUE = 1;
 const PROP_BOOL_FALSE = 2;
@@ -46,9 +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);
@@ -62,7 +53,6 @@ export class CommandBuffer {
         this.view = new DataView(this.buffer);
         this.bytes = new Uint8Array(this.buffer);
     }
-    // -- Public command methods -----------------------------------------------
     removeNode(nodeId) {
         this.ensureCapacity(5);
         this.writeU8(CMD_REMOVE);
@@ -154,7 +144,6 @@ export class CommandBuffer {
         this.writeU32(encoded.length);
         this.writeBytes(encoded);
     }
-    // -- Result accessors -----------------------------------------------------
     /** Return a Uint8Array view of the written bytes (no copy). */
     getBuffer() {
         return new Uint8Array(this.buffer, 0, this.offset);
@@ -170,7 +159,6 @@ export class CommandBuffer {
         this.bytes = new Uint8Array(this.buffer);
         this.offset = 0;
     }
-    // -- Private helpers ------------------------------------------------------
     writeStructuralCommand(cmd, nodeId, node) {
         const v = node;
         if (typeof v.raw === "string") {
@@ -192,7 +180,7 @@ export class CommandBuffer {
             this.writeBytes(encoded);
         }
         else {
-            // Structured node — serialize as JSON
+            // Structured node, serialize as JSON
             const json = JSON.stringify(node);
             const encoded = encoder.encode(json);
             this.ensureCapacity(10 + encoded.length);
@@ -228,4 +216,3 @@ export class CommandBuffer {
         this.offset += data.length;
     }
 }
-//# sourceMappingURL=command-buffer.js.map

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;
@@ -15,8 +10,18 @@ export interface OptimizeStaticConfig {
 export interface CompileOptions {
     mdastPlugins?: MdastPluginDefinition[];
     hastPlugins?: HastPluginDefinition[];
-    optimizeStatic?: OptimizeStaticConfig;
     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;
+}
+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): MdastNode;
+/** Parse MDX source into a materialized mdast tree. */
+export declare function mdxToMdast(source: string): MdastNode;
+/** Convert Markdown source to a materialized hast tree. */
+export declare function markdownToHast(source: string): HastNode;
+/** Convert MDX source to a materialized hast tree. */
+export declare function mdxToHast(source: string): HastNode;

package/dist/compile.js

@@ -1,39 +1,27 @@
-/**
- * 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 "../index.js";
+import { ArenaReader } from "./mdast/mdast-reader.js";
+import { materializeTree } from "./mdast/mdast-materializer.js";
+import { HastReader } from "./hast/hast-reader.js";
+import { materializeHastTree } from "./hast/hast-materializer.js";
 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 };
     };
@@ -49,20 +37,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);
             }
@@ -70,7 +54,7 @@ function runHastPluginsOnHandle(handle, plugins, source, filename) {
     };
     return runNext();
 }
-export function compileMarkdownToHtml(source, options = {}) {
+export function markdownToHtml(source, options = {}) {
     const { mdastPlugins = [], hastPlugins = [], filename = "<unknown>" } = options;
     if (mdastPlugins.length === 0 && hastPlugins.length === 0) {
         return parseToHtml(source);
@@ -94,7 +78,7 @@ export function compileMarkdownToHtml(source, options = {}) {
     }
     return finish(handleResult);
 }
-export function compileMdxToJs(source, options = {}) {
+export function mdxToJs(source, options = {}) {
     const { mdastPlugins = [], hastPlugins = [], optimizeStatic, filename = "<unknown>" } = options;
     const mdxOptions = optimizeStatic ? { optimizeStatic } : undefined;
     if (mdastPlugins.length === 0 && hastPlugins.length === 0) {
@@ -119,10 +103,8 @@ export function compileMdxToJs(source, options = {}) {
     }
     return finish(handleResult);
 }
-// ---------------------------------------------------------------------------
 // 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) {
     if (mdastPlugins.length === 0) {
@@ -141,4 +123,30 @@ function createHastHandleFromMdast(source, mdastPlugins, mdx, filename) {
     }
     return convert(mdastResult);
 }
-//# sourceMappingURL=compile.js.map
+// Step-by-step API: individual pipeline stages with materialized trees
+/** Parse Markdown source into a materialized mdast tree. */
+export function markdownToMdast(source) {
+    const handle = createMdastHandle(source);
+    const buf = serializeMdastHandle(handle);
+    return materializeTree(new ArenaReader(buf));
+}
+/** Parse MDX source into a materialized mdast tree. */
+export function mdxToMdast(source) {
+    const handle = createMdxMdastHandle(source);
+    const buf = serializeMdastHandle(handle);
+    return materializeTree(new ArenaReader(buf));
+}
+/** Convert Markdown source to a materialized hast tree. */
+export function markdownToHast(source) {
+    const handle = createHastHandle(source);
+    const buf = serializeHandle(handle);
+    dropHandle(handle);
+    return materializeHastTree(new HastReader(buf));
+}
+/** Convert MDX source to a materialized hast tree. */
+export function mdxToHast(source) {
+    const handle = createMdxHastHandle(source);
+    const buf = serializeHandle(handle);
+    dropHandle(handle);
+    return materializeHastTree(new HastReader(buf));
+}

package/dist/hast/hast-materializer.js

@@ -147,4 +147,3 @@ export function materializeHastNode(reader, nodeId) {
 export function materializeHastTree(reader) {
     return materializeHastNode(reader, 0);
 }
-//# sourceMappingURL=hast-materializer.js.map

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

@@ -1,5 +1,5 @@
 import type { BufferHeader } from "../types.js";
-import type { MdxJsxAttribute, MdxJsxExpressionAttribute } from "mdast-util-mdx-jsx";
+import type { MdxJsxAttribute, MdxJsxExpressionAttribute } from "../mdx-types.js";
 export type { MdxJsxAttribute, MdxJsxExpressionAttribute };
 export declare const HAST_ROOT = 0;
 export declare const HAST_ELEMENT = 1;

package/dist/hast/hast-reader.js

@@ -21,7 +21,7 @@ const MDX_ATTR_BOOLEAN_PROP = 0;
 const MDX_ATTR_LITERAL_PROP = 1;
 const MDX_ATTR_EXPRESSION_PROP = 2;
 const MDX_ATTR_SPREAD = 3;
-// HastNode field offsets (same layout as MDAST — shared binary format)
+// HastNode field offsets (same layout as MDAST, shared binary format)
 //   id: u32          @ 0
 //   node_type: u8    @ 4
 //   _pad: [u8; 3]    @ 5
@@ -277,4 +277,3 @@ export class HastReader {
         return this.getString(ref.offset, ref.len);
     }
 }
-//# sourceMappingURL=hast-reader.js.map

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

@@ -1,9 +1,9 @@
 import { type HastNode } from "./hast-materializer.js";
 import type { HastRaw } from "../types.js";
 import type { Element, Text, Comment, Doctype } from "hast";
-import type { MdxJsxFlowElementHast, MdxJsxTextElementHast } from "mdast-util-mdx-jsx";
-import type { MdxFlowExpressionHast, MdxTextExpressionHast } from "mdast-util-mdx-expression";
-import type { MdxjsEsmHast } from "mdast-util-mdxjs-esm";
+import type { MdxJsxFlowElementHast, MdxJsxTextElementHast } from "../mdx-types.js";
+import type { MdxFlowExpressionHast, MdxTextExpressionHast } from "../mdx-types.js";
+import type { MdxjsEsmHast } from "../mdx-types.js";
 export type HastHandle = any;
 /** ESTree-compatible Program node returned by `parseExpression()`. */
 export type EstreeProgram = Record<string, any>;
@@ -15,19 +15,19 @@ export interface HastDiagnostic {
 export interface HastVisitorContext {
     readonly source: string;
     readonly filename: string;
-    removeNode(node: HastNode): void;
-    replaceNode(node: HastNode, newNode: HastNode): void;
-    insertBefore(node: HastNode, newNode: HastNode): void;
-    insertAfter(node: HastNode, newNode: HastNode): void;
-    wrapNode(node: HastNode, parentNode: HastNode): void;
-    prependChild(node: HastNode, childNode: HastNode): void;
-    appendChild(node: HastNode, childNode: HastNode): void;
-    setProperty(node: HastNode, key: string, value: unknown): void;
+    removeNode(node: Readonly<HastNode>): void;
+    replaceNode(node: Readonly<HastNode>, newNode: HastNode): void;
+    insertBefore(node: Readonly<HastNode>, newNode: HastNode): void;
+    insertAfter(node: Readonly<HastNode>, newNode: HastNode): void;
+    wrapNode(node: Readonly<HastNode>, parentNode: HastNode): void;
+    prependChild(node: Readonly<HastNode>, childNode: HastNode): void;
+    appendChild(node: Readonly<HastNode>, childNode: HastNode): void;
+    setProperty(node: Readonly<HastNode>, key: string, value: unknown): void;
     /** Collect the concatenated text of all descendant text nodes (like DOM textContent). */
-    textContent(node: HastNode): string;
+    textContent(node: Readonly<HastNode>): string;
     report(opts: {
         message: string;
-        node?: HastNode;
+        node?: Readonly<HastNode>;
         severity?: "error" | "warning" | "info";
     }): void;
     getDiagnostics(): HastDiagnostic[];
@@ -35,9 +35,9 @@ export interface HastVisitorContext {
 /** A filtered visitor: Rust filters by tag/component name, only matched nodes cross the boundary. */
 export interface HastFilteredVisitor<N extends HastNode = HastNode> {
     filter: string[];
-    visit(node: N, ctx: HastVisitorContext): HastNode | void | Promise<HastNode | void>;
+    visit(node: Readonly<N>, ctx: HastVisitorContext): HastNode | void | Promise<HastNode | void>;
 }
-type HastVisitorFn<N extends HastNode = HastNode> = (node: N, ctx: HastVisitorContext) => HastNode | void | Promise<HastNode | void>;
+type HastVisitorFn<N extends HastNode = HastNode> = (node: Readonly<N>, ctx: HastVisitorContext) => HastNode | void | Promise<HastNode | void>;
 export interface HastVisitorInstance {
     element?: HastFilteredVisitor<Element> | HastFilteredVisitor<Element>[];
     mdxJsxFlowElement?: HastFilteredVisitor<MdxJsxFlowElementHast> | HastFilteredVisitor<MdxJsxFlowElementHast>[];