@mintlify/common 1.0.1269 → 1.0.1271

package/dist/mdx/plugins/remark/remarkVisibilityForMarkdown.js

@@ -1,4 +1,9 @@
 import { WILDCARD_GROUP, checkGroupAccess, isPageGroups } from '../../../navigation/groupAccess.js';
+import { isObject } from '../../../types/guards.js';
+import { getAST, stringifyTree } from '../../remark-core.js';
+import { BLOCK_LINK_LABEL } from './firstPartyMarkdownComponents.js';
+import { evaluateStatic } from './staticEvaluator.js';
+import { chargeUnfoldBudget, chargeUnfoldCall, collectMarkdownComponentContext, collectUsageProps, containsJsx, createUnfoldBudget, definitionGatesContent, DROP_ELEMENTS, dropPairedDarkOnly, escapeInterpolatedText, HEADING_ELEMENTS, isPresentationalAttribute, UNWRAP_BLOCK_ELEMENTS, UNWRAP_INLINE_ELEMENTS, escapeLinkLabel, extractProgramExpression, markdownLinkDestination, MAX_UNFOLD_DEPTH, GFM_ALERT_PATTERN, HEADLINE_ATTRIBUTES, KEEP_TAG_COMPONENTS, materializeComponent, serializeExpressionJsx, } from './unfoldComponentsForMarkdown.js';
 export function isVisibilityElement(node) {
     return ((node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') &&
         node.name === 'Visibility');
@@ -6,6 +11,19 @@ export function isVisibilityElement(node) {
 function isMdxJsxElement(node) {
     return node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement';
 }
+/** `{}` and `{/* comment *\/}` compile to nothing, so they are not children. */
+function isEmptyChild(node) {
+    var _a;
+    if (node.type === 'text')
+        return node.value.trim() === '';
+    if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
+        const estree = (_a = node.data) === null || _a === void 0 ? void 0 : _a.estree;
+        return estree === undefined || estree === null || estree.body.length === 0;
+    }
+    if (node.type === 'paragraph')
+        return node.children.every((child) => isEmptyChild(child));
+    return false;
+}
 export const VISIBILITY_AUDIENCES = ['humans', 'agents', 'signed-in', 'signed-out'];
 export const VISIBILITY_FOR_EXPECTED = '"humans", "agents", "signed-in", "signed-out", or { groups: [...] }';
 export function isVisibilityAudience(value) {
@@ -60,7 +78,7 @@ function toVisibilityGroups(value) {
     return rule && isPageGroups([rule]) ? rule : undefined;
 }
 export function toVisibilityGroupsRule(value) {
-    if (!isRecord(value) || Object.keys(value).length !== 1)
+    if (!isObject(value) || Object.keys(value).length !== 1)
         return undefined;
     const groups = toVisibilityGroups(value.groups);
     return groups && { groups };
@@ -123,15 +141,21 @@ function mayOverrideFor(attr) {
         return (key !== null && key !== void 0 ? key : literalKey) === 'for';
     });
 }
-export function resolveVisibilityFor(node) {
-    var _a, _b;
+/**
+ * Resolves a `Visibility` audience. With `literalScope`, an evaluated audience that shows content
+ * to agents must resolve the same from literal values alone; otherwise it is dynamic, since an
+ * object it was read from may have been changed by a write the evaluator cannot see.
+ */
+export function resolveVisibilityFor(node, scope = new Map(), literalScope) {
+    var _a, _b, _c;
     let invalidRaw;
     let sawDynamic = false;
     let sawAttribute = false;
     const lastFor = node.attributes.findLastIndex((attr) => attr.type === 'mdxJsxAttribute' && attr.name === 'for');
     if (node.attributes.slice(lastFor + 1).some(mayOverrideFor))
         return { kind: 'dynamic' };
-    for (const attr of node.attributes) {
+    // JSX applies the last `for`, so earlier ones never take effect
+    for (const attr of lastFor === -1 ? [] : node.attributes.slice(lastFor, lastFor + 1)) {
         if (attr.type !== 'mdxJsxAttribute' || attr.name !== 'for')
             continue;
         sawAttribute = true;
@@ -172,6 +196,28 @@ export function resolveVisibilityFor(node) {
                     continue;
                 }
             }
+            const expression = extractProgramExpression('data' in attr.value ? (_c = attr.value.data) === null || _c === void 0 ? void 0 : _c.estree : undefined);
+            const evaluated = evaluateStatic(expression, { scope });
+            if (evaluated.ok) {
+                const value = evaluated.value;
+                if (isVisibilityAudience(value)) {
+                    const resolution = { kind: 'audience', audience: value };
+                    if (literalScope === undefined || isHiddenFromAgents(resolution))
+                        return resolution;
+                    const literal = evaluateStatic(expression, { scope: literalScope });
+                    if (literal.ok && literal.value === value)
+                        return resolution;
+                    sawDynamic = true;
+                    continue;
+                }
+                const rule = toVisibilityGroupsRule(value);
+                if (rule)
+                    return { kind: 'groups', groups: rule.groups };
+                if (typeof value === 'string') {
+                    invalidRaw !== null && invalidRaw !== void 0 ? invalidRaw : (invalidRaw = value);
+                    continue;
+                }
+            }
             sawDynamic = true;
         }
     }
@@ -224,221 +270,579 @@ export function matchesVisibilityAuthRule(rule, viewer) {
         return !viewer.signedIn;
     return checkGroupAccess(toPageGroups(rule.groups), new Set(viewer.signedIn ? [...viewer.groups, WILDCARD_GROUP] : []));
 }
-// `export * from` is intentionally ignored: it exposes no statically-knowable
-// names and creates no page-local JSX bindings in MDX, so there is nothing to
-// collect.
-function collectEsmIdentifiers(node) {
-    var _a, _b, _c;
-    const names = new Set();
-    if (node.type !== 'mdxjsEsm')
-        return names;
-    for (const statement of (_c = (_b = (_a = node.data) === null || _a === void 0 ? void 0 : _a.estree) === null || _b === void 0 ? void 0 : _b.body) !== null && _c !== void 0 ? _c : []) {
-        if (statement.type === 'ImportDeclaration') {
-            for (const specifier of statement.specifiers) {
-                names.add(specifier.local.name);
-            }
+function transformChildren(children, ctx) {
+    return dropPairedDarkOnly(children, (child) => usageClassName(child, ctx)).flatMap((child) => transformNode(child, ctx));
+}
+function usageClassName(node, ctx) {
+    var _a;
+    if (!isMdxJsxElement(node))
+        return undefined;
+    const hasClass = node.attributes.some((attr) => attr.type === 'mdxJsxAttribute' && (attr.name === 'className' || attr.name === 'class'));
+    if (!hasClass)
+        return undefined;
+    const props = collectUsageProps(node, ctx);
+    return (_a = props.get('className')) !== null && _a !== void 0 ? _a : props.get('class');
+}
+const BLOCK_NODE_TYPES = new Set([
+    'blockquote',
+    'code',
+    'heading',
+    'list',
+    'table',
+    'thematicBreak',
+    'definition',
+    'footnoteDefinition',
+    'mdxJsxFlowElement',
+    'mdxFlowExpression',
+    'mdxjsEsm',
+    'yaml',
+    'toml',
+    'math',
+]);
+function wrapPhrasingRuns(nodes) {
+    const result = [];
+    let run = [];
+    const flush = () => {
+        if (run.length === 0)
+            return;
+        const paragraph = { type: 'paragraph', children: [] };
+        replaceChildren(paragraph.children, run);
+        result.push(paragraph);
+        run = [];
+    };
+    for (const node of nodes) {
+        if (BLOCK_NODE_TYPES.has(node.type) || node.type === 'paragraph' || node.type === 'html') {
+            flush();
+            result.push(node);
         }
-        if (statement.type === 'ExportNamedDeclaration') {
-            if (statement.declaration) {
-                if (statement.declaration.type === 'VariableDeclaration') {
-                    for (const declarator of statement.declaration.declarations) {
-                        if (declarator.id.type === 'Identifier') {
-                            names.add(declarator.id.name);
-                        }
-                    }
-                }
-                else if (statement.declaration.id) {
-                    names.add(statement.declaration.id.name);
-                }
-            }
-            // Re-exports: `export { Panel } from '...'` keep names in specifiers
-            for (const specifier of statement.specifiers) {
-                if (specifier.local.type === 'Identifier') {
-                    names.add(specifier.local.name);
-                }
-                if (specifier.exported.type === 'Identifier') {
-                    names.add(specifier.exported.name);
-                }
-            }
+        else {
+            run.push(node);
+        }
+    }
+    flush();
+    return result;
+}
+const PHRASING_NODE_TYPES = new Set([
+    'text',
+    'emphasis',
+    'strong',
+    'delete',
+    'inlineCode',
+    'inlineMath',
+    'break',
+    'link',
+    'image',
+    'linkReference',
+    'imageReference',
+    'footnoteReference',
+    'html',
+    'mdxJsxTextElement',
+    'mdxTextExpression',
+]);
+function isPhrasingContent(node) {
+    return PHRASING_NODE_TYPES.has(node.type);
+}
+function flattenToPhrasing(nodes) {
+    const result = [];
+    const pushGroup = (children) => {
+        if (children.length === 0)
+            return;
+        if (result.length > 0)
+            result.push({ type: 'text', value: ' ' });
+        result.push(...children);
+    };
+    for (const node of nodes) {
+        if (node.type === 'paragraph' || node.type === 'heading') {
+            pushGroup([...node.children]);
+        }
+        else if (node.type === 'blockquote') {
+            pushGroup(flattenToPhrasing([...node.children]));
+        }
+        else if (node.type === 'mdxJsxFlowElement') {
+            // Kept tags such as View carry selectors, so the tag stays and only its content flattens
+            pushGroup([
+                {
+                    type: 'mdxJsxTextElement',
+                    name: node.name,
+                    attributes: node.attributes,
+                    children: flattenToPhrasing([...node.children]).filter(isPhrasingContent),
+                },
+            ]);
+        }
+        else if (node.type === 'list') {
+            for (const item of node.children)
+                pushGroup(flattenToPhrasing([...item.children]));
+        }
+        else if (node.type === 'code') {
+            pushGroup([{ type: 'inlineCode', value: node.value }]);
         }
-        if (statement.type === 'ExportDefaultDeclaration') {
-            const declaration = statement.declaration;
-            if ((declaration.type === 'FunctionDeclaration' || declaration.type === 'ClassDeclaration') &&
-                declaration.id) {
-                names.add(declaration.id.name);
+        else if (node.type === 'table') {
+            for (const row of node.children) {
+                for (const cell of row.children)
+                    pushGroup([...cell.children]);
             }
         }
+        else if (!BLOCK_NODE_TYPES.has(node.type)) {
+            result.push(node);
+        }
     }
-    return names;
+    return result;
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null;
+/**
+ * When a usage's body is one static expression, such as `<Check>{0}</Check>`, `children` is that
+ * value rather than its markdown text, so `children ? … : …` takes the branch React would.
+ */
+function bodyExpressionValue(bodyChildren, ctx) {
+    var _a;
+    let only = bodyChildren.length === 1 ? bodyChildren[0] : undefined;
+    if ((only === null || only === void 0 ? void 0 : only.type) === 'paragraph') {
+        const meaningful = only.children.filter((child) => !isEmptyChild(child));
+        only = meaningful.length === 1 ? meaningful[0] : undefined;
+    }
+    if ((only === null || only === void 0 ? void 0 : only.type) !== 'mdxFlowExpression' && (only === null || only === void 0 ? void 0 : only.type) !== 'mdxTextExpression')
+        return undefined;
+    const evaluated = evaluateStatic(extractProgramExpression((_a = only.data) === null || _a === void 0 ? void 0 : _a.estree), {
+        scope: ctx.moduleScope,
+    });
+    if (!evaluated.ok || (typeof evaluated.value === 'object' && evaluated.value !== null)) {
+        return undefined;
+    }
+    return { value: evaluated.value };
 }
-function getJsxReferenceBaseName(name) {
-    let current = name;
-    while (isRecord(current) && current.type === 'JSXMemberExpression') {
-        current = current.object;
+function unfoldUsage(node, name, ctx) {
+    var _a;
+    const def = ctx.defs.get(name);
+    if (!def)
+        return undefined;
+    const withinLimits = !ctx.stack.includes(def) && ctx.stack.length < MAX_UNFOLD_DEPTH && chargeUnfoldCall(ctx);
+    if (!withinLimits)
+        return definitionGatesContent(def, ctx.defs) ? [] : undefined;
+    const bodyChildren = node.children.filter((child) => !isEmptyChild(child));
+    const transformedChildren = transformChildren(bodyChildren, ctx);
+    const childrenRoot = { type: 'root', children: transformedChildren };
+    const childrenMarkdown = transformedChildren.length > 0 ? stringifyTree(childrenRoot).trim() : '';
+    const failedProps = new Set();
+    const props = collectUsageProps(node, ctx, failedProps);
+    // Body children replace any children attribute, even when they render nothing
+    if (bodyChildren.length > 0) {
+        props.delete('children');
+        failedProps.delete('children');
     }
-    if (isRecord(current) && current.type === 'JSXIdentifier' && typeof current.name === 'string') {
-        return current.name;
+    const trustedFailed = new Set();
+    const trustedProps = collectUsageProps(node, Object.assign(Object.assign({}, ctx), { moduleScope: ctx.literalScope }), trustedFailed);
+    if (bodyChildren.length > 0)
+        trustedProps.delete('children');
+    const markdown = materializeComponent(def, name, props, childrenMarkdown, ctx, failedProps, bodyExpressionValue(bodyChildren, ctx), { props: trustedProps, failedProps: trustedFailed });
+    if (markdown === undefined) {
+        if (definitionGatesContent(def, ctx.defs))
+            return [];
+        // Same fallback as inside definitions: headline and description props still render
+        return ((_a = unfoldForeignUsage(node, name, ctx, transformedChildren)) !== null && _a !== void 0 ? _a : wrapPhrasingRuns(transformedChildren));
+    }
+    if (markdown.trim() === '')
+        return [];
+    if (!chargeUnfoldBudget(ctx, markdown.length)) {
+        return definitionGatesContent(def, ctx.defs) ? [] : wrapPhrasingRuns(transformedChildren);
+    }
+    const innerCtx = Object.assign(Object.assign({}, ctx), { stack: [...ctx.stack, def] });
+    return parseMarkdown(markdown, innerCtx);
+}
+function parseMarkdown(markdown, ctx) {
+    try {
+        // Unfolded output is never real ESM; a line that reads like `import` or `export` is text
+        const children = getAST(markdown).children.map((child) => child.type === 'mdxjsEsm'
+            ? { type: 'paragraph', children: [{ type: 'text', value: child.value }] }
+            : child);
+        return transformChildren(children, ctx);
+    }
+    catch (_a) {
+        return [{ type: 'text', value: markdown }];
+    }
+}
+/** The first of `names` whose prop is a string with visible text. */
+function firstTextProp(props, names) {
+    for (const name of names) {
+        const value = props.get(name);
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
     }
     return undefined;
 }
-// Walks an estree for JSX component references, e.g. `<Logo />` within
-// `export const Header = () => <Logo />` or `{<Demo />}` expressions.
-function collectEstreeJsxNames(estree, names) {
-    const queue = [estree];
-    const seen = new Set();
-    while (queue.length > 0) {
-        const current = queue.pop();
-        if (Array.isArray(current)) {
-            queue.push(...current);
-            continue;
-        }
-        if (!isRecord(current) || seen.has(current))
-            continue;
-        seen.add(current);
-        if (current.type === 'JSXOpeningElement') {
-            const baseName = getJsxReferenceBaseName(current.name);
-            // Lowercase JSX names are intrinsic elements, never component bindings.
-            if (baseName && /^[A-Z]/.test(baseName))
-                names.add(baseName);
+/** A linked headline when the component has an `href`, and a bold one otherwise. */
+function headlineMarkdown(title, href) {
+    const label = escapeInterpolatedText(title);
+    if (typeof href !== 'string' || href === '')
+        return `**${label}**`;
+    return `[${escapeLinkLabel(label)}](${markdownLinkDestination(href)})`;
+}
+function unfoldForeignUsage(node, name, ctx, transformed) {
+    if (KEEP_TAG_COMPONENTS.has(name))
+        return undefined;
+    const props = collectUsageProps(node, ctx);
+    if (props.get('aria-hidden') === true || props.get('aria-hidden') === 'true')
+        return [];
+    const result = [];
+    const title = firstTextProp(props, HEADLINE_ATTRIBUTES);
+    if (title !== undefined) {
+        result.push(...parseMarkdown(headlineMarkdown(title, props.get('href')), ctx));
+    }
+    const transformedChildren = transformed !== null && transformed !== void 0 ? transformed : transformChildren([...node.children], ctx);
+    const hasChildContent = transformedChildren.some((child) => !(child.type === 'text' && child.value.trim() === ''));
+    if (hasChildContent) {
+        result.push(...transformedChildren);
+    }
+    else {
+        const childrenProp = props.get('children');
+        const body = typeof childrenProp === 'number'
+            ? String(childrenProp)
+            : firstTextProp(props, ['children', 'description', 'alt']);
+        if (body !== undefined)
+            result.push(...parseMarkdown(escapeInterpolatedText(body), ctx));
+    }
+    if (result.length === 0) {
+        const ariaLabel = firstTextProp(props, ['aria-label']);
+        if (ariaLabel !== undefined)
+            return parseMarkdown(escapeInterpolatedText(ariaLabel), ctx);
+    }
+    return wrapPhrasingRuns(result);
+}
+function unfoldEmbeddedFrame(node, ctx) {
+    const props = collectUsageProps(node, ctx);
+    if (props.get('aria-hidden') === true || props.get('aria-hidden') === 'true')
+        return [];
+    const rawLabel = firstTextProp(props, ['title', 'aria-label']);
+    const src = props.get('src');
+    if (typeof src === 'string' && src !== '') {
+        const label = escapeInterpolatedText(rawLabel !== null && rawLabel !== void 0 ? rawLabel : src);
+        return parseMarkdown(`[${escapeLinkLabel(label)}](${markdownLinkDestination(src)})`, ctx);
+    }
+    return rawLabel === undefined ? [] : parseMarkdown(escapeInterpolatedText(rawLabel), ctx);
+}
+const PHRASING_WRAPPERS = {
+    strong: 'strong',
+    b: 'strong',
+    em: 'emphasis',
+    i: 'emphasis',
+    del: 'delete',
+    s: 'delete',
+};
+/** HTML written in the page becomes markdown; tags with no markdown form stay without styling. */
+function transformIntrinsicElement(node, name, ctx) {
+    const props = collectUsageProps(node, ctx);
+    if (props.get('aria-hidden') === true || props.get('aria-hidden') === 'true')
+        return [];
+    const fallbackLabel = accessibleLabel(props);
+    const fallback = () => fallbackLabel === '' ? [] : [{ type: 'text', value: fallbackLabel }];
+    if (DROP_ELEMENTS.has(name))
+        return fallback();
+    if (name === 'br')
+        return node.type === 'mdxJsxTextElement' ? [{ type: 'break' }] : [];
+    if (name === 'hr')
+        return [{ type: 'thematicBreak' }];
+    if (name === 'img') {
+        const src = props.get('src');
+        const alt = props.get('alt');
+        if (typeof src === 'string' && src !== '') {
+            return [{ type: 'image', url: src, alt: typeof alt === 'string' ? alt : '' }];
         }
-        queue.push(...Object.values(current));
+        return typeof alt === 'string' && alt !== '' ? [{ type: 'text', value: alt }] : [];
+    }
+    const children = transformChildren([...node.children], ctx);
+    const phrasing = () => flattenToPhrasing(children).filter(isPhrasingContent);
+    if (UNWRAP_BLOCK_ELEMENTS.has(name) || UNWRAP_INLINE_ELEMENTS.has(name)) {
+        return children.length > 0 ? children : fallback();
+    }
+    const depth = HEADING_ELEMENTS[name];
+    if (depth !== undefined) {
+        const text = phrasing();
+        return text.length > 0 ? [{ type: 'heading', depth, children: text }] : [];
+    }
+    const wrapper = PHRASING_WRAPPERS[name];
+    if (wrapper !== undefined) {
+        const text = phrasing();
+        return text.length > 0 ? [{ type: wrapper, children: text }] : [];
+    }
+    if (name === 'code') {
+        const value = textContent(children);
+        return value === '' ? [] : [{ type: 'inlineCode', value }];
+    }
+    if (name === 'blockquote') {
+        if (children.length === 0)
+            return fallback();
+        const blockquote = { type: 'blockquote', children: [] };
+        replaceChildren(blockquote.children, wrapPhrasingRuns(children));
+        return [blockquote];
     }
+    if (name === 'a') {
+        const href = props.get('href');
+        if (typeof href !== 'string' || href === '')
+            return children.length > 0 ? children : fallback();
+        return linkContent(children, href, fallbackLabel);
+    }
+    node.attributes = node.attributes.filter((attr) => attr.type !== 'mdxJsxAttribute' || !isPresentationalAttribute(attr.name));
+    replaceChildren(node.children, children);
+    return [node];
 }
-// JSX rendered inside an ESM node's own declarations, so stripping `Header`
-// can also pull in helpers that only exist to serve it.
-function collectJsxReferences(node) {
-    var _a;
-    const names = new Set();
-    if (node.type === 'mdxjsEsm') {
-        collectEstreeJsxNames((_a = node.data) === null || _a === void 0 ? void 0 : _a.estree, names);
+function isBlockHtmlElement(name) {
+    return (HEADING_ELEMENTS[name] !== undefined ||
+        UNWRAP_BLOCK_ELEMENTS.has(name) ||
+        name === 'blockquote' ||
+        name === 'hr');
+}
+function accessibleLabel(props) {
+    for (const key of ['aria-label', 'title']) {
+        const value = props.get(key);
+        if (typeof value === 'string' && value.trim() !== '')
+            return value;
     }
-    return names;
+    return '';
 }
-// Classifies every JSX component usage on the page: names used only inside
-// `<Visibility for="humans">` land in `hiddenNames`, everything else in
-// `visibleNames`. Usage inside an agents block counts as visible since that
-// content survives into the markdown output.
-function collectJsxUsage(nodes, insideHumans, hiddenNames, visibleNames) {
-    var _a, _b, _c;
+/**
+ * A link label holds only inline content, so a link around blocks moves onto their first
+ * heading, or follows them as its own line.
+ */
+function linkContent(children, url, accessible) {
+    const blocks = wrapPhrasingRuns(children);
+    const [first] = blocks;
+    if (blocks.length === 0 || (blocks.length === 1 && (first === null || first === void 0 ? void 0 : first.type) === 'paragraph')) {
+        const text = flattenToPhrasing(children).filter(isPhrasingContent);
+        const label = accessible === '' ? url : accessible;
+        return [
+            { type: 'link', url, children: text.length > 0 ? text : [{ type: 'text', value: label }] },
+        ];
+    }
+    const label = accessible === '' ? BLOCK_LINK_LABEL : accessible;
+    const heading = blocks.find((block) => block.type === 'heading');
+    if ((heading === null || heading === void 0 ? void 0 : heading.type) === 'heading') {
+        heading.children = [{ type: 'link', url, children: heading.children }];
+        return blocks;
+    }
+    return [
+        ...blocks,
+        {
+            type: 'paragraph',
+            children: [{ type: 'link', url, children: [{ type: 'text', value: label }] }],
+        },
+    ];
+}
+function textContent(nodes) {
+    let text = '';
     for (const node of nodes) {
-        let childInsideHumans = insideHumans;
-        if (isMdxJsxElement(node)) {
-            if (node.name === 'Visibility') {
-                const resolution = resolveVisibilityFor(node);
-                if (isHiddenFromAgents(resolution))
-                    childInsideHumans = true;
-            }
-            else {
-                const baseName = (_a = node.name) === null || _a === void 0 ? void 0 : _a.split('.')[0];
-                // Lowercase JSX names are intrinsic elements, never component bindings.
-                if (baseName && /^[A-Z]/.test(baseName)) {
-                    (insideHumans ? hiddenNames : visibleNames).add(baseName);
-                }
-            }
+        if (node.type === 'text' || node.type === 'inlineCode')
+            text += node.value;
+        else if ('children' in node)
+            text += textContent(node.children);
+    }
+    return text;
+}
+function unfoldComponentElement(node, name, ctx) {
+    var _a;
+    if (name === 'Visibility')
+        return undefined;
+    const baseName = name.split('.')[0];
+    if (baseName === undefined || !/^[A-Z]/.test(baseName))
+        return undefined;
+    const element = name === 'Steps' ? withStepDefaults(node, ctx) : node;
+    return (_a = unfoldUsage(element, name, ctx)) !== null && _a !== void 0 ? _a : unfoldForeignUsage(element, name, ctx);
+}
+/** `Steps` numbers its `Step` children and passes its `titleSize` down; a Step's own props win. */
+function withStepDefaults(node, ctx) {
+    const titleSize = collectUsageProps(node, ctx).get('titleSize');
+    let index = 0;
+    const number = (child) => {
+        // A one-line `<Step>` parses as inline, inside a paragraph of its own, and Steps flattens
+        // fragments before numbering
+        if (child.type === 'paragraph')
+            return Object.assign(Object.assign({}, child), { children: child.children.map(number) });
+        if (isMdxJsxElement(child) && child.name === null) {
+            return Object.assign(Object.assign({}, child), { children: child.children.map(number) });
         }
-        // Expression-embedded usages like `{<Demo />}` live in estree, not mdast.
-        if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
-            collectEstreeJsxNames((_b = node.data) === null || _b === void 0 ? void 0 : _b.estree, insideHumans ? hiddenNames : visibleNames);
+        // Agent markdown unwraps a Visibility agents can see, so its Steps keep counting; one hidden
+        // from agents is dropped and takes no number
+        if (isMdxJsxElement(child) && child.name === 'Visibility') {
+            const resolution = resolveVisibilityFor(child, ctx.moduleScope, ctx.literalScope);
+            if (resolution.kind === 'invalid' || isHiddenFromAgents(resolution))
+                return child;
+            return Object.assign(Object.assign({}, child), { children: child.children.map(number) });
         }
-        // Attribute-embedded usages like `<Card icon={<Logo />}>` also live in estree.
-        if (isMdxJsxElement(node)) {
-            for (const attr of node.attributes) {
-                const expression = attr.type === 'mdxJsxAttribute' ? attr.value : attr;
-                if (expression && typeof expression === 'object' && 'data' in expression) {
-                    collectEstreeJsxNames((_c = expression.data) === null || _c === void 0 ? void 0 : _c.estree, insideHumans ? hiddenNames : visibleNames);
-                }
-            }
+        if (!isMdxJsxElement(child) || child.name !== 'Step')
+            return child;
+        index += 1;
+        const defaults = [
+            { type: 'mdxJsxAttribute', name: 'stepNumber', value: String(index) },
+        ];
+        if (typeof titleSize === 'string') {
+            defaults.push({ type: 'mdxJsxAttribute', name: 'titleSize', value: titleSize });
         }
-        if ('children' in node && Array.isArray(node.children)) {
-            collectJsxUsage(node.children, childInsideHumans, hiddenNames, visibleNames);
+        return Object.assign(Object.assign({}, child), { attributes: [...defaults, ...child.attributes] });
+    };
+    return Object.assign(Object.assign({}, node), { children: node.children.map(number) });
+}
+function withinUnfoldBudget(ctx, cost) {
+    if (cost > ctx.budget.remainingBytes)
+        return false;
+    return chargeUnfoldBudget(ctx, cost);
+}
+function transformExpression(node, ctx) {
+    var _a;
+    const expression = extractProgramExpression((_a = node.data) === null || _a === void 0 ? void 0 : _a.estree);
+    if (expression === undefined)
+        return undefined;
+    const jsx = serializeExpressionJsx(expression, ctx);
+    if (jsx !== undefined) {
+        const trimmed = jsx.trim();
+        if (trimmed === '')
+            return [];
+        if (!withinUnfoldBudget(ctx, trimmed.length))
+            return undefined;
+        try {
+            return transformChildren(getAST(trimmed).children, ctx);
         }
+        catch (_b) {
+            return [{ type: 'text', value: trimmed }];
+        }
+    }
+    const evaluated = evaluateStatic(expression, { scope: ctx.moduleScope });
+    if (evaluated.ok) {
+        const value = evaluated.value;
+        if (value === null || value === undefined || typeof value === 'boolean')
+            return [];
+        if (typeof value === 'object')
+            return [];
+        const text = String(value);
+        if (!withinUnfoldBudget(ctx, text.length))
+            return undefined;
+        return [{ type: 'text', value: text }];
     }
+    // Kept as source, the expression would print `Visibility` copy agents should not see
+    if (containsJsx(expression, 'Visibility'))
+        return [];
+    return undefined;
 }
-function transformChildren(children, esmToStrip) {
-    return children.flatMap((child) => transformNode(child, esmToStrip));
+function promoteComponentOnlyParagraph(node, ctx) {
+    const meaningful = dropPairedDarkOnly(node.children.filter((child) => !(child.type === 'text' && child.value.trim() === '')), (child) => usageClassName(child, ctx));
+    if (meaningful.length === 0)
+        return undefined;
+    const result = [];
+    for (const child of meaningful) {
+        // A one-line `<h2>` or `<div>` parses as inline but stands for a block; inline tags stay in
+        // their paragraph so the spaces between them survive
+        if (child.type === 'mdxJsxTextElement' && typeof child.name === 'string') {
+            if (isBlockHtmlElement(child.name)) {
+                result.push(...transformIntrinsicElement(child, child.name, ctx));
+                continue;
+            }
+            if (/^[a-z]/.test(child.name))
+                return undefined;
+        }
+        if (child.type === 'mdxJsxTextElement' &&
+            typeof child.name === 'string' &&
+            child.name !== 'Visibility') {
+            const unfolded = unfoldComponentElement(child, child.name, ctx);
+            if (unfolded === undefined)
+                return undefined;
+            result.push(...unfolded);
+            continue;
+        }
+        if (child.type === 'mdxTextExpression') {
+            const transformed = transformExpression(child, ctx);
+            if (transformed === undefined)
+                return undefined;
+            result.push(...transformed);
+            continue;
+        }
+        return undefined;
+    }
+    return wrapPhrasingRuns(result);
 }
-function transformNode(node, esmToStrip) {
-    // Snippet definitions are only stripped when every usage of the components
-    // they declare sits inside a `<Visibility for="humans">` block; JSX that the
-    // author left visible keeps its definition in the markdown output.
+function transformNode(node, ctx) {
     if (node.type === 'mdxjsEsm') {
-        return esmToStrip.has(node) ? [] : [node];
+        return [];
+    }
+    // A fragment renders only its children
+    if (isMdxJsxElement(node) && node.name === null) {
+        const unwrapped = transformChildren([...node.children], ctx);
+        return node.type === 'mdxJsxTextElement' ? flattenToPhrasing(unwrapped) : unwrapped;
     }
     if (isMdxJsxElement(node) && node.name === 'Visibility') {
-        const resolution = resolveVisibilityFor(node);
+        const resolution = resolveVisibilityFor(node, ctx.moduleScope, ctx.literalScope);
         if (resolution.kind === 'invalid') {
             console.warn(`<Visibility for="${resolution.raw}"> has an unknown audience — expected ${VISIBILITY_FOR_EXPECTED}. The content was removed from the markdown output.`);
             return [];
         }
         if (isHiddenFromAgents(resolution))
             return [];
-        if (resolution.kind === 'audience') {
-            return transformChildren(node.children, esmToStrip);
+        return transformChildren(node.children, ctx);
+    }
+    if (isMdxJsxElement(node) && (node.name === 'iframe' || node.name === 'embed')) {
+        const unfolded = unfoldEmbeddedFrame(node, ctx);
+        return node.type === 'mdxJsxTextElement' ? flattenToPhrasing(unfolded) : unfolded;
+    }
+    if (isMdxJsxElement(node) && typeof node.name === 'string' && /^[a-z]/.test(node.name)) {
+        const converted = transformIntrinsicElement(node, node.name, ctx);
+        return node.type === 'mdxJsxTextElement'
+            ? flattenToPhrasing(converted)
+            : wrapPhrasingRuns(converted);
+    }
+    if (node.type === 'paragraph') {
+        const promoted = promoteComponentOnlyParagraph(node, ctx);
+        if (promoted !== undefined)
+            return promoted;
+    }
+    if (isMdxJsxElement(node) && typeof node.name === 'string' && node.name !== '') {
+        const unfolded = unfoldComponentElement(node, node.name, ctx);
+        if (unfolded !== undefined) {
+            return node.type === 'mdxJsxTextElement' ? flattenToPhrasing(unfolded) : unfolded;
         }
     }
+    if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') {
+        const transformed = transformExpression(node, ctx);
+        if (transformed === undefined)
+            return [node];
+        return node.type === 'mdxTextExpression'
+            ? flattenToPhrasing(transformed)
+            : wrapPhrasingRuns(transformed);
+    }
     if ('children' in node && Array.isArray(node.children)) {
-        const next = transformChildren(node.children, esmToStrip);
-        node.children = next;
+        replaceChildren(node.children, transformChildren([...node.children], ctx));
     }
     return [node];
 }
-export const remarkVisibilityForMarkdown = () => (tree) => {
-    var _a, _b, _c, _d;
-    const hiddenNames = new Set();
-    const visibleNames = new Set();
-    collectJsxUsage(tree.children, false, hiddenNames, visibleNames);
-    const esmNodes = tree.children.filter((child) => child.type === 'mdxjsEsm');
-    const declaredNames = new Map(esmNodes.map((node) => [node, [...collectEsmIdentifiers(node)]]));
-    const referencedNames = new Map(esmNodes.map((node) => [node, [...collectJsxReferences(node)]]));
-    const esmToStrip = new Set();
-    // Keep-alive fixed point: a node with any visibly-used name keeps every
-    // name it declares or renders visible, so a visible `<PanelAlias />` keeps
-    // the `export const Panel = ...` node it aliases, and a kept `Footer` keeps
-    // the `Logo` helper it renders, even when both live in separate ESM nodes.
-    let visibleChanged = true;
-    while (visibleChanged) {
-        visibleChanged = false;
-        for (const node of esmNodes) {
-            const declared = (_a = declaredNames.get(node)) !== null && _a !== void 0 ? _a : [];
-            if (!declared.some((name) => visibleNames.has(name)))
-                continue;
-            for (const name of [...declared, ...((_b = referencedNames.get(node)) !== null && _b !== void 0 ? _b : [])]) {
-                if (!visibleNames.has(name)) {
-                    visibleNames.add(name);
-                    visibleChanged = true;
+function replaceChildren(children, next) {
+    children.length = 0;
+    children.push(...next);
+}
+function normalizeGfmAlerts(nodes) {
+    for (const node of nodes) {
+        if (node.type === 'blockquote') {
+            const [first] = node.children;
+            if ((first === null || first === void 0 ? void 0 : first.type) === 'paragraph') {
+                const [firstChild] = first.children;
+                if ((firstChild === null || firstChild === void 0 ? void 0 : firstChild.type) === 'text') {
+                    const match = GFM_ALERT_PATTERN.exec(firstChild.value);
+                    if (match) {
+                        const remainder = firstChild.value.slice(match[0].length).replace(/^\n/, '');
+                        if (remainder === '') {
+                            first.children.shift();
+                            if (first.children.length === 0)
+                                node.children.shift();
+                        }
+                        else {
+                            firstChild.value = remainder;
+                        }
+                        node.children.unshift({ type: 'html', value: match[0] });
+                    }
                 }
             }
         }
-    }
-    // Fixed point: stripping a node marks everything it declares or renders as
-    // hidden, so `export { Panel as PanelAlias }` pulls in the `export const
-    // Panel = ...` it aliases, and a stripped `Header` pulls in the `Logo`
-    // helper rendered only inside its body, instead of leaking their source.
-    let changed = true;
-    while (changed) {
-        changed = false;
-        for (const node of esmNodes) {
-            if (esmToStrip.has(node))
-                continue;
-            const names = (_c = declaredNames.get(node)) !== null && _c !== void 0 ? _c : [];
-            // Declared-but-never-rendered names don't block stripping: when a node
-            // mixes a hidden component with unused names, hiding wins over leaking.
-            const hiddenOnly = names.some((name) => hiddenNames.has(name)) &&
-                !names.some((name) => visibleNames.has(name));
-            if (!hiddenOnly)
-                continue;
-            esmToStrip.add(node);
-            // Visible names stay out of hiddenNames so the two sets stay disjoint.
-            for (const name of [...names, ...((_d = referencedNames.get(node)) !== null && _d !== void 0 ? _d : [])]) {
-                if (!hiddenNames.has(name) && !visibleNames.has(name)) {
-                    hiddenNames.add(name);
-                    changed = true;
-                }
-            }
+        if ('children' in node && Array.isArray(node.children)) {
+            normalizeGfmAlerts([...node.children]);
         }
     }
-    tree.children = transformChildren(tree.children, esmToStrip);
+}
+export const remarkVisibilityForMarkdown = () => (tree) => {
+    const componentContext = collectMarkdownComponentContext(tree);
+    const ctx = Object.assign(Object.assign({}, componentContext), { stack: [], budget: createUnfoldBudget() });
+    tree.children = transformChildren(tree.children, ctx);
+    normalizeGfmAlerts(tree.children);
 };