@thallylabs/migrate 0.2.19 → 0.2.22

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/repository.ts
 import { compileSync as compileSync2 } from "@mdx-js/mdx";
+import { createHash as createHash2 } from "crypto";
 import { spawn } from "child_process";
 import {
   closeSync,
@@ -16,7 +17,7 @@ import {
 import { createRequire } from "module";
 import { basename as basename3, dirname as dirname4, extname as extname6, isAbsolute as isAbsolute2, posix as posix3, relative as relative5, resolve as resolvePath, sep as sep2 } from "path";
 import { parse as parseYaml4 } from "yaml";
-import * as ts3 from "typescript";
+import * as ts4 from "typescript";
 
 // src/components.ts
 import { createHash } from "crypto";
@@ -263,7 +264,8 @@ function unwrapDocusaurusMdxCodeBlocks(body) {
   }
   return isMdxCodeBlock ? body : output.join("\n");
 }
-function normalizeExplicitHeadingIds(raw) {
+var HTML_ID = /^[^\s"'<>`{}&]+$/u;
+function normalizeExplicitHeadingIds(raw, warn) {
   const { front, body } = splitFrontmatterBlock(raw);
   return front + replaceOutsideCode(body, (segment) => segment.split("\n").map((line) => {
     if (!/^[ \t]{0,3}#{1,6}[ \t]+/.test(line)) return line;
@@ -272,10 +274,12 @@ function normalizeExplicitHeadingIds(raw) {
       const marker = trimmed.lastIndexOf(" {#");
       if (marker >= 0) {
         const id = trimmed.slice(marker + 3, -1);
-        if (/^[A-Za-z][A-Za-z0-9_-]*$/.test(id)) {
-          return `<a id="${id}"></a>
-${trimmed.slice(0, marker).trimEnd()}`;
-        }
+        const heading = trimmed.slice(0, marker).trimEnd();
+        if (/[{}]/.test(id)) return line;
+        if (HTML_ID.test(id)) return `<a id="${id}"></a>
+${heading}`;
+        warn?.(`Heading anchor {#${id}} is not a valid HTML id and was removed from "${heading.replace(/^\s*#+\s*/, "")}".`);
+        return heading;
       }
     }
     if (trimmed.endsWith("*/}")) {
@@ -283,7 +287,7 @@ ${trimmed.slice(0, marker).trimEnd()}`;
       if (marker >= 0) {
         const comment = trimmed.slice(marker + 4, -3).trim();
         const id = comment.startsWith("#") ? comment.slice(1) : "";
-        if (/^[A-Za-z][A-Za-z0-9_.:-]*$/.test(id)) {
+        if (HTML_ID.test(id)) {
           return `<a id="${id}"></a>
 ${trimmed.slice(0, marker).trimEnd()}`;
         }
@@ -425,6 +429,9 @@ function bracketDelta(line) {
   return delta;
 }
 var ESM_OPEN = /^(?:import|export)\b/;
+function latexElement(source, block = false) {
+  return `<Latex${block ? " block" : ""}>{${JSON.stringify(source)}}</Latex>`;
+}
 function protectMathBlocks(raw) {
   const { front, body } = splitFrontmatterBlock(raw);
   const lines = body.split(/\r\n|\r|\n/);
@@ -439,7 +446,7 @@ function protectMathBlocks(raw) {
     const trimmed = line.trim();
     if (mathBlockDelimiter) {
       if (trimmed === mathBlockDelimiter) {
-        output.push("```math", ...mathLines, "```");
+        output.push(latexElement(mathLines.join("\n"), true));
         mathBlockDelimiter = null;
         mathLines = [];
         converted = true;
@@ -481,11 +488,11 @@ function protectMathBlocks(raw) {
         (whole, block, inline) => {
           if (block !== void 0) {
             converted = true;
-            return `\`$$${block}$$\``;
+            return latexElement(unmask(block));
           }
           if (inline !== void 0 && hasTexSignal(unmask(inline))) {
             converted = true;
-            return `\`$${inline}$\``;
+            return latexElement(unmask(inline));
           }
           return whole;
         }
@@ -671,13 +678,25 @@ function maskCode(body) {
   if (fenceBuffer.length) lines.push(stash(fenceBuffer.join("\n")));
   return {
     masked: lines.join("\n"),
-    unmask: (text2) => text2.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)])
+    unmask: (text2) => text2.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)]),
+    openFence: codeFence
   };
 }
+function closeOpenFence(body) {
+  const { openFence } = maskCode(body);
+  return openFence ? `${body}${body.endsWith("\n") ? "" : "\n"}${openFence}
+` : body;
+}
 function replaceOutsideCode(body, transform) {
   const { masked, unmask } = maskCode(body);
   return unmask(transform(masked));
 }
+function mdxComment(text2) {
+  return `{/*${text2.replace(/\*\//g, "* /")}*/}`;
+}
+function replaceOutsideCodeAndComments(body, transform) {
+  return replaceOutsideCode(body, (masked) => masked.split(/(\{\s*\/\*[\s\S]*?\*\/\s*\})/).map((part, index) => index % 2 ? part : transform(part)).join(""));
+}
 function rewriteFernRelativePageLinks(body, currentSourcePath, routesBySourcePath) {
   const rewrite = (target) => {
     if (!target || target.startsWith("/") || target.startsWith("#") || target.startsWith("?") || target.includes("\\") || /[\u0000-\u001f\u007f]/.test(target) || /^[A-Za-z][A-Za-z\d+.-]*:/.test(target)) return target;
@@ -739,7 +758,7 @@ function normalizeFernFileTrees(body) {
   ));
 }
 function normalizeHtmlComments(body) {
-  return replaceOutsideCode(body, (whole) => whole.replace(/<!--([\s\S]*?)-->/g, (_match, comment) => `{/*${comment}*/}`));
+  return replaceOutsideCode(body, (whole) => whole.replace(/<!--([\s\S]*?)-->/g, (_match, comment) => mdxComment(comment)));
 }
 function normalizeFernCallouts(body) {
   return replaceOutsideCode(body, (whole) => {
@@ -1207,6 +1226,32 @@ function injectReactHookImports(body) {
 
 ${body}` : body;
 }
+function normalizeFlowParagraphContainers(body) {
+  if (!body.includes("<p")) return body;
+  let tree;
+  try {
+    tree = descriptionParser.parse(body);
+  } catch {
+    return body;
+  }
+  const edits = [];
+  function visit(node) {
+    if (node.type === "mdxJsxFlowElement" && node.name === "p" && node.children?.some((child) => child.type === "paragraph" || child.type === "list" || child.type === "mdxJsxFlowElement")) {
+      const start = node.position?.start.offset;
+      const end = node.position?.end.offset;
+      if (start !== void 0 && end !== void 0 && body.slice(start, start + 2) === "<p") {
+        const closing = body.slice(start, end).match(/<\/p\s*>\s*$/i);
+        if (closing?.index !== void 0) {
+          edits.push({ offset: start + 1, value: "div" });
+          edits.push({ offset: start + closing.index + 2, value: "div" });
+        }
+      }
+    }
+    for (const child of node.children ?? []) visit(child);
+  }
+  visit(tree);
+  return edits.sort((a, b) => b.offset - a.offset).reduce((text2, edit) => text2.slice(0, edit.offset) + edit.value + text2.slice(edit.offset + 1), body);
+}
 function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   const runFern = platform === "fern";
   const runMintlify = platform === "mintlify";
@@ -1218,6 +1263,13 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
       /:([+\w-]+):/g,
       (shortcode, name) => nameToEmoji[name] ?? shortcode
     ));
+    rewritten = replaceOutsideCode(rewritten, (segment) => segment.replace(
+      /\b(href|src)=\{\s*require\(\s*(['"])@docusaurus\/useBaseUrl\2\s*\)\.default\(\s*(['"])([^'"]+)\3\s*\)\s*\}/g,
+      (original, attribute, _moduleQuote, _pathQuote, path) => {
+        if (!/^[\w./~%-]+$/.test(path) || path.split("/").includes("..")) return original;
+        return `${attribute}="/${path.replace(/^\.\//, "").replace(/^\/+/, "")}"`;
+      }
+    ));
     rewritten = normalizeDocusaurusTabBlocks(normalizeDocusaurusTabs(removeGlobalDocusaurusImports(rewritten)));
     rewritten = replaceOutsideCode(rewritten, (segment) => segment.replace(
       /\bimport\s+([A-Za-z_$][\w$]*)\s+from\s+(['"])(@site\/[^'"]+)\2\s*;?/g,
@@ -1230,7 +1282,7 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   }
   if (runMintlify) rewritten = normalizeMintlifyParameterAnchors(rewritten);
   rewritten = replaceOutsideCode(rewritten, (segment) => {
-    let result = convertHtmlStyleAttributes(segment).replace(/<!--([\s\S]*?)-->/g, (_match, content) => `{/*${content}*/}`).replace(/<Danger(\s[^>]*)?>/g, "<Error$1>").replace(/<\/Danger>/g, "</Error>").replace(/<Warn(\s[^>]*)?>/g, "<Warning$1>").replace(/<\/Warn>/g, "</Warning>").replace(/<Check(\s[^>]*)?>/g, "<Note$1>").replace(/<\/Check>/g, "</Note>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
+    let result = convertHtmlStyleAttributes(segment).replace(/<!--([\s\S]*?)-->/g, (_match, content) => mdxComment(content)).replace(/<Danger(\s[^>]*)?>/g, "<Error$1>").replace(/<\/Danger>/g, "</Error>").replace(/<Warn(\s[^>]*)?>/g, "<Warning$1>").replace(/<\/Warn>/g, "</Warning>").replace(/<Check(\s[^>]*)?>/g, "<Note$1>").replace(/<\/Check>/g, "</Note>").replace(/<Tree\.Folder/g, "<Folder").replace(/<\/Tree\.Folder>/g, "</Folder>").replace(/<Tree\.File/g, "<File").replace(/<\/Tree\.File>/g, "</File>");
     if (runDocusaurus) {
       result = result.replace(/<TabItem\b([^>]*)>/g, (_match, attributes) => {
         const title = attributes.match(/\blabel=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean) ?? attributes.match(/\bvalue=(?:"([^"]*)"|'([^']*)')/)?.slice(1).find(Boolean) ?? "Tab";
@@ -1254,7 +1306,7 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
       return normalizeMdx(body, platform, false);
     }
   }
-  return normalized;
+  return normalizeFlowParagraphContainers(normalized);
 }
 function parseMarkdownPage(input) {
   const parsed = parseFrontmatter(input.raw);
@@ -2190,26 +2242,33 @@ function hash(value) {
 function portableSpecifier(path) {
   return path.replace(/\.tsx?$/, "");
 }
-function wrapImpureCssModuleSelectors(css) {
+function sanitizeCssModuleSelectors(css) {
   const root = postcss.parse(css);
+  let omitted = 0;
   root.walkRules((rule) => {
-    rule.selector = selectorParser((selectors) => {
-      selectors.each((selector) => {
-        let hasClassOrId = false;
-        selector.walk((node) => {
-          if (node.type === "class" || node.type === "id") hasClassOrId = true;
-        });
-        if (hasClassOrId) return;
-        const nodes = selector.nodes.splice(0, selector.nodes.length);
-        const container = selectorParser.selector({ value: "" });
-        for (const node of nodes) container.append(node);
-        const globalPseudo = selectorParser.pseudo({ value: ":global" });
-        globalPseudo.append(container);
-        selector.append(globalPseudo);
+    if (rule.parent?.type === "atrule" && /keyframes$/i.test(rule.parent.name)) return;
+    if (/^:export$|^:import\(/.test(rule.selector.trim())) return;
+    const selectors = selectorParser().astSync(rule.selector);
+    selectors.each((selector) => {
+      let hasLocalClassOrId = false;
+      selector.walk((node) => {
+        if (node.type !== "class" && node.type !== "id") return;
+        let parent = node.parent;
+        while (parent) {
+          if (parent.type === "pseudo" && parent.value === ":global") return;
+          parent = parent.parent;
+        }
+        hasLocalClassOrId = true;
       });
-    }).processSync(rule.selector);
+      if (!hasLocalClassOrId) {
+        selector.remove();
+        omitted++;
+      }
+    });
+    if (selectors.nodes.length === 0) rule.remove();
+    else rule.selector = selectors.toString();
   });
-  return root.toString();
+  return { css: root.toString(), omitted };
 }
 function sourceFile(source, filename) {
   return ts2.createSourceFile(
@@ -2380,7 +2439,8 @@ function neutralizeUnresolvableImportsWithoutAst(content, currentFile, warn) {
   });
   for (const { name, specifier } of dropped) {
     warn(`Component import ${JSON.stringify(specifier)} could not be resolved because this page has invalid MDX (see the previous warning), so the import and its usage were removed to keep the site building.`, currentFile);
-    result = result.replace(new RegExp(`<${name}(?:\\s[^>]*)?/>`, "g"), `{/* Removed <${name}>: unresolved during fallback migration */}`).replace(new RegExp(`<${name}(?:\\s[^>]*)?>[\\s\\S]*?<\\/${name}>`, "g"), `{/* Removed <${name}>: unresolved during fallback migration */}`);
+    const removed = mdxComment(` Removed <${name}>: unresolved during fallback migration `);
+    result = replaceOutsideCodeAndComments(result, (segment) => segment.replace(new RegExp(`<${name}(?:\\s[^>]*)?/>`, "g"), removed).replace(new RegExp(`<${name}(?:\\s[^>]*)?>[\\s\\S]*?<\\/${name}>`, "g"), removed));
   }
   return result;
 }
@@ -2439,6 +2499,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
   }
   function copyGraph(entry) {
     const staged = /* @__PURE__ */ new Map();
+    const stagedWarnings = [];
     let stagedBytes = 0;
     function stageShim(filename, content) {
       const shimDestination = `${destinationRoot}/shims/${filename}`;
@@ -2459,13 +2520,14 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
       if (!CODE_EXTENSIONS.has(extension)) {
         if (extension === ".css" && /@import\b|url\s*\(/i.test(content.toString("utf8"))) throw new Error("CSS resource dependencies require manual migration");
         if (extension === ".css" && path.toLowerCase().endsWith(".module.css")) {
-          let wrapped;
+          let sanitized;
           try {
-            wrapped = wrapImpureCssModuleSelectors(content.toString("utf8"));
+            sanitized = sanitizeCssModuleSelectors(content.toString("utf8"));
           } catch {
             throw new Error("CSS module could not be parsed to check for Turbopack-safe selectors");
           }
-          staged.set(destination, { path: destination, content: wrapped });
+          if (sanitized.omitted > 0) stagedWarnings.push({ path, omitted: sanitized.omitted });
+          staged.set(destination, { path: destination, content: sanitized.css });
         }
         return;
       }
@@ -2534,6 +2596,9 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
     }
     visit(entry);
     for (const [path, file] of staged) copied.set(path, file);
+    for (const { path, omitted } of stagedWarnings) {
+      warn(`Site-authored CSS module ${relative2(root, path).replace(/\\/g, "/")} has ${omitted} global-only selector branch(es) that cannot be copied into Thally CSS Modules; those styles were omitted.`, path);
+    }
     copiedBytes += stagedBytes;
     return outputPath(entry);
   }
@@ -2787,7 +2852,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
             warn(`Asset import ${JSON.stringify(rawSpecifier)} could not be copied as a component; it was copied to ${rescuedAssetHref} and bound to that URL instead.`, currentFile);
           } else {
             edits.push({ start: importStart, end: importEnd, value: "" });
-            warn(`Component import ${JSON.stringify(rawSpecifier)} could not be copied and was removed: ${error instanceof Error ? error.message : "unsupported dependency"}. Its usage on this page was neutralized.`, currentFile);
+            warn(`Site-authored component import ${JSON.stringify(rawSpecifier)} could not be copied and was removed: ${error instanceof Error ? error.message : "unsupported dependency"}. Its usage on this page was neutralized; review this custom implementation manually.`, currentFile);
           }
         }
       }
@@ -3043,7 +3108,7 @@ ${inlineSource}` });
       const start = node.position.start.offset;
       const end = node.position.end.offset;
       const videoId = youtubeEmbedVideoId(node, specifier);
-      const value = videoId ? `<iframe width="560" height="315" src="https://www.youtube.com/embed/${videoId}" title="Embedded video" allowFullScreen />` : `{/* Removed <${node.name}>: unsupported import '${specifier}' */}`;
+      const value = videoId ? `<iframe width="560" height="315" src="https://www.youtube.com/embed/${videoId}" title="Embedded video" allowFullScreen />` : mdxComment(` Removed <${node.name}>: unsupported import '${specifier}' `);
       edits.push({ start, end, value });
     });
     const rendered = applyReplacements(content, edits);
@@ -3117,6 +3182,110 @@ import { customComponents as ${name} } from ${JSON.stringify(registryPath)}
   ];
 }
 
+// src/source-styles.ts
+import postcss2 from "postcss";
+import selectorParser2 from "postcss-selector-parser";
+import ts3 from "typescript";
+var PLATFORM_CLASSES = /* @__PURE__ */ new Set(["navbar-link"]);
+var PLATFORM_IDS = /* @__PURE__ */ new Set(["footer", "navbar", "sidebar"]);
+var PLATFORM_CLASS_PREFIX = /^(?:mintlify[-_]|fern[-_]|docusaurus[-_]|theme-doc-|theme-code-block|DocSearch|pagination-nav|menu__)/i;
+var SHARED_THEME_CLASSES = /* @__PURE__ */ new Set(["dark", "light"]);
+var UTILITY_CLASS = /^(?:[mp][trblxy]?|w|h|min-w|max-w|min-h|max-h|text|bg|border|rounded|flex|grid|gap|space-[xy]|items|justify|overflow|truncate|hidden|block|inline|relative|absolute|sticky|z|opacity)-/;
+function withoutFencedCode(content) {
+  let fence;
+  return content.split("\n").map((line) => {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/)?.[1];
+    if (fence) {
+      if (marker?.[0] === fence.marker && marker.length >= fence.length) fence = void 0;
+      return "";
+    }
+    if (marker) {
+      fence = { marker: marker[0], length: marker.length };
+      return "";
+    }
+    return line;
+  }).join("\n");
+}
+function authoredStyleNames(contents) {
+  const classes = /* @__PURE__ */ new Set();
+  const ids = /* @__PURE__ */ new Set();
+  for (const original of contents) {
+    const content = withoutFencedCode(original);
+    for (const match of content.matchAll(/\b(?:className|class)\s*=\s*["']([^"']+)["']/g)) {
+      for (const name of match[1].split(/\s+/)) if (name) classes.add(name);
+    }
+    for (const match of content.matchAll(/\bid\s*=\s*["']([^"']+)["']/g)) ids.add(match[1]);
+    if (!content.includes("className={")) continue;
+    const source = ts3.createSourceFile("component.tsx", content, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
+    const visit = (node) => {
+      if (ts3.isJsxAttribute(node) && ts3.isIdentifier(node.name) && node.name.text === "className" && node.initializer) {
+        const collect = (value) => {
+          if (ts3.isStringLiteral(value) || ts3.isNoSubstitutionTemplateLiteral(value)) {
+            for (const name of value.text.split(/\s+/)) if (name) classes.add(name);
+          } else ts3.forEachChild(value, collect);
+        };
+        collect(node.initializer);
+      }
+      ts3.forEachChild(node, visit);
+    };
+    visit(source);
+  }
+  return { classes, ids };
+}
+function projectAuthoredStyles(css, contents) {
+  const names = authoredStyleNames(contents);
+  const root = postcss2.parse(css);
+  let omittedSelectors = 0;
+  let rewrittenSelectors = 0;
+  root.walkRules((rule) => {
+    if (rule.parent?.type === "atrule" && /keyframes$/i.test(rule.parent.name)) return;
+    const retained = [];
+    try {
+      selectorParser2((selectors) => {
+        selectors.each((selector) => {
+          let hasAuthoredAnchor = false;
+          let hasPlatformAnchor = false;
+          selector.walk((node) => {
+            let ancestor = node.parent;
+            let isNestedInPseudo = false;
+            while (ancestor && ancestor !== selector) {
+              if (ancestor.type === "pseudo") isNestedInPseudo = true;
+              ancestor = ancestor.parent;
+            }
+            if (node.type === "class") {
+              if (SHARED_THEME_CLASSES.has(node.value)) return;
+              if (PLATFORM_CLASSES.has(node.value) || PLATFORM_CLASS_PREFIX.test(node.value) || UTILITY_CLASS.test(node.value) || !names.classes.has(node.value)) hasPlatformAnchor = true;
+              else if (!isNestedInPseudo) hasAuthoredAnchor = true;
+            } else if (node.type === "id") {
+              if (PLATFORM_IDS.has(node.value) || !names.ids.has(node.value)) hasPlatformAnchor = true;
+              else if (!isNestedInPseudo) hasAuthoredAnchor = true;
+            } else if (node.type === "attribute" && node.attribute === "data-as") {
+              node.remove();
+              rewrittenSelectors += 1;
+            }
+          });
+          if (hasAuthoredAnchor && !hasPlatformAnchor) retained.push(selector.toString());
+          else omittedSelectors += 1;
+        });
+      }).processSync(rule.selector);
+    } catch {
+      omittedSelectors += 1;
+    }
+    if (retained.length) rule.selector = retained.join(", ");
+    else rule.remove();
+  });
+  const hasStyleRule = (nodes) => Boolean(nodes?.some((node) => node.type === "rule" || node.type === "atrule" && hasStyleRule(node.nodes)));
+  root.walkAtRules((rule) => {
+    if (rule.name === "font-face" || rule.name === "property") return;
+    if (!hasStyleRule(rule.nodes)) rule.remove();
+  });
+  if (omittedSelectors === 0 && rewrittenSelectors === 0) return { css, omittedSelectors };
+  root.walkComments((comment) => {
+    comment.remove();
+  });
+  return { css: root.toString(), omittedSelectors };
+}
+
 // src/docusaurus.ts
 import { existsSync as existsSync3, lstatSync as lstatSync3, readFileSync as readFileSync3 } from "fs";
 import { extname as extname4, posix as posix2 } from "path";
@@ -4115,6 +4284,47 @@ function projectMintlifyNavigation(config, options = {}) {
       message: "Mintlify navigation could not be projected; generated navigation will be used."
     });
   }
+  const versionOwner = languages.length > 0 ? languages.find((entry) => entry.default === true) ?? languages[0] : navigation;
+  const globalNavigation = objectValue2(versionOwner.global) ?? objectValue2(navigation.global);
+  const shortcuts = Array.isArray(globalNavigation?.anchors) ? globalNavigation.anchors.flatMap((value) => {
+    const anchor = objectValue2(value);
+    const label = typeof anchor?.anchor === "string" ? anchor.anchor.trim() : "";
+    const href = projectedHref(anchor?.href);
+    if (!label || !href) return [];
+    return [{ label, href, ...iconName(anchor?.icon) ? { icon: iconName(anchor?.icon) } : {} }];
+  }) : [];
+  const rawVersions = Array.isArray(versionOwner.versions) ? versionOwner.versions.map(objectValue2).filter((value) => value !== null).sort((left, right) => Number(right.default === true) - Number(left.default === true)) : [];
+  const versionNames = rawVersions.map((entry) => typeof entry.version === "string" ? entry.version.trim() : "").filter(Boolean);
+  const annotateVersions = (items) => items.map((item) => {
+    const version = versionNames.find((name) => item.tab.startsWith(`${name}: `));
+    return version ? { ...item, version, displayLabel: item.tab.slice(version.length + 2) } : item;
+  });
+  const firstPage = (item) => {
+    const visit = (entries) => {
+      for (const entry of entries) {
+        if (typeof entry === "string") return entry;
+        const nested = visit(entry.pages);
+        if (nested) return nested;
+      }
+      return void 0;
+    };
+    return visit([...item.pages ?? [], ...item.groups ?? []]);
+  };
+  const defaultVersion = rawVersions.find((entry) => entry.default === true) ?? rawVersions[0];
+  const versions = rawVersions.length > 1 ? rawVersions.flatMap((entry) => {
+    const label = typeof entry.version === "string" ? entry.version.trim() : "";
+    if (!label) return [];
+    const candidates = tabs.filter((item) => item.tab.startsWith(`${label}: `)).map(firstPage).filter((page) => Boolean(page));
+    const landing = candidates.find((page) => page.startsWith(`${label}/`)) ?? candidates[0];
+    if (!landing) return [];
+    const firstSegment = landing.split("/")[0];
+    const prefix = firstSegment === label ? label : "";
+    return [{ label, prefix, href: `/${landing}`, ...entry === defaultVersion ? { default: true } : {} }];
+  }) : [];
+  if (versions.length > 1) {
+    tabs = annotateVersions(tabs);
+    for (const [locale, items] of Object.entries(localizedNavigation)) localizedNavigation[locale] = annotateVersions(items);
+  }
   const redirects = Array.isArray(config.redirects) ? config.redirects.flatMap((value) => {
     const redirect = objectValue2(value);
     if (!redirect || typeof redirect.source !== "string" || typeof redirect.destination !== "string") return [];
@@ -4139,7 +4349,11 @@ function projectMintlifyNavigation(config, options = {}) {
   return {
     docsConfig: {
       tabs,
-      ...projectionTrace.rootContainerKind === "dropdowns" ? { navigation: { display: "dropdown" } } : {},
+      ...projectionTrace.rootContainerKind === "dropdowns" || versions.length > 1 || shortcuts.length > 0 ? { navigation: {
+        ...projectionTrace.rootContainerKind === "dropdowns" ? { display: "dropdown" } : {},
+        ...versions.length > 1 ? { versions } : {},
+        ...shortcuts.length > 0 ? { shortcuts } : {}
+      } } : {},
       ...projectedCompatibleConfig(config, warnings),
       ...projectedApiMdx(config, warnings),
       ...i18n ? { i18n } : {},
@@ -4816,9 +5030,10 @@ function descriptorSort(left, right) {
   if (leftPosition !== rightPosition) return leftPosition - rightPosition;
   return left.sourcePath.localeCompare(right.sourcePath, void 0, { numeric: true });
 }
-function registerDoc(docId, context) {
+function registerDoc(docId, context, sourceDirectory) {
   const key = normalizeDocId(docId);
-  const descriptor = context.descriptorByDocId.get(key) ?? context.descriptors.find((page) => page.navigationId === docusaurusRouteId(key));
+  const scopedKey = sourceDirectory && !docId.startsWith("/") ? normalizeDocId(posix2.join(sourceDirectory, key)) : void 0;
+  const descriptor = (scopedKey ? context.descriptorByDocId.get(scopedKey) : void 0) ?? context.descriptorByDocId.get(key) ?? context.descriptors.find((page) => page.navigationId === docusaurusRouteId(key));
   if (!descriptor) {
     context.warnings.push({
       code: "missing-page",
@@ -4830,10 +5045,10 @@ function registerDoc(docId, context) {
   context.referencedNavigationIds.add(descriptor.navigationId);
   return descriptor.navigationId;
 }
-function generatedIndexPage(label, linkValue, context) {
+function generatedIndexPage(label, linkValue, context, sourceDirectory) {
   const link = objectValue3(linkValue);
   if (!link) return null;
-  if (link.type === "doc" && typeof link.id === "string") return registerDoc(link.id, context);
+  if (link.type === "doc" && typeof link.id === "string") return registerDoc(link.id, context, sourceDirectory);
   if (link.type !== "generated-index") return null;
   const fallback = `category/${slugifySegment(label)}`;
   const unprefixedNavigationId = typeof link.slug === "string" ? routeFromSlug(link.slug, fallback) ?? fallback : fallback;
@@ -5076,7 +5291,7 @@ function autogeneratedItems(dirName, context) {
         };
       }
     }
-    const landing = generatedIndexPage(metadata.label ?? titleCase2(segment), metadata.link, context);
+    const landing = generatedIndexPage(metadata.label ?? titleCase2(segment), metadata.link, context, directory);
     if (landing && !pages2.includes(landing)) pages2.unshift(landing);
     return {
       position: metadata.position ?? Number.MAX_SAFE_INTEGER,
@@ -5910,6 +6125,7 @@ var FRONTMATTER_HEAD_BYTES = 65536;
 var MAX_WITHHELD_SCAN_BYTES = MAX_PAGE_BYTES * 8;
 var MAX_DROPPED_GATED_WARNINGS = 20;
 var MAX_ASSET_BYTES = 25e6;
+var MAX_REFERENCED_ASSET_BYTES = 1e8;
 var MAX_TOTAL_ASSET_BYTES = 5e8;
 var GIT_LFS_POINTER_PREFIX = "version https://git-lfs.github.com/spec/v1";
 function listAssetPaths(paths) {
@@ -6641,7 +6857,7 @@ function selectGroupWithinBudget(scanned, rank, warnings, allVersionPrefixes, la
   const dropped = ranked.slice(budget).map(({ file }) => file);
   if (warnings) {
     const droppedPages = label === "file" ? dropped.filter((file) => isDocumentationExtension(file.relativePath)) : dropped;
-    const noun = label === "file" ? "page" : "image or media file";
+    const noun = label === "file" ? "page" : label === "snippet" ? "snippet file" : "image or media file";
     const droppedVersions = /* @__PURE__ */ new Set();
     for (const file of dropped) {
       const firstSegment = file.relativePath.split("/", 1)[0];
@@ -6651,16 +6867,19 @@ function selectGroupWithinBudget(scanned, rank, warnings, allVersionPrefixes, la
     const rest = droppedPages.length - examples.length;
     warnings.push({
       code: "limit-reached",
-      message: `This repository has more than ${budget} ${label === "file" ? "files" : "assets"}, so only the first ${budget} (in navigation order, default version first) were migrated. ${droppedPages.length} ${noun}(s) were left out` + (examples.length > 0 ? `: ${examples.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}` : "") + (droppedVersions.size > 0 ? ` (versions: ${[...droppedVersions].slice(0, 5).join(", ")}${droppedVersions.size > 5 ? `, and ${droppedVersions.size - 5} more` : ""})` : "") + (label === "file" ? ". To include them, run the migration on a smaller part of the repository with --docs-dir." : ". Copy them into public/ manually if your pages use them.")
+      message: `This repository has more than ${budget} ${label === "file" ? "files" : label === "snippet" ? "snippets" : "assets"}, so only the first ${budget} (in navigation order, default version first) were migrated. ${droppedPages.length} ${noun}(s) were left out` + (examples.length > 0 ? `: ${examples.join(", ")}${rest > 0 ? `, and ${rest} more` : ""}` : "") + (droppedVersions.size > 0 ? ` (versions: ${[...droppedVersions].slice(0, 5).join(", ")}${droppedVersions.size > 5 ? `, and ${droppedVersions.size - 5} more` : ""})` : "") + (label === "asset" ? ". Copy them into public/ manually if your pages use them." : ". To include them, run the migration on a smaller part of the repository with --docs-dir.")
     });
   }
   return ranked.slice(0, budget).map(({ file }) => file);
 }
 function selectFilesWithinBudget(scanned, rank, warnings, allVersionPrefixes, budget = MAX_SOURCE_FILES) {
   const isAsset = (file) => ASSET_EXTENSIONS.has(extname6(file.relativePath).toLowerCase());
+  const isSnippet = (file) => file.relativePath.split("/").some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase()));
+  const snippetFiles = scanned.filter((file) => !isAsset(file) && isSnippet(file));
   const assetFiles = scanned.filter(isAsset);
-  const otherFiles = scanned.filter((file) => !isAsset(file));
+  const otherFiles = scanned.filter((file) => !isAsset(file) && !isSnippet(file));
   return [
+    ...selectGroupWithinBudget(snippetFiles, rank, warnings, allVersionPrefixes, "snippet", budget),
     ...selectGroupWithinBudget(otherFiles, rank, warnings, allVersionPrefixes, "file", budget),
     ...selectGroupWithinBudget(assetFiles, rank, warnings, allVersionPrefixes, "asset", budget)
   ];
@@ -7159,19 +7378,26 @@ function interpolateSnippet(snippet, attributes, children) {
     });
   }).join("\n");
 }
+function isolateFences(snippet, source, start, end) {
+  const fence = /^\s*(?:`{3,}|~{3,})/;
+  const lines = snippet.split("\n");
+  const before = source.slice(source.lastIndexOf("\n", start - 1) + 1, start);
+  const after = source.slice(end, source.indexOf("\n", end) < 0 ? void 0 : source.indexOf("\n", end));
+  return `${fence.test(lines[0]) && /\S/.test(before) ? "\n" : ""}${snippet}${fence.test(lines[lines.length - 1]) && /\S/.test(after) ? "\n" : ""}`;
+}
 function snippetComponentBody(source, componentName) {
-  const parsed = ts3.createSourceFile("snippet.tsx", source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
+  const parsed = ts4.createSourceFile("snippet.tsx", source, ts4.ScriptTarget.Latest, true, ts4.ScriptKind.TSX);
   for (const statement of parsed.statements) {
-    if (!ts3.isVariableStatement(statement)) continue;
+    if (!ts4.isVariableStatement(statement)) continue;
     for (const declaration of statement.declarationList.declarations) {
-      if (!ts3.isIdentifier(declaration.name) || declaration.name.text !== componentName) continue;
+      if (!ts4.isIdentifier(declaration.name) || declaration.name.text !== componentName) continue;
       const initializer = declaration.initializer;
-      if (!initializer || !ts3.isArrowFunction(initializer)) continue;
-      const returned = ts3.isBlock(initializer.body) ? initializer.body.statements.find(ts3.isReturnStatement)?.expression : initializer.body;
+      if (!initializer || !ts4.isArrowFunction(initializer)) continue;
+      const returned = ts4.isBlock(initializer.body) ? initializer.body.statements.find(ts4.isReturnStatement)?.expression : initializer.body;
       if (!returned) continue;
       let expression = returned;
-      while (ts3.isParenthesizedExpression(expression)) expression = expression.expression;
-      if (ts3.isJsxElement(expression) || ts3.isJsxSelfClosingElement(expression) || ts3.isJsxFragment(expression)) {
+      while (ts4.isParenthesizedExpression(expression)) expression = expression.expression;
+      if (ts4.isJsxElement(expression) || ts4.isJsxSelfClosingElement(expression) || ts4.isJsxFragment(expression)) {
         return expression.getText(parsed);
       }
     }
@@ -7179,31 +7405,31 @@ function snippetComponentBody(source, componentName) {
   return source;
 }
 function statefulSnippetDeclaration(source, componentName) {
-  const parsed = ts3.createSourceFile("snippet.tsx", source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
-  const isEsm = (statement2) => ts3.isImportDeclaration(statement2) || (ts3.isVariableStatement(statement2) || ts3.isFunctionDeclaration(statement2) || ts3.isClassDeclaration(statement2)) && !!ts3.getModifiers(statement2)?.some((modifier) => modifier.kind === ts3.SyntaxKind.ExportKeyword);
+  const parsed = ts4.createSourceFile("snippet.tsx", source, ts4.ScriptTarget.Latest, true, ts4.ScriptKind.TSX);
+  const isEsm = (statement2) => ts4.isImportDeclaration(statement2) || (ts4.isVariableStatement(statement2) || ts4.isFunctionDeclaration(statement2) || ts4.isClassDeclaration(statement2)) && !!ts4.getModifiers(statement2)?.some((modifier) => modifier.kind === ts4.SyntaxKind.ExportKeyword);
   if (parsed.statements.length === 0 || !parsed.statements.every(isEsm)) return null;
-  const statement = parsed.statements.find((candidate) => ts3.isVariableStatement(candidate) && candidate.declarationList.declarations.length === 1 && ts3.isIdentifier(candidate.declarationList.declarations[0].name) && candidate.declarationList.declarations[0].name.text === componentName);
-  if (!statement || !ts3.isVariableStatement(statement)) return null;
+  const statement = parsed.statements.find((candidate) => ts4.isVariableStatement(candidate) && candidate.declarationList.declarations.length === 1 && ts4.isIdentifier(candidate.declarationList.declarations[0].name) && candidate.declarationList.declarations[0].name.text === componentName);
+  if (!statement || !ts4.isVariableStatement(statement)) return null;
   const declaration = statement.declarationList.declarations[0];
-  if (!declaration.initializer || !ts3.isArrowFunction(declaration.initializer) || !ts3.isBlock(declaration.initializer.body)) return null;
+  if (!declaration.initializer || !ts4.isArrowFunction(declaration.initializer) || !ts4.isBlock(declaration.initializer.body)) return null;
   const body = declaration.initializer.body.statements;
-  if (body.length < 2 || !body.some(ts3.isReturnStatement)) return null;
+  if (body.length < 2 || !body.some(ts4.isReturnStatement)) return null;
   return source.trim();
 }
 function staticNamedSnippetValues(source) {
   const values = /* @__PURE__ */ new Map();
-  const parsed = ts3.createSourceFile("snippet.tsx", source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
+  const parsed = ts4.createSourceFile("snippet.tsx", source, ts4.ScriptTarget.Latest, true, ts4.ScriptKind.TSX);
   for (const statement of parsed.statements) {
-    if (!ts3.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts3.SyntaxKind.ExportKeyword)) continue;
+    if (!ts4.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts4.SyntaxKind.ExportKeyword)) continue;
     for (const declaration of statement.declarationList.declarations) {
-      if (!ts3.isIdentifier(declaration.name) || !declaration.initializer) continue;
+      if (!ts4.isIdentifier(declaration.name) || !declaration.initializer) continue;
       const expression = declaration.initializer;
-      if (ts3.isStringLiteral(expression) || ts3.isNoSubstitutionTemplateLiteral(expression)) {
+      if (ts4.isStringLiteral(expression) || ts4.isNoSubstitutionTemplateLiteral(expression)) {
         values.set(declaration.name.text, JSON.stringify(expression.text));
-      } else if (ts3.isNumericLiteral(expression)) {
+      } else if (ts4.isNumericLiteral(expression)) {
         values.set(declaration.name.text, expression.text);
-      } else if (expression.kind === ts3.SyntaxKind.TrueKeyword || expression.kind === ts3.SyntaxKind.FalseKeyword) {
-        values.set(declaration.name.text, expression.kind === ts3.SyntaxKind.TrueKeyword ? "true" : "false");
+      } else if (expression.kind === ts4.SyntaxKind.TrueKeyword || expression.kind === ts4.SyntaxKind.FalseKeyword) {
+        values.set(declaration.name.text, expression.kind === ts4.SyntaxKind.TrueKeyword ? "true" : "false");
       }
     }
   }
@@ -7530,6 +7756,19 @@ function rewriteRepositoryAssetLinks(body, currentFile, siteRoot, onReferenced)
   });
 }
 var LOCAL_EXPORT_DECLARATION = /^\s*export\s+(?:const|let|var|function|class|async\s+function)\s+([A-Za-z_$][\w$]*)/;
+function replaceOutsideMdxComments(body, transform) {
+  const comment = /\{\/\*[\s\S]*?\*\/\}/g;
+  let cursor = 0;
+  let output = "";
+  for (const match of body.matchAll(comment)) {
+    output += transform(body.slice(cursor, match.index)) + match[0];
+    cursor = match.index + match[0].length;
+  }
+  return output + transform(body.slice(cursor));
+}
+function replaceOutsideCodeAndMdxComments(body, transform) {
+  return replaceOutsideCode(body, (segment) => replaceOutsideMdxComments(segment, transform));
+}
 function locallyDeclaredNames(raw) {
   const names = /* @__PURE__ */ new Set();
   let codeFence = null;
@@ -7575,7 +7814,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
     });
     return `{/* ${verdict.kind === "oversized" ? "Oversized" : "Unreadable"} content not inlined: ${shown} */}`;
   };
-  let withoutImports = replaceOutsideCode(raw, (source2) => source2.replace(
+  let withoutImports = replaceOutsideCodeAndMdxComments(raw, (source2) => source2.replace(
     SNIPPET_IMPORT_PATTERN,
     (_statement, namedComponent, defaultComponent, sourcePath) => {
       const componentName = namedComponent ?? defaultComponent;
@@ -7602,17 +7841,23 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
         else snippets.set(componentName, snippetComponentBody(nested, componentName));
         return "";
       } catch {
+        let hasLiveUsage = false;
+        replaceOutsideCodeAndMdxComments(raw, (segment) => {
+          if (new RegExp(`<${componentName}(?:\\s|/?>)`).test(segment)) hasLiveUsage = true;
+          return segment;
+        });
+        if (!hasLiveUsage) return "";
         warnings.push({
           code: "missing-page",
           message: `Imported snippet ${sourcePath} could not be resolved and was left as a comment.`,
           source: relative5(repositoryRoot, currentFile).replace(/\\/g, "/")
         });
-        snippets.set(componentName, `{/* Missing imported snippet: ${sourcePath} */}`);
+        snippets.set(componentName, mdxComment(` Missing imported snippet: ${sourcePath} `));
         return "";
       }
     }
   ));
-  withoutImports = replaceOutsideCode(withoutImports, (source2) => source2.replace(
+  withoutImports = replaceOutsideCodeAndMdxComments(withoutImports, (source2) => source2.replace(
     SNIPPET_VALUE_IMPORT_PATTERN,
     (statement, names, sourcePath) => {
       const bindings = names.split(",").map((name) => name.trim()).filter(Boolean).map((name) => {
@@ -7656,7 +7901,12 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
   ));
   const localNames = locallyDeclaredNames(withoutImports);
   for (const [componentName, candidate] of globalAliases) {
-    if (snippets.has(componentName) || localNames.has(componentName) || gate?.(candidate)?.kind === "gated" || !new RegExp(`<${componentName}(?:\\s|/?>)`).test(withoutImports)) continue;
+    let hasLiveUsage = false;
+    replaceOutsideCodeAndMdxComments(withoutImports, (source2) => {
+      if (new RegExp(`<${componentName}(?:\\s|/?>)`).test(source2)) hasLiveUsage = true;
+      return source2;
+    });
+    if (snippets.has(componentName) || localNames.has(componentName) || gate?.(candidate)?.kind === "gated" || !hasLiveUsage) continue;
     const blocked = blockInline(candidate, relative5(repositoryRoot, candidate).replace(/\\/g, "/"));
     if (blocked) {
       snippets.set(componentName, blocked);
@@ -7676,48 +7926,49 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
     if (declaration) preservedDeclarations.set(componentName, declaration);
     else snippets.set(componentName, snippetComponentBody(nested, componentName));
   }
-  let result = withoutImports;
-  for (const [componentName, snippet] of snippets) {
-    result = result.replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)\\s*/>`, "g"), (_tag, attributes) => {
-      return interpolateSnippet(snippet, attributes);
-    }).replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)>([\\s\\S]*?)<\\/${componentName}>`, "g"), (_tag, attributes, children) => {
-      return interpolateSnippet(snippet, attributes, children);
-    });
-  }
-  result = result.replace(SNIPPET_TAG_PATTERN, (_tag, doubleQuoted, singleQuoted) => {
-    const filePath = doubleQuoted ?? singleQuoted;
-    try {
-      const candidate = [
-        () => resolveWithin(siteRoot, `snippets/${filePath}`),
-        () => resolveSnippetPath(filePath, currentFile, repositoryRoot, siteRoot)
-      ].map((resolveCandidate) => {
-        try {
-          return resolveCandidate();
-        } catch {
-          return void 0;
-        }
-      }).find((path) => path !== void 0 && existsSync5(path) && lstatSync5(path).isFile());
-      if (!candidate) throw new Error("file not found");
-      const blocked = blockInline(candidate, filePath, `Snippet file="${filePath}"`);
-      if (blocked) return blocked;
-      return inlineMdxSnippets(
-        withoutFrontmatter(readFileSync5(candidate, "utf8")),
-        candidate,
-        repositoryRoot,
-        warnings,
-        depth + 1,
-        siteRoot,
-        globalAliases,
-        gate
-      );
-    } catch {
-      warnings.push({
-        code: "missing-page",
-        message: `Snippet file="${filePath}" could not be resolved and was left as a comment.`,
-        source: relative5(repositoryRoot, currentFile).replace(/\\/g, "/")
+  let result = replaceOutsideCodeAndComments(withoutImports, (segment) => {
+    for (const [componentName, snippet] of snippets) {
+      segment = segment.replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)\\s*/>`, "g"), (tag, attributes, offset, source2) => {
+        return isolateFences(closeOpenCodeFence(interpolateSnippet(snippet, attributes)), source2, offset, offset + tag.length);
+      }).replace(new RegExp(`<${componentName}((?:\\s[^>]*)?)>([\\s\\S]*?)<\\/${componentName}>`, "g"), (tag, attributes, children, offset, source2) => {
+        return isolateFences(closeOpenCodeFence(interpolateSnippet(snippet, attributes, children)), source2, offset, offset + tag.length);
       });
-      return `{/* Missing snippet: ${filePath} */}`;
     }
+    return segment.replace(SNIPPET_TAG_PATTERN, (tag, doubleQuoted, singleQuoted, offset, source2) => {
+      const filePath = doubleQuoted ?? singleQuoted;
+      try {
+        const candidate = [
+          () => resolveWithin(siteRoot, `snippets/${filePath}`),
+          () => resolveSnippetPath(filePath, currentFile, repositoryRoot, siteRoot)
+        ].map((resolveCandidate) => {
+          try {
+            return resolveCandidate();
+          } catch {
+            return void 0;
+          }
+        }).find((path) => path !== void 0 && existsSync5(path) && lstatSync5(path).isFile());
+        if (!candidate) throw new Error("file not found");
+        const blocked = blockInline(candidate, filePath, `Snippet file="${filePath}"`);
+        if (blocked) return blocked;
+        return isolateFences(closeOpenCodeFence(inlineMdxSnippets(
+          withoutFrontmatter(readFileSync5(candidate, "utf8")),
+          candidate,
+          repositoryRoot,
+          warnings,
+          depth + 1,
+          siteRoot,
+          globalAliases,
+          gate
+        )), source2, offset, offset + tag.length);
+      } catch {
+        warnings.push({
+          code: "missing-page",
+          message: `Snippet file="${filePath}" could not be resolved and was left as a comment.`,
+          source: relative5(repositoryRoot, currentFile).replace(/\\/g, "/")
+        });
+        return mdxComment(` Missing snippet: ${filePath} `);
+      }
+    });
   });
   if (preservedDeclarations.size > 0) {
     const frontmatter = result.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
@@ -7726,7 +7977,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
 
 ${result.slice(prefix.length)}`;
   }
-  return depth === 0 ? hoistMdxImports(result) : result;
+  return depth === 0 ? hoistMdxImports(result) : closeOpenFence(result);
 }
 function injectOpenApiSpecs(config, specs, warnings) {
   const tabs = config.tabs.map((tab) => ({ ...tab }));
@@ -7913,7 +8164,7 @@ function migrateRepository(options) {
   const sourceBudget = options.maxSourceFiles ?? MAX_SOURCE_FILES;
   const scannedFiles = scanFiles(contentRoot, repositoryDir, warnings, discoveryRank, sourceBudget);
   const mintignoreFilteredFiles = mintignoreMatcher ? scannedFiles.filter((file) => !mintignoreMatcher.ignores(file.relativePath)) : scannedFiles;
-  const discoveryBudgetApplied = discoveryRank !== void 0 && mintignoreFilteredFiles.length > sourceBudget;
+  const isUnreferencedSnippetModule = (file) => file.relativePath.split("/").some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase())) && isDocumentationExtension(file.relativePath) && !referenceOrder.has(normalizedReferenceKey(file.relativePath));
   const files = discoveryRank ? selectFilesWithinBudget(mintignoreFilteredFiles, discoveryRank, warnings, allVersionPrefixes, sourceBudget) : mintignoreFilteredFiles;
   if (platform === "fern" && fernProjectRoot) {
     const discovered2 = new Set(files.map((file) => file.relativePath));
@@ -7992,6 +8243,10 @@ function migrateRepository(options) {
     }
     for (const file of mintignoreFilteredFiles) {
       if (keptFiles.has(file) || !isDocFile(file)) continue;
+      if (isUnreferencedSnippetModule(file)) {
+        if (classifyPageGate(file).reason) withheldDocFiles.push(file);
+        continue;
+      }
       droppedPageCount++;
       if (!isGateCandidate(file)) {
         const snippetReason = classifyPageGate(file).reason;
@@ -8214,7 +8469,7 @@ function migrateRepository(options) {
     const publishedText = trackPublishedRefs ? raw : void 0;
     const pageAssetReferences = [];
     if (platform === "fern" || platform === "mintlify" || platform === "docusaurus") {
-      raw = normalizeExplicitHeadingIds(raw);
+      raw = normalizeExplicitHeadingIds(raw, (message) => warnings.push({ code: "invalid-page", message, source: file.relativePath }));
     }
     if (componentMigrator) {
       const warningsBeforeTransform = warnings.length;
@@ -8226,13 +8481,7 @@ function migrateRepository(options) {
     }
     if (platform === "fern" || platform === "mintlify" || platform === "docusaurus") {
       const protectedMath = protectMathBlocks(raw);
-      if (protectedMath.converted) {
-        warnings.push({
-          code: "unsupported-config",
-          message: "Math (KaTeX '$$...$$') has no renderer in Thally yet; it was kept as a fenced code block instead of being dropped.",
-          source: relative5(repositoryDir, file.absolutePath).replace(/\\/g, "/")
-        });
-      } else if (protectedMath.guardTriggered) {
+      if (protectedMath.guardTriggered) {
         warnings.push({
           code: "unsupported-config",
           message: "A suspected math span looked like it needed converting, but doing so broke the page; the page was kept as originally authored instead.",
@@ -8324,7 +8573,7 @@ function migrateRepository(options) {
       page.body = replaceUnknownComponents(page.body, (name) => {
         warnings.push({
           code: "unsupported-config",
-          message: `Component <${name}> has no equivalent in Thally and wasn't found on this page; it was replaced with a plain <div> (or removed, if self-closing) so the page still builds. Add a matching component or edit the page.`,
+          message: `Unresolved MDX component <${name}> was replaced with a plain <div> (or removed, if self-closing) so the page still builds. It may be a site-authored or third-party implementation; review its source before adding a Thally equivalent.`,
           source: file.relativePath
         });
       });
@@ -8451,9 +8700,31 @@ function migrateRepository(options) {
     const source = /^src\/mdx\/migrated\/[^/]+\/source\/(.+)$/.exec(file.path)?.[1];
     return source ? [resolvePath(repositoryDir, source)] : [];
   }));
+  const rootStylesheetPath = platform === "mintlify" && mintlifyProjectRoot ? resolveWithin(mintlifyProjectRoot, "style.css") : void 0;
+  const hasRootStylesheet = Boolean(rootStylesheetPath && existsSync5(rootStylesheetPath) && lstatSync5(rootStylesheetPath).isFile() && !lstatSync5(rootStylesheetPath).isSymbolicLink());
+  let rootStyleProjection;
+  let rootStyleProblem;
+  if (hasRootStylesheet && rootStylesheetPath && lstatSync5(rootStylesheetPath).size <= MAX_ASSET_BYTES) {
+    const css = readFileSync5(rootStylesheetPath, "utf8");
+    if (/@import\b|url\s*\(\s*['"]?\s*(?:javascript:|file:)/i.test(css)) rootStyleProblem = "unsafe";
+    else {
+      try {
+        rootStyleProjection = projectAuthoredStyles(css, [
+          ...pages.map((page) => page.body),
+          ...(componentMigrator?.files() ?? []).map((file) => typeof file.content === "string" ? file.content : "")
+        ]);
+      } catch {
+        rootStyleProblem = "parse";
+      }
+    }
+  }
+  if (trackPublishedRefs && rootStyleProjection?.css) {
+    addPathReferences(rootStyleProjection.css, "", publishedExact, publishedLoose);
+  }
   const siteAssetPaths = /* @__PURE__ */ new Map();
   const fontAssetByRelative = /* @__PURE__ */ new Map();
   for (const file of [...files, ...repositoryAssets, ...fernReferencedAssets]) {
+    if (rootStylesheetPath && file.absolutePath === rootStylesheetPath) continue;
     const firstSegment = file.relativePath.split("/", 1)[0].toLowerCase();
     const siteKind = platform !== "mintlify" ? void 0 : fontRelativePaths.has(file.relativePath) ? "font" : isMintlifyServedScriptOrStyle(file.relativePath) && !importedComponentSources.has(file.absolutePath) ? extname6(file.relativePath).toLowerCase() === ".css" ? "style" : "script" : void 0;
     if (!siteKind && !ASSET_EXTENSIONS.has(extname6(file.relativePath).toLowerCase())) continue;
@@ -8499,7 +8770,8 @@ function migrateRepository(options) {
   const lfsPointerAssets = [];
   const ambiguouslyNamedAssets = [];
   for (const { file, assetPath, size } of orderedAssetCandidates) {
-    if (size > MAX_ASSET_BYTES || totalAssetBytes + size > MAX_TOTAL_ASSET_BYTES) {
+    const individualLimit = referencedAssetPaths.has(assetPath) ? MAX_REFERENCED_ASSET_BYTES : MAX_ASSET_BYTES;
+    if (size > individualLimit || totalAssetBytes + size > MAX_TOTAL_ASSET_BYTES) {
       overBudgetAssets.push(file.relativePath);
       if (referencedAssetPaths.has(assetPath)) overBudgetReferenced++;
       continue;
@@ -8541,7 +8813,7 @@ function migrateRepository(options) {
     for (const entry of copiedSite.filter((item) => item.kind === "style")) {
       warnings.push({
         code: "unsupported-config",
-        message: `Migration gap: custom stylesheet ${entry.path} is NOT applied. It was copied to public/${entry.path} but no page loads it, Thally cannot load a stylesheet from docs.json, and Mintlify-specific selectors will not match Thally's markup. Port the styles you need by hand into src/app/globals.css.`,
+        message: `Migration gap: custom stylesheet ${entry.path} is NOT applied. It was copied to public/${entry.path} but was not declared in docs.json stylesheets; its selectors may target Mintlify's markup. Review and port its authored rules into a Thally stylesheet.`,
         source: entry.path
       });
     }
@@ -8559,7 +8831,7 @@ function migrateRepository(options) {
   if (overBudgetAssets.length > 0) {
     warnings.push({
       code: "limit-reached",
-      message: `${overBudgetAssets.length} asset file${overBudgetAssets.length === 1 ? " was" : "s were"} not copied because files over ${MAX_ASSET_BYTES / 1e6} MB, or beyond ${MAX_TOTAL_ASSET_BYTES / 1e6} MB in total, are skipped: ${listAssetPaths(overBudgetAssets)}. ` + (overBudgetReferenced > 0 ? `${overBudgetReferenced} of them ${overBudgetReferenced === 1 ? "is" : "are"} used by pages, so those images will be broken until you copy ${overBudgetAssets.length === 1 ? "it" : "them"}. ` : "") + `Copy ${overBudgetAssets.length === 1 ? "it" : "them"} into public/ manually.`
+      message: `${overBudgetAssets.length} asset file${overBudgetAssets.length === 1 ? " was" : "s were"} not copied because unreferenced files over ${MAX_ASSET_BYTES / 1e6} MB, referenced files over ${MAX_REFERENCED_ASSET_BYTES / 1e6} MB, or files beyond ${MAX_TOTAL_ASSET_BYTES / 1e6} MB in total, are skipped: ${listAssetPaths(overBudgetAssets)}. ` + (overBudgetReferenced > 0 ? `${overBudgetReferenced} of them ${overBudgetReferenced === 1 ? "is" : "are"} used by pages, so those images will be broken until you copy ${overBudgetAssets.length === 1 ? "it" : "them"}. ` : "") + `Copy ${overBudgetAssets.length === 1 ? "it" : "them"} into public/ manually.`
     });
   }
   if (lfsPointerAssets.length > 0) {
@@ -8568,7 +8840,31 @@ function migrateRepository(options) {
       message: `${lfsPointerAssets.length} asset file${lfsPointerAssets.length === 1 ? " is a Git LFS pointer" : "s are Git LFS pointers"}, not real content, and ${lfsPointerAssets.length === 1 ? "was" : "were"} not copied (Git LFS was skipped during clone because the host has no git-lfs binary): ${listAssetPaths(lfsPointerAssets)}. Install git-lfs and re-run the migration, or copy the real files into public/ manually.`
     });
   }
-  if (!discoveryBudgetApplied && files.length >= sourceBudget) {
+  if (hasRootStylesheet && rootStylesheetPath && mintlifyProjectRoot) {
+    const size = lstatSync5(rootStylesheetPath).size;
+    if (size > MAX_ASSET_BYTES || totalAssetBytes + size > MAX_TOTAL_ASSET_BYTES) {
+      warnings.push({ code: "limit-reached", message: "Mintlify root style.css exceeded the asset budget and was not imported.", source: "style.css" });
+    } else if (rootStyleProblem === "unsafe") {
+      warnings.push({ code: "unsupported-config", message: "Mintlify root style.css contains a CSS import or unsafe URL; review and import it manually.", source: "style.css" });
+    } else if (rootStyleProblem === "parse" || !rootStyleProjection) {
+      warnings.push({ code: "unsupported-config", message: "Mintlify root style.css could not be parsed and was not imported.", source: "style.css" });
+    } else {
+      if (rootStyleProjection.omittedSelectors > 0) warnings.push({
+        code: "unsupported-config",
+        source: "style.css",
+        message: `Skipped ${rootStyleProjection.omittedSelectors} stylesheet selector${rootStyleProjection.omittedSelectors === 1 ? "" : "s"} that target platform-owned or unreferenced markup. Recreate any intentional shell customization with Thally configuration.`
+      });
+      if (rootStyleProjection.css.trim()) {
+        const identity = createHash2("sha256").update(componentSourceIdentity(options.sourceUrl, repositoryDir, mintlifyProjectRoot)).digest("hex").slice(0, 12);
+        const assetPath = `migrated/${identity}/style.css`;
+        const content = Buffer.from(rootStyleProjection.css);
+        assets.push({ path: assetPath, content });
+        docsConfig = { ...docsConfig, stylesheets: [...docsConfig.stylesheets ?? [], `/${assetPath}`] };
+        totalAssetBytes += content.length;
+      }
+    }
+  }
+  if (!discoveryRank && files.length >= sourceBudget) {
     warnings.push({ code: "limit-reached", message: `Stopped scanning after ${sourceBudget} files, so the rest of the repository was not looked at. Run the migration on a smaller part of the repository with --docs-dir.` });
   }
   if (platform === "docusaurus") {
@@ -9241,6 +9537,7 @@ function mergeMigrationConfig(existing, incoming) {
     // Collection presentation belongs to the imported information
     // architecture; starter defaults must not coerce source dropdowns to tabs.
     navigation: incoming.navigation ?? existing.navigation,
+    ...existing.stylesheets?.length || incoming.stylesheets?.length ? { stylesheets: [.../* @__PURE__ */ new Set([...existing.stylesheets ?? [], ...incoming.stylesheets ?? []])] } : {},
     ...i18n ? { i18n } : {},
     // Existing providers win per provider; imported ones fill the gaps.
     // A malformed (string/array) existing value must not spread into index keys.
@@ -9587,7 +9884,7 @@ function embeddedMintlifyConfig(body) {
 function plainDescription(value) {
   return value.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").replace(/[`*_>#-]/g, "").replace(/\s+/g, " ").trim().slice(0, 240);
 }
-function withoutFencedCode(body) {
+function withoutFencedCode2(body) {
   let fenceCharacter = "";
   let fenceLength = 0;
   return body.split("\n").map((line) => {
@@ -9897,7 +10194,7 @@ function sanitizeRemoteMarkdown(body) {
   }).join("\n");
   const urlSafeMarkdown = sanitizeMarkdownUrls(sanitized);
   if (urlSafeMarkdown === null) return null;
-  const executable = withoutFencedCode(urlSafeMarkdown).replace(/\{\/\*[\s\S]*?\*\/\}/g, "").replace(/<(?:https?:\/\/|mailto:)[^>]+>/gi, "").replace(/(`+)[\s\S]*?\1/g, "");
+  const executable = withoutFencedCode2(urlSafeMarkdown).replace(/\{\/\*[\s\S]*?\*\/\}/g, "").replace(/<(?:https?:\/\/|mailto:)[^>]+>/gi, "").replace(/(`+)[\s\S]*?\1/g, "");
   if (/^\s*(?:import|export)\s/m.test(executable)) return null;
   let hasUnsafeExpression = false;
   const withoutStaticProps = executable.replace(/=\{([^{}\n]*)\}/g, (original, value) => {
@@ -10847,7 +11144,7 @@ async function migrateUrl(options) {
 }
 
 // src/remote-api.ts
-import { createHash as createHash2 } from "crypto";
+import { createHash as createHash3 } from "crypto";
 import { lookup } from "dns/promises";
 import { request } from "https";
 import { isIP } from "net";
@@ -11007,7 +11304,7 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       const extension = /\.ya?ml$/i.test(url.pathname) ? "yaml" : "json";
       const body = await downloadSpec(reference.url, fetcher);
       const operations = parseOpenApi(body, extension);
-      const filename = `openapi-${createHash2("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
+      const filename = `openapi-${createHash3("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
       assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });
       for (const page of pages) {
         const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;