satteri 0.8.0 → 0.9.0

package/dist/mdx-attr.d.ts

@@ -0,0 +1,2 @@
+import type { MdxJsxAttributeUnion } from "./types.js";
+export declare function decodeMdxJsxAttr(kind: number, name: string, value: string): MdxJsxAttributeUnion;

package/dist/mdx-attr.js

@@ -0,0 +1,20 @@
+/** Decode an MDX JSX attribute from its wire `(kind, name, value)` — shared by
+ *  the generated mdast tail decoder and the hast path so the kind dispatch lives
+ *  once. Expression/spread values carry phantom-space sentinels, restored here. */
+import { restorePhantomSpaces } from "./phantom.js";
+export function decodeMdxJsxAttr(kind, name, value) {
+    switch (kind) {
+        case 0:
+            return { type: "mdxJsxAttribute", name, value: null };
+        case 1:
+            return { type: "mdxJsxAttribute", name, value };
+        case 2:
+            return {
+                type: "mdxJsxAttribute",
+                name,
+                value: { type: "mdxJsxAttributeValueExpression", value: restorePhantomSpaces(value) },
+            };
+        default:
+            return { type: "mdxJsxExpressionAttribute", value: restorePhantomSpaces(value) };
+    }
+}

package/dist/op-stream.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Low-level op-stream writer shared by the MDAST/HAST declarative compilers.
+ *
+ * Emits the compact OPEN/CLOSE/field/REF/KEEP_CHILDREN/PROP stream that Rust
+ * replays straight into the arena (`replay_opstream` in js_commands.rs; byte
+ * values in generated/wire-constants.ts) — the only structural encoding for
+ * plugin-built content. Strings ride ByteWriter's zero-alloc path (inline
+ * char codes when short ASCII, `encodeInto` otherwise).
+ */
+import { ByteWriter } from "./byte-writer.js";
+export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_COMMA_SEP, PROP_INT, PROP_NULL, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
+export declare class OpWriter extends ByteWriter {
+    #private;
+    constructor();
+    /**
+     * Start a compile on this (shared, module-level) writer. Encoding evaluates
+     * plugin-supplied getters and `toJSON`; if one of those calls a context
+     * mutation, the nested compile would reset the stream under the outer one
+     * and corrupt it silently — throw instead. Pair with `end` in a `finally`.
+     */
+    begin(): void;
+    end(): void;
+    open(type: number): void;
+    close(): void;
+    str(field: number, s: string): void;
+    u8(field: number, v: number): void;
+    u32(field: number, v: number): void;
+    bool(field: number, v: boolean): void;
+    data(value: unknown): void;
+    prop(name: string, kind: number, value: string): void;
+    ref(id: number): void;
+    /** Table column-alignment codes (0=none, 1=left, 2=right, 3=center). */
+    align(codes: readonly number[]): void;
+    keepChildren(): void;
+}
+/** Emit one MDX JSX attribute as an OP_PROP, mirroring `encode_js_jsx_attrs`:
+ *  null→boolean, string→literal, `{ value }` object→expression, else→boolean. */
+export declare function emitMdxAttr(w: OpWriter, a: Record<string, unknown>): void;

package/dist/op-stream.js

@@ -0,0 +1,125 @@
+/**
+ * Low-level op-stream writer shared by the MDAST/HAST declarative compilers.
+ *
+ * Emits the compact OPEN/CLOSE/field/REF/KEEP_CHILDREN/PROP stream that Rust
+ * replays straight into the arena (`replay_opstream` in js_commands.rs; byte
+ * values in generated/wire-constants.ts) — the only structural encoding for
+ * plugin-built content. Strings ride ByteWriter's zero-alloc path (inline
+ * char codes when short ASCII, `encodeInto` otherwise).
+ */
+import { ByteWriter } from "./byte-writer.js";
+import { OP_OPEN, OP_CLOSE, OP_REF, OP_KEEP_CHILDREN, OP_STR, OP_U8, OP_U32, OP_BOOL, OP_DATA, OP_PROP, OP_ALIGN, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
+// Re-exported so visitors/readers keep importing wire constants from here.
+export { OF_VALUE, OF_URL, OF_TITLE, OF_ALT, OF_LANG, OF_META, OF_IDENTIFIER, OF_LABEL, OF_NAME, OF_REFERENCE_TYPE, OF_DEPTH, OF_CHECKED, OF_START, OF_ORDERED, OF_SPREAD, OF_TAGNAME, OF_EXPLICIT, PROP_STRING, PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_COMMA_SEP, PROP_INT, PROP_NULL, MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "./generated/wire-constants.js";
+export class OpWriter extends ByteWriter {
+    #encoding = false;
+    constructor() {
+        super(512);
+    }
+    /**
+     * Start a compile on this (shared, module-level) writer. Encoding evaluates
+     * plugin-supplied getters and `toJSON`; if one of those calls a context
+     * mutation, the nested compile would reset the stream under the outer one
+     * and corrupt it silently — throw instead. Pair with `end` in a `finally`.
+     */
+    begin() {
+        if (this.#encoding) {
+            throw new Error("reentrant op-stream compile: a node getter or toJSON invoked a context mutation while its node was being encoded");
+        }
+        this.#encoding = true;
+        this.reset();
+    }
+    end() {
+        this.#encoding = false;
+    }
+    open(type) {
+        this.ensure(2);
+        this.buf[this.n++] = OP_OPEN;
+        this.buf[this.n++] = type;
+    }
+    close() {
+        this.ensure(1);
+        this.buf[this.n++] = OP_CLOSE;
+    }
+    str(field, s) {
+        this.ensure(2);
+        this.buf[this.n++] = OP_STR;
+        this.buf[this.n++] = field;
+        this.utf8WithU32Len(s);
+    }
+    u8(field, v) {
+        this.ensure(3);
+        this.buf[this.n++] = OP_U8;
+        this.buf[this.n++] = field;
+        this.buf[this.n++] = v & 255;
+    }
+    u32(field, v) {
+        this.ensure(6);
+        this.buf[this.n++] = OP_U32;
+        this.buf[this.n++] = field;
+        this.writeU32(v);
+    }
+    bool(field, v) {
+        this.ensure(3);
+        this.buf[this.n++] = OP_BOOL;
+        this.buf[this.n++] = field;
+        this.buf[this.n++] = v ? 1 : 0;
+    }
+    data(value) {
+        const json = JSON.stringify(value);
+        // `JSON.stringify` yields undefined for a function or a `toJSON`
+        // returning undefined; a clear error beats a TypeError deep in the
+        // string encoder.
+        if (typeof json !== "string") {
+            throw new Error("node `data` is not JSON-serializable");
+        }
+        this.ensure(1);
+        this.buf[this.n++] = OP_DATA;
+        this.utf8WithU32Len(json);
+    }
+    prop(name, kind, value) {
+        this.ensure(1);
+        this.buf[this.n++] = OP_PROP;
+        this.utf8WithU32Len(name);
+        this.ensure(1);
+        this.buf[this.n++] = kind;
+        this.utf8WithU32Len(value);
+    }
+    ref(id) {
+        this.ensure(5);
+        this.buf[this.n++] = OP_REF;
+        this.writeU32(id);
+    }
+    /** Table column-alignment codes (0=none, 1=left, 2=right, 3=center). */
+    align(codes) {
+        this.ensure(5 + codes.length);
+        this.buf[this.n++] = OP_ALIGN;
+        this.writeU32(codes.length);
+        for (let i = 0; i < codes.length; i++)
+            this.buf[this.n++] = codes[i] & 255;
+    }
+    keepChildren() {
+        this.ensure(1);
+        this.buf[this.n++] = OP_KEEP_CHILDREN;
+    }
+}
+/** Emit one MDX JSX attribute as an OP_PROP, mirroring `encode_js_jsx_attrs`:
+ *  null→boolean, string→literal, `{ value }` object→expression, else→boolean. */
+export function emitMdxAttr(w, a) {
+    if (a.type === "mdxJsxExpressionAttribute") {
+        w.prop("", MDX_ATTR_SPREAD, typeof a.value === "string" ? a.value : "");
+        return;
+    }
+    const name = typeof a.name === "string" ? a.name : "";
+    const val = a.value;
+    if (typeof val === "string") {
+        w.prop(name, MDX_ATTR_LITERAL_PROP, val);
+    }
+    else if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+        const expr = val.value;
+        w.prop(name, MDX_ATTR_EXPRESSION_PROP, typeof expr === "string" ? expr : "");
+    }
+    else {
+        w.prop(name, MDX_ATTR_BOOLEAN_PROP, "");
+    }
+}

package/dist/phantom.d.ts

@@ -0,0 +1,2 @@
+/** Restore phantom-space sentinels to real spaces, allocating only when present. */
+export declare function restorePhantomSpaces(value: string): string;

package/dist/phantom.js

@@ -0,0 +1,13 @@
+/**
+ * Sentinel the MDX parser substitutes for spaces inside expression and JSX
+ * attribute-expression values (see `PHANTOM_SPACE` in
+ * satteri-pulldown-cmark/src/mdx.rs). mdast and hast keep the sentinel in the
+ * stored value; readers and visitors restore the real space on the way out.
+ * Both plugin-facing paths (direct walk match and materialized child) must
+ * restore it so a node's `value` reads the same regardless of how it's reached.
+ */
+const PHANTOM_SPACE = "\uF002";
+/** Restore phantom-space sentinels to real spaces, allocating only when present. */
+export function restorePhantomSpaces(value) {
+    return value.includes(PHANTOM_SPACE) ? value.replaceAll(PHANTOM_SPACE, " ") : value;
+}

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { Position } from "unist";
-import type { Literal as MdastLiteral, Nodes as MdastStdNodes } from "mdast";
-import type { Nodes as HastStdNodes } from "hast";
+import type { Literal as MdastLiteral, Nodes as MdastStdNodes, Parent as MdastParent, PhrasingContent } from "mdast";
+import type { Literal as HastLiteral, Nodes as HastStdNodes } from "hast";
 export type { Position, Point } from "unist";
 export type { MdxJsxFlowElement, MdxJsxTextElement, MdxJsxAttribute as MdxJsxAttributeNode, MdxJsxExpressionAttribute as MdxJsxExpressionAttributeNode, MdxJsxAttributeValueExpression as MdxJsxAttributeValueExpressionNode, MdxFlowExpression, MdxTextExpression, MdxjsEsm, MdxJsxFlowElementHast, MdxJsxTextElementHast, MdxFlowExpressionHast, MdxTextExpressionHast, MdxjsEsmHast, } from "./mdx-types.js";
 export type { ContainerDirective, LeafDirective, TextDirective, DirectiveAttributes, } from "./directive-types.js";
@@ -16,6 +16,14 @@ export interface MathNode extends MdastLiteral {
 export interface InlineMath extends MdastLiteral {
     type: "inlineMath";
 }
+export interface Superscript extends MdastParent {
+    type: "superscript";
+    children: PhrasingContent[];
+}
+export interface Subscript extends MdastParent {
+    type: "subscript";
+    children: PhrasingContent[];
+}
 declare module "mdast" {
     interface FrontmatterContentMap {
         toml: Toml;
@@ -24,17 +32,20 @@ declare module "mdast" {
         toml: Toml;
         math: MathNode;
         inlineMath: InlineMath;
+        superscript: Superscript;
+        subscript: Subscript;
     }
     interface PhrasingContentMap {
         inlineMath: InlineMath;
+        superscript: Superscript;
+        subscript: Subscript;
     }
     interface BlockContentMap {
         math: MathNode;
     }
 }
-export interface HastRaw {
+export interface HastRaw extends HastLiteral {
     type: "raw";
-    value: string;
 }
 declare module "hast" {
     interface RootContentMap {
@@ -56,6 +67,25 @@ export type MdastNode = MdastStdNodes;
  * (e.g. `tagName` on `"element"`, `value` on `"text"`).
  */
 export type HastNode = HastStdNodes;
+/**
+ * Registry for typing well-known keys on the plugin data bag. Augment it to
+ * give specific `ctx.data` / `result.data` keys a type:
+ *
+ * ```ts
+ * declare module "satteri" {
+ *   interface DataMap {
+ *     toc: TocEntry[];
+ *   }
+ * }
+ * ```
+ */
+export interface DataMap {
+}
+/**
+ * The document-level plugin data bag (`ctx.data` and `result.data`): any
+ * string key holding any value, plus the typed keys registered in {@link DataMap}.
+ */
+export type Data = Record<string, unknown> & Partial<DataMap>;
 export interface StringRefRaw {
     offset: number;
     len: number;

package/dist/visitor-shared.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Cold/shape-stable helpers shared by the mdast and hast visitors. The
+ * per-node hot decoders stay duplicated in each visitor on purpose: sharing
+ * them would feed differently-shaped arguments through one call site and turn
+ * it polymorphic.
+ */
+import type { CommandBuffer } from "./command-buffer.js";
+export declare function asArray<T>(value: T | T[]): T[];
+/** Thrown when declarative replacement content can't be compiled to the
+ *  structural op-stream — an unsupported node type (e.g. a bare `root`/`doctype`
+ *  handed in as content) or an out-of-range numeric field. The op-stream is the
+ *  only structural encoding, so this is a hard error rather than a fallback. */
+export declare function unencodableContentError(content: unknown): Error;
+/**
+ * Arena id for a node passed to a context method, via a per-kind `nid` lookup
+ * (closure keeps each kind's call site monomorphic). Plugin-built nodes have
+ * no id; without this check the id would coerce to 0 in the command buffer
+ * and the mutation would silently target the document root.
+ */
+export declare function makeRequireNid<TNode>(nid: (node: TNode) => number | undefined): (node: TNode, method: string) => number;
+/** Concatenate the return-value and context command buffers for one pass,
+ *  resetting both for reuse. */
+export declare function mergeAndReset(returnBuffer: CommandBuffer, ctx: {
+    getCommandBuffer(): CommandBuffer;
+}): {
+    merged: Uint8Array;
+    hasMutations: boolean;
+};

package/dist/visitor-shared.js

@@ -0,0 +1,52 @@
+/**
+ * Cold/shape-stable helpers shared by the mdast and hast visitors. The
+ * per-node hot decoders stay duplicated in each visitor on purpose: sharing
+ * them would feed differently-shaped arguments through one call site and turn
+ * it polymorphic.
+ */
+const EMPTY_BYTES = new Uint8Array(0);
+export function asArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/** Thrown when declarative replacement content can't be compiled to the
+ *  structural op-stream — an unsupported node type (e.g. a bare `root`/`doctype`
+ *  handed in as content) or an out-of-range numeric field. The op-stream is the
+ *  only structural encoding, so this is a hard error rather than a fallback. */
+export function unencodableContentError(content) {
+    const type = content?.type;
+    return new Error(`satteri: cannot encode replacement content${typeof type === "string" ? ` of type "${type}"` : ""} ` +
+        "into the structural op-stream — unsupported node type or out-of-range numeric field.");
+}
+/**
+ * Arena id for a node passed to a context method, via a per-kind `nid` lookup
+ * (closure keeps each kind's call site monomorphic). Plugin-built nodes have
+ * no id; without this check the id would coerce to 0 in the command buffer
+ * and the mutation would silently target the document root.
+ */
+export function makeRequireNid(nid) {
+    return (node, method) => {
+        const id = nid(node);
+        if (id === undefined) {
+            throw new Error(`${method}: node has no arena id — it was built in JS, not read from this tree. ` +
+                `Pass plugin-built nodes as new content (e.g. the second argument of insertAfter).`);
+        }
+        return id;
+    };
+}
+/** Concatenate the return-value and context command buffers for one pass,
+ *  resetting both for reuse. */
+export function mergeAndReset(returnBuffer, ctx) {
+    const ctxCmdBuf = ctx.getCommandBuffer();
+    // The common case — no mutations this pass — allocates nothing.
+    if (returnBuffer.length === 0 && ctxCmdBuf.length === 0) {
+        return { merged: EMPTY_BYTES, hasMutations: false };
+    }
+    const ctxBuf = ctxCmdBuf.getBuffer();
+    const retBuf = returnBuffer.getBuffer();
+    const merged = new Uint8Array(retBuf.length + ctxBuf.length);
+    merged.set(retBuf, 0);
+    merged.set(ctxBuf, retBuf.length);
+    returnBuffer.reset();
+    ctxCmdBuf.reset();
+    return { merged, hasMutations: true };
+}

package/dist/wire-read.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Little-endian primitives for reading the walk/snapshot wire buffers. Shared by
+ * the hand-written decoders and the generated layout decoder so both interpret
+ * the bytes identically.
+ */
+import type { Position } from "unist";
+/** Read a u16 (LE) at `off`. */
+export declare function ru16(view: DataView, off: number): number;
+/** Read a u32 (LE) at `off`. */
+export declare function ru32(view: DataView, off: number): number;
+/** Read a UTF-8 string of `len` bytes at `off`. Very short ASCII runs decode
+ *  with a charCode loop — TextDecoder's per-call overhead dominates there. The
+ *  threshold is lower than the encode-side `INLINE_STR_MAX`: decoding builds a
+ *  JS string by concatenation, which costs more per char than storing bytes.
+ *  Measured crossover ~8-12 bytes (Node 24: 8B 30 vs 57 ns, 16B 64 vs 57). */
+export declare function rstr(buf: Uint8Array, off: number, len: number): string;
+/**
+ * Decode the 24-byte position block ([startOffset, endOffset, startLine,
+ * startColumn, endLine, endColumn], u32 LE each) shared by the walk prefixes
+ * and the snapshot node structs. A zero start line is the sentinel for
+ * synthesized nodes with no source range (e.g. GFM autolink-literal nodes, or a
+ * plugin-built replacement spliced by the rebuild): unist lines are 1-based, so
+ * line 0 always means "no source position" — even when the rebuild has rebased
+ * the (otherwise zero) offset by the spliced subtree's source base. Surfaced as
+ * `undefined` so a node reads the same however it's reached.
+ */
+export declare function readPosition(view: DataView, off: number): Position | undefined;

package/dist/wire-read.js

@@ -0,0 +1,59 @@
+/**
+ * Little-endian primitives for reading the walk/snapshot wire buffers. Shared by
+ * the hand-written decoders and the generated layout decoder so both interpret
+ * the bytes identically.
+ */
+const textDecoder = new TextDecoder("utf-8");
+/** Read a u16 (LE) at `off`. */
+export function ru16(view, off) {
+    return view.getUint16(off, true);
+}
+/** Read a u32 (LE) at `off`. */
+export function ru32(view, off) {
+    return view.getUint32(off, true);
+}
+/** Read a UTF-8 string of `len` bytes at `off`. Very short ASCII runs decode
+ *  with a charCode loop — TextDecoder's per-call overhead dominates there. The
+ *  threshold is lower than the encode-side `INLINE_STR_MAX`: decoding builds a
+ *  JS string by concatenation, which costs more per char than storing bytes.
+ *  Measured crossover ~8-12 bytes (Node 24: 8B 30 vs 57 ns, 16B 64 vs 57). */
+export function rstr(buf, off, len) {
+    if (len === 0)
+        return "";
+    if (len <= 8) {
+        let ascii = true;
+        for (let i = 0; i < len; i++) {
+            if (buf[off + i] > 127) {
+                ascii = false;
+                break;
+            }
+        }
+        if (ascii) {
+            let s = "";
+            for (let i = 0; i < len; i++)
+                s += String.fromCharCode(buf[off + i]);
+            return s;
+        }
+    }
+    return textDecoder.decode(buf.subarray(off, off + len));
+}
+/**
+ * Decode the 24-byte position block ([startOffset, endOffset, startLine,
+ * startColumn, endLine, endColumn], u32 LE each) shared by the walk prefixes
+ * and the snapshot node structs. A zero start line is the sentinel for
+ * synthesized nodes with no source range (e.g. GFM autolink-literal nodes, or a
+ * plugin-built replacement spliced by the rebuild): unist lines are 1-based, so
+ * line 0 always means "no source position" — even when the rebuild has rebased
+ * the (otherwise zero) offset by the spliced subtree's source base. Surfaced as
+ * `undefined` so a node reads the same however it's reached.
+ */
+export function readPosition(view, off) {
+    const startLine = ru32(view, off + 8);
+    if (startLine === 0)
+        return undefined;
+    const startOffset = ru32(view, off);
+    return {
+        start: { offset: startOffset, line: startLine, column: ru32(view, off + 12) },
+        end: { offset: ru32(view, off + 4), line: ru32(view, off + 16), column: ru32(view, off + 20) },
+    };
+}