satteri 0.8.1 → 0.9.1

package/dist/compile.d.ts

@@ -1,5 +1,5 @@
 import type { MdastPluginInput, HastPluginInput } from "./plugin.js";
-import type { MdastNode, HastNode } from "./types.js";
+import type { MdastNode, HastNode, Data } from "./types.js";
 /** Configuration for static subtree collapsing during MDX compilation. */
 export interface OptimizeStaticConfig {
     component: string;
@@ -130,6 +130,14 @@ export interface CompileOptions {
      * `pathToFileURL` before passing it.
      */
     fileURL?: URL;
+    /**
+     * Initial document-level data bag, seeding `ctx.data` before any plugin runs.
+     * It is the same object plugins mutate and the caller reads back as
+     * `result.data`, so values flow both into and out of a compile. Defaults to a
+     * fresh empty object. Used by reference and mutated in place, so pass a
+     * throwaway object per compile rather than a shared one.
+     */
+    data?: Data;
 }
 /**
  * MDX-only compile options.
@@ -200,6 +208,8 @@ export interface MarkdownToHtmlResult {
     html: string;
     /** Frontmatter block at the start of the document, or `null` if none. */
     frontmatter: Frontmatter | null;
+    /** Document-level data bag shared with plugins via `ctx.data`; the seeded `data` option if provided, else a fresh `{}`. */
+    data: Data;
 }
 /** Result of {@link mdxToJs}. */
 export interface MdxToJsResult {
@@ -207,6 +217,8 @@ export interface MdxToJsResult {
     code: string;
     /** Frontmatter block at the start of the document, or `null` if none. */
     frontmatter: Frontmatter | null;
+    /** Document-level data bag shared with plugins via `ctx.data`; the seeded `data` option if provided, else a fresh `{}`. */
+    data: Data;
 }
 type AnyFn = (...args: any[]) => unknown;
 type ReturnsPromise<F> = F extends AnyFn ? Extract<ReturnType<F>, Promise<unknown>> extends never ? false : true : false;

package/dist/compile.js

@@ -3,6 +3,7 @@ import { visitMdastHandle, resolveMdastSubscriptions, } from "./mdast/mdast-visi
 import { createHastHandle, createMdxHastHandle, renderHandle, compileHandle, dropHandle, createMdastHandle, createMdxMdastHandle, applyCommandsToMdastHandle, convertMdastToHastHandle, getHandleSource, getMdastFrontmatter, serializeHandle, } from "#binding";
 import { MdastReader } from "./mdast/mdast-reader.js";
 import { materializeMdastTree } from "./mdast/mdast-materializer.js";
+import { markHandleMutated } from "./lazy-child-resolver.js";
 import { HastReader } from "./hast/hast-reader.js";
 import { materializeHastTree } from "./hast/hast-materializer.js";
 /**
@@ -74,13 +75,21 @@ function featuresToNative(features) {
     }
     return { features: result, convertOptions };
 }
+/** Free a handle's arena. A plugin's visitor can hand child stubs to user code;
+ *  pass `invalidateStubs` so the epoch bump makes any stub retained past this
+ *  point hit the designed retention error instead of snapshotting the freed arena. */
+function releaseHandle(handle, invalidateStubs) {
+    if (invalidateStubs)
+        markHandleMutated(handle);
+    dropHandle(handle);
+}
 function warnDroppedTransforms(plugin, dropped, kind) {
     const name = plugin.name ?? "<anonymous>";
     const noun = dropped === 1 ? "transform" : "transforms";
     console.warn(`satteri: plugin "${name}" queued ${dropped} ${kind} ${noun} on node(s) that were removed or ` +
         `replaced earlier in the same pass; ${dropped === 1 ? "it was" : "they were"} dropped.`);
 }
-function runMdastPluginsOnHandle(handle, plugins, fileURL) {
+function runMdastPluginsOnHandle(handle, plugins, fileURL, data) {
     // Each plugin runs once over the tree. A transform that passes a child
     // through (returning it inside the replacement) keeps that child's identity,
     // so a patch the same pass queued on it still applies — nesting composes in
@@ -88,10 +97,11 @@ function runMdastPluginsOnHandle(handle, plugins, fileURL) {
     // them up front, or hand off to a later plugin that sees the materialized tree.
     const runPlugin = (plugin) => {
         const subs = resolveMdastSubscriptions(plugin);
-        const result = visitMdastHandle(handle, plugin, subs, () => getHandleSource(handle), fileURL);
+        const result = visitMdastHandle(handle, plugin, subs, () => getHandleSource(handle), fileURL, data);
         const apply = (r) => {
             if (!r.hasMutations)
                 return;
+            markHandleMutated(handle);
             const dropped = applyCommandsToMdastHandle(handle, r.commandBuffer);
             if (dropped)
                 warnDroppedTransforms(plugin, dropped, "mdast");
@@ -111,7 +121,7 @@ function runMdastPluginsOnHandle(handle, plugins, fileURL) {
     };
     return runNext();
 }
-function runHastPluginsOnHandle(handle, plugins, source, fileURL) {
+function runHastPluginsOnHandle(handle, plugins, source, fileURL, data) {
     if (plugins.length === 0)
         return;
     let i = 0;
@@ -121,7 +131,7 @@ function runHastPluginsOnHandle(handle, plugins, source, fileURL) {
             i++;
             const plugin = typeof raw === "function" ? raw() : raw;
             const subs = resolveSubscriptions(plugin);
-            const result = visitHastHandle(handle, plugin, subs, source, fileURL);
+            const result = visitHastHandle(handle, plugin, subs, source, fileURL, data);
             const warnIfDropped = (dropped) => {
                 if (dropped)
                     warnDroppedTransforms(plugin, dropped, "hast");
@@ -181,30 +191,31 @@ function mdxOptionsToNative(opts) {
     return result;
 }
 export function markdownToHtml(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], features, fileURL } = options;
+    const { mdastPlugins = [], hastPlugins = [], features, fileURL, data = {} } = options;
+    const hastMayHaveStubs = hastPlugins.length > 0;
     const { features: nativeFeatures, convertOptions: nativeConvertOptions } = featuresToNative(features);
-    const result = createHastHandleFromMdast(source, mdastPlugins, false, fileURL, nativeFeatures, nativeConvertOptions);
+    const result = createHastHandleFromMdast(source, mdastPlugins, false, fileURL, nativeFeatures, nativeConvertOptions, data);
     const renderAndDrop = (h, frontmatter) => {
         try {
             const html = renderHandle(h);
-            return { html, frontmatter };
+            return { html, frontmatter, data };
         }
         finally {
-            dropHandle(h);
+            releaseHandle(h, hastMayHaveStubs);
         }
     };
     const runHastThenRender = (r) => {
         let hastResult;
         try {
-            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL);
+            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL, data);
         }
         catch (err) {
-            dropHandle(r.hastHandle);
+            releaseHandle(r.hastHandle, hastMayHaveStubs);
             throw err;
         }
         if (hastResult instanceof Promise) {
             return hastResult.then(() => renderAndDrop(r.hastHandle, r.frontmatter), (err) => {
-                dropHandle(r.hastHandle);
+                releaseHandle(r.hastHandle, hastMayHaveStubs);
                 throw err;
             });
         }
@@ -215,31 +226,32 @@ export function markdownToHtml(source, options = {}) {
     return runHastThenRender(result);
 }
 export function mdxToJs(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], features, fileURL, ...mdxFields } = options;
+    const { mdastPlugins = [], hastPlugins = [], features, fileURL, data = {}, ...mdxFields } = options;
+    const hastMayHaveStubs = hastPlugins.length > 0;
     const mdxOptions = mdxOptionsToNative(mdxFields);
     const { features: nativeFeatures, convertOptions: nativeConvertOptions } = featuresToNative(features);
-    const result = createHastHandleFromMdast(source, mdastPlugins, true, fileURL, nativeFeatures, nativeConvertOptions);
+    const result = createHastHandleFromMdast(source, mdastPlugins, true, fileURL, nativeFeatures, nativeConvertOptions, data);
     const compileAndDrop = (h, frontmatter) => {
         try {
             const code = compileHandle(h, mdxOptions);
-            return { code, frontmatter };
+            return { code, frontmatter, data };
         }
         finally {
-            dropHandle(h);
+            releaseHandle(h, hastMayHaveStubs);
         }
     };
     const runHastThenCompile = (r) => {
         let hastResult;
         try {
-            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL);
+            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL, data);
         }
         catch (err) {
-            dropHandle(r.hastHandle);
+            releaseHandle(r.hastHandle, hastMayHaveStubs);
             throw err;
         }
         if (hastResult instanceof Promise) {
             return hastResult.then(() => compileAndDrop(r.hastHandle, r.frontmatter), (err) => {
-                dropHandle(r.hastHandle);
+                releaseHandle(r.hastHandle, hastMayHaveStubs);
                 throw err;
             });
         }
@@ -280,37 +292,41 @@ function createHastHandleFromMdast(source, mdastPlugins, mdx, fileURL,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 nativeFeatures, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-nativeConvertOptions) {
+nativeConvertOptions, data) {
     const mdastHandle = mdx
         ? createMdxMdastHandle(source, nativeFeatures)
         : createMdastHandle(source, nativeFeatures);
-    // finally{drop} is intentional: convertMdastToHastHandle empties the arena
+    const mdastMayHaveStubs = mdastPlugins.length > 0;
+    // finally{release} is intentional: convertMdastToHastHandle empties the arena
     // on success, but if any step here throws the handle would otherwise leak.
     const finalize = (r) => {
         try {
             const frontmatter = readFrontmatter(r.handle);
+            // convert empties the mdast arena, so invalidate any stub held past this point.
+            if (mdastMayHaveStubs)
+                markHandleMutated(r.handle);
             const hastHandle = convertMdastToHastHandle(r.handle, nativeConvertOptions);
             return { hastHandle, frontmatter };
         }
         finally {
-            dropHandle(r.handle);
+            releaseHandle(r.handle, mdastMayHaveStubs);
         }
     };
     try {
         if (mdastPlugins.length === 0) {
             return finalize({ handle: mdastHandle });
         }
-        const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, fileURL);
+        const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, fileURL, data);
         if (mdastResult instanceof Promise) {
             return mdastResult.then(finalize, (err) => {
-                dropHandle(mdastHandle);
+                releaseHandle(mdastHandle, mdastMayHaveStubs);
                 throw err;
             });
         }
         return finalize(mdastResult);
     }
     catch (err) {
-        dropHandle(mdastHandle);
+        releaseHandle(mdastHandle, mdastMayHaveStubs);
         throw err;
     }
 }
@@ -322,7 +338,7 @@ export function markdownToMdast(source, options = {}) {
         return materializeMdastTree(new MdastReader(serializeHandle(handle)));
     }
     finally {
-        dropHandle(handle);
+        releaseHandle(handle, true);
     }
 }
 /** Parse MDX source into a materialized mdast tree. */
@@ -332,7 +348,7 @@ export function mdxToMdast(source, options = {}) {
         return materializeMdastTree(new MdastReader(serializeHandle(handle)));
     }
     finally {
-        dropHandle(handle);
+        releaseHandle(handle, true);
     }
 }
 /** Convert Markdown source to a materialized hast tree. */
@@ -343,7 +359,7 @@ export function markdownToHast(source, options = {}) {
         return materializeHastTree(new HastReader(serializeHandle(handle)));
     }
     finally {
-        dropHandle(handle);
+        releaseHandle(handle, true);
     }
 }
 /** Convert MDX source to a materialized hast tree. */
@@ -354,6 +370,6 @@ export function mdxToHast(source, options = {}) {
         return materializeHastTree(new HastReader(serializeHandle(handle)));
     }
     finally {
-        dropHandle(handle);
+        releaseHandle(handle, true);
     }
 }

package/dist/directive-types.d.ts

@@ -1,5 +1,5 @@
 import type { BlockContent, Data as MdastData, DefinitionContent, Parent as MdastParent, PhrasingContent } from "mdast";
-export type DirectiveAttributes = Record<string, string>;
+export type DirectiveAttributes = Record<string, string | null | undefined>;
 export interface ContainerDirective extends MdastParent {
     type: "containerDirective";
     name: string;
@@ -8,7 +8,6 @@ export interface ContainerDirective extends MdastParent {
     data?: ContainerDirectiveData | undefined;
 }
 export interface ContainerDirectiveData extends MdastData {
-    directiveLabel?: boolean | undefined;
 }
 export interface LeafDirective extends MdastParent {
     type: "leafDirective";
@@ -33,6 +32,9 @@ declare module "mdast" {
         containerDirective: ContainerDirective;
         leafDirective: LeafDirective;
     }
+    interface ParagraphData {
+        directiveLabel?: boolean | null | undefined;
+    }
     interface PhrasingContentMap {
         textDirective: TextDirective;
     }

package/dist/generated/arena-layout.d.ts

@@ -0,0 +1,37 @@
+/** `b"MDAR"` magic, read as a little-endian u32. */
+export declare const ARENA_MAGIC = 1380009037;
+/** `Arena<K>` kind tags carried in the header's `kind` field. */
+export declare const KIND_MDAST = 1;
+export declare const KIND_HAST = 2;
+/** `ArenaNode` `#[repr(C)]` field byte offsets (u32 fields; `node_type` is a u8). */
+export declare const FIELD: {
+    readonly id: 0;
+    readonly node_type: 4;
+    readonly parent: 8;
+    readonly start_offset: 12;
+    readonly end_offset: 16;
+    readonly start_line: 20;
+    readonly start_column: 24;
+    readonly end_line: 28;
+    readonly end_column: 32;
+    readonly children_start: 36;
+    readonly children_count: 40;
+    readonly data_offset: 44;
+    readonly data_len: 48;
+};
+/** Raw-buffer header byte offsets (4-byte fields, u32 LE). */
+export declare const HEADER: {
+    readonly magic: 0;
+    readonly kind: 4;
+    readonly node_struct_size: 8;
+    readonly node_count: 12;
+    readonly nodes_offset: 16;
+    readonly children_count: 20;
+    readonly children_offset: 24;
+    readonly type_data_len: 28;
+    readonly type_data_offset: 32;
+    readonly source_len: 36;
+    readonly source_offset: 40;
+    readonly node_data_count: 44;
+    readonly node_data_offset: 48;
+};

package/dist/generated/arena-layout.js

@@ -0,0 +1,41 @@
+// @generated by `cargo run -p satteri-layout-codegen`. Do not edit by hand.
+// Arena raw-buffer layout, declared once in `satteri-layout-codegen/src/schema.rs`.
+// The Rust side is pinned to these offsets by the compile-time asserts in
+// `satteri-arena/src/generated/layout.rs`.
+/** `b"MDAR"` magic, read as a little-endian u32. */
+export const ARENA_MAGIC = 0x5241444d;
+/** `Arena<K>` kind tags carried in the header's `kind` field. */
+export const KIND_MDAST = 1;
+export const KIND_HAST = 2;
+/** `ArenaNode` `#[repr(C)]` field byte offsets (u32 fields; `node_type` is a u8). */
+export const FIELD = {
+    id: 0,
+    node_type: 4,
+    parent: 8,
+    start_offset: 12,
+    end_offset: 16,
+    start_line: 20,
+    start_column: 24,
+    end_line: 28,
+    end_column: 32,
+    children_start: 36,
+    children_count: 40,
+    data_offset: 44,
+    data_len: 48,
+};
+/** Raw-buffer header byte offsets (4-byte fields, u32 LE). */
+export const HEADER = {
+    magic: 0,
+    kind: 4,
+    node_struct_size: 8,
+    node_count: 12,
+    nodes_offset: 16,
+    children_count: 20,
+    children_offset: 24,
+    type_data_len: 28,
+    type_data_offset: 32,
+    source_len: 36,
+    source_offset: 40,
+    node_data_count: 44,
+    node_data_offset: 48,
+};

package/dist/generated/wire-constants.d.ts

@@ -0,0 +1,51 @@
+export declare const OP_OPEN = 1;
+export declare const OP_CLOSE = 2;
+export declare const OP_REF = 3;
+export declare const OP_KEEP_CHILDREN = 4;
+export declare const OP_STR = 5;
+export declare const OP_U8 = 6;
+export declare const OP_U32 = 7;
+export declare const OP_BOOL = 8;
+export declare const OP_DATA = 9;
+export declare const OP_PROP = 10;
+export declare const OP_ALIGN = 11;
+export declare const OF_VALUE = 0;
+export declare const OF_URL = 1;
+export declare const OF_TITLE = 2;
+export declare const OF_ALT = 3;
+export declare const OF_LANG = 4;
+export declare const OF_META = 5;
+export declare const OF_IDENTIFIER = 6;
+export declare const OF_LABEL = 7;
+export declare const OF_NAME = 8;
+export declare const OF_REFERENCE_TYPE = 9;
+export declare const OF_DEPTH = 10;
+export declare const OF_CHECKED = 11;
+export declare const OF_START = 12;
+export declare const OF_ORDERED = 13;
+export declare const OF_SPREAD = 14;
+export declare const OF_TAGNAME = 15;
+export declare const OF_EXPLICIT = 16;
+export declare const CMD_REMOVE = 1;
+export declare const CMD_INSERT_BEFORE = 5;
+export declare const CMD_INSERT_AFTER = 6;
+export declare const CMD_PREPEND_CHILD = 7;
+export declare const CMD_APPEND_CHILD = 8;
+export declare const CMD_WRAP = 9;
+export declare const CMD_REPLACE = 11;
+export declare const CMD_SET_PROPERTY = 12;
+export declare const CMD_SET_CHILDREN = 13;
+export declare const PAYLOAD_RAW_MARKDOWN = 16;
+export declare const PAYLOAD_RAW_HTML = 17;
+export declare const PAYLOAD_OPSTREAM = 20;
+export declare const PROP_STRING = 0;
+export declare const PROP_BOOL_TRUE = 1;
+export declare const PROP_BOOL_FALSE = 2;
+export declare const PROP_SPACE_SEP = 3;
+export declare const PROP_COMMA_SEP = 4;
+export declare const PROP_INT = 5;
+export declare const PROP_NULL = 6;
+export declare const MDX_ATTR_BOOLEAN_PROP = 0;
+export declare const MDX_ATTR_LITERAL_PROP = 1;
+export declare const MDX_ATTR_EXPRESSION_PROP = 2;
+export declare const MDX_ATTR_SPREAD = 3;

package/dist/generated/wire-constants.js

@@ -0,0 +1,63 @@
+// @generated by `cargo run -p satteri-layout-codegen`. Do not edit by hand.
+// JS<->Rust wire-protocol byte values, declared once in
+// `satteri-layout-codegen/src/schema.rs`. Rust twins live in
+// `satteri-plugin-api/src/generated/wire_constants.rs` and
+// `satteri-ast/src/generated/wire_constants.rs`.
+// Op-stream op codes (JS `OpWriter` -> Rust `replay_opstream`).
+export const OP_OPEN = 0x01; // [type: u8]
+export const OP_CLOSE = 0x02;
+export const OP_REF = 0x03; // [id: u32 LE] — splice an existing node
+export const OP_KEEP_CHILDREN = 0x04; // splice the anchor node's original children
+export const OP_STR = 0x05; // [field: u8][len: u32 LE][utf8]
+export const OP_U8 = 0x06; // [field: u8][value: u8]
+export const OP_U32 = 0x07; // [field: u8][value: u32 LE]
+export const OP_BOOL = 0x08; // [field: u8][0|1]
+export const OP_DATA = 0x09; // [len: u32 LE][json utf8]
+export const OP_PROP = 0x0a; // [name str][kind: u8][value str] — HAST element property
+export const OP_ALIGN = 0x0b; // [len: u32 LE][ColumnAlign bytes] — table column alignment
+// Op-stream field ids (single namespace across OP_STR/OP_U8/OP_U32/OP_BOOL).
+export const OF_VALUE = 0;
+export const OF_URL = 1;
+export const OF_TITLE = 2;
+export const OF_ALT = 3;
+export const OF_LANG = 4;
+export const OF_META = 5;
+export const OF_IDENTIFIER = 6;
+export const OF_LABEL = 7;
+export const OF_NAME = 8; // directive / MDX JSX element name
+export const OF_REFERENCE_TYPE = 9;
+export const OF_DEPTH = 10;
+export const OF_CHECKED = 11;
+export const OF_START = 12;
+export const OF_ORDERED = 13;
+export const OF_SPREAD = 14;
+export const OF_TAGNAME = 15; // HAST element tag name
+export const OF_EXPLICIT = 16; // MDX JSX `_mdxExplicitJsx` flag
+// Command bytes (0x01–0x0F range). Each is followed by [nodeId: u32 LE];
+// structural commands then carry [payloadType: u8][payload…].
+export const CMD_REMOVE = 0x01;
+export const CMD_INSERT_BEFORE = 0x05;
+export const CMD_INSERT_AFTER = 0x06;
+export const CMD_PREPEND_CHILD = 0x07;
+export const CMD_APPEND_CHILD = 0x08;
+export const CMD_WRAP = 0x09;
+export const CMD_REPLACE = 0x0b;
+export const CMD_SET_PROPERTY = 0x0c; // [valueType: u8][name str][value str], PROP_* value kinds
+export const CMD_SET_CHILDREN = 0x0d; // payload is a Root-wrapped child list
+// Structural-command payload types (0x10+, a range distinct from commands).
+export const PAYLOAD_RAW_MARKDOWN = 0x10; // [len: u32 LE][utf8] — re-parsed as markdown
+export const PAYLOAD_RAW_HTML = 0x11; // [len: u32 LE][utf8] — re-parsed as HTML/MDX
+export const PAYLOAD_OPSTREAM = 0x14; // [len: u32 LE][op bytes] — replayed straight into the arena
+// Property value kinds (HAST element properties and SET_PROPERTY commands).
+export const PROP_STRING = 0; // UTF-8 value
+export const PROP_BOOL_TRUE = 1; // no value bytes
+export const PROP_BOOL_FALSE = 2; // no value bytes
+export const PROP_SPACE_SEP = 3; // space-separated list (UTF-8)
+export const PROP_COMMA_SEP = 4; // comma-separated list (UTF-8)
+export const PROP_INT = 5; // decimal string, parsed to i64
+export const PROP_NULL = 6; // no value bytes
+// MDX JSX attribute kinds (MDAST and HAST MDX JSX element type_data).
+export const MDX_ATTR_BOOLEAN_PROP = 0; // name only, no value
+export const MDX_ATTR_LITERAL_PROP = 1; // name="literal"
+export const MDX_ATTR_EXPRESSION_PROP = 2; // name={expr}
+export const MDX_ATTR_SPREAD = 3; // {...expr}

package/dist/handles.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Opaque handles to Rust-owned arenas. The napi-generated `index.d.ts` refers
+ * to `MdastHandle`/`HastHandle`/`AnyHandle` as bare, undeclared names; these
+ * global declarations give those signatures real types. The kind brand makes
+ * passing a hast handle to an mdast entry point (a runtime error in Rust) a
+ * compile error in TS.
+ */
+declare global {
+    interface MdastHandle {
+        readonly __satteriHandleKind: "mdast";
+    }
+    interface HastHandle {
+        readonly __satteriHandleKind: "hast";
+    }
+    /** Handle accepted by kind-agnostic entry points (drop, serialize, …). */
+    type AnyHandle = MdastHandle | HastHandle;
+}
+type MdastHandleAlias = MdastHandle;
+type HastHandleAlias = HastHandle;
+type AnyHandleAlias = AnyHandle;
+export type { MdastHandleAlias as MdastHandle, HastHandleAlias as HastHandle, AnyHandleAlias as AnyHandle, };

package/dist/handles.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,18 @@
+import type { LazyChildResolver } from "../lazy-child-resolver.js";
+import type { HastNode } from "../types.js";
+import type { HastReader } from "./hast-reader.js";
+type HastResolver = LazyChildResolver<HastReader, HastNode>;
+/**
+ * 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()`
+ * in hast-visitor.ts.
+ */
+export declare class HastChildStub {
+    _resolver: HastResolver;
+    _id: number;
+    type: string;
+    constructor(resolver: HastResolver, id: number, nodeType: number);
+}
+export {};

package/dist/hast/child-stub.js

@@ -0,0 +1,43 @@
+import { flatByTag, stubDescriptors } from "../child-stub.js";
+import { NAME_TO_TYPE, TYPE_NAMES } from "./generated/node-types.js";
+const N = NAME_TO_TYPE;
+/** Per-type stub fields, mirroring `materializeHastNode`'s switch. */
+const HAST_STUB_FIELDS = {
+    [N.root]: ["children"],
+    [N.element]: ["tagName", "properties", "children"],
+    [N.text]: ["value"],
+    [N.comment]: ["value"],
+    [N.doctype]: [],
+    [N.raw]: ["value"],
+    [N.mdxJsxFlowElement]: ["name", "attributes", "children"],
+    [N.mdxJsxTextElement]: ["name", "attributes", "children"],
+    [N.mdxFlowExpression]: ["value"],
+    [N.mdxTextExpression]: ["value"],
+    [N.mdxjsEsm]: ["value"],
+};
+const TYPE_NAME_BY_TAG = flatByTag(TYPE_NAMES);
+const HAST_STUB_DESCRIPTORS = [];
+for (const tag of Object.keys(HAST_STUB_FIELDS)) {
+    const nodeType = Number(tag);
+    HAST_STUB_DESCRIPTORS[nodeType] = stubDescriptors(HAST_STUB_FIELDS[nodeType]);
+}
+/** 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()`
+ * in hast-visitor.ts.
+ */
+export class HastChildStub {
+    _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, HAST_STUB_DESCRIPTORS[nodeType] ?? FALLBACK_DESCRIPTORS);
+    }
+}

package/dist/hast/element-props.d.ts

@@ -0,0 +1,2 @@
+export type HastPropertyValue = string | number | boolean | string[];
+export declare function decodeElementProp(kind: number, value: string): HastPropertyValue;

package/dist/hast/element-props.js

@@ -0,0 +1,23 @@
+/** Decode a HAST element property value from its wire `(kind, value)` — shared
+ *  by the walk decoder and the snapshot reader so the kind dispatch lives once.
+ *  The bool kinds carry no value string (callers pass `""`). */
+import { PROP_BOOL_TRUE, PROP_BOOL_FALSE, PROP_SPACE_SEP, PROP_COMMA_SEP, PROP_INT, } from "../generated/wire-constants.js";
+export function decodeElementProp(kind, value) {
+    switch (kind) {
+        case PROP_BOOL_TRUE:
+            return true;
+        case PROP_BOOL_FALSE:
+            return false;
+        case PROP_SPACE_SEP:
+            return value.split(" ").filter((s) => s.length > 0);
+        case PROP_COMMA_SEP:
+            return value
+                .split(",")
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+        case PROP_INT:
+            return Number(value);
+        default:
+            return value; // PROP_STRING
+    }
+}

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

@@ -0,0 +1,14 @@
+/** 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>>;
+/** 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 HAST_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 HAST_CUSTOM_TYPES: readonly string[];