satteri 0.8.0 → 0.9.0

package/dist/hast/hast-materializer.js

@@ -1,5 +1,7 @@
 import { HastReader, HAST_ROOT, HAST_ELEMENT, HAST_TEXT, HAST_COMMENT, HAST_DOCTYPE, HAST_RAW, HAST_MDX_JSX_ELEMENT, HAST_MDX_JSX_TEXT_ELEMENT, HAST_MDX_FLOW_EXPRESSION, HAST_MDX_TEXT_EXPRESSION, HAST_MDX_ESM, } from "./hast-reader.js";
+import { TYPE_NAMES } from "./generated/node-types.js";
 import { lazyProp, lazyGroup } from "../lazy-props.js";
+import { restorePhantomSpaces } from "../phantom.js";
 function propsToRecord(props) {
     const result = {};
     for (const p of props) {
@@ -12,47 +14,13 @@ function propsToRecord(props) {
  */
 export function materializeHastNode(reader, nodeId) {
     const nodeType = reader.getNodeType(nodeId);
-    let typeName;
-    switch (nodeType) {
-        case HAST_ROOT:
-            typeName = "root";
-            break;
-        case HAST_ELEMENT:
-            typeName = "element";
-            break;
-        case HAST_TEXT:
-            typeName = "text";
-            break;
-        case HAST_COMMENT:
-            typeName = "comment";
-            break;
-        case HAST_DOCTYPE:
-            typeName = "doctype";
-            break;
-        case HAST_RAW:
-            typeName = "raw";
-            break;
-        case HAST_MDX_JSX_ELEMENT:
-            typeName = "mdxJsxFlowElement";
-            break;
-        case HAST_MDX_JSX_TEXT_ELEMENT:
-            typeName = "mdxJsxTextElement";
-            break;
-        case HAST_MDX_FLOW_EXPRESSION:
-            typeName = "mdxFlowExpression";
-            break;
-        case HAST_MDX_TEXT_EXPRESSION:
-            typeName = "mdxTextExpression";
-            break;
-        case HAST_MDX_ESM:
-            typeName = "mdxjsEsm";
-            break;
-        default:
-            typeName = `unknown(${nodeType})`;
-            break;
+    const typeName = TYPE_NAMES[nodeType] ?? `unknown(${nodeType})`;
+    const node = { type: typeName };
+    // Position decodes to three objects; defer it — passthrough children (e.g.
+    // replaceNode keeping `node.children`) never read it.
+    if (reader.hasPosition(nodeId)) {
+        Object.defineProperty(node, "position", lazyProp("position", () => reader.getPosition(nodeId)));
     }
-    const position = reader.getPosition(nodeId);
-    const node = (position ? { type: typeName, position } : { type: typeName });
     // _nodeId: non-enumerable internal reference
     Object.defineProperty(node, "_nodeId", {
         value: nodeId,
@@ -135,11 +103,7 @@ export function materializeHastNode(reader, nodeId) {
         case HAST_MDX_FLOW_EXPRESSION:
         case HAST_MDX_TEXT_EXPRESSION:
             Object.defineProperties(node, {
-                // Substitute U+F002 phantom-space sentinels (see PHANTOM_SPACE in
-                // satteri-pulldown-cmark/src/mdx.rs) back to regular spaces — mdast
-                // and hast keep phantoms in the value field; only the compile path
-                // drops them.
-                value: lazyProp("value", () => reader.getTextValue(nodeId).replaceAll("", " ")),
+                value: lazyProp("value", () => restorePhantomSpaces(reader.getTextValue(nodeId))),
             });
             break;
         case HAST_MDX_ESM:

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

@@ -1,17 +1,18 @@
 import type { BufferHeader } from "../types.js";
 import type { MdxJsxAttribute, MdxJsxExpressionAttribute } from "../mdx-types.js";
+import type { Position } from "unist";
 export type { MdxJsxAttribute, MdxJsxExpressionAttribute };
-export declare const HAST_ROOT = 0;
-export declare const HAST_ELEMENT = 1;
-export declare const HAST_TEXT = 2;
-export declare const HAST_COMMENT = 3;
-export declare const HAST_DOCTYPE = 4;
-export declare const HAST_RAW = 5;
-export declare const HAST_MDX_JSX_ELEMENT = 10;
-export declare const HAST_MDX_JSX_TEXT_ELEMENT = 11;
-export declare const HAST_MDX_FLOW_EXPRESSION = 12;
-export declare const HAST_MDX_ESM = 13;
-export declare const HAST_MDX_TEXT_EXPRESSION = 14;
+export declare const HAST_ROOT: number;
+export declare const HAST_ELEMENT: number;
+export declare const HAST_TEXT: number;
+export declare const HAST_COMMENT: number;
+export declare const HAST_DOCTYPE: number;
+export declare const HAST_RAW: number;
+export declare const HAST_MDX_JSX_ELEMENT: number;
+export declare const HAST_MDX_JSX_TEXT_ELEMENT: number;
+export declare const HAST_MDX_FLOW_EXPRESSION: number;
+export declare const HAST_MDX_ESM: number;
+export declare const HAST_MDX_TEXT_EXPRESSION: number;
 export interface HastProperty {
     name: string;
     value: string | number | boolean | string[];
@@ -33,20 +34,14 @@ export declare class HastReader {
     /** Read a substring from the string pool by byte offset and length. */
     getString(offset: number, len: number): string;
     /** Get position data for a node. */
-    getPosition(nodeId: number): {
-        start: {
-            offset: number;
-            line: number;
-            column: number;
-        };
-        end: {
-            offset: number;
-            line: number;
-            column: number;
-        };
-    } | undefined;
+    getPosition(nodeId: number): Position | undefined;
+    /** Whether the node carries a source position (line 0 + offset 0 is the
+     *  synthesized-node sentinel), without decoding the three position objects. */
+    hasPosition(nodeId: number): boolean;
     /** Get the node_type byte for a given node ID. */
     getNodeType(nodeId: number): number;
+    /** Get the parent id for a given node (0xffffffff at the root). */
+    getParentId(nodeId: number): number;
     /** Get child node IDs for a given node. */
     getChildIds(nodeId: number): number[];
     /** Push child node IDs directly onto a stack array (reverse order for depth-first). */

package/dist/hast/hast-reader.js

@@ -1,53 +1,20 @@
-// HAST node type constants (must match node_types.rs)
-export const HAST_ROOT = 0;
-export const HAST_ELEMENT = 1;
-export const HAST_TEXT = 2;
-export const HAST_COMMENT = 3;
-export const HAST_DOCTYPE = 4;
-export const HAST_RAW = 5;
-// MDX-specific HAST node types
-export const HAST_MDX_JSX_ELEMENT = 10;
-export const HAST_MDX_JSX_TEXT_ELEMENT = 11;
-export const HAST_MDX_FLOW_EXPRESSION = 12;
-export const HAST_MDX_ESM = 13;
-export const HAST_MDX_TEXT_EXPRESSION = 14;
-const PROP_STRING = 0;
-const PROP_BOOL_TRUE = 1;
-const PROP_BOOL_FALSE = 2;
-const PROP_SPACE_SEP = 3;
-const PROP_COMMA_SEP = 4;
-// MDX JSX attribute kinds (must match node_types.rs)
-const MDX_ATTR_BOOLEAN_PROP = 0;
-const MDX_ATTR_LITERAL_PROP = 1;
-const MDX_ATTR_EXPRESSION_PROP = 2;
-const MDX_ATTR_SPREAD = 3;
-// HastNode field offsets (same layout as MDAST, shared binary format)
-//   id: u32          @ 0
-//   node_type: u8    @ 4
-//   _pad: [u8; 3]    @ 5
-//   parent: u32      @ 8
-//   ...
-//   children_start: u32 @ 36
-//   children_count: u32 @ 40
-//   data_offset: u32 @ 44
-//   data_len: u32    @ 48
-//   Total: 52 bytes
-const FIELD = {
-    node_type: 4,
-    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,
-};
-// "MDAR" bytes: 4d 44 41 52; read as LE u32 = 0x5241444d
-const MAGIC = 0x5241444d;
-const KIND_HAST = 2;
+import { restorePhantomSpaces } from "../phantom.js";
+import { readPosition } from "../wire-read.js";
+import { MDX_ATTR_BOOLEAN_PROP, MDX_ATTR_LITERAL_PROP, MDX_ATTR_EXPRESSION_PROP, MDX_ATTR_SPREAD, } from "../op-stream.js";
+import { decodeElementProp } from "./element-props.js";
+import { NAME_TO_TYPE } from "./generated/node-types.js";
+import { ARENA_MAGIC, KIND_HAST, FIELD, HEADER } from "../generated/arena-layout.js";
+export const HAST_ROOT = NAME_TO_TYPE.root;
+export const HAST_ELEMENT = NAME_TO_TYPE.element;
+export const HAST_TEXT = NAME_TO_TYPE.text;
+export const HAST_COMMENT = NAME_TO_TYPE.comment;
+export const HAST_DOCTYPE = NAME_TO_TYPE.doctype;
+export const HAST_RAW = NAME_TO_TYPE.raw;
+export const HAST_MDX_JSX_ELEMENT = NAME_TO_TYPE.mdxJsxFlowElement;
+export const HAST_MDX_JSX_TEXT_ELEMENT = NAME_TO_TYPE.mdxJsxTextElement;
+export const HAST_MDX_FLOW_EXPRESSION = NAME_TO_TYPE.mdxFlowExpression;
+export const HAST_MDX_ESM = NAME_TO_TYPE.mdxjsEsm;
+export const HAST_MDX_TEXT_EXPRESSION = NAME_TO_TYPE.mdxTextExpression;
 export class HastReader {
     #view;
     #header;
@@ -65,27 +32,27 @@ export class HastReader {
     }
     #readHeader() {
         const v = this.#view;
-        const magic = v.getUint32(0, true);
-        if (magic !== MAGIC) {
+        const magic = v.getUint32(HEADER.magic, true);
+        if (magic !== ARENA_MAGIC) {
             throw new Error(`Invalid HAST buffer: bad magic 0x${magic.toString(16)}`);
         }
-        const kind = v.getUint32(4, true);
+        const kind = v.getUint32(HEADER.kind, true);
         if (kind !== KIND_HAST) {
             throw new Error(`HastReader was handed a buffer of kind ${kind} (expected ${KIND_HAST}). ` +
                 `MDAST and HAST node types overlap; reading the wrong kind decodes garbage.`);
         }
         return {
-            nodeStructSize: v.getUint32(8, true),
-            nodeCount: v.getUint32(12, true),
-            nodesOffset: v.getUint32(16, true),
-            childrenCount: v.getUint32(20, true),
-            childrenOffset: v.getUint32(24, true),
-            typeDataLen: v.getUint32(28, true),
-            typeDataOffset: v.getUint32(32, true),
-            sourceLen: v.getUint32(36, true),
-            sourceOffset: v.getUint32(40, true),
-            nodeDataCount: v.getUint32(44, true),
-            nodeDataOffset: v.getUint32(48, true),
+            nodeStructSize: v.getUint32(HEADER.node_struct_size, true),
+            nodeCount: v.getUint32(HEADER.node_count, true),
+            nodesOffset: v.getUint32(HEADER.nodes_offset, true),
+            childrenCount: v.getUint32(HEADER.children_count, true),
+            childrenOffset: v.getUint32(HEADER.children_offset, true),
+            typeDataLen: v.getUint32(HEADER.type_data_len, true),
+            typeDataOffset: v.getUint32(HEADER.type_data_offset, true),
+            sourceLen: v.getUint32(HEADER.source_len, true),
+            sourceOffset: v.getUint32(HEADER.source_offset, true),
+            nodeDataCount: v.getUint32(HEADER.node_data_count, true),
+            nodeDataOffset: v.getUint32(HEADER.node_data_offset, true),
         };
     }
     #nodeDataTable = null;
@@ -139,30 +106,27 @@ export class HastReader {
     }
     /** Get position data for a node. */
     getPosition(nodeId) {
+        const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
+        return readPosition(this.#view, base + FIELD.start_offset);
+    }
+    /** Whether the node carries a source position (line 0 + offset 0 is the
+     *  synthesized-node sentinel), without decoding the three position objects. */
+    hasPosition(nodeId) {
         const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
         const v = this.#view;
-        const startLine = v.getUint32(base + FIELD.start_line, true);
-        const startOffset = v.getUint32(base + FIELD.start_offset, true);
-        if (startLine === 0 && startOffset === 0)
-            return undefined;
-        return {
-            start: {
-                offset: startOffset,
-                line: startLine,
-                column: v.getUint32(base + FIELD.start_column, true),
-            },
-            end: {
-                offset: v.getUint32(base + FIELD.end_offset, true),
-                line: v.getUint32(base + FIELD.end_line, true),
-                column: v.getUint32(base + FIELD.end_column, true),
-            },
-        };
+        return (v.getUint32(base + FIELD.start_line, true) !== 0 ||
+            v.getUint32(base + FIELD.start_offset, true) !== 0);
     }
     /** Get the node_type byte for a given node ID. */
     getNodeType(nodeId) {
         const { nodesOffset, nodeStructSize } = this.#header;
         return this.#view.getUint8(nodesOffset + nodeId * nodeStructSize + FIELD.node_type);
     }
+    /** Get the parent id for a given node (0xffffffff at the root). */
+    getParentId(nodeId) {
+        const { nodesOffset, nodeStructSize } = this.#header;
+        return this.#view.getUint32(nodesOffset + nodeId * nodeStructSize + FIELD.parent, true);
+    }
     /** Get child node IDs for a given node. */
     getChildIds(nodeId) {
         const base = this.#header.nodesOffset + nodeId * this.#header.nodeStructSize;
@@ -233,39 +197,8 @@ export class HastReader {
             const name = this.getString(nameRef.offset, nameRef.len);
             const valueType = data[base + 8];
             const valueRef = this.#readStringRef(data, base + 12);
-            switch (valueType) {
-                case PROP_BOOL_TRUE:
-                    properties.push({ name, value: true });
-                    break;
-                case PROP_BOOL_FALSE:
-                    properties.push({ name, value: false });
-                    break;
-                case PROP_STRING:
-                    properties.push({ name, value: this.getString(valueRef.offset, valueRef.len) });
-                    break;
-                case PROP_SPACE_SEP: {
-                    const raw = this.getString(valueRef.offset, valueRef.len);
-                    properties.push({ name, value: raw.split(" ").filter((s) => s.length > 0) });
-                    break;
-                }
-                case PROP_COMMA_SEP: {
-                    const raw = this.getString(valueRef.offset, valueRef.len);
-                    properties.push({
-                        name,
-                        value: raw
-                            .split(",")
-                            .map((s) => s.trim())
-                            .filter((s) => s.length > 0),
-                    });
-                    break;
-                }
-                case 5: {
-                    // PROP_INT
-                    const raw = this.getString(valueRef.offset, valueRef.len);
-                    properties.push({ name, value: Number(raw) });
-                    break;
-                }
-            }
+            const valueStr = this.getString(valueRef.offset, valueRef.len);
+            properties.push({ name, value: decodeElementProp(valueType, valueStr) });
         }
         return { tagName, properties };
     }
@@ -313,14 +246,14 @@ export class HastReader {
                         name: this.getString(attrNameRef.offset, attrNameRef.len),
                         value: {
                             type: "mdxJsxAttributeValueExpression",
-                            value: this.getString(attrValueRef.offset, attrValueRef.len).replaceAll("", " "),
+                            value: restorePhantomSpaces(this.getString(attrValueRef.offset, attrValueRef.len)),
                         },
                     });
                     break;
                 case MDX_ATTR_SPREAD:
                     attributes.push({
                         type: "mdxJsxExpressionAttribute",
-                        value: this.getString(attrValueRef.offset, attrValueRef.len).replaceAll("", " "),
+                        value: restorePhantomSpaces(this.getString(attrValueRef.offset, attrValueRef.len)),
                     });
                     break;
             }

package/dist/hast/hast-visitor.d.ts

@@ -1,11 +1,12 @@
 import { type HastNode } from "./hast-materializer.js";
-import type { HastRaw } from "../types.js";
-import type { Element, Text, Comment, Doctype } from "hast";
+import type { HastRaw, Data } from "../types.js";
+import type { Element, Text, Comment, Doctype, Parents as HastParents, Root as HastRoot } from "hast";
 import type { Program } from "estree-jsx";
 import type { MdxJsxFlowElementHast, MdxJsxTextElementHast } from "../mdx-types.js";
 import type { MdxFlowExpressionHast, MdxTextExpressionHast } from "../mdx-types.js";
 import type { MdxjsEsmHast } from "../mdx-types.js";
-export type HastHandle = any;
+import type { HastHandle } from "../handles.js";
+export type { HastHandle };
 /** ESTree-compatible Program node returned by `parseExpression()`. */
 export type EstreeProgram = Program;
 export interface HastDiagnostic {
@@ -21,21 +22,45 @@ export interface HastVisitorContext {
      * decoded filesystem path.
      */
     readonly fileURL: URL | undefined;
+    /**
+     * Document-level data bag, shared across every plugin in the compile and
+     * across the mdast→hast phase boundary. Mutate keys directly
+     * (`ctx.data.foo = x`); the bag itself isn't reassignable. Values are kept
+     * on the JS side, so any value is allowed, including functions and class
+     * instances. Returned to the caller as `result.data`.
+     */
+    readonly data: Data;
     removeNode(node: Readonly<HastNode>): void;
-    replaceNode(node: Readonly<HastNode>, newNode: HastNode): void;
-    insertBefore(node: Readonly<HastNode>, newNode: HastNode): void;
-    insertAfter(node: Readonly<HastNode>, newNode: HastNode): void;
+    replaceNode(node: Readonly<HastNode>, newNode: HastContent): void;
+    insertBefore(node: Readonly<HastNode>, newNode: HastContent | HastContent[]): void;
+    insertAfter(node: Readonly<HastNode>, newNode: HastContent | HastContent[]): void;
     /**
      * Wrap `node` in `parentNode`, making it `parentNode`'s first child. Any
      * children `parentNode` declares are kept after it, so a `div` with an anchor
      * child wraps a heading as `div > [heading, anchor]`.
      */
-    wrapNode(node: Readonly<HastNode>, parentNode: HastNode): void;
-    prependChild(node: Readonly<HastNode>, childNode: HastNode): void;
-    appendChild(node: Readonly<HastNode>, childNode: HastNode): void;
+    wrapNode(node: Readonly<HastNode>, parentNode: HastContent): void;
+    prependChild(node: Readonly<HastNode>, childNode: HastContent | HastContent[]): void;
+    appendChild(node: Readonly<HastNode>, childNode: HastContent | HastContent[]): void;
+    /** Insert one node or an array at `index`; clamps (`0` or less prepends, past the end appends). */
+    insertChildAt(node: Readonly<HastNode>, index: number, childNode: HastContent | HastContent[]): void;
+    /** Remove the `index`-th child of `node`; a no-op when there is no such child. */
+    removeChildAt(node: Readonly<HastNode>, index: number): void;
     setProperty(node: Readonly<HastNode>, key: string, value: unknown): void;
     /** Collect the concatenated text of all descendant text nodes (like DOM textContent). */
     textContent(node: Readonly<HastNode>): string;
+    /**
+     * The parent of a node, or `undefined` at the root. Within a pass the same
+     * parent is always the same object, so visitors on sibling nodes can dedupe
+     * by identity.
+     */
+    parent<N extends Exclude<HastNode, HastRoot>>(node: Readonly<N>): Readonly<HastParents>;
+    parent(node: Readonly<HastNode>): Readonly<HastParents> | undefined;
+    /**
+     * Index of `node` within its parent's children, or `undefined` at the root.
+     * Use this rather than `parent.children.indexOf(node)`, which won't find it.
+     */
+    indexOf(node: Readonly<HastNode>): number | undefined;
     report(opts: {
         message: string;
         node?: Readonly<HastNode>;
@@ -43,6 +68,9 @@ export interface HastVisitorContext {
     }): void;
     getDiagnostics(): HastDiagnostic[];
 }
+/** New content for a HAST structural mutation. Unlike [`MdastContent`], HAST has
+ *  a `raw` node type, so it needs no raw/rawHtml escape hatch. */
+export type HastContent = HastNode;
 /** A filtered visitor: Rust filters by tag/component name, only matched nodes cross the boundary. */
 export interface HastFilteredVisitor<N extends HastNode = HastNode> {
     filter: string[];
@@ -72,7 +100,6 @@ interface ResolvedSubscription {
     tagFilter: string[];
     visitFn: (node: HastNode, ctx: HastVisitorContext) => HastNode | void;
 }
-/** Resolve subscriptions from a plugin instance. */
 export declare function resolveSubscriptions(plugin: HastVisitorInstance): ResolvedSubscription[];
 /**
  * Walk a handle's arena in Rust, dispatch matched nodes to JS visitor functions,
@@ -82,5 +109,4 @@ export declare function resolveSubscriptions(plugin: HastVisitorInstance): Resol
  * replaced earlier in the same pass (the caller warns when non-zero), or a
  * Promise of that count if any visitor is async.
  */
-export declare function visitHastHandle(handle: HastHandle, plugin: HastVisitorInstance, subs: ResolvedSubscription[], source: string | (() => string), fileURL: URL | undefined): number | Promise<number>;
-export {};
+export declare function visitHastHandle(handle: HastHandle, plugin: HastVisitorInstance, subs: ResolvedSubscription[], source: string | (() => string), fileURL: URL | undefined, data?: Data): number | Promise<number>;