@markuplint/mdx-parser 5.0.0-alpha.0

package/ARCHITECTURE.md

@@ -0,0 +1,212 @@
+# @markuplint/mdx-parser
+
+## Overview
+
+`@markuplint/mdx-parser` parses MDX (`.mdx`) files for markuplint. MDX combines Markdown with JSX, allowing React components, JavaScript expressions, and ES module imports/exports alongside Markdown content. This parser converts both JSX elements and Markdown constructs into markuplint's AST, enabling lint rules to work on MDX documents.
+
+## Design Decisions
+
+### Why extend `MarkdownAwareParser`?
+
+Both plain Markdown and MDX share the same Markdown constructs (headings, links, images, lists, emphasis, etc.). The `MarkdownAwareParser` base class (from `@markuplint/markdown-parser`) provides shared conversion logic for these constructs. The MDX parser adds:
+
+1. **JSX element handling** -- `mdxJsxFlowElement`/`mdxJsxTextElement` mapped to `MLASTElement`
+2. **Expression handling** -- `{expr}` mapped to psblock nodes
+3. **ESM handling** -- `import`/`export` mapped to psblock nodes
+4. **JSX-specific options** -- XML-style end tags, booleanish attributes, case-sensitive tag names
+
+### MDX JSX vs HTML
+
+| Aspect            | Markdown HTML             | MDX JSX                             |
+| ----------------- | ------------------------- | ----------------------------------- |
+| Self-closing tags | Optional (`<br>`)         | Required (`<br />`)                 |
+| Comments          | `<!-- comment -->`        | `{/* comment */}`                   |
+| Attribute names   | HTML (`class`, `for`)     | JSX (`className`, `htmlFor`)        |
+| Attribute values  | Strings only (`data="x"`) | Strings or expressions (`data={x}`) |
+| Components        | Not supported             | `<MyComponent />`                   |
+
+### Why `remark-parse` + `remark-mdx` (not `@mdx-js/mdx`)?
+
+`@mdx-js/mdx` internally wraps `remark-parse` + `remark-mdx` and adds ~24 unnecessary dependencies for JS compilation that markuplint doesn't need. The parse-stage mdast is identical either way.
+
+### MDX v2/v3 only (not v1)
+
+MDX v1 uses a fundamentally different parser architecture with no shared code. Since v1 is deprecated and the ecosystem has migrated, we target v2/v3 only.
+
+### No `@markuplint/mdx-spec` package needed
+
+MDX uses React JSX syntax. The existing `@markuplint/react-spec` provides JSX attribute mappings:
+
+```json
+{
+  "parser": { "\\.mdx$": "@markuplint/mdx-parser" },
+  "specs": { "\\.mdx$": "@markuplint/react-spec" }
+}
+```
+
+## How It Works
+
+```
+.mdx source file
+    |
+    v
+[remark-parse + remark-gfm + remark-mdx + remark-frontmatter]
+    |
+    v
+[collectDefinitions()]       Extract [id]: url definitions
+    |
+    v
+[flattenMdastChildren()]     Unwrap JSX elements from paragraph wrappers
+    |
+    v
+[nodeize() per mdast node]
+    |
+    +-- mdxJsxFlowElement   -->  MLASTElement via parseCodeFragment
+    +-- mdxJsxTextElement   -->  MLASTElement via parseCodeFragment
+    +-- mdxFlowExpression   -->  psblock
+    +-- mdxTextExpression   -->  psblock
+    +-- mdxjsEsm            -->  psblock (import/export)
+    +-- heading             -->  h1-h6 element (via MarkdownAwareParser)
+    +-- paragraph           -->  p element
+    +-- emphasis/strong     -->  em/strong elements
+    +-- link/image          -->  a/img elements with attributes
+    +-- list/listItem       -->  ul/ol > li elements
+    +-- blockquote          -->  blockquote element
+    +-- inlineCode/code     -->  code / pre>code elements
+    +-- table/row/cell      -->  table > tr > th/td elements
+    +-- delete (GFM)        -->  del element
+    +-- linkReference       -->  a element (resolved) or psblock
+    +-- imageReference      -->  img element (resolved) or psblock
+    +-- text                -->  MLASTText
+    +-- yaml                -->  psblock (#ps:yaml)
+    +-- html (rare in MDX)  -->  parseCodeFragment
+    v
+MLASTDocument
+```
+
+### Class Hierarchy
+
+```
+Parser<MdastNode>               (from @markuplint/parser-utils)
+  |
+  MarkdownAwareParser           (from @markuplint/markdown-parser)
+    |                            - Shared Markdown-to-HTML conversion
+    |
+    MDXParser                   (this package)
+      |                          - tokenize(): remark-parse + remark-gfm + remark-mdx
+      |                          - nodeize(): MDX types first, then Markdown delegation
+      |                          - #visitJsxElement(): JSX -> MLASTElement
+      |                          - visitAttr(): JSX attribute handling (quoteSet, dynamic value)
+      |                          - detectElementType(): uppercase/dot = authored
+```
+
+### Paragraph Flattening
+
+MDX's remark-mdx wraps inline JSX elements in `paragraph` nodes:
+
+```mdx
+Text with <Badge>inline</Badge> component.
+```
+
+produces a `paragraph` containing `text`, `mdxJsxTextElement`, `text`. The `flattenMdastChildren()` function detects paragraphs containing JSX and unwraps their children to the top level, ensuring JSX elements are directly accessible.
+
+Pure Markdown paragraphs (no JSX) are kept as-is and converted to `<p>` elements.
+
+### JSX Element Handling
+
+JSX elements are parsed via `parseCodeFragment()` with `namelessFragment: true`:
+
+1. **Self-closing** (`<Component prop="val" />`): entire token is the start tag
+2. **With children** (`<Card>...</Card>`): split into start tag token + children + end tag token
+3. **Fragments** (`<>...</>`): produce `#jsx-fragment` nodes
+
+The start tag is parsed by `parseCodeFragment` to extract attributes, then `visitElement()` wires up children.
+
+### JSX Attribute Handling
+
+| Attribute Form     | Example                    | Mapping                  |
+| ------------------ | -------------------------- | ------------------------ |
+| String value       | `name="email"`             | Standard attribute       |
+| Expression value   | `data={value}`             | `isDynamicValue: true`   |
+| Object expression  | `style={{ color: "red" }}` | `isDynamicValue: true`   |
+| Boolean (no value) | `disabled`                 | Empty value (booleanish) |
+| Spread             | `{...props}`               | `type: 'spread'`         |
+
+IDL attribute mapping (`className` -> `class`, `htmlFor` -> `for`) is handled at the core level by `MLAttr` when paired with `@markuplint/react-spec` (which sets `useIDLAttributeNames: true`).
+
+### Component Detection
+
+| Tag               | `detectElementType()` | Example                     |
+| ----------------- | --------------------- | --------------------------- |
+| `<div>`           | `html`                | Native HTML element         |
+| `<MyComponent>`   | `authored`            | React component             |
+| `<Layout.Header>` | `authored`            | Member expression component |
+| `<x-widget>`      | `web-component`       | Custom element              |
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph upstream ["Upstream"]
+        parserUtils["@markuplint/parser-utils\n(Parser)"]
+        mdParser["@markuplint/markdown-parser\n(MarkdownAwareParser)"]
+        remark["remark-parse + remark-gfm\n(Markdown + GFM)"]
+        remarkMdx["remark-mdx\n(MDX syntax extensions)"]
+        remarkFm["remark-frontmatter\n(Front matter support)"]
+    end
+
+    subgraph pkg ["@markuplint/mdx-parser"]
+        mdxParser["MDXParser\nextends MarkdownAwareParser"]
+        flatten["flattenMdastChildren()\nparagraph unwrapping"]
+        jsxVisit["#visitJsxElement()\nJSX -> MLASTElement"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core\n(MLASTDocument -> MLDOM)"]
+        reactSpec["@markuplint/react-spec\n(JSX attribute specs)"]
+    end
+
+    parserUtils -->|"base utilities"| mdParser
+    mdParser -->|"MarkdownAwareParser"| mdxParser
+    remark -->|"mdast AST"| mdxParser
+    remarkMdx -->|"MDX node types"| mdxParser
+    remarkFm -->|"front matter"| mdxParser
+    mdxParser --> flatten --> jsxVisit
+    mdxParser -->|"MLASTDocument"| mlCore
+    reactSpec -->|"JSX attribute mapping"| mlCore
+```
+
+## External Dependencies
+
+| Dependency                    | Purpose                                       |
+| ----------------------------- | --------------------------------------------- |
+| `@markuplint/markdown-parser` | MarkdownAwareParser base class                |
+| `@markuplint/ml-ast`          | AST type definitions                          |
+| `@markuplint/parser-utils`    | Parser utilities                              |
+| `unified`                     | Processor pipeline for remark                 |
+| `remark-parse`                | Markdown -> mdast parser                      |
+| `remark-gfm`                  | GFM extensions (tables, strikethrough)        |
+| `remark-mdx`                  | MDX syntax extensions (JSX, expressions, ESM) |
+| `remark-frontmatter`          | Front matter (YAML) support                   |
+
+## Directory Structure
+
+```
+src/
++-- index.ts              -- Re-exports parser instance
++-- parser.ts             -- MDXParser class, flattenMdastChildren helper
++-- index.spec.ts         -- Unit and integration tests
+```
+
+## Relationship to @markuplint/markdown-parser
+
+Both parsers share `MarkdownAwareParser` as a common base class:
+
+| Aspect          | markdown-parser (.md)      | mdx-parser (.mdx)                  |
+| --------------- | -------------------------- | ---------------------------------- |
+| Base class      | MarkdownAwareParser        | MarkdownAwareParser                |
+| HTML regions    | HtmlParser re-parse        | parseCodeFragment (XML-style)      |
+| JSX support     | No                         | Yes (components, expressions, ESM) |
+| Attribute style | HTML (`class`, `for`)      | JSX (`className`, `htmlFor`)       |
+| Tag closing     | HTML rules (void elements) | XML rules (self-closing required)  |
+| Spec package    | None needed                | `@markuplint/react-spec`           |

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
+
+### Features
+
+- **mdx-parser:** add MDX parser for markuplint ([a097250](https://github.com/markuplint/markuplint/commit/a0972504aac1317cda5b2e6f0b2f3a1d7bc578fd))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2024 Yusuke Hirao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,43 @@
+# @markuplint/mdx-parser
+
+[![npm version](https://badge.fury.io/js/%40markuplint%2Fmdx-parser.svg)](https://www.npmjs.com/package/@markuplint/mdx-parser)
+
+[**MDX**](https://mdxjs.com/) ファイルで **markuplint** を使用するためのパーサーです。
+
+JSX 要素、式、import/export を標準的な Markdown コンテンツと併せてパースします。Markdown 構文は対応する HTML 要素に変換され、markuplint のルールで解析できるようになります。[GFM](https://github.github.com/gfm/)（テーブル、取り消し線、オートリンク）および YAML フロントマターをサポートしています。
+
+## インストール
+
+```shell
+$ npm install -D @markuplint/mdx-parser
+
+$ yarn add -D @markuplint/mdx-parser
+```
+
+## 使い方
+
+[設定ファイル](https://markuplint.dev/configuration/#properties/parser)に `parser` と `specs` オプションを追加してください。
+
+```json
+{
+  "parser": {
+    ".mdx$": "@markuplint/mdx-parser"
+  },
+  "specs": {
+    ".mdx$": "@markuplint/react-spec"
+  }
+}
+```
+
+## 機能
+
+- **JSX 要素**: 自己閉じ（`<Badge />`）とコンテナ（`<Card>...</Card>`）の両方のコンポーネントに対応
+- **IDL 属性変換**: React スタイルの属性（例: `className`、`htmlFor`）を対応する HTML 属性に変換
+- **式**: `{variable}` や `{condition ? a : b}` を動的な値として扱う
+- **ESM import/export**: `import` 文と `export` 文をブロックとして認識
+- **JSX 内の Markdown**: JSX コンテナ内の Markdown コンテンツを再帰的にパース
+
+## 既知の制限事項
+
+- **MDX v2/v3 のみ**: MDX v1 構文はサポートされていません。
+- **合成された属性位置**: Markdown 構文から導出された属性（例: `[テキスト](url)` の `href`）は、属性値の正確な文字位置ではなく、Markdown 構文全体のソース位置を共有します。

package/README.md

@@ -0,0 +1,43 @@
+# @markuplint/mdx-parser
+
+[![npm version](https://badge.fury.io/js/%40markuplint%2Fmdx-parser.svg)](https://www.npmjs.com/package/@markuplint/mdx-parser)
+
+Use **markuplint** with [**MDX**](https://mdxjs.com/) files.
+
+Parses JSX elements, expressions, and imports alongside standard Markdown content. Markdown constructs are converted to their corresponding HTML elements so that markuplint rules can analyze them. Supports [GFM](https://github.github.com/gfm/) (tables, strikethrough, autolinks) and YAML frontmatter.
+
+## Install
+
+```shell
+$ npm install -D @markuplint/mdx-parser
+
+$ yarn add -D @markuplint/mdx-parser
+```
+
+## Usage
+
+Add `parser` and `specs` options to your [configuration](https://markuplint.dev/configuration/#properties/parser).
+
+```json
+{
+  "parser": {
+    ".mdx$": "@markuplint/mdx-parser"
+  },
+  "specs": {
+    ".mdx$": "@markuplint/react-spec"
+  }
+}
+```
+
+## Features
+
+- **JSX elements**: Both self-closing (`<Badge />`) and container (`<Card>...</Card>`) components
+- **IDL attribute conversion**: When paired with `@markuplint/react-spec`, React-style attributes (e.g., `className`, `htmlFor`) are mapped to their HTML equivalents
+- **Expressions**: `{variable}` and `{condition ? a : b}` are treated as dynamic values
+- **ESM imports/exports**: `import` and `export` statements are recognized as blocks
+- **Markdown inside JSX**: Markdown content within JSX containers is recursively parsed
+
+## Known Limitations
+
+- **MDX v2/v3 only**: MDX v1 syntax is not supported.
+- **Synthesized attribute positions**: Attributes derived from Markdown syntax (e.g., `href` from `[text](url)`) share the source position of the enclosing Markdown construct rather than pointing to the exact character range of the attribute value.

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @module @markuplint/mdx-parser
+ */
+export { parser } from './parser.js';

package/lib/index.js

@@ -0,0 +1,4 @@
+/**
+ * @module @markuplint/mdx-parser
+ */
+export { parser } from './parser.js';

package/lib/parser.d.ts

@@ -0,0 +1,64 @@
+import type { MLASTNodeTreeItem, MLASTParentNode } from '@markuplint/ml-ast';
+import type { Token } from '@markuplint/parser-utils';
+import type { RootContent } from 'mdast';
+import { MarkdownAwareParser } from '@markuplint/markdown-parser';
+type MdastNode = RootContent;
+/**
+ * Parser for MDX files that maps JSX elements to markuplint's AST.
+ *
+ * Uses remark-parse + remark-mdx to produce an MDX-extended mdast,
+ * then converts JSX elements to MLASTElement nodes and delegates
+ * Markdown content to the shared MarkdownAwareParser base class.
+ */
+declare class MDXParser extends MarkdownAwareParser {
+    #private;
+    constructor();
+    /**
+     * Tokenizes the raw MDX source into an mdast tree.
+     *
+     * Resets parser state, parses via remark (with GFM, MDX, and frontmatter
+     * plugins), collects link/image reference definitions, and flattens
+     * JSX elements out of paragraph wrappers.
+     *
+     * @returns The flattened mdast children and fragment flag.
+     */
+    tokenize(): {
+        ast: RootContent[];
+        isFragment: boolean;
+    };
+    /**
+     * Converts a single mdast node into markuplint AST nodes.
+     *
+     * Handles MDX-specific nodes (JSX elements, expressions, ESM imports/exports)
+     * first, then delegates to the shared `nodeizeMarkdownNode()` for common
+     * Markdown constructs.
+     *
+     * @param originNode - The mdast node to convert.
+     * @param parentNode - Parent AST node, or `null` for top-level.
+     * @param depth - Current nesting depth.
+     * @returns An array of markuplint AST nodes.
+     */
+    nodeize(originNode: MdastNode, parentNode: MLASTParentNode | null, depth: number): readonly MLASTNodeTreeItem[];
+    /**
+     * Processes a JSX attribute token with dynamic value detection.
+     * IDL attribute name mapping is now handled declaratively by the spec's
+     * useIDLAttributeNames and ml-core's attr resolution.
+     *
+     * @param token - The raw attribute token from the source.
+     * @returns The processed attribute node.
+     */
+    visitAttr(token: Token): (import("@markuplint/ml-ast").MLASTHTMLAttr & {
+        __rightText?: string;
+    }) | (import("@markuplint/ml-ast").MLASTSpreadAttr & {
+        __rightText?: string;
+    });
+    /**
+     * MDX components use uppercase or dot notation following React's convention.
+     *
+     * @param nodeName - The element name to classify.
+     * @returns The element type (`'html'` or `'authored'`).
+     */
+    detectElementType(nodeName: string): import("@markuplint/ml-ast").ElementType;
+}
+export declare const parser: MDXParser;
+export {};

package/lib/parser.js

@@ -0,0 +1,260 @@
+import { MarkdownAwareParser } from '@markuplint/markdown-parser';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkMdx from 'remark-mdx';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+/**
+ * Parser for MDX files that maps JSX elements to markuplint's AST.
+ *
+ * Uses remark-parse + remark-mdx to produce an MDX-extended mdast,
+ * then converts JSX elements to MLASTElement nodes and delegates
+ * Markdown content to the shared MarkdownAwareParser base class.
+ */
+class MDXParser extends MarkdownAwareParser {
+    constructor() {
+        super({
+            endTagType: 'xml',
+            booleanish: true,
+            tagNameCaseSensitive: true,
+        });
+    }
+    /**
+     * Tokenizes the raw MDX source into an mdast tree.
+     *
+     * Resets parser state, parses via remark (with GFM, MDX, and frontmatter
+     * plugins), collects link/image reference definitions, and flattens
+     * JSX elements out of paragraph wrappers.
+     *
+     * @returns The flattened mdast children and fragment flag.
+     */
+    tokenize() {
+        this.resetMarkdownState();
+        const processor = unified().use(remarkParse).use(remarkGfm).use(remarkMdx).use(remarkFrontmatter, ['yaml']);
+        const mdast = processor.parse(this.rawCode);
+        this.collectDefinitions(mdast.children);
+        return {
+            ast: flattenMdastChildren(mdast.children),
+            isFragment: true,
+        };
+    }
+    /**
+     * Converts a single mdast node into markuplint AST nodes.
+     *
+     * Handles MDX-specific nodes (JSX elements, expressions, ESM imports/exports)
+     * first, then delegates to the shared `nodeizeMarkdownNode()` for common
+     * Markdown constructs.
+     *
+     * @param originNode - The mdast node to convert.
+     * @param parentNode - Parent AST node, or `null` for top-level.
+     * @param depth - Current nesting depth.
+     * @returns An array of markuplint AST nodes.
+     */
+    nodeize(
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    originNode, parentNode, depth) {
+        const position = originNode.position;
+        if (!position) {
+            return [];
+        }
+        const offset = position.start.offset ?? 0;
+        const endOffset = position.end.offset ?? offset;
+        const token = this.sliceFragment(offset, endOffset);
+        // MDX-specific node types first
+        switch (originNode.type) {
+            case 'mdxJsxFlowElement':
+            case 'mdxJsxTextElement': {
+                return this.#visitJsxElement(originNode, token, depth, parentNode);
+            }
+            case 'mdxFlowExpression':
+            case 'mdxTextExpression': {
+                return this.visitPsBlock({
+                    ...token,
+                    depth,
+                    parentNode,
+                    nodeName: originNode.type,
+                    isFragment: false,
+                });
+            }
+            case 'mdxjsEsm': {
+                return this.visitPsBlock({
+                    ...token,
+                    depth,
+                    parentNode,
+                    nodeName: 'mdxjsEsm',
+                    isFragment: false,
+                });
+            }
+        }
+        // Try common Markdown node handling
+        const result = this.nodeizeMarkdownNode(originNode, token, offset, endOffset, depth, parentNode);
+        if (result !== null) {
+            return result;
+        }
+        switch (originNode.type) {
+            case 'text': {
+                return this.visitText({
+                    ...token,
+                    depth,
+                    parentNode,
+                });
+            }
+            case 'html': {
+                return this.parseCodeFragment({
+                    ...token,
+                    depth,
+                    parentNode,
+                });
+            }
+            default: {
+                // Unhandled node types fallback to psblock
+                return this.visitPsBlock({
+                    ...token,
+                    depth,
+                    parentNode,
+                    nodeName: originNode.type,
+                    isFragment: false,
+                });
+            }
+        }
+    }
+    /**
+     * Processes a JSX attribute token with dynamic value detection.
+     * IDL attribute name mapping is now handled declaratively by the spec's
+     * useIDLAttributeNames and ml-core's attr resolution.
+     *
+     * @param token - The raw attribute token from the source.
+     * @returns The processed attribute node.
+     */
+    visitAttr(token) {
+        const attr = super.visitAttr(token, {
+            quoteSet: [
+                { start: '"', end: '"', type: 'string' },
+                { start: "'", end: "'", type: 'string' },
+                { start: '{', end: '}', type: 'script' },
+            ],
+        });
+        if (attr.type === 'spread') {
+            return attr;
+        }
+        if (attr.startQuote.raw === '{' && attr.endQuote.raw === '}') {
+            this.updateAttr(attr, {
+                isDynamicValue: true,
+            });
+        }
+        return attr;
+    }
+    /**
+     * MDX components use uppercase or dot notation following React's convention.
+     *
+     * @param nodeName - The element name to classify.
+     * @returns The element type (`'html'` or `'authored'`).
+     */
+    detectElementType(nodeName) {
+        return super.detectElementType(nodeName, /^[A-Z]|\./);
+    }
+    /**
+     * Visits a JSX element from the mdast, computing start tag and end tag
+     * positions from the element's children and delegating to visitElement.
+     */
+    #visitJsxElement(
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+    originNode, token, depth, parentNode) {
+        const children = originNode.children;
+        const isSelfClosing = token.raw.trimEnd().endsWith('/>');
+        if (isSelfClosing || children.length === 0) {
+            // Self-closing or empty element: the whole token is the start tag
+            const parsedNodes = this.parseCodeFragment({
+                ...token,
+                depth,
+                parentNode,
+            }, { namelessFragment: true });
+            const startTag = parsedNodes.at(0);
+            if (!startTag || startTag.type !== 'starttag') {
+                return this.visitPsBlock({
+                    ...token,
+                    depth,
+                    parentNode,
+                    nodeName: originNode.type,
+                    isFragment: false,
+                });
+            }
+            return super.visitElement(startTag, [], {
+                namelessFragment: true,
+                createEndTagToken: () => null,
+            });
+        }
+        // Element with children: split into start tag + children + end tag
+        const firstChild = children[0];
+        const lastChild = children.at(-1);
+        const firstChildOffset = firstChild?.position?.start.offset ?? token.offset + token.raw.length;
+        const lastChildEndOffset = lastChild?.position?.end.offset ?? firstChildOffset;
+        const elementEndOffset = originNode.position?.end.offset ?? 0;
+        const startTagToken = this.sliceFragment(token.offset, firstChildOffset);
+        const parsedNodes = this.parseCodeFragment({
+            ...startTagToken,
+            depth,
+            parentNode,
+        }, { namelessFragment: true });
+        const startTag = parsedNodes.at(0);
+        if (!startTag || startTag.type !== 'starttag') {
+            return this.visitPsBlock({
+                ...token,
+                depth,
+                parentNode,
+                nodeName: originNode.type,
+                isFragment: false,
+            });
+        }
+        return super.visitElement(startTag, [...children], {
+            namelessFragment: true,
+            createEndTagToken: () => {
+                if (lastChildEndOffset >= elementEndOffset) {
+                    return null;
+                }
+                const endTagToken = this.sliceFragment(lastChildEndOffset, elementEndOffset);
+                if (!endTagToken.raw.trim()) {
+                    return null;
+                }
+                return {
+                    ...endTagToken,
+                    depth,
+                    parentNode,
+                };
+            },
+        });
+    }
+}
+/**
+ * Flattens top-level mdast children by extracting JSX elements
+ * from paragraph wrappers so they appear at the top level.
+ *
+ * Only inspects direct children of root; does not recurse into nested nodes.
+ * Position information of unwrapped children is preserved from the original mdast.
+ *
+ * @param children - The root-level mdast children to process.
+ * @returns A new array with JSX-containing paragraphs unwrapped.
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function flattenMdastChildren(children) {
+    const result = [];
+    for (const child of children) {
+        if (child.type === 'paragraph' && 'children' in child) {
+            const pgChildren = child.children;
+            const hasJsx = pgChildren.some(c => c.type === 'mdxJsxTextElement' || c.type === 'mdxTextExpression');
+            if (hasJsx) {
+                // JSX in paragraph: unwrap all children to top level
+                result.push(...pgChildren);
+            }
+            else {
+                // Pure markdown paragraph: keep as-is
+                result.push(child);
+            }
+        }
+        else {
+            result.push(child);
+        }
+    }
+    return result;
+}
+export const parser = new MDXParser();