satteri 0.8.1 → 0.9.1

package/README.md

@@ -163,6 +163,57 @@ heading(node) {
 }
 ```
 
+### Sharing data between plugins
+
+Each context exposes a `data` object, a document-scoped grab bag shared across every visitor in the compile. Writes from one plugin are visible to later plugins, and the bag persists across the mdast→hast boundary, so hast plugins can read what mdast plugins wrote. After compilation the final state is returned on `result.data`, making it suitable for things like extracting a table of contents.
+
+```ts
+const collectHeadings = defineMdastPlugin({
+  name: "collect-headings",
+  heading(node, ctx) {
+    const list = (ctx.data.headings as string[]) ?? [];
+    const first = node.children[0];
+    if (first && "value" in first) list.push(first.value as string);
+    ctx.data.headings = list;
+  },
+});
+
+const { html, data } = markdownToHtml("# A\n\n# B", { mdastPlugins: [collectHeadings] });
+console.log(data?.headings); // ["A", "B"]
+```
+
+The bag lives entirely on the JS side, so any value is allowed, including functions, class instances, and `Map`/`Set`. References are preserved across plugins and across the mdast→hast boundary. A fresh, empty bag is created for every compile unless you seed one with the `data` option.
+
+To seed data into the bag before plugins run, pass an object to the `data` option. The same object is available in all plugins and returned as `result.data` after compilation, so you can pre-populate it with values or methods that plugins can read and update.
+
+```ts
+const data = { title: "Hello" };
+const rewriteTitle = defineMdastPlugin({
+  name: "rewrite-title",
+  heading(_node, ctx) {
+    ctx.data.title = "Updated";
+  },
+});
+
+const result = markdownToHtml("# A", { mdastPlugins: [rewriteTitle], data });
+console.log(result.data === data); // true, the seeded object is returned
+console.log(data.title); // "Updated"
+```
+
+By default keys are typed as `unknown`. To give a key a type, augment the `DataMap` interface:
+
+```ts
+declare module "satteri" {
+  interface DataMap {
+    headings: string[];
+  }
+}
+
+// now ctx.data.headings and result.data.headings are typed as string[] | undefined
+```
+
+Unregistered keys stay `unknown`, so the bag remains open-ended.
+
 ### How transforms compose
 
 Unlike remark and rehype, which re-walk the tree until it stops changing, each Sätteri plugin walks the tree **once**. Within that single pass:
@@ -299,6 +350,7 @@ interface CompileOptions {
   hastPlugins?: HastPluginDefinition[];
   features?: Features;
   fileURL?: URL;
+  data?: Data;
 }
 
 // mdxToJs accepts MdxCompileOptions, which extends CompileOptions
@@ -309,6 +361,8 @@ interface MdxCompileOptions extends CompileOptions {
 
 `fileURL` is the `URL` of the document being processed, surfaced to plugins as `ctx.fileURL` (a `URL`, or `undefined` when omitted). Pass a file URL such as Astro's `fileURL`, or convert a filesystem path with Node's `pathToFileURL`; read it back with `fileURLToPath(ctx.fileURL)`.
 
+`data` seeds the document-level data bag before plugins run, surfaced as `ctx.data` and returned as `result.data`. See [Sharing data between plugins](#sharing-data-between-plugins).
+
 `Features` controls the Markdown extensions Sätteri's parser recognizes: `gfm`, `frontmatter`, `math`, `directive`, `smartPunctuation`, etc. `gfm`, `math`, and `smartPunctuation` also accept granular options. For example, `math: { singleDollarTextMath: false }` keeps single `$` as literal text. See the [Features reference](https://satteri.dev/docs/features/) for the full list.
 
 ## License

package/dist/byte-writer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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;
+    /** 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;
+}

package/dist/byte-writer.js

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+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). */
+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).
+    buf = EMPTY;
+    n = 0;
+    #initialSize;
+    constructor(initialSize) {
+        this.#initialSize = initialSize;
+    }
+    /** Number of bytes written so far. */
+    get length() {
+        return this.n;
+    }
+    /** Reset for reuse; the grown buffer is retained so steady state is alloc-free. */
+    reset() {
+        this.n = 0;
+    }
+    /** View of the bytes written so far (no copy; valid until the next write or reset). */
+    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. */
+    ensure(extra) {
+        if (this.n + extra <= this.buf.length)
+            return;
+        let size = Math.max(this.#initialSize, this.buf.length * 2);
+        while (this.n + extra > size)
+            size *= 2;
+        const grown = new Uint8Array(size);
+        grown.set(this.buf);
+        this.buf = grown;
+    }
+    /** Write a u32 (LE) at the cursor; caller must have `ensure`d 4 bytes. */
+    writeU32(v) {
+        const buf = this.buf;
+        let n = this.n;
+        buf[n++] = v & 255;
+        buf[n++] = (v >> 8) & 255;
+        buf[n++] = (v >> 16) & 255;
+        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++) {
+                if (s.charCodeAt(i) > 127) {
+                    ascii = false;
+                    break;
+                }
+            }
+            if (ascii) {
+                // Inline stores, not writeU32: a per-string method call in the
+                // unoptimized tier is exactly what this class's header rules out.
+                const buf = this.buf;
+                let n = this.n;
+                buf[n++] = len & 255;
+                buf[n++] = (len >> 8) & 255;
+                buf[n++] = (len >> 16) & 255;
+                buf[n++] = (len >>> 24) & 255;
+                for (let i = 0; i < len; i++)
+                    buf[n + i] = s.charCodeAt(i);
+                this.n = n + len;
+                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.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.n += written;
+    }
+}

package/dist/child-stub.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+/**
+ * Descriptor template 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`.
+ */
+export declare function stubDescriptors(fields: readonly string[]): PropertyDescriptorMap;
+/** 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

@@ -0,0 +1,57 @@
+/**
+ * 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. */
+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. */
+const FIELD_GETTERS = new Map();
+function fieldGetter(key) {
+    let getter = FIELD_GETTERS.get(key);
+    if (getter === undefined) {
+        getter = function () {
+            let real = REAL_NODES.get(this);
+            if (real === undefined) {
+                real = this._resolver.materializeOne(this._id);
+                REAL_NODES.set(this, real);
+            }
+            const value = real[key];
+            Object.defineProperty(this, key, {
+                value,
+                writable: true,
+                enumerable: true,
+                configurable: true,
+            });
+            return value;
+        };
+        FIELD_GETTERS.set(key, getter);
+    }
+    return getter;
+}
+/**
+ * Descriptor template 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`.
+ */
+export function stubDescriptors(fields) {
+    const map = {};
+    for (const key of [...fields, "position", "data"]) {
+        map[key] = { get: fieldGetter(key), enumerable: true, configurable: true };
+    }
+    return map;
+}
+/** Node tags are dense small ints, so the per-child stub loop indexes flat
+ *  arrays instead of paying Map/dictionary lookups. */
+export function flatByTag(table) {
+    const flat = [];
+    for (const tag of Object.keys(table)) {
+        const nodeType = Number(tag);
+        flat[nodeType] = table[nodeType];
+    }
+    return flat;
+}

package/dist/command-buffer.d.ts

@@ -2,20 +2,22 @@
  * Binary command buffer for efficient JS→Rust mutation serialization.
  *
  * Simple mutations (remove, setProperty) are encoded as compact binary commands.
- * Structural mutations (insert, replace) carry payloads that can be raw strings
- * (for Rust to re-parse) or JSON-serialized node trees.
+ * 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 { ByteWriter } from "./byte-writer.js";
 import type { MdastNode } from "./types.js";
 type ReturnClass = "no_change" | "raw_markdown" | "raw_html" | "structured_node";
 export declare function classifyReturn(value: unknown): ReturnClass;
-export declare class CommandBuffer {
-    private buffer;
-    private view;
-    private bytes;
-    private offset;
+/** Structural commands that carry a subtree payload. Each has an `${op}Opstream`
+ *  twin (declarative content) and a raw twin (`{raw}`/`{rawHtml}` escape hatch). */
+export type StructuralOp = "replace" | "insertBefore" | "insertAfter" | "prependChild" | "appendChild" | "wrapNode";
+export declare class CommandBuffer extends ByteWriter {
     constructor();
     removeNode(nodeId: number): void;
     /** Unified set-property for both MDAST and HAST nodes. */
@@ -50,28 +52,23 @@ export declare class CommandBuffer {
     } | {
         rawHtml: string;
     }): void;
-    /** Write a REPLACE command with a pre-serialized JSON payload. */
-    replaceRawJson(nodeId: number, json: string): void;
-    /** Replace a node's child list (Root-wrapped `json`) while keeping the node. */
-    setChildren(nodeId: number, json: string): void;
-    /** Write any structural command with a pre-serialized JSON payload. */
-    insertBeforeRawJson(nodeId: number, json: string): void;
-    insertAfterRawJson(nodeId: number, json: string): void;
-    prependChildRawJson(nodeId: number, json: string): void;
-    appendChildRawJson(nodeId: number, json: string): void;
-    wrapNodeRawJson(nodeId: number, json: string): void;
-    private writeRawJsonCommand;
+    /** 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;
     /** Return a Uint8Array view of the written bytes (no copy). */
     getBuffer(): Uint8Array;
-    /** Number of bytes written so far. */
-    get length(): number;
-    /** Reset the buffer for reuse, releasing the old ArrayBuffer. */
+    /** 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. */
     private writeStructuralCommand;
-    private ensureCapacity;
-    private grow;
-    private writeU8;
-    private writeU32;
-    private writeBytes;
 }
 export {};

package/dist/command-buffer.js

@@ -2,33 +2,17 @@
  * Binary command buffer for efficient JS→Rust mutation serialization.
  *
  * Simple mutations (remove, setProperty) are encoded as compact binary commands.
- * Structural mutations (insert, replace) carry payloads that can be raw strings
- * (for Rust to re-parse) or JSON-serialized node trees.
+ * 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.
  */
-// Command bytes (0x01–0x0F)
-const CMD_REMOVE = 0x01;
-const CMD_INSERT_BEFORE = 0x05;
-const CMD_INSERT_AFTER = 0x06;
-const CMD_PREPEND_CHILD = 0x07;
-const CMD_APPEND_CHILD = 0x08;
-const CMD_WRAP = 0x09;
-const CMD_REPLACE = 0x0b;
-const CMD_SET_PROPERTY = 0x0c;
-const CMD_SET_CHILDREN = 0x0d;
-// 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;
-const PROP_SPACE_SEP = 3;
-const PROP_INT = 5;
-const PROP_NULL = 6;
+import { ByteWriter } from "./byte-writer.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";
 export function classifyReturn(value) {
     if (value === undefined || value === null)
         return "no_change";
@@ -42,61 +26,50 @@ export function classifyReturn(value) {
     throw new Error("Invalid return value from visitor: must have raw, rawHtml, or type");
 }
 const INITIAL_SIZE = 4096;
-const encoder = new TextEncoder();
-const EMPTY_U8 = new Uint8Array(0);
-export class CommandBuffer {
-    buffer;
-    view;
-    bytes;
-    offset = 0;
+export class CommandBuffer extends ByteWriter {
     constructor() {
-        this.buffer = new ArrayBuffer(INITIAL_SIZE);
-        this.view = new DataView(this.buffer);
-        this.bytes = new Uint8Array(this.buffer);
+        super(INITIAL_SIZE);
     }
     removeNode(nodeId) {
-        this.ensureCapacity(5);
-        this.writeU8(CMD_REMOVE);
+        this.ensure(5);
+        this.buf[this.n++] = CMD_REMOVE;
         this.writeU32(nodeId);
     }
     /** Unified set-property for both MDAST and HAST nodes. */
     setProperty(nodeId, key, value) {
-        const encodedName = encoder.encode(key);
         let valueType;
-        let encodedValue;
+        let str;
         if (value === null || value === undefined) {
             valueType = PROP_NULL;
-            encodedValue = EMPTY_U8;
+            str = "";
         }
         else if (value === true) {
             valueType = PROP_BOOL_TRUE;
-            encodedValue = EMPTY_U8;
+            str = "";
         }
         else if (value === false) {
             valueType = PROP_BOOL_FALSE;
-            encodedValue = EMPTY_U8;
+            str = "";
         }
         else if (typeof value === "number") {
             valueType = PROP_INT;
-            encodedValue = encoder.encode(String(value));
+            str = String(value);
         }
         else if (Array.isArray(value)) {
             valueType = PROP_SPACE_SEP;
-            encodedValue = encoder.encode(value.join(" "));
+            str = value.join(" ");
         }
         else {
             valueType = PROP_STRING;
-            encodedValue = encoder.encode(String(value));
+            str = String(value);
         }
-        // 1(cmd) + 4(nodeId) + 1(valueType) + 4(nameLen) + name + 4(valueLen) + value
-        this.ensureCapacity(14 + encodedName.length + encodedValue.length);
-        this.writeU8(CMD_SET_PROPERTY);
+        // 1(cmd) + 4(nodeId) + 1(valueType); name and value are length-prefixed strings
+        this.ensure(6);
+        this.buf[this.n++] = CMD_SET_PROPERTY;
         this.writeU32(nodeId);
-        this.writeU8(valueType);
-        this.writeU32(encodedName.length);
-        this.writeBytes(encodedName);
-        this.writeU32(encodedValue.length);
-        this.writeBytes(encodedValue);
+        this.buf[this.n++] = valueType;
+        this.utf8WithU32Len(key);
+        this.utf8WithU32Len(str);
     }
     insertBefore(nodeId, newNode) {
         this.writeStructuralCommand(CMD_INSERT_BEFORE, nodeId, newNode);
@@ -116,108 +89,67 @@ export class CommandBuffer {
     replace(nodeId, newNode) {
         this.writeStructuralCommand(CMD_REPLACE, nodeId, newNode);
     }
-    /** Write a REPLACE command with a pre-serialized JSON payload. */
-    replaceRawJson(nodeId, json) {
-        this.writeRawJsonCommand(CMD_REPLACE, nodeId, json);
+    /** Header (cmd + nodeId + payloadType) followed by a length-prefixed string payload. */
+    writePayloadCommand(cmd, nodeId, payloadType, s) {
+        this.ensure(6);
+        this.buf[this.n++] = cmd;
+        this.writeU32(nodeId);
+        this.buf[this.n++] = payloadType;
+        this.utf8WithU32Len(s);
+    }
+    replaceOpstream(nodeId, ops) {
+        this.writeOpstreamCommand(CMD_REPLACE, nodeId, ops);
     }
-    /** Replace a node's child list (Root-wrapped `json`) while keeping the node. */
-    setChildren(nodeId, json) {
-        this.writeRawJsonCommand(CMD_SET_CHILDREN, nodeId, json);
+    /** Replace a node's child list (root-wrapped `ops`) while keeping the node. */
+    setChildrenOpstream(nodeId, ops) {
+        this.writeOpstreamCommand(CMD_SET_CHILDREN, nodeId, ops);
     }
-    /** Write any structural command with a pre-serialized JSON payload. */
-    insertBeforeRawJson(nodeId, json) {
-        this.writeRawJsonCommand(CMD_INSERT_BEFORE, nodeId, json);
+    insertBeforeOpstream(nodeId, ops) {
+        this.writeOpstreamCommand(CMD_INSERT_BEFORE, nodeId, ops);
     }
-    insertAfterRawJson(nodeId, json) {
-        this.writeRawJsonCommand(CMD_INSERT_AFTER, nodeId, json);
+    insertAfterOpstream(nodeId, ops) {
+        this.writeOpstreamCommand(CMD_INSERT_AFTER, nodeId, ops);
     }
-    prependChildRawJson(nodeId, json) {
-        this.writeRawJsonCommand(CMD_PREPEND_CHILD, nodeId, json);
+    prependChildOpstream(nodeId, ops) {
+        this.writeOpstreamCommand(CMD_PREPEND_CHILD, nodeId, ops);
     }
-    appendChildRawJson(nodeId, json) {
-        this.writeRawJsonCommand(CMD_APPEND_CHILD, nodeId, json);
+    appendChildOpstream(nodeId, ops) {
+        this.writeOpstreamCommand(CMD_APPEND_CHILD, nodeId, ops);
     }
-    wrapNodeRawJson(nodeId, json) {
-        this.writeRawJsonCommand(CMD_WRAP, nodeId, json);
+    wrapNodeOpstream(nodeId, ops) {
+        this.writeOpstreamCommand(CMD_WRAP, nodeId, ops);
     }
-    writeRawJsonCommand(cmd, nodeId, json) {
-        const encoded = encoder.encode(json);
-        this.ensureCapacity(10 + encoded.length);
-        this.writeU8(cmd);
+    writeOpstreamCommand(cmd, nodeId, ops) {
+        this.ensure(10 + ops.length);
+        this.buf[this.n++] = cmd;
         this.writeU32(nodeId);
-        this.writeU8(PAYLOAD_SERDE_JSON);
-        this.writeU32(encoded.length);
-        this.writeBytes(encoded);
+        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 new Uint8Array(this.buffer, 0, this.offset);
-    }
-    /** Number of bytes written so far. */
-    get length() {
-        return this.offset;
+        return this.take();
     }
-    /** Reset the buffer for reuse, releasing the old ArrayBuffer. */
+    /** Reset for reuse, releasing the old buffer (handed-out views stay intact). */
     reset() {
-        this.buffer = new ArrayBuffer(INITIAL_SIZE);
-        this.view = new DataView(this.buffer);
-        this.bytes = new Uint8Array(this.buffer);
-        this.offset = 0;
+        if (this.n === 0)
+            return;
+        this.release();
     }
+    /** Raw structural content (`{raw}`/`{rawHtml}` escape hatches). Declarative
+     *  nodes go through the `*Opstream` methods, not here. */
     writeStructuralCommand(cmd, nodeId, node) {
         const v = node;
         if (typeof v.raw === "string") {
-            const encoded = encoder.encode(v.raw);
-            this.ensureCapacity(10 + encoded.length); // 1(cmd) + 4(nodeId) + 1(payloadType) + 4(len) + payload
-            this.writeU8(cmd);
-            this.writeU32(nodeId);
-            this.writeU8(PAYLOAD_RAW_MARKDOWN);
-            this.writeU32(encoded.length);
-            this.writeBytes(encoded);
+            this.writePayloadCommand(cmd, nodeId, PAYLOAD_RAW_MARKDOWN, v.raw);
         }
         else if (typeof v.rawHtml === "string") {
-            const encoded = encoder.encode(v.rawHtml);
-            this.ensureCapacity(10 + encoded.length);
-            this.writeU8(cmd);
-            this.writeU32(nodeId);
-            this.writeU8(PAYLOAD_RAW_HTML);
-            this.writeU32(encoded.length);
-            this.writeBytes(encoded);
+            this.writePayloadCommand(cmd, nodeId, PAYLOAD_RAW_HTML, v.rawHtml);
         }
         else {
-            // Structured node, serialize as JSON
-            const json = JSON.stringify(node);
-            const encoded = encoder.encode(json);
-            this.ensureCapacity(10 + encoded.length);
-            this.writeU8(cmd);
-            this.writeU32(nodeId);
-            this.writeU8(PAYLOAD_SERDE_JSON);
-            this.writeU32(encoded.length);
-            this.writeBytes(encoded);
-        }
-    }
-    ensureCapacity(needed) {
-        while (this.offset + needed > this.buffer.byteLength) {
-            this.grow();
+            throw new Error("CommandBuffer: structural content must be {raw} or {rawHtml}");
         }
     }
-    grow() {
-        const newBuffer = new ArrayBuffer(this.buffer.byteLength * 2);
-        new Uint8Array(newBuffer).set(this.bytes);
-        this.buffer = newBuffer;
-        this.view = new DataView(this.buffer);
-        this.bytes = new Uint8Array(this.buffer);
-    }
-    writeU8(val) {
-        this.view.setUint8(this.offset, val);
-        this.offset += 1;
-    }
-    writeU32(val) {
-        this.view.setUint32(this.offset, val, true);
-        this.offset += 4;
-    }
-    writeBytes(data) {
-        this.bytes.set(data, this.offset);
-        this.offset += data.length;
-    }
 }