satteri 0.9.4 → 0.10.0

package/README.md

@@ -31,9 +31,19 @@ import { mdxToJs } from "satteri";
 const { code } = mdxToJs("# Hello\n\n<MyComponent />");
 ```
 
+### Markdown to JS
+
+Like `mdxToJs`, but the source is plain Markdown: `{...}` expressions, JSX tags, and `import`/`export` lines are ordinary text instead of MDX syntax.
+
+```ts
+import { markdownToJs } from "satteri";
+
+const { code } = markdownToJs("# Hello\n\n{not an expression}");
+```
+
 ### With plugins
 
-Both functions accept `mdastPlugins` (operate on the Markdown AST) and `hastPlugins` (operate on the HTML AST). A plugin is an object with a `name` and a visitor per node type; `defineMdastPlugin` / `defineHastPlugin` add type inference.
+All three functions accept `mdastPlugins` (operate on the Markdown AST) and `hastPlugins` (operate on the HTML AST). A plugin is an object with a `name` and a visitor per node type; `defineMdastPlugin` / `defineHastPlugin` add type inference.
 
 ```ts
 import { markdownToHtml, defineMdastPlugin } from "satteri";

package/dist/binding.browser.d.ts

@@ -1 +1 @@
-export { applyCommandsAndConvertToHastHandle, applyCommandsToHandle, applyCommandsToMdastHandle, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createMdastHandle, createMdxHastHandle, createMdxMdastHandle, dropHandle, getHandleSource, getMdastFrontmatter, getNodeData, mdastTextContentHandle, parseEsm, parseExpression, parseToHtml, renderHandle, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../browser.js";
+export { applyCommandsAndCompileHandle, applyCommandsAndConvertToHastHandle, applyCommandsAndRenderHandle, applyCommandsToHandle, applyCommandsToMdastHandle, applyMdastCommandsAndConvertAndCompile, applyMdastCommandsAndConvertAndRender, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createHastHandleFromHtml, createHastHandleWithFrontmatter, createMdastHandle, createMdxHastHandle, createMdxHastHandleWithFrontmatter, createMdxMdastHandle, dropHandle, getHandleSource, getMdastFrontmatter, getNodeData, markdownToHtmlFast, markdownToJsFast, mdastTextContentHandle, mdxToJsFast, parseEsm, parseExpression, parseToHtml, renderHandle, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../browser.js";

package/dist/binding.browser.js

@@ -1,2 +1,2 @@
 // @ts-nocheck — WASM browser binding has no type declarations
-export { applyCommandsAndConvertToHastHandle, applyCommandsToHandle, applyCommandsToMdastHandle, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createMdastHandle, createMdxHastHandle, createMdxMdastHandle, dropHandle, getHandleSource, getMdastFrontmatter, getNodeData, mdastTextContentHandle, parseEsm, parseExpression, parseToHtml, renderHandle, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../browser.js";
+export { applyCommandsAndCompileHandle, applyCommandsAndConvertToHastHandle, applyCommandsAndRenderHandle, applyCommandsToHandle, applyCommandsToMdastHandle, applyMdastCommandsAndConvertAndCompile, applyMdastCommandsAndConvertAndRender, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createHastHandleFromHtml, createHastHandleWithFrontmatter, createMdastHandle, createMdxHastHandle, createMdxHastHandleWithFrontmatter, createMdxMdastHandle, dropHandle, getHandleSource, getMdastFrontmatter, getNodeData, markdownToHtmlFast, markdownToJsFast, mdastTextContentHandle, mdxToJsFast, parseEsm, parseExpression, parseToHtml, renderHandle, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../browser.js";

package/dist/binding.d.ts

@@ -1 +1 @@
-export { applyCommandsAndConvertToHastHandle, applyCommandsToHandle, applyCommandsToMdastHandle, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createMdastHandle, createMdxHastHandle, createMdxMdastHandle, dropHandle, getHandleSource, getMdastFrontmatter, getNodeData, mdastTextContentHandle, parseEsm, parseExpression, parseToHtml, renderHandle, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../index.js";
+export { applyCommandsAndCompileHandle, applyCommandsAndConvertToHastHandle, applyCommandsAndRenderHandle, applyCommandsToHandle, applyCommandsToMdastHandle, applyMdastCommandsAndConvertAndCompile, applyMdastCommandsAndConvertAndRender, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createHastHandleFromHtml, createHastHandleWithFrontmatter, createMdastHandle, createMdxHastHandle, createMdxHastHandleWithFrontmatter, createMdxMdastHandle, dropHandle, getHandleSource, getMdastFrontmatter, getNodeData, markdownToHtmlFast, markdownToJsFast, mdastTextContentHandle, mdxToJsFast, parseEsm, parseExpression, parseToHtml, renderHandle, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../index.js";

package/dist/binding.js

@@ -1 +1 @@
-export { applyCommandsAndConvertToHastHandle, applyCommandsToHandle, applyCommandsToMdastHandle, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createMdastHandle, createMdxHastHandle, createMdxMdastHandle, dropHandle, getHandleSource, getMdastFrontmatter, getNodeData, mdastTextContentHandle, parseEsm, parseExpression, parseToHtml, renderHandle, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../index.js";
+export { applyCommandsAndCompileHandle, applyCommandsAndConvertToHastHandle, applyCommandsAndRenderHandle, applyCommandsToHandle, applyCommandsToMdastHandle, applyMdastCommandsAndConvertAndCompile, applyMdastCommandsAndConvertAndRender, compileHandle, compileMdx, convertMdastToHastHandle, createHastHandle, createHastHandleFromHtml, createHastHandleWithFrontmatter, createMdastHandle, createMdxHastHandle, createMdxHastHandleWithFrontmatter, createMdxMdastHandle, dropHandle, getHandleSource, getMdastFrontmatter, getNodeData, markdownToHtmlFast, markdownToJsFast, mdastTextContentHandle, mdxToJsFast, parseEsm, parseExpression, parseToHtml, renderHandle, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../index.js";

package/dist/byte-writer.d.ts

@@ -16,6 +16,7 @@ export declare class ByteWriter {
     constructor(initialSize: number);
     /** Number of bytes written so far. */
     get length(): number;
+    get capacity(): number;
     /** Reset for reuse; the grown buffer is retained so steady state is alloc-free. */
     reset(): void;
     /** View of the bytes written so far (no copy; valid until the next write or reset). */
@@ -28,4 +29,7 @@ export declare class ByteWriter {
     protected writeU32(v: number): void;
     /** u32 byte length + UTF-8 bytes (self-ensuring). */
     protected utf8WithU32Len(s: string): void;
+    /** Backpatch a u32 (LE) at `pos` in the already-written region; the cursor
+     *  is left untouched. */
+    protected patchU32(pos: number, v: number): void;
 }

package/dist/byte-writer.js

@@ -29,6 +29,9 @@ export class ByteWriter {
     get length() {
         return this.n;
     }
+    get capacity() {
+        return this.buf.length;
+    }
     /** Reset for reuse; the grown buffer is retained so steady state is alloc-free. */
     reset() {
         this.n = 0;
@@ -97,10 +100,16 @@ export class ByteWriter {
         const lenPos = this.n;
         this.n += 4;
         const written = encoder.encodeInto(s, this.buf.subarray(this.n)).written;
-        this.buf[lenPos] = written & 255;
-        this.buf[lenPos + 1] = (written >> 8) & 255;
-        this.buf[lenPos + 2] = (written >> 16) & 255;
-        this.buf[lenPos + 3] = (written >>> 24) & 255;
+        this.patchU32(lenPos, written);
         this.n += written;
     }
+    /** Backpatch a u32 (LE) at `pos` in the already-written region; the cursor
+     *  is left untouched. */
+    patchU32(pos, v) {
+        const buf = this.buf;
+        buf[pos] = v & 255;
+        buf[pos + 1] = (v >> 8) & 255;
+        buf[pos + 2] = (v >> 16) & 255;
+        buf[pos + 3] = (v >>> 24) & 255;
+    }
 }

package/dist/child-stub.d.ts

@@ -5,13 +5,17 @@
  * Passthrough children (the common replaceNode shape) thus compile to one-word
  * refs without ever serializing the arena.
  */
+export type StubDescriptorEntry = readonly [string, PropertyDescriptor];
 /**
- * Descriptor template for one node type's stub fields. Own enumerable getters
+ * Descriptor entries for one node type's stub fields. Own enumerable getters
  * so a spread copy carries correct values. `position`/`data` ride on every
  * stub; they may yield `undefined` where a materialized node omits the key —
- * accepted drift, invisible to `toEqual`.
+ * accepted drift, invisible to `toEqual`. Installed one `defineProperty` at a
+ * time: `Object.defineProperties` re-validates the whole map per call and
+ * costs nearly double.
  */
-export declare function stubDescriptors(fields: readonly string[]): PropertyDescriptorMap;
+export declare function stubDescriptors(fields: readonly string[]): readonly StubDescriptorEntry[];
+export declare function installStubDescriptors(host: object, entries: readonly StubDescriptorEntry[]): void;
 /** Node tags are dense small ints, so the per-child stub loop indexes flat
  *  arrays instead of paying Map/dictionary lookups. */
 export declare function flatByTag<T>(table: Readonly<Record<number, T>>): readonly (T | undefined)[];

package/dist/child-stub.js

@@ -20,11 +20,12 @@ function fieldGetter(key) {
                 REAL_NODES.set(this, real);
             }
             const value = real[key];
+            // Mirrors the deep-frozen node it forwards to; nothing redefines a stub field after this.
             Object.defineProperty(this, key, {
                 value,
-                writable: true,
+                writable: false,
                 enumerable: true,
-                configurable: true,
+                configurable: false,
             });
             return value;
         };
@@ -33,17 +34,27 @@ function fieldGetter(key) {
     return getter;
 }
 /**
- * Descriptor template for one node type's stub fields. Own enumerable getters
+ * Descriptor entries for one node type's stub fields. Own enumerable getters
  * so a spread copy carries correct values. `position`/`data` ride on every
  * stub; they may yield `undefined` where a materialized node omits the key —
- * accepted drift, invisible to `toEqual`.
+ * accepted drift, invisible to `toEqual`. Installed one `defineProperty` at a
+ * time: `Object.defineProperties` re-validates the whole map per call and
+ * costs nearly double.
  */
 export function stubDescriptors(fields) {
-    const map = {};
+    const entries = [];
     for (const key of [...fields, "position", "data"]) {
-        map[key] = { get: fieldGetter(key), enumerable: true, configurable: true };
+        entries.push([key, { get: fieldGetter(key), enumerable: true, configurable: true }]);
+    }
+    return entries;
+}
+export function installStubDescriptors(host, entries) {
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        if (e === undefined)
+            continue;
+        Object.defineProperty(host, e[0], e[1]);
     }
-    return map;
 }
 /** Node tags are dense small ints, so the per-child stub loop indexes flat
  *  arrays instead of paying Map/dictionary lookups. */

package/dist/command-buffer.d.ts

@@ -10,65 +10,51 @@
  * All multi-byte integers are little-endian to match native x86/ARM layout and
  * avoid byte-swapping on the Rust side.
  */
-import { ByteWriter } from "./byte-writer.js";
+import { OpWriter } from "./op-stream.js";
 import type { MdastNode } from "./types.js";
 type ReturnClass = "no_change" | "raw_markdown" | "raw_html" | "structured_node";
+/** Input to the structural mutators (`replace`, `insertBefore`, …). */
+type StructuralContent = MdastNode | {
+    raw: string;
+    mdxExpressions?: boolean;
+} | {
+    rawHtml: string;
+};
 export declare function classifyReturn(value: unknown): ReturnClass;
-/** Structural commands that carry a subtree payload. Each has an `${op}Opstream`
- *  twin (declarative content) and a raw twin (`{raw}`/`{rawHtml}` escape hatch). */
+/** Backings above this are dropped on release so one huge compile does not retain megabytes forever. */
+export declare const COMMAND_BUFFER_RETAIN_MAX: number;
+export declare function acquireCommandBuffer(): CommandBuffer;
+export declare function releaseCommandBuffer(buf: CommandBuffer): void;
+/** Structural commands that carry a subtree payload emitted in place via `emitOpstreamCommand`. */
 export type StructuralOp = "replace" | "insertBefore" | "insertAfter" | "prependChild" | "appendChild" | "wrapNode";
-export declare class CommandBuffer extends ByteWriter {
+export declare const STRUCTURAL_CMD: Record<StructuralOp, number>;
+export declare class CommandBuffer extends OpWriter {
+    #private;
     constructor();
+    reset(): void;
+    /** Emit a structural command whose opstream payload is written by `emit`
+     *  via the inherited op methods. If `emit` returns false or throws, the
+     *  buffer is rolled back to the command start so the Rust decoder never
+     *  sees a half-written command. Returns `emit`'s verdict. */
+    emitOpstreamCommand(cmd: number, nodeId: number, emit: () => boolean): boolean;
     removeNode(nodeId: number): void;
-    /** Unified set-property for both MDAST and HAST nodes. */
+    /** Unified set-property for both MDAST and HAST nodes.
+     *
+     *  Hot path: uses `encodeInto` to write UTF-8 straight into the buffer (no
+     *  per-call `Uint8Array`), reserving the worst-case length up front and
+     *  backfilling the length prefix once the byte count is known. */
     setProperty(nodeId: number, key: string, value: unknown): void;
-    insertBefore(nodeId: number, newNode: MdastNode | {
-        raw: string;
-    } | {
-        rawHtml: string;
-    }): void;
-    insertAfter(nodeId: number, newNode: MdastNode | {
-        raw: string;
-    } | {
-        rawHtml: string;
-    }): void;
-    prependChild(nodeId: number, newNode: MdastNode | {
-        raw: string;
-    } | {
-        rawHtml: string;
-    }): void;
-    appendChild(nodeId: number, newNode: MdastNode | {
-        raw: string;
-    } | {
-        rawHtml: string;
-    }): void;
-    wrapNode(nodeId: number, parentNode: MdastNode | {
-        raw: string;
-    } | {
-        rawHtml: string;
-    }): void;
-    replace(nodeId: number, newNode: MdastNode | {
-        raw: string;
-    } | {
-        rawHtml: string;
-    }): void;
-    /** Header (cmd + nodeId + payloadType) followed by a length-prefixed string payload. */
-    private writePayloadCommand;
-    replaceOpstream(nodeId: number, ops: Uint8Array): void;
-    /** Replace a node's child list (root-wrapped `ops`) while keeping the node. */
-    setChildrenOpstream(nodeId: number, ops: Uint8Array): void;
-    insertBeforeOpstream(nodeId: number, ops: Uint8Array): void;
-    insertAfterOpstream(nodeId: number, ops: Uint8Array): void;
-    prependChildOpstream(nodeId: number, ops: Uint8Array): void;
-    appendChildOpstream(nodeId: number, ops: Uint8Array): void;
-    wrapNodeOpstream(nodeId: number, ops: Uint8Array): void;
-    private writeOpstreamCommand;
+    insertBefore(nodeId: number, newNode: StructuralContent): void;
+    insertAfter(nodeId: number, newNode: StructuralContent): void;
+    prependChild(nodeId: number, newNode: StructuralContent): void;
+    appendChild(nodeId: number, newNode: StructuralContent): void;
+    wrapNode(nodeId: number, parentNode: StructuralContent): void;
+    replace(nodeId: number, newNode: StructuralContent): void;
+    /** Header (cmd + nodeId + PAYLOAD_RAW + flags) followed by a length-prefixed string. */
+    private writeRawCommand;
     /** Return a Uint8Array view of the written bytes (no copy). */
     getBuffer(): Uint8Array;
-    /** Reset for reuse, releasing the old buffer (handed-out views stay intact). */
-    reset(): void;
-    /** Raw structural content (`{raw}`/`{rawHtml}` escape hatches). Declarative
-     *  nodes go through the `*Opstream` methods, not here. */
+    /** Encode the raw-string escape hatch; declarative nodes use `*Opstream` instead. */
     private writeStructuralCommand;
 }
 export {};

package/dist/command-buffer.js

@@ -10,9 +10,9 @@
  * All multi-byte integers are little-endian to match native x86/ARM layout and
  * avoid byte-swapping on the Rust side.
  */
-import { ByteWriter } from "./byte-writer.js";
+import { OpWriter } from "./op-stream.js";
 import { PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_INT, PROP_NULL, } from "./op-stream.js";
-import { CMD_REMOVE, CMD_INSERT_BEFORE, CMD_INSERT_AFTER, CMD_PREPEND_CHILD, CMD_APPEND_CHILD, CMD_WRAP, CMD_REPLACE, CMD_SET_PROPERTY, CMD_SET_CHILDREN, PAYLOAD_RAW_MARKDOWN, PAYLOAD_RAW_HTML, PAYLOAD_OPSTREAM, } from "./generated/wire-constants.js";
+import { CMD_REMOVE, CMD_INSERT_BEFORE, CMD_INSERT_AFTER, CMD_PREPEND_CHILD, CMD_APPEND_CHILD, CMD_WRAP, CMD_REPLACE, CMD_SET_PROPERTY, CMD_SET_CHILDREN, PAYLOAD_RAW, RAW_LITERAL_BRACES, PAYLOAD_OPSTREAM, } from "./generated/wire-constants.js";
 export function classifyReturn(value) {
     if (value === undefined || value === null)
         return "no_change";
@@ -26,17 +26,105 @@ export function classifyReturn(value) {
     throw new Error("Invalid return value from visitor: must have raw, rawHtml, or type");
 }
 const INITIAL_SIZE = 4096;
-export class CommandBuffer extends ByteWriter {
+/** Free list recycling `CommandBuffer` instances (and their grown backings)
+ *  across plugin passes. Safe to retain the backing because `mergeAndReset`
+ *  copies the bytes out before a buffer is released, so no view outlives a
+ *  pass. Cap bounds the pool for processes that briefly burst high. */
+const COMMAND_BUFFER_POOL_MAX = 8;
+/** Backings above this are dropped on release so one huge compile does not retain megabytes forever. */
+export const COMMAND_BUFFER_RETAIN_MAX = 1 << 20;
+const commandBufferPool = [];
+export function acquireCommandBuffer() {
+    return commandBufferPool.pop() ?? new CommandBuffer();
+}
+export function releaseCommandBuffer(buf) {
+    if (commandBufferPool.length >= COMMAND_BUFFER_POOL_MAX)
+        return;
+    if (buf.capacity > COMMAND_BUFFER_RETAIN_MAX)
+        return;
+    buf.reset();
+    commandBufferPool.push(buf);
+}
+export const STRUCTURAL_CMD = {
+    replace: CMD_REPLACE,
+    insertBefore: CMD_INSERT_BEFORE,
+    insertAfter: CMD_INSERT_AFTER,
+    prependChild: CMD_PREPEND_CHILD,
+    appendChild: CMD_APPEND_CHILD,
+    wrapNode: CMD_WRAP,
+};
+export class CommandBuffer extends OpWriter {
+    /** Set while a structural payload is being emitted in place; command
+     *  methods must not interleave bytes into it. */
+    #inOpstream = false;
     constructor() {
         super(INITIAL_SIZE);
     }
+    reset() {
+        this.#inOpstream = false;
+        super.reset();
+    }
+    #assertNotEncoding() {
+        if (this.#inOpstream) {
+            throw new Error("reentrant command emission: a node getter or toJSON invoked a context mutation while a structural payload was being encoded");
+        }
+    }
+    /** Emit a structural command whose opstream payload is written by `emit`
+     *  via the inherited op methods. If `emit` returns false or throws, the
+     *  buffer is rolled back to the command start so the Rust decoder never
+     *  sees a half-written command. Returns `emit`'s verdict. */
+    emitOpstreamCommand(cmd, nodeId, emit) {
+        const commandStart = this.n;
+        const lenPos = this.#beginOpstream(cmd, nodeId);
+        // ok starts false so a throwing emit still hits the abort in finally
+        let ok = false;
+        try {
+            ok = emit();
+        }
+        finally {
+            if (!ok)
+                this.#abortOpstream(commandStart);
+        }
+        if (ok)
+            this.#endOpstream(lenPos);
+        return ok;
+    }
+    /** Open a structural command whose opstream payload is emitted in place via
+     *  the inherited op methods; returns the backpatch position for
+     *  `#endOpstream`. Pair with `#abortOpstream` on failure. */
+    #beginOpstream(cmd, nodeId) {
+        this.#assertNotEncoding();
+        this.#inOpstream = true;
+        this.ensure(10);
+        this.buf[this.n++] = cmd;
+        this.writeU32(nodeId);
+        this.buf[this.n++] = PAYLOAD_OPSTREAM;
+        const lenPos = this.n;
+        this.n += 4;
+        return lenPos;
+    }
+    #endOpstream(lenPos) {
+        this.#inOpstream = false;
+        this.patchU32(lenPos, this.n - (lenPos + 4));
+    }
+    /** Roll back an in-progress opstream command (unencodable content). */
+    #abortOpstream(commandStart) {
+        this.#inOpstream = false;
+        this.n = commandStart;
+    }
     removeNode(nodeId) {
+        this.#assertNotEncoding();
         this.ensure(5);
         this.buf[this.n++] = CMD_REMOVE;
         this.writeU32(nodeId);
     }
-    /** Unified set-property for both MDAST and HAST nodes. */
+    /** Unified set-property for both MDAST and HAST nodes.
+     *
+     *  Hot path: uses `encodeInto` to write UTF-8 straight into the buffer (no
+     *  per-call `Uint8Array`), reserving the worst-case length up front and
+     *  backfilling the length prefix once the byte count is known. */
     setProperty(nodeId, key, value) {
+        this.#assertNotEncoding();
         let valueType;
         let str;
         if (value === null || value === undefined) {
@@ -89,64 +177,29 @@ export class CommandBuffer extends ByteWriter {
     replace(nodeId, newNode) {
         this.writeStructuralCommand(CMD_REPLACE, nodeId, newNode);
     }
-    /** Header (cmd + nodeId + payloadType) followed by a length-prefixed string payload. */
-    writePayloadCommand(cmd, nodeId, payloadType, s) {
-        this.ensure(6);
+    /** Header (cmd + nodeId + PAYLOAD_RAW + flags) followed by a length-prefixed string. */
+    writeRawCommand(cmd, nodeId, flags, s) {
+        this.#assertNotEncoding();
+        this.ensure(7);
         this.buf[this.n++] = cmd;
         this.writeU32(nodeId);
-        this.buf[this.n++] = payloadType;
+        this.buf[this.n++] = PAYLOAD_RAW;
+        this.buf[this.n++] = flags;
         this.utf8WithU32Len(s);
     }
-    replaceOpstream(nodeId, ops) {
-        this.writeOpstreamCommand(CMD_REPLACE, nodeId, ops);
-    }
-    /** Replace a node's child list (root-wrapped `ops`) while keeping the node. */
-    setChildrenOpstream(nodeId, ops) {
-        this.writeOpstreamCommand(CMD_SET_CHILDREN, nodeId, ops);
-    }
-    insertBeforeOpstream(nodeId, ops) {
-        this.writeOpstreamCommand(CMD_INSERT_BEFORE, nodeId, ops);
-    }
-    insertAfterOpstream(nodeId, ops) {
-        this.writeOpstreamCommand(CMD_INSERT_AFTER, nodeId, ops);
-    }
-    prependChildOpstream(nodeId, ops) {
-        this.writeOpstreamCommand(CMD_PREPEND_CHILD, nodeId, ops);
-    }
-    appendChildOpstream(nodeId, ops) {
-        this.writeOpstreamCommand(CMD_APPEND_CHILD, nodeId, ops);
-    }
-    wrapNodeOpstream(nodeId, ops) {
-        this.writeOpstreamCommand(CMD_WRAP, nodeId, ops);
-    }
-    writeOpstreamCommand(cmd, nodeId, ops) {
-        this.ensure(10 + ops.length);
-        this.buf[this.n++] = cmd;
-        this.writeU32(nodeId);
-        this.buf[this.n++] = PAYLOAD_OPSTREAM;
-        this.writeU32(ops.length);
-        this.buf.set(ops, this.n);
-        this.n += ops.length;
-    }
     /** Return a Uint8Array view of the written bytes (no copy). */
     getBuffer() {
         return this.take();
     }
-    /** Reset for reuse, releasing the old buffer (handed-out views stay intact). */
-    reset() {
-        if (this.n === 0)
-            return;
-        this.release();
-    }
-    /** Raw structural content (`{raw}`/`{rawHtml}` escape hatches). Declarative
-     *  nodes go through the `*Opstream` methods, not here. */
+    /** Encode the raw-string escape hatch; declarative nodes use `*Opstream` instead. */
     writeStructuralCommand(cmd, nodeId, node) {
         const v = node;
         if (typeof v.raw === "string") {
-            this.writePayloadCommand(cmd, nodeId, PAYLOAD_RAW_MARKDOWN, v.raw);
+            const flags = v.mdxExpressions === false ? RAW_LITERAL_BRACES : 0;
+            this.writeRawCommand(cmd, nodeId, flags, v.raw);
         }
         else if (typeof v.rawHtml === "string") {
-            this.writePayloadCommand(cmd, nodeId, PAYLOAD_RAW_HTML, v.rawHtml);
+            this.writeRawCommand(cmd, nodeId, RAW_LITERAL_BRACES, v.rawHtml);
         }
         else {
             throw new Error("CommandBuffer: structural content must be {raw} or {rawHtml}");

package/dist/compile.d.ts

@@ -1,4 +1,4 @@
-import type { MdastPluginInput, HastPluginInput } from "./plugin.js";
+import type { MdastPluginList, HastPluginList } from "./plugin.js";
 import type { MdastNode, HastNode, Data } from "./types.js";
 /** Configuration for static subtree collapsing during MDX compilation. */
 export interface OptimizeStaticConfig {
@@ -110,6 +110,8 @@ export interface Features {
     subscript?: boolean;
     /** Obsidian-style wikilinks (`[[link]]`). Default: false. */
     wikilinks?: boolean;
+    /** Definition lists (a term line then a `: definition`). Default: false. */
+    definitionList?: boolean;
     /**
      * Smart punctuation à la SmartyPants. Default: false.
      *
@@ -119,10 +121,24 @@ export interface Features {
      * ```
      */
     smartPunctuation?: boolean | SmartPunctuationOptions;
+    /**
+     * Parse raw HTML embedded in Markdown into real HAST element nodes.
+     * Default: false.
+     *
+     * By default, inline and block HTML is kept as opaque `raw` nodes
+     * (re-emitted verbatim on stringify). With `rawHtml: true`, the tree is
+     * reparsed so raw HTML becomes structured `element`/`text`/`comment` nodes
+     * with normalized properties, including tags that open in one raw block
+     * and close in another. Positions are not preserved through the reparse.
+     */
+    rawHtml?: boolean;
 }
 export interface CompileOptions {
-    mdastPlugins?: MdastPluginInput[];
-    hastPlugins?: HastPluginInput[];
+    /** MDAST plugins, in run order. A nested array runs its own plugins, in
+     *  their own order, at the array's position. */
+    mdastPlugins?: MdastPluginList;
+    /** HAST plugins, in run order. Nests like `mdastPlugins`. */
+    hastPlugins?: HastPluginList;
     features?: Features;
     /**
      * The document being processed, surfaced to plugins as `ctx.fileURL`. Must
@@ -140,12 +156,9 @@ export interface CompileOptions {
     data?: Data;
 }
 /**
- * MDX-only compile options.
- *
- * These are the fields specific to MDX compilation, separate from the shared
- * pipeline options in {@link CompileOptions}. Useful for wrappers (Vite/Rollup
- * plugins, framework integrations) that want to expose MDX-specific knobs
- * without re-exposing the shared pipeline fields.
+ * JS/JSX output options, accepted by both {@link mdxToJs} and
+ * {@link markdownToJs}. Exported on its own so wrappers can expose the codegen
+ * knobs without the shared pipeline fields.
  */
 export interface MdxOnlyOptions {
     optimizeStatic?: OptimizeStaticConfig;
@@ -195,6 +208,8 @@ export interface MdxOnlyOptions {
 }
 export interface MdxCompileOptions extends CompileOptions, MdxOnlyOptions {
 }
+export interface MarkdownToJsOptions extends CompileOptions, MdxOnlyOptions {
+}
 /** Frontmatter block extracted from the parsed Markdown/MDX source. */
 export interface Frontmatter {
     /** Delimiter syntax used for the block. */
@@ -220,27 +235,50 @@ export interface MdxToJsResult {
     /** Document-level data bag shared with plugins via `ctx.data`; the seeded `data` option if provided, else a fresh `{}`. */
     data: Data;
 }
+/** Result of {@link markdownToJs}. */
+export interface MarkdownToJsResult {
+    /** Compiled JavaScript module source. */
+    code: string;
+    /** Frontmatter block at the start of the document, or `null` if none. */
+    frontmatter: Frontmatter | null;
+    /** Document-level data bag shared with plugins via `ctx.data`; the seeded `data` option if provided, else a fresh `{}`. */
+    data: Data;
+}
+type CombineAsync<A> = "async" extends A ? "async" : "maybe" extends A ? "maybe" : "sync";
 type AnyFn = (...args: any[]) => unknown;
-type ReturnsPromise<F> = F extends AnyFn ? Extract<ReturnType<F>, Promise<unknown>> extends never ? false : true : false;
+type ReturnsPromise<F> = F extends AnyFn ? [Extract<ReturnType<F>, Promise<unknown>>] extends [never] ? "sync" : [Exclude<ReturnType<F>, Promise<unknown>>] extends [never] ? "async" : "maybe" : "sync";
 type FieldIsAsync<V> = V extends AnyFn ? ReturnsPromise<V> : V extends {
     visit: infer F;
 } ? ReturnsPromise<F> : V extends ReadonlyArray<infer Item> ? Item extends {
     visit: infer F;
-} ? ReturnsPromise<F> : false : false;
+} ? ReturnsPromise<F> : "sync" : "sync";
 type AnyVisitorAsync<P> = {
     [K in keyof P]-?: FieldIsAsync<NonNullable<P[K]>>;
 }[keyof P];
-type IsPluginAsync<P> = true extends AnyVisitorAsync<P> ? true : false;
-type ResolveInput<P> = P extends () => infer D ? D : P;
-type AnyInputAsync<Ps> = Ps extends ReadonlyArray<infer P> ? true extends IsPluginAsync<ResolveInput<P>> ? true : false : false;
-type OptionsAsync<O> = (O extends {
-    mdastPlugins: infer Ps;
-} ? AnyInputAsync<Ps> : false) extends true ? true : (O extends {
-    hastPlugins: infer Ps;
-} ? AnyInputAsync<Ps> : false) extends true ? true : false;
-type ResultFor<O, R> = OptionsAsync<O> extends true ? Promise<R> : R;
+type IsPluginAsync<P> = P extends unknown ? CombineAsync<AnyVisitorAsync<P>> : never;
+type ResolveInput<P, D extends readonly unknown[] = [0, 0, 0, 0, 0, 0, 0, 0]> = D extends readonly [
+    unknown,
+    ...infer Rest
+] ? P extends ReadonlyArray<infer Item> ? ResolveInput<Item, Rest> : P extends (...args: never[]) => infer Def ? ResolveInput<Def, Rest> : P : never;
+type AnyInputAsync<Ps> = Ps extends ReadonlyArray<infer P> ? CombineAsync<IsPluginAsync<ResolveInput<P>>> : "sync";
+type OptionsAsync<O extends CompileOptions> = CombineAsync<AnyInputAsync<NonNullable<O["mdastPlugins"]>> | AnyInputAsync<NonNullable<O["hastPlugins"]>>>;
+type ResultFor<O extends CompileOptions, R> = {
+    sync: R;
+    async: Promise<R>;
+    maybe: R | Promise<R>;
+}[OptionsAsync<O>];
+export declare function markdownToHtml(source: string): MarkdownToHtmlResult;
 export declare function markdownToHtml<O extends CompileOptions>(source: string, options?: O): ResultFor<O, MarkdownToHtmlResult>;
+export declare function mdxToJs(source: string): MdxToJsResult;
 export declare function mdxToJs<O extends MdxCompileOptions>(source: string, options?: O): ResultFor<O, MdxToJsResult>;
+/**
+ * Compile plain Markdown to a JavaScript module: like {@link mdxToJs}, but
+ * without MDX syntax: `{...}` expressions, JSX tags, and `import`/`export`
+ * lines are ordinary Markdown. HTML has no JSX representation and is dropped;
+ * enable `features: { rawHtml: true }` to parse it into real elements instead.
+ */
+export declare function markdownToJs(source: string): MarkdownToJsResult;
+export declare function markdownToJs<O extends MarkdownToJsOptions>(source: string, options?: O): ResultFor<O, MarkdownToJsResult>;
 export interface EvaluateOptions extends Omit<MdxCompileOptions, "jsx" | "outputFormat"> {
     Fragment: unknown;
     jsx: (type: unknown, props: unknown, key?: unknown) => unknown;
@@ -260,20 +298,30 @@ export interface EvaluateOptions extends Omit<MdxCompileOptions, "jsx" | "output
  * ```
  */
 export declare function evaluate(source: string, options: EvaluateOptions): Record<string, unknown> | Promise<Record<string, unknown>>;
-/** Parse Markdown source into a materialized mdast tree. */
-export declare function markdownToMdast(source: string, options?: {
+/** Options for the step-by-step tree functions. */
+export interface TreeOptions {
     features?: Features;
-}): MdastNode;
+    /**
+     * Record `position` on every node. Default: `true`.
+     *
+     * A unist position is three objects per node and roughly half a materialized
+     * tree's memory, on top of the parser's line-index build. Pass `false` when
+     * nothing downstream reads `node.position`.
+     */
+    position?: boolean;
+}
+/** Parse Markdown source into a materialized mdast tree. */
+export declare function markdownToMdast(source: string, options?: TreeOptions): MdastNode;
 /** Parse MDX source into a materialized mdast tree. */
-export declare function mdxToMdast(source: string, options?: {
-    features?: Features;
-}): MdastNode;
+export declare function mdxToMdast(source: string, options?: TreeOptions): MdastNode;
 /** Convert Markdown source to a materialized hast tree. */
-export declare function markdownToHast(source: string, options?: {
-    features?: Features;
-}): HastNode;
+export declare function markdownToHast(source: string, options?: TreeOptions): HastNode;
 /** Convert MDX source to a materialized hast tree. */
-export declare function mdxToHast(source: string, options?: {
-    features?: Features;
-}): HastNode;
+export declare function mdxToHast(source: string, options?: TreeOptions): HastNode;
+/**
+ * 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 declare function htmlToHast(html: string): HastNode;
 export {};