@mintlify/common 1.0.1269 → 1.0.1271

package/dist/mdx/remark-core.d.ts

@@ -0,0 +1,7 @@
+import type { Root } from 'mdast';
+import type { PluggableList } from 'unified';
+export declare const coreRemarkMdxPlugins: PluggableList;
+export declare const coreRemark: import("unified").Processor<Root, undefined, undefined, Root, string>;
+export declare const getAST: (str: string, filePath?: string) => Root;
+export declare const stringifyTree: (tree: Root) => string;
+export declare const stringifyTreeForAgents: (tree: Root) => string;

package/dist/mdx/remark-core.js

@@ -0,0 +1,32 @@
+import { remark } from 'remark';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
+import remarkMdx from 'remark-mdx';
+import remarkStringify from 'remark-stringify';
+import { preprocessCustomHeadingIds } from './preprocessCustomHeadingIds.js';
+import { preprocessMdxFragmentCode } from './preprocessMdxFragmentCode.js';
+import { getJsxEsmTree } from './snippets/getJsxEsmTree.js';
+import { isJsxOrTsx } from './snippets/isJsxOrTsx.js';
+export const coreRemarkMdxPlugins = [
+    remarkMdx,
+    remarkGfm,
+    [remarkFrontmatter, ['yaml', 'toml']],
+    remarkMath,
+];
+export const coreRemark = remark().use(coreRemarkMdxPlugins).freeze();
+const agentRemarkMdxPlugins = [
+    remarkMdx,
+    [remarkGfm, { tablePipeAlign: false }],
+    [remarkFrontmatter, ['yaml', 'toml']],
+    remarkMath,
+];
+const agentRemark = remark().use(agentRemarkMdxPlugins).freeze();
+export const getAST = (str, filePath) => {
+    if (isJsxOrTsx(filePath)) {
+        return getJsxEsmTree(str, filePath);
+    }
+    return coreRemark().parse(preprocessCustomHeadingIds(preprocessMdxFragmentCode(str)));
+};
+export const stringifyTree = (tree) => coreRemark().use(remarkStringify).stringify(tree);
+export const stringifyTreeForAgents = (tree) => agentRemark().use(remarkStringify).stringify(tree);

package/dist/mdx/remark.d.ts

@@ -1,10 +1,4 @@
-import type { Root } from 'mdast';
-import type { PluggableList } from 'unified';
 import { type RemarkUserMentionsOptions } from './plugins/remark/remarkUserMentions.js';
-export declare const coreRemarkMdxPlugins: PluggableList;
-export declare const coreRemark: import("unified").Processor<Root, undefined, undefined, Root, string>;
-export declare const getAST: (str: string, filePath?: string) => Root;
-export declare const stringifyTree: (tree: Root) => string;
-export declare const stringifyTreeForAgents: (tree: Root) => string;
+export { coreRemark, coreRemarkMdxPlugins, getAST, stringifyTree, stringifyTreeForAgents, } from './remark-core.js';
 export declare function stripVisibilityForMarkdown(mdx: string): string;
 export declare function transformContentForMarkdown(mdx: string, mentionOptions?: RemarkUserMentionsOptions): string;

package/dist/mdx/remark.js

@@ -1,37 +1,7 @@
-import { remark } from 'remark';
-import remarkFrontmatter from 'remark-frontmatter';
-import remarkGfm from 'remark-gfm';
-import remarkMath from 'remark-math';
-import remarkMdx from 'remark-mdx';
-import remarkStringify from 'remark-stringify';
 import { remarkUserMentions, } from './plugins/remark/remarkUserMentions.js';
 import { remarkVisibilityForMarkdown } from './plugins/remark/remarkVisibilityForMarkdown.js';
-import { preprocessCustomHeadingIds } from './preprocessCustomHeadingIds.js';
-import { preprocessMdxFragmentCode } from './preprocessMdxFragmentCode.js';
-import { getJsxEsmTree } from './snippets/getJsxEsmTree.js';
-import { isJsxOrTsx } from './snippets/isJsxOrTsx.js';
-export const coreRemarkMdxPlugins = [
-    remarkMdx,
-    remarkGfm,
-    [remarkFrontmatter, ['yaml', 'toml']],
-    remarkMath,
-];
-export const coreRemark = remark().use(coreRemarkMdxPlugins).freeze();
-const agentRemarkMdxPlugins = [
-    remarkMdx,
-    [remarkGfm, { tablePipeAlign: false }],
-    [remarkFrontmatter, ['yaml', 'toml']],
-    remarkMath,
-];
-const agentRemark = remark().use(agentRemarkMdxPlugins).freeze();
-export const getAST = (str, filePath) => {
-    if (isJsxOrTsx(filePath)) {
-        return getJsxEsmTree(str, filePath);
-    }
-    return coreRemark().parse(preprocessCustomHeadingIds(preprocessMdxFragmentCode(str)));
-};
-export const stringifyTree = (tree) => coreRemark().use(remarkStringify).stringify(tree);
-export const stringifyTreeForAgents = (tree) => agentRemark().use(remarkStringify).stringify(tree);
+import { getAST, stringifyTreeForAgents } from './remark-core.js';
+export { coreRemark, coreRemarkMdxPlugins, getAST, stringifyTree, stringifyTreeForAgents, } from './remark-core.js';
 export function stripVisibilityForMarkdown(mdx) {
     const tree = getAST(mdx);
     remarkVisibilityForMarkdown()(tree);

package/dist/mdx/snippets/getExportMap.js

@@ -1,5 +1,6 @@
 import { jsx, toJs } from 'estree-util-to-js';
 import { visit } from 'unist-util-visit';
+import { collectPatternNames } from '../estreeReferences.js';
 import { moduleExportName } from './importedExportName.js';
 import { nodeIncludesExport } from './nodeIncludesExport.js';
 import { addExportPrefix } from './resolveImport/addExportPrefix.js';
@@ -11,6 +12,7 @@ export const getExportMapFromTree = (tree) => {
     var _a;
     const exportMap = {};
     visit(tree, (node) => {
+        var _a;
         if (!nodeIncludesExport(node))
             return;
         for (const bodyChild of node.data.estree.body) {
@@ -39,8 +41,8 @@ export const getExportMapFromTree = (tree) => {
                 for (const specifier of bodyChild.specifiers) {
                     const localName = specifier.local.name;
                     const exportedName = moduleExportName(specifier.exported);
-                    // Find the original declaration
-                    const originalDeclaration = findDeclarationInTree(localName, node);
+                    // Find the original declaration, which may itself be exported
+                    const originalDeclaration = (_a = findDeclarationInTree(localName, node)) !== null && _a !== void 0 ? _a : findExportedDeclaration(localName, tree);
                     if (originalDeclaration) {
                         const wrappedNode = structuredClone(node);
                         wrappedNode.data.estree.body = [originalDeclaration];
@@ -55,15 +57,15 @@ export const getExportMapFromTree = (tree) => {
                 // Variable declarations
                 if (bodyChild.declaration.type === 'VariableDeclaration') {
                     for (const declaration of bodyChild.declaration.declarations) {
-                        if (declaration.id.type !== 'Identifier')
-                            continue;
                         if (declaration.init == null)
                             continue;
                         // Sometimes when more than one exports are defined next to each other, the body includes multiple exports so we isolate the export we are looking for.
                         const isolatedExport = structuredClone(node);
                         isolatedExport.data.estree.body = [bodyChild];
                         const value = toJs(isolatedExport.data.estree, { handlers: jsx }).value;
-                        exportMap[declaration.id.name] = value;
+                        // A destructured declaration binds every name in its pattern with the same statement
+                        for (const name of patternNames(declaration.id))
+                            exportMap[name] = value;
                     }
                 }
                 // Function declarations
@@ -89,6 +91,32 @@ export const getExportMapFromTree = (tree) => {
     }
     return exportMap;
 };
+function patternNames(pattern) {
+    const names = new Set();
+    collectPatternNames(pattern, names);
+    return names;
+}
+function findExportedDeclaration(name, tree) {
+    let found = null;
+    visit(tree, (node) => {
+        var _a;
+        if (found !== null || !nodeIncludesExport(node))
+            return;
+        for (const bodyChild of node.data.estree.body) {
+            if (bodyChild.type !== 'ExportNamedDeclaration' || bodyChild.declaration == null)
+                continue;
+            const declaration = bodyChild.declaration;
+            const declares = declaration.type === 'VariableDeclaration'
+                ? declaration.declarations.some((declarator) => patternNames(declarator.id).has(name))
+                : ((_a = declaration.id) === null || _a === void 0 ? void 0 : _a.name) === name;
+            if (declares) {
+                found = bodyChild;
+                return;
+            }
+        }
+    });
+    return found;
+}
 /**
  * Find a declaration by name in the tree
  */

package/dist/mdx/snippets/resolveAllImports.js

@@ -16,7 +16,7 @@ import { estreeIsProgram, isImportDeclaration, isMdxJsEsm } from '../utils.js';
 import { findAndRemoveImports } from './findAndRemoveImports.js';
 import { getExportMapFromTree } from './getExportMap.js';
 import { getSpecifierPackageName } from './isBareSpecifier.js';
-import { resolveImport } from './resolveImport/index.js';
+import { createImportResolutionState, resolveImport } from './resolveImport/index.js';
 import { injectToTopOfFileOfTree } from './resolveImport/injectToTopOfFile.js';
 import { resolveImportPath } from './resolveImportPath.js';
 const hasImportDeclaration = (node) => isMdxJsEsm(node) && estreeIsProgram(node) && node.data.estree.body.some(isImportDeclaration);
@@ -119,6 +119,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
         ? takePackageReExports(ast, packages.packageNames)
         : [];
     const exportMap = getExportMapFromTree(ast);
+    const importState = createImportResolutionState();
     const strippedSnippets = new Map();
     for (const source of Object.keys(fileWithImports.importMap)) {
         const resolvedPath = resolveImportPath(source, fileWithImports.filename);
@@ -198,7 +199,7 @@ export const resolveAllImports = (params) => __awaiter(void 0, void 0, void 0, f
                     else {
                         console.log(located.message);
                     }
-                });
+                }, importState);
                 if (contentWithResolvedImport == undefined) {
                     throw new Error('Import failed to resolve');
                 }

package/dist/mdx/snippets/resolveImport/exportCollision.d.ts

@@ -3,5 +3,6 @@ export type ExportCollisionWarning = {
     message: string;
 };
 export type OnExportCollision = (warning: ExportCollisionWarning) => void;
+export declare const isSameStatement: (left: string, right: string) => boolean;
 /** Same name, different code: the first declaration wins, so say so instead of failing silently. */
 export declare const warnOnExportCollision: (name: string, existing: string, incoming: string, onWarning?: OnExportCollision) => void;

package/dist/mdx/snippets/resolveImport/exportCollision.js

@@ -1,7 +1,8 @@
 const normalizeStatement = (statement) => statement.replace(/\s+/g, ' ').trim();
+export const isSameStatement = (left, right) => normalizeStatement(left) === normalizeStatement(right);
 /** Same name, different code: the first declaration wins, so say so instead of failing silently. */
 export const warnOnExportCollision = (name, existing, incoming, onWarning) => {
-    if (normalizeStatement(existing) === normalizeStatement(incoming))
+    if (isSameStatement(existing, incoming))
         return;
     onWarning === null || onWarning === void 0 ? void 0 : onWarning({
         type: 'export-collision',

package/dist/mdx/snippets/resolveImport/index.d.ts

@@ -1,14 +1,24 @@
 import type { Root } from 'mdast';
 import type { ImportSpecifier } from '../../../types/mdx/snippets/import.js';
+import { collectContextFromTree } from '../../plugins/remark/staticEvaluator.js';
 import { type OnExportCollision } from './exportCollision.js';
 export { type ExportCollisionWarning, type OnExportCollision } from './exportCollision.js';
 export { findExport } from './findExport.js';
 export { injectToTopOfFileOfTree } from './injectToTopOfFile.js';
+/** What one page's imports have resolved so far. Pass the same state for every import of a page. */
+export interface ImportResolutionState {
+    /** The local name the page declares for each binding of each imported snippet */
+    bindings: Map<Root, Map<string, string>>;
+    /** Evaluated module scope of each imported snippet */
+    contexts: Map<Root, ReturnType<typeof collectContextFromTree>>;
+}
+export declare const createImportResolutionState: () => ImportResolutionState;
 /**
  *
  * @param importSpecifier The name of the imported component we want to replace
  * @param destinationPageContent The content of the page we want to inject the import into
  * @param importedFileContent The content of the file we are importing from
+ * @param state Shared by every import of one page, so readers of a snippet binding share one value
  * @returns
  */
-export declare const resolveImport: (importSpecifier: ImportSpecifier, destinationPageContent: Root, importedFileContent: Root, exportMap: Record<string, string>, onWarning?: OnExportCollision) => Promise<Root | undefined>;
+export declare const resolveImport: (importSpecifier: ImportSpecifier, destinationPageContent: Root, importedFileContent: Root, exportMap: Record<string, string>, onWarning?: OnExportCollision, state?: ImportResolutionState) => Promise<Root | undefined>;

package/dist/mdx/snippets/resolveImport/index.js

@@ -8,18 +8,39 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { MdxImportSpecifier } from '../../../types/mdx/snippets/import.js';
+import { collectContextFromTree, serializeStaticValue, } from '../../plugins/remark/staticEvaluator.js';
 import { getAST } from '../../remark.js';
 import { getExportMapFromTree } from '../getExportMap.js';
 import { warnOnExportCollision } from './exportCollision.js';
 import { findExport } from './findExport.js';
 import { injectToTopOfFileOfTree } from './injectToTopOfFile.js';
 import { resolveComponentWithContent } from './resolveComponentWithContent.js';
+import { collectExportedNames, collectTopLevelBindingNames, declarationSource, exportedBindingName, injectBelowEagerDependencies, isolateExportedDeclarator, patternSiblingNames, prepareSnippetSiblings, } from './snippetDeclarations.js';
 export { findExport } from './findExport.js';
 export { injectToTopOfFileOfTree } from './injectToTopOfFile.js';
 const VALID_SPECIFIERS = [
     MdxImportSpecifier.ImportSpecifier,
     MdxImportSpecifier.RenamedImportSpecifier,
 ];
+export const createImportResolutionState = () => ({
+    bindings: new Map(),
+    contexts: new Map(),
+});
+/** The local names this page already declares for each binding of `snippet`. */
+function heldSnippetBindings(state, snippet) {
+    var _a;
+    const held = (_a = state.bindings.get(snippet)) !== null && _a !== void 0 ? _a : new Map();
+    state.bindings.set(snippet, held);
+    return held;
+}
+function snippetContext(state, tree) {
+    const cached = state.contexts.get(tree);
+    if (cached !== undefined)
+        return cached;
+    const context = collectContextFromTree(tree);
+    state.contexts.set(tree, context);
+    return context;
+}
 const OTHER_SPECIFIERS = [
     MdxImportSpecifier.ImportDefaultSpecifier,
     MdxImportSpecifier.ImportNamespaceSpecifier,
@@ -29,29 +50,121 @@ const OTHER_SPECIFIERS = [
  * @param importSpecifier The name of the imported component we want to replace
  * @param destinationPageContent The content of the page we want to inject the import into
  * @param importedFileContent The content of the file we are importing from
+ * @param state Shared by every import of one page, so readers of a snippet binding share one value
  * @returns
  */
-export const resolveImport = (importSpecifier, destinationPageContent, importedFileContent, exportMap, onWarning) => __awaiter(void 0, void 0, void 0, function* () {
-    var _a, _b;
+export const resolveImport = (importSpecifier_1, destinationPageContent_1, importedFileContent_1, exportMap_1, onWarning_1, ...args_1) => __awaiter(void 0, [importSpecifier_1, destinationPageContent_1, importedFileContent_1, exportMap_1, onWarning_1, ...args_1], void 0, function* (importSpecifier, destinationPageContent, importedFileContent, exportMap, onWarning, state = createImportResolutionState()) {
+    var _a, _b, _c;
     if (VALID_SPECIFIERS.includes(importSpecifier.type)) {
         // normal import: import { Component } from '/snippets/Component.mdx' or jsx file
-        // find "Component" in "/snippets/Component.mdx" or jsx files
-        const exportContent = findExport(importSpecifier.name, importedFileContent, importSpecifier.renamedName);
-        if (exportContent == undefined)
-            throw new Error(`Could not find export ${importSpecifier.name} in snippet`);
-        // `import { X as Y }` binds Y; an existing declaration of that name wins
         const localName = (_a = importSpecifier.renamedName) !== null && _a !== void 0 ? _a : importSpecifier.name;
-        const existing = exportMap[localName];
-        if (existing !== undefined) {
-            warnOnExportCollision(localName, existing, exportContent, onWarning);
+        const destinationBindings = collectTopLevelBindingNames(destinationPageContent);
+        const destinationExports = collectExportedNames(destinationPageContent);
+        // An existing binding or export of the name wins; warn when its definition differs. MDX
+        // modules cannot declare unexported bindings, so a page export alias also keeps the name.
+        const keepExisting = (incoming) => {
+            var _a, _b;
+            const injected = exportMap[localName];
+            if (injected !== undefined) {
+                warnOnExportCollision(localName, injected, incoming, onWarning);
+                return true;
+            }
+            if (!destinationBindings.has(localName) && !destinationExports.has(localName))
+                return false;
+            warnOnExportCollision(localName, (_a = declarationSource(destinationPageContent, localName)) !== null && _a !== void 0 ? _a : '', (_b = declarationSource(getAST(incoming), localName)) !== null && _b !== void 0 ? _b : incoming, onWarning);
+            return true;
+        };
+        const binding = exportedBindingName(importedFileContent, importSpecifier.name);
+        const held = heldSnippetBindings(state, importedFileContent);
+        const holder = held.get(binding);
+        // A binding this page already declares, explicitly or as a private sibling, is aliased so
+        // every reader shares one value, as it would in a real module
+        if (holder !== undefined && holder !== localName) {
+            const statement = `export const ${localName} = ${holder};`;
+            if (keepExisting(statement))
+                return destinationPageContent;
+            injectBelowEagerDependencies(destinationPageContent, getAST(statement).children);
+            exportMap[localName] = statement;
+            return destinationPageContent;
+        }
+        const exportContent = findExport(importSpecifier.name, structuredClone(importedFileContent), importSpecifier.renamedName);
+        if (exportContent == undefined) {
+            const sourceScope = snippetContext(state, importedFileContent).moduleScope;
+            if (!collectExportedNames(importedFileContent).has(importSpecifier.name) ||
+                !sourceScope.has(binding)) {
+                throw new Error(`Could not find export ${importSpecifier.name} in snippet`);
+            }
+            const serialize = (name) => {
+                const stored = sourceScope.get(name);
+                return serializeStaticValue(stored === undefined ? undefined : stored);
+            };
+            const statement = `export const ${localName} = ${serialize(binding)};`;
+            if (keepExisting(statement))
+                return destinationPageContent;
+            // The other names a destructuring export binds are declared privately too, so a sibling
+            // that reads one later shares it instead of copying the whole pattern again
+            const siblings = [];
+            for (const [name, privateName] of patternSiblingNames(importedFileContent, binding)) {
+                if (held.has(name) || !sourceScope.has(name))
+                    continue;
+                const sibling = `export const ${privateName} = ${serialize(name)};`;
+                siblings.push(sibling);
+                (_b = exportMap[privateName]) !== null && _b !== void 0 ? _b : (exportMap[privateName] = sibling);
+                held.set(name, privateName);
+            }
+            injectToTopOfFileOfTree(destinationPageContent, getAST([...siblings, statement].join('\n')).children);
+            exportMap[localName] = statement;
+            held.set(binding, localName);
             return destinationPageContent;
         }
-        // Inject "export const Component = `...`" into the top of the destination page and record
-        // every name it declares so a later import or inlined snippet dedupes against it
-        const injected = getAST(exportContent);
-        injectToTopOfFileOfTree(destinationPageContent, injected.children);
-        for (const [declared, statement] of Object.entries(getExportMapFromTree(injected))) {
-            (_b = exportMap[declared]) !== null && _b !== void 0 ? _b : (exportMap[declared] = statement);
+        if (keepExisting(exportContent))
+            return destinationPageContent;
+        const statementTree = getAST(exportContent);
+        // A grouped statement is injected whole unless another of its names is already taken.
+        // `findExport` keeps the binding's original name when renaming it is unsafe, so the local name
+        // is then declared as an alias and no other declarator may take it.
+        const exportedNames = collectTopLevelBindingNames(statementTree);
+        const exportedDeclarator = exportedNames.has(binding) ? binding : localName;
+        const localAlias = exportedDeclarator === localName
+            ? []
+            : getAST(`export const ${localName} = ${exportedDeclarator};`).children;
+        const redeclaresDestination = [...exportedNames].some((declared) => declared !== exportedDeclarator &&
+            (declared === localName ||
+                held.has(declared) ||
+                destinationBindings.has(declared) ||
+                destinationExports.has(declared)));
+        const isolated = redeclaresDestination
+            ? isolateExportedDeclarator(statementTree, exportedDeclarator)
+            : statementTree;
+        const { siblings, statement, trailing, privateNames } = prepareSnippetSiblings(destinationPageContent, importedFileContent, isolated, { name: importSpecifier.name, localName }, held);
+        const injected = {
+            type: 'root',
+            children: [...siblings, ...statement.children, ...localAlias, ...trailing],
+        };
+        injectBelowEagerDependencies(destinationPageContent, injected.children);
+        // `findExport` keeps the original name when renaming the declaration is unsafe. The binding's
+        // own name is checked first, since a grouped statement can also declare a different
+        // declarator under the local name.
+        const statementNames = collectTopLevelBindingNames(statement);
+        if (statementNames.has(binding))
+            held.set(binding, binding);
+        else if (statementNames.has(localName))
+            held.set(binding, localName);
+        // A grouped statement declares its other snippet bindings on the page under their own names
+        const snippetBindings = collectTopLevelBindingNames(importedFileContent);
+        for (const declared of statementNames) {
+            if (declared !== localName && snippetBindings.has(declared) && !held.has(declared)) {
+                held.set(declared, declared);
+            }
+        }
+        for (const [original, privateName] of privateNames) {
+            if (!held.has(original))
+                held.set(original, privateName);
+        }
+        // Record every exported name, private siblings included, so a later import or inlined
+        // snippet dedupes against it
+        for (const [declared, source] of Object.entries(getExportMapFromTree(injected))) {
+            (_c = exportMap[declared]) !== null && _c !== void 0 ? _c : (exportMap[declared] = source);
         }
         return destinationPageContent;
     }

package/dist/mdx/snippets/resolveImport/resolveComponentWithContent.js

@@ -15,8 +15,8 @@ import { JSXParser } from '../../lib/jsxParser.js';
 import { getAST } from '../../remark.js';
 import { createUniqueVariableName, isMdxJsxFlowElement } from '../../utils.js';
 import { findAndRemoveExports } from '../findAndRemoveExports.js';
-import { warnOnExportCollision } from './exportCollision.js';
-import { injectToTopOfFileOfTree } from './injectToTopOfFile.js';
+import { isSameStatement, warnOnExportCollision, } from './exportCollision.js';
+import { injectBelowEagerDependencies, isPrivateSiblingName, pruneDeclaredNames, statementSourceNames, takePrivateDeclarations, } from './snippetDeclarations.js';
 /**
  *
  * @param tree The tree to inject into
@@ -274,19 +274,52 @@ const replaceCodePlaceholdersWithProps = (tree, propValues) => {
     });
 };
 const reinsertExports = (content, exportMap, snippetExportMap, onWarning) => {
+    var _a;
     const nodesToInject = [];
+    const injectedStatements = new Set();
     for (const [key, value] of Object.entries(snippetExportMap)) {
         const existing = exportMap[key];
+        // An alias maps to its local's declaration, which does not declare the alias itself. The
+        // declaration is still inserted when nothing else supplies it, but the alias is not claimed.
+        const declaresKey = key === 'default' || statementSourceNames(value).has(key);
+        if (existing == undefined && !declaresKey) {
+            const declared = [...statementSourceNames(value)];
+            const unsupplied = declared.every((name) => exportMap[name] === undefined && snippetExportMap[name] === undefined);
+            if (unsupplied && !injectedStatements.has(value)) {
+                nodesToInject.push(...getAST(value).children);
+                injectedStatements.add(value);
+                for (const name of declared)
+                    exportMap[name] = value;
+            }
+            continue;
+        }
         if (existing == undefined) {
-            const exportAST = getAST(value);
-            nodesToInject.push(...exportAST.children);
+            // A destructured export maps each of its names to the same statement: insert it once, and
+            // without the names the page already declares
+            const taken = new Set([...statementSourceNames(value)].filter((name) => name !== key && exportMap[name] !== undefined && exportMap[name] !== value));
+            const statement = taken.size === 0
+                ? value
+                : pruneDeclaredNames(value, taken, (name) => exportMap[name] !== undefined);
+            if (statement === undefined) {
+                for (const name of taken)
+                    warnOnExportCollision(name, (_a = exportMap[name]) !== null && _a !== void 0 ? _a : '', value, onWarning);
+                continue;
+            }
+            if (!injectedStatements.has(statement))
+                nodesToInject.push(...getAST(statement).children);
+            injectedStatements.add(statement);
             exportMap[key] = value;
         }
+        else if (isPrivateSiblingName(key) && isSameStatement(existing, value)) {
+            // The same snippet helper, already injected: move it up so this snippet's code reads it
+            // after it is declared. Different code under a reserved name falls through to a warning.
+            nodesToInject.push(...takePrivateDeclarations(content, [key]));
+        }
         else {
             warnOnExportCollision(key, existing, value, onWarning);
         }
     }
     if (nodesToInject.length > 0) {
-        injectToTopOfFileOfTree(content, nodesToInject);
+        injectBelowEagerDependencies(content, nodesToInject);
     }
 };

package/dist/mdx/snippets/resolveImport/snippetDeclarations.d.ts

@@ -0,0 +1,56 @@
+import type { Root, RootContent } from 'mdast';
+export declare function isolateExportedDeclarator(tree: Root, name: string): Root;
+/** Names a module makes importable: named export declarations, specifiers, and default. */
+export declare function collectExportedNames(tree: Root): Set<string>;
+/** Every top-level lexical binding in the tree's ESM statements, exported or not. */
+export declare function collectTopLevelBindingNames(tree: Root): Set<string>;
+/** The local binding behind an export name, following `export { local as name }`. */
+export declare function exportedBindingName(tree: Root, exportName: string): string;
+/** Source of the top-level declaration that binds `name`, without any `export` keyword. */
+export declare function declarationSource(tree: Root, name: string): string | undefined;
+/** Names an export statement's source declares, destructured patterns included. */
+export declare function statementSourceNames(source: string): Set<string>;
+/**
+ * Rewrites a single variable export so it no longer declares the names in `drop`. A declarator
+ * that only binds dropped names and that no kept declarator reads is removed, so its initializer
+ * never runs. Any other dropped name is renamed to a private name throughout the statement, so
+ * rest elements still receive the same keys and kept declarators still read the snippet's values.
+ */
+export declare function pruneDeclaredNames(source: string, drop: ReadonlySet<string>, isNameTaken?: (name: string) => boolean): string | undefined;
+export declare function isPrivateSiblingName(name: string): boolean;
+/**
+ * Removes the private sibling declarations for `names` from the tree, with the private siblings
+ * they reference, and returns them dependencies first so they can be re-inserted above new readers.
+ */
+export declare function takePrivateDeclarations(tree: Root, names: Iterable<string>): RootContent[];
+/**
+ * Injects each node as high as it can go: at the top of the page, or just below the last
+ * declaration it reads while initializing, such as a reused helper that could not move above a
+ * page binding. Placing nodes one at a time keeps helpers that need no such dependency at the top,
+ * above any existing code that reads them.
+ */
+export declare function injectBelowEagerDependencies(tree: Root, nodes: RootContent[]): void;
+export type SnippetInjection = {
+    /** Declared above the imported statement. */
+    siblings: RootContent[];
+    statement: Root;
+    /** Declared below the imported statement, because they read it while initializing. */
+    trailing: RootContent[];
+    /** The final name of each snippet binding that is now declared privately on the page. */
+    privateNames: Map<string, string>;
+};
+/**
+ * Collects the snippet declarations the injected statement transitively references. They stay
+ * private to the import, as in a real module: each gets a reserved name derived from its snippet,
+ * and dependencies are declared first. A sibling an earlier import already injected is reused and
+ * moved up with its own dependencies, so it stays above every reader.
+ */
+/**
+ * The private names that the other bindings of `binding`'s declarator take on a page, such as
+ * `other` for `export const [binding, other] = …`.
+ */
+export declare function patternSiblingNames(imported: Root, binding: string): Map<string, string>;
+export declare function prepareSnippetSiblings(destination: Root, imported: Root, statement: Root, requested: {
+    name: string;
+    localName: string;
+}, heldBindings?: ReadonlyMap<string, string>): SnippetInjection;