satteri 0.9.4 → 0.10.0

package/dist/mdast/generated/layout.js

@@ -1,7 +1,6 @@
 // @generated by `cargo run -p satteri-layout-codegen`. Do not edit by hand.
 import { ru16, ru32, rstr } from "../../wire-read.js";
 import { restorePhantomSpaces } from "../../phantom.js";
-import { lazyGroup } from "../../lazy-props.js";
 import { decodeMdxJsxAttr } from "../../mdx-attr.js";
 import { decodeColumnAlign } from "../column-align.js";
 /** Walk-wire fields per node-type tag (see Rust `write_mdast_type_data_inline`). */
@@ -57,13 +56,16 @@ const MDAST_LAYOUTS = {
         { js: "value", offset: 8, kind: "str32" },
     ],
     28: [{ js: "value", offset: 8, kind: "str32" }],
+    38: [
+        { js: "name", offset: 0, kind: "str16" },
+        { js: "value", offset: 8, kind: "str32" },
+    ],
     102: [{ js: "value", offset: 0, kind: "str32", phantom: true }],
     103: [{ js: "value", offset: 0, kind: "str32", phantom: true }],
     104: [{ js: "value", offset: 0, kind: "str32", phantom: true }],
 };
 /** Materialized property names per tag (the non-skip `js` names above),
- *  precomputed so `materializeMdastFields` doesn't rebuild them per node.
- *  Exported for the child-stub field tables. */
+ *  exported for the child-stub field tables. */
 export const MDAST_LAYOUT_KEYS = {
     2: ["depth"],
     7: ["value"],
@@ -81,6 +83,7 @@ export const MDAST_LAYOUT_KEYS = {
     20: ["identifier", "label"],
     27: ["meta", "value"],
     28: ["value"],
+    38: ["name", "value"],
     102: ["value"],
     103: ["value"],
     104: ["value"],
@@ -237,36 +240,29 @@ export function decodeMdastTypeData(view, buf, start, nodeType, node) {
  * Attach a node's fixed `type_data` fields, materialized from the arena
  * snapshot, driven by `MDAST_LAYOUTS`. Returns `false` for tags with no entry,
  * so the materializer falls through to its hand-written cases (list, table,
- * directives, MDX JSX). Fields resolve lazily on first access.
+ * directives, MDX JSX). Fields are eager plain stores.
  */
 export function materializeMdastFields(reader, node, nodeId, nodeType) {
     const fields = MDAST_LAYOUTS[nodeType];
     if (fields === undefined)
         return false;
-    lazyGroup(node, MDAST_LAYOUT_KEYS[nodeType], () => {
-        const data = reader.getTypeData(nodeId);
-        const out = {};
-        for (const f of fields) {
-            if (f.kind === "u8") {
-                // Short type_data falls back to the layout's declared default,
-                // matching the Rust walk serializer.
-                const b = data[f.offset] ?? f.default ?? 0;
-                if (!f.skip)
-                    out[f.js] = f.values ? (f.values[b] ?? f.values[0]) : b;
-            }
-            else {
-                // Short type_data (e.g. a 20-byte ReferenceData-only imageReference)
-                // yields an empty ref, mirroring the Rust decoders' bounds checks.
-                const ref = f.offset + 8 <= data.length
-                    ? reader.readStringRef(data, f.offset)
-                    : { offset: 0, len: 0 };
-                if (f.skip)
-                    continue;
-                const s = f.nullable && ref.len === 0 ? null : reader.getString(ref.offset, ref.len);
-                out[f.js] = f.phantom && typeof s === "string" ? restorePhantomSpaces(s) : s;
-            }
+    const out = node;
+    for (const f of fields) {
+        if (f.skip)
+            continue;
+        if (f.kind === "u8") {
+            // Short type_data falls back to the layout's declared default,
+            // matching the Rust walk serializer.
+            const b = reader.fieldU8(nodeId, f.offset, f.default ?? 0);
+            out[f.js] = f.values ? (f.values[b] ?? f.values[0]) : b;
         }
-        return out;
-    });
+        else {
+            // Short type_data (e.g. a 20-byte ReferenceData-only imageReference)
+            // reads as empty, mirroring the Rust decoders' bounds checks.
+            const raw = reader.fieldString(nodeId, f.offset);
+            const s = f.nullable && raw === "" ? null : raw;
+            out[f.js] = f.phantom && typeof s === "string" ? restorePhantomSpaces(s) : s;
+        }
+    }
     return true;
 }

package/dist/mdast/generated/node-types.d.ts

@@ -38,6 +38,10 @@ export declare const NodeType: Readonly<{
     readonly TextDirective: 32;
     readonly Superscript: 33;
     readonly Subscript: 34;
+    readonly DescriptionList: 35;
+    readonly DescriptionTerm: 36;
+    readonly DescriptionDetails: 37;
+    readonly Custom: 38;
     readonly MdxJsxFlowElement: 100;
     readonly MdxJsxTextElement: 101;
     readonly MdxFlowExpression: 102;

package/dist/mdast/generated/node-types.js

@@ -35,6 +35,10 @@ export const TYPE_NAMES = {
     32: "textDirective",
     33: "superscript",
     34: "subscript",
+    35: "descriptionList",
+    36: "descriptionTerm",
+    37: "descriptionDetails",
+    38: "custom",
     100: "mdxJsxFlowElement",
     101: "mdxJsxTextElement",
     102: "mdxFlowExpression",
@@ -77,6 +81,10 @@ export const NAME_TO_TYPE = {
     textDirective: 32,
     superscript: 33,
     subscript: 34,
+    descriptionList: 35,
+    descriptionTerm: 36,
+    descriptionDetails: 37,
+    custom: 38,
     mdxJsxFlowElement: 100,
     mdxJsxTextElement: 101,
     mdxFlowExpression: 102,
@@ -119,6 +127,10 @@ export const NodeType = Object.freeze({
     TextDirective: 32,
     Superscript: 33,
     Subscript: 34,
+    DescriptionList: 35,
+    DescriptionTerm: 36,
+    DescriptionDetails: 37,
+    Custom: 38,
     MdxJsxFlowElement: 100,
     MdxJsxTextElement: 101,
     MdxFlowExpression: 102,
@@ -161,6 +173,10 @@ export const NodeTypeName = {
     32: "TextDirective",
     33: "Superscript",
     34: "Subscript",
+    35: "DescriptionList",
+    36: "DescriptionTerm",
+    37: "DescriptionDetails",
+    38: "Custom",
     100: "MdxJsxFlowElement",
     101: "MdxJsxTextElement",
     102: "MdxFlowExpression",
@@ -202,6 +218,10 @@ export const VISITOR_KEYS = new Set([
     "textDirective",
     "superscript",
     "subscript",
+    "descriptionList",
+    "descriptionTerm",
+    "descriptionDetails",
+    "custom",
     "mdxJsxFlowElement",
     "mdxJsxTextElement",
     "mdxFlowExpression",
@@ -245,6 +265,10 @@ export const MDAST_OPSTREAM_TYPES = {
     textDirective: 32,
     superscript: 33,
     subscript: 34,
+    descriptionList: 35,
+    descriptionTerm: 36,
+    descriptionDetails: 37,
+    custom: 38,
     mdxJsxFlowElement: 100,
     mdxJsxTextElement: 101,
     mdxFlowExpression: 102,
@@ -261,6 +285,7 @@ export const MDAST_CUSTOM_TYPES = [
     "containerDirective",
     "leafDirective",
     "textDirective",
+    "descriptionDetails",
     "mdxJsxFlowElement",
     "mdxJsxTextElement",
 ];

package/dist/mdast/mdast-materializer.d.ts

@@ -1,10 +1,19 @@
 import type { Root } from "mdast";
-import type { MdastNode } from "../types.js";
 import type { MdastReader } from "./mdast-reader.js";
 export declare const LEAF_TYPES: ReadonlySet<number>;
+/** A `custom` node is a leaf when it has a non-empty `value` and no children or
+ *  `data.h*`. Leafness is per node there, not per type, so the read paths ask
+ *  this instead of {@link LEAF_TYPES}.
+ *  @see {@link Custom} */
+export declare function isCustomLeaf(node: {
+    readonly value?: unknown;
+    readonly data?: unknown;
+}, childCount: number): boolean;
 /**
- * Materialize a single MDAST node from a binary buffer as a lazy JS object.
+ * Materialize a single MDAST node; scalars eager, `children` lazy, memoized
+ * per `(reader, id)`; `frozen` (the plugin walk path) deep-freezes so plugins
+ * cannot corrupt the shared cache.
  */
-export declare function materializeNode(reader: MdastReader, nodeId: number): MdastNode;
+export declare const materializeNode: (reader: MdastReader, nodeId: number, frozen?: boolean, refs?: import("../visitor-shared.js").NodeRefs) => import("mdast").Nodes;
 /** Materialize the full tree from root (nodeId=0). */
 export declare function materializeMdastTree(reader: MdastReader): Root;

package/dist/mdast/mdast-materializer.js

@@ -1,47 +1,99 @@
-import { lazyProp, lazyGroup } from "../lazy-props.js";
-import { TYPE_NAMES } from "./generated/node-types.js";
+import { NAME_TO_TYPE, TYPE_NAMES } from "./generated/node-types.js";
 import { materializeMdastFields } from "./generated/layout.js";
+import { createMaterializer } from "../materializer-cache.js";
+/** Internal tag for user-defined nodes; its stored `name` field carries the
+ *  author's public `type` string. */
+const MDAST_CUSTOM = NAME_TO_TYPE.custom;
 // Leaf node types that do NOT have children.
 // Type 9 = `definition`; type 18 = `imageReference` — leaves per mdast spec
 // (imageReference carries `alt` as a string, not children).
 export const LEAF_TYPES = new Set([
     9, 10, 13, 7, 8, 14, 3, 16, 18, 20, 25, 26, 27, 28, 102, 103, 104,
 ]);
+/** A `custom` node is a leaf when it has a non-empty `value` and no children or
+ *  `data.h*`. Leafness is per node there, not per type, so the read paths ask
+ *  this instead of {@link LEAF_TYPES}.
+ *  @see {@link Custom} */
+export function isCustomLeaf(node, childCount) {
+    const { value, data } = node;
+    if (childCount !== 0 || typeof value !== "string" || value === "")
+        return false;
+    if (data === null || typeof data !== "object")
+        return true;
+    if ("hName" in data && typeof data.hName === "string")
+        return false;
+    if ("hChildren" in data && Array.isArray(data.hChildren))
+        return false;
+    if (!("hProperties" in data))
+        return true;
+    const props = data.hProperties;
+    return props === null || typeof props !== "object" || Array.isArray(props);
+}
 /**
- * Add type-specific lazy properties to a node object.
+ * Add type-specific properties to a node object as eager plain stores.
  */
 function addTypeProperties(node, reader, nodeId, nodeType) {
     // Fixed-field types materialize from the generated layout table; the rest
     // (variable-length / cross-field) stay in the hand-written switch.
-    if (materializeMdastFields(reader, node, nodeId, nodeType))
+    if (materializeMdastFields(reader, node, nodeId, nodeType)) {
+        // User-defined node: surface the stored `name` as the open `node.type`.
+        // Drop an empty `value` so a parent node isn't given a spurious leaf field.
+        if (nodeType === MDAST_CUSTOM) {
+            const n = node;
+            if (n.name !== undefined)
+                n.type = n.name;
+            delete n.name;
+            if (n.value === "")
+                delete n.value;
+        }
         return;
+    }
     switch (nodeType) {
         case 5: {
             // list
-            const resolveList = () => {
-                const d = reader.getListData(nodeId);
-                return { ordered: d.ordered, start: d.ordered ? d.start : null, spread: d.spread };
-            };
-            lazyGroup(node, ["ordered", "start", "spread"], resolveList);
+            const d = reader.getListData(nodeId);
+            const n = node;
+            n.ordered = d.ordered;
+            n.start = d.ordered ? d.start : null;
+            n.spread = d.spread;
             break;
         }
-        case 6: // listItem
-            lazyGroup(node, ["spread", "checked"], () => reader.getListItemData(nodeId));
+        case 6: {
+            // listItem
+            const d = reader.getListItemData(nodeId);
+            const n = node;
+            n.spread = d.spread;
+            n.checked = d.checked;
             break;
+        }
+        case 37: {
+            // descriptionDetails
+            const d = reader.getDescriptionDetailsData(nodeId);
+            node.spread = d.spread;
+            break;
+        }
         case 21: // table
-            Object.defineProperties(node, {
-                align: lazyProp("align", () => reader.getTableAlign(nodeId)),
-            });
+            node.align = reader.getTableAlign(nodeId);
             break;
         case 30: // containerDirective
         case 31: // leafDirective
-        case 32: // textDirective
-            lazyGroup(node, ["name", "attributes"], () => reader.getDirectiveData(nodeId));
+        case 32: {
+            // textDirective
+            const d = reader.getDirectiveData(nodeId);
+            const n = node;
+            n.name = d.name;
+            n.attributes = d.attributes;
             break;
+        }
         case 100: // mdxJsxFlowElement
-        case 101: // mdxJsxTextElement
-            lazyGroup(node, ["name", "attributes"], () => reader.getMdxJsxElementData(nodeId));
+        case 101: {
+            // mdxJsxTextElement
+            const d = reader.getMdxJsxElementData(nodeId);
+            const n = node;
+            n.name = d.name;
+            n.attributes = d.attributes;
             break;
+        }
         // Nodes with no type-specific props:
         // root(0), paragraph(1), thematicBreak(3), blockquote(4),
         // emphasis(11), strong(12), break(14), tableRow(22), tableCell(23), delete(24)
@@ -49,68 +101,21 @@ function addTypeProperties(node, reader, nodeId, nodeType) {
             break;
     }
 }
+const mdastMaterializer = createMaterializer({
+    label: "materializeNode",
+    typeNames: TYPE_NAMES,
+    hasChildren: (nodeType, node, reader, nodeId) => nodeType === MDAST_CUSTOM
+        ? !isCustomLeaf(node, reader.getChildIds(nodeId).length)
+        : !LEAF_TYPES.has(nodeType),
+    populate: addTypeProperties,
+});
 /**
- * Materialize a single MDAST node from a binary buffer as a lazy JS object.
+ * Materialize a single MDAST node; scalars eager, `children` lazy, memoized
+ * per `(reader, id)`; `frozen` (the plugin walk path) deep-freezes so plugins
+ * cannot corrupt the shared cache.
  */
-export function materializeNode(reader, nodeId) {
-    const rawNode = reader.getNode(nodeId);
-    const nodeType = rawNode.type;
-    const typeName = TYPE_NAMES[nodeType] ?? `unknown(${nodeType})`;
-    const node = { type: typeName };
-    if (rawNode.position !== undefined) {
-        node.position = rawNode.position;
-    }
-    // _nodeId: non-enumerable internal reference
-    Object.defineProperty(node, "_nodeId", {
-        value: nodeId,
-        writable: false,
-        configurable: true,
-        enumerable: false,
-    });
-    // Type-specific lazy properties
-    addTypeProperties(node, reader, nodeId, nodeType);
-    // Plugin-set `data` survives the visitor walk via its own getter but
-    // would be dropped when materialized from a serialized handle.
-    const rawData = reader.getNodeData(nodeId);
-    if (rawData !== null) {
-        try {
-            const parsed = JSON.parse(rawData);
-            if (parsed && typeof parsed === "object" && Object.keys(parsed).length > 0) {
-                Object.defineProperty(node, "data", {
-                    value: parsed,
-                    writable: true,
-                    configurable: true,
-                    enumerable: true,
-                });
-            }
-        }
-        catch (err) {
-            if (process.env.NODE_ENV !== "production") {
-                console.warn(`materializeNode: malformed node_data for nodeId=${nodeId}`, err);
-            }
-        }
-    }
-    // children: lazy getter (only for non-leaf nodes)
-    if (!LEAF_TYPES.has(nodeType)) {
-        Object.defineProperty(node, "children", {
-            get() {
-                const childIds = reader.getChildIds(nodeId);
-                const children = childIds.map((id) => materializeNode(reader, id));
-                Object.defineProperty(this, "children", {
-                    value: children,
-                    writable: true,
-                    configurable: true,
-                    enumerable: true,
-                });
-                return children;
-            },
-            configurable: true,
-            enumerable: true,
-        });
-    }
-    return node;
-}
+export const materializeNode = mdastMaterializer.node;
 /** Materialize the full tree from root (nodeId=0). */
 export function materializeMdastTree(reader) {
-    return materializeNode(reader, 0);
+    return mdastMaterializer.tree(reader, 0);
 }

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

@@ -1,4 +1,5 @@
 import type { MdastNodeRaw, BufferHeader, StringRefRaw, MdxJsxAttributeUnion } from "../types.js";
+import { readPosition } from "../wire-read.js";
 export { NodeType, NodeTypeName } from "./generated/node-types.js";
 export declare class MdastReader {
     #private;
@@ -16,11 +17,19 @@ export declare class MdastReader {
     getNode(nodeId: number): MdastNodeRaw;
     /** Fast path: read only the type byte for a node. */
     getNodeType(nodeId: number): number;
+    getPosition(nodeId: number): ReturnType<typeof readPosition>;
     /** Fast path: read only the parent id for a node (0xffffffff at the root). */
     getParentId(nodeId: number): number;
     getChildIds(nodeId: number): number[];
     /** Push child node IDs directly onto a stack array (reverse order for depth-first). */
     pushChildIds(nodeId: number, stack: number[]): void;
+    /** Fixed-layout field reads that touch the buffer directly. The generated
+     *  decoder runs once per node, so an intermediate view or ref object here
+     *  costs an allocation per field. */
+    fieldU8(nodeId: number, offset: number, fallback: number): number;
+    /** `""` when the field is absent or empty; callers map that to `null` for
+     *  nullable fields, matching the Rust decoders' bounds checks. */
+    fieldString(nodeId: number, offset: number): string;
     getTypeData(nodeId: number): Uint8Array;
     /** Read a StringRef (offset: u32 LE, len: u32 LE) from type data. */
     readStringRef(typeData: Uint8Array, byteOffset?: number): StringRefRaw;
@@ -46,6 +55,12 @@ export declare class MdastReader {
         checked: boolean | null;
         spread: boolean;
     };
+    /**
+     * DescriptionDetailsData #[repr(C)]: spread(0). Valid for descriptionDetails.
+     */
+    getDescriptionDetailsData(nodeId: number): {
+        spread: boolean;
+    };
     /**
      * TableData #[repr(C)]: align_count(0..4), then align_count bytes.
      * Alignment bytes: 0=none, 1=left, 2=right, 3=center.

package/dist/mdast/mdast-reader.js

@@ -1,6 +1,7 @@
 import { restorePhantomSpaces } from "../phantom.js";
 import { readPosition } from "../wire-read.js";
 import { decodeColumnAlign } from "./column-align.js";
+import { PoolOffsets } from "../string-pool.js";
 import { NodeTypeName } from "./generated/node-types.js";
 import { ARENA_MAGIC, KIND_MDAST, FIELD, HEADER } from "../generated/arena-layout.js";
 export { NodeType, NodeTypeName } from "./generated/node-types.js";
@@ -9,6 +10,8 @@ export class MdastReader {
     #header;
     #textDecoder;
     #stringPoolCache = null;
+    #poolChecked = false;
+    #poolOffsets = null;
     constructor(buffer) {
         if (buffer instanceof Uint8Array) {
             this.#view = new DataView(buffer.buffer, buffer.byteOffset, buffer.byteLength);
@@ -16,7 +19,7 @@ export class MdastReader {
         else {
             this.#view = new DataView(buffer);
         }
-        this.#textDecoder = new TextDecoder("utf-8");
+        this.#textDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
         this.#header = this.#readHeader();
     }
     #readHeader() {
@@ -86,9 +89,21 @@ export class MdastReader {
     getString(offset, len) {
         if (len === 0)
             return "";
-        const { stringPoolOffset } = this.#header;
-        const bytes = new Uint8Array(this.#view.buffer, this.#view.byteOffset + stringPoolOffset + offset, len);
-        return this.#textDecoder.decode(bytes);
+        const pool = this.getStringPool();
+        if (!this.#poolChecked) {
+            this.#poolChecked = true;
+            const { stringPoolOffset, stringPoolLen } = this.#header;
+            const extraBytes = stringPoolLen - pool.length;
+            if (extraBytes > 0) {
+                const bytes = new Uint8Array(this.#view.buffer, this.#view.byteOffset + stringPoolOffset, stringPoolLen);
+                this.#poolOffsets = new PoolOffsets(bytes, extraBytes);
+            }
+        }
+        // An all-ASCII pool has byte offsets equal to its UTF-16 indices.
+        const offsets = this.#poolOffsets;
+        return offsets === null
+            ? pool.substring(offset, offset + len)
+            : offsets.slice(pool, offset, len);
     }
     getNode(nodeId) {
         const { nodesOffset, nodeStructSize, nodeCount } = this.#header;
@@ -116,6 +131,10 @@ export class MdastReader {
         const { nodesOffset, nodeStructSize } = this.#header;
         return this.#view.getUint8(nodesOffset + nodeId * nodeStructSize + FIELD.node_type);
     }
+    getPosition(nodeId) {
+        const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
+        return readPosition(this.#view, base + FIELD.start_offset);
+    }
     /** Fast path: read only the parent id for a node (0xffffffff at the root). */
     getParentId(nodeId) {
         const { nodesOffset, nodeStructSize } = this.#header;
@@ -148,6 +167,27 @@ export class MdastReader {
             stack.push(v.getUint32(childrenOffset + (childrenStart + i) * 4, true));
         }
     }
+    /** Fixed-layout field reads that touch the buffer directly. The generated
+     *  decoder runs once per node, so an intermediate view or ref object here
+     *  costs an allocation per field. */
+    fieldU8(nodeId, offset, fallback) {
+        const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
+        const v = this.#view;
+        if (offset >= v.getUint32(base + FIELD.data_len, true))
+            return fallback;
+        const at = this.#header.typeDataOffset + v.getUint32(base + FIELD.data_offset, true);
+        return v.getUint8(at + offset);
+    }
+    /** `""` when the field is absent or empty; callers map that to `null` for
+     *  nullable fields, matching the Rust decoders' bounds checks. */
+    fieldString(nodeId, offset) {
+        const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
+        const v = this.#view;
+        if (offset + 8 > v.getUint32(base + FIELD.data_len, true))
+            return "";
+        const at = this.#header.typeDataOffset + v.getUint32(base + FIELD.data_offset, true) + offset;
+        return this.getString(v.getUint32(at, true), v.getUint32(at + 4, true));
+    }
     getTypeData(nodeId) {
         const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
         const v = this.#view;
@@ -159,10 +199,10 @@ export class MdastReader {
     }
     /** Read a StringRef (offset: u32 LE, len: u32 LE) from type data. */
     readStringRef(typeData, byteOffset = 0) {
-        const view = new DataView(typeData.buffer, typeData.byteOffset + byteOffset);
+        const at = typeData.byteOffset - this.#view.byteOffset + byteOffset;
         return {
-            offset: view.getUint32(0, true),
-            len: view.getUint32(4, true),
+            offset: this.#view.getUint32(at, true),
+            len: this.#view.getUint32(at + 4, true),
         };
     }
     /**
@@ -170,9 +210,7 @@ export class MdastReader {
      * These store a single StringRef as their type data.
      */
     getTextValue(nodeId) {
-        const data = this.getTypeData(nodeId);
-        const ref = this.readStringRef(data);
-        return this.getString(ref.offset, ref.len);
+        return this.fieldString(nodeId, 0);
     }
     /**
      * ListData #[repr(C)]: start(0..4), ordered(4), spread(5), _pad(6..8).
@@ -199,6 +237,13 @@ export class MdastReader {
             spread: data[1] !== 0,
         };
     }
+    /**
+     * DescriptionDetailsData #[repr(C)]: spread(0). Valid for descriptionDetails.
+     */
+    getDescriptionDetailsData(nodeId) {
+        const data = this.getTypeData(nodeId);
+        return { spread: data.length > 0 && data[0] !== 0 };
+    }
     /**
      * TableData #[repr(C)]: align_count(0..4), then align_count bytes.
      * Alignment bytes: 0=none, 1=left, 2=right, 3=center.