satteri 0.6.3 → 0.8.0

package/dist/hast/hast-visitor.js

@@ -21,24 +21,37 @@ function attachParseExpression(node, parseFn) {
         configurable: true,
     });
 }
-/** Inject `_hast: true` marker on a HastNode and all its children for JSON serialization. */
+/**
+ * Serialize a HastNode for the command buffer. Marks each node `_hast: true`,
+ * and — except at the root, which is the new replacement content — emits a
+ * reused (materialized) node as a `{ _ref: id }` placeholder so the rebuild
+ * splices the original in place (preserving its id, applying any pending patch
+ * on it) instead of rebuilding it fresh.
+ */
 function markHast(node) {
-    const n = node;
+    return markHastNode(node, true);
+}
+function markHastNode(node, isRoot) {
+    if (!isRoot) {
+        const id = nodeIdMap.get(node) ?? node._nodeId;
+        if (typeof id === "number")
+            return { _ref: id };
+    }
     const obj = { _hast: true, type: node.type };
     if ("tagName" in node)
-        obj.tagName = n.tagName;
+        obj.tagName = node.tagName;
     if ("properties" in node)
-        obj.properties = n.properties;
+        obj.properties = node.properties;
     if ("value" in node)
-        obj.value = n.value;
+        obj.value = node.value;
     if ("name" in node)
-        obj.name = n.name;
+        obj.name = node.name;
     if ("attributes" in node)
-        obj.attributes = n.attributes;
-    if ("data" in node && n.data != null)
-        obj.data = n.data;
+        obj.attributes = node.attributes;
+    if ("data" in node && node.data != null)
+        obj.data = node.data;
     if ("children" in node) {
-        obj.children = n.children.map(markHast);
+        obj.children = node.children.map((c) => markHastNode(c, false));
     }
     return obj;
 }
@@ -52,11 +65,11 @@ class HastVisitorContextImpl {
     #pendingNodes = new Map();
     #handle;
     #getSource;
-    filename;
-    constructor(handle, getSource, filename) {
+    fileURL;
+    constructor(handle, getSource, fileURL) {
         this.#handle = handle;
         this.#getSource = getSource;
-        this.filename = filename;
+        this.fileURL = fileURL;
     }
     get source() {
         const value = this.#getSource();
@@ -99,7 +112,8 @@ class HastVisitorContextImpl {
         }
         if (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") {
             // MDX JSX nodes use `attributes`, not `properties`, keep replaceNode path
-            const current = this.#pendingNodes.get(id) ?? node;
+            const pending = this.#pendingNodes.get(id);
+            const current = (pending ?? node);
             const updated = { ...current };
             const attrs = [...(updated.attributes ?? [])];
             const idx = attrs.findIndex((a) => a.type === "mdxJsxAttribute" && a.name === key);
@@ -109,7 +123,7 @@ class HastVisitorContextImpl {
                 ? null
                 : typeof value === "string"
                     ? value
-                    : `${value}`;
+                    : String(value);
             attrs.push({ type: "mdxJsxAttribute", name: key, value: attrValue });
             updated.attributes = attrs;
             this.replaceNode(node, updated);
@@ -213,6 +227,21 @@ function decodeProperties(view, buf, pos) {
     }
     return properties;
 }
+/** Decode the 24-byte position block written by `serialize_hast_node_inline`. */
+function readPositionPrefix(view, offset) {
+    const startOffset = view.getUint32(offset, true);
+    const endOffset = view.getUint32(offset + 4, true);
+    const startLine = view.getUint32(offset + 8, true);
+    const startColumn = view.getUint32(offset + 12, true);
+    const endLine = view.getUint32(offset + 16, true);
+    const endColumn = view.getUint32(offset + 20, true);
+    if (startLine === 0 && startOffset === 0)
+        return undefined;
+    return {
+        start: { offset: startOffset, line: startLine, column: startColumn },
+        end: { offset: endOffset, line: endLine, column: endColumn },
+    };
+}
 /**
  * Walk-path element node: uses prototype getters instead of per-instance
  * Object.defineProperty. V8 optimises shared hidden classes far better,
@@ -228,8 +257,6 @@ class WalkElement {
     /** @internal */ _propsPos;
     /** @internal */ _childIds;
     /** @internal */ _resolver;
-    /** @internal */ _dataPos;
-    /** @internal */ _dataLen;
     get properties() {
         const val = decodeProperties(this._view, this._buf, this._propsPos);
         Object.defineProperty(this, "properties", {
@@ -250,59 +277,29 @@ class WalkElement {
         });
         return val;
     }
-    get data() {
-        if (this._dataPos < 0)
-            return undefined;
-        const val = JSON.parse(textDecoder.decode(this._buf.subarray(this._dataPos, this._dataPos + this._dataLen)));
-        Object.defineProperty(this, "data", {
-            value: val,
-            writable: true,
-            enumerable: true,
-            configurable: true,
-        });
-        return val;
-    }
 }
-/** Read a matched element node from the binary data section into a HastNode.
- *  Only tagName is decoded eagerly; properties, children, and data are lazy. */
-function readElementFromBinary(view, buf, offset, nodeId, resolver) {
+/** Read the tail of a matched element node (tag + properties).
+ *  Common prelude (data/position/children) is already consumed by `readMatchedNode`. */
+function readElementFromBinary(view, buf, offset, nodeId, resolver, position, childIds, data) {
     let pos = offset;
     // Eager: tagName (almost always accessed by visitors)
     const tagLen = view.getUint16(pos, true);
     pos += 2;
     const tagName = textDecoder.decode(buf.subarray(pos, pos + tagLen));
     pos += tagLen;
-    // Pre-scan: find section byte offsets without decoding strings
     const propsPos = pos;
-    const propCount = view.getUint16(pos, true);
-    pos += 2;
-    for (let i = 0; i < propCount; i++) {
-        const nLen = view.getUint16(pos, true);
-        pos += 2 + nLen + 1; // name + kind byte
-        const vLen = view.getUint16(pos, true);
-        pos += 2 + vLen; // value
-    }
-    const childCount = view.getUint16(pos, true);
-    pos += 2;
-    const childIdsPos = pos;
-    pos += childCount * 4;
-    const nodeDataLen = view.getUint32(pos, true);
-    pos += 4;
-    const nodeDataPos = nodeDataLen > 0 ? pos : -1;
-    // Collect child IDs for lazy materialization
-    const ids = [];
-    for (let i = 0; i < childCount; i++)
-        ids.push(view.getUint32(childIdsPos + i * 4, true));
     // Build node using class (prototype getters, no per-instance defineProperty)
     const node = new WalkElement();
     node.tagName = tagName;
+    if (position !== undefined)
+        node.position = position;
+    if (data !== null)
+        node.data = data;
     node._view = view;
     node._buf = buf;
     node._propsPos = propsPos;
-    node._childIds = ids;
+    node._childIds = childIds;
     node._resolver = resolver;
-    node._dataPos = nodeDataPos;
-    node._dataLen = nodeDataLen;
     nodeIdMap.set(node, nodeId);
     return node;
 }
@@ -315,10 +312,15 @@ const TEXT_NODE_TYPES = {
     [HAST_MDX_TEXT_EXPRESSION]: "mdxTextExpression",
     [HAST_MDX_ESM]: "mdxjsEsm",
 };
-function readTextFromBinary(view, buf, offset, nodeId, nodeType) {
+function readTextFromBinary(view, buf, offset, nodeId, nodeType, position, data) {
     const valLen = view.getUint32(offset, true);
     const value = textDecoder.decode(buf.subarray(offset + 4, offset + 4 + valLen));
-    const node = { type: TEXT_NODE_TYPES[nodeType], value };
+    const base = { type: TEXT_NODE_TYPES[nodeType], value };
+    if (position !== undefined)
+        base.position = position;
+    if (data !== null)
+        base.data = data;
+    const node = base;
     nodeIdMap.set(node, nodeId);
     if (nodeType === HAST_MDX_FLOW_EXPRESSION || nodeType === HAST_MDX_TEXT_EXPRESSION) {
         attachParseExpression(node, napiParseExpression);
@@ -329,14 +331,14 @@ function readTextFromBinary(view, buf, offset, nodeId, nodeType) {
     return node;
 }
 /** Read an MDX JSX element from the binary data section. */
-function readMdxJsxFromBinary(view, buf, offset, nodeId, nodeType, resolver) {
+function readMdxJsxFromBinary(view, buf, offset, nodeId, nodeType, resolver, position, childIds, data) {
     let pos = offset;
     // Name
     const nameLen = view.getUint16(pos, true);
     pos += 2;
     const name = nameLen > 0 ? textDecoder.decode(buf.subarray(pos, pos + nameLen)) : null;
     pos += nameLen;
-    // Attributes: [kind: u8][nameLen: u16][name][valLen: u16][val]
+    // Attributes: [kind: u8][nameLen: u16][name][valLen: u32][val]
     const attrCount = view.getUint16(pos, true);
     pos += 2;
     const attributes = [];
@@ -370,7 +372,36 @@ function readMdxJsxFromBinary(view, buf, offset, nodeId, nodeType, resolver) {
                 break;
         }
     }
-    // Child IDs
+    const typeName = nodeType === HAST_MDX_JSX_ELEMENT ? "mdxJsxFlowElement" : "mdxJsxTextElement";
+    const base = { type: typeName, name, attributes };
+    if (position !== undefined)
+        base.position = position;
+    if (data !== null)
+        base.data = data;
+    nodeIdMap.set(base, nodeId);
+    makeLazyChildren(base, childIds, resolver);
+    return base;
+}
+function readMatchedNode(view, buf, offset, nodeId, nodeType, resolver) {
+    let pos = offset;
+    // Shared prelude (matches serialize_hast_node_inline / serialize_mdast_node_inline):
+    //   [data_len: u32][data_bytes][position: 24B][child_count: u16][child_ids: N×u32]
+    // Data (JSON), eagerly parsed
+    const dataLen = view.getUint32(pos, true);
+    pos += 4;
+    let data = null;
+    if (dataLen > 0) {
+        const jsonStr = textDecoder.decode(buf.subarray(pos, pos + dataLen));
+        try {
+            data = JSON.parse(jsonStr);
+        }
+        catch {
+            /* ignore malformed JSON */
+        }
+        pos += dataLen;
+    }
+    const position = readPositionPrefix(view, pos);
+    pos += 24;
     const childCount = view.getUint16(pos, true);
     pos += 2;
     const childIds = [];
@@ -378,16 +409,9 @@ function readMdxJsxFromBinary(view, buf, offset, nodeId, nodeType, resolver) {
         childIds.push(view.getUint32(pos, true));
         pos += 4;
     }
-    const typeName = nodeType === HAST_MDX_JSX_ELEMENT ? "mdxJsxFlowElement" : "mdxJsxTextElement";
-    const node = { type: typeName, name, attributes };
-    nodeIdMap.set(node, nodeId);
-    makeLazyChildren(node, childIds, resolver);
-    resolver.attachLazyData(node, nodeId);
-    return node;
-}
-function readMatchedNode(view, buf, offset, nodeId, nodeType, resolver) {
+    // Dispatch to type-specific tail (pos now sits at the type-specific section)
     if (nodeType === HAST_ELEMENT) {
-        return readElementFromBinary(view, buf, offset, nodeId, resolver);
+        return readElementFromBinary(view, buf, pos, nodeId, resolver, position, childIds, data);
     }
     else if (nodeType === HAST_TEXT ||
         nodeType === HAST_COMMENT ||
@@ -395,13 +419,18 @@ function readMatchedNode(view, buf, offset, nodeId, nodeType, resolver) {
         nodeType === HAST_MDX_FLOW_EXPRESSION ||
         nodeType === HAST_MDX_TEXT_EXPRESSION ||
         nodeType === HAST_MDX_ESM) {
-        return readTextFromBinary(view, buf, offset, nodeId, nodeType);
+        return readTextFromBinary(view, buf, pos, nodeId, nodeType, position, data);
     }
     else if (nodeType === HAST_MDX_JSX_ELEMENT || nodeType === HAST_MDX_JSX_TEXT_ELEMENT) {
-        return readMdxJsxFromBinary(view, buf, offset, nodeId, nodeType, resolver);
-    }
-    // Fallback: minimal node
-    const node = { type: `unknown(${nodeType})` };
+        return readMdxJsxFromBinary(view, buf, pos, nodeId, nodeType, resolver, position, childIds, data);
+    }
+    // Fallback: minimal node carrying whatever prelude data we found
+    const base = { type: `unknown(${nodeType})` };
+    if (position !== undefined)
+        base.position = position;
+    if (data !== null)
+        base.data = data;
+    const node = base;
     nodeIdMap.set(node, nodeId);
     return node;
 }
@@ -527,11 +556,13 @@ function mergeAndReset(returnBuffer, ctx) {
  * Walk a handle's arena in Rust, dispatch matched nodes to JS visitor functions,
  * and apply mutations back to the handle. No arena buffers cross NAPI.
  *
- * Returns void if all visitors are sync, or a Promise if any visitor is async.
+ * Returns the number of patches dropped because their target was removed or
+ * replaced earlier in the same pass (the caller warns when non-zero), or a
+ * Promise of that count if any visitor is async.
  */
-export function visitHastHandle(handle, plugin, subs, source, filename) {
+export function visitHastHandle(handle, plugin, subs, source, fileURL) {
     const getSource = typeof source === "function" ? source : () => source;
-    const ctx = new HastVisitorContextImpl(handle, getSource, filename);
+    const ctx = new HastVisitorContextImpl(handle, getSource, fileURL);
     const returnBuffer = new CommandBuffer();
     const resolver = new LazyChildResolver(handle);
     const rustSubs = subs.map((s) => ({ nodeType: s.nodeType, tagFilter: s.tagFilter }));
@@ -543,14 +574,16 @@ export function visitHastHandle(handle, plugin, subs, source, filename) {
                     returnBuffer.replaceRawJson(nodeId, JSON.stringify(markHast(result)));
                 }
             }
-            applyMutations(handle, returnBuffer, ctx);
+            return applyMutations(handle, returnBuffer, ctx);
         });
     }
-    applyMutations(handle, returnBuffer, ctx);
+    return applyMutations(handle, returnBuffer, ctx);
 }
+/** Returns the number of patches dropped as stranded (0 when none). */
 function applyMutations(handle, returnBuffer, ctx) {
     const { merged, hasMutations } = mergeAndReset(returnBuffer, ctx);
     if (hasMutations) {
-        applyCommandsToHandle(handle, merged);
+        return applyCommandsToHandle(handle, merged);
     }
+    return 0;
 }

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

@@ -13,12 +13,21 @@ export interface MdastDiagnostic {
 }
 export declare class MdastVisitorContext {
     #private;
-    readonly filename: string;
-    constructor(handle: MdastHandle, getSource: () => string, filename: string);
+    /**
+     * The URL of the document being processed (the compile `fileURL` option),
+     * or `undefined` when none was given. Use `fileURLToPath(ctx.fileURL)` for a
+     * decoded filesystem path.
+     */
+    readonly fileURL: URL | undefined;
+    constructor(handle: MdastHandle, getSource: () => string, fileURL: URL | undefined);
     get source(): string;
     removeNode(node: Readonly<MdastNode>): void;
     insertBefore(node: Readonly<MdastNode>, newNode: MdastNode): void;
     insertAfter(node: Readonly<MdastNode>, newNode: MdastNode): void;
+    /**
+     * Wrap `node` in `parentNode`, making it `parentNode`'s first child. Any
+     * children `parentNode` declares are kept after it.
+     */
     wrapNode(node: Readonly<MdastNode>, parentNode: MdastNode): void;
     prependChild(node: Readonly<MdastNode>, childNode: MdastNode): void;
     appendChild(node: Readonly<MdastNode>, childNode: MdastNode): void;
@@ -102,5 +111,5 @@ export declare function resolveMdastSubscriptions(plugin: MdastPluginInstance):
  * Returns MdastVisitResult synchronously if all visitors are sync,
  * or Promise<MdastVisitResult> if any visitor is async.
  */
-export declare function visitMdastHandle(handle: MdastHandle, plugin: MdastPluginInstance, subs: MdastSubscription[], source: string | (() => string), filename: string): MdastVisitResult | Promise<MdastVisitResult>;
+export declare function visitMdastHandle(handle: MdastHandle, plugin: MdastPluginInstance, subs: MdastSubscription[], source: string | (() => string), fileURL: URL | undefined): MdastVisitResult | Promise<MdastVisitResult>;
 export {};

package/dist/mdast/mdast-visitor.js

@@ -60,11 +60,16 @@ export class MdastVisitorContext {
     #diagnostics = [];
     #handle;
     #getSource;
-    filename;
-    constructor(handle, getSource, filename) {
+    /**
+     * The URL of the document being processed (the compile `fileURL` option),
+     * or `undefined` when none was given. Use `fileURLToPath(ctx.fileURL)` for a
+     * decoded filesystem path.
+     */
+    fileURL;
+    constructor(handle, getSource, fileURL) {
         this.#handle = handle;
         this.#getSource = getSource;
-        this.filename = filename;
+        this.fileURL = fileURL;
     }
     get source() {
         const value = this.#getSource();
@@ -80,6 +85,10 @@ export class MdastVisitorContext {
     insertAfter(node, newNode) {
         this.#commandBuffer.insertAfter(nid(node), newNode);
     }
+    /**
+     * Wrap `node` in `parentNode`, making it `parentNode`'s first child. Any
+     * children `parentNode` declares are kept after it.
+     */
     wrapNode(node, parentNode) {
         this.#commandBuffer.wrapNode(nid(node), parentNode);
     }
@@ -501,6 +510,36 @@ function readMdastMatchedNode(view, buf, dataOffset, nodeId, nodeType, resolver)
 /** Apply a sync visitor result to the return buffer.
  *  If the result is the same object as the input node, treat it as a no-op
  *  so that context mutations (e.g. setProperty) are not clobbered. */
+/** The arena id of a node if it is an existing (materialized) node, else
+ *  undefined for a freshly-built one. */
+function reusedId(node) {
+    if (node === null || typeof node !== "object")
+        return undefined;
+    const id = nid(node);
+    return typeof id === "number" ? id : undefined;
+}
+/**
+ * Rewrite a returned replacement tree so every *reused* node (one that came
+ * from the arena, at any depth) becomes a `{ _ref: id }` placeholder. The
+ * rebuild splices those originals back in place, preserving their ids — so a
+ * patch a nested visitor queued on a passed-through child still lands, in the
+ * same pass. Freshly-built nodes serialize as before. The root is never reffed:
+ * it is the new shape replacing the visited node.
+ */
+function refifyReusedNodes(node, isRoot) {
+    if (node === null || typeof node !== "object")
+        return node;
+    if (!isRoot) {
+        const id = reusedId(node);
+        if (id !== undefined)
+            return { _ref: id };
+    }
+    const children = node.children;
+    if (Array.isArray(children)) {
+        return { ...node, children: children.map((c) => refifyReusedNodes(c, false)) };
+    }
+    return node;
+}
 function applyMdastVisitResult(result, nodeId, returnBuffer, originalNode) {
     if (result === undefined || result === null)
         return;
@@ -515,7 +554,7 @@ function applyMdastVisitResult(result, nodeId, returnBuffer, originalNode) {
             returnBuffer.replace(nodeId, result);
             break;
         case "structured_node":
-            returnBuffer.replace(nodeId, result);
+            returnBuffer.replace(nodeId, refifyReusedNodes(result, true));
             break;
     }
 }
@@ -526,9 +565,9 @@ function applyMdastVisitResult(result, nodeId, returnBuffer, originalNode) {
  * Returns MdastVisitResult synchronously if all visitors are sync,
  * or Promise<MdastVisitResult> if any visitor is async.
  */
-export function visitMdastHandle(handle, plugin, subs, source, filename) {
+export function visitMdastHandle(handle, plugin, subs, source, fileURL) {
     const getSource = typeof source === "function" ? source : () => source;
-    const context = new MdastVisitorContext(handle, getSource, filename);
+    const context = new MdastVisitorContext(handle, getSource, fileURL);
     const returnBuffer = new CommandBuffer();
     const resolver = new MdastLazyChildResolver(handle);
     const rustSubs = subs.map((s) => ({ nodeType: s.nodeType, tagFilter: [] }));

package/index.d.ts

@@ -4,34 +4,43 @@
  * Apply MDAST commands and convert to HAST handle in one step.
  * The MDAST handle is consumed (emptied).
  */
-export declare function applyCommandsAndConvertToHastHandle(handle: MdastHandle, commandBuf: Uint8Array): HastHandle
+export declare function applyCommandsAndConvertToHastHandle(handle: MdastHandle, commandBuf: Uint8Array, convertOptions?: JsConvertOptions | undefined | null): HastHandle
 
-/** Apply a command buffer to a HAST handle's arena in-place. */
-export declare function applyCommandsToHandle(handle: HastHandle, commandBuf: Uint8Array): void
+/**
+ * Apply a command buffer to a HAST handle's arena in-place. Returns how many
+ * patches were dropped because their target lived inside a subtree this pass
+ * removed or replaced (see the lenient note below); the JS pipeline warns when
+ * non-zero. Mirrors `apply_commands_to_mdast_handle`.
+ */
+export declare function applyCommandsToHandle(handle: HastHandle, commandBuf: Uint8Array): number
 
-/** Apply a command buffer to an MDAST handle in-place. */
-export declare function applyCommandsToMdastHandle(handle: MdastHandle, commandBuf: Uint8Array): void
+/**
+ * Apply a command buffer to an MDAST handle in-place. Returns how many patches
+ * were dropped because their target lived inside a subtree this pass removed or
+ * replaced (see the lenient note below); the JS pipeline warns when non-zero.
+ */
+export declare function applyCommandsToMdastHandle(handle: MdastHandle, commandBuf: Uint8Array): number
 
 /** Compile a HAST handle's arena to MDX JavaScript. Does not consume the handle. */
 export declare function compileHandle(handle: HastHandle, options?: JsMdxOptions | undefined | null): string
 
 /** Compile MDX source directly to JavaScript. */
-export declare function compileMdx(source: string, options?: JsMdxOptions | undefined | null, features?: JsFeatures | undefined | null): string
+export declare function compileMdx(source: string, options?: JsMdxOptions | undefined | null, features?: JsFeatures | undefined | null, convertOptions?: JsConvertOptions | undefined | null): string
 
 /** Convert an MDAST handle to a HAST handle. The MDAST handle is consumed (emptied). */
-export declare function convertMdastToHastHandle(handle: MdastHandle): HastHandle
+export declare function convertMdastToHastHandle(handle: MdastHandle, convertOptions?: JsConvertOptions | undefined | null): HastHandle
 
 /**
  * Parse markdown source and convert to HAST. Returns an opaque handle.
  * The arena stays in Rust memory, no buffer is copied to JS.
  */
-export declare function createHastHandle(source: string, features?: JsFeatures | undefined | null): HastHandle
+export declare function createHastHandle(source: string, features?: JsFeatures | undefined | null, convertOptions?: JsConvertOptions | undefined | null): HastHandle
 
 /** Parse markdown source into an MDAST arena handle. */
 export declare function createMdastHandle(source: string, features?: JsFeatures | undefined | null): MdastHandle
 
 /** Parse MDX source and convert to HAST. Returns an opaque handle. */
-export declare function createMdxHastHandle(source: string, features?: JsFeatures | undefined | null): HastHandle
+export declare function createMdxHastHandle(source: string, features?: JsFeatures | undefined | null, convertOptions?: JsConvertOptions | undefined | null): HastHandle
 
 /** Parse MDX source into an MDAST arena handle. */
 export declare function createMdxMdastHandle(source: string, features?: JsFeatures | undefined | null): MdastHandle
@@ -60,15 +69,38 @@ export declare function getMdastFrontmatter(handle: MdastHandle): JsFrontmatter
  */
 export declare function getNodeData(handle: AnyHandle, nodeId: number): string | null
 
+/**
+ * MDAST→HAST conversion options passed from JavaScript.
+ *
+ * Input-only: `object_to_js = false` because `FunctionRef` only crosses
+ * JS → Rust. A `JsConvertOptions` never gets serialized back to JS.
+ */
+export interface JsConvertOptions {
+  /** `<h2>` label opening the footnotes section. Default: `"Footnotes"`. */
+  footnoteLabel?: string
+  /** Backref `<a>` content. Default: `"\u{21a9}"` (↩). */
+  footnoteBackContent?: string | ((arg0: number, arg1: number) => string)
+  /**
+   * Backref `aria-label`. The token `{reference}` is replaced with the
+   * footnote number (`1`) or `number-K` (`1-2`) for repeated references.
+   * Default: `"Back to reference {reference}"`.
+   */
+  footnoteBackLabel?: string | ((arg0: number, arg1: number) => string)
+}
+
 /** Feature toggles for the Markdown/MDX parser, passed from JavaScript. */
 export interface JsFeatures {
   /** GFM: tables, footnotes, strikethrough, task lists. Default: true. */
   gfm?: boolean
+  /** Granular GFM control (overrides `gfm`). */
+  gfmOptions?: JsGfmOptions
   /** Frontmatter: YAML (`--- ... ---`) and TOML (`+++ ... +++`). Default: true. */
   frontmatter?: boolean
-  /** Math blocks and inline math (`$$ ... $$`, `$ ... $`). Default: true. */
+  /** Math blocks and inline math (`$$ ... $$`, `$ ... $`). Default: false. */
   math?: boolean
-  /** Heading attributes (`# text { #id .class }`). Default: true. */
+  /** Granular math control (overrides `math`). */
+  mathOptions?: JsMathOptions
+  /** Heading attributes (`# text { #id .class }`). Default: false. */
   headingAttributes?: boolean
   /** Colon-delimited container directive blocks (`:::`). Default: false. */
   directive?: boolean
@@ -92,6 +124,30 @@ export interface JsFrontmatter {
   value: string
 }
 
+/**
+ * Granular GFM toggles, nested under `features.gfm`. The footnote i18n
+ * strings (label, back-content, back-label) travel separately via the
+ * `JsConvertOptions` argument on conversion entry points; the JS package
+ * extracts them from `features.gfm.footnotes` before calling in.
+ */
+export interface JsGfmOptions {
+  /**
+   * Enable GFM footnotes (`[^id]`). Default: true. Set `false` to drop
+   * footnote parsing while keeping the rest of the GFM bundle.
+   */
+  footnotes?: boolean
+}
+
+/** Granular math toggles, nested under `features.math`. */
+export interface JsMathOptions {
+  /**
+   * Treat single-dollar runs (`$ ... $`) as inline math. Default: true.
+   * Set `false` to keep single `$` as literal text (prose with currency)
+   * while still parsing double-dollar (`$$ ... $$`) display math.
+   */
+  singleDollarTextMath?: boolean
+}
+
 /** MDX compile options passed from JavaScript. */
 export interface JsMdxOptions {
   /**
@@ -189,7 +245,7 @@ export declare function parseEsm(source: string): string | null
 export declare function parseExpression(source: string): string | null
 
 /** Parse Markdown source and return HTML string directly. */
-export declare function parseToHtml(source: string, features?: JsFeatures | undefined | null): string
+export declare function parseToHtml(source: string, features?: JsFeatures | undefined | null, convertOptions?: JsConvertOptions | undefined | null): string
 
 /** Render a HAST handle's arena to HTML. Does not consume the handle. */
 export declare function renderHandle(handle: HastHandle): string