specra 0.1.13 → 0.2.0

package/dist/mdx.js

@@ -0,0 +1,1099 @@
+import fs from "fs";
+import path from "path";
+import matter from "gray-matter";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
+import remarkRehype from "remark-rehype";
+import rehypeSlug from "rehype-slug";
+import rehypeRaw from "rehype-raw";
+import rehypeKatex from "rehype-katex";
+import rehypeStringify from "rehype-stringify";
+import { toHtml } from "hast-util-to-html";
+import { getAllCategoryConfigs } from "./category";
+import { sortSidebarItems, sortSidebarGroups, buildSidebarStructure } from "./sidebar-utils";
+import { sanitizePath, validatePathWithinDirectory, validateMDXSecurity } from "./mdx-security";
+import { getConfig } from "./config";
+const DOCS_DIR = path.join(process.cwd(), "docs");
+/**
+ * Map of lowercased HTML tag names to PascalCase component names.
+ * When rehype processes MDX, it lowercases all custom tags.
+ * This map restores the correct component name for rendering.
+ */
+const COMPONENT_TAG_MAP = {
+    accordion: 'Accordion',
+    accordionitem: 'AccordionItem',
+    tabs: 'Tabs',
+    tab: 'Tab',
+    callout: 'Callout',
+    card: 'Card',
+    cardgrid: 'CardGrid',
+    imagecard: 'ImageCard',
+    imagecardgrid: 'ImageCardGrid',
+    steps: 'Steps',
+    step: 'Step',
+    icon: 'Icon',
+    mermaid: 'Mermaid',
+    math: 'Math',
+    columns: 'Columns',
+    column: 'Column',
+    docbadge: 'DocBadge',
+    badge: 'Badge',
+    tooltip: 'Tooltip',
+    frame: 'Frame',
+    codeblock: 'CodeBlock',
+    image: 'Image',
+    'specra-image': 'Image',
+    'specra-math': 'Math',
+    video: 'Video',
+    apiendpoint: 'ApiEndpoint',
+    apiparams: 'ApiParams',
+    apiresponse: 'ApiResponse',
+    apiplayground: 'ApiPlayground',
+    apireference: 'ApiReference',
+};
+/**
+ * Map of lowercased attribute names to their correct camelCase form.
+ * HTML lowercases all attribute names, so we need to restore them.
+ */
+const PROP_NAME_MAP = {
+    defaultopen: 'defaultOpen',
+    defaultvalue: 'defaultValue',
+    classname: 'className',
+    tabgroup: 'tabGroup',
+    defaultchecked: 'defaultChecked',
+    defaultselected: 'defaultSelected',
+    apikey: 'apiKey',
+    baseurl: 'baseURL',
+};
+/**
+ * Pre-process markdown to convert JSX expression attributes into
+ * HTML-safe string attributes before the remark/rehype pipeline.
+ *
+ * JSX expressions like `cols={{ sm: 1, md: 2 }}` and `span={2}` are
+ * not valid HTML and get mangled by the HTML parser. This converts them
+ * to quoted string attributes that survive parsing, using a special
+ * `__jsx:` prefix so `convertProps` can parse them back.
+ *
+ * Examples:
+ *   cols={{ sm: 1, md: 2 }}  →  cols="__jsx:{ sm: 1, md: 2 }"
+ *   span={2}                  →  span="__jsx:2"
+ *   variant="success"         →  (unchanged, already a string)
+ */
+function preprocessJsxExpressions(markdown) {
+    // Split markdown into fenced code blocks and non-code segments.
+    // Only process JSX expressions in non-code segments to avoid corrupting code examples.
+    // Matches ```` ``` ```` or ```` ```` ```` fenced blocks (3+ backticks or tildes).
+    const fencedCodeRegex = /(^|\n)((`{3,}|~{3,}).*\n[\s\S]*?\n\3\s*(?:\n|$))/g;
+    const segments = [];
+    let lastIndex = 0;
+    let match;
+    while ((match = fencedCodeRegex.exec(markdown)) !== null) {
+        const codeStart = match.index + (match[1]?.length || 0);
+        // Add the non-code segment before this code block
+        if (codeStart > lastIndex) {
+            segments.push({ text: markdown.slice(lastIndex, codeStart), isCode: false });
+        }
+        // Add the code block as-is
+        segments.push({ text: match[2], isCode: true });
+        lastIndex = match.index + match[0].length;
+    }
+    // Add remaining non-code segment
+    if (lastIndex < markdown.length) {
+        segments.push({ text: markdown.slice(lastIndex), isCode: false });
+    }
+    // Build a pattern that matches known component tag names (case-insensitive for safety)
+    const allNames = [...new Set([
+            ...Object.values(COMPONENT_TAG_MAP),
+            ...Object.keys(COMPONENT_TAG_MAP),
+        ])].join('|');
+    // Regex to find tag starts — the actual tag end is found by the scanner below,
+    // because a simple [^>] regex breaks on `>` inside JSX expressions (e.g. Mermaid's `-->`).
+    const tagStartRegex = new RegExp(`<((?:${allNames}))(?=\\s|/?>)`, 'gi');
+    // Map of HTML5 element names that need renaming to avoid parser collisions.
+    // <image> → <img> (HTML5 spec), <math> → MathML namespace switch.
+    const HTML5_RENAMES = {
+        image: 'specra-image',
+        math: 'specra-math',
+    };
+    // Only process non-code segments
+    return segments.map(({ text, isCode }) => {
+        if (isCode)
+            return text;
+        let processed = '';
+        let lastEnd = 0;
+        // Reset regex state for each segment
+        tagStartRegex.lastIndex = 0;
+        let startMatch;
+        while ((startMatch = tagStartRegex.exec(text)) !== null) {
+            const tagStart = startMatch.index;
+            const tagName = startMatch[1];
+            // Scan forward from after the tag name to find the tag end,
+            // properly handling quotes, template literals, and brace expressions.
+            let pos = tagStart + startMatch[0].length;
+            let inDoubleQuote = false;
+            let inSingleQuote = false;
+            let inTemplateLiteral = false;
+            let braceDepth = 0;
+            let tagEnd = -1;
+            let isSelfClosing = false;
+            while (pos < text.length) {
+                const ch = text[pos];
+                if (inDoubleQuote) {
+                    if (ch === '\\')
+                        pos++; // skip escaped char
+                    else if (ch === '"')
+                        inDoubleQuote = false;
+                }
+                else if (inSingleQuote) {
+                    if (ch === '\\')
+                        pos++; // skip escaped char
+                    else if (ch === "'")
+                        inSingleQuote = false;
+                }
+                else if (inTemplateLiteral) {
+                    if (ch === '\\')
+                        pos++; // skip escaped char
+                    else if (ch === '`')
+                        inTemplateLiteral = false;
+                }
+                else if (braceDepth > 0) {
+                    if (ch === '{')
+                        braceDepth++;
+                    else if (ch === '}')
+                        braceDepth--;
+                    else if (ch === '"')
+                        inDoubleQuote = true;
+                    else if (ch === "'")
+                        inSingleQuote = true;
+                    else if (ch === '`')
+                        inTemplateLiteral = true;
+                }
+                else {
+                    // Top level of tag attributes
+                    if (ch === '"')
+                        inDoubleQuote = true;
+                    else if (ch === "'")
+                        inSingleQuote = true;
+                    else if (ch === '{')
+                        braceDepth++;
+                    else if (ch === '/' && text[pos + 1] === '>') {
+                        isSelfClosing = true;
+                        tagEnd = pos + 2;
+                        break;
+                    }
+                    else if (ch === '>') {
+                        tagEnd = pos + 1;
+                        break;
+                    }
+                }
+                pos++;
+            }
+            if (tagEnd === -1)
+                continue; // Unclosed tag, skip
+            // Extract attributes between tag name and closing >
+            const attrsStart = tagStart + startMatch[0].length;
+            const attrsEnd = isSelfClosing ? tagEnd - 2 : tagEnd - 1;
+            const attrs = text.slice(attrsStart, attrsEnd);
+            // Process JSX expression attributes (name={...}) into HTML-safe string attributes
+            let result = '';
+            let aPos = 0;
+            while (aPos < attrs.length) {
+                const attrMatch = attrs.slice(aPos).match(/^(\w+)=\{/);
+                if (attrMatch) {
+                    const attrName = attrMatch[1];
+                    const braceStart2 = aPos + attrMatch[0].length;
+                    // Find matching closing brace, handling nesting + quotes
+                    let depth = 1;
+                    let inDQ = false, inSQ = false, inTL = false;
+                    let j = braceStart2;
+                    for (; j < attrs.length && depth > 0; j++) {
+                        const c = attrs[j];
+                        if (inDQ) {
+                            if (c === '\\')
+                                j++;
+                            else if (c === '"')
+                                inDQ = false;
+                        }
+                        else if (inSQ) {
+                            if (c === '\\')
+                                j++;
+                            else if (c === "'")
+                                inSQ = false;
+                        }
+                        else if (inTL) {
+                            if (c === '\\')
+                                j++;
+                            else if (c === '`')
+                                inTL = false;
+                        }
+                        else {
+                            if (c === '{')
+                                depth++;
+                            else if (c === '}')
+                                depth--;
+                            else if (c === '"')
+                                inDQ = true;
+                            else if (c === "'")
+                                inSQ = true;
+                            else if (c === '`')
+                                inTL = true;
+                        }
+                    }
+                    if (depth === 0) {
+                        const expression = attrs.slice(braceStart2, j - 1);
+                        // Encode " and newlines so the value survives HTML attribute parsing
+                        // and the multiline-collapsing step. parse5 decodes &#10; back to \n.
+                        const escaped = expression.replace(/"/g, '&quot;').replace(/\n/g, '&#10;');
+                        result += `${attrName}="__jsx:${escaped}"`;
+                        aPos = j;
+                    }
+                    else {
+                        result += attrs[aPos];
+                        aPos++;
+                    }
+                }
+                else {
+                    result += attrs[aPos];
+                    aPos++;
+                }
+            }
+            // Collapse multiline attributes to a single line so remark-parse
+            // recognizes the tag as inline HTML.
+            result = result.replace(/\s*\n\s*/g, ' ');
+            // Rename tags that collide with HTML5 built-in elements
+            const rename = HTML5_RENAMES[tagName.toLowerCase()];
+            const safeName = rename || tagName;
+            const safeOpen = `<${safeName}`;
+            // Add text before this tag
+            processed += text.slice(lastEnd, tagStart);
+            // Emit the processed tag
+            if (isSelfClosing) {
+                // Convert self-closing to explicit open+close (HTML5 doesn't honor />
+                // on non-void elements — it swallows subsequent siblings as children).
+                processed += `${safeOpen}${result}></${safeName}>`;
+            }
+            else {
+                processed += `${safeOpen}${result}>`;
+            }
+            lastEnd = tagEnd;
+            // Advance regex past this tag to avoid re-matching inside attrs
+            tagStartRegex.lastIndex = tagEnd;
+        }
+        // Add remaining text
+        processed += text.slice(lastEnd);
+        // Rename closing tags to match the opening tag renames
+        processed = processed.replace(/<\/Image\s*>/gi, '</specra-image>');
+        processed = processed.replace(/<\/Math\s*>/gi, '</specra-math>');
+        // Convert JSX string children to a `children` prop attribute.
+        // In JSX, <Math>{"E = mc^2"}</Math> passes the string as children.
+        // In Svelte, slot content is not a string prop, so we convert it to an attribute.
+        const jsxChildrenRegex = new RegExp(`(<(?:${allNames})[^>]*>)\\s*\\{\\s*(["'])([\\s\\S]*?)\\2\\s*\\}\\s*(<\\/(?:${allNames})\\s*>)`, 'gi');
+        processed = processed.replace(jsxChildrenRegex, (_match, openTag, _quote, content, closeTag) => {
+            // Unescape JavaScript string escape sequences (e.g. \\ → \, \n → newline)
+            const unescaped = content.replace(/\\(.)/g, (_, ch) => {
+                switch (ch) {
+                    case 'n': return '\n';
+                    case 't': return '\t';
+                    case 'r': return '\r';
+                    case '\\': return '\\';
+                    case '"': return '"';
+                    case "'": return "'";
+                    default: return ch;
+                }
+            });
+            // Escape for HTML attribute value
+            const escaped = unescaped.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+            // Inject children prop into the opening tag
+            const newOpenTag = openTag.slice(0, -1) + ` children="${escaped}">`;
+            return `${newOpenTag}${closeTag}`;
+        });
+        return processed;
+    }).join('');
+}
+/**
+ * Parse a JSX expression string into a JavaScript value.
+ * Handles objects like `{ sm: 1, md: 2 }`, numbers, booleans, and strings.
+ */
+function parseJsxExpression(expr) {
+    const trimmed = expr.trim();
+    // Number
+    if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+        return Number(trimmed);
+    }
+    // Boolean
+    if (trimmed === 'true')
+        return true;
+    if (trimmed === 'false')
+        return false;
+    // null/undefined
+    if (trimmed === 'null')
+        return null;
+    if (trimmed === 'undefined')
+        return undefined;
+    // String literal (quoted or template literal)
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'")) ||
+        (trimmed.startsWith('`') && trimmed.endsWith('`'))) {
+        return trimmed.slice(1, -1);
+    }
+    // Object literal like { sm: 1, md: 2 }
+    // Convert JS object syntax to JSON: add quotes around keys
+    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+        try {
+            // Try direct JSON parse first
+            return JSON.parse(trimmed);
+        }
+        catch {
+            // Convert JS object notation to JSON: { sm: 1, md: 2 } → {"sm": 1, "md": 2}
+            const jsonStr = trimmed.replace(/(\w+)\s*:/g, '"$1":').replace(/:\s*'([^']*)'/g, ': "$1"');
+            try {
+                return JSON.parse(jsonStr);
+            }
+            catch {
+                return trimmed;
+            }
+        }
+    }
+    // Array literal
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return trimmed;
+        }
+    }
+    return trimmed;
+}
+/**
+ * Process markdown content to HTML using remark/rehype pipeline.
+ */
+async function processMarkdownToHtml(markdown) {
+    const result = await unified()
+        .use(remarkParse)
+        .use(remarkGfm)
+        .use(remarkMath)
+        .use(remarkRehype, { allowDangerousHtml: true })
+        .use(rehypeRaw)
+        .use(rehypeSlug)
+        .use(rehypeKatex)
+        .use(rehypeStringify)
+        .process(markdown);
+    return String(result);
+}
+/**
+ * Convert hast properties to component props with correct casing.
+ * Also parses back JSX expression values that were encoded during preprocessing.
+ */
+function convertProps(properties) {
+    const props = {};
+    for (const [key, value] of Object.entries(properties)) {
+        const propName = PROP_NAME_MAP[key] || key;
+        // HTML boolean attributes come through as empty strings
+        if (value === '' || value === true) {
+            props[propName] = true;
+        }
+        else if (typeof value === 'string' && value.startsWith('__jsx:')) {
+            // Parse back JSX expressions that were encoded during preprocessing
+            const expression = value.slice(6).replace(/&quot;/g, '"').replace(/&#10;/g, '\n');
+            props[propName] = parseJsxExpression(expression);
+        }
+        else {
+            props[propName] = value;
+        }
+    }
+    return props;
+}
+/**
+ * Check if a hast node is a component element (custom tag).
+ */
+function isComponentElement(node) {
+    return node.type === 'element' && COMPONENT_TAG_MAP[node.tagName] !== undefined;
+}
+/**
+ * Check if a hast node is a fenced code block (<pre><code class="language-*">).
+ * Returns the extracted props for CodeBlock if it is, or null otherwise.
+ */
+function extractCodeBlockProps(node) {
+    if (node.type !== 'element' || node.tagName !== 'pre')
+        return null;
+    const codeChild = node.children?.find((c) => c.type === 'element' && c.tagName === 'code');
+    if (!codeChild)
+        return null;
+    // Extract language from className like ['language-javascript']
+    const classNames = codeChild.properties?.className || [];
+    const langClass = classNames.find((c) => typeof c === 'string' && c.startsWith('language-'));
+    if (!langClass)
+        return null;
+    const language = langClass.replace('language-', '');
+    // Extract text content from the code element
+    const code = extractTextContent(codeChild).replace(/\n$/, '');
+    // Check for filename in data attributes (e.g. from remark-code-meta)
+    const filename = node.properties?.['data-filename'] || codeChild.properties?.['data-filename'];
+    return { code, language, ...(filename ? { filename } : {}) };
+}
+/**
+ * Recursively extract text content from a hast node.
+ */
+function extractTextContent(node) {
+    if (node.type === 'text')
+        return node.value || '';
+    if (node.children) {
+        return node.children.map((c) => extractTextContent(c)).join('');
+    }
+    return '';
+}
+/**
+ * Check if hast children contain raw markdown text that needs re-processing.
+ * This happens when markdown content is inside custom component tags —
+ * the HTML parser treats it as plain text instead of parsing it as markdown.
+ */
+function childrenContainMarkdownText(children) {
+    for (const child of children) {
+        if (child.type === 'text' && child.value) {
+            const text = child.value.trim();
+            if (!text)
+                continue;
+            // Check for markdown patterns: headings, bold, italic, links, lists
+            // Text nodes inside HTML-parsed component tags often start with \n + whitespace
+            if (/(?:^|\n)\s*#{1,6}\s/.test(child.value) || // headings
+                /\*\*/.test(text) || // bold
+                /\[.*\]\(/.test(text) || // links
+                /(?:^|\n)\s*[-*+]\s/.test(child.value) || // unordered lists
+                /(?:^|\n)\s*\d+\.\s/.test(child.value) || // ordered lists
+                (text.length > 10 && /\n/.test(text.trim())) // multi-line text content (paragraphs)
+            ) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Remove common leading whitespace from all lines in a text block.
+ * This is necessary because markdown content inside component tags
+ * inherits indentation from the MDX formatting, and 4+ spaces of
+ * indentation would cause remark to treat lines as code blocks.
+ */
+function dedent(text) {
+    const lines = text.split('\n');
+    // Find the minimum indentation of non-empty lines
+    let minIndent = Infinity;
+    for (const line of lines) {
+        if (line.trim().length === 0)
+            continue;
+        const indent = line.match(/^(\s*)/)?.[1].length ?? 0;
+        if (indent < minIndent)
+            minIndent = indent;
+    }
+    if (minIndent === 0 || minIndent === Infinity)
+        return text;
+    // Strip the common indent from all lines
+    return lines.map(line => line.slice(minIndent)).join('\n');
+}
+/**
+ * Extract raw text from hast children, preserving component tags as placeholders.
+ * Returns the markdown text and a map of placeholders to component MdxNodes.
+ */
+async function processComponentChildren(children) {
+    // Separate text runs from component/element children.
+    // For sequences of text-only nodes, re-process through markdown.
+    // For component elements, process recursively as before.
+    const result = [];
+    let textBuffer = '';
+    async function flushTextBuffer() {
+        if (textBuffer.trim()) {
+            // Dedent the text to remove inherited indentation from MDX formatting,
+            // otherwise 4+ space indented lines get parsed as code blocks
+            const dedented = dedent(textBuffer);
+            // Re-process accumulated text through the markdown pipeline
+            const processor = unified()
+                .use(remarkParse)
+                .use(remarkGfm)
+                .use(remarkMath)
+                .use(remarkRehype, { allowDangerousHtml: true })
+                .use(rehypeRaw)
+                .use(rehypeSlug)
+                .use(rehypeKatex);
+            const mdast = processor.parse(dedented);
+            const hast = await processor.run(mdast);
+            const processedChildren = hast.children || [];
+            // These children are now proper HTML elements (headings, paragraphs, etc.)
+            const nodes = await hastChildrenToMdxNodes(processedChildren);
+            result.push(...nodes);
+        }
+        textBuffer = '';
+    }
+    for (const child of children) {
+        if (child.type === 'text') {
+            textBuffer += child.value || '';
+        }
+        else if (isComponentElement(child)) {
+            await flushTextBuffer();
+            const componentName = COMPONENT_TAG_MAP[child.tagName];
+            const props = convertProps(child.properties || {});
+            const childNodes = child.children && child.children.length > 0
+                ? await processSmartChildren(child.children)
+                : [];
+            result.push({
+                type: 'component',
+                name: componentName,
+                props,
+                children: childNodes,
+            });
+        }
+        else if (child.type === 'element') {
+            // Regular HTML element inside a component — flush text first, then serialize
+            await flushTextBuffer();
+            const codeBlockProps = extractCodeBlockProps(child);
+            if (codeBlockProps) {
+                result.push({
+                    type: 'component',
+                    name: 'CodeBlock',
+                    props: codeBlockProps,
+                    children: [],
+                });
+            }
+            else if (hasNestedComponent(child)) {
+                const openTag = toHtml({ ...child, children: [] }).replace(/<\/[^>]+>$/, '');
+                result.push({ type: 'html', content: openTag });
+                result.push(...await processSmartChildren(child.children));
+                result.push({ type: 'html', content: `</${child.tagName}>` });
+            }
+            else {
+                const html = toHtml(child).trim();
+                if (html) {
+                    result.push({ type: 'html', content: html });
+                }
+            }
+        }
+    }
+    await flushTextBuffer();
+    return result;
+}
+/**
+ * Smart child processing: detects if children contain raw markdown text
+ * and re-processes it through the markdown pipeline if needed.
+ */
+async function processSmartChildren(children) {
+    if (childrenContainMarkdownText(children)) {
+        return processComponentChildren(children);
+    }
+    return hastChildrenToMdxNodes(children);
+}
+/**
+ * Recursively convert hast children to MdxNode array.
+ * Groups consecutive non-component nodes into single HTML blocks.
+ */
+async function hastChildrenToMdxNodes(children) {
+    const nodes = [];
+    let htmlBuffer = [];
+    function flushHtmlBuffer() {
+        if (htmlBuffer.length > 0) {
+            const html = toHtml({ type: 'root', children: htmlBuffer });
+            const trimmed = html.trim();
+            if (trimmed) {
+                nodes.push({ type: 'html', content: trimmed });
+            }
+            else if (html.includes(' ') && !html.includes('\n')) {
+                // Preserve horizontal whitespace between elements (e.g., spaces between inline components).
+                // Newline-only whitespace is formatting and can be discarded.
+                nodes.push({ type: 'html', content: ' ' });
+            }
+            htmlBuffer = [];
+        }
+    }
+    for (const child of children) {
+        // Check for fenced code blocks first (<pre><code class="language-*">)
+        const codeBlockProps = extractCodeBlockProps(child);
+        if (codeBlockProps) {
+            flushHtmlBuffer();
+            nodes.push({
+                type: 'component',
+                name: 'CodeBlock',
+                props: codeBlockProps,
+                children: [],
+            });
+        }
+        else if (isComponentElement(child)) {
+            flushHtmlBuffer();
+            const componentName = COMPONENT_TAG_MAP[child.tagName];
+            const props = convertProps(child.properties || {});
+            const childNodes = child.children && child.children.length > 0
+                ? await processSmartChildren(child.children)
+                : [];
+            nodes.push({
+                type: 'component',
+                name: componentName,
+                props,
+                children: childNodes,
+            });
+        }
+        else {
+            // Check if this regular element contains any component elements nested within
+            if (hasNestedComponent(child)) {
+                flushHtmlBuffer();
+                // This is a regular HTML element that contains component children
+                // We need to handle it specially - wrap it as an HTML open tag,
+                // then process children, then close tag
+                if (child.type === 'element') {
+                    const openTag = toHtml({ ...child, children: [] }).replace(/<\/[^>]+>$/, '');
+                    nodes.push({ type: 'html', content: openTag });
+                    nodes.push(...await hastChildrenToMdxNodes(child.children));
+                    nodes.push({ type: 'html', content: `</${child.tagName}>` });
+                }
+                else {
+                    htmlBuffer.push(child);
+                }
+            }
+            else {
+                htmlBuffer.push(child);
+            }
+        }
+    }
+    flushHtmlBuffer();
+    return nodes;
+}
+/**
+ * Check if a hast node or any of its descendants is a component element.
+ */
+function hasNestedComponent(node) {
+    if (isComponentElement(node))
+        return true;
+    if (node.children) {
+        return node.children.some((child) => hasNestedComponent(child));
+    }
+    return false;
+}
+/**
+ * Process markdown content to a structured MdxNode tree.
+ * Runs the same remark/rehype pipeline but produces an AST
+ * instead of a stringified HTML output.
+ */
+async function processMarkdownToMdxNodes(markdown) {
+    // Pre-process JSX expression attributes into HTML-safe string attributes
+    const preprocessed = preprocessJsxExpressions(markdown);
+    const processor = unified()
+        .use(remarkParse)
+        .use(remarkGfm)
+        .use(remarkMath)
+        .use(remarkRehype, { allowDangerousHtml: true })
+        .use(rehypeRaw)
+        .use(rehypeSlug)
+        .use(rehypeKatex);
+    const mdast = processor.parse(preprocessed);
+    const hast = await processor.run(mdast);
+    // The hast root has children - process them into MdxNodes
+    const children = hast.children || [];
+    return hastChildrenToMdxNodes(children);
+}
+/**
+ * Calculate reading time based on word count
+ * Average reading speed: 200 words per minute
+ */
+function calculateReadingTime(content) {
+    const words = content.trim().split(/\s+/).length;
+    const minutes = Math.ceil(words / 200);
+    return { minutes, words };
+}
+export function getVersions() {
+    try {
+        const versions = fs.readdirSync(DOCS_DIR);
+        return versions.filter((v) => fs.statSync(path.join(DOCS_DIR, v)).isDirectory());
+    }
+    catch (error) {
+        return ["v1.0.0"];
+    }
+}
+/**
+ * Recursively find all MDX files in a directory
+ */
+function findMdxFiles(dir, baseDir = dir) {
+    const files = [];
+    try {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                files.push(...findMdxFiles(fullPath, baseDir));
+            }
+            else if (entry.isFile() && entry.name.endsWith(".mdx")) {
+                // Get relative path from base directory and normalize to forward slashes
+                const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
+                files.push(relativePath);
+            }
+        }
+    }
+    catch (error) {
+        console.error(`Error reading directory ${dir}:`, error);
+    }
+    return files;
+}
+/**
+ * Internal function to read a doc from file path
+ */
+function readDocFromFile(filePath, originalSlug) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        // Validate path is within allowed directory
+        if (!validatePathWithinDirectory(filePath, DOCS_DIR)) {
+            console.error(`[Security] Path traversal attempt blocked: ${filePath}`);
+            return null;
+        }
+        const fileContents = fs.readFileSync(filePath, "utf8");
+        const { data, content } = matter(fileContents);
+        // Security: Validate MDX content for dangerous patterns
+        const securityCheck = validateMDXSecurity(content, {
+            strictMode: process.env.NODE_ENV === 'production',
+            blockDangerousPatterns: true,
+        });
+        if (!securityCheck.valid) {
+            console.error(`[Security] MDX validation failed for ${filePath}:`, securityCheck.issues);
+            if (process.env.NODE_ENV === 'production') {
+                return null;
+            }
+            // In development, log warnings but continue
+            console.warn('[Security] Continuing in development mode with sanitized content');
+        }
+        // Use sanitized content if available
+        const safeContent = securityCheck.sanitized || content;
+        // Calculate reading time
+        const { minutes, words } = calculateReadingTime(safeContent);
+        // If custom slug provided, replace only the filename part, keep the folder structure
+        let finalSlug = originalSlug;
+        if (data.slug) {
+            const customSlug = data.slug.replace(/^\//, '');
+            const parts = originalSlug.split("/");
+            if (parts.length > 1) {
+                // Keep folder structure, replace only filename
+                parts[parts.length - 1] = customSlug;
+                finalSlug = parts.join("/");
+            }
+            else {
+                // Root level file, use custom slug as-is
+                finalSlug = customSlug;
+            }
+        }
+        return {
+            slug: finalSlug,
+            filePath: originalSlug, // Keep original file path for sidebar
+            title: data.title || originalSlug,
+            meta: {
+                ...data,
+                content: safeContent,
+                reading_time: minutes,
+                word_count: words,
+                ...(data.protected === true ? { isProtected: true } : {}),
+            },
+            content: safeContent,
+        };
+    }
+    catch (error) {
+        console.error(`Error reading file ${filePath}:`, error);
+        return null;
+    }
+}
+export function getI18nConfig() {
+    const config = getConfig();
+    const i18n = config.features?.i18n;
+    if (!i18n)
+        return null;
+    if (typeof i18n === 'boolean') {
+        return i18n ? {
+            defaultLocale: 'en',
+            locales: ['en'],
+            localeNames: { en: 'English' }
+        } : null;
+    }
+    return i18n;
+}
+export async function getDocBySlug(slug, version = "v1.0.0", locale) {
+    try {
+        // Security: Sanitize and validate slug
+        const sanitizedVersion = sanitizePath(version);
+        let sanitizedSlug = sanitizePath(slug);
+        // Get i18n config
+        const i18nConfig = getI18nConfig();
+        // Determine locale from slug if not provided
+        let detectedLocale = locale || i18nConfig?.defaultLocale;
+        if (i18nConfig) {
+            const parts = sanitizedSlug.split('/');
+            if (parts.length > 0 && i18nConfig.locales.includes(parts[0])) {
+                detectedLocale = parts[0];
+                sanitizedSlug = parts.slice(1).join('/');
+                if (sanitizedSlug === "")
+                    sanitizedSlug = "index";
+            }
+        }
+        const targetLocale = detectedLocale;
+        const isDefaultLocale = targetLocale === i18nConfig?.defaultLocale;
+        // Try finding the file in this order:
+        // 1. Localized extension: slug.locale.mdx (e.g. guide.fr.mdx)
+        // 2. Default file: slug.mdx (only if using default locale and configured to fallback or strictly default)
+        // Construct potential paths
+        const basePath = path.join(DOCS_DIR, sanitizedVersion);
+        let result = null;
+        // 1. Try localized file extension
+        if (targetLocale) {
+            const localizedPath = path.join(basePath, `${sanitizedSlug}.${targetLocale}.mdx`);
+            const doc = readDocFromFile(localizedPath, sanitizedSlug);
+            if (doc) {
+                doc.slug = i18nConfig ? `${targetLocale}/${sanitizedSlug}` : sanitizedSlug;
+                doc.meta.locale = targetLocale;
+                result = doc;
+            }
+        }
+        // 2. Try default file
+        if (!result) {
+            const defaultPath = path.join(basePath, `${sanitizedSlug}.mdx`);
+            const doc = readDocFromFile(defaultPath, sanitizedSlug);
+            if (doc && (isDefaultLocale || !i18nConfig)) {
+                const usePrefix = i18nConfig && (i18nConfig.prefixDefault || targetLocale !== i18nConfig.defaultLocale);
+                if (usePrefix && targetLocale) {
+                    doc.slug = `${targetLocale}/${doc.slug}`;
+                }
+                doc.meta.locale = targetLocale || 'en';
+                result = doc;
+            }
+        }
+        // Process markdown for the found doc
+        if (result) {
+            const rawContent = result.content;
+            result.content = await processMarkdownToHtml(rawContent);
+            result.contentNodes = await processMarkdownToMdxNodes(rawContent);
+        }
+        return result;
+    }
+    catch (error) {
+        console.error(`Error reading doc ${slug}:`, error);
+        return null;
+    }
+}
+export function getAllDocs(version = "v1.0.0", locale) {
+    try {
+        const versionDir = path.join(DOCS_DIR, version);
+        if (!fs.existsSync(versionDir)) {
+            return [];
+        }
+        // Get i18n config
+        const i18nConfig = getI18nConfig();
+        const targetLocale = locale || i18nConfig?.defaultLocale || 'en';
+        const mdxFiles = findMdxFiles(versionDir);
+        const categoryConfigs = getAllCategoryConfigs(version);
+        const docs = mdxFiles.map((file) => {
+            // file contains path relative to version dir, e.g. "getting-started/intro.mdx" or "intro.fr.mdx"
+            let originalFilePath = file.replace(/\.mdx$/, "");
+            // Handle localized files
+            let isLocalized = false;
+            let fileLocale = i18nConfig?.defaultLocale || 'en';
+            if (i18nConfig) {
+                // Check for .<locale> suffix
+                const parts = originalFilePath.split('.');
+                const lastPart = parts[parts.length - 1];
+                if (i18nConfig.locales.includes(lastPart)) {
+                    fileLocale = lastPart;
+                    isLocalized = true;
+                    originalFilePath = parts.slice(0, -1).join('.');
+                }
+            }
+            // Read doc directly from file (no HTML processing - sidebar only needs metadata)
+            const slug = isLocalized ? originalFilePath : originalFilePath;
+            const filePath = isLocalized
+                ? path.join(versionDir, `${originalFilePath}.${fileLocale}.mdx`)
+                : path.join(versionDir, `${originalFilePath}.mdx`);
+            const doc = readDocFromFile(filePath, slug);
+            if (!doc)
+                return null;
+            // Set locale info
+            if (i18nConfig) {
+                const usePrefix = i18nConfig.prefixDefault || fileLocale !== i18nConfig.defaultLocale;
+                doc.slug = usePrefix ? `${fileLocale}/${doc.slug}` : doc.slug;
+            }
+            doc.meta.locale = fileLocale;
+            // Override filePath properties for sidebar grouping
+            // (we want grouped by logical path, not physically localized path if possible)
+            doc.filePath = originalFilePath; // Use logical path (without .fr) for grouping
+            const folderPath = path.dirname(originalFilePath).replace(/\\/g, '/');
+            if (folderPath !== ".") {
+                const categoryConfig = categoryConfigs.get(folderPath);
+                if (categoryConfig) {
+                    doc.categoryLabel = categoryConfig.label;
+                    doc.categoryPosition = categoryConfig.position ?? categoryConfig.sidebar_position;
+                    doc.categoryCollapsible = categoryConfig.collapsible;
+                    doc.categoryCollapsed = categoryConfig.collapsed;
+                    doc.categoryIcon = categoryConfig.icon;
+                    doc.categoryTabGroup = categoryConfig.tab_group;
+                }
+            }
+            return doc;
+        });
+        const isDevelopment = process.env.NODE_ENV === "development";
+        // Create a map to track unique slugs and avoid duplicates, prioritizing target locale
+        const uniqueDocs = new Map();
+        // Sort docs such that target locale comes first? No, we need to filter/merge.
+        const validDocs = docs.filter((doc) => doc !== null && (isDevelopment || !doc.meta.draft));
+        // Group by logical slug (we stored logical path in filePath, maybe use that?)
+        // Actually doc.slug might differ if custom slug used.
+        // If we have intro.mdx (en) and intro.fr.mdx (fr)
+        // And targetLocale is 'fr'
+        // We want the 'fr' one.
+        validDocs.forEach(doc => {
+            // Identify logical slug. 
+            // If doc.slug already has prefix (e.g. fr/intro), stripped slug is 'intro'.
+            let logicalSlug = doc.slug;
+            if (i18nConfig) {
+                const parts = logicalSlug.split('/');
+                if (i18nConfig.locales.includes(parts[0])) {
+                    logicalSlug = parts.slice(1).join('/');
+                }
+            }
+            const existing = uniqueDocs.get(logicalSlug);
+            if (!existing) {
+                // If doc matches target locale or is default (and we allow default fallback), take it.
+                // For now, take everything, filter later?
+                // Better: Only add if it matches target locale OR is default and we don't have target yet.
+                if (doc.meta.locale === targetLocale) {
+                    uniqueDocs.set(logicalSlug, doc);
+                }
+                else if (doc.meta.locale === i18nConfig?.defaultLocale) {
+                    uniqueDocs.set(logicalSlug, doc);
+                }
+            }
+            else {
+                // We have an existing entry. prefer targetLocale
+                if (doc.meta.locale === targetLocale && existing.meta.locale !== targetLocale) {
+                    uniqueDocs.set(logicalSlug, doc);
+                }
+            }
+        });
+        const sortedDocs = Array.from(uniqueDocs.values()).sort((a, b) => {
+            const orderA = a.meta.sidebar_position ?? a.meta.order ?? 999;
+            const orderB = b.meta.sidebar_position ?? b.meta.order ?? 999;
+            return orderA - orderB;
+        });
+        return sortedDocs;
+    }
+    catch (error) {
+        console.error(`Error getting all docs for version ${version}:`, error);
+        return [];
+    }
+}
+// export function getAdjacentDocs(currentSlug: string, allDocs: Doc[]): { previous?: Doc; next?: Doc } {
+//   const currentIndex = allDocs.findIndex((doc) => doc.slug === currentSlug)
+//   if (currentIndex === -1) {
+//     return {}
+//   }
+//   return {
+//     previous: currentIndex > 0 ? allDocs[currentIndex - 1] : undefined,
+//     next: currentIndex < allDocs.length - 1 ? allDocs[currentIndex + 1] : undefined,
+//   }
+// }
+// Flatten the sidebar structure into a linear order
+function flattenSidebarOrder(rootGroups, standalone) {
+    const flatDocs = [];
+    // Recursively flatten groups - intermix folders and files by position
+    const flattenGroup = (group) => {
+        const sortedChildren = sortSidebarGroups(group.children);
+        const sortedItems = sortSidebarItems(group.items);
+        // Merge child groups and items, then sort by position
+        const merged = [
+            ...sortedChildren.map(([, childGroup]) => ({
+                type: 'group',
+                group: childGroup,
+                position: childGroup.position
+            })),
+            ...sortedItems.map((doc) => ({
+                type: 'item',
+                doc,
+                position: doc.meta.sidebar_position ?? doc.meta.order ?? 999
+            }))
+        ];
+        // Sort by position
+        merged.sort((a, b) => a.position - b.position);
+        // Process in sorted order
+        merged.forEach((item) => {
+            if (item.type === 'group') {
+                flattenGroup(item.group);
+            }
+            else {
+                flatDocs.push(item.doc);
+            }
+        });
+    };
+    // Add standalone items first
+    sortSidebarItems(standalone).forEach((doc) => {
+        flatDocs.push(doc);
+    });
+    // Then add all grouped items
+    const sortedRootGroups = sortSidebarGroups(rootGroups);
+    sortedRootGroups.forEach(([, group]) => {
+        flattenGroup(group);
+    });
+    return flatDocs;
+}
+export function getAdjacentDocs(currentSlug, allDocs) {
+    // Build the same sidebar structure
+    const { rootGroups, standalone } = buildSidebarStructure(allDocs);
+    // Flatten into the same order as shown in the sidebar
+    const orderedDocs = flattenSidebarOrder(rootGroups, standalone);
+    // Find current doc in the ordered list
+    const currentIndex = orderedDocs.findIndex((doc) => doc.slug === currentSlug);
+    if (currentIndex === -1) {
+        return {};
+    }
+    const currentDoc = orderedDocs[currentIndex];
+    // Get current doc's tab group (from meta or category)
+    const currentTabGroup = currentDoc.meta?.tab_group || currentDoc.categoryTabGroup;
+    // Filter docs to match the current doc's tab group status
+    // If current has a tab group, only show docs in the same tab group
+    // If current has NO tab group, only show docs with NO tab group
+    const filteredDocs = orderedDocs.filter((doc) => {
+        const docTabGroup = doc.meta?.tab_group || doc.categoryTabGroup;
+        // If current doc has a tab group, only include docs with the same tab group
+        if (currentTabGroup) {
+            return docTabGroup === currentTabGroup;
+        }
+        // If current doc has no tab group, only include docs with no tab group
+        return !docTabGroup;
+    });
+    // Find current doc's index within the filtered list
+    const filteredIndex = filteredDocs.findIndex((doc) => doc.slug === currentSlug);
+    if (filteredIndex === -1) {
+        return {};
+    }
+    return {
+        previous: filteredIndex > 0 ? filteredDocs[filteredIndex - 1] : undefined,
+        next: filteredIndex < filteredDocs.length - 1 ? filteredDocs[filteredIndex + 1] : undefined,
+    };
+}
+export function extractTableOfContents(content) {
+    const headingRegex = /^(#{2,3})\s+(.+)$/gm;
+    const toc = [];
+    let match;
+    while ((match = headingRegex.exec(content)) !== null) {
+        const level = match[1].length;
+        const text = match[2];
+        // Generate ID the same way rehype-slug does
+        const id = text
+            .toLowerCase()
+            .replace(/\s+/g, "-") // Replace spaces with hyphens first
+            .replace(/[^a-z0-9-]/g, "") // Remove special chars (dots, slashes, etc)
+            .replace(/^-|-$/g, ""); // Remove leading/trailing hyphens
+        toc.push({ id, title: text, level });
+    }
+    return toc;
+}
+/**
+ * Check if a slug represents a category (has child documents)
+ */
+export function isCategoryPage(slug, allDocs) {
+    return allDocs.some((doc) => {
+        const parts = doc.slug.split("/");
+        const docParent = parts.slice(0, -1).join("/");
+        return docParent === slug && doc.slug !== slug;
+    });
+}