@effected/markdown 0.6.2 → 0.7.0

package/FrontmatterSource.js

@@ -0,0 +1,188 @@
+import { FrontmatterFormat } from "./MarkdownNode.js";
+import { scanRawFrontmatter } from "./internal/blocks/frontmatter.js";
+import { Effect, Schema } from "effect";
+
+//#region src/FrontmatterSource.ts
+/**
+* String-level frontmatter split and join — the raw-source surface, usable
+* without parsing the body at all.
+*
+* @remarks
+* The `MarkdownFrontmatter` seam requires a parsed `MarkdownDocument`; this
+* module serves the consumer whose body the CommonMark engine cannot or
+* should not parse (an MDX page, a template) and whose contract is
+* byte-exact boundaries (a snapshot hash over the body). It runs the SAME
+* closed fence grammar as the parser's offset-0 pre-scan — `---` yaml,
+* `+++` toml, `---json` json, fence lines exactly the fence, an unclosed
+* fence is not frontmatter — over raw bytes, and never parses the
+* frontmatter value or the body: string level only, decoding is the codec
+* modules' business.
+*/
+/**
+* The three line-terminator spellings a fence line may end with. Recorded by
+* {@link FrontmatterSource.split} as fidelity — what the source's fence
+* lines actually used — and consumed by {@link FrontmatterSource.join}.
+*
+* @public
+*/
+const FrontmatterNewline = Schema.Literals([
+	"\n",
+	"\r\n",
+	"\r"
+]);
+/**
+* A frontmatter block at string level: the format its fence declared, the
+* exact bytes between the fence lines, and the fence lines' terminator.
+*
+* @remarks
+* `value` is the exact source slice strictly between the opening fence line
+* (its terminator included) and the closing fence line: every value line
+* WITH its own terminator, verbatim — so a block whose value is one blank
+* line (`"\n"`) stays distinct from a block with no value lines (`""`), and
+* interior CRLF terminators survive untouched. This deliberately differs
+* from the parsed `Frontmatter` NODE's `value`, which drops the final
+* terminator; the node feeds codecs, this feeds byte-exact reconstruction.
+* {@link FrontmatterSource.join} accepts a value without a trailing
+* terminator too, appending `newline` so a hand-built block cannot fuse its
+* last line into the closing fence.
+*
+* `newline` is a fidelity field: `split` always records the terminator
+* following the opening fence; when absent (a hand-built block), `join`
+* uses `"\n"`.
+*
+* @public
+*/
+var FrontmatterSourceBlock = class extends Schema.Class("FrontmatterSourceBlock")({
+	format: FrontmatterFormat,
+	value: Schema.String,
+	newline: Schema.optionalKey(FrontmatterNewline)
+}) {};
+/**
+* The result of {@link FrontmatterSource.split}: the frontmatter block when
+* one exists, the exact body remainder, and the body's byte offset.
+*
+* @remarks
+* `body` is exactly `source.slice(bodyOffset)` — the string and the offset
+* can never disagree. With no block, `body` is the whole source and
+* `bodyOffset` is `0`. With a block, `bodyOffset` sits immediately after
+* the closing fence line and its line terminator (the terminator belongs to
+* the fence line, as every line's terminator belongs to its line), which is
+* gray-matter's body boundary; when the closing fence ends the document
+* there is no terminator and the body is empty.
+*
+* `bodyOffset` is informational output of `split`; `join` never reads it,
+* and it constructor-defaults to `0` so a hand-built value for `join` can
+* omit it.
+*
+* @public
+*/
+var FrontmatterSourceSplit = class extends Schema.Class("FrontmatterSourceSplit")({
+	frontmatter: Schema.optionalKey(FrontmatterSourceBlock),
+	body: Schema.String,
+	bodyOffset: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0)))
+}) {};
+/** The opening fence line per format (the closed grammar's spellings). */
+const OPEN_FENCE = {
+	yaml: "---",
+	toml: "+++",
+	json: "---json"
+};
+/** The closing fence line per format. */
+const CLOSE_FENCE = {
+	yaml: "---",
+	toml: "+++",
+	json: "---"
+};
+/**
+* The string-level frontmatter facade: split raw source at the fence
+* boundaries and join it back, without parsing anything.
+*
+* @public
+*/
+var FrontmatterSource = class {
+	constructor() {}
+	/**
+	* Split raw source into its frontmatter block and body, at string level.
+	* Total: never fails, never parses — absence of a block (including an
+	* opening fence with no closing fence, which per the grammar is not
+	* frontmatter) is a representable result, not an error.
+	*
+	* @remarks
+	* The grammar is the parser's own offset-0 pre-scan, over raw bytes:
+	* the fence set is closed (`---` yaml, `+++` toml, `---json` json), a
+	* fence line is exactly the fence with no surrounding whitespace, and a
+	* leading BOM means offset 0 is not a fence — strip one before calling
+	* if the source may carry it. Unlike the parse path there is no capture
+	* toggle here, so absence is one fact: the source has no closed block.
+	* (`MarkdownDocument`'s two-reason absence exists because parsing can be
+	* asked not to look; this surface always looks.)
+	*
+	* Byte exactness: `source.slice(0, result.bodyOffset) + result.body`
+	* reassembles `source` exactly, and {@link FrontmatterSource.join}
+	* reproduces the original bytes for an unmodified round-trip — see
+	* `join` for the two normalizations at the contract's edge.
+	*
+	* @example
+	* ```ts
+	* import { FrontmatterSource } from "@effected/markdown";
+	*
+	* const split = FrontmatterSource.split("---\ntitle: hi\n---\n\n# Body\n");
+	* console.log(split.frontmatter?.format); // => "yaml"
+	* console.log(split.frontmatter?.value); // => "title: hi\n"
+	* console.log(split.body); // => "\n# Body\n"
+	* ```
+	*
+	* @param source - The raw document source, body format irrelevant.
+	* @returns A {@link FrontmatterSourceSplit}; `frontmatter` is absent when
+	*   the source opens with no closed fence block.
+	*/
+	static split(source) {
+		const capture = scanRawFrontmatter(source);
+		if (capture === null) return FrontmatterSourceSplit.make({
+			body: source,
+			bodyOffset: 0
+		});
+		return FrontmatterSourceSplit.make({
+			frontmatter: FrontmatterSourceBlock.make({
+				format: capture.format,
+				value: capture.value,
+				newline: capture.newline
+			}),
+			body: source.slice(capture.bodyOffset),
+			bodyOffset: capture.bodyOffset
+		});
+	}
+	/**
+	* Serialize a split back to one source string. Total and pure.
+	*
+	* @remarks
+	* With no block the body is returned verbatim. With a block the output
+	* is the opening fence, `newline` (default `"\n"`), the value — a
+	* non-empty value missing a final line terminator gets `newline`
+	* appended, so the closing fence always starts its own line — the
+	* closing fence, `newline`, then the body verbatim.
+	*
+	* **Round-trip contract:** `join(split(source)) === source`, byte for
+	* byte, for every source whose closing fence line ends with a line
+	* terminator matching the opening fence's. The two edges where join
+	* normalizes instead: a closing fence at end-of-document gains a final
+	* `newline` (the block's one unterminated spelling), and fence lines
+	* with MISMATCHED terminators (say `---\r\n … ---\n`) re-emit both with
+	* the opening one. Value and body bytes survive verbatim in every case.
+	*
+	* @param split - The parts to serialize, typically from
+	*   {@link FrontmatterSource.split} or built with
+	*   `FrontmatterSourceSplit.make`.
+	* @returns The combined source string.
+	*/
+	static join(split) {
+		const block = split.frontmatter;
+		if (block === void 0) return split.body;
+		const newline = block.newline ?? "\n";
+		const value = block.value === "" || block.value.endsWith("\n") || block.value.endsWith("\r") ? block.value : `${block.value}${newline}`;
+		return `${OPEN_FENCE[block.format]}${newline}${value}${CLOSE_FENCE[block.format]}${newline}${split.body}`;
+	}
+};
+
+//#endregion
+export { FrontmatterNewline, FrontmatterSource, FrontmatterSourceBlock, FrontmatterSourceSplit };

package/Markdown.js

@@ -1,6 +1,7 @@
 import { Root } from "./MarkdownNode.js";
 import { isGuardExceeded, isRawMarkdownError } from "./internal/carriers.js";
 import { parseBlocks } from "./internal/blockParser.js";
+import { parsePhrasingText } from "./internal/phrasing.js";
 import { stringifyTree } from "./internal/stringify.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
 import { Effect, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
@@ -176,6 +177,79 @@ var Markdown = class Markdown {
 	*/
 	static parse = Effect.fn("Markdown.parse")((text, options) => Effect.fromResult(Markdown.parseResult(text, options)));
 	/**
+	* Parse a text fragment as a single paragraph's inline content,
+	* synchronously, as a `Result` — the phrasing-level twin of
+	* {@link Markdown.parseResult}, for callers holding already-markdown
+	* prose (a link-carrying sentence, a backtick span) who want its
+	* phrasing nodes without a full document parse and a paragraph splice.
+	*
+	* @remarks
+	* The whole input is prepared exactly the way the block pass prepares one
+	* paragraph's content — leading and trailing whitespace trimmed, line
+	* terminators normalized to `\n` — and handed to the inline pass, so the
+	* result matches the `children` of the paragraph a full parse of the same
+	* fragment would produce. Node positions are correct relative to the
+	* input string.
+	*
+	* Two consequences of the single-paragraph contract:
+	*
+	* - **Blank lines do not break blocks.** A `\n\n` in the input stays
+	*   inline content (literal newlines in a text node); nothing at this
+	*   level opens a heading, list or code block — `# foo` is the text
+	*   `# foo`.
+	* - **No reference context exists.** The fragment carries no definitions,
+	*   so `[foo]`, `![foo]` and `[^foo]` remain literal text — the same
+	*   result a full parse of the isolated fragment produces.
+	*
+	* `options.dialect` selects the inline dialect (default `"gfm"`);
+	* `options.frontmatter` has no effect at phrasing level. Failure is rare
+	* by design, on {@link Markdown.parseResult}'s terms: only a
+	* hardening-guard trip (delimiter or bracket nesting past the cap) fails.
+	*
+	* @example
+	* ```ts
+	* import { Markdown } from "@effected/markdown";
+	* import { Result } from "effect";
+	*
+	* const ok = Markdown.parsePhrasingResult("see [the docs](./docs.md)");
+	* if (Result.isSuccess(ok)) {
+	*   console.log(ok.success.map((node) => node.type)); // => ["text", "link"]
+	* }
+	* ```
+	*
+	* @param text - The prose fragment to parse.
+	* @param options - Optional {@link MarkdownParseOptions}; the dialect
+	*   defaults to `"gfm"`.
+	* @returns A `Result` succeeding with the fragment's phrasing content, or
+	*   failing with {@link MarkdownParseError}.
+	*/
+	static parsePhrasingResult(text, options) {
+		try {
+			return Result.succeed(parsePhrasingText(text, dialectOf(options)));
+		} catch (caught) {
+			if (isGuardExceeded(caught)) return Result.fail(new MarkdownParseError({ diagnostic: MarkdownDiagnostic.fromRaw(text, {
+				code: caught.reason,
+				message: caught.message,
+				offset: caught.offset,
+				length: 0
+			}) }));
+			throw caught;
+		}
+	}
+	/**
+	* Parse a text fragment as a single paragraph's inline content. Defined
+	* in terms of {@link Markdown.parsePhrasingResult} — synchronous callers
+	* can use that variant directly; the single-paragraph contract (blank
+	* lines stay inline, references never form) is documented there.
+	*
+	* @param text - The prose fragment to parse.
+	* @param options - Optional {@link MarkdownParseOptions}; the dialect
+	*   defaults to `"gfm"`.
+	* @returns An `Effect` that succeeds with the fragment's phrasing
+	*   content, or fails with {@link MarkdownParseError}.
+	*/
+	static parsePhrasing = Effect.fn("Markdown.parsePhrasing")((text, options) => Effect.fromResult(Markdown.parsePhrasingResult(text, options)));
+	/**
 	* Serialize a {@link Root} tree to canonical markdown, synchronously, as a
 	* `Result`. The pure primitive twin of {@link Markdown.stringify}, on the
 	* same terms as {@link Markdown.parseResult}.
@@ -192,6 +266,66 @@ var Markdown = class Markdown {
 	* contract — but is not a byte-level round-trip of any original source;
 	* surgical editing goes through the offset-splice edit layer instead.
 	*
+	* **The canonical form is a stability commitment, so a test may assert
+	* against these bytes.** There are no options to configure and therefore
+	* nothing to drift, the choices below are pinned by byte-level tests, and
+	* the engine is cross-checked against commonmark.js over the full
+	* CommonMark 0.31.2 corpus. Changing any of them is a **breaking** change
+	* to this package, never a patch. A consumer asserting on rendered
+	* markdown should serialize through here rather than through a third-party
+	* stringifier whose defaults are free to move.
+	*
+	* The canonical choices a byte-level assertion depends on, for a node
+	* carrying no fidelity field:
+	*
+	* | Construct | Canonical form |
+	* | --- | --- |
+	* | Heading | ATX (`## x`), at every depth |
+	* | Thematic break | `***` |
+	* | Bullet list marker | `-` |
+	* | Ordered list delimiter | `.`, flipping to `)` to separate an immediately adjacent sibling list |
+	* | Emphasis / strong | `*` / `**` |
+	* | Code block | fenced when the node carries a `lang` or a `fenceChar`, with the fence grown past any interior backtick run; otherwise indented — **except where indenting would not re-parse as a code block**, which forces a fence (see below) |
+	* | Block separation | exactly one blank line |
+	* | Document | a single trailing newline |
+	*
+	* A node carrying a fidelity field overrides the corresponding row —
+	* `headingStyle: "setext"`, `markerChar`, `fenceChar`, `delimiter` — which
+	* is how a parsed document re-serializes in its author's spelling. The
+	* rows describe a synthesized node, which is the case a test asserting on
+	* generated markdown actually has.
+	*
+	* **Representability wins over the table.** The canonical form never emits
+	* text that would re-parse as something else, so a row yields where the two
+	* conflict. The case that reaches a consumer is the indented code block: an
+	* indented block directly after a list is absorbed as list content, so a
+	* `Code` node with neither `lang` nor `fenceChar` emits **fenced** in that
+	* position and indented everywhere else. A byte-level assertion over
+	* synthesized code blocks therefore depends on the preceding sibling.
+	*
+	* **The posture that makes this a non-issue**, and the one a consumer
+	* building trees for byte-level assertion should adopt: set `fenceChar` on
+	* every `Code` node that carries neither a `lang` nor one already, in a
+	* post-decode walk that reaches nested nodes. The choice then leaves the
+	* emitter entirely and no output depends on a node's neighbours.
+	*
+	* **MDX nodes (constructed trees only — the parser reads no MDX syntax)**
+	* serialize to valid MDX with the mdast-util-mdx defaults, and these
+	* choices are part of the same stability commitment: attribute values
+	* quote with `"` (the quote escaped as `"`), an empty element
+	* self-closes spaced (`<a />`), a fragment is `<></>`, flow children take
+	* block layout indented two spaces per JSX ancestor, attributes move onto
+	* their own lines only when one carries a line ending, expressions emit
+	* `{expr}` with two-space continuation indent, and ESM values emit
+	* verbatim. A tree containing any MDX node additionally escapes `{` in
+	* text — MDX makes it significant — while a tree with none serializes
+	* byte-identically to the table above.
+	*
+	* To *normalize* a document to different choices — a `-` list rewritten to
+	* `*`, setext headings rewritten to ATX — use `MarkdownFormat` with
+	* `MarkdownFormattingOptions`. That is the configurable surface; this one
+	* deliberately is not.
+	*
 	* Failure is rare by design, symmetric with parse: only a hardening-guard
 	* trip on a tree nesting past the depth cap fails, and only synthesized
 	* or decoded trees can nest that far.
@@ -220,6 +354,18 @@ var Markdown = class Markdown {
 	* {@link Markdown.stringifyResult} — synchronous callers can use that
 	* variant directly.
 	*
+	* @remarks
+	* The canonical form is a **stability commitment** and safe to assert
+	* against byte-for-byte; the choices it makes, and the reason changing one
+	* is a breaking change, are documented on
+	* {@link Markdown.stringifyResult}.
+	*
+	* **Fidelity fields must be set on the DECODED tree.** `Mdast.fromMdast`
+	* admits spec mdast and strips everything outside it, so a `fenceChar`,
+	* `headingStyle`, `markerChar` or `delimiter` placed on a plain mdast tree
+	* before admission is silently dropped and the canonical default applies.
+	* Set them on the nodes that come back.
+	*
 	* @param root - The document tree to serialize.
 	* @returns An `Effect` that succeeds with markdown source, or fails with
 	*   {@link MarkdownStringifyError}.

package/MarkdownDocument.js

@@ -1,8 +1,8 @@
 import { MarkdownRange } from "./MarkdownEdit.js";
 import { Definition, Root } from "./MarkdownNode.js";
+import { scanFrontmatter } from "./internal/blocks/frontmatter.js";
 import { preprocessLines } from "./internal/preprocess.js";
 import { normalizeLabelText } from "./internal/references.js";
-import { scanFrontmatter } from "./internal/blocks/frontmatter.js";
 import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
 import { parsePassResult } from "./Markdown.js";
 import { Effect, Result, Schema } from "effect";
@@ -115,7 +115,8 @@ const phrasingText = (nodes) => {
 		case "strong":
 		case "delete":
 		case "link":
-		case "linkReference": out += phrasingText(node.children);
+		case "linkReference":
+		case "mdxJsxTextElement": out += phrasingText(node.children);
 	}
 	return out;
 };
@@ -275,7 +276,7 @@ var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocu
 					offset: start,
 					length: boundary - start
 				}),
-				children: blocks.slice(current.index + 1, end).filter((child) => child.type !== "frontmatter"),
+				children: blocks.slice(current.index + 1, end).filter((child) => child.type !== "frontmatter" && child.type !== "mdxjsEsm"),
 				text: phrasingText(block.children),
 				bodyRange: MarkdownRange.make({
 					offset: bodyStart,

package/MarkdownNode.js

@@ -324,6 +324,8 @@ const PhrasingContent = Schema.suspend(() => Schema.Union([
 	InlineCode,
 	Link,
 	LinkReference,
+	MdxJsxTextElement,
+	MdxTextExpression,
 	Strong,
 	Text
 ]));
@@ -567,6 +569,8 @@ const FlowContent = Schema.suspend(() => Schema.Union([
 	Heading,
 	Html,
 	List,
+	MdxFlowExpression,
+	MdxJsxFlowElement,
 	Paragraph,
 	Table,
 	ThematicBreak
@@ -581,6 +585,147 @@ const FlowContent = Schema.suspend(() => Schema.Union([
 */
 const ListContent = Schema.suspend(() => Schema.Union([ListItem]));
 /**
+* MdxJsxAttributeValueExpression — a JSX attribute value written as an
+* expression (`<a b={c} />`); `value` holds the expression source text
+* between the braces, never evaluated or parsed.
+*
+* The primary construction path is a JSON-encoded prop:
+* `MdxJsxAttributeValueExpression.make({ value: JSON.stringify(props) })`.
+*
+* @public
+*/
+var MdxJsxAttributeValueExpression = class extends Schema.Class("MdxJsxAttributeValueExpression")({
+	type: Schema.tag("mdxJsxAttributeValueExpression"),
+	value: Schema.String,
+	position: NodePosition
+}) {};
+/**
+* MdxJsxAttribute — a named JSX attribute (`<a b="c" />`). `value` is a
+* string literal, a {@link MdxJsxAttributeValueExpression}, or — for a
+* boolean attribute (`<a b />`) — absent or `null`, both of which the
+* mdast-util-mdx-jsx contract spells (its parser writes `null`; absence is
+* the constructed-tree spelling). The serializer treats the two identically.
+*
+* `name` must be non-empty — an attribute without a name has no MDX spelling,
+* so the schema refuses it at construction and decode (the oracle's
+* serialize-time crash, moved to the admission boundary).
+*
+* @public
+*/
+var MdxJsxAttribute = class extends Schema.Class("MdxJsxAttribute")(Schema.Struct({
+	type: Schema.tag("mdxJsxAttribute"),
+	name: Schema.String,
+	value: Schema.optionalKey(Schema.NullOr(Schema.Union([MdxJsxAttributeValueExpression, Schema.String]))),
+	position: NodePosition
+}).pipe(Schema.check(Schema.makeFilter((attribute) => attribute.name.length === 0 ? "an MDX JSX attribute requires a non-empty name" : void 0)))) {};
+/**
+* MdxJsxExpressionAttribute — a JSX attribute written whole as an expression
+* (`<a {...b} />`); `value` holds the expression source text between the
+* braces.
+*
+* @public
+*/
+var MdxJsxExpressionAttribute = class extends Schema.Class("MdxJsxExpressionAttribute")({
+	type: Schema.tag("mdxJsxExpressionAttribute"),
+	value: Schema.String,
+	position: NodePosition
+}) {};
+/**
+* The union of every node that may appear in a JSX element's `attributes`
+* array. A real `Schema.Union` for the construction pass-through documented
+* on `RowContent`.
+*
+* Attribute carriers are node-shaped values — they carry `type` and
+* `position` per the mdast-util-mdx-jsx contract — but they are **not tree
+* content**: they never appear in a `children` array, so they are excluded
+* from `MarkdownNode` and invisible to the visitor and to
+* `MarkdownDocument.find`.
+*
+* @public
+*/
+const MdxJsxAttributeContent = Schema.Union([MdxJsxAttribute, MdxJsxExpressionAttribute]);
+/**
+* MdxJsxFlowElement — a JSX element in flow (block) position (`<Component />`
+* on its own lines). `name` is `null` for a fragment (`<></>`); children are
+* flow content, per the oracle's `BlockContent | DefinitionContent` model.
+*
+* A fragment cannot carry attributes — that shape has no MDX spelling — so
+* the schema refuses it at construction and decode. A **named** element's
+* name must be non-empty on the same terms: `""` has no MDX spelling either
+* (the oracle's parser only ever produces a real name or `null`, and its
+* serializer treats a falsy name as the fragment), so `null` is the one
+* fragment spelling and the empty string fails typed.
+*
+* @public
+*/
+var MdxJsxFlowElement = class extends Schema.Class("MdxJsxFlowElement")(Schema.Struct({
+	type: Schema.tag("mdxJsxFlowElement"),
+	name: Schema.NullOr(Schema.String),
+	attributes: Schema.Array(MdxJsxAttributeContent),
+	children: Schema.Array(Schema.suspend(() => FlowContent)),
+	position: NodePosition
+}).pipe(Schema.check(Schema.makeFilter((element) => {
+	if (element.name !== null && element.name.length === 0) return "an MDX JSX element requires a non-empty name (`null` is the fragment spelling)";
+	return element.name === null && element.attributes.length > 0 ? "an MDX JSX fragment cannot carry attributes" : void 0;
+})))) {};
+/**
+* MdxJsxTextElement — a JSX element in text (phrasing) position
+* (`a <b>c</b> d`). `name` is `null` for a fragment; children are phrasing
+* content. Refuses attributes on a fragment and an empty-string name, on the
+* same terms as {@link MdxJsxFlowElement}.
+*
+* @public
+*/
+var MdxJsxTextElement = class extends Schema.Class("MdxJsxTextElement")(Schema.Struct({
+	type: Schema.tag("mdxJsxTextElement"),
+	name: Schema.NullOr(Schema.String),
+	attributes: Schema.Array(MdxJsxAttributeContent),
+	children: Schema.Array(Schema.suspend(() => PhrasingContent)),
+	position: NodePosition
+}).pipe(Schema.check(Schema.makeFilter((element) => {
+	if (element.name !== null && element.name.length === 0) return "an MDX JSX element requires a non-empty name (`null` is the fragment spelling)";
+	return element.name === null && element.attributes.length > 0 ? "an MDX JSX fragment cannot carry attributes" : void 0;
+})))) {};
+/**
+* MdxFlowExpression — an expression in flow (block) position (`{a + b}` on
+* its own lines); `value` holds the expression source text between the
+* braces.
+*
+* @public
+*/
+var MdxFlowExpression = class extends Schema.Class("MdxFlowExpression")({
+	type: Schema.tag("mdxFlowExpression"),
+	value: Schema.String,
+	position: NodePosition
+}) {};
+/**
+* MdxTextExpression — an expression in text (phrasing) position
+* (`a {b} c`); `value` holds the expression source text between the braces.
+*
+* @public
+*/
+var MdxTextExpression = class extends Schema.Class("MdxTextExpression")({
+	type: Schema.tag("mdxTextExpression"),
+	value: Schema.String,
+	position: NodePosition
+}) {};
+/**
+* MdxjsEsm — an MDX ESM block (`import`/`export` statements); `value` holds
+* the statement source verbatim.
+*
+* Only ever a child of {@link Root}, per the mdast-util-mdxjs-esm content
+* registration — ESM cannot nest inside a JSX element or any other
+* container. As with the frontmatter head node, the constraint is structural
+* (the `Root` children union admits it, no other union does), not validated.
+*
+* @public
+*/
+var MdxjsEsm = class extends Schema.Class("MdxjsEsm")({
+	type: Schema.tag("mdxjsEsm"),
+	value: Schema.String,
+	position: NodePosition
+}) {};
+/**
 * The frontmatter formats the capture recognizes, keyed by their opening
 * fence: `---` is yaml, `+++` is toml and `---json` is json.
 *
@@ -631,13 +776,18 @@ const FrontmatterContent = Schema.suspend(() => Frontmatter);
 * mdast leaves a root's content model open; a parsed markdown document is
 * flow content, optionally headed by one {@link Frontmatter} node — mdast's
 * `FlowContentFrontmatter` merge, which admits frontmatter at the root and
-* nowhere else.
+* nowhere else. {@link MdxjsEsm} is likewise admitted at the root and nowhere
+* else, per mdast-util-mdxjs-esm's `RootContentMap` registration.
 *
 * @public
 */
 var Root = class extends Schema.Class("Root")({
 	type: Schema.tag("root"),
-	children: Schema.Array(Schema.suspend(() => Schema.Union([Frontmatter, FlowContent]))),
+	children: Schema.Array(Schema.suspend(() => Schema.Union([
+		Frontmatter,
+		MdxjsEsm,
+		FlowContent
+	]))),
 	position: NodePosition
 }) {};
 /**
@@ -650,10 +800,11 @@ const MarkdownNode = Schema.suspend(() => Schema.Union([
 	FrontmatterContent,
 	FlowContent,
 	ListContent,
+	MdxjsEsm,
 	PhrasingContent,
 	RowContent,
 	TableContent
 ]));
 
 //#endregion
-export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterFormat, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, MarkdownNode, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar };
+export { Blockquote, Break, BreakStyle, BulletChar, Code, Definition, Delete, Emphasis, EmphasisChar, FenceChar, FlowContent, FootnoteDefinition, FootnoteReference, Frontmatter, FrontmatterContent, FrontmatterFormat, Heading, HeadingDepth, HeadingStyle, Html, Image, ImageReference, InlineCode, Link, LinkReference, List, ListContent, ListDelimiter, ListItem, MarkdownNode, MdxFlowExpression, MdxJsxAttribute, MdxJsxAttributeContent, MdxJsxAttributeValueExpression, MdxJsxExpressionAttribute, MdxJsxFlowElement, MdxJsxTextElement, MdxTextExpression, MdxjsEsm, Paragraph, PhrasingContent, Point, Position, ReferenceType, Root, RowContent, Strong, Table, TableAlign, TableCell, TableContent, TableRow, Text, ThematicBreak, ThematicBreakChar };