@dogsbay/format-mdx 0.2.0-beta.12 → 0.2.0-beta.120

package/dist/parse.js

@@ -8,12 +8,22 @@
  *   4. Parse markdown sections with markdown-it for inline formatting.
  *   5. Map components to TreeNode types.
  *
- * The MDX served by Mintlify/Next.js uses well-formed, XML-like JSX tags with
- * string attributes — no complex JSX expressions. This means a simple recursive
- * tag parser works without a full JSX/AST parser.
+ * The MDX served by Mintlify/Next.js/Fumadocs uses well-formed, XML-like JSX
+ * tags with string attributes — no complex JSX expressions. This means a
+ * simple recursive tag parser works without a full JSX/AST parser.
+ *
+ * Extension points (plans/format-fumadocs.md): the component registry is
+ * open — `parseMdx(source, { adapter, components })` merges
+ * builtins < adapter < per-source config. Unknown block components are
+ * NEVER dropped: they become `mdx-raw` nodes carrying the verbatim source
+ * span plus a fidelity-ledger entry.
  */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
 import MarkdownIt from "markdown-it";
+import { inlineToDogsbayMd } from "@dogsbay/format-dogsbay-md";
 const md = new MarkdownIt({ html: true, linkify: true });
+// ── Built-in component tag → TreeNode type mapping ───────
 const COMPONENT_MAP = {
     // Callouts — map to native Obsidian callout syntax
     Info: { type: "callout", container: true, propsFromAttrs: () => ({ variant: "info" }) },
@@ -21,17 +31,30 @@ const COMPONENT_MAP = {
     Warning: { type: "callout", container: true, propsFromAttrs: () => ({ variant: "warning" }) },
     Note: { type: "callout", container: true, propsFromAttrs: () => ({ variant: "note" }) },
     Danger: { type: "callout", container: true, propsFromAttrs: () => ({ variant: "danger" }) },
+    // Mintlify's success callout. Unmapped it was preserved as raw MDX, so the
+    // exporter stripped the tag and the "this worked" framing was lost; it
+    // surfaced only once snippet inlining exposed the 19 uses inside snippets.
+    Check: { type: "callout", container: true, propsFromAttrs: () => ({ variant: "success" }) },
     Callout: {
         type: "callout", container: true,
-        propsFromAttrs: (attrs) => ({ variant: attrs.type || "note", title: attrs.title }),
+        propsFromAttrs: (attrs) => ({
+            variant: mapCalloutType(attrs.type || "note"),
+            title: attrs.title,
+        }),
     },
     // Tabs
     Tabs: { type: "tabs", container: true },
     Tab: {
         type: "tab", container: true,
-        propsFromAttrs: (attrs) => ({ title: attrs.title || attrs.label || "" }),
+        propsFromAttrs: (attrs) => ({ title: attrs.title || attrs.label || attrs.value || "" }),
     },
     CodeGroup: { type: "tabs", container: true },
+    // Mintlify renders these in a side panel next to an API description; there
+    // is no equivalent anywhere else, and the fenced code inside already carries
+    // its own title (```json Response). Unwrapping keeps the code and loses only
+    // the panel placement — preserving them as raw MDX lost the code entirely.
+    RequestExample: { type: "", container: true, toNode: (_a, inner, ctx) => ctx.parseBlocks(inner) },
+    ResponseExample: { type: "", container: true, toNode: (_a, inner, ctx) => ctx.parseBlocks(inner) },
     // Steps
     Steps: { type: "steps", container: true },
     Step: {
@@ -56,12 +79,16 @@ const COMPONENT_MAP = {
             title: attrs.title || "",
             icon: attrs.icon,
             href: attrs.href,
+            // Fumadocs cards carry their body in a description attr —
+            // dropping it loses real content.
+            description: attrs.description,
         }),
     },
     // Frame (image wrapper with optional caption)
     Frame: {
         type: "figure", container: true,
-        propsFromAttrs: (attrs) => ({ caption: attrs.caption }),
+        // A caption is inline Markdown; Mintlify's is plain text, so it is escaped
+        propsFromAttrs: (attrs) => ({ caption: typeof attrs.caption === "string" ? inlineToDogsbayMd([{ type: "text", text: attrs.caption }]) : attrs.caption }),
     },
     // Strip these — LLM-specific preambles or site-specific interactive widgets
     AgentInstructions: { type: "", container: true, strip: true },
@@ -69,22 +96,278 @@ const COMPONENT_MAP = {
     ContactSalesCard: { type: "", container: true, strip: true },
     InstallConfigurator: { type: "", container: true, strip: true },
 };
+/** Fumadocs/Mintlify callout `type` attr → Dogsbay callout variant. */
+function mapCalloutType(type) {
+    const map = {
+        note: "note",
+        info: "info",
+        tip: "tip",
+        warn: "warning",
+        warning: "warning",
+        error: "danger",
+        danger: "danger",
+        caution: "warning",
+        success: "success",
+    };
+    return map[type.toLowerCase()] ?? "note";
+}
 // Tags we recognize as self-closing (no children)
-const SELF_CLOSING_TAGS = new Set(["Frame", "ContactSalesCard"]);
+// `Frame` is NOT here: it is a CONTAINER. Measured on the real corpora, dub has
+// 818 `<Frame>` opens, 818 `</Frame>` closes and zero self-closing forms;
+// mintlify-docs has 537/526. Declaring it self-closing meant every Frame
+// opened and immediately closed, so its `<img>` fell out as a SIBLING node —
+// producing 818 empty `figure` nodes, 818 "figure had no renderable content"
+// ledger drops that were false, and the loss of the caption↔image pairing.
+// That single wrong entry was the largest line in the export ledger.
+const SELF_CLOSING_TAGS = new Set(["ContactSalesCard"]);
+function buildCtx(opts) {
+    const map = { ...COMPONENT_MAP };
+    const selfClosing = new Set(SELF_CLOSING_TAGS);
+    if (opts?.adapter?.components)
+        Object.assign(map, opts.adapter.components);
+    for (const tag of opts?.adapter?.selfClosingTags ?? [])
+        selfClosing.add(tag);
+    if (opts?.components)
+        Object.assign(map, opts.components);
+    for (const tag of opts?.selfClosingTags ?? [])
+        selfClosing.add(tag);
+    return {
+        map,
+        selfClosing,
+        ledger: [],
+        moduleData: {},
+        imports: {},
+        rootDir: opts?.rootDir,
+        inlining: opts?.inlining ?? new Set(),
+        file: opts?.file,
+    };
+}
 // ── Main parser ──────────────────────────────────────────
-export function mdxToTree(source) {
+/**
+ * Parse MDX into TreeNode[] + fidelity ledger.
+ */
+export function parseMdx(source, opts) {
+    const ctx = buildCtx(opts);
     // Strip LLM preamble (blockquote at top referencing llms.txt)
     let cleaned = stripPreamble(source);
-    // Strip JSX component definitions (export const Foo = () => { ... };)
-    // These are React components embedded in MDX that can't be converted
-    cleaned = stripJsxExports(cleaned);
-    // Parse into a flat list of segments: markdown blocks and component blocks
-    const segments = segmentMdx(cleaned);
-    // Convert segments to TreeNode[]
-    const tree = segmentsToTree(segments);
+    // Adapter raw-text preprocessing (variable substitution, includes, …)
+    if (opts?.adapter?.preprocess) {
+        cleaned = opts.adapter.preprocess(cleaned, { filePath: opts.file });
+    }
+    // Adapter inline transforms (e.g. <Link …>…</Link> → markdown link)
+    cleaned = applyInlineTransforms(cleaned, opts?.adapter);
+    // Drop MDX comments. `{/* … */}` is an expression whose only content is a JS
+    // block comment, so MDX renders NOTHING for it — but we turned each one into
+    // a paragraph of literal source. Mintlify's own docs carry vale directives
+    // (`{/* vale Mintlify.Semicolons = NO */}`) on 42 pages, and every one of
+    // them showed up as visible prose on the rendered site. vale is the standard
+    // docs linter, so this is not a Mintlify quirk.
+    cleaned = stripMdxComments(cleaned);
+    // Strip MDX import statements and export blocks — fence-aware.
+    // Export literals are captured for handlers (same-file data pattern).
+    const stripped = stripMdxStatements(cleaned);
+    cleaned = stripped.source;
+    ctx.moduleData = stripped.moduleData;
+    ctx.imports = stripped.imports;
+    // An `export const X = (props) => (<JSX/>)` is a COMPONENT DEFINITION, and
+    // real docs put real documentation inside one. Stripping it is correct — it
+    // is JavaScript with props interpolated, so it cannot be rendered statically
+    // — but stripping it SILENTLY is not. dub's
+    // `snippets/webhook-response-body-parameters.mdx` is one such export and
+    // nothing else: 888 source chars became a zero-byte page with an empty
+    // ledger, and the four parameters it defines went missing from all 13
+    // webhook and postback pages that include it.
+    for (const [name, literal] of Object.entries(ctx.moduleData)) {
+        if (!/=>/.test(literal) || !/<[A-Za-z]/.test(literal))
+            continue;
+        ctx.ledger.push({
+            component: `export const ${name} (JSX component definition, ${literal.length} chars of content not rendered)`,
+            action: "stripped",
+            line: 0,
+        });
+    }
+    // Collapse block-leading multi-line lowercase-HTML opening tags to one line.
+    cleaned = collapseMultilineHtmlOpenTags(cleaned);
+    cleaned = joinBlankLinesInHtmlBlocks(cleaned);
+    const tree = parseBlocks(cleaned, ctx);
     // Post-process: rewrite links, fix JSX attributes, handle dark mode images
-    postProcess(tree);
-    return tree;
+    postProcess(tree, opts?.linkRedirects ?? {});
+    const grouped = groupTabbedCode(tree);
+    return { tree: grouped, ledger: ctx.ledger, moduleData: ctx.moduleData };
+}
+/**
+ * Back-compat convenience: parse and return only the tree.
+ * Prefer `parseMdx` — it also returns the fidelity ledger.
+ */
+export function mdxToTree(source, opts) {
+    return parseMdx(source, opts).tree;
+}
+/**
+ * Parse an MDX fragment (component children) — no preamble/statement
+ * stripping, shared registry + ledger via ctx.
+ */
+function parseBlocks(source, ctx) {
+    return segmentsToTree(segmentMdx(source, ctx), ctx);
+}
+/**
+ * Remove `{/* … *​/}` MDX comments, fence-aware.
+ *
+ * Only an expression whose ENTIRE body is a block comment is removed: `{foo /*
+ * note *​/}` is a real expression and must survive to the mdx-raw path. When
+ * the comment occupied a whole line, the line goes with it, so no blank
+ * paragraph is left behind.
+ */
+export function stripMdxComments(source) {
+    // Line-based fence tracking rather than a regex split. The regex anchored the
+    // opener at column 0, so an INDENTED fence — a code block inside a list item
+    // or a <Step>, which is everywhere in Mintlify docs — was not protected, and
+    // its comments were stripped. It also let a ``` opener pair with a ~~~ closer
+    // and desynced from there, the same over-greedy-mask bug the Docusaurus
+    // sanitizer notes were written about. An unterminated fence now protects the
+    // remainder of the file rather than exposing it.
+    const out = [];
+    // Prose is buffered and stripped as a BLOCK, never line by line — a comment
+    // may span lines, and per-line stripping would miss it.
+    let prose = [];
+    const flush = () => {
+        if (prose.length === 0)
+            return;
+        out.push(stripCommentsOutsideCode(prose.join("\n")));
+        prose = [];
+    };
+    let fence = null;
+    for (const line of source.split("\n")) {
+        const m = /^\s*(`{3,}|~{3,})/.exec(line);
+        if (fence) {
+            // Only a run of the SAME character, at least as long, closes it.
+            if (m && m[1][0] === fence.char && m[1].length >= fence.len)
+                fence = null;
+            out.push(line);
+            continue;
+        }
+        // A fence INSIDE an open comment is commented-out sample code, not a code
+        // block. Treating it as one flushed the prose buffer mid-comment, so the
+        // comment could never be matched and `{/*`, the sample and `*/}` all
+        // rendered as visible page content — commenting out an example is a
+        // common docs idiom, so this fired on real pages.
+        if (m && !hasOpenComment(prose)) {
+            flush();
+            fence = { char: m[1][0], len: m[1].length };
+            out.push(line);
+            continue;
+        }
+        prose.push(line);
+    }
+    flush();
+    return out.join("\n");
+}
+/**
+ * Inline code spans, replaced with a NUL-delimited index.
+ *
+ * A span may cross lines (CommonMark allows it) but never a BLANK line — that
+ * bound is what stops one unbalanced backtick from pairing with the opener of
+ * a real span two paragraphs later and mis-masking everything between, which
+ * is the parity bug the split-based version had. Restricting spans to a single
+ * line also fixed it, but silently dropped multi-line spans from protection.
+ */
+const CODE_SPAN = /`+(?:[^`\n]|\n(?![ \t]*\n))*`+/g;
+function maskCodeSpans(text) {
+    const spans = [];
+    const masked = text.replace(CODE_SPAN, (m) => {
+        // A multi-line span that swallows a comment CLOSER it did not also open is
+        // almost certainly not a code span at all — it is an unbalanced backtick
+        // inside a comment pairing with one after it. Masking the `*/}` hid the
+        // close, so the comment read as open forever and the next fenced block was
+        // deleted. Leave it unmasked; a real documented span (`{/* x */}`) opens
+        // and closes inside itself and is unaffected.
+        if (m.includes("\n") && m.includes("*/}") && !m.includes("{/*"))
+            return m;
+        spans.push(m);
+        return `\u0000${spans.length - 1}\u0000`;
+    });
+    return { masked, spans };
+}
+/**
+ * Does the buffered prose end with an unclosed `{/*`?
+ *
+ * Masked first: scanning raw text meant a page that merely DOCUMENTS the
+ * syntax (`` `{/*` `` — 49 files in mintlify-docs contain `{/*`) looked like
+ * it had a comment open forever, which disabled fence protection for the rest
+ * of the file and deleted content from real code blocks.
+ */
+function hasOpenComment(prose) {
+    const masked = maskCodeSpans(prose.join("\n")).masked.split("\n");
+    let openLine = -1;
+    for (let i = masked.length - 1; i >= 0; i--) {
+        const line = masked[i];
+        if (line.includes("*/}") && line.lastIndexOf("*/}") > line.lastIndexOf("{/*"))
+            return false;
+        if (line.includes("{/*")) {
+            openLine = i;
+            break;
+        }
+    }
+    if (openLine === -1)
+        return false;
+    // Bounded by a blank line, exactly like the stripper's own regexes: a
+    // comment that has not closed by then is never going to match, so treating
+    // the remainder of the FILE as commented-out un-protected every later fence
+    // and deleted content from real code blocks.
+    return !masked.slice(openLine + 1).some((l) => l.trim() === "");
+}
+/**
+ * Remove `{/* … *\/}` comments from a prose span, leaving INLINE CODE alone.
+ *
+ * Two ways this ate real content before:
+ *
+ *  - A code span documenting the syntax lost its contents:
+ *    "Always use `{/* … *\/}`" became "Always use ``". Mintlify's own docs do
+ *    exactly this on ~8 pages, in four languages.
+ *  - An UNTERMINATED `{/*` matched forward to the next `*\/` anywhere in the
+ *    file, swallowing every paragraph in between. A single typo silently
+ *    deleted the rest of a page.
+ *
+ * So: split on inline code spans and skip them, and require the comment to
+ * close before the next blank line — an unterminated one is left as-is rather
+ * than eating the document.
+ */
+function stripCommentsOutsideCode(part) {
+    // MASK code spans, don't split on them. Splitting broke twice:
+    //
+    //  - the "comment owns its line" rule is anchored with `^`, which matched at
+    //    the start of every SEGMENT — a position that is mid-line whenever a code
+    //    span precedes it. `Use \`code\` {/* vale off */}` then consumed the
+    //    trailing newline and mashed the next line onto it.
+    //  - `[^\`]*` crossed newlines, so one unbalanced backtick earlier in the
+    //    block flipped the odd/even parity and a documented `{/* … */}` code span
+    //    was emptied — the exact bug this function exists to prevent.
+    //
+    // Masking keeps line structure intact and makes parity a per-line question.
+    const { masked, spans } = maskCodeSpans(part);
+    const stripped = masked
+        // Comment alone on its line takes the line with it.
+        .replace(/^[ \t]*\{\s*\/\*(?:(?!\*\/)[^\n])*(?:\n(?!\s*\n)(?:(?!\*\/)[^\n])*)*\*\/\s*\}[ \t]*\n?/gm, "")
+        // Otherwise just the expression, leaving surrounding text intact.
+        .replace(/\{\s*\/\*(?:(?!\*\/)[^\n])*(?:\n(?!\s*\n)(?:(?!\*\/)[^\n])*)*\*\/\s*\}/g, "");
+    return stripped.replace(/\u0000(\d+)\u0000/g, (m, i) => spans[Number(i)] ?? m);
+}
+function applyInlineTransforms(source, adapter) {
+    if (!adapter?.inlineTransforms)
+        return source;
+    // Never rewrite inside fenced code blocks: split on fences, transform
+    // only the prose spans.
+    const parts = source.split(/(^(?:`{3,}|~{3,})[^\n]*\n[\s\S]*?\n(?:`{3,}|~{3,})[ \t]*$)/m);
+    return parts
+        .map((part, idx) => {
+        if (idx % 2 === 1)
+            return part; // fence span — untouched
+        let result = part;
+        for (const [regex, replacement] of adapter.inlineTransforms) {
+            result = result.replace(regex, replacement);
+        }
+        return result;
+    })
+        .join("");
 }
 // ── Post-processing ──────────────────────────────────────
 /**
@@ -93,28 +376,134 @@ export function mdxToTree(source) {
  * - Convert JSX className to HTML class
  * - Handle dark mode images (className="hidden dark:block" → hide by default)
  */
-function postProcess(nodes) {
+/**
+ * Group CONSECUTIVE code blocks carrying `tab="…"` into one tab group.
+ *
+ * fumadocs' `remarkCodeTab` gives a bare fence a tab label and groups the run
+ * that follows; there is no wrapping element. Without this the labels were
+ * read but each fence still rendered as its own standalone code block, so a
+ * before/after comparison lost the thing that made it a comparison.
+ *
+ * Runs on every source, not just fumadocs: `tab=` has no other meaning in a
+ * fence info string, so a source that uses it means this.
+ */
+function groupTabbedCode(nodes) {
+    const out = [];
+    let run = [];
+    const flush = () => {
+        if (run.length === 0)
+            return;
+        // A single tabbed fence is not a group — keep it a plain code block.
+        if (run.length === 1) {
+            out.push(run[0]);
+        }
+        else {
+            out.push({
+                type: "tabs",
+                children: run.map((code) => ({
+                    type: "tab",
+                    props: { title: String(code.props?.tab ?? "") },
+                    children: [code],
+                })),
+            });
+        }
+        run = [];
+    };
     for (const node of nodes) {
+        if (node.children)
+            node.children = groupTabbedCode(node.children);
+        if (node.type === "code" && node.props?.tab) {
+            run.push(node);
+            continue;
+        }
+        flush();
+        out.push(node);
+    }
+    flush();
+    return out;
+}
+/**
+ * Rewrite an internal link so it resolves in the IMPORTED site.
+ *
+ * Two corrections, both measured on Mintlify's own docs, where they broke two
+ * of the four cards on the front page:
+ *
+ *  1. `/dir/index` → `/dir`. A `dir/index.mdx` page is routed at `/dir` (every
+ *     importer collapses it, and so does the nav), but links written to the
+ *     file path kept the `/index` and 404'd. 107 links in that corpus.
+ *  2. A path that the source's own `redirects` map moves — a docs site
+ *     accumulates these as pages are renamed, and its own pages go on linking
+ *     to the old path because the live site serves the redirect. After import
+ *     nothing serves it. 16 links, including `/installation` → `/cli/install`.
+ *
+ * Anchors and query strings are preserved, and redirect chains are followed
+ * with a seen-set so a cycle in someone's config cannot hang the import.
+ */
+export function rewriteInternalHref(href, redirects = {}) {
+    if (!href.startsWith("/"))
+        return href;
+    const [pathAndQuery, ...hashParts] = href.split("#");
+    const hash = hashParts.length ? `#${hashParts.join("#")}` : "";
+    const [rawPath, ...queryParts] = pathAndQuery.split("?");
+    const query = queryParts.length ? `?${queryParts.join("?")}` : "";
+    let path = rawPath.replace(/\/index$/, "") || "/";
+    const seen = new Set([path]);
+    for (let hop = 0; hop < 8; hop++) {
+        // `Object.hasOwn`, not a bare index: the map comes from someone else's
+        // config, and a plain-object lookup of `/toString` or `/constructor`
+        // returns an inherited FUNCTION. `target.replace` then threw a TypeError
+        // that aborted the whole import rather than producing a bad link.
+        const key = Object.hasOwn(redirects, path)
+            ? path
+            : path.replace(/\/$/, "");
+        const target = Object.hasOwn(redirects, key) ? redirects[key] : undefined;
+        if (typeof target !== "string" || seen.has(target))
+            break;
+        seen.add(target);
+        path = target.replace(/\/index$/, "") || "/";
+    }
+    return `${path}${query}${hash}`;
+}
+function postProcess(nodes, redirects = {}) {
+    for (const node of nodes) {
+        // Never touch preserved raw spans — byte-exactness is the contract.
+        if (node.type === "mdx-raw")
+            continue;
         // Fix HTML strings
         if (node.html) {
-            node.html = fixHtml(node.html);
+            node.html = fixHtml(node.html, redirects);
         }
         // Fix href props (cards, links, etc.)
         if (node.props?.href && typeof node.props.href === "string") {
-            node.props.href = node.props.href.replace(/^\/en\//, "/docs/");
+            node.props.href = rewriteInternalHref(node.props.href.replace(/^\/en\//, "/docs/"), redirects);
         }
         // Handle figure nodes (from <Frame>) — process children HTML
         if (node.type === "figure" && node.children) {
             // Filter out dark-only images, keep light/default ones
             filterDarkModeImages(node);
         }
+        // Inline links live on `inline`, not just `props`/`html` — a body link is
+        // the common case and was untouched by the href fix above.
+        for (const inl of node.inline ?? [])
+            rewriteInlineHrefs(inl, redirects);
         if (node.children)
-            postProcess(node.children);
+            postProcess(node.children, redirects);
     }
 }
-function fixHtml(html) {
+/** Apply the href rewrite to an inline node and its children. */
+function rewriteInlineHrefs(node, redirects) {
+    if (node.type === "link" && typeof node.href === "string") {
+        node.href = rewriteInternalHref(node.href.replace(/^\/en\//, "/docs/"), redirects);
+    }
+    for (const child of node.children ?? []) {
+        rewriteInlineHrefs(child, redirects);
+    }
+}
+function fixHtml(html, redirects = {}) {
     // Rewrite internal links: /en/foo#bar → /docs/foo#bar
     html = html.replace(/href="\/en\//g, 'href="/docs/');
+    // …then the /index collapse + source redirects, on every internal href.
+    html = html.replace(/href="(\/[^"]*)"/g, (_m, h) => `href="${rewriteInternalHref(h, redirects)}"`);
     // Convert JSX className to HTML class
     html = html.replace(/className="/g, 'class="');
     return html;
@@ -177,59 +566,339 @@ function stripPreamble(source) {
     return content.trim();
 }
 /**
- * Strip `export const Foo = () => { ... };` blocks from MDX source.
+ * Strip MDX module-level statements — fence-aware so `import` lines inside
+ * code samples survive untouched:
+ * - `import … from "…"` lines (incl. multi-line import blocks) — Fumadocs
+ *   and Docusaurus corpora carry these at the top of the body;
+ * - `export const Foo = …;` blocks — depth-tracked over BOTH braces and
+ *   brackets (data arrays like `export const fields = [ {…}, ];` would
+ *   otherwise leave a stray `];` behind).
  *
- * These are React component definitions embedded in MDX that can't be
- * converted to static markup. They appear as bare JavaScript in the
- * markdown and would otherwise render as visible source code.
- *
- * Uses brace-depth tracking to find the end of each export block.
+ * Export blocks are not just stripped — their right-hand sides are
+ * CAPTURED into `moduleData` (name → raw literal text). Docsets commonly
+ * keep component data as same-file exports (`<DatabaseTable
+ * fields={twoFactorTableFields} />`); handlers resolve those identifiers
+ * statically via `ctx.moduleData`. No execution, ever.
  */
-function stripJsxExports(source) {
+function stripMdxStatements(source) {
     const lines = source.split("\n");
     const result = [];
+    const moduleData = {};
+    const imports = {};
     let i = 0;
+    let inFence = false;
+    let fenceChar = "";
     while (i < lines.length) {
         const line = lines[i];
-        // Detect export const ... = () => { or export const ... = ({ ... }) => {
-        if (line.match(/^export\s+const\s+\w+\s*=/)) {
-            // Skip this entire block by tracking brace depth
+        const trimmed = line.trim();
+        // Fence tracking — statements inside fences are code, not MDX.
+        if (!inFence) {
+            const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+            if (fenceMatch) {
+                inFence = true;
+                fenceChar = fenceMatch[1][0];
+                result.push(line);
+                i++;
+                continue;
+            }
+        }
+        else {
+            if (trimmed.match(new RegExp(`^${fenceChar === "`" ? "`" : "~"}{3,}\\s*$`))) {
+                inFence = false;
+            }
+            result.push(line);
+            i++;
+            continue;
+        }
+        // import statements (possibly spanning lines until the `from "…"` /
+        // quoted specifier terminator)
+        if (trimmed.match(/^import\s/)) {
+            const start = i;
+            while (i < lines.length && !lines[i].match(/["'][^"']*["'];?\s*$/)) {
+                i++;
+            }
+            const statement = lines.slice(start, i + 1).join(" ");
+            i++; // skip the terminating line
+            // Remember `import X from "/snippets/foo.mdx"`. Mintlify's reuse
+            // mechanism is an MDX import of another .mdx file used as a component;
+            // throwing the specifier away is what turned <LinkArguments /> into an
+            // unresolvable unknown component.
+            // BOTH forms. dub uses `import Foo from …` for plain snippets and
+            // `import { Foo } from …` for parameterised ones, and matching only the
+            // default form left the named ones unresolved on 13 pages.
+            const spec = /\sfrom\s*["']([^"']+\.mdx?)["']/.exec(statement)?.[1];
+            if (spec) {
+                const clause = statement.slice("import".length, statement.search(/\sfrom\s/));
+                const def = /^\s*([A-Za-z_$][\w$]*)\s*(?:,|$)/.exec(clause);
+                if (def)
+                    imports[def[1]] = spec;
+                const named = /\{([^}]*)\}/.exec(clause);
+                for (const part of named?.[1].split(",") ?? []) {
+                    const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+                    if (name && /^[A-Za-z_$][\w$]*$/.test(name))
+                        imports[name] = spec;
+                }
+            }
+            continue;
+        }
+        // export const Foo = <literal or component>;
+        const exportMatch = line.match(/^export\s+const\s+([\w$]+)\s*=\s*(.*)$/);
+        if (exportMatch) {
+            const name = exportMatch[1];
+            const captured = [exportMatch[2]];
             let depth = 0;
             let started = false;
-            while (i < lines.length) {
-                for (const ch of lines[i]) {
-                    if (ch === "{") {
+            let quote = null;
+            let j = i;
+            while (j < lines.length) {
+                const scan = j === i ? exportMatch[2] : lines[j];
+                for (let k = 0; k < scan.length; k++) {
+                    const ch = scan[k];
+                    if (quote) {
+                        if (ch === quote && scan[k - 1] !== "\\")
+                            quote = null;
+                        continue;
+                    }
+                    if (ch === '"' || ch === "'" || ch === "`") {
+                        quote = ch;
+                        continue;
+                    }
+                    if (ch === "{" || ch === "[" || ch === "(") {
                         depth++;
                         started = true;
                     }
-                    if (ch === "}")
+                    if (ch === "}" || ch === "]" || ch === ")")
                         depth--;
                 }
-                i++;
-                // End when we've seen at least one { and depth returns to 0
+                if (j > i)
+                    captured.push(lines[j]);
+                j++;
                 if (started && depth <= 0)
                     break;
             }
-            // Also skip trailing semicolons or blank lines
+            i = j;
             while (i < lines.length && (lines[i].trim() === ";" || lines[i].trim() === "")) {
                 i++;
             }
+            const literal = captured.join("\n").trim().replace(/;$/, "").trim();
+            if (literal)
+                moduleData[name] = literal;
             continue;
         }
         result.push(line);
         i++;
     }
-    return result.join("\n");
+    return { source: result.join("\n"), moduleData, imports };
+}
+/**
+ * Collapse a block-leading multi-line HTML opening tag onto one line so
+ * markdown-it parses it as a single inline-HTML tag. MDX/JSX allows attributes
+ * on separate lines (e.g. a styled `<a\n href=…\n className=…\n>text</a>`); the
+ * JSX plugin only claims CAPITALISED component tags, so a lowercase multi-line
+ * tag falls through to markdown-it, which mangles it — the lone `>` line becomes
+ * a blockquote and the attributes become literal text. Single-line lowercase
+ * tags already parse correctly, so collapsing the head is a safe, targeted fix.
+ * Fence-aware; only triggers when a line STARTS with a lowercase tag opener that
+ * does not close on that line (rare in prose).
+ */
+function collapseMultilineHtmlOpenTags(source) {
+    const lines = source.split("\n");
+    const out = [];
+    let inFence = false;
+    let fenceChar = "";
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        if (!inFence) {
+            const fm = trimmed.match(/^(`{3,}|~{3,})/);
+            if (fm) {
+                inFence = true;
+                fenceChar = fm[1][0];
+                out.push(line);
+                continue;
+            }
+        }
+        else {
+            if (new RegExp(`^${fenceChar === "`" ? "`" : "~"}{3,}\\s*$`).test(trimmed))
+                inFence = false;
+            out.push(line);
+            continue;
+        }
+        // A line that starts with a lowercase HTML tag opener but does not close it.
+        if (/^<[a-z][a-z0-9-]*(\s|$)/.test(trimmed) && firstUnquotedGt(line) === -1) {
+            const buf = [line];
+            let j = i + 1;
+            let closed = false;
+            for (; j < lines.length && j - i < 40; j++) {
+                buf.push(lines[j]);
+                if (firstUnquotedGt(lines[j]) !== -1) {
+                    closed = true;
+                    break;
+                }
+            }
+            if (closed) {
+                out.push(normalizeJsxAttrs(collapseTagHead(buf.join("\n"))));
+                i = j;
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out.join("\n");
+}
+/** Index of the first `>` outside single/double quotes on this line, or -1. */
+function firstUnquotedGt(s) {
+    let q = "";
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (q) {
+            if (c === q)
+                q = "";
+            continue;
+        }
+        if (c === '"' || c === "'")
+            q = c;
+        else if (c === ">")
+            return i;
+    }
+    return -1;
+}
+/** Collapse the opening tag (up to and incl. the first unquoted `>`, tracking
+ *  quotes across newlines) onto one line; leave content after the tag intact. */
+/**
+ * Rewrite JSX-only attributes on a LOWERCASE HTML tag into HTML markdown-it
+ * will accept.
+ *
+ * markdown-it's HTML rules require quoted or bare attribute values, so a JSX
+ * expression attribute — `style={{ borderRadius: "12px" }}` — makes the whole
+ * tag fail to parse as HTML and it is emitted as ESCAPED TEXT. On ollama that
+ * showed a reader a literal `&lt;img src="…" /&gt;` and lost the image: 25
+ * occurrences across 17 pages, 5 of them the page's only images.
+ *
+ * `style={{ … }}` converts (camelCase → kebab-case, the real CSS); any other
+ * expression attribute is dropped, because its value is JavaScript and there
+ * is nothing faithful to put in its place.
+ */
+export function normalizeJsxAttrs(tag, onDrop) {
+    return tag.replace(/\s([A-Za-z_:][\w:.-]*)=\{(\{[\s\S]*?\}|[^{}]*)\}/g, (_m, name, expr) => {
+        if (name === "style" && expr.startsWith("{")) {
+            const css = [...expr.matchAll(/([A-Za-z_][\w]*)\s*:\s*"([^"]*)"|([A-Za-z_][\w]*)\s*:\s*'([^']*)'/g)]
+                .map(([, k1, v1, k2, v2]) => {
+                const key = (k1 ?? k2).replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+                return `${key}:${v1 ?? v2}`;
+            })
+                .join(";");
+            if (css)
+                return ` style="${css}"`;
+        }
+        onDrop?.(name);
+        return "";
+    });
+}
+const VOID_HTML = new Set([
+    "area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr",
+]);
+/**
+ * Remove blank lines inside a balanced block-level raw-HTML region.
+ *
+ * markdown-it ends an html_block at the first BLANK LINE, so a container whose
+ * children are separated by blank lines is split: everything after the first
+ * child is emitted as separate blocks, and the trailing bare `</div>` closers
+ * arrive as their own node. On ollama's integration pages that dropped items
+ * 2–6 of a six-item capability grid — ~380 words of real prose — before the
+ * exporter could even see them, so no ledger could record it.
+ *
+ * Only PURE-MARKUP regions are joined (every non-blank line starts with a tag).
+ * A region containing markdown keeps its blank lines, because there the blank
+ * line is meaningful and markdown-it is right to split.
+ */
+function joinBlankLinesInHtmlBlocks(source) {
+    const lines = source.split("\n");
+    const out = [];
+    let inFence = false;
+    let fenceChar = "";
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (!inFence) {
+            const fm = trimmed.match(/^(`{3,}|~{3,})/);
+            if (fm) {
+                inFence = true;
+                fenceChar = fm[1][0];
+                out.push(lines[i]);
+                continue;
+            }
+        }
+        else {
+            if (new RegExp(`^${fenceChar === "`" ? "`" : "~"}{3,}\\s*$`).test(trimmed))
+                inFence = false;
+            out.push(lines[i]);
+            continue;
+        }
+        if (!/^<[a-z][a-z0-9-]*(\s|>)/.test(trimmed)) {
+            out.push(lines[i]);
+            continue;
+        }
+        // Scan to the matching close, tracking depth.
+        let depth = 0;
+        let end = -1;
+        let pure = true;
+        for (let j = i; j < lines.length; j++) {
+            const t = lines[j].trim();
+            if (t !== "" && !/^<\/?[A-Za-z]/.test(t))
+                pure = false;
+            for (const m of t.matchAll(/<(\/?)([a-z][a-z0-9-]*)([^>]*)>/g)) {
+                const [, slash, name, rest] = m;
+                if (VOID_HTML.has(name) || rest.trimEnd().endsWith("/"))
+                    continue;
+                depth += slash ? -1 : 1;
+            }
+            if (depth <= 0) {
+                end = j;
+                break;
+            }
+        }
+        if (end === -1 || end === i || !pure) {
+            out.push(lines[i]);
+            continue;
+        }
+        for (let j = i; j <= end; j++) {
+            if (lines[j].trim() !== "")
+                out.push(lines[j]);
+        }
+        i = end;
+    }
+    return out.join("\n");
+}
+function collapseTagHead(text) {
+    let q = "";
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (q) {
+            if (c === q)
+                q = "";
+            continue;
+        }
+        if (c === '"' || c === "'")
+            q = c;
+        else if (c === ">") {
+            return text.slice(0, i + 1).replace(/\s*\n\s*/g, " ") + text.slice(i + 1);
+        }
+    }
+    return text;
 }
 /**
  * Split MDX source into alternating markdown and component segments.
- * Handles nested components, fenced code blocks, and self-closing tags.
+ * Handles nested components, fenced code blocks, multi-line tag heads,
+ * and self-closing tags. Unknown capitalized tags are captured too —
+ * they become `mdx-raw` nodes downstream (never dropped).
  */
-function segmentMdx(source) {
+function segmentMdx(source, ctx) {
     const segments = [];
     const lines = source.split("\n");
     let i = 0;
     let markdownBuffer = [];
+    let inFence = false;
+    let fenceChar = "";
     function flushMarkdown() {
         const content = markdownBuffer.join("\n").trim();
         if (content) {
@@ -240,73 +909,94 @@ function segmentMdx(source) {
     while (i < lines.length) {
         const line = lines[i];
         const trimmed = line.trim();
-        // Check for single-line component: <Tag>content</Tag> on one line
-        const singleLineMatch = trimmed.match(/^<([A-Z]\w*)(\s[^>]*)?>(.+)<\/\1>$/);
-        if (singleLineMatch && COMPONENT_MAP[singleLineMatch[1]]) {
-            flushMarkdown();
-            const tag = singleLineMatch[1];
-            const attrStr = singleLineMatch[2] || "";
-            const children = singleLineMatch[3];
-            segments.push({
-                kind: "component",
-                tag,
-                attrs: parseAttrs(attrStr),
-                children,
-                selfClosing: false,
-            });
+        // Fence tracking — component tags inside code samples are literal text.
+        if (!inFence) {
+            const fenceMatch = trimmed.match(/^(`{3,}|~{3,})/);
+            if (fenceMatch) {
+                inFence = true;
+                fenceChar = fenceMatch[1][0];
+                markdownBuffer.push(line);
+                i++;
+                continue;
+            }
+        }
+        else {
+            if (trimmed.match(new RegExp(`^${fenceChar === "`" ? "`" : "~"}{3,}\\s*$`))) {
+                inFence = false;
+            }
+            markdownBuffer.push(line);
             i++;
             continue;
         }
-        // Check for component opening tag at the start of a line
-        const openMatch = trimmed.match(/^<([A-Z]\w*)(\s[^>]*)?\s*\/?>$/);
-        if (openMatch) {
-            const tag = openMatch[1];
-            const attrStr = openMatch[2] || "";
-            const isSelfClose = trimmed.endsWith("/>");
-            if (COMPONENT_MAP[tag]) {
-                flushMarkdown();
-                if (isSelfClose) {
+        // Component tag at the start of a line? (name may end the line when
+        // attributes continue on the next line, e.g. <TypeTable\n type={{…}})
+        const tagMatch = trimmed.match(/^<([A-Z][A-Za-z0-9]*)(?=[\s/>]|$)/);
+        if (tagMatch) {
+            const tag = tagMatch[1];
+            // Assemble the tag head — attributes may span multiple lines
+            // (e.g. <TypeTable type={{ … }} />). Join lines until the scanner
+            // finds the terminating `>` outside quotes/braces.
+            const head = scanTagHead(lines, i, tag);
+            if (head) {
+                const { attrStr, selfClosing, headEndLine, afterHead } = head;
+                const isSelfClosing = selfClosing || ctx.selfClosing.has(tag);
+                if (isSelfClosing) {
+                    flushMarkdown();
                     segments.push({
                         kind: "component",
                         tag,
                         attrs: parseAttrs(attrStr),
                         children: "",
+                        raw: rawSpan(lines, i, headEndLine),
                         selfClosing: true,
+                        line: i + 1,
                     });
+                    if (afterHead.trim())
+                        markdownBuffer.push(afterHead);
+                    i = headEndLine + 1;
+                    continue;
+                }
+                // Content and close on the head's own trailing text?
+                const inlineClose = afterHead.match(new RegExp(`^([\\s\\S]*)</${tag}\\s*>\\s*$`));
+                if (inlineClose) {
+                    flushMarkdown();
+                    segments.push({
+                        kind: "component",
+                        tag,
+                        attrs: parseAttrs(attrStr),
+                        children: inlineClose[1],
+                        raw: rawSpan(lines, i, headEndLine),
+                        selfClosing: false,
+                        line: i + 1,
+                    });
+                    i = headEndLine + 1;
+                    continue;
+                }
+                // Collect children until the matching closing tag.
+                const collected = collectUntilClose(lines, headEndLine + 1, tag);
+                if (!collected.found && !ctx.map[tag]) {
+                    // Unterminated UNKNOWN tag — likely prose starting with "<Word>"
+                    // or malformed MDX. Don't swallow the document into one raw
+                    // blob; let the head line(s) flow through as markdown.
+                    markdownBuffer.push(line);
                     i++;
                     continue;
                 }
-                // Collect children until closing tag
-                const { content, endLine } = collectUntilClose(lines, i + 1, tag);
-                segments.push({
-                    kind: "component",
-                    tag,
-                    attrs: parseAttrs(attrStr),
-                    children: content,
-                    selfClosing: false,
-                });
-                i = endLine + 1;
-                continue;
-            }
-        }
-        // Also check for opening tags that aren't on their own line (with content after)
-        const inlineOpenMatch = trimmed.match(/^<([A-Z]\w*)(\s[^>]*)?>$/);
-        if (inlineOpenMatch && !openMatch) {
-            const tag = inlineOpenMatch[1];
-            const attrStr = inlineOpenMatch[2] || "";
-            if (COMPONENT_MAP[tag]) {
                 flushMarkdown();
-                const { content, endLine } = collectUntilClose(lines, i + 1, tag);
+                const childPrefix = afterHead.trim() ? `${afterHead}\n` : "";
                 segments.push({
                     kind: "component",
                     tag,
                     attrs: parseAttrs(attrStr),
-                    children: content,
+                    children: childPrefix + dedent(collected.content),
+                    raw: rawSpan(lines, i, collected.endLine),
                     selfClosing: false,
+                    line: i + 1,
                 });
-                i = endLine + 1;
+                i = collected.endLine + 1;
                 continue;
             }
+            // No terminated tag head — fall through: plain markdown line.
         }
         markdownBuffer.push(line);
         i++;
@@ -314,6 +1004,64 @@ function segmentMdx(source) {
     flushMarkdown();
     return segments;
 }
+function rawSpan(lines, from, to) {
+    return lines.slice(from, Math.min(to + 1, lines.length)).join("\n");
+}
+/**
+ * Scan a tag head starting at lines[startLine] for tag `tag`. The head may
+ * span several lines (multi-line attribute objects). Returns null when no
+ * terminating `>` is found within a sane window — the line is then treated
+ * as plain markdown.
+ *
+ * The window exists to stop a stray `<` from swallowing the rest of the
+ * document; it is NOT a statement about how big a real attribute may be.
+ * At 60 lines it was cutting real content in half: better-auth 1.5.6 writes
+ * `<DatabaseTable fields={[…]}/>` with one object per field and one property
+ * per line, so a 12-column table needs ~70 lines. The scanner gave up, the
+ * component fell back to plain text, and the whole table shipped as literal
+ * JSX in the reader — silently, because a head that never closes looks
+ * exactly like prose that happens to start with `<`.
+ *
+ * The bound stays generous rather than absent: a runaway scan is still
+ * bounded, but no plausible hand-written attribute reaches it.
+ */
+function scanTagHead(lines, startLine, tag) {
+    const MAX_HEAD_LINES = 600;
+    let text = "";
+    for (let j = startLine; j < Math.min(lines.length, startLine + MAX_HEAD_LINES); j++) {
+        text = text ? `${text}\n${lines[j]}` : lines[j].trimStart();
+        // Scan from just past "<Tag" for the terminating ">" at depth 0.
+        const offset = 1 + tag.length;
+        let depth = 0;
+        let quote = null;
+        for (let k = offset; k < text.length; k++) {
+            const ch = text[k];
+            if (quote) {
+                if (ch === quote && text[k - 1] !== "\\")
+                    quote = null;
+                continue;
+            }
+            if (ch === '"' || ch === "'" || ch === "`") {
+                quote = ch;
+                continue;
+            }
+            if (ch === "{")
+                depth++;
+            else if (ch === "}")
+                depth--;
+            else if (ch === ">" && depth <= 0) {
+                const selfClosing = text[k - 1] === "/";
+                const attrEnd = selfClosing ? k - 1 : k;
+                const attrStr = text.slice(offset, attrEnd);
+                // The scan buffer ends at line j, so everything past ">" is the
+                // remainder of the final head line.
+                const afterHead = text.slice(k + 1);
+                return { attrStr, selfClosing, headEndLine: j, afterHead };
+            }
+        }
+    }
+    return null;
+}
 /**
  * Collect lines until the matching closing tag, handling nesting.
  * Respects fenced code blocks (content inside is literal).
@@ -348,7 +1096,7 @@ function collectUntilClose(lines, startLine, tag) {
         if (closeMatch) {
             depth--;
             if (depth === 0) {
-                return { content: dedent(collected.join("\n")), endLine: i };
+                return { content: collected.join("\n"), endLine: i, found: true };
             }
         }
         const openMatch = trimmed.match(new RegExp(`^<${tag}(\\s[^>]*)?>$`));
@@ -359,7 +1107,7 @@ function collectUntilClose(lines, startLine, tag) {
         i++;
     }
     // If we never found the closing tag, return everything
-    return { content: dedent(collected.join("\n")), endLine: lines.length - 1 };
+    return { content: collected.join("\n"), endLine: lines.length - 1, found: false };
 }
 /**
  * Remove common leading whitespace from all lines.
@@ -383,99 +1131,362 @@ function dedent(text) {
     return lines.map((line) => line.slice(minIndent)).join("\n");
 }
 // ── Attribute parsing ────────────────────────────────────
-function parseAttrs(attrStr) {
+/**
+ * Parse a JSX attribute string. Supports `key="v"`, `key='v'`,
+ * `key={expr}` (balanced braces — `{{obj}}` keeps the inner `{obj}`),
+ * and bare boolean attributes (`requireSession` → "true").
+ */
+export function parseAttrs(attrStr) {
     const attrs = {};
-    // Match: key="value" or key={value} or key='value'
-    const re = /(\w+)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{([^}]*)\})/g;
-    let match;
-    while ((match = re.exec(attrStr))) {
-        attrs[match[1]] = match[2] ?? match[3] ?? match[4] ?? "";
+    const s = attrStr;
+    let i = 0;
+    while (i < s.length) {
+        while (i < s.length && /\s/.test(s[i]))
+            i++;
+        const keyMatch = /^[A-Za-z_][\w-]*/.exec(s.slice(i));
+        if (!keyMatch) {
+            i++;
+            continue;
+        }
+        const key = keyMatch[0];
+        i += key.length;
+        while (i < s.length && /\s/.test(s[i]))
+            i++;
+        if (s[i] !== "=") {
+            attrs[key] = "true"; // bare attribute
+            continue;
+        }
+        i++;
+        while (i < s.length && /\s/.test(s[i]))
+            i++;
+        const ch = s[i];
+        if (ch === '"' || ch === "'") {
+            const end = s.indexOf(ch, i + 1);
+            attrs[key] = end === -1 ? s.slice(i + 1) : s.slice(i + 1, end);
+            i = end === -1 ? s.length : end + 1;
+        }
+        else if (ch === "{") {
+            let depth = 0;
+            let quote = null;
+            let k = i;
+            for (; k < s.length; k++) {
+                const c = s[k];
+                if (quote) {
+                    if (c === quote && s[k - 1] !== "\\")
+                        quote = null;
+                    continue;
+                }
+                if (c === '"' || c === "'" || c === "`") {
+                    quote = c;
+                    continue;
+                }
+                if (c === "{")
+                    depth++;
+                else if (c === "}") {
+                    depth--;
+                    if (depth === 0)
+                        break;
+                }
+            }
+            attrs[key] = s.slice(i + 1, k).trim();
+            i = k + 1;
+        }
+        else {
+            const m = /^\S+/.exec(s.slice(i));
+            attrs[key] = m?.[0] ?? "";
+            i += m?.[0].length ?? 1;
+        }
     }
     return attrs;
 }
 // ── Segments → TreeNode[] ────────────────────────────────
-function segmentsToTree(segments) {
+function mdxRawNode(seg) {
+    return { type: "mdx-raw", props: { source: seg.raw, component: seg.tag } };
+}
+/**
+ * Resolve `<Snippet />` to the parsed content of the `.mdx` it was imported
+ * from, or null when it cannot be resolved (missing file, cycle, no rootDir).
+ *
+ * A specifier starting with `/` is DOCS-ROOT-relative, which is Mintlify's
+ * rule — treating it as an absolute filesystem path finds nothing. Everything
+ * else resolves against the importing file.
+ */
+function inlineSnippet(seg, ctx) {
+    const spec = ctx.imports[seg.tag];
+    // The importing file's path may be RELATIVE to the docs root (that is what
+    // the CLI stamps for ledger entries), so resolve it before taking dirname.
+    const fileDir = ctx.file
+        ? isAbsolute(ctx.file)
+            ? dirname(ctx.file)
+            : ctx.rootDir
+                ? resolve(ctx.rootDir, dirname(ctx.file))
+                : undefined
+        : undefined;
+    const base = spec.startsWith("/") ? ctx.rootDir : fileDir;
+    if (!base)
+        return null;
+    const path = resolve(base, spec.replace(/^\//, ""));
+    if (!existsSync(path))
+        return null;
+    if (ctx.inlining.has(path)) {
+        // A snippet that includes itself would recurse forever. Record and stop.
+        ctx.ledger.push({
+            component: `${seg.tag} (import cycle at ${spec})`,
+            action: "stripped",
+            line: seg.line,
+            file: ctx.file,
+        });
+        return null;
+    }
+    if (ctx.inlining.size >= 10)
+        return null;
+    let source;
+    try {
+        source = readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    // Strip the snippet's own frontmatter — it describes the snippet file, not
+    // the page including it.
+    source = source.replace(/^---\n[\s\S]*?\n---\n/, "");
+    // A snippet whose whole body is `export const X = (props) => (<JSX/>)` is a
+    // parameterised component. Its JSX body is real documentation, and the only
+    // thing standing between it and the reader is `{prop}` interpolation — which
+    // is a STATIC substitution from the attributes at the use site, not code to
+    // execute. dub's webhook parameter block is this shape and appears on 13
+    // pages.
+    const arrow = /^\s*export\s+const\s+[\w$]+\s*=\s*\(([^)]*)\)\s*=>\s*\(([\s\S]*)\)\s*;?\s*$/.exec(source);
+    if (arrow) {
+        const body = substituteProps(arrow[2], seg.attrs, seg.children);
+        if (!body.trim())
+            return null;
+        source = dedentBlock(body);
+    }
+    ctx.inlining.add(path);
+    try {
+        const sub = parseMdx(source, {
+            components: ctx.map,
+            selfClosingTags: [...ctx.selfClosing],
+            file: path,
+            rootDir: ctx.rootDir,
+            inlining: ctx.inlining,
+        });
+        ctx.ledger.push(...sub.ledger);
+        return sub.tree;
+    }
+    finally {
+        ctx.inlining.delete(path);
+    }
+}
+/**
+ * Replace `{name}` in a snippet component's JSX body with the value supplied
+ * at the use site. Purely textual: an expression that is not a bare prop name
+ * is left alone, and `{children}` takes the element's own inner source.
+ */
+function substituteProps(body, attrs, children) {
+    return body.replace(/\{([A-Za-z_$][\w$]*)\}/g, (whole, name) => {
+        if (name === "children")
+            return children;
+        return name in attrs ? attrs[name] : whole;
+    });
+}
+/** Remove the common leading indentation of a block. */
+function dedentBlock(text) {
+    const lines = text.split("\n").filter((l) => l.trim() !== "");
+    const indent = Math.min(...lines.map((l) => l.match(/^[ \t]*/)[0].length), Infinity);
+    return indent > 0 && Number.isFinite(indent)
+        ? text
+            .split("\n")
+            .map((l) => l.slice(indent))
+            .join("\n")
+        : text;
+}
+function segmentsToTree(segments, ctx) {
     const nodes = [];
     for (const seg of segments) {
         if (seg.kind === "markdown") {
-            nodes.push(...markdownToNodes(seg.content));
+            nodes.push(...markdownToNodes(seg.content, ctx));
+            continue;
         }
-        else {
-            const mapping = COMPONENT_MAP[seg.tag];
-            if (!mapping || mapping.strip)
+        const mapping = ctx.map[seg.tag];
+        // An unmapped component that was IMPORTED from another .mdx file is a
+        // snippet, not an unknown component. Mintlify's reuse mechanism is exactly
+        // this, and on dub it accounted for ~170 of the 198 "preserved" nodes: the
+        // content was sitting in `snippets/*.mdx` in the same repo the whole time,
+        // while the exporter stripped `<LinkArguments />` down to nothing.
+        if (!mapping && ctx.imports[seg.tag]) {
+            const inlined = inlineSnippet(seg, ctx);
+            if (inlined) {
+                nodes.push(...inlined);
                 continue;
-            const node = componentToNode(seg, mapping);
-            if (node)
-                nodes.push(node);
+            }
+        }
+        // Unknown component — NEVER drop. Preserve byte-exact + ledger.
+        if (!mapping) {
+            ctx.ledger.push({
+                component: seg.tag,
+                action: "preserved",
+                line: seg.line,
+                file: ctx.file,
+            });
+            nodes.push(mdxRawNode(seg));
+            continue;
+        }
+        if (mapping.strip && !mapping.toNode) {
+            ctx.ledger.push({
+                component: seg.tag,
+                action: "stripped",
+                line: seg.line,
+                file: ctx.file,
+            });
+            continue;
         }
+        const node = componentToNode(seg, mapping, ctx);
+        if (Array.isArray(node))
+            nodes.push(...node);
+        else if (node)
+            nodes.push(node);
     }
     return nodes;
 }
-function componentToNode(seg, mapping) {
+function componentToNode(seg, mapping, ctx) {
+    // Function form — full control, with "preserve" fallback.
+    if (mapping.toNode) {
+        const hctx = {
+            parseBlocks: (s) => parseBlocks(s, ctx),
+            ledger: (entry) => ctx.ledger.push({ ...entry, file: ctx.file }),
+            moduleData: ctx.moduleData,
+        };
+        const result = mapping.toNode(seg.attrs, seg.children, hctx);
+        if (result === "preserve") {
+            ctx.ledger.push({
+                component: seg.tag,
+                action: "preserved",
+                line: seg.line,
+                file: ctx.file,
+            });
+            return mdxRawNode(seg);
+        }
+        if (result === null) {
+            ctx.ledger.push({
+                component: seg.tag,
+                action: "stripped",
+                line: seg.line,
+                file: ctx.file,
+            });
+            return null;
+        }
+        return result;
+    }
     const props = mapping.propsFromAttrs
         ? mapping.propsFromAttrs(seg.attrs)
         : {};
     // Special handling for tabs container
     if (mapping.type === "tabs") {
-        return tabsToNode(seg);
+        return tabsToNode(seg, ctx);
     }
     // Special handling for steps container
     if (mapping.type === "steps") {
-        return stepsToNode(seg);
-    }
-    // Special handling for accordion-group
-    if (mapping.type === "accordion-group") {
-        // Parse children as segments, extract accordion items
-        const childSegments = segmentMdx(seg.children);
-        const children = segmentsToTree(childSegments);
-        return { type: "accordion-group", children };
-    }
-    // Special handling for cards container
-    if (mapping.type === "cards") {
-        const childSegments = segmentMdx(seg.children);
-        const children = segmentsToTree(childSegments);
-        return { type: "cards", children };
-    }
-    // For callouts, details, card — parse children as content
-    const children = seg.selfClosing ? [] : mdxToTree(seg.children);
+        return stepsToNode(seg, ctx);
+    }
+    // Special handling for accordion-group / cards — children are components
+    if (mapping.type === "accordion-group" || mapping.type === "cards") {
+        const children = parseBlocks(seg.children, ctx);
+        return { type: mapping.type, children };
+    }
+    // Children policy (default: parse as nested blocks)
+    const policy = mapping.children ?? "blocks";
+    let children;
+    if (seg.selfClosing || policy === "ignore") {
+        children = [];
+    }
+    else if (policy === "raw") {
+        children = seg.children.trim()
+            ? [{ type: "mdx-raw", props: { source: seg.children, component: seg.tag } }]
+            : [];
+    }
+    else if (policy === "code") {
+        children = codePolicyChildren(seg.children);
+    }
+    else {
+        children = parseBlocks(seg.children, ctx);
+    }
     const node = { type: mapping.type };
-    if (Object.keys(props).length > 0)
-        node.props = props;
+    const cleanProps = Object.fromEntries(Object.entries(props).filter(([, v]) => v !== undefined));
+    if (Object.keys(cleanProps).length > 0)
+        node.props = cleanProps;
     if (children.length > 0)
         node.children = children;
-    // For callout types, if there's a title prop, set it
-    if (mapping.type === "callout" && props.title) {
-        node.props = { ...props };
-    }
     return node;
 }
+/**
+ * `children: "code"` policy — keep inner content as a single code node.
+ * A lone inner fence is unwrapped (keeps its language); anything else
+ * becomes a language-less code node verbatim.
+ */
+function codePolicyChildren(inner) {
+    const trimmed = inner.trim();
+    if (!trimmed)
+        return [];
+    const fenceMatch = trimmed.match(/^```([^\n`]*)\n([\s\S]*?)\n?```$/);
+    if (fenceMatch) {
+        const lang = fenceMatch[1].trim().split(/\s+/)[0] || null;
+        return [{ type: "code", props: { lang, code: fenceMatch[2] } }];
+    }
+    return [{ type: "code", props: { lang: null, code: trimmed } }];
+}
 // ── Tabs handling ────────────────────────────────────────
-function tabsToNode(seg) {
+function tabsToNode(seg, ctx) {
     // Parse children to find <Tab> segments
-    const childSegments = segmentMdx(seg.children);
+    const childSegments = segmentMdx(seg.children, ctx);
     const tabs = [];
     for (const child of childSegments) {
         if (child.kind === "component" && child.tag === "Tab") {
-            const title = child.attrs.title || child.attrs.label || "";
-            const content = mdxToTree(child.children);
+            const title = child.attrs.title || child.attrs.label || child.attrs.value || "";
+            const content = parseBlocks(child.children, ctx);
             tabs.push({
                 type: "tab",
                 props: { title },
                 children: content,
             });
+            continue;
+        }
+        // A <CodeGroup> is mapped to `tabs` but its children are FENCED CODE
+        // BLOCKS, not <Tab>. Discarding non-Tab children emptied 124 of 147 tab
+        // groups on the dub corpus — every code sample in them vanished before the
+        // exporter ever saw it. Each code block becomes a tab, labelled by its
+        // fence title or language.
+        if (child.kind === "markdown") {
+            for (const node of parseBlocks(child.content, ctx)) {
+                if (node.type !== "code") {
+                    // Never silently: a paragraph inside a <CodeGroup> is rare but real,
+                    // and dropping it with no record is what this package forbids.
+                    ctx.ledger.push({
+                        component: `${seg.tag} (non-code ${node.type} child)`,
+                        action: "stripped",
+                        line: 0,
+                    });
+                    continue;
+                }
+                const label = node.props?.tab ||
+                    node.props?.title ||
+                    node.props?.lang ||
+                    `Tab ${tabs.length + 1}`;
+                tabs.push({ type: "tab", props: { title: label }, children: [node] });
+            }
         }
-        // Ignore non-Tab children inside Tabs
     }
     return { type: "tabs", children: tabs };
 }
 // ── Steps handling ───────────────────────────────────────
-function stepsToNode(seg) {
-    const childSegments = segmentMdx(seg.children);
+function stepsToNode(seg, ctx) {
+    const childSegments = segmentMdx(seg.children, ctx);
     const steps = [];
     for (const child of childSegments) {
         if (child.kind === "component" && child.tag === "Step") {
             const title = child.attrs.title || "";
-            const content = mdxToTree(child.children);
+            const content = parseBlocks(child.children, ctx);
             // Prepend title as bold text if present
             const children = [];
             if (title) {
@@ -497,11 +1508,11 @@ function stepsToNode(seg) {
  *
  * Uses markdown-it for tokenization, then walks tokens to build TreeNode[].
  */
-function markdownToNodes(content) {
+function markdownToNodes(content, ctx) {
     const tokens = md.parse(content, {});
-    return tokensToTree(tokens);
+    return tokensToTree(tokens, ctx);
 }
-function tokensToTree(tokens) {
+function tokensToTree(tokens, ctx) {
     const nodes = [];
     let i = 0;
     while (i < tokens.length) {
@@ -524,7 +1535,7 @@ function tokensToTree(tokens) {
                 i++;
             }
             i++; // skip close token
-            const node = openTokenToNode(token, children);
+            const node = openTokenToNode(token, children, ctx);
             if (node)
                 nodes.push(node);
             continue;
@@ -532,12 +1543,54 @@ function tokensToTree(tokens) {
         // Handle flat (self-closing) tokens
         switch (token.type) {
             case "fence": {
-                const lang = token.info?.split(/\s+/)[0] || "";
+                const info = token.info?.trim() ?? "";
+                const lang = info.split(/\s+/)[0] || "";
                 const code = token.content.replace(/\n$/, "");
-                nodes.push({
-                    type: "code",
-                    props: { lang: lang || null, code },
-                });
+                const props = { lang: lang || null, code };
+                // Info-string metadata: title="auth.ts" (Fumadocs/Docusaurus/
+                // Expressive Code convention) — dropping it loses real content.
+                // fumadocs' `remarkCodeTab`: `tab="Before"` is the TAB LABEL, and it
+                // is independent of `title=` (which is the filename) — a real fence
+                // carries both. 354 fences across the fumadocs corpus use it, and
+                // without reading it every tab was labelled with its language.
+                const tabMatch = info.match(/\btab=(?:["']([^"']*)["']|(\S+))/);
+                if (tabMatch)
+                    props.tab = tabMatch[1] ?? tabMatch[2];
+                const titleMatch = info.match(/title=["']([^"']*)["']/);
+                if (titleMatch) {
+                    props.title = titleMatch[1];
+                }
+                else {
+                    // Mintlify's convention is a BARE second token — ```bash npm — and
+                    // it is what labels the tab inside a <CodeGroup>. Without it every
+                    // tab of a four-manager install block was labelled "bash", which is
+                    // both useless to a reader and a hard build error in Docusaurus
+                    // (Tabs requires unique values). Only a plain filename/word token
+                    // qualifies: highlight ranges ({1,3}) and flags (showLineNumbers,
+                    // key=value) are meta, not titles.
+                    // SUBTRACT the known meta, then take what is left — do not require
+                    // the whole remainder to look like a title. Requiring that rejected
+                    // every real title that travels with meta, which on Mintlify's own
+                    // export (`theme={null}` on all 1338 fences) was ALL of them, plus
+                    // `.env`, `iOS (SwiftUI)`, `示例`, and `cURL {5}`. It also promoted
+                    // bare flags (`wrap`, `twoslash`) to titles, which then rendered as
+                    // a wrong label in the code-block title bar.
+                    let rest = info.slice(lang.length);
+                    rest = rest
+                        // key=value FIRST — otherwise the range strip below eats the
+                        // `{null}` out of `theme={null}` and leaves a bare `theme=`.
+                        .replace(/[A-Za-z_][\w-]*=(?:"[^"]*"|'[^']*'|\{[^}]*\}|\S+)/g, " ")
+                        .replace(/\{[^}]*\}/g, " ") // highlight ranges: {1,3-5}
+                        .replace(
+                    // Known bare flags. An unknown bare word is treated as a title:
+                    // a wrong title is visible and fixable, a dropped one is not.
+                    /(?:^|\s)(?:showLineNumbers|noLineNumbers|no-line-numbers|lineNumbers|twoslash|ts2js|noCopy|nocopy|copy|wrap|nowrap|expandable|collapsible|live|editable|frame)(?=\s|$)/g, " ")
+                        .replace(/\s+/g, " ")
+                        .trim();
+                    if (rest)
+                        props.title = rest;
+                }
+                nodes.push({ type: "code", props });
                 i++;
                 break;
             }
@@ -555,7 +1608,26 @@ function tokensToTree(tokens) {
             }
             case "html_block": {
                 const trimmed = token.content.trim();
-                if (!trimmed.match(/^<[A-Z]/)) {
+                const jsxMatch = trimmed.match(/^<([A-Z][A-Za-z0-9]*)/);
+                if (jsxMatch) {
+                    // JSX that slipped past segmentation (multi-line heads the
+                    // segmenter's window missed, odd formatting). Never drop —
+                    // preserve byte-exact + ledger.
+                    ctx.ledger.push({
+                        component: jsxMatch[1],
+                        action: "preserved",
+                        line: (token.map?.[0] ?? 0) + 1,
+                        file: ctx.file,
+                    });
+                    nodes.push({
+                        type: "mdx-raw",
+                        props: {
+                            source: token.content.replace(/\n$/, ""),
+                            component: jsxMatch[1],
+                        },
+                    });
+                }
+                else {
                     nodes.push({ type: "html", html: token.content });
                 }
                 i++;
@@ -571,8 +1643,8 @@ function tokensToTree(tokens) {
 /**
  * Map an opening token (nesting=1) + its collected children to a TreeNode.
  */
-function openTokenToNode(token, childTokens) {
-    const children = tokensToTree(childTokens);
+function openTokenToNode(token, childTokens, ctx) {
+    const children = tokensToTree(childTokens, ctx);
     switch (token.type) {
         case "heading_open": {
             const level = parseInt(token.tag.slice(1), 10);
@@ -590,8 +1662,17 @@ function openTokenToNode(token, childTokens) {
             return { type: "paragraph", children };
         case "blockquote_open":
             return { type: "blockquote", children };
-        case "ordered_list_open":
-            return { type: "ordered-list", children };
+        case "ordered_list_open": {
+            // Preserve the list's start number. markdown-it sets a `start` attr only
+            // when the first item is not 1 — which happens when interspersed block
+            // content (an image div, a callout) splits a `1. 2. 3.` list into several
+            // lists starting at 2, 3, … Dropping it renumbered every fragment from 1.
+            const startAttr = token.attrGet?.("start");
+            const start = startAttr != null ? parseInt(startAttr, 10) : undefined;
+            return start != null && !Number.isNaN(start)
+                ? { type: "ordered-list", props: { start }, children }
+                : { type: "ordered-list", children };
+        }
         case "bullet_list_open":
             return { type: "unordered-list", children };
         case "list_item_open":