`markdownToMdast` and `mdxToMdast` should return `Root`

[lumirlumir]

What's the problem?

Hello, and thanks as always for your efforts!

---

markdownToMdast() and mdxToMdast() are declared as returning MdastNode:

export type MdastNode = MdastStdNodes;
// mdast.Nodes = Root | RootContent

This unnecessarily includes RootContent, even though both functions parse a complete document and always return a Root.

Minimal reproduction

import { markdownToMdast } from "satteri";
import type { Root } from "mdast";

const root: Root = markdownToMdast("# Hello");

TypeScript reports that MdastNode is not assignable to Root, requiring an unnecessary assertion:

const root = markdownToMdast("# Hello") as Root;

The implementation delegates to materializeMdastTree(), whose return type is already Root:

export declare function materializeMdastTree(
  reader: MdastReader,
): Root;

At runtime, empty and non-empty documents both return type: "root".

References:

satteri/packages/satteri/src/compile.ts

Lines 1082 to 1089 in 166419c

	export function markdownToMdast(source: string, options: { features?: Features } = {}): MdastNode {
	const handle = createMdastHandle(source, featuresToNative(options.features).features);
	try {
	return materializeMdastTree(new MdastReader(serializeHandle(handle)));
	} finally {
	releaseHandle(handle, true);
	}
	}

satteri/packages/satteri/src/mdast/mdast-materializer.ts

Lines 114 to 117 in 166419c

	/** Materialize the full tree from root (nodeId=0). */
	export function materializeMdastTree(reader: MdastReader): Root {
	return materializeNode(reader, 0) as Root;
	}

---

Another reference: The fromMarkdown function from mdast-util-from-markdown also returns the Root type.

import { fromMarkdown } from 'mdast-util-from-markdown';

Environment Information

satteri: 0.9.5
TypeScript: 6.0.3
Node.js: v24.18.0
Windows x64 (NT 10.0.26200.0)

What's the expected result?

Both APIs should return Root:

import type { Root } from "mdast";

export declare function markdownToMdast(
  source: string,
  options?: { features?: Features },
): Root;

export declare function mdxToMdast(
  source: string,
  options?: { features?: Features },
): Root;

Participation

• I am willing to submit a pull request for this issue.