@thallylabs/migrate 0.2.21 → 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";
@@ -428,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/);
@@ -442,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;
@@ -484,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;
         }
@@ -1222,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";
@@ -1233,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,
@@ -1269,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);
@@ -2205,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(
@@ -2455,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}`;
@@ -2475,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;
       }
@@ -2550,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);
   }
@@ -2803,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);
           }
         }
       }
@@ -3133,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";
@@ -4131,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 [];
@@ -4155,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 } : {},
@@ -4832,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",
@@ -4846,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;
@@ -5092,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,
@@ -5926,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) {
@@ -7186,18 +7386,18 @@ function isolateFences(snippet, source, start, 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);
       }
     }
@@ -7205,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");
       }
     }
   }
@@ -7556,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;
@@ -7601,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;
@@ -7628,6 +7841,12 @@ 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.`,
@@ -7638,7 +7857,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
       }
     }
   ));
-  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) => {
@@ -7682,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);
@@ -7705,9 +7929,9 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
   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(interpolateSnippet(snippet, attributes), source2, offset, offset + tag.length);
+        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(interpolateSnippet(snippet, attributes, children), source2, offset, offset + tag.length);
+        return isolateFences(closeOpenCodeFence(interpolateSnippet(snippet, attributes, children)), source2, offset, offset + tag.length);
       });
     }
     return segment.replace(SNIPPET_TAG_PATTERN, (tag, doubleQuoted, singleQuoted, offset, source2) => {
@@ -7726,7 +7950,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
         if (!candidate) throw new Error("file not found");
         const blocked = blockInline(candidate, filePath, `Snippet file="${filePath}"`);
         if (blocked) return blocked;
-        return isolateFences(inlineMdxSnippets(
+        return isolateFences(closeOpenCodeFence(inlineMdxSnippets(
           withoutFrontmatter(readFileSync5(candidate, "utf8")),
           candidate,
           repositoryRoot,
@@ -7735,7 +7959,7 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
           siteRoot,
           globalAliases,
           gate
-        ), source2, offset, offset + tag.length);
+        )), source2, offset, offset + tag.length);
       } catch {
         warnings.push({
           code: "missing-page",
@@ -7940,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));
@@ -8019,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;
@@ -8253,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.",
@@ -8351,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
         });
       });
@@ -8478,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;
@@ -8526,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;
@@ -8568,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
       });
     }
@@ -8586,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) {
@@ -8595,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") {
@@ -9268,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.
@@ -9614,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) => {
@@ -9924,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) => {
@@ -10874,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";
@@ -11034,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;