satteri 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -2,13 +2,19 @@ export { markdownToHtml, mdxToJs, evaluate, markdownToMdast, mdxToMdast, markdow
 export type { CompileOptions, MdxCompileOptions, MdxOnlyOptions, EvaluateOptions, OptimizeStaticConfig, Features, SmartPunctuationOptions, Frontmatter, MarkdownToHtmlResult, MdxToJsResult, } from "./compile.js";
 export { defineMdastPlugin, defineHastPlugin } from "./plugin.js";
 export type { MdastPluginDefinition, HastPluginDefinition, MdastPluginInput, HastPluginInput, } from "./plugin.js";
-export type { HastVisitorInstance, HastVisitorContext, HastFilteredVisitor, EstreeProgram, } from "./hast/hast-visitor.js";
-export type { MdastNode, HastNode, Position, Point, MdxJsxAttributeNode, MdxJsxExpressionAttributeNode, MdxJsxAttributeValueExpressionNode, MdxJsxAttributeUnion, MdxJsxFlowElement, MdxJsxTextElement, MdxFlowExpression, MdxTextExpression, MdxjsEsm, MdxJsxFlowElementHast, MdxJsxTextElementHast, MdxFlowExpressionHast, MdxTextExpressionHast, MdxjsEsmHast, } from "./types.js";
+export type { HastVisitorInstance, HastVisitorContext, HastFilteredVisitor, HastContent, EstreeProgram, } from "./hast/hast-visitor.js";
+export type { MdastNode, HastNode, DataMap, Data, Position, Point, MdxJsxAttributeNode, MdxJsxExpressionAttributeNode, MdxJsxAttributeValueExpressionNode, MdxJsxAttributeUnion, MdxJsxFlowElement, MdxJsxTextElement, MdxFlowExpression, MdxTextExpression, MdxjsEsm, MdxJsxFlowElementHast, MdxJsxTextElementHast, MdxFlowExpressionHast, MdxTextExpressionHast, MdxjsEsmHast, } from "./types.js";
 export { visitMdastHandle, resolveMdastSubscriptions } from "./mdast/mdast-visitor.js";
-export type { MdastPluginInstance } from "./mdast/mdast-visitor.js";
+export type { MdastPluginInstance, MdastContent } from "./mdast/mdast-visitor.js";
 export { visitHastHandle, resolveSubscriptions as resolveHastSubscriptions, } from "./hast/hast-visitor.js";
 export { MdastReader } from "./mdast/mdast-reader.js";
 export { materializeMdastTree } from "./mdast/mdast-materializer.js";
 export { HastReader } from "./hast/hast-reader.js";
 export { materializeHastTree } from "./hast/hast-materializer.js";
-export { createMdastHandle, createMdxMdastHandle, createHastHandle, createMdxHastHandle, convertMdastToHastHandle, serializeHandle, renderHandle, compileHandle, dropHandle, applyCommandsToMdastHandle, applyCommandsAndConvertToHastHandle, getHandleSource, } from "#binding";
+export { createMdastHandle, createMdxMdastHandle, createHastHandle, createMdxHastHandle, serializeHandle, renderHandle, compileHandle, getHandleSource, } from "#binding";
+import { applyCommandsAndConvertToHastHandle as napiApplyCommandsAndConvertToHastHandle, convertMdastToHastHandle as napiConvertMdastToHastHandle } from "#binding";
+import type { AnyHandle } from "./handles.js";
+export declare function applyCommandsToMdastHandle(handle: MdastHandle, commandBuf: Uint8Array): number;
+export declare function convertMdastToHastHandle(handle: MdastHandle, convertOptions?: Parameters<typeof napiConvertMdastToHastHandle>[1]): HastHandle;
+export declare function dropHandle(handle: AnyHandle): void;
+export declare function applyCommandsAndConvertToHastHandle(handle: MdastHandle, commandBuf: Uint8Array, convertOptions?: Parameters<typeof napiApplyCommandsAndConvertToHastHandle>[2]): HastHandle;

package/dist/index.js

@@ -10,4 +10,26 @@ export { MdastReader } from "./mdast/mdast-reader.js";
 export { materializeMdastTree } from "./mdast/mdast-materializer.js";
 export { HastReader } from "./hast/hast-reader.js";
 export { materializeHastTree } from "./hast/hast-materializer.js";
-export { createMdastHandle, createMdxMdastHandle, createHastHandle, createMdxHastHandle, convertMdastToHastHandle, serializeHandle, renderHandle, compileHandle, dropHandle, applyCommandsToMdastHandle, applyCommandsAndConvertToHastHandle, getHandleSource, } from "#binding";
+export { createMdastHandle, createMdxMdastHandle, createHastHandle, createMdxHastHandle, serializeHandle, renderHandle, compileHandle, getHandleSource, } from "#binding";
+import { applyCommandsToMdastHandle as napiApplyCommandsToMdastHandle, applyCommandsAndConvertToHastHandle as napiApplyCommandsAndConvertToHastHandle, convertMdastToHastHandle as napiConvertMdastToHastHandle, dropHandle as napiDropHandle, } from "#binding";
+import { markHandleMutated } from "./lazy-child-resolver.js";
+// The raw NAPI mutators renumber or empty the arena; without the epoch bump a
+// child stub retained past a manual-pipeline pass would silently snapshot the
+// changed arena (or die with an opaque RangeError) instead of hitting the
+// retention error.
+export function applyCommandsToMdastHandle(handle, commandBuf) {
+    markHandleMutated(handle);
+    return napiApplyCommandsToMdastHandle(handle, commandBuf);
+}
+export function convertMdastToHastHandle(handle, convertOptions) {
+    markHandleMutated(handle);
+    return napiConvertMdastToHastHandle(handle, convertOptions);
+}
+export function dropHandle(handle) {
+    markHandleMutated(handle);
+    napiDropHandle(handle);
+}
+export function applyCommandsAndConvertToHastHandle(handle, commandBuf, convertOptions) {
+    markHandleMutated(handle);
+    return napiApplyCommandsAndConvertToHastHandle(handle, commandBuf, convertOptions);
+}

package/dist/lazy-child-resolver.d.ts

@@ -0,0 +1,36 @@
+import type { AnyHandle } from "./handles.js";
+/** Record that `handle`'s arena was rebuilt. Resolvers created before the bump
+ *  refuse to take a fresh snapshot afterwards (their ids are stale). */
+export declare function markHandleMutated(handle: AnyHandle): void;
+/**
+ * Lazy node materializer for the walk paths: serializes the handle's arena
+ * once, on the first stub materialization, then materializes nodes from that
+ * snapshot. Subclasses supply reader construction and per-node materialization
+ * so the hot path stays free of per-node closures.
+ */
+export declare abstract class LazyChildResolver<TReader, TNode> {
+    #private;
+    constructor(handle: AnyHandle);
+    protected abstract createReader(wire: Uint8Array): TReader;
+    protected abstract materializeNode(reader: TReader, nodeId: number): TNode;
+    protected abstract readParentId(reader: TReader, nodeId: number): number;
+    protected abstract readChildIds(reader: TReader, nodeId: number): number[];
+    /**
+     * Mark the visitor pass over. Child ids were captured at match time; once
+     * the pass's mutations land the arena is rebuilt and ids renumbered, so a
+     * later snapshot would map those stale ids onto the wrong nodes (or out of
+     * range). Failing loudly here beats silently wrong children.
+     */
+    seal(): void;
+    /** Guards the `.children` getters: a first read after the pass is refused
+     *  outright, even when no mutation landed — match-time ids cannot be trusted
+     *  once the plugin no longer controls the tree. */
+    assertUnsealed(): void;
+    /** Materialize one node for a child stub's first real-field read. */
+    materializeOne(nodeId: number): TNode;
+    /** Arena id of `nodeId`'s parent in the pass snapshot, or undefined at the root. */
+    parentIdOf(nodeId: number): number | undefined;
+    /** Index of `nodeId` within its parent's children in the pass snapshot,
+     *  or undefined at the root. */
+    indexInParent(nodeId: number): number | undefined;
+}

package/dist/lazy-child-resolver.js

@@ -0,0 +1,95 @@
+import { serializeHandle } from "#binding";
+/** Rebuild count per handle: bumped whenever a command buffer lands and
+ *  renumbers the arena, invalidating ids captured before it. */
+const HANDLE_EPOCHS = new WeakMap();
+/** Record that `handle`'s arena was rebuilt. Resolvers created before the bump
+ *  refuse to take a fresh snapshot afterwards (their ids are stale). */
+export function markHandleMutated(handle) {
+    HANDLE_EPOCHS.set(handle, (HANDLE_EPOCHS.get(handle) ?? 0) + 1);
+}
+/** Arena sentinel in the node struct's parent field: the node has no parent. */
+const NO_PARENT = 0xffffffff;
+/**
+ * Lazy node materializer for the walk paths: serializes the handle's arena
+ * once, on the first stub materialization, then materializes nodes from that
+ * snapshot. Subclasses supply reader construction and per-node materialization
+ * so the hot path stays free of per-node closures.
+ */
+export class LazyChildResolver {
+    #handle;
+    #reader = null;
+    #sealed = false;
+    #epoch;
+    constructor(handle) {
+        this.#handle = handle;
+        this.#epoch = HANDLE_EPOCHS.get(handle) ?? 0;
+    }
+    /**
+     * Mark the visitor pass over. Child ids were captured at match time; once
+     * the pass's mutations land the arena is rebuilt and ids renumbered, so a
+     * later snapshot would map those stale ids onto the wrong nodes (or out of
+     * range). Failing loudly here beats silently wrong children.
+     */
+    seal() {
+        this.#sealed = true;
+    }
+    /** Guards the `.children` getters: a first read after the pass is refused
+     *  outright, even when no mutation landed — match-time ids cannot be trusted
+     *  once the plugin no longer controls the tree. */
+    assertUnsealed() {
+        if (this.#sealed) {
+            throw new Error("Cannot read node content: this node was retained past its visitor pass " +
+                "and the tree may have changed since; read it inside the visitor.");
+        }
+    }
+    #ensureReader() {
+        if (this.#reader === null) {
+            // A node id proves the tree was read in-pass, so a deferred snapshot is
+            // still faithful as long as no command buffer rebuilt the arena since
+            // match time (ids renumber on rebuild). An existing reader is always
+            // safe: the snapshot is an immutable pre-mutation copy.
+            if ((HANDLE_EPOCHS.get(this.#handle) ?? 0) !== this.#epoch) {
+                throw new Error("Cannot read node content: this node was retained past its visitor pass " +
+                    "and the tree has changed since; read it inside the visitor.");
+            }
+            // The serialized buffer already carries each node's `data` blob (read
+            // eagerly by the materializer), and the arena isn't mutated mid-visit —
+            // so no separate lazy NAPI fetch is needed. This also keeps walk-path
+            // children consistent with the fully materialized tree (no `data` key
+            // when a node has none).
+            this.#reader = this.createReader(serializeHandle(this.#handle));
+        }
+        return this.#reader;
+    }
+    /** Materialize one node for a child stub's first real-field read. */
+    materializeOne(nodeId) {
+        return this.materializeNode(this.#ensureReader(), nodeId);
+    }
+    /** Arena id of `nodeId`'s parent in the pass snapshot, or undefined at the root. */
+    parentIdOf(nodeId) {
+        this.assertUnsealed();
+        const parentId = this.readParentId(this.#ensureReader(), nodeId);
+        return parentId === NO_PARENT ? undefined : parentId;
+    }
+    /** Per-parent child-id→index maps, built lazily: null until a plugin calls
+     *  `indexInParent` (most never do). Cache-safe because the snapshot is immutable. */
+    #childIndexByParent = null;
+    /** Index of `nodeId` within its parent's children in the pass snapshot,
+     *  or undefined at the root. */
+    indexInParent(nodeId) {
+        this.assertUnsealed();
+        const reader = this.#ensureReader();
+        const parentId = this.readParentId(reader, nodeId);
+        if (parentId === NO_PARENT)
+            return undefined;
+        const byParent = (this.#childIndexByParent ??= new Map());
+        let indexById = byParent.get(parentId);
+        if (indexById === undefined) {
+            const map = new Map();
+            this.readChildIds(reader, parentId).forEach((id, i) => map.set(id, i));
+            byParent.set(parentId, map);
+            indexById = map;
+        }
+        return indexById.get(nodeId);
+    }
+}

package/dist/lazy-props.d.ts

@@ -7,4 +7,4 @@ export declare function lazyProp<T>(key: string, get: () => T): PropertyDescript
  * Uses a shared resolve-once pattern: the first getter to fire reads all data,
  * defines own properties for every key, then each per-key getter returns its value.
  */
-export declare function lazyGroup(node: object, keys: string[], resolve: () => Record<string, unknown>): void;
+export declare function lazyGroup(node: object, keys: readonly string[], resolve: () => Record<string, unknown>): void;

package/dist/mdast/child-stub.d.ts

@@ -0,0 +1,18 @@
+import type { LazyChildResolver } from "../lazy-child-resolver.js";
+import type { MdastNode } from "../types.js";
+import type { MdastReader } from "./mdast-reader.js";
+type MdastResolver = LazyChildResolver<MdastReader, MdastNode>;
+/**
+ * Walk-path child stub: arena id + `type` eagerly, every other field a lazy
+ * forward to the materialized node (first read snapshots the arena via
+ * `materializeOne`, which enforces the handle epoch — the pass seal is checked
+ * where the stubs are built). Spread/identity rules are enforced by `nid()`
+ * (authoritative doc in hast-visitor.ts).
+ */
+export declare class MdastChildStub {
+    _resolver: MdastResolver;
+    _id: number;
+    type: string;
+    constructor(resolver: MdastResolver, id: number, nodeType: number);
+}
+export {};

package/dist/mdast/child-stub.js

@@ -0,0 +1,46 @@
+import { flatByTag, stubDescriptors } from "../child-stub.js";
+import { MDAST_LAYOUT_KEYS } from "./generated/layout.js";
+import { NAME_TO_TYPE, TYPE_NAMES } from "./generated/node-types.js";
+import { LEAF_TYPES } from "./mdast-materializer.js";
+const N = NAME_TO_TYPE;
+/** Per-type stub fields for the types `addTypeProperties` hand-writes; the
+ *  fixed-layout types come from the generated `MDAST_LAYOUT_KEYS`. */
+const HAND_WRITTEN_FIELDS = {
+    [N.list]: ["ordered", "start", "spread"],
+    [N.listItem]: ["spread", "checked"],
+    [N.table]: ["align"],
+    [N.containerDirective]: ["name", "attributes"],
+    [N.leafDirective]: ["name", "attributes"],
+    [N.textDirective]: ["name", "attributes"],
+    [N.mdxJsxFlowElement]: ["name", "attributes"],
+    [N.mdxJsxTextElement]: ["name", "attributes"],
+};
+const TYPE_NAME_BY_TAG = flatByTag(TYPE_NAMES);
+const MDAST_STUB_DESCRIPTORS = [];
+for (const tag of Object.keys(TYPE_NAMES)) {
+    const nodeType = Number(tag);
+    const fields = [...(MDAST_LAYOUT_KEYS[nodeType] ?? HAND_WRITTEN_FIELDS[nodeType] ?? [])];
+    if (!LEAF_TYPES.has(nodeType))
+        fields.push("children");
+    MDAST_STUB_DESCRIPTORS[nodeType] = stubDescriptors(fields);
+}
+/** Unknown node types still expose the prelude-backed lazy fields. */
+const FALLBACK_DESCRIPTORS = stubDescriptors([]);
+/**
+ * Walk-path child stub: arena id + `type` eagerly, every other field a lazy
+ * forward to the materialized node (first read snapshots the arena via
+ * `materializeOne`, which enforces the handle epoch — the pass seal is checked
+ * where the stubs are built). Spread/identity rules are enforced by `nid()`
+ * (authoritative doc in hast-visitor.ts).
+ */
+export class MdastChildStub {
+    _resolver;
+    _id;
+    type;
+    constructor(resolver, id, nodeType) {
+        this._resolver = resolver;
+        this._id = id;
+        this.type = TYPE_NAME_BY_TAG[nodeType] ?? `unknown(${nodeType})`;
+        Object.defineProperties(this, MDAST_STUB_DESCRIPTORS[nodeType] ?? FALLBACK_DESCRIPTORS);
+    }
+}

package/dist/mdast/column-align.d.ts

@@ -0,0 +1 @@
+export declare function decodeColumnAlign(byte: number): string | null;

package/dist/mdast/column-align.js

@@ -0,0 +1,6 @@
+/** Decode a table column-alignment byte — shared by the generated walk decoder
+ *  and the snapshot reader so the mapping lives in one place. */
+const ALIGN_NAMES = [null, "left", "right", "center"];
+export function decodeColumnAlign(byte) {
+    return ALIGN_NAMES[byte] ?? null;
+}

package/dist/mdast/generated/layout.d.ts

@@ -0,0 +1,19 @@
+import type { MdastReader } from "../mdast-reader.js";
+/** 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. */
+export declare const MDAST_LAYOUT_KEYS: Readonly<Record<number, readonly string[]>>;
+/**
+ * Decode a node's type-specific `type_data` from the walk buffer onto `node`,
+ * driven by `MDAST_LAYOUTS` (fixed-field types) and `MDAST_TAILS` (counted
+ * attribute lists). Returns `false` for tags in neither, so the caller falls
+ * through to the remaining hand-written cases (list, listItem).
+ */
+export declare function decodeMdastTypeData(view: DataView, buf: Uint8Array, start: number, nodeType: number, node: Record<string, unknown>): boolean;
+/**
+ * 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.
+ */
+export declare function materializeMdastFields(reader: MdastReader, node: object, nodeId: number, nodeType: number): boolean;

package/dist/mdast/generated/layout.js

@@ -0,0 +1,272 @@
+// @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`). */
+const MDAST_LAYOUTS = {
+    2: [{ js: "depth", offset: 0, kind: "u8", default: 1 }],
+    7: [{ js: "value", offset: 0, kind: "str32" }],
+    10: [{ js: "value", offset: 0, kind: "str32" }],
+    13: [{ js: "value", offset: 0, kind: "str32" }],
+    25: [{ js: "value", offset: 0, kind: "str32" }],
+    26: [{ js: "value", offset: 0, kind: "str32" }],
+    8: [
+        { js: "lang", offset: 0, kind: "str16", nullable: true },
+        { js: "meta", offset: 8, kind: "str16", nullable: true },
+        { js: "value", offset: 16, kind: "str32" },
+    ],
+    9: [
+        { js: "url", offset: 0, kind: "str16" },
+        { js: "title", offset: 8, kind: "str16", nullable: true },
+        { js: "identifier", offset: 16, kind: "str16" },
+        { js: "label", offset: 24, kind: "str16" },
+    ],
+    15: [
+        { js: "url", offset: 0, kind: "str16" },
+        { js: "title", offset: 8, kind: "str16", nullable: true },
+    ],
+    16: [
+        { js: "url", offset: 0, kind: "str16" },
+        { js: "alt", offset: 8, kind: "str16" },
+        { js: "title", offset: 16, kind: "str16", nullable: true },
+    ],
+    17: [
+        { js: "identifier", offset: 0, kind: "str16" },
+        { js: "label", offset: 8, kind: "str16" },
+        { js: "referenceType", offset: 16, kind: "u8", values: ["shortcut", "collapsed", "full"] },
+    ],
+    18: [
+        { js: "identifier", offset: 0, kind: "str16" },
+        { js: "label", offset: 8, kind: "str16" },
+        { js: "referenceType", offset: 16, kind: "u8", values: ["shortcut", "collapsed", "full"] },
+        { js: "alt", offset: 20, kind: "str16" },
+    ],
+    19: [
+        { js: "identifier", offset: 0, kind: "str16" },
+        { js: "label", offset: 8, kind: "str16" },
+    ],
+    20: [
+        { js: "identifier", offset: 0, kind: "str16" },
+        { js: "label", offset: 8, kind: "str16" },
+        { js: "", offset: 16, kind: "u8", skip: true },
+    ],
+    27: [
+        { js: "meta", offset: 0, kind: "str16", nullable: true },
+        { js: "value", offset: 8, kind: "str32" },
+    ],
+    28: [{ 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. */
+export const MDAST_LAYOUT_KEYS = {
+    2: ["depth"],
+    7: ["value"],
+    10: ["value"],
+    13: ["value"],
+    25: ["value"],
+    26: ["value"],
+    8: ["lang", "meta", "value"],
+    9: ["url", "title", "identifier", "label"],
+    15: ["url", "title"],
+    16: ["url", "alt", "title"],
+    17: ["identifier", "label", "referenceType"],
+    18: ["identifier", "label", "referenceType", "alt"],
+    19: ["identifier", "label"],
+    20: ["identifier", "label"],
+    27: ["meta", "value"],
+    28: ["value"],
+    102: ["value"],
+    103: ["value"],
+    104: ["value"],
+};
+/** Walk-wire tail descriptors (a name head, then a counted item list) for
+ *  the variable-length attribute types the generic decoder below handles
+ *  without a hand-written case: `map` is a string key/value object
+ *  (directives), `jsx` a typed MDX-JSX attribute array. */
+const MDAST_TAILS = {
+    21: { head: [], item: [{ js: "align", kind: "u8" }], bytes: { attrsKey: "align" } },
+    30: {
+        head: [{ js: "name", kind: "str16" }],
+        item: [
+            { js: "key", kind: "str16" },
+            { js: "value", kind: "str16" },
+        ],
+        map: { attrsKey: "attributes", key: "key", value: "value" },
+    },
+    31: {
+        head: [{ js: "name", kind: "str16" }],
+        item: [
+            { js: "key", kind: "str16" },
+            { js: "value", kind: "str16" },
+        ],
+        map: { attrsKey: "attributes", key: "key", value: "value" },
+    },
+    32: {
+        head: [{ js: "name", kind: "str16" }],
+        item: [
+            { js: "key", kind: "str16" },
+            { js: "value", kind: "str16" },
+        ],
+        map: { attrsKey: "attributes", key: "key", value: "value" },
+    },
+    100: {
+        head: [{ js: "name", kind: "str16" }],
+        item: [
+            { js: "kind", kind: "u8" },
+            { js: "name", kind: "str16" },
+            { js: "value", kind: "str32" },
+        ],
+        jsx: { attrsKey: "attributes" },
+    },
+    101: {
+        head: [{ js: "name", kind: "str16" }],
+        item: [
+            { js: "kind", kind: "u8" },
+            { js: "name", kind: "str16" },
+            { js: "value", kind: "str32" },
+        ],
+        jsx: { attrsKey: "attributes" },
+    },
+};
+/**
+ * Decode a node's type-specific `type_data` from the walk buffer onto `node`,
+ * driven by `MDAST_LAYOUTS` (fixed-field types) and `MDAST_TAILS` (counted
+ * attribute lists). Returns `false` for tags in neither, so the caller falls
+ * through to the remaining hand-written cases (list, listItem).
+ */
+export function decodeMdastTypeData(view, buf, start, nodeType, node) {
+    const fields = MDAST_LAYOUTS[nodeType];
+    if (fields !== undefined) {
+        let pos = start;
+        for (const f of fields) {
+            if (f.kind === "u8") {
+                const b = buf[pos];
+                pos += 1;
+                if (f.skip)
+                    continue;
+                node[f.js] = f.values ? (f.values[b] ?? f.values[0]) : b;
+            }
+            else {
+                const len = f.kind === "str32" ? ru32(view, pos) : ru16(view, pos);
+                pos += f.kind === "str32" ? 4 : 2;
+                const raw = rstr(buf, pos, len);
+                pos += len;
+                if (f.skip)
+                    continue;
+                node[f.js] = f.nullable && len === 0 ? null : f.phantom ? restorePhantomSpaces(raw) : raw;
+            }
+        }
+        return true;
+    }
+    const tail = MDAST_TAILS[nodeType];
+    if (tail !== undefined) {
+        let pos = start;
+        // Reads are inlined and advance `pos` in place (no per-field tuple): this
+        // runs per attribute item in the matched-node decode path, and the
+        // unoptimized tiers CodSpeed measures won't elide the allocation.
+        for (const f of tail.head) {
+            let value;
+            if (f.kind === "u8") {
+                value = buf[pos];
+                pos += 1;
+            }
+            else {
+                const len = f.kind === "str32" ? ru32(view, pos) : ru16(view, pos);
+                pos += f.kind === "str32" ? 4 : 2;
+                const raw = rstr(buf, pos, len);
+                pos += len;
+                value = f.phantom ? restorePhantomSpaces(raw) : raw;
+            }
+            // MDX JSX elements carry a nullable name (empty → null); map heads keep it.
+            node[f.js] = tail.jsx !== undefined && value === "" ? null : value;
+        }
+        const count = ru16(view, pos);
+        pos += 2;
+        const readItem = () => {
+            const item = {};
+            for (const f of tail.item) {
+                if (f.kind === "u8") {
+                    item[f.js] = buf[pos];
+                    pos += 1;
+                }
+                else {
+                    const len = f.kind === "str32" ? ru32(view, pos) : ru16(view, pos);
+                    pos += f.kind === "str32" ? 4 : 2;
+                    const raw = rstr(buf, pos, len);
+                    pos += len;
+                    item[f.js] = f.phantom ? restorePhantomSpaces(raw) : raw;
+                }
+            }
+            return item;
+        };
+        if (tail.map !== undefined) {
+            const attrs = {};
+            for (let i = 0; i < count; i++) {
+                const item = readItem();
+                attrs[item[tail.map.key]] = item[tail.map.value];
+            }
+            node[tail.map.attrsKey] = attrs;
+        }
+        else if (tail.jsx !== undefined) {
+            const attrs = [];
+            for (let i = 0; i < count; i++) {
+                const item = readItem();
+                attrs.push(decodeMdxJsxAttr(item.kind, item.name, item.value));
+            }
+            node[tail.jsx.attrsKey] = attrs;
+        }
+        else {
+            const align = [];
+            for (let i = 0; i < count; i++) {
+                const item = readItem();
+                align.push(decodeColumnAlign(item.align));
+            }
+            node[tail.bytes.attrsKey] = align;
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * 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.
+ */
+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;
+            }
+        }
+        return out;
+    });
+    return true;
+}

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

@@ -0,0 +1,58 @@
+/** Node-type tag -> canonical AST name. */
+export declare const TYPE_NAMES: Readonly<Record<number, string>>;
+/** Canonical AST name -> node-type tag. */
+export declare const NAME_TO_TYPE: Readonly<Record<string, number>>;
+/** Node-type tag by Rust enum variant name. */
+export declare const NodeType: Readonly<{
+    readonly Root: 0;
+    readonly Paragraph: 1;
+    readonly Heading: 2;
+    readonly ThematicBreak: 3;
+    readonly Blockquote: 4;
+    readonly List: 5;
+    readonly ListItem: 6;
+    readonly Html: 7;
+    readonly Code: 8;
+    readonly Definition: 9;
+    readonly Text: 10;
+    readonly Emphasis: 11;
+    readonly Strong: 12;
+    readonly InlineCode: 13;
+    readonly Break: 14;
+    readonly Link: 15;
+    readonly Image: 16;
+    readonly LinkReference: 17;
+    readonly ImageReference: 18;
+    readonly FootnoteDefinition: 19;
+    readonly FootnoteReference: 20;
+    readonly Table: 21;
+    readonly TableRow: 22;
+    readonly TableCell: 23;
+    readonly Delete: 24;
+    readonly Yaml: 25;
+    readonly Toml: 26;
+    readonly Math: 27;
+    readonly InlineMath: 28;
+    readonly ContainerDirective: 30;
+    readonly LeafDirective: 31;
+    readonly TextDirective: 32;
+    readonly Superscript: 33;
+    readonly Subscript: 34;
+    readonly MdxJsxFlowElement: 100;
+    readonly MdxJsxTextElement: 101;
+    readonly MdxFlowExpression: 102;
+    readonly MdxTextExpression: 103;
+    readonly MdxjsEsm: 104;
+}>;
+/** Node-type tag -> Rust variant name (`typeName` diagnostics). */
+export declare const NodeTypeName: Readonly<Record<number, string>>;
+/** Names a plugin can subscribe to (every node except `root`). */
+export declare const VISITOR_KEYS: ReadonlySet<string>;
+/** Name -> tag for the types the op-stream can encode; one lookup gates AND
+ *  resolves the emit-path tag. Excluded names (see `*_OPSTREAM_EXCLUDED` in
+ *  schema.rs) have no encoding — the visitor throws for them. */
+export declare const MDAST_OPSTREAM_TYPES: Readonly<Record<string, number>>;
+/** Names of the variable-length `custom` node types (hand-written or
+ *  `Tail`-generated codec). The op-stream round-trip oracle asserts it covers
+ *  every one, so a forgotten or drifted encode/decode arm fails loudly. */
+export declare const MDAST_CUSTOM_TYPES: readonly string[];