satteri 0.10.5 → 0.11.1

package/README.md

@@ -41,6 +41,17 @@ import { markdownToJs } from "satteri";
 const { code } = markdownToJs("# Hello\n\n{not an expression}");
 ```
 
+### HAST to HTML
+
+`hastToHtml` serializes a HAST root, a single node, or an array of nodes without adding a trailing newline. Raw HTML nodes are emitted verbatim; MDX nodes are skipped.
+
+```ts
+import { hastToHtml, markdownToHast } from "satteri";
+
+const html = hastToHtml(markdownToHast("**Hello**"));
+// <p><strong>Hello</strong></p>
+```
+
 ### With plugins
 
 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.

package/dist/arena-reader.d.ts

@@ -0,0 +1,13 @@
+import type { ArenaWire, BufferHeader } from "./types.js";
+export declare class ArenaReader {
+    #private;
+    readonly u8: Uint8Array;
+    readonly u32: Uint32Array;
+    readonly header: BufferHeader;
+    constructor(buffer: ArrayBuffer | Uint8Array, kind: number);
+    getWire(): ArenaWire;
+    getNodeData(nodeId: number): string | null;
+    getNodeDataTable(): ReadonlyMap<number, string> | null;
+    getStringPool(): string;
+    getString(offset: number, len: number): string;
+}

package/dist/arena-reader.js

@@ -0,0 +1,104 @@
+import { ARENA_MAGIC, HEADER, KIND_MDAST } from "./generated/arena-layout.js";
+export class ArenaReader {
+    u8;
+    u32;
+    #view;
+    header;
+    #textDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
+    #stringPoolCache = null;
+    constructor(buffer, kind) {
+        let u8 = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);
+        // A foreign slice may not have the alignment required by a u32 view.
+        if ((u8.byteOffset & 3) !== 0)
+            u8 = u8.slice();
+        this.u8 = u8;
+        this.u32 = new Uint32Array(u8.buffer, u8.byteOffset, u8.byteLength >> 2);
+        this.#view = new DataView(u8.buffer, u8.byteOffset, u8.byteLength);
+        this.header = readHeader(this.#view, kind);
+    }
+    #nodeDataTable = null;
+    #wire = null;
+    // Memoize wire setup because the lazy materializer requests it for every node.
+    getWire() {
+        return (this.#wire ??= {
+            u8: this.u8,
+            u32: this.u32,
+            nodesB: this.header.nodesOffset,
+            nodesW: this.header.nodesOffset >> 2,
+            strideB: this.header.nodeStructSize,
+            strideW: this.header.nodeStructSize >> 2,
+            childrenW: this.header.childrenOffset >> 2,
+            typeDataB: this.header.typeDataOffset,
+            pool: this.getStringPool(),
+        });
+    }
+    // Index data blobs once to keep materialization O(nodes), rather than O(nodes × entries).
+    getNodeData(nodeId) {
+        const table = this.getNodeDataTable();
+        if (table === null)
+            return null;
+        return table.get(nodeId) ?? null;
+    }
+    getNodeDataTable() {
+        if (this.header.nodeDataCount === 0)
+            return null;
+        if (this.#nodeDataTable === null) {
+            this.#nodeDataTable = new Map();
+            const v = this.#view;
+            let pos = this.header.nodeDataOffset;
+            for (let i = 0; i < this.header.nodeDataCount; i++) {
+                const id = v.getUint32(pos, true);
+                pos += 4;
+                const len = v.getUint32(pos, true);
+                pos += 4;
+                const slice = this.u8.subarray(pos, pos + len);
+                this.#nodeDataTable.set(id, this.#textDecoder.decode(slice));
+                pos += len;
+            }
+        }
+        return this.#nodeDataTable;
+    }
+    // The pool includes interned strings; it is not the original document source.
+    getStringPool() {
+        return this.#stringPoolCache ?? this.#initPool();
+    }
+    #initPool() {
+        const { stringPoolOffset, stringPoolLen } = this.header;
+        const pool = this.#textDecoder.decode(this.u8.subarray(stringPoolOffset, stringPoolOffset + stringPoolLen));
+        this.#stringPoolCache = pool;
+        return pool;
+    }
+    // The serializer remaps string refs to UTF-16 offsets, matching substring indices.
+    getString(offset, len) {
+        if (len === 0)
+            return "";
+        const pool = this.#stringPoolCache ?? this.#initPool();
+        return pool.substring(offset, offset + len);
+    }
+}
+function readHeader(view, expectedKind) {
+    const magic = view.getUint32(HEADER.magic, true);
+    if (magic !== ARENA_MAGIC) {
+        throw new Error(expectedKind === KIND_MDAST
+            ? `Invalid buffer: bad magic 0x${magic.toString(16)}, expected 0x${ARENA_MAGIC.toString(16)}`
+            : `Invalid HAST buffer: bad magic 0x${magic.toString(16)}`);
+    }
+    const kind = view.getUint32(HEADER.kind, true);
+    if (kind !== expectedKind) {
+        throw new Error(`${expectedKind === KIND_MDAST ? "MdastReader" : "HastReader"} was handed a buffer of kind ${kind} (expected ${expectedKind}). ` +
+            `MDAST and HAST node types overlap; reading the wrong kind decodes garbage.`);
+    }
+    return {
+        nodeStructSize: view.getUint32(HEADER.node_struct_size, true),
+        nodeCount: view.getUint32(HEADER.node_count, true),
+        nodesOffset: view.getUint32(HEADER.nodes_offset, true),
+        childrenCount: view.getUint32(HEADER.children_count, true),
+        childrenOffset: view.getUint32(HEADER.children_offset, true),
+        typeDataLen: view.getUint32(HEADER.type_data_len, true),
+        typeDataOffset: view.getUint32(HEADER.type_data_offset, true),
+        stringPoolLen: view.getUint32(HEADER.string_pool_len, true),
+        stringPoolOffset: view.getUint32(HEADER.string_pool_offset, true),
+        nodeDataCount: view.getUint32(HEADER.node_data_count, true),
+        nodeDataOffset: view.getUint32(HEADER.node_data_offset, true),
+    };
+}

package/dist/binding.browser.d.ts

@@ -1 +1 @@
-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";
+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, renderHastOpstream, parseHastWire, parseMdastWire, 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 { 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";
+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, renderHastOpstream, parseHastWire, parseMdastWire, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../browser.js";

package/dist/binding.d.ts

@@ -1 +1 @@
-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";
+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, renderHastOpstream, parseHastWire, parseMdastWire, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../index.js";

package/dist/binding.js

@@ -1 +1 @@
-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";
+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, renderHastOpstream, parseHastWire, parseMdastWire, serializeHandle, setNodeData, textContentHandle, walkHandle, walkMdastHandle, } from "../index.js";

package/dist/byte-writer.d.ts

@@ -1,35 +1,17 @@
-/**
- * Growable little-endian byte buffer shared by the op-stream and command-buffer
- * encoders — the two hottest write paths in the package.
- *
- * Subclasses write single bytes directly through the protected `buf`/`n`
- * fields after an `ensure` for the whole record (one bounds check per record,
- * not per byte, and no per-byte call in unoptimized tiers — CodSpeed's
- * Simulation mode runs too few iterations for V8 to inline method calls).
- * Only the non-trivial logic lives here: growth, u32 writes, and UTF-8
- * string encoding.
- */
 export declare class ByteWriter {
     #private;
     protected buf: Uint8Array;
     protected n: number;
     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). */
     take(): Uint8Array;
-    /** Release the backing (handed-out views stay intact); next write re-allocates. */
     protected release(): void;
-    /** Grow (doubling) so `extra` more bytes fit; required before unchecked writes. */
     ensure(extra: number): void;
     /** Write a u32 (LE) at the cursor; caller must have `ensure`d 4 bytes. */
     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

@@ -1,38 +1,23 @@
-/**
- * Growable little-endian byte buffer shared by the op-stream and command-buffer
- * encoders — the two hottest write paths in the package.
- *
- * Subclasses write single bytes directly through the protected `buf`/`n`
- * fields after an `ensure` for the whole record (one bounds check per record,
- * not per byte, and no per-byte call in unoptimized tiers — CodSpeed's
- * Simulation mode runs too few iterations for V8 to inline method calls).
- * Only the non-trivial logic lives here: growth, u32 writes, and UTF-8
- * string encoding.
- */
+// Write bytes inline after reserving each record to avoid per-byte calls and bounds checks.
 const encoder = new TextEncoder();
 const EMPTY = new Uint8Array(0);
-/** Below this length the inline char-code copy beats `encodeInto`'s call
- *  overhead; above it the native bulk path wins (and skips the ASCII scan).
- *  Measured crossover ~16 bytes (Node 24: 8B 15 vs 41 ns, 16B 37 vs 43,
- *  32B 73 vs 52). */
+// Below 16 bytes, inline ASCII writes beat encodeInto call overhead.
 const INLINE_STR_MAX = 16;
 export class ByteWriter {
-    // Backing allocates on first write: visitor passes construct buffers that
-    // often never receive a byte (read-only plugins).
+    // Read-only plugin passes should allocate no backing buffer.
     buf = EMPTY;
     n = 0;
     #initialSize;
     constructor(initialSize) {
         this.#initialSize = initialSize;
     }
-    /** Number of bytes written so far. */
     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. */
+    // Retain capacity so repeated plugin passes can reuse the buffer without allocating.
     reset() {
         this.n = 0;
     }
@@ -40,12 +25,11 @@ export class ByteWriter {
     take() {
         return this.n === 0 ? EMPTY : this.buf.subarray(0, this.n);
     }
-    /** Release the backing (handed-out views stay intact); next write re-allocates. */
     release() {
         this.buf = EMPTY;
         this.n = 0;
     }
-    /** Grow (doubling) so `extra` more bytes fit; required before unchecked writes. */
+    // Reserve capacity before unchecked writes.
     ensure(extra) {
         if (this.n + extra <= this.buf.length)
             return;
@@ -66,12 +50,9 @@ export class ByteWriter {
         buf[n++] = (v >>> 24) & 255;
         this.n = n;
     }
-    /** u32 byte length + UTF-8 bytes (self-ensuring). */
     utf8WithU32Len(s) {
         const len = s.length;
         this.ensure(4 + len * 3); // worst-case UTF-8 is 3 bytes per UTF-16 unit
-        // Short strings: inline char copy (cheaper than a native call), guarded by a
-        // quick ASCII scan. Anything longer — or non-ASCII — goes to encodeInto.
         if (len <= INLINE_STR_MAX) {
             let ascii = true;
             for (let i = 0; i < len; i++) {
@@ -81,8 +62,7 @@ export class ByteWriter {
                 }
             }
             if (ascii) {
-                // Inline stores, not writeU32: a per-string method call in the
-                // unoptimized tier is exactly what this class's header rules out.
+                // Inline stores avoid per-string method calls before V8 has optimized this path.
                 const buf = this.buf;
                 let n = this.n;
                 buf[n++] = len & 255;
@@ -95,16 +75,12 @@ export class ByteWriter {
                 return;
             }
         }
-        // Bulk path: encodeInto writes UTF-8 straight into the buffer (no alloc, no
-        // per-char loop); backpatch the byte length once it's known.
         const lenPos = this.n;
         this.n += 4;
         const written = encoder.encodeInto(s, this.buf.subarray(this.n)).written;
         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;

package/dist/child-stub.d.ts

@@ -1,21 +1,4 @@
-/**
- * Shared machinery for walk-path child stubs (see `hast/child-stub.ts` and
- * `mdast/child-stub.ts`): lightweight stand-ins that carry arena id + type
- * eagerly and defer the full-arena snapshot until a plugin reads a real field.
- * Passthrough children (the common replaceNode shape) thus compile to one-word
- * refs without ever serializing the arena.
- */
 export type StubDescriptorEntry = readonly [string, PropertyDescriptor];
-/**
- * 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`. 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[]): 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

@@ -1,14 +1,6 @@
-/**
- * Shared machinery for walk-path child stubs (see `hast/child-stub.ts` and
- * `mdast/child-stub.ts`): lightweight stand-ins that carry arena id + type
- * eagerly and defer the full-arena snapshot until a plugin reads a real field.
- * Passthrough children (the common replaceNode shape) thus compile to one-word
- * refs without ever serializing the arena.
- */
-/** Stub → materialized arena node, filled on the first real-field read. */
+// Child stubs let unchanged children pass through as arena references without serializing the tree.
 const REAL_NODES = new WeakMap();
-/** One shared memoizing getter per field name, so stubs install shared
- *  descriptor templates instead of allocating per-field closures per node. */
+// Share getters across stubs to avoid allocating a closure for every field of every node.
 const FIELD_GETTERS = new Map();
 function fieldGetter(key) {
     let getter = FIELD_GETTERS.get(key);
@@ -16,11 +8,11 @@ function fieldGetter(key) {
         getter = function () {
             let real = REAL_NODES.get(this);
             if (real === undefined) {
-                real = this._resolver.materializeOne(this._id);
+                real = this._materialize();
                 REAL_NODES.set(this, real);
             }
             const value = real[key];
-            // Mirrors the deep-frozen node it forwards to; nothing redefines a stub field after this.
+            // Stub fields must remain as immutable as the frozen nodes they expose.
             Object.defineProperty(this, key, {
                 value,
                 writable: false,
@@ -33,14 +25,7 @@ function fieldGetter(key) {
     }
     return getter;
 }
-/**
- * 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`. Installed one `defineProperty` at a
- * time: `Object.defineProperties` re-validates the whole map per call and
- * costs nearly double.
- */
+// Individual defineProperty calls avoid the descriptor-map validation cost of defineProperties.
 export function stubDescriptors(fields) {
     const entries = [];
     for (const key of [...fields, "position", "data"]) {
@@ -56,8 +41,7 @@ export function installStubDescriptors(host, entries) {
         Object.defineProperty(host, e[0], e[1]);
     }
 }
-/** Node tags are dense small ints, so the per-child stub loop indexes flat
- *  arrays instead of paying Map/dictionary lookups. */
+// Dense node tags allow array indexing on the per-child hot path.
 export function flatByTag(table) {
     const flat = [];
     for (const tag of Object.keys(table)) {

package/dist/command-buffer.d.ts

@@ -1,19 +1,6 @@
-/**
- * Binary command buffer for efficient JS→Rust mutation serialization.
- *
- * Simple mutations (remove, setProperty) are encoded as compact binary commands.
- * Structural mutations (insert, replace, …) carry one of two payload kinds:
- * compiled op-streams (`PAYLOAD_OPSTREAM`, replayed straight into the arena —
- * see op-stream.ts) for declarative content, or raw markdown/HTML strings
- * (re-parsed by Rust) for the `{raw}`/`{rawHtml}` escape hatches.
- *
- * All multi-byte integers are little-endian to match native x86/ARM layout and
- * avoid byte-swapping on the Rust side.
- */
 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;
@@ -25,36 +12,28 @@ export declare function classifyReturn(value: unknown): ReturnClass;
 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 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.
-     *
-     *  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;
+    setField(nodeId: number, key: string, value: unknown): void;
+    setAttribute(nodeId: number, name: string, value: unknown): void;
+    /** Set a HAST element's list property from `encodeTokenList` bytes, whose
+     *  separator the renderer picks from the element's schema. */
+    setTokenListProperty(nodeId: number, key: string, tokens: string): void;
     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;
-    /** Encode the raw-string escape hatch; declarative nodes use `*Opstream` instead. */
     private writeStructuralCommand;
 }
 export {};

package/dist/command-buffer.js

@@ -1,18 +1,7 @@
-/**
- * Binary command buffer for efficient JS→Rust mutation serialization.
- *
- * Simple mutations (remove, setProperty) are encoded as compact binary commands.
- * Structural mutations (insert, replace, …) carry one of two payload kinds:
- * compiled op-streams (`PAYLOAD_OPSTREAM`, replayed straight into the arena —
- * see op-stream.ts) for declarative content, or raw markdown/HTML strings
- * (re-parsed by Rust) for the `{raw}`/`{rawHtml}` escape hatches.
- *
- * All multi-byte integers are little-endian to match native x86/ARM layout and
- * avoid byte-swapping on the Rust side.
- */
+// Little-endian fields match the Rust wire protocol without byte swapping on x86/ARM.
 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, RAW_LITERAL_BRACES, PAYLOAD_OPSTREAM, } from "./generated/wire-constants.js";
+import { PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_INT, PROP_NULL, PROP_TOKEN_LIST, } 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_FIELD, CMD_SET_ATTRIBUTE, 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,10 +15,7 @@ export function classifyReturn(value) {
     throw new Error("Invalid return value from visitor: must have raw, rawHtml, or type");
 }
 const INITIAL_SIZE = 4096;
-/** 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. */
+// collectCommands copies bytes before release, so pooled buffers cannot invalidate returned commands.
 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;
@@ -54,8 +40,7 @@ export const STRUCTURAL_CMD = {
     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. */
+    // Commands must not interleave bytes while a structural payload is being emitted.
     #inOpstream = false;
     constructor() {
         super(INITIAL_SIZE);
@@ -69,14 +54,10 @@ export class CommandBuffer extends OpWriter {
             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. */
+    // Roll back failed payloads so the Rust decoder never sees a partial command.
     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();
@@ -89,9 +70,6 @@ export class CommandBuffer extends OpWriter {
             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;
@@ -107,7 +85,6 @@ export class CommandBuffer extends OpWriter {
         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;
@@ -118,12 +95,16 @@ export class CommandBuffer extends OpWriter {
         this.buf[this.n++] = CMD_REMOVE;
         this.writeU32(nodeId);
     }
-    /** 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.#writeNamedValue(CMD_SET_PROPERTY, nodeId, key, value);
+    }
+    setField(nodeId, key, value) {
+        this.#writeNamedValue(CMD_SET_FIELD, nodeId, key, value);
+    }
+    setAttribute(nodeId, name, value) {
+        this.#writeNamedValue(CMD_SET_ATTRIBUTE, nodeId, name, value);
+    }
+    #writeNamedValue(cmd, nodeId, key, value) {
         this.#assertNotEncoding();
         let valueType;
         let str;
@@ -151,14 +132,24 @@ export class CommandBuffer extends OpWriter {
             valueType = PROP_STRING;
             str = String(value);
         }
-        // 1(cmd) + 4(nodeId) + 1(valueType); name and value are length-prefixed strings
         this.ensure(6);
-        this.buf[this.n++] = CMD_SET_PROPERTY;
+        this.buf[this.n++] = cmd;
         this.writeU32(nodeId);
         this.buf[this.n++] = valueType;
         this.utf8WithU32Len(key);
         this.utf8WithU32Len(str);
     }
+    /** Set a HAST element's list property from `encodeTokenList` bytes, whose
+     *  separator the renderer picks from the element's schema. */
+    setTokenListProperty(nodeId, key, tokens) {
+        this.#assertNotEncoding();
+        this.ensure(6);
+        this.buf[this.n++] = CMD_SET_PROPERTY;
+        this.writeU32(nodeId);
+        this.buf[this.n++] = PROP_TOKEN_LIST;
+        this.utf8WithU32Len(key);
+        this.utf8WithU32Len(tokens);
+    }
     insertBefore(nodeId, newNode) {
         this.writeStructuralCommand(CMD_INSERT_BEFORE, nodeId, newNode);
     }
@@ -177,7 +168,6 @@ export class CommandBuffer extends OpWriter {
     replace(nodeId, newNode) {
         this.writeStructuralCommand(CMD_REPLACE, nodeId, newNode);
     }
-    /** Header (cmd + nodeId + PAYLOAD_RAW + flags) followed by a length-prefixed string. */
     writeRawCommand(cmd, nodeId, flags, s) {
         this.#assertNotEncoding();
         this.ensure(7);
@@ -187,11 +177,10 @@ export class CommandBuffer extends OpWriter {
         this.buf[this.n++] = flags;
         this.utf8WithU32Len(s);
     }
-    /** Return a Uint8Array view of the written bytes (no copy). */
+    // This view aliases the buffer and must be copied before it is released to the pool.
     getBuffer() {
         return this.take();
     }
-    /** Encode the raw-string escape hatch; declarative nodes use `*Opstream` instead. */
     writeStructuralCommand(cmd, nodeId, node) {
         const v = node;
         if (typeof v.raw === "string") {

package/dist/compile-options.d.ts

@@ -0,0 +1,11 @@
+import type { markdownToHtmlFast } from "#binding";
+import type { Features, MdxOnlyOptions } from "./compile-types.js";
+export declare const DEFAULT_PARSE_OPTIONS: number;
+export type NativeConvertOptions = NonNullable<Parameters<typeof markdownToHtmlFast>[2]>;
+type NativeCompileOptions = {
+    parseOptions: number;
+    convertOptions: NativeConvertOptions | undefined;
+};
+export declare function featuresToNative(features: Features | undefined): NativeCompileOptions;
+export declare function mdxOptionsToNative(opts: MdxOnlyOptions): MdxOnlyOptions | undefined;
+export {};