satteri 0.6.3 → 0.8.0

package/README.md

@@ -163,6 +163,14 @@ heading(node) {
 }
 ```
 
+### How transforms compose
+
+Unlike remark and rehype, which re-walk the tree until it stops changing, each Sätteri plugin walks the tree **once**. Within that single pass:
+
+- **Passed-through children keep their identity.** When a visitor returns a replacement that reuses the original node's children (e.g. `{ ...node, children: [...node.children] }`), those children are spliced back unchanged — so a transform the same pass queues on a nested one still applies. This is what lets a `containerDirective` visitor turn both an outer `:::note` and a nested `:::tip` into asides in one go.
+- **A plugin's own freshly-built nodes are not re-walked by that plugin.** If a visitor returns a brand-new node (one that didn't come from the tree), the same plugin won't visit it. Produce its final shape directly, or hand it off to a later plugin — every plugin runs over the fully materialized output of the ones before it.
+- **Dropping a subtree drops transforms queued inside it.** If one visitor removes or replaces a node while another (in the same pass) had queued a transform on something inside that subtree, the orphaned transform is dropped and a warning is logged. This is usually intentional — you discarded that subtree on purpose — but the warning helps catch the cases where it isn't.
+
 ### Async plugins
 
 Visitors can optionally be async. When any visitor is async, `markdownToHtml` and `mdxToJs` return a `Promise<string>` instead of `string`. For performance reasons, it is typically best to avoid async visitors, especially if your visitor matches a large number of nodes.
@@ -289,7 +297,8 @@ Type-safe wrapper for HAST plugin definitions.
 interface CompileOptions {
   mdastPlugins?: MdastPluginDefinition[];
   hastPlugins?: HastPluginDefinition[];
-  filename?: string;
+  features?: Features;
+  fileURL?: URL;
 }
 
 // mdxToJs accepts MdxCompileOptions, which extends CompileOptions
@@ -298,6 +307,10 @@ interface MdxCompileOptions extends CompileOptions {
 }
 ```
 
+`fileURL` is the `URL` of the document being processed, surfaced to plugins as `ctx.fileURL` (a `URL`, or `undefined` when omitted). Pass a file URL such as Astro's `fileURL`, or convert a filesystem path with Node's `pathToFileURL`; read it back with `fileURLToPath(ctx.fileURL)`.
+
+`Features` controls the Markdown extensions Sätteri's parser recognizes: `gfm`, `frontmatter`, `math`, `directive`, `smartPunctuation`, etc. `gfm`, `math`, and `smartPunctuation` also accept granular options. For example, `math: { singleDollarTextMath: false }` keeps single `$` as literal text. See the [Features reference](https://satteri.dev/docs/features/) for the full list.
+
 ## License
 
 MIT

package/dist/compile.d.ts

@@ -16,15 +16,91 @@ export interface SmartPunctuationOptions {
     /** Replace `...` with ellipsis (`…`). Default: true. */
     ellipses?: boolean;
 }
+/**
+ * Per-backref callback. Invoked once per anchor in the footnotes section
+ * with 1-based `referenceNumber` and `rerunIndex` (1 on the first backref
+ * to that definition, 2 on the second, and so on). Must return the final
+ * string used as the backref content or `aria-label`.
+ */
+export type FootnoteBackrefCallback = (referenceNumber: number, rerunIndex: number) => string;
+/**
+ * i18n strings for the GFM footnotes section. Mirrors `footnoteLabel`,
+ * `footnoteBackLabel`, and `footnoteBackContent` from remark-rehype.
+ *
+ * `backContent` and `backLabel` each accept either a template string with
+ * the `{reference}` placeholder (substituted with `1` or `1-2` to match
+ * remark-rehype's default suffix), or a callback receiving the raw
+ * `(referenceNumber, rerunIndex)` pair.
+ *
+ * Passing this object enables footnotes. To turn them off, use
+ * `gfm: { footnotes: false }`.
+ */
+export interface FootnoteOptions {
+    /** `<h2>` label opening the footnotes section. Default: `"Footnotes"`. */
+    label?: string;
+    /**
+     * Backref `<a>` content. Default: `"↩"`.
+     *
+     * Template form: the string is used as-is, and a `<sup>K</sup>` marker
+     * is auto-appended on reruns (k > 1). Callback form: returns the full
+     * content for each backref; no auto-sup is added.
+     */
+    backContent?: string | FootnoteBackrefCallback;
+    /**
+     * Backref `aria-label`. Default: `"Back to reference {reference}"`.
+     *
+     * Template form: `{reference}` becomes `n` for the first backref, `n-K`
+     * for subsequent ones. Callback form: returns the `aria-label` string
+     * for each backref.
+     */
+    backLabel?: string | FootnoteBackrefCallback;
+}
+/** Granular GFM toggles, nested under {@link Features.gfm}. */
+export interface GfmOptions {
+    /**
+     * Enable GFM footnotes (`[^id]`). Default: true.
+     *
+     * Pass `false` to drop footnote parsing while keeping the rest of GFM;
+     * pass an object to enable footnotes with custom i18n strings (see
+     * {@link FootnoteOptions}).
+     */
+    footnotes?: boolean | FootnoteOptions;
+}
+/** Granular math toggles, nested under {@link Features.math}. */
+export interface MathOptions {
+    /**
+     * Treat single-dollar runs (`$ ... $`) as inline math. Default: true.
+     *
+     * Set `false` to keep single `$` as literal text while still parsing
+     * `$$ ... $$` display math. Mirrors `singleDollarTextMath` from
+     * remark-math.
+     */
+    singleDollarTextMath?: boolean;
+}
 /** Parser feature toggles. All default to their documented value when omitted. */
 export interface Features {
-    /** GFM: tables, footnotes, strikethrough, task lists. Default: true. */
-    gfm?: boolean;
+    /**
+     * GFM: tables, footnotes, strikethrough, task lists. Default: true.
+     *
+     * Pass an options object for granular control:
+     * ```ts
+     * gfm: { footnotes: false }                   // skip footnotes only
+     * gfm: { footnotes: { label: "Notes" } }      // localize footnotes
+     * ```
+     */
+    gfm?: boolean | GfmOptions;
     /** Frontmatter: YAML (`--- ... ---`) and TOML (`+++ ... +++`). Default: true. */
     frontmatter?: boolean;
-    /** Math blocks and inline math. Default: true. */
-    math?: boolean;
-    /** Heading attributes (`# text { #id .class }`). Default: true. */
+    /**
+     * Math blocks and inline math. Default: false.
+     *
+     * Pass an options object for granular control:
+     * ```ts
+     * math: { singleDollarTextMath: false }       // $$..$$ only, $..$ literal
+     * ```
+     */
+    math?: boolean | MathOptions;
+    /** Heading attributes (`# text { #id .class }`). Default: false. */
     headingAttributes?: boolean;
     /** Colon-delimited container directive blocks (`:::`). Default: false. */
     directive?: boolean;
@@ -48,7 +124,12 @@ export interface CompileOptions {
     mdastPlugins?: MdastPluginInput[];
     hastPlugins?: HastPluginInput[];
     features?: Features;
-    filename?: string;
+    /**
+     * The document being processed, surfaced to plugins as `ctx.fileURL`. Must
+     * be a `URL` (e.g. Astro's `fileURL`); convert a filesystem path with Node's
+     * `pathToFileURL` before passing it.
+     */
+    fileURL?: URL;
 }
 /**
  * MDX-only compile options.

package/dist/compile.js

@@ -5,16 +5,55 @@ import { MdastReader } from "./mdast/mdast-reader.js";
 import { materializeMdastTree } from "./mdast/mdast-materializer.js";
 import { HastReader } from "./hast/hast-reader.js";
 import { materializeHastTree } from "./hast/hast-materializer.js";
+/**
+ * Split the user-facing `Features` (with nested unions) into the flat napi
+ * `JsFeatures` shape plus the conversion-side `JsConvertOptions` carrying
+ * the footnote i18n strings. The public API only exposes `features`; the
+ * footnote strings are routed to napi internally.
+ */
 function featuresToNative(features) {
     if (!features)
-        return undefined;
+        return { features: undefined, convertOptions: undefined };
     const result = {};
-    if (features.gfm !== undefined)
-        result.gfm = features.gfm;
+    let convertOptions;
+    if (features.gfm !== undefined) {
+        if (typeof features.gfm === "object") {
+            const g = features.gfm;
+            const gfmOpts = {};
+            if (g.footnotes !== undefined) {
+                if (typeof g.footnotes === "object") {
+                    gfmOpts.footnotes = true;
+                    convertOptions = convertOptions ?? {};
+                    if (g.footnotes.label !== undefined)
+                        convertOptions.footnoteLabel = g.footnotes.label;
+                    if (g.footnotes.backContent !== undefined)
+                        convertOptions.footnoteBackContent = g.footnotes.backContent;
+                    if (g.footnotes.backLabel !== undefined)
+                        convertOptions.footnoteBackLabel = g.footnotes.backLabel;
+                }
+                else {
+                    gfmOpts.footnotes = g.footnotes;
+                }
+            }
+            result.gfmOptions = gfmOpts;
+        }
+        else {
+            result.gfm = features.gfm;
+        }
+    }
     if (features.frontmatter !== undefined)
         result.frontmatter = features.frontmatter;
-    if (features.math !== undefined)
-        result.math = features.math;
+    if (features.math !== undefined) {
+        if (typeof features.math === "object") {
+            const mathOpts = {};
+            if (features.math.singleDollarTextMath !== undefined)
+                mathOpts.singleDollarTextMath = features.math.singleDollarTextMath;
+            result.mathOptions = mathOpts;
+        }
+        else {
+            result.math = features.math;
+        }
+    }
     if (features.headingAttributes !== undefined)
         result.headingAttributes = features.headingAttributes;
     if (features.directive !== undefined)
@@ -33,41 +72,46 @@ function featuresToNative(features) {
             result.smartPunctuation = features.smartPunctuation;
         }
     }
-    return result;
+    return { features: result, convertOptions };
+}
+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, filename) {
-    let pendingCommands = null;
+function runMdastPluginsOnHandle(handle, plugins, fileURL) {
+    // 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
+    // one pass. A plugin's own freshly-built nodes are not re-walked; transform
+    // 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 apply = (r) => {
+            if (!r.hasMutations)
+                return;
+            const dropped = applyCommandsToMdastHandle(handle, r.commandBuffer);
+            if (dropped)
+                warnDroppedTransforms(plugin, dropped, "mdast");
+        };
+        return result instanceof Promise ? result.then(apply) : apply(result);
+    };
     let i = 0;
     const runNext = () => {
         while (i < plugins.length) {
-            const idx = i++;
-            const raw = plugins[idx];
+            const raw = plugins[i++];
             const plugin = typeof raw === "function" ? raw() : raw;
-            const subs = resolveMdastSubscriptions(plugin);
-            const result = visitMdastHandle(handle, plugin, subs, () => getHandleSource(handle), filename);
-            if (result instanceof Promise) {
-                return result.then((r) => {
-                    applyMdastResult(r, idx, plugins.length, handle);
-                    return runNext();
-                });
-            }
-            applyMdastResult(result, idx, plugins.length, handle);
+            const r = runPlugin(plugin);
+            if (r instanceof Promise)
+                return r.then(runNext);
         }
-        return { handle, pendingCommands };
+        return { handle };
     };
-    function applyMdastResult(result, idx, total, h) {
-        if (result.hasMutations) {
-            if (idx === total - 1) {
-                pendingCommands = result.commandBuffer;
-            }
-            else {
-                applyCommandsToMdastHandle(h, result.commandBuffer);
-            }
-        }
-    }
     return runNext();
 }
-function runHastPluginsOnHandle(handle, plugins, source, filename) {
+function runHastPluginsOnHandle(handle, plugins, source, fileURL) {
     if (plugins.length === 0)
         return;
     let i = 0;
@@ -77,10 +121,18 @@ function runHastPluginsOnHandle(handle, plugins, source, filename) {
             i++;
             const plugin = typeof raw === "function" ? raw() : raw;
             const subs = resolveSubscriptions(plugin);
-            const result = visitHastHandle(handle, plugin, subs, source, filename);
+            const result = visitHastHandle(handle, plugin, subs, source, fileURL);
+            const warnIfDropped = (dropped) => {
+                if (dropped)
+                    warnDroppedTransforms(plugin, dropped, "hast");
+            };
             if (result instanceof Promise) {
-                return result.then(runNext);
+                return result.then((dropped) => {
+                    warnIfDropped(dropped);
+                    return runNext();
+                });
             }
+            warnIfDropped(result);
         }
     };
     return runNext();
@@ -129,9 +181,9 @@ function mdxOptionsToNative(opts) {
     return result;
 }
 export function markdownToHtml(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], features, filename = "<unknown>" } = options;
-    const nativeFeatures = featuresToNative(features);
-    const result = createHastHandleFromMdast(source, mdastPlugins, false, filename, nativeFeatures);
+    const { mdastPlugins = [], hastPlugins = [], features, fileURL } = options;
+    const { features: nativeFeatures, convertOptions: nativeConvertOptions } = featuresToNative(features);
+    const result = createHastHandleFromMdast(source, mdastPlugins, false, fileURL, nativeFeatures, nativeConvertOptions);
     const renderAndDrop = (h, frontmatter) => {
         try {
             const html = renderHandle(h);
@@ -144,7 +196,7 @@ export function markdownToHtml(source, options = {}) {
     const runHastThenRender = (r) => {
         let hastResult;
         try {
-            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, filename);
+            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL);
         }
         catch (err) {
             dropHandle(r.hastHandle);
@@ -163,10 +215,10 @@ export function markdownToHtml(source, options = {}) {
     return runHastThenRender(result);
 }
 export function mdxToJs(source, options = {}) {
-    const { mdastPlugins = [], hastPlugins = [], features, filename = "<unknown>", ...mdxFields } = options;
+    const { mdastPlugins = [], hastPlugins = [], features, fileURL, ...mdxFields } = options;
     const mdxOptions = mdxOptionsToNative(mdxFields);
-    const nativeFeatures = featuresToNative(features);
-    const result = createHastHandleFromMdast(source, mdastPlugins, true, filename, nativeFeatures);
+    const { features: nativeFeatures, convertOptions: nativeConvertOptions } = featuresToNative(features);
+    const result = createHastHandleFromMdast(source, mdastPlugins, true, fileURL, nativeFeatures, nativeConvertOptions);
     const compileAndDrop = (h, frontmatter) => {
         try {
             const code = compileHandle(h, mdxOptions);
@@ -179,7 +231,7 @@ export function mdxToJs(source, options = {}) {
     const runHastThenCompile = (r) => {
         let hastResult;
         try {
-            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, filename);
+            hastResult = runHastPluginsOnHandle(r.hastHandle, hastPlugins, source, fileURL);
         }
         catch (err) {
             dropHandle(r.hastHandle);
@@ -224,9 +276,11 @@ function readFrontmatter(handle) {
 /** Parse, run mdast plugins, capture frontmatter, then convert to HAST.
  *  Frontmatter is read from the post-plugin MDAST so visitor mutations to
  *  the yaml/toml node are reflected in the returned value. */
-function createHastHandleFromMdast(source, mdastPlugins, mdx, filename, 
+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
-nativeFeatures) {
+nativeConvertOptions) {
     const mdastHandle = mdx
         ? createMdxMdastHandle(source, nativeFeatures)
         : createMdastHandle(source, nativeFeatures);
@@ -234,11 +288,8 @@ nativeFeatures) {
     // on success, but if any step here throws the handle would otherwise leak.
     const finalize = (r) => {
         try {
-            if (r.pendingCommands) {
-                applyCommandsToMdastHandle(r.handle, r.pendingCommands);
-            }
             const frontmatter = readFrontmatter(r.handle);
-            const hastHandle = convertMdastToHastHandle(r.handle);
+            const hastHandle = convertMdastToHastHandle(r.handle, nativeConvertOptions);
             return { hastHandle, frontmatter };
         }
         finally {
@@ -247,9 +298,9 @@ nativeFeatures) {
     };
     try {
         if (mdastPlugins.length === 0) {
-            return finalize({ handle: mdastHandle, pendingCommands: null });
+            return finalize({ handle: mdastHandle });
         }
-        const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, filename);
+        const mdastResult = runMdastPluginsOnHandle(mdastHandle, mdastPlugins, fileURL);
         if (mdastResult instanceof Promise) {
             return mdastResult.then(finalize, (err) => {
                 dropHandle(mdastHandle);
@@ -266,7 +317,7 @@ nativeFeatures) {
 // Step-by-step API: individual pipeline stages with materialized trees
 /** Parse Markdown source into a materialized mdast tree. */
 export function markdownToMdast(source, options = {}) {
-    const handle = createMdastHandle(source, featuresToNative(options.features));
+    const handle = createMdastHandle(source, featuresToNative(options.features).features);
     try {
         return materializeMdastTree(new MdastReader(serializeHandle(handle)));
     }
@@ -276,7 +327,7 @@ export function markdownToMdast(source, options = {}) {
 }
 /** Parse MDX source into a materialized mdast tree. */
 export function mdxToMdast(source, options = {}) {
-    const handle = createMdxMdastHandle(source, featuresToNative(options.features));
+    const handle = createMdxMdastHandle(source, featuresToNative(options.features).features);
     try {
         return materializeMdastTree(new MdastReader(serializeHandle(handle)));
     }
@@ -286,7 +337,8 @@ export function mdxToMdast(source, options = {}) {
 }
 /** Convert Markdown source to a materialized hast tree. */
 export function markdownToHast(source, options = {}) {
-    const handle = createHastHandle(source, featuresToNative(options.features));
+    const { features: nativeFeatures, convertOptions } = featuresToNative(options.features);
+    const handle = createHastHandle(source, nativeFeatures, convertOptions);
     try {
         return materializeHastTree(new HastReader(serializeHandle(handle)));
     }
@@ -296,7 +348,8 @@ export function markdownToHast(source, options = {}) {
 }
 /** Convert MDX source to a materialized hast tree. */
 export function mdxToHast(source, options = {}) {
-    const handle = createMdxHastHandle(source, featuresToNative(options.features));
+    const { features: nativeFeatures, convertOptions } = featuresToNative(options.features);
+    const handle = createMdxHastHandle(source, nativeFeatures, convertOptions);
     try {
         return materializeHastTree(new HastReader(serializeHandle(handle)));
     }

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

@@ -15,11 +15,21 @@ export interface HastDiagnostic {
 }
 export interface HastVisitorContext {
     readonly source: string;
-    readonly 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;
     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;
+    /**
+     * 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;
@@ -68,7 +78,9 @@ export declare function resolveSubscriptions(plugin: HastVisitorInstance): Resol
  * 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 declare function visitHastHandle(handle: HastHandle, plugin: HastVisitorInstance, subs: ResolvedSubscription[], source: string | (() => string), filename: string): void | Promise<void>;
+export declare function visitHastHandle(handle: HastHandle, plugin: HastVisitorInstance, subs: ResolvedSubscription[], source: string | (() => string), fileURL: URL | undefined): number | Promise<number>;
 export {};