@thallylabs/migrate 0.2.11 → 0.2.14

package/dist/index.js

@@ -16,7 +16,7 @@ import {
 import { createRequire } from "module";
 import { basename as basename3, dirname as dirname4, extname as extname5, isAbsolute as isAbsolute2, relative as relative5, resolve as resolvePath, sep as sep2 } from "path";
 import { parse as parseYaml4 } from "yaml";
-import * as ts2 from "typescript";
+import * as ts3 from "typescript";
 
 // src/components.ts
 import { createHash } from "crypto";
@@ -26,7 +26,7 @@ import postcss from "postcss";
 import selectorParser from "postcss-selector-parser";
 import remarkMdx2 from "remark-mdx";
 import remarkParse2 from "remark-parse";
-import ts from "typescript";
+import ts2 from "typescript";
 import { unified as unified2 } from "unified";
 
 // src/frontmatter.ts
@@ -142,7 +142,15 @@ var THALLY_BUILTIN_COMPONENTS = /* @__PURE__ */ new Set([
   "Visibility",
   "Human",
   "Agent",
-  "BannerPreview"
+  "BannerPreview",
+  "Banner",
+  "CodeBlock",
+  "Column",
+  "FileTree",
+  "LiteYouTubeEmbed",
+  "MDX",
+  "Video",
+  "YouTube"
 ]);
 function isThallyBuiltinComponent(name) {
   return THALLY_BUILTIN_COMPONENTS.has(name) || THALLY_BUILTIN_COMPONENTS.has(name.split(".")[0]);
@@ -1094,12 +1102,117 @@ function normalizeMintlifyParameterAnchors(body) {
     (match, _tag, _before, doubleQuoted, singleQuoted) => `${anchorFor(doubleQuoted ?? singleQuoted)}${match}`
   ));
 }
+function matchFenceLine(line) {
+  const match = line.match(/^(\s*)(`{3,}|~{3,})(.*)$/);
+  if (!match) return null;
+  return { index: -1, indent: match[1], char: match[2][0], length: match[2].length, info: match[3].trim(), rest: match[3] };
+}
+function normalizeNestedCodeFences(body) {
+  const lines = body.split("\n");
+  const fences = lines.map((line, index) => {
+    const fence = matchFenceLine(line);
+    return fence ? { ...fence, index } : null;
+  }).filter((fence) => fence !== null);
+  if (fences.length === 0) return body;
+  const stack = [];
+  const roots = [];
+  for (const fence of fences) {
+    const top = stack.at(-1);
+    if (top && fence.info === "" && fence.char === top.open.char && fence.length >= top.open.length) {
+      stack.pop();
+      const block = { open: top.open, close: fence, children: top.children };
+      const parent = stack.at(-1);
+      if (parent) parent.children.push(block);
+      else roots.push(block);
+    } else {
+      stack.push({ open: fence, children: [] });
+    }
+  }
+  if (stack.length > 0) return body;
+  const widenedLengths = /* @__PURE__ */ new Map();
+  function requiredLength(block) {
+    const deepestChild = Math.max(0, ...block.children.map(requiredLength));
+    const length = Math.max(block.open.length, deepestChild > 0 ? deepestChild + 1 : 0);
+    widenedLengths.set(block.open.index, length);
+    widenedLengths.set(block.close.index, length);
+    return length;
+  }
+  roots.forEach(requiredLength);
+  return lines.map((line, index) => {
+    const targetLength = widenedLengths.get(index);
+    const fence = targetLength ? matchFenceLine(line) : null;
+    if (!targetLength || !fence || targetLength <= fence.length) return line;
+    return `${fence.indent}${fence.char.repeat(targetLength)}${fence.rest}`;
+  }).join("\n");
+}
+function maskCodeRegions(body) {
+  let inFence = false;
+  return body.split("\n").map((line) => {
+    if (/^\s*(`{3,}|~{3,})/.test(line)) {
+      inFence = !inFence;
+      return " ".repeat(line.length);
+    }
+    if (inFence) return " ".repeat(line.length);
+    return line.replace(/`[^`]*`/g, (span) => " ".repeat(span.length));
+  }).join("\n");
+}
+function isKnownComponentName(name, body) {
+  if (isThallyBuiltinComponent(name)) return true;
+  if (new RegExp(`^\\s*export\\s+(?:const|function|default\\s+function)\\s+${name}\\b`, "m").test(body)) return true;
+  if (new RegExp(`^\\s*import\\s+(?:\\{[^}]*\\b${name}\\b[^}]*\\}|${name})\\s+from\\s+['"][^'"]+['"]`, "m").test(body)) return true;
+  return false;
+}
+function escapeOrphanCapitalizedTags(body) {
+  const masked = maskCodeRegions(body);
+  const tagPattern = /<(\/?)([A-Z][A-Za-z0-9]*)(?:\s+[^<>]*?)?(\/?)>/g;
+  const opens = /* @__PURE__ */ new Map();
+  const closedOrSelfClosed = /* @__PURE__ */ new Set();
+  for (const match of masked.matchAll(tagPattern)) {
+    const [full, closing, name, selfClosing] = match;
+    if (closing || selfClosing) {
+      closedOrSelfClosed.add(name);
+      continue;
+    }
+    const start = match.index;
+    const list = opens.get(name) ?? [];
+    list.push({ start, end: start + full.length });
+    opens.set(name, list);
+  }
+  const edits = [];
+  for (const [name, ranges] of opens) {
+    if (closedOrSelfClosed.has(name) || isKnownComponentName(name, body)) continue;
+    edits.push(...ranges);
+  }
+  if (edits.length === 0) return body;
+  try {
+    compileSync(body, { outputFormat: "program" });
+    return body;
+  } catch {
+  }
+  edits.sort((a, b) => a.start - b.start);
+  let result = "";
+  let cursor = 0;
+  for (const edit of edits) {
+    result += body.slice(cursor, edit.start);
+    result += body.slice(edit.start, edit.end).replace(/^</, "&lt;").replace(/>$/, "&gt;");
+    cursor = edit.end;
+  }
+  return result + body.slice(cursor);
+}
+var REACT_HOOK_NAMES = ["useState", "useEffect", "useRef", "useCallback", "useMemo", "useContext", "useReducer"];
+function injectReactHookImports(body) {
+  const masked = maskCodeRegions(body);
+  const used = REACT_HOOK_NAMES.filter((hook) => new RegExp(`\\b${hook}\\s*\\(`).test(masked) && !new RegExp(`import\\s*\\{[^}]*\\b${hook}\\b[^}]*\\}\\s*from\\s*['"]react['"]`).test(body));
+  return used.length > 0 ? `import { ${used.join(", ")} } from 'react'
+
+${body}` : body;
+}
 function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   const runFern = platform === "fern";
   const runMintlify = platform === "mintlify";
   const runDocusaurus = platform === "docusaurus";
   const sourceBody = runDocusaurus && unwrapMdxCodeBlocks ? unwrapDocusaurusMdxCodeBlocks(body) : body;
-  let rewritten = normalizeDocusaurusAdmonitions(normalizeExplicitHeadingIds(runFern ? normalizeFernFileTrees(normalizeFernCallouts(sourceBody)) : sourceBody));
+  let rewritten = normalizeDocusaurusAdmonitions(normalizeExplicitHeadingIds(runFern ? normalizeFernFileTrees(normalizeFernCallouts(normalizeNestedCodeFences(sourceBody))) : normalizeNestedCodeFences(sourceBody)));
   if (runDocusaurus) {
     rewritten = replaceOutsideCode(rewritten, (segment) => segment.replace(
       /:([+\w-]+):/g,
@@ -1133,7 +1246,7 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
     return result;
   });
   if (runFern) rewritten = unwrapFernCodeBlockTabs(rewritten);
-  const normalized = provideScopedGlobalReferences(rewritten);
+  const normalized = escapeOrphanCapitalizedTags(provideScopedGlobalReferences(rewritten));
   if (runDocusaurus && sourceBody !== body) {
     try {
       compileSync(normalized, { outputFormat: "program" });
@@ -1151,7 +1264,7 @@ function parseMarkdownPage(input) {
     ...input.locale ? { locale: input.locale } : {}
   };
   const identity = input.resolveIdentity?.(parsed.data, fallbackIdentity) ?? fallbackIdentity;
-  let body = normalizeMdx(parsed.content, input.platform).trim();
+  let body = injectReactHookImports(normalizeMdx(parsed.content, input.platform)).trim();
   const keywords = Array.isArray(parsed.data.keywords) ? parsed.data.keywords.filter((value) => typeof value === "string") : [];
   const heading = leadingPageHeading(body);
   const title = typeof parsed.data.title === "string" && parsed.data.title.trim() ? parsed.data.title.trim() : heading?.title ?? titleFromId(identity.navigationId);
@@ -1261,6 +1374,543 @@ function normalizeAssetPath(value) {
   return segments.join("/");
 }
 
+// src/inline-extraction.ts
+import ts from "typescript";
+var SERVER_ONLY_IDENTIFIERS = /* @__PURE__ */ new Set(["process", "require", "module", "exports", "__dirname", "__filename", "Buffer"]);
+var BROWSER_IDENTIFIERS = /* @__PURE__ */ new Set([
+  "window",
+  "document",
+  "localStorage",
+  "sessionStorage",
+  "navigator",
+  "location",
+  "history",
+  "IntersectionObserver",
+  "ResizeObserver",
+  "MutationObserver",
+  "matchMedia",
+  "requestAnimationFrame",
+  "cancelAnimationFrame",
+  "alert",
+  "confirm",
+  "prompt",
+  "HTMLElement",
+  "Element",
+  "Node",
+  "Event",
+  "KeyboardEvent",
+  "MouseEvent",
+  "CustomEvent",
+  "FormData",
+  "File",
+  "FileReader",
+  "Image",
+  "Audio",
+  "XMLHttpRequest",
+  "WebSocket",
+  "getComputedStyle",
+  "innerWidth",
+  "innerHeight",
+  "scrollTo"
+]);
+var JS_GLOBALS = /* @__PURE__ */ new Set([
+  "undefined",
+  "NaN",
+  "Infinity",
+  "globalThis",
+  "arguments",
+  "Object",
+  "Function",
+  "Array",
+  "Number",
+  "Boolean",
+  "String",
+  "Symbol",
+  "BigInt",
+  "Date",
+  "RegExp",
+  "Error",
+  "AggregateError",
+  "EvalError",
+  "RangeError",
+  "ReferenceError",
+  "SyntaxError",
+  "TypeError",
+  "URIError",
+  "JSON",
+  "Math",
+  "Intl",
+  "Reflect",
+  "Proxy",
+  "Promise",
+  "Map",
+  "Set",
+  "WeakMap",
+  "WeakSet",
+  "WeakRef",
+  "ArrayBuffer",
+  "SharedArrayBuffer",
+  "DataView",
+  "Atomics",
+  "Int8Array",
+  "Uint8Array",
+  "Uint8ClampedArray",
+  "Int16Array",
+  "Uint16Array",
+  "Int32Array",
+  "Uint32Array",
+  "Float32Array",
+  "Float64Array",
+  "BigInt64Array",
+  "BigUint64Array",
+  "parseInt",
+  "parseFloat",
+  "isNaN",
+  "isFinite",
+  "encodeURI",
+  "encodeURIComponent",
+  "decodeURI",
+  "decodeURIComponent",
+  "console",
+  "fetch",
+  "URL",
+  "URLSearchParams",
+  "Headers",
+  "Request",
+  "Response",
+  "AbortController",
+  "AbortSignal",
+  "TextEncoder",
+  "TextDecoder",
+  "atob",
+  "btoa",
+  "structuredClone",
+  "queueMicrotask",
+  "performance",
+  "setTimeout",
+  "clearTimeout",
+  "setInterval",
+  "clearInterval"
+]);
+var IMPLICIT_MODULE_NAMES = /* @__PURE__ */ new Set(["React", "MintlifyComponents"]);
+function parse(source) {
+  return ts.createSourceFile("inline.tsx", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+}
+function bindingNames(name, into) {
+  if (ts.isIdentifier(name)) into.add(name.text);
+  else for (const element of name.elements) if (ts.isBindingElement(element)) bindingNames(element.name, into);
+}
+function isFunctionLike(node) {
+  return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) || ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node);
+}
+function functionScope(fn) {
+  const scope = /* @__PURE__ */ new Set();
+  if ((ts.isFunctionExpression(fn) || ts.isFunctionDeclaration(fn)) && fn.name) scope.add(fn.name.text);
+  for (const parameter of fn.parameters) bindingNames(parameter.name, scope);
+  function collect(node) {
+    if (ts.isVariableDeclaration(node)) bindingNames(node.name, scope);
+    if ((ts.isFunctionDeclaration(node) || ts.isClassDeclaration(node)) && node.name) scope.add(node.name.text);
+    if (isFunctionLike(node)) return;
+    ts.forEachChild(node, collect);
+  }
+  if (fn.body) ts.forEachChild(fn.body, collect);
+  if (fn.body && !ts.isBlock(fn.body)) collect(fn.body);
+  return scope;
+}
+function collectRefs(root) {
+  const refs = [];
+  const assigned = [];
+  let awaitOutsideAsync = false;
+  let dynamicImport = false;
+  function bound(name, scopes) {
+    return scopes.some((scope) => scope.has(name));
+  }
+  function push(name, kind, scopes) {
+    if (!bound(name, scopes)) refs.push({ name, kind });
+  }
+  function walkNode(node, scopes, inAsync) {
+    if (ts.isTypeNode(node)) return;
+    if (isFunctionLike(node)) {
+      const nextScopes = [...scopes, functionScope(node)];
+      const async = !!node.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword);
+      for (const parameter of node.parameters) {
+        if (!ts.isIdentifier(parameter.name)) walkNode(parameter.name, nextScopes, async);
+        if (parameter.initializer) walkNode(parameter.initializer, nextScopes, async);
+      }
+      if (node.body) walkNode(node.body, nextScopes, async);
+      return;
+    }
+    if (ts.isAwaitExpression(node) && !inAsync) awaitOutsideAsync = true;
+    const target = ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment ? node.left : (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) && (node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken) ? node.operand : void 0;
+    if (target) {
+      let base = target;
+      while (ts.isPropertyAccessExpression(base) || ts.isElementAccessExpression(base)) base = base.expression;
+      if (ts.isIdentifier(base) && !bound(base.text, scopes)) assigned.push(base.text);
+    }
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) dynamicImport = true;
+    if (ts.isIdentifier(node)) {
+      const parent = node.parent;
+      const kind = ts.isJsxExpression(parent) && parent.parent && ts.isJsxAttribute(parent.parent) ? "prop" : "other";
+      push(node.text, kind, scopes);
+      return;
+    }
+    if (ts.isJsxOpeningElement(node) || ts.isJsxSelfClosingElement(node)) {
+      let tag = node.tagName;
+      while (ts.isPropertyAccessExpression(tag)) tag = tag.expression;
+      if (ts.isIdentifier(tag)) {
+        if (node.tagName !== tag || /^[A-Z]/.test(tag.text)) push(tag.text, node.tagName === tag ? "tag" : "member", scopes);
+      }
+      walkNode(node.attributes, scopes, inAsync);
+      return;
+    }
+    if (ts.isJsxClosingElement(node)) return;
+    if (ts.isJsxAttribute(node)) {
+      if (node.initializer) walkNode(node.initializer, scopes, inAsync);
+      return;
+    }
+    if (ts.isPropertyAccessExpression(node)) {
+      walkNode(node.expression, scopes, inAsync);
+      return;
+    }
+    if (ts.isQualifiedName(node)) return;
+    if (ts.isPropertyAssignment(node)) {
+      if (ts.isComputedPropertyName(node.name)) walkNode(node.name.expression, scopes, inAsync);
+      walkNode(node.initializer, scopes, inAsync);
+      return;
+    }
+    if (ts.isShorthandPropertyAssignment(node)) {
+      push(node.name.text, "other", scopes);
+      if (node.objectAssignmentInitializer) walkNode(node.objectAssignmentInitializer, scopes, inAsync);
+      return;
+    }
+    if (ts.isBindingElement(node)) {
+      if (node.propertyName && ts.isComputedPropertyName(node.propertyName)) walkNode(node.propertyName.expression, scopes, inAsync);
+      if (node.initializer) walkNode(node.initializer, scopes, inAsync);
+      if (!ts.isIdentifier(node.name)) walkNode(node.name, scopes, inAsync);
+      return;
+    }
+    if (ts.isVariableDeclaration(node)) {
+      if (!ts.isIdentifier(node.name)) walkNode(node.name, scopes, inAsync);
+      if (node.initializer) walkNode(node.initializer, scopes, inAsync);
+      return;
+    }
+    if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) {
+      node.members.forEach((member) => walkNode(member, scopes, inAsync));
+      for (const clause of node.heritageClauses ?? []) for (const type of clause.types) walkNode(type.expression, scopes, inAsync);
+      return;
+    }
+    if (ts.isPropertyDeclaration(node)) {
+      if (node.initializer) walkNode(node.initializer, scopes, inAsync);
+      return;
+    }
+    if (ts.isLabeledStatement(node)) {
+      walkNode(node.statement, scopes, inAsync);
+      return;
+    }
+    if (ts.isBreakOrContinueStatement(node)) return;
+    ts.forEachChild(node, (child) => walkNode(child, scopes, inAsync));
+  }
+  walkNode(root, [], false);
+  return { refs, assigned, awaitOutsideAsync, dynamicImport };
+}
+function declaredNames(statement) {
+  const isDefault = !!(ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : void 0)?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword) || ts.isExportAssignment(statement);
+  const names = /* @__PURE__ */ new Set();
+  let componentLike = false;
+  if (ts.isVariableStatement(statement)) {
+    for (const declaration of statement.declarationList.declarations) {
+      bindingNames(declaration.name, names);
+      const initializer = declaration.initializer && unwrap(declaration.initializer);
+      if (ts.isIdentifier(declaration.name) && /^[A-Z]/.test(declaration.name.text) && initializer && (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer) || ts.isClassExpression(initializer))) {
+        componentLike = true;
+      }
+    }
+  } else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) {
+    names.add(statement.name.text);
+    componentLike = /^[A-Z]/.test(statement.name.text);
+  }
+  return { names: [...names], componentLike, defaultExport: isDefault };
+}
+function unwrap(expression) {
+  let current = expression;
+  while (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current)) current = current.expression;
+  return current;
+}
+function analyzeUnit(index, source, reactGlobals) {
+  const sf = parse(source);
+  const statement = sf.statements[0];
+  const blockers = [];
+  if (!statement || sf.statements.length !== 1) {
+    return { index, source, names: [], refs: [], assigned: [], hooks: false, clientOnly: false, componentLike: false, blockers: ["is not a single declaration"] };
+  }
+  const { names, componentLike, defaultExport } = declaredNames(statement);
+  if (defaultExport) blockers.push("is a default export");
+  const { refs, assigned, awaitOutsideAsync, dynamicImport } = collectRefs(statement);
+  if (awaitOutsideAsync) blockers.push("uses await outside an async function");
+  if (dynamicImport) blockers.push("uses a dynamic import()");
+  const initializer = ts.isVariableStatement(statement) && statement.declarationList.declarations.length === 1 ? statement.declarationList.declarations[0].initializer && unwrap(statement.declarationList.declarations[0].initializer) : statement;
+  if (initializer && isFunctionLike(initializer) && initializer.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword)) {
+    blockers.push("is an async (server) component");
+  }
+  for (const { name } of refs) {
+    if (SERVER_ONLY_IDENTIFIERS.has(name)) blockers.push(`uses the server-only \`${name}\``);
+  }
+  let handlers = false;
+  function scanHandlers(node) {
+    if (ts.isJsxAttribute(node) && ts.isIdentifier(node.name) && /^on[A-Z]/.test(node.name.text)) handlers = true;
+    ts.forEachChild(node, scanHandlers);
+  }
+  scanHandlers(statement);
+  return {
+    index,
+    source,
+    names,
+    refs,
+    assigned,
+    hooks: refs.some(({ name }) => reactGlobals.has(name)) || /\bReact\.(?:use[A-Z]\w*|createContext|forwardRef|memo)\b/.test(source),
+    clientOnly: handlers || refs.some(({ name }) => BROWSER_IDENTIFIERS.has(name)),
+    componentLike,
+    blockers: [...new Set(blockers)]
+  };
+}
+function helperNames(source) {
+  const statement = parse(source).statements[0];
+  return statement ? declaredNames(statement).names : [];
+}
+function importLocals(statementText) {
+  const sf = parse(statementText);
+  const locals = [];
+  for (const statement of sf.statements) {
+    if (!ts.isImportDeclaration(statement) || !statement.importClause) continue;
+    const clause = statement.importClause;
+    if (clause.name) locals.push(clause.name.text);
+    const named = clause.namedBindings;
+    if (named && ts.isNamespaceImport(named)) locals.push(named.name.text);
+    if (named && ts.isNamedImports(named)) for (const element of named.elements) locals.push(element.name.text);
+  }
+  return locals;
+}
+function expressionRefs(expression) {
+  const sf = parse(`const __expression = (${expression})`);
+  const statement = sf.statements[0];
+  return statement ? collectRefs(statement).refs : [];
+}
+function bodyReferences(tree) {
+  const mdastTags = /* @__PURE__ */ new Set();
+  const refs = [];
+  function visit(node) {
+    if (node.type === "mdxjsEsm") return;
+    if (["mdxJsxFlowElement", "mdxJsxTextElement"].includes(node.type) && node.name) {
+      const root = node.name.split(".")[0];
+      if (node.name.includes(".")) refs.push({ name: root, kind: "member" });
+      else mdastTags.add(root);
+    }
+    if (["mdxFlowExpression", "mdxTextExpression"].includes(node.type) && node.value) refs.push(...expressionRefs(node.value));
+    for (const attribute of node.attributes ?? []) {
+      const value = attribute.value;
+      if (attribute.type === "mdxJsxExpressionAttribute" && typeof value === "string") {
+        refs.push(...expressionRefs(`{${value}}`));
+      } else if (value && typeof value === "object" && typeof value.value === "string") {
+        refs.push(...expressionRefs(value.value).map((ref, _index, all) => all.length === 1 && value.value.trim() === ref.name ? { name: ref.name, kind: "prop" } : ref));
+      }
+    }
+    for (const child of node.children ?? []) visit(child);
+  }
+  visit(tree);
+  return { mdastTags, refs };
+}
+function planInlineExtraction(input) {
+  const units = input.declarations.map((declaration, index) => analyzeUnit(index, declaration.source, input.reactGlobals));
+  const owner = /* @__PURE__ */ new Map();
+  for (const unit of units) for (const name of unit.names) owner.set(name, unit.index);
+  for (let changed = true; changed; ) {
+    changed = false;
+    for (const unit of units) {
+      if (unit.hooks) continue;
+      if (unit.refs.some(({ name }) => /^use[A-Z]/.test(name) && units[owner.get(name) ?? -1]?.hooks)) {
+        unit.hooks = true;
+        changed = true;
+      }
+    }
+  }
+  const importByLocal = /* @__PURE__ */ new Map();
+  for (const statement of input.copyableImports) for (const local of importLocals(statement)) importByLocal.set(local, statement);
+  const helperByName = /* @__PURE__ */ new Map();
+  for (const helper of input.helperDeclarations) {
+    for (const name of helperNames(helper)) helperByName.set(name, helper);
+  }
+  const body = bodyReferences(input.tree);
+  const dependencies = (unit) => {
+    const found = /* @__PURE__ */ new Set();
+    for (const { name } of unit.refs) {
+      const target = owner.get(name);
+      if (target !== void 0 && target !== unit.index) found.add(target);
+    }
+    return found;
+  };
+  const closureOf = (rootIndex) => {
+    const seen = /* @__PURE__ */ new Set([rootIndex]);
+    const queue = [rootIndex];
+    while (queue.length) for (const next of dependencies(units[queue.pop()])) {
+      if (!seen.has(next)) {
+        seen.add(next);
+        queue.push(next);
+      }
+    }
+    return seen;
+  };
+  const intrinsicBlocker = (unit) => {
+    if (unit.blockers.length > 0) return `\`${unit.names[0] ?? "a dependency"}\` ${unit.blockers[0]}`;
+    for (const { name, kind } of unit.refs) {
+      if (owner.has(name) || importByLocal.has(name) || helperByName.has(name)) continue;
+      if (input.unavailableImports.has(name)) {
+        return `\`${unit.names[0]}\` uses \`${name}\`, imported from ${input.unavailableImports.get(name)}, which is not available in the migrated project`;
+      }
+      if (input.reactGlobals.has(name) || IMPLICIT_MODULE_NAMES.has(name) || JS_GLOBALS.has(name) || BROWSER_IDENTIFIERS.has(name)) continue;
+      if ((kind === "tag" || kind === "member") && isThallyBuiltinComponent(name)) continue;
+      return `\`${unit.names[0]}\` uses \`${name}\`, which is not declared or imported on the page`;
+    }
+    return void 0;
+  };
+  const roots = units.filter((unit) => unit.hooks && unit.names.some((name) => /^[A-Z]/.test(name))).map((unit) => unit.index);
+  const blocked = [];
+  const active = new Set(roots);
+  const block = (rootIndex, reason) => {
+    active.delete(rootIndex);
+    blocked.push({ name: units[rootIndex].names.find((name) => /^[A-Z]/.test(name)) ?? units[rootIndex].names[0], reason });
+  };
+  for (const rootIndex of roots) {
+    for (const member of closureOf(rootIndex)) {
+      const reason = intrinsicBlocker(units[member]);
+      if (reason) {
+        block(rootIndex, reason);
+        break;
+      }
+    }
+  }
+  for (let round = 0; round <= units.length + 1; round += 1) {
+    const inModule = /* @__PURE__ */ new Set();
+    for (const rootIndex of active) for (const member of closureOf(rootIndex)) inModule.add(member);
+    const clientSide = /* @__PURE__ */ new Set();
+    for (const index of inModule) if (units[index].hooks || units[index].clientOnly) clientSide.add(index);
+    for (let changed = true; changed; ) {
+      changed = false;
+      for (const index of inModule) {
+        if (clientSide.has(index)) continue;
+        const unit = units[index];
+        const callsClient = unit.refs.some(({ name, kind }) => {
+          const target = owner.get(name);
+          return target !== void 0 && clientSide.has(target) && kind !== "tag" && kind !== "prop";
+        });
+        if (callsClient) {
+          clientSide.add(index);
+          changed = true;
+        }
+      }
+    }
+    for (const rootIndex of active) clientSide.add(rootIndex);
+    const nonModuleRefs = [...body.refs];
+    for (const unit of units) if (!inModule.has(unit.index)) nonModuleRefs.push(...unit.refs);
+    const referencedByPage = (index) => units[index].names.some((name) => body.mdastTags.has(name) || nonModuleRefs.some((ref) => ref.name === name));
+    const kept = /* @__PURE__ */ new Set();
+    for (const index of inModule) {
+      if (clientSide.has(index)) continue;
+      if (!units[index].componentLike || referencedByPage(index)) kept.add(index);
+    }
+    for (let changed = true; changed; ) {
+      changed = false;
+      for (const index of kept) for (const dependency of dependencies(units[index])) {
+        if (inModule.has(dependency) && !clientSide.has(dependency) && !kept.has(dependency)) {
+          kept.add(dependency);
+          changed = true;
+        }
+      }
+    }
+    const moved = new Set([...inModule].filter((index) => !kept.has(index)));
+    const pageRefs = [...nonModuleRefs];
+    for (const index of kept) pageRefs.push(...units[index].refs);
+    const violation = [...moved].find((index) => clientSide.has(index) && units[index].names.some((name) => pageRefs.some((ref) => ref.name === name && ref.kind !== "tag" && ref.kind !== "prop")));
+    if (violation !== void 0) {
+      const names = units[violation].names;
+      const readsIt = (ref) => names.includes(ref.name) && ref.kind !== "tag" && ref.kind !== "prop";
+      const readers = units.filter((unit) => !moved.has(unit.index) && unit.refs.some(readsIt));
+      const promotable = !body.refs.some(readsIt) && readers.every((unit) => unit.componentLike && !active.has(unit.index) && [...closureOf(unit.index)].every((member) => !intrinsicBlocker(units[member])));
+      if (promotable && readers.length > 0) {
+        for (const unit of readers) active.add(unit.index);
+        continue;
+      }
+      for (const rootIndex of [...active]) {
+        if (closureOf(rootIndex).has(violation)) {
+          block(rootIndex, `\`${names[0]}\` is also read or called by page code that stays on the server`);
+        }
+      }
+      continue;
+    }
+    const reachable = new Set([...kept].filter(referencedByPage));
+    for (let changed = true; changed; ) {
+      changed = false;
+      for (const index of [...reachable]) for (const dependency of dependencies(units[index])) {
+        if (kept.has(dependency) && !reachable.has(dependency)) {
+          reachable.add(dependency);
+          changed = true;
+        }
+      }
+    }
+    const mutated = [...reachable].find((index) => units.some((unit) => unit.assigned.some((name) => units[index].names.includes(name))));
+    if (mutated !== void 0) {
+      for (const rootIndex of [...active]) {
+        if (closureOf(rootIndex).has(mutated)) {
+          block(rootIndex, `\`${units[mutated].names[0]}\` is mutable state that page code also uses, so a copy in the client module would diverge`);
+        }
+      }
+      continue;
+    }
+    const movedNames = [...moved].flatMap((index) => units[index].names);
+    const registryNames = movedNames.filter((name) => body.mdastTags.has(name));
+    const importNames = movedNames.filter((name) => pageRefs.some((ref) => ref.name === name));
+    const moduleMembers = [...inModule].sort((a, b) => a - b);
+    const moduleNames = new Set(moduleMembers.flatMap((index) => units[index].names));
+    const usedImports = [];
+    const usedHelpers = [];
+    for (const index of moduleMembers) {
+      for (const { name } of units[index].refs) {
+        const statement = importByLocal.get(name);
+        if (statement && !usedImports.includes(statement)) usedImports.push(statement);
+        const helper = helperByName.get(name);
+        if (helper && !usedHelpers.includes(helper)) usedHelpers.push(helper);
+      }
+    }
+    for (const statement of usedImports) for (const local of importLocals(statement)) moduleNames.add(local);
+    for (const helper of usedHelpers) for (const name of helperNames(helper)) moduleNames.add(name);
+    const pageReferences = new Set(pageRefs.map((ref) => ref.name));
+    for (const tag of body.mdastTags) pageReferences.add(tag);
+    return {
+      blocked,
+      moved: [...moved].sort((a, b) => a - b),
+      copied: [...kept].sort((a, b) => a - b),
+      movedNames,
+      moduleImports: usedImports,
+      moduleHelpers: usedHelpers,
+      registryNames: [...new Set(registryNames)],
+      pageImportNames: [...new Set(importNames)],
+      moduleNames,
+      pageReferences
+    };
+  }
+  return { blocked, moved: [], copied: [], movedNames: [], moduleImports: [], moduleHelpers: [], registryNames: [], pageImportNames: [], moduleNames: /* @__PURE__ */ new Set(), pageReferences: /* @__PURE__ */ new Set() };
+}
+function unboundTags(moduleSource, boundNames) {
+  const sf = parse(moduleSource);
+  const tags = /* @__PURE__ */ new Set();
+  for (const statement of sf.statements) {
+    if (ts.isImportDeclaration(statement)) continue;
+    for (const ref of collectRefs(statement).refs) {
+      if ((ref.kind === "tag" || ref.kind === "member") && /^[A-Z]/.test(ref.name) && !boundNames.has(ref.name)) tags.add(ref.name);
+    }
+  }
+  return [...tags].sort();
+}
+
 // src/components.ts
 function normalizeIndentedFences(content) {
   const lines = content.split("\n");
@@ -1307,23 +1957,23 @@ function normalizeIndentedFences(content) {
 }
 function staticServerHelper(path, imported, local) {
   if (imported === "default") return null;
-  const parsed = ts.createSourceFile(path, readFileSync(path, "utf8"), ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const parsed = ts2.createSourceFile(path, readFileSync(path, "utf8"), ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
   const isLiteral = (node) => {
-    if (ts.isParenthesizedExpression(node)) return isLiteral(node.expression);
-    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) || ts.isNumericLiteral(node)) return true;
-    if ([ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword, ts.SyntaxKind.NullKeyword].includes(node.kind)) return true;
-    if (ts.isPrefixUnaryExpression(node)) return [ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken].includes(node.operator) && ts.isNumericLiteral(node.operand);
-    if (ts.isArrayLiteralExpression(node)) return node.elements.every((element) => ts.isExpression(element) && isLiteral(element));
-    if (ts.isObjectLiteralExpression(node)) return node.properties.every((property) => ts.isPropertyAssignment(property) && (ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) || ts.isNumericLiteral(property.name)) && isLiteral(property.initializer));
+    if (ts2.isParenthesizedExpression(node)) return isLiteral(node.expression);
+    if (ts2.isStringLiteral(node) || ts2.isNoSubstitutionTemplateLiteral(node) || ts2.isNumericLiteral(node)) return true;
+    if ([ts2.SyntaxKind.TrueKeyword, ts2.SyntaxKind.FalseKeyword, ts2.SyntaxKind.NullKeyword].includes(node.kind)) return true;
+    if (ts2.isPrefixUnaryExpression(node)) return [ts2.SyntaxKind.PlusToken, ts2.SyntaxKind.MinusToken].includes(node.operator) && ts2.isNumericLiteral(node.operand);
+    if (ts2.isArrayLiteralExpression(node)) return node.elements.every((element) => ts2.isExpression(element) && isLiteral(element));
+    if (ts2.isObjectLiteralExpression(node)) return node.properties.every((property) => ts2.isPropertyAssignment(property) && (ts2.isIdentifier(property.name) || ts2.isStringLiteral(property.name) || ts2.isNumericLiteral(property.name)) && isLiteral(property.initializer));
     return false;
   };
   for (const statement of parsed.statements) {
-    if (!ts.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    if (!ts2.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword)) continue;
     for (const declaration of statement.declarationList.declarations) {
-      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== imported || !declaration.initializer || !ts.isArrowFunction(declaration.initializer)) continue;
+      if (!ts2.isIdentifier(declaration.name) || declaration.name.text !== imported || !declaration.initializer || !ts2.isArrowFunction(declaration.initializer)) continue;
       const arrow = declaration.initializer;
       if (arrow.parameters.length > 0) continue;
-      const result = ts.isBlock(arrow.body) ? arrow.body.statements.length === 1 && ts.isReturnStatement(arrow.body.statements[0]) ? arrow.body.statements[0].expression : void 0 : arrow.body;
+      const result = ts2.isBlock(arrow.body) ? arrow.body.statements.length === 1 && ts2.isReturnStatement(arrow.body.statements[0]) ? arrow.body.statements[0].expression : void 0 : arrow.body;
       if (result && isLiteral(result)) return `export const ${local} = () => (${result.getText(parsed)});`;
     }
   }
@@ -1547,12 +2197,12 @@ function wrapImpureCssModuleSelectors(css) {
   return root.toString();
 }
 function sourceFile(source, filename) {
-  return ts.createSourceFile(
+  return ts2.createSourceFile(
     filename,
     source,
-    ts.ScriptTarget.Latest,
+    ts2.ScriptTarget.Latest,
     true,
-    /\.[cm]?ts$/.test(filename) ? ts.ScriptKind.TS : ts.ScriptKind.TSX
+    /\.[cm]?ts$/.test(filename) ? ts2.ScriptKind.TS : ts2.ScriptKind.TSX
   );
 }
 function walk(node, visitor) {
@@ -1563,24 +2213,24 @@ function implicitReactImports(source) {
   const bindings = /* @__PURE__ */ new Set();
   const references = /* @__PURE__ */ new Set();
   function bind(name) {
-    if (ts.isIdentifier(name)) bindings.add(name.text);
-    else for (const element of name.elements) if (ts.isBindingElement(element)) bind(element.name);
+    if (ts2.isIdentifier(name)) bindings.add(name.text);
+    else for (const element of name.elements) if (ts2.isBindingElement(element)) bind(element.name);
   }
   for (const statement of source.statements) {
-    if (ts.isImportDeclaration(statement) && statement.importClause) {
+    if (ts2.isImportDeclaration(statement) && statement.importClause) {
       const clause = statement.importClause;
       if (clause.name) bindings.add(clause.name.text);
       if (clause.namedBindings) {
-        if (ts.isNamespaceImport(clause.namedBindings)) bindings.add(clause.namedBindings.name.text);
+        if (ts2.isNamespaceImport(clause.namedBindings)) bindings.add(clause.namedBindings.name.text);
         else for (const element of clause.namedBindings.elements) bindings.add(element.name.text);
       }
     }
-    if (ts.isVariableStatement(statement)) for (const declaration of statement.declarationList.declarations) bind(declaration.name);
-    if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) bindings.add(statement.name.text);
+    if (ts2.isVariableStatement(statement)) for (const declaration of statement.declarationList.declarations) bind(declaration.name);
+    if ((ts2.isFunctionDeclaration(statement) || ts2.isClassDeclaration(statement)) && statement.name) bindings.add(statement.name.text);
   }
   function visit(node) {
-    if (ts.isIdentifier(node) && !(ts.isPropertyAccessExpression(node.parent) && node.parent.name === node) && !(ts.isPropertyAssignment(node.parent) && node.parent.name === node)) references.add(node.text);
-    ts.forEachChild(node, visit);
+    if (ts2.isIdentifier(node) && !(ts2.isPropertyAccessExpression(node.parent) && node.parent.name === node) && !(ts2.isPropertyAssignment(node.parent) && node.parent.name === node)) references.add(node.text);
+    ts2.forEachChild(node, visit);
   }
   visit(source);
   const hooks = [...REACT_GLOBALS].filter((name) => references.has(name) && !bindings.has(name)).sort();
@@ -1596,13 +2246,22 @@ function implicitReactImports(source) {
     usesMintlifyComponents ? mintlifyComponentsShim() : ""
   ].filter(Boolean).join("\n");
 }
+function resolveInlineBuiltinReferences(source, moduleNames) {
+  const unresolved = unboundTags(source, moduleNames);
+  if (unresolved.length === 0) return source;
+  return [
+    "import { builtinMdxComponents } from '@/components/mdx/builtin-components';",
+    `const { ${unresolved.join(", ")} } = builtinMdxComponents;`,
+    source
+  ].join("\n");
+}
 function imports(statement) {
-  if (!ts.isStringLiteral(statement.moduleSpecifier) || !statement.importClause) return [];
+  if (!ts2.isStringLiteral(statement.moduleSpecifier) || !statement.importClause) return [];
   const clause = statement.importClause;
   if (clause.isTypeOnly) return [];
   const source = statement.moduleSpecifier.text;
   const bindings = clause.name ? [{ local: clause.name.text, imported: "default", source }] : [];
-  if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+  if (clause.namedBindings && ts2.isNamedImports(clause.namedBindings)) {
     for (const element of clause.namedBindings.elements) {
       if (!element.isTypeOnly) bindings.push({ local: element.name.text, imported: element.propertyName?.text ?? element.name.text, source });
     }
@@ -1618,6 +2277,7 @@ var CLIENT_BUILTIN_COMPONENT_TAGS = /* @__PURE__ */ new Set([
   "ParamField",
   "Expandable",
   "CodeGroup",
+  "CodeBlock",
   "Badge",
   "Tooltip",
   "Tabs",
@@ -1627,6 +2287,7 @@ var CLIENT_BUILTIN_COMPONENT_TAGS = /* @__PURE__ */ new Set([
   "InlineRequestExample",
   "InlineResponseExample",
   "Tree",
+  "FileTree",
   "Folder",
   "File",
   "Mermaid",
@@ -1648,8 +2309,8 @@ var CLIENT_BUILTIN_COMPONENT_TAGS = /* @__PURE__ */ new Set([
 function isConfirmedClientBoundaryTag(name) {
   return EXTRACTED_CLIENT_COMPONENT_TAG.test(name) || CLIENT_BUILTIN_COMPONENT_TAGS.has(name);
 }
-function functionValuedAttribute(node, declaredNames) {
-  const isFunctionValue = (value) => declaredNames.has(value.trim()) || isFunctionInitializer(value.trim(), 0);
+function functionValuedAttribute(node, declaredNames2) {
+  const isFunctionValue = (value) => declaredNames2.has(value.trim()) || isFunctionInitializer(value.trim(), 0);
   for (const attribute of node.attributes ?? []) {
     const raw = attribute.value;
     const value = raw && typeof raw === "object" ? raw.value : void 0;
@@ -1662,21 +2323,21 @@ function functionValuedAttribute(node, declaredNames) {
   }
   return void 0;
 }
-function propsTargetExtractedClientComponent(body, declaredNames) {
+function propsTargetExtractedClientComponent(body, declaredNames2) {
   const tree = parser.parse(body);
   let found = false;
   walk(tree, (node) => {
     if (found || !node.name || !isConfirmedClientBoundaryTag(node.name)) return;
-    if (functionValuedAttribute(node, declaredNames) !== void 0) found = true;
+    if (functionValuedAttribute(node, declaredNames2) !== void 0) found = true;
   });
   return found;
 }
-function hasAnyFunctionValuedProp(body, declaredNames) {
+function hasAnyFunctionValuedProp(body, declaredNames2) {
   const tree = parser.parse(body);
   let found = false;
   walk(tree, (node) => {
     if (found || !node.name) return;
-    if (functionValuedAttribute(node, declaredNames) !== void 0) found = true;
+    if (functionValuedAttribute(node, declaredNames2) !== void 0) found = true;
   });
   return found;
 }
@@ -1684,13 +2345,13 @@ function declarationsReferenceBrowserGlobal(body) {
   const tree = parser.parse(body);
   let found = false;
   function inspect(node) {
-    if (ts.isIdentifier(node) && (node.text === "document" || node.text === "window")) found = true;
-    ts.forEachChild(node, inspect);
+    if (ts2.isIdentifier(node) && (node.text === "document" || node.text === "window")) found = true;
+    ts2.forEachChild(node, inspect);
   }
   for (const node of tree.children ?? []) {
     if (found || node.type !== "mdxjsEsm" || node.value === void 0) continue;
     for (const statement of sourceFile(node.value, "inline.tsx").statements) {
-      if (ts.isVariableStatement(statement) || ts.isFunctionDeclaration(statement)) inspect(statement);
+      if (ts2.isVariableStatement(statement) || ts2.isFunctionDeclaration(statement)) inspect(statement);
     }
   }
   return found;
@@ -1794,14 +2455,14 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
         return;
       }
       const text = content.toString("utf8");
-      const syntax = ts.transpileModule(text, {
+      const syntax = ts2.transpileModule(text, {
         fileName: path,
         reportDiagnostics: true,
-        compilerOptions: { jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.ESNext }
+        compilerOptions: { jsx: ts2.JsxEmit.Preserve, target: ts2.ScriptTarget.ESNext, module: ts2.ModuleKind.ESNext }
       });
-      if (syntax.diagnostics?.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) throw new Error("component source contains unsupported JavaScript or TypeScript syntax");
+      if (syntax.diagnostics?.some((diagnostic) => diagnostic.category === ts2.DiagnosticCategory.Error)) throw new Error("component source contains unsupported JavaScript or TypeScript syntax");
       const ast = sourceFile(text, path);
-      if (ast.statements.some((statement) => ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression) && statement.expression.text === "use server")) throw new Error("server-only component modules require manual migration");
+      if (ast.statements.some((statement) => ts2.isExpressionStatement(statement) && ts2.isStringLiteral(statement.expression) && statement.expression.text === "use server")) throw new Error("server-only component modules require manual migration");
       const edits = [];
       function dependency(literal, importDeclaration) {
         const specifier = literal.text;
@@ -1811,10 +2472,10 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           const localName = importDeclaration?.importClause?.name?.text;
           if (localName) {
             let renameToProp2 = function(node) {
-              if (ts.isJsxAttribute(node) && node.name.getText(ast) === "to" && ts.isJsxOpeningLikeElement(node.parent.parent) && node.parent.parent.tagName.getText(ast) === localName) {
+              if (ts2.isJsxAttribute(node) && node.name.getText(ast) === "to" && ts2.isJsxOpeningLikeElement(node.parent.parent) && node.parent.parent.tagName.getText(ast) === localName) {
                 edits.push({ start: node.name.getStart(ast), end: node.name.end, value: "href" });
               }
-              ts.forEachChild(node, renameToProp2);
+              ts2.forEachChild(node, renameToProp2);
             };
             var renameToProp = renameToProp2;
             renameToProp2(ast);
@@ -1837,15 +2498,15 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
         edits.push({ start: literal.getStart(ast), end: literal.end, value: JSON.stringify(portableSpecifier(nextPath.startsWith(".") ? nextPath : `./${nextPath}`)) });
       }
       function inspect(node) {
-        if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
-          dependency(node.moduleSpecifier, ts.isImportDeclaration(node) ? node : void 0);
+        if ((ts2.isImportDeclaration(node) || ts2.isExportDeclaration(node)) && node.moduleSpecifier && ts2.isStringLiteral(node.moduleSpecifier)) {
+          dependency(node.moduleSpecifier, ts2.isImportDeclaration(node) ? node : void 0);
         }
-        if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require")) {
+        if (ts2.isCallExpression(node) && (node.expression.kind === ts2.SyntaxKind.ImportKeyword || ts2.isIdentifier(node.expression) && node.expression.text === "require")) {
           const argument = node.arguments[0];
-          if (node.arguments.length !== 1 || !argument || !ts.isStringLiteralLike(argument)) throw new Error("computed component imports require manual migration");
+          if (node.arguments.length !== 1 || !argument || !ts2.isStringLiteralLike(argument)) throw new Error("computed component imports require manual migration");
           dependency(argument);
         }
-        ts.forEachChild(node, inspect);
+        ts2.forEachChild(node, inspect);
       }
       inspect(ast);
       const replaced = applyReplacements(text, edits);
@@ -1923,15 +2584,15 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
     function hasExpressionReference(names, options = {}) {
       let found = false;
       function inspect2(node) {
-        if (ts.isIdentifier(node) && names.has(node.text)) found = true;
-        ts.forEachChild(node, inspect2);
+        if (ts2.isIdentifier(node) && names.has(node.text)) found = true;
+        ts2.forEachChild(node, inspect2);
       }
       walk(tree, (node) => {
         if (options.excludedNodes?.some((excluded) => node.position?.start.offset !== void 0 && node.position.end.offset !== void 0 && node.position.start.offset >= excluded.position.start.offset && node.position.end.offset <= excluded.position.end.offset)) return;
         if (node.name && [...names].some((name) => node.name.startsWith(`${name}.`) || options.includeDirectTags && node.name === name)) found = true;
         if (options.includeDeclarations !== false && node.type === "mdxjsEsm" && node.value) {
           for (const statement of sourceFile(node.value, "expression.tsx").statements) {
-            if (!ts.isImportDeclaration(statement)) inspect2(statement);
+            if (!ts2.isImportDeclaration(statement)) inspect2(statement);
           }
         }
         const expressions = [
@@ -1960,13 +2621,13 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
       if (node.value === void 0 || node.position?.start.offset === void 0) continue;
       const ast = sourceFile(node.value, "inline.tsx");
       for (const statement of ast.statements) {
-        if (!ts.isImportDeclaration(statement)) {
+        if (!ts2.isImportDeclaration(statement)) {
           let inspect2 = function(node2) {
-            if (ts.isCallExpression(node2) && (node2.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node2.expression) && node2.expression.text === "require")) unsupportedDependency = true;
-            ts.forEachChild(node2, inspect2);
+            if (ts2.isCallExpression(node2) && (node2.expression.kind === ts2.SyntaxKind.ImportKeyword || ts2.isIdentifier(node2.expression) && node2.expression.text === "require")) unsupportedDependency = true;
+            ts2.forEachChild(node2, inspect2);
           };
           var inspect = inspect2;
-          let unsupportedDependency = ts.isExportDeclaration(statement) && !!statement.moduleSpecifier;
+          let unsupportedDependency = ts2.isExportDeclaration(statement) && !!statement.moduleSpecifier;
           inspect2(statement);
           if (unsupportedDependency) {
             hasUnsupportedImports = true;
@@ -1980,7 +2641,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           continue;
         }
         const bindings = imports(statement);
-        const rawSpecifier = ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : "";
+        const rawSpecifier = ts2.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : "";
         const specifier = rawSpecifier.startsWith("@site/") ? `/${rawSpecifier.slice("@site/".length)}` : rawSpecifier;
         if (isScaffoldProvidedImport(specifier)) {
           if (specifier === "react" && bindings.length > 0 && bindings.every((binding) => REACT_GLOBALS.has(binding.imported)) && !hasExpressionReference(new Set(bindings.map((binding) => binding.local)))) {
@@ -2043,7 +2704,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           } catch {
           }
         }
-        if (!bindings.length || statement.importClause?.namedBindings && ts.isNamespaceImport(statement.importClause.namedBindings)) {
+        if (!bindings.length || statement.importClause?.namedBindings && ts2.isNamespaceImport(statement.importClause.namedBindings)) {
           warn("Namespace or side-effect MDX imports require manual registration; the import was preserved.", currentFile);
           hasUnsupportedImports = true;
           continue;
@@ -2116,10 +2777,60 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
         }
       }
     }
+    const refusedInlineComponents = /* @__PURE__ */ new Set();
+    {
+      const plan = planInlineExtraction({
+        declarations,
+        tree,
+        copyableImports: [...moduleImports, ...realPageImports],
+        helperDeclarations: serverPageDeclarations,
+        unavailableImports: unsupportedImports,
+        reactGlobals: REACT_GLOBALS
+      });
+      for (const { name, reason } of plan.blocked) {
+        refusedInlineComponents.add(name);
+        warn(`Inline component "${name}" calls a React hook but was left in the page: ${reason}. Move it and everything it uses into a client component manually.`, currentFile);
+      }
+      const moduleSource = plan.moved.length === 0 ? "" : [
+        ...plan.moduleImports,
+        ...plan.moduleHelpers,
+        ...[...plan.moved, ...plan.copied].sort((a, b) => a - b).map((index) => declarations[index].source)
+      ].join("\n\n");
+      if (plan.moved.length > 0 && (copied.size >= MAX_COMPONENT_FILES || Buffer.byteLength(moduleSource) > MAX_FILE_BYTES || copiedBytes + Buffer.byteLength(moduleSource) > MAX_COMPONENT_BYTES)) {
+        warn(`Inline component "${plan.movedNames[0]}" exceeded the component migration budget; source was preserved.`, currentFile);
+      } else if (plan.moved.length > 0) {
+        const path = `${destinationRoot}/inline-${hash(`${relative2(root, currentFile)}:components`)}.jsx`;
+        const inlineSource = `${resolveInlineBuiltinReferences(moduleSource, plan.moduleNames)}
+`;
+        copied.set(path, { path, content: `'use client';
+${implicitReactImports(sourceFile(inlineSource, "inline.jsx"))}
+${inlineSource}` });
+        copiedBytes += Buffer.byteLength(inlineSource);
+        const movedIndexes = new Set(plan.moved);
+        for (const index of plan.moved) edits.push({ start: declarations[index].start, end: declarations[index].end, value: "" });
+        for (const name of plan.registryNames) {
+          const registered = register(path, name);
+          aliases.set(name, registered);
+          moduleImports.push(`import { ${name} } from ${JSON.stringify(portableSpecifier(`./${relative2(destinationRoot, path).replace(/\\/g, "/")}`))};`);
+        }
+        if (plan.pageImportNames.length > 0) {
+          realPageImports.push(`import { ${plan.pageImportNames.join(", ")} } from ${JSON.stringify(portableSpecifier(`@/${path.replace(/^src\//, "").replace(/\\/g, "/")}`))};`);
+        }
+        for (const entry of [...sharedImportEdits]) {
+          const locals = [...sourceFile(content.slice(entry.start, entry.end), "shared.tsx").statements].flatMap((statement) => ts2.isImportDeclaration(statement) ? imports(statement).map((binding) => binding.local) : []);
+          if (locals.length === 0 || locals.some((local) => plan.pageReferences.has(local))) continue;
+          edits.push(entry);
+          sharedImportEdits.splice(sharedImportEdits.indexOf(entry), 1);
+        }
+        for (let index = declarations.length - 1; index >= 0; index -= 1) {
+          if (movedIndexes.has(index)) declarations.splice(index, 1);
+        }
+      }
+    }
     if (droppedMdxDataBindings.size > 0) {
       for (const node of esmNodes) {
         let stripDroppedSpreads2 = function(inner) {
-          if (ts.isSpreadElement(inner) && ts.isIdentifier(inner.expression) && droppedMdxDataBindings.has(inner.expression.text)) {
+          if (ts2.isSpreadElement(inner) && ts2.isIdentifier(inner.expression) && droppedMdxDataBindings.has(inner.expression.text)) {
             const start = nodeStart + inner.getStart(ast);
             let end = nodeStart + inner.end;
             const following = nodeText.slice(inner.end).match(/^\s*,/);
@@ -2127,7 +2838,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
             edits.push({ start, end, value: "" });
             return;
           }
-          ts.forEachChild(inner, stripDroppedSpreads2);
+          ts2.forEachChild(inner, stripDroppedSpreads2);
         };
         var stripDroppedSpreads = stripDroppedSpreads2;
         if (node.value === void 0 || node.position?.start.offset === void 0) continue;
@@ -2161,7 +2872,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
       }
     });
     const statefulDeclarationNames = new Set(
-      declarations.filter(({ source }) => /\bon[A-Z]\w*\s*=|\buse[A-Z]\w*\s*\(/.test(source)).map(({ source }) => source.match(/^export const (\w+)/)?.[1]).filter((name) => !!name)
+      declarations.filter(({ source }) => /\bon[A-Z]\w*\s*=|\buse[A-Z]\w*\s*\(/.test(source)).map(({ source }) => source.match(/^export const (\w+)/)?.[1]).filter((name) => !!name && !refusedInlineComponents.has(name))
     );
     const extracted = [];
     for (const candidate of tree.children ?? []) {
@@ -2180,12 +2891,12 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
         continue;
       }
       const jsx = content.slice(node.position.start.offset, node.position.end.offset);
-      const result = ts.transpileModule(`export default function Inline() { return (${jsx}); }`, {
+      const result = ts2.transpileModule(`export default function Inline() { return (${jsx}); }`, {
         fileName: "inline.jsx",
-        compilerOptions: { jsx: ts.JsxEmit.Preserve },
+        compilerOptions: { jsx: ts2.JsxEmit.Preserve },
         reportDiagnostics: true
       });
-      if (result.diagnostics?.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error)) {
+      if (result.diagnostics?.some((diagnostic) => diagnostic.category === ts2.DiagnosticCategory.Error)) {
         warn("Interactive MDX could not be safely extracted as JSX; source was preserved.", currentFile);
         continue;
       }
@@ -2193,15 +2904,15 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
     }
     if (extracted.length && declarations.length) {
       let bind2 = function(name) {
-        if (ts.isIdentifier(name)) declared.add(name.text);
-        else for (const element of name.elements) if (ts.isBindingElement(element)) bind2(element.name);
+        if (ts2.isIdentifier(name)) declared.add(name.text);
+        else for (const element of name.elements) if (ts2.isBindingElement(element)) bind2(element.name);
       };
       var bind = bind2;
       const declared = /* @__PURE__ */ new Set();
       for (const declaration of declarations) {
         for (const statement of sourceFile(declaration.source, "declaration.tsx").statements) {
-          if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) declared.add(statement.name.text);
-          if (ts.isVariableStatement(statement)) for (const variable of statement.declarationList.declarations) bind2(variable.name);
+          if ((ts2.isFunctionDeclaration(statement) || ts2.isClassDeclaration(statement)) && statement.name) declared.add(statement.name.text);
+          if (ts2.isVariableStatement(statement)) for (const variable of statement.declarationList.declarations) bind2(variable.name);
         }
       }
       const hasSharedDeclarations = hasExpressionReference(declared, {
@@ -2362,22 +3073,22 @@ function mergeComponentRegistry(existing, incoming) {
   const name = `MigratedRegistry${fingerprint}`;
   const registryPath = `./migrated-components-${fingerprint}`;
   const source = sourceFile(existing, "custom-components.tsx");
-  const alreadyImported = source.statements.some((statement) => ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === registryPath);
+  const alreadyImported = source.statements.some((statement) => ts2.isImportDeclaration(statement) && ts2.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === registryPath);
   let initializer;
   for (const statement of source.statements) {
-    if (!ts.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
+    if (!ts2.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword)) continue;
     for (const declaration of statement.declarationList.declarations) {
-      if (ts.isIdentifier(declaration.name) && declaration.name.text === "customComponents") initializer = declaration.initializer;
+      if (ts2.isIdentifier(declaration.name) && declaration.name.text === "customComponents") initializer = declaration.initializer;
     }
   }
-  while (initializer && (ts.isAsExpression(initializer) || ts.isSatisfiesExpression(initializer) || ts.isParenthesizedExpression(initializer))) initializer = initializer.expression;
-  if (!initializer || !ts.isObjectLiteralExpression(initializer)) {
+  while (initializer && (ts2.isAsExpression(initializer) || ts2.isSatisfiesExpression(initializer) || ts2.isParenthesizedExpression(initializer))) initializer = initializer.expression;
+  if (!initializer || !ts2.isObjectLiteralExpression(initializer)) {
     throw new Error("Cannot safely merge src/mdx/custom-components.tsx: export customComponents as an object literal before importing components. The existing registry was preserved.");
   }
   const content = alreadyImported ? existing : applyReplacements(existing, [
     {
-      start: source.statements.filter((statement) => ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
-      end: source.statements.filter((statement) => ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
+      start: source.statements.filter((statement) => ts2.isExpressionStatement(statement) && ts2.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
+      end: source.statements.filter((statement) => ts2.isExpressionStatement(statement) && ts2.isStringLiteral(statement.expression)).at(-1)?.end ?? 0,
       value: `
 import { customComponents as ${name} } from ${JSON.stringify(registryPath)}
 `
@@ -2524,7 +3235,7 @@ function projectedHref(value) {
   return href;
 }
 function labelFor(value, fallback) {
-  for (const key of ["tab", "group", "anchor", "product", "dropdown", "version", "menu", "label", "name", "title"]) {
+  for (const key of ["tab", "group", "anchor", "product", "dropdown", "version", "menu", "item", "label", "name", "title"]) {
     if (typeof value[key] === "string" && value[key]) return String(value[key]);
   }
   return fallback;
@@ -2596,29 +3307,40 @@ function readMintlifyConfig(repositoryRoot) {
   const raw = readMintlifyJson(configPath, repositoryRoot);
   return resolveJsonReferences(raw, configPath, repositoryRoot, /* @__PURE__ */ new Set());
 }
+function specSource(value) {
+  const source = typeof value === "string" ? value : objectValue(value)?.source;
+  return typeof source === "string" && source.trim() ? source.trim() : void 0;
+}
+var hasNavigationChildren = (node) => ["groups", "pages"].some((key) => Array.isArray(node[key]) && node[key].length > 0);
 function mintlifyNavigationApiReferences(config) {
   const navigation = objectValue(config.navigation) ?? config;
   const references = [];
   const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus", "languages"];
   const nestedKeys = ["groups", "pages"];
-  function visit(rawNode, tabLabel) {
-    const node = withFlattenedProductGroups(rawNode);
+  function collect(node, tabLabel, sibling) {
     for (const kind of ["openapi", "asyncapi"]) {
-      const value = node[kind];
-      if (typeof value === "string" && value.trim()) {
-        references.push({ value: value.trim(), kind, tabLabel });
-        continue;
-      }
-      const object = objectValue(value);
-      if (object && typeof object.source === "string" && object.source.trim()) {
+      const value = specSource(node[kind]);
+      const directory = objectValue(node[kind])?.directory;
+      if (value) {
         references.push({
-          value: object.source.trim(),
+          value,
           kind,
           tabLabel,
-          ...typeof object.directory === "string" && object.directory.trim() ? { directory: object.directory.trim() } : {}
+          ...sibling,
+          ...typeof directory === "string" && directory.trim() ? { directory: directory.trim() } : {}
         });
       }
     }
+  }
+  const siblingSources = /* @__PURE__ */ new Map();
+  function uniqueSiblingLabel(label, source) {
+    let candidate = label;
+    for (let n = 2; siblingSources.has(candidate) && siblingSources.get(candidate) !== source; n++) candidate = `${label} (${n})`;
+    siblingSources.set(candidate, source);
+    return candidate;
+  }
+  function visitChildren(rawNode, tabLabel) {
+    const node = withFlattenedProductGroups(rawNode);
     for (const key of containerKeys) {
       const entries = node[key];
       if (!Array.isArray(entries)) continue;
@@ -2637,10 +3359,45 @@ function mintlifyNavigationApiReferences(config) {
         if (object) visit(object, tabLabel);
       }
     }
+    if (Array.isArray(node.menu)) {
+      const tab = tabLabel ?? "Documentation";
+      const items = node.menu.flatMap((entry) => {
+        const object = objectValue(entry);
+        return object ? [object] : [];
+      });
+      const apiItems = items.filter((item) => specSource(item.openapi) || specSource(item.asyncapi));
+      const soleContent = apiItems.length === 1 && !hasNavigationChildren(node) && !items.some(hasNavigationChildren);
+      items.forEach((item, index) => {
+        if (soleContent && apiItems[0] === item) collect(item, tab);
+        else if (apiItems.includes(item)) {
+          const label = uniqueSiblingLabel(
+            `${tab}: ${labelFor(item, `Menu item ${index + 1}`)}`,
+            `${specSource(item.openapi) ?? ""}|${specSource(item.asyncapi) ?? ""}`
+          );
+          const icon = iconName(item.icon);
+          collect(item, label, { parentTab: tab, ...icon ? { icon } : {}, ...item.hidden === true ? { hidden: true } : {} });
+        }
+        visitChildren(item, tabLabel);
+      });
+    }
+  }
+  function visit(node, tabLabel) {
+    collect(node, tabLabel);
+    visitChildren(node, tabLabel);
   }
   visit(navigation, void 0);
   return references;
 }
+function insertApiTab(tabs, tab, parentTab) {
+  let index = -1;
+  if (parentTab) {
+    tabs.forEach((candidate, position) => {
+      if (candidate.tab === parentTab || candidate.tab.startsWith(`${parentTab}: `)) index = position;
+    });
+  }
+  tabs.splice(index === -1 ? tabs.length : index + 1, 0, tab);
+  return tabs;
+}
 function normalizePageRef(value, pathPrefix = "") {
   if (/^(?:https?:)?\/\//i.test(value) || value.startsWith("#")) return null;
   let ref = localReference(value).split("?", 1)[0].replace(/^\/+/, "");
@@ -2726,6 +3483,65 @@ function convertPage(value, context) {
   }
   return null;
 }
+var KNOWN_NAVIGATION_KEYS = /* @__PURE__ */ new Set([
+  "tabs",
+  "anchors",
+  "products",
+  "dropdowns",
+  "versions",
+  "menus",
+  "languages",
+  "productGroups",
+  "groups",
+  "pages",
+  "menu",
+  "global"
+]);
+function convertMenuItems(items, context) {
+  return items.flatMap((value, index) => {
+    const item = objectValue(value);
+    if (!item) return [];
+    const label = labelFor(item, `Menu item ${index + 1}`);
+    if (typeof item.description === "string" && item.description.trim()) {
+      warnOnce(
+        context,
+        `menu-item-description:${label}`,
+        `Mintlify menu item "${label}" has a description, which Thally groups cannot display; it was omitted.`
+      );
+    }
+    const hasUnsourcedSpec = Boolean(item.openapi || item.asyncapi) && !specSource(item.openapi) && !specSource(item.asyncapi);
+    if (hasUnsourcedSpec) {
+      warnOnce(
+        context,
+        `menu-item-spec:${label}`,
+        `Mintlify menu item "${label}" has an openapi/asyncapi value without a "source", so its API reference was not migrated.`
+      );
+    }
+    const children = convertNavigationValues([
+      ...Array.isArray(item.groups) ? item.groups : [],
+      ...Array.isArray(item.pages) ? item.pages : []
+    ], context);
+    if (typeof item.href === "string" && item.href) {
+      warnOnce(
+        context,
+        `menu-item-href:${label}`,
+        `Mintlify menu item "${label}" links to ${item.href}, which cannot be represented as a Thally group; the link was omitted.`
+      );
+    }
+    if (children.length === 0) {
+      if (!specSource(item.openapi) && !specSource(item.asyncapi) && !hasUnsourcedSpec) {
+        warnOnce(context, `menu-item-empty:${label}`, `Mintlify menu item "${label}" has no projectable pages and was omitted.`);
+      }
+      return [];
+    }
+    return [{
+      group: label,
+      ...iconName(item.icon) ? { icon: iconName(item.icon) } : {},
+      ...item.hidden === true ? { hidden: true } : {},
+      pages: children
+    }];
+  });
+}
 function convertNavigationValues(values, context) {
   return values.flatMap((value) => {
     const page = convertPage(value, context);
@@ -2737,6 +3553,13 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
   if (!rawContainer) return [];
   const container = withFlattenedProductGroups(rawContainer);
   const containerKeys = ["tabs", "anchors", "products", "dropdowns", "versions", "menus"];
+  for (const key of Object.keys(container)) {
+    if (KNOWN_NAVIGATION_KEYS.has(key)) continue;
+    const entries = container[key];
+    if (Array.isArray(entries) && entries.some((entry) => objectValue(entry))) {
+      warnOnce(context, `unknown-container:${key}`, `Mintlify navigation key "${key}" is not supported and its contents were not projected.`);
+    }
+  }
   for (const key of containerKeys) {
     if (!Array.isArray(container[key])) continue;
     const entries = [...container[key]];
@@ -2748,7 +3571,7 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
       if (!object) return [];
       const tab = labelFor(object, `${fallbackTab} ${index + 1}`);
       const href = projectedHref(object.href);
-      const hasNestedContainers = containerKeys.some((containerKey) => Array.isArray(object[containerKey]));
+      const hasNestedContainers = [...containerKeys, "menu"].some((containerKey) => Array.isArray(object[containerKey]));
       if (href && !object.pages && !object.groups && !hasNestedContainers) {
         return [{
           tab,
@@ -2780,6 +3603,11 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
       return [];
     });
     if (tabs.length > 0) {
+      for (const sibling of ["groups", "pages", "menu"]) {
+        if (Array.isArray(container[sibling]) && container[sibling].length > 0) {
+          warnOnce(context, `container-sibling:${key}:${sibling}`, `Mintlify "${sibling}" next to "${key}" was not projected; only the "${key}" containers were kept.`);
+        }
+      }
       if (depth === 0 && trace) trace.rootContainerKind = key;
       return tabs;
     }
@@ -2792,7 +3620,10 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
     ...rawGroups,
     ...rawPages
   ];
-  const children = convertNavigationValues(values, context);
+  const children = [
+    ...convertNavigationValues(values, context),
+    ...Array.isArray(container.menu) ? convertMenuItems(container.menu, context) : []
+  ];
   return children.length > 0 ? [{
     tab: fallbackTab,
     ...hasRootNodes ? { pages: children } : { groups: children },
@@ -2842,7 +3673,7 @@ function projectedGlobalNavigationLinks(value) {
       const label = labelFor(item, "");
       if (label) links.push({ label, href });
     }
-    for (const key of ["tabs", "anchors", "dropdowns", "products", "versions", "languages", "menus"]) {
+    for (const key of ["tabs", "anchors", "dropdowns", "products", "versions", "languages", "menus", "menu"]) {
       if (Array.isArray(item[key])) visit(item[key]);
     }
   };
@@ -4676,6 +5507,10 @@ var MAX_PAGE_BYTES = 2e6;
 var MAX_ASSET_BYTES = 25e6;
 var MAX_TOTAL_ASSET_BYTES = 5e8;
 var GIT_LFS_POINTER_PREFIX = "version https://git-lfs.github.com/spec/v1";
+function listAssetPaths(paths) {
+  const shown = paths.slice(0, 5).join(", ");
+  return paths.length > 5 ? `${shown}, and ${paths.length - 5} more` : shown;
+}
 function isGitLfsPointer(content) {
   return content.length < 1024 && content.toString("utf8", 0, GIT_LFS_POINTER_PREFIX.length) === GIT_LFS_POINTER_PREFIX;
 }
@@ -5099,17 +5934,23 @@ function parseGitHubRepositoryUrl(rawUrl) {
 }
 var CLONE_RETRY_ATTEMPTS = 3;
 var CLONE_RETRY_DELAY_MS = 1e3;
-var DEFAULT_CLONE_TIMEOUT_MS = 10 * 6e4;
+var DEFAULT_CLONE_IDLE_TIMEOUT_MS = 2 * 6e4;
+var MAX_GIT_PROCESS_MS = 60 * 6e4;
+var HARD_TIMEOUT_REASON = `still running after ${MAX_GIT_PROCESS_MS / 6e4} minutes`;
+var GIT_EXIT_DRAIN_MS = 2e3;
 var RETRYABLE_CLONE_ERROR = /RPC failed|Recv failure|early EOF|curl \d+|Could not resolve host|Connection (?:reset|refused|timed out)|The remote end hung up|SSL[_ ]?(?:read|connect|write) error|timed out|network is unreachable/i;
 function delay(ms) {
   return new Promise((resolve3) => {
     setTimeout(resolve3, ms);
   });
 }
-function gitProcessTimeoutMs() {
+function gitIdleTimeoutMs() {
   const raw = process.env.THALLY_MIGRATE_CLONE_TIMEOUT_MS;
   const parsed = raw ? Number(raw) : NaN;
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_TIMEOUT_MS;
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_CLONE_IDLE_TIMEOUT_MS;
+}
+function gitErrorTail(stderr) {
+  return stderr.split(/[\r\n]+/).map((line) => line.trim()).filter((line) => line && !/^(?:remote: )?[A-Za-z][A-Za-z ]*:\s+\d+%/.test(line)).slice(-5).join("\n");
 }
 function runGit(args, options) {
   return new Promise((resolve3, reject) => {
@@ -5119,24 +5960,66 @@ function runGit(args, options) {
       env: { ...process.env, ...options.env }
     });
     let stderr = "";
-    let timedOut = false;
-    const timer = setTimeout(() => {
-      timedOut = true;
+    let timeoutReason = "";
+    let settled = false;
+    let exitCode;
+    let drainTimer;
+    const idleMs = gitIdleTimeoutMs();
+    const idleMessage = `no progress for ${idleMs < 1e3 ? `${idleMs}ms` : `${Math.round(idleMs / 1e3)}s`}`;
+    const clearTimers = () => {
+      clearTimeout(idleTimer);
+      clearTimeout(hardTimer);
+      clearTimeout(drainTimer);
+    };
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      child.stderr.destroy();
+      if (code === 0) resolve3();
+      else if (timeoutReason) {
+        const hint = timeoutReason === HARD_TIMEOUT_REASON ? "" : "; on a very slow link, raise THALLY_MIGRATE_CLONE_TIMEOUT_MS (milliseconds of allowed silence)";
+        reject(new Error(`${options.label}: timed out (${timeoutReason}) and was killed. Check your network connection and try again${hint}.`));
+      } else reject(new Error(`${options.label}: ${gitErrorTail(stderr) || `git exited ${code}`}`));
+    };
+    const kill = (reason) => {
+      if (exitCode !== void 0) {
+        finish(exitCode);
+        return;
+      }
+      timeoutReason = reason;
       child.kill("SIGKILL");
-    }, gitProcessTimeoutMs());
+    };
+    let idleTimer = setTimeout(() => {
+      kill(idleMessage);
+    }, idleMs);
+    const hardTimer = setTimeout(() => {
+      kill(HARD_TIMEOUT_REASON);
+    }, MAX_GIT_PROCESS_MS);
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk) => {
-      if (stderr.length < 16e3) stderr += chunk;
+      stderr = (stderr + chunk).slice(-16e3);
+      if (exitCode !== void 0 || settled) return;
+      clearTimeout(idleTimer);
+      idleTimer = setTimeout(() => {
+        kill(idleMessage);
+      }, idleMs);
     });
     child.on("error", (error) => {
-      clearTimeout(timer);
+      if (settled) return;
+      settled = true;
+      clearTimers();
       reject(error);
     });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      if (code === 0) resolve3();
-      else if (timedOut) reject(new Error(`${options.label} timed out after ${gitProcessTimeoutMs()}ms and was killed.`));
-      else reject(new Error(`${options.label}: ${stderr.trim() || `git exited ${code}`}`));
+    child.on("close", finish);
+    child.on("exit", (code) => {
+      exitCode = code;
+      clearTimeout(idleTimer);
+      clearTimeout(hardTimer);
+      if (timeoutReason) finish(code);
+      else drainTimer = setTimeout(() => {
+        finish(code);
+      }, GIT_EXIT_DRAIN_MS);
     });
   });
 }
@@ -5152,7 +6035,7 @@ var LFS_FILTER_OVERRIDE_ENV = {
   GIT_CONFIG_VALUE_3: "false"
 };
 function cloneOnce(source, targetDir) {
-  const args = ["clone", "--depth", "1", "--single-branch"];
+  const args = ["clone", "--progress", "--depth", "1", "--single-branch"];
   if (source.branch !== "HEAD") args.push("--branch", source.branch);
   args.push("--", source.cloneUrl, targetDir);
   return runGit(args, {
@@ -5201,6 +6084,7 @@ async function initSubmodules(targetDir, warnings) {
         "submodule",
         "update",
         "--init",
+        "--progress",
         "--depth",
         "1",
         "--",
@@ -5438,6 +6322,13 @@ function classifyApiSpec(path) {
   if (!topLevel) return "unknown";
   return /asyncapi/i.test(topLevel) ? "asyncapi" : "openapi";
 }
+var SPEC_DIRECTORY = "openapi";
+function specAssetPath(filename) {
+  return `${SPEC_DIRECTORY}/${filename}`;
+}
+function specAsset(filename, content) {
+  return { path: specAssetPath(filename), content, projectRelative: true };
+}
 function mintlifyTopLevelApiReferences(config) {
   const api = config?.api && typeof config.api === "object" && !Array.isArray(config.api) ? config.api : null;
   if (!api) return [];
@@ -5458,7 +6349,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
   const seen = /* @__PURE__ */ new Set();
   const specs = [];
   for (const reference of references) {
-    const dedupeKey = `${reference.kind}:${reference.value}`;
+    const dedupeKey = `${reference.kind}:${reference.value}:${reference.tabLabel ?? ""}`;
     if (seen.has(dedupeKey)) continue;
     seen.add(dedupeKey);
     const tabSuffix = reference.tabLabel ? ` (tab "${reference.tabLabel}")` : "";
@@ -5470,7 +6361,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       continue;
     }
     if (/^https:\/\//i.test(reference.value)) {
-      remoteSpecs.push({ url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {} });
+      remoteSpecs.push({ url: reference.value, ...reference.tabLabel ? { tabLabel: reference.tabLabel } : {}, ...reference.parentTab ? { parentTab: reference.parentTab } : {}, ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {} });
       warnings.push({
         code: "unsupported-config",
         message: `The remote OpenAPI spec "${reference.value}"${tabSuffix} requires a network download before this import is complete.`,
@@ -5501,15 +6392,19 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       filename: basename3(match.relativePath),
       content: readFileSync5(match.absolutePath),
       tabLabel: reference.tabLabel,
+      parentTab: reference.parentTab,
+      icon: reference.icon,
+      hidden: reference.hidden,
       sourcePath: match.relativePath,
       directory: reference.directory
     });
   }
   const filenameOwners = /* @__PURE__ */ new Map();
+  const filenameSources = /* @__PURE__ */ new Map();
   for (const spec of specs) {
     const groupKey = spec.tabLabel ?? "\0default";
     const owner = filenameOwners.get(spec.filename);
-    if (owner !== void 0 && owner !== groupKey) {
+    if (owner !== void 0 && owner !== groupKey && filenameSources.get(spec.filename) !== spec.sourcePath) {
       let disambiguated = spec.sourcePath.replace(/\//g, "-");
       while (filenameOwners.has(disambiguated) && filenameOwners.get(disambiguated) !== groupKey) {
         disambiguated = `${groupKey.replace(/\W+/g, "-")}-${disambiguated}`;
@@ -5517,6 +6412,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       spec.filename = disambiguated;
     }
     filenameOwners.set(spec.filename, groupKey);
+    filenameSources.set(spec.filename, spec.sourcePath);
   }
   return specs;
 }
@@ -5571,7 +6467,7 @@ function apiOperationLinkMap(sources, docsConfig) {
   const prefixLandings = /* @__PURE__ */ new Map();
   const apiTabs = docsConfig.tabs.filter((tab) => !tab.hidden && tab.api);
   apiTabs.forEach((tab, index) => {
-    const source = sources.find((entry) => tab.api?.source === `/${entry.filename}`);
+    const source = sources.find((entry) => tab.api?.source === specAssetPath(entry.filename));
     if (!source || !source.prefix) return;
     const specId = index === 0 ? "default" : slugifyApiSpecId(tab.tab);
     const prefix = source.prefix.replace(/^\/+|\/+$/g, "").toLowerCase();
@@ -5773,18 +6669,18 @@ function interpolateSnippet(snippet, attributes, children) {
   }).join("\n");
 }
 function snippetComponentBody(source, componentName) {
-  const parsed = ts2.createSourceFile("snippet.tsx", source, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
+  const parsed = ts3.createSourceFile("snippet.tsx", source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
   for (const statement of parsed.statements) {
-    if (!ts2.isVariableStatement(statement)) continue;
+    if (!ts3.isVariableStatement(statement)) continue;
     for (const declaration of statement.declarationList.declarations) {
-      if (!ts2.isIdentifier(declaration.name) || declaration.name.text !== componentName) continue;
+      if (!ts3.isIdentifier(declaration.name) || declaration.name.text !== componentName) continue;
       const initializer = declaration.initializer;
-      if (!initializer || !ts2.isArrowFunction(initializer)) continue;
-      const returned = ts2.isBlock(initializer.body) ? initializer.body.statements.find(ts2.isReturnStatement)?.expression : initializer.body;
+      if (!initializer || !ts3.isArrowFunction(initializer)) continue;
+      const returned = ts3.isBlock(initializer.body) ? initializer.body.statements.find(ts3.isReturnStatement)?.expression : initializer.body;
       if (!returned) continue;
       let expression = returned;
-      while (ts2.isParenthesizedExpression(expression)) expression = expression.expression;
-      if (ts2.isJsxElement(expression) || ts2.isJsxSelfClosingElement(expression) || ts2.isJsxFragment(expression)) {
+      while (ts3.isParenthesizedExpression(expression)) expression = expression.expression;
+      if (ts3.isJsxElement(expression) || ts3.isJsxSelfClosingElement(expression) || ts3.isJsxFragment(expression)) {
         return expression.getText(parsed);
       }
     }
@@ -5792,30 +6688,31 @@ function snippetComponentBody(source, componentName) {
   return source;
 }
 function statefulSnippetDeclaration(source, componentName) {
-  const parsed = ts2.createSourceFile("snippet.tsx", source, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
-  if (parsed.statements.length !== 1) return null;
-  const statement = parsed.statements[0];
-  if (!ts2.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword) || statement.declarationList.declarations.length !== 1) return null;
+  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);
+  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 declaration = statement.declarationList.declarations[0];
-  if (!ts2.isIdentifier(declaration.name) || declaration.name.text !== componentName || !declaration.initializer || !ts2.isArrowFunction(declaration.initializer) || !ts2.isBlock(declaration.initializer.body)) return null;
+  if (!declaration.initializer || !ts3.isArrowFunction(declaration.initializer) || !ts3.isBlock(declaration.initializer.body)) return null;
   const body = declaration.initializer.body.statements;
-  if (body.length < 2 || !body.some(ts2.isReturnStatement)) return null;
+  if (body.length < 2 || !body.some(ts3.isReturnStatement)) return null;
   return source.trim();
 }
 function staticNamedSnippetValues(source) {
   const values = /* @__PURE__ */ new Map();
-  const parsed = ts2.createSourceFile("snippet.tsx", source, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
+  const parsed = ts3.createSourceFile("snippet.tsx", source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
   for (const statement of parsed.statements) {
-    if (!ts2.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword)) continue;
+    if (!ts3.isVariableStatement(statement) || !statement.modifiers?.some((modifier) => modifier.kind === ts3.SyntaxKind.ExportKeyword)) continue;
     for (const declaration of statement.declarationList.declarations) {
-      if (!ts2.isIdentifier(declaration.name) || !declaration.initializer) continue;
+      if (!ts3.isIdentifier(declaration.name) || !declaration.initializer) continue;
       const expression = declaration.initializer;
-      if (ts2.isStringLiteral(expression) || ts2.isNoSubstitutionTemplateLiteral(expression)) {
+      if (ts3.isStringLiteral(expression) || ts3.isNoSubstitutionTemplateLiteral(expression)) {
         values.set(declaration.name.text, JSON.stringify(expression.text));
-      } else if (ts2.isNumericLiteral(expression)) {
+      } else if (ts3.isNumericLiteral(expression)) {
         values.set(declaration.name.text, expression.text);
-      } else if (expression.kind === ts2.SyntaxKind.TrueKeyword || expression.kind === ts2.SyntaxKind.FalseKeyword) {
-        values.set(declaration.name.text, expression.kind === ts2.SyntaxKind.TrueKeyword ? "true" : "false");
+      } else if (expression.kind === ts3.SyntaxKind.TrueKeyword || expression.kind === ts3.SyntaxKind.FalseKeyword) {
+        values.set(declaration.name.text, expression.kind === ts3.SyntaxKind.TrueKeyword ? "true" : "false");
       }
     }
   }
@@ -5970,7 +6867,15 @@ function preserveLinkedAnchors(pages) {
       const key = comparable(cell.text);
       candidateIndexes.set(key, [...candidateIndexes.get(key) ?? [], { index: cell.index, kind: "table" }]);
     }
-    for (const heading of headings) existing.add(heading.text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, ""));
+    const headingSlugs = /* @__PURE__ */ new Map();
+    const slugCounts = /* @__PURE__ */ new Map();
+    for (const heading of headings) {
+      const slug2 = heading.text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+      existing.add(slug2);
+      const seen = slugCounts.get(slug2) ?? 0;
+      slugCounts.set(slug2, seen + 1);
+      if (slug2) headingSlugs.set(seen === 0 ? slug2 : `${slug2}-${seen}`, heading.index);
+    }
     const headingAliases = /* @__PURE__ */ new Map();
     const tableAliases = /* @__PURE__ */ new Map();
     for (const fragment of fragments) {
@@ -5984,6 +6889,14 @@ function preserveLinkedAnchors(pages) {
         const selections = linkIndexes.map((index2) => matches.filter((candidate) => candidate.index < index2).at(-1));
         if (selections.length && selections.every((candidate) => candidate?.index === selections[0]?.index)) match = selections[0];
       }
+      if (!match && matches.length > 1) {
+        const headingMatches = matches.filter((candidate) => candidate.kind === "heading");
+        if (headingMatches.length === 1) match = headingMatches[0];
+      }
+      if (!match) {
+        const index2 = headingSlugs.get(fragment.toLowerCase());
+        if (index2 !== void 0) match = { index: index2, kind: "heading" };
+      }
       if (!match) continue;
       const { index, kind } = match;
       const aliases = kind === "heading" ? headingAliases : tableAliases;
@@ -6231,8 +7144,17 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
   result = result.replace(SNIPPET_TAG_PATTERN, (_tag, doubleQuoted, singleQuoted) => {
     const filePath = doubleQuoted ?? singleQuoted;
     try {
-      const candidate = resolveWithin(siteRoot, `snippets/${filePath}`);
-      if (!existsSync5(candidate) || !lstatSync5(candidate).isFile()) throw new Error("file not found");
+      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");
       return inlineMdxSnippets(
         withoutFrontmatter(readFileSync5(candidate, "utf8")),
         candidate,
@@ -6254,32 +7176,37 @@ function inlineMdxSnippets(raw, currentFile, repositoryRoot, warnings, depth = 0
   if (preservedDeclarations.size > 0) {
     const frontmatter = result.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
     const prefix = frontmatter?.[0] ?? "";
-    result = `${prefix}${[...preservedDeclarations.values()].join("\n\n")}
+    result = `${prefix}${[...new Set(preservedDeclarations.values())].join("\n\n")}
 
 ${result.slice(prefix.length)}`;
   }
   return depth === 0 ? hoistMdxImports(result) : result;
 }
 function injectOpenApiSpecs(config, specs, warnings) {
-  let tabs = config.tabs.map((tab) => ({ ...tab }));
+  const tabs = config.tabs.map((tab) => ({ ...tab }));
   for (const spec of specs) {
     const apiTab = spec.tabLabel ? tabs.find((tab) => tab.tab === spec.tabLabel) : tabs.find((tab) => tab.tab.toLowerCase().includes("api"));
     if (apiTab) {
       if (apiTab.api && warnings) {
         warnings.push({
           code: "unsupported-config",
-          message: `Tab "${apiTab.tab}" already uses another OpenAPI spec, and Thally supports one API spec per tab, so "/${spec.filename}" was not added. Put it in its own tab to include it.`
+          message: `Tab "${apiTab.tab}" already uses another OpenAPI spec, and Thally supports one API spec per tab, so "${specAssetPath(spec.filename)}" was not added. Put it in its own tab to include it.`
         });
         continue;
       }
       apiTab.api = {
-        source: `/${spec.filename}`,
+        source: specAssetPath(spec.filename),
         // An API-only tab needs generated endpoint navigation; an authored
         // page tab keeps its own groups alongside the bound spec.
         ...apiTab.groups?.length || apiTab.pages?.length ? { navigation: false } : {}
       };
     } else {
-      tabs = [...tabs, { tab: spec.tabLabel ?? "API Reference", api: { source: `/${spec.filename}` } }];
+      insertApiTab(tabs, {
+        tab: spec.tabLabel ?? "API Reference",
+        ...spec.icon ? { icon: spec.icon } : {},
+        ...spec.hidden ? { hidden: true } : {},
+        api: { source: specAssetPath(spec.filename) }
+      }, spec.parentTab);
     }
   }
   return { ...config, tabs };
@@ -6658,9 +7585,9 @@ function migrateRepository(options) {
       });
       continue;
     }
-    const declaredNames = functionDeclaredNames(page.body);
-    if (hasAnyFunctionValuedProp(page.body, declaredNames)) {
-      if (propsTargetExtractedClientComponent(page.body, declaredNames)) {
+    const declaredNames2 = functionDeclaredNames(page.body);
+    if (hasAnyFunctionValuedProp(page.body, declaredNames2)) {
+      if (propsTargetExtractedClientComponent(page.body, declaredNames2)) {
         skipped++;
         warnings.push({
           code: "skipped-file",
@@ -6777,28 +7704,35 @@ function migrateRepository(options) {
     ...assetCandidates.filter((candidate) => !isReferenced(candidate))
   ];
   let totalAssetBytes = 0;
+  const overBudgetAssets = [];
+  let overBudgetReferenced = 0;
+  const lfsPointerAssets = [];
   for (const { file, assetPath, size } of orderedAssetCandidates) {
     if (size > MAX_ASSET_BYTES || totalAssetBytes + size > MAX_TOTAL_ASSET_BYTES) {
-      const referencingPages = referencedAssetPaths.get(assetPath);
-      warnings.push({
-        code: "limit-reached",
-        message: "This file was not copied because it is larger than 25 MB or the copied files would exceed 500 MB in total. Add it to public/ manually" + (referencingPages ? `; it is used by ${[...referencingPages].slice(0, 3).join(", ")}${referencingPages.size > 3 ? `, and ${referencingPages.size - 3} more` : ""}.` : "."),
-        source: file.relativePath
-      });
+      overBudgetAssets.push(file.relativePath);
+      if (referencedAssetPaths.has(assetPath)) overBudgetReferenced++;
       continue;
     }
     const content = readFileSync5(file.absolutePath);
     if (isGitLfsPointer(content)) {
-      warnings.push({
-        code: "unsupported-config",
-        message: "This asset is a Git LFS pointer, not its real content (Git LFS was skipped during clone because the host has no git-lfs binary). Install git-lfs and re-run the migration, or add the real file to public/ manually.",
-        source: file.relativePath
-      });
+      lfsPointerAssets.push(file.relativePath);
       continue;
     }
     assets.push({ path: assetPath, content });
     totalAssetBytes += size;
   }
+  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.`
+    });
+  }
+  if (lfsPointerAssets.length > 0) {
+    warnings.push({
+      code: "unsupported-config",
+      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 >= MAX_SOURCE_FILES) {
     warnings.push({ code: "limit-reached", message: `Stopped scanning after ${MAX_SOURCE_FILES} files, so the rest of the repository was not looked at. Run the migration on a smaller part of the repository with --docs-dir.` });
   }
@@ -6887,8 +7821,8 @@ function migrateRepository(options) {
         }
         specFilenameSources.set(filename, spec.absolutePath);
         const specContent = readFileSync5(spec.absolutePath);
-        if (!assets.some((asset) => asset.path === filename)) {
-          assets.push({ path: filename, content: specContent });
+        if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
+          assets.push(specAsset(filename, specContent));
         }
         resolvedSpecs.push({ filename, tabLabel: section.tabLabel, content: specContent, routeSegments: section.routeSegments ?? [] });
         continue;
@@ -6929,8 +7863,8 @@ function migrateRepository(options) {
   } else if (platform === "mintlify") {
     const resolvedSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs);
     for (const spec of resolvedSpecs) {
-      if (!assets.some((asset) => asset.path === spec.filename)) {
-        assets.push({ path: spec.filename, content: spec.content });
+      if (!assets.some((asset) => asset.path === specAssetPath(spec.filename))) {
+        assets.push(specAsset(spec.filename, spec.content));
       }
     }
     if (resolvedSpecs.length > 0) {
@@ -6944,8 +7878,8 @@ function migrateRepository(options) {
       const fallback = findOpenApi(files);
       if (fallback) {
         const filename = basename3(fallback.relativePath);
-        if (!assets.some((asset) => asset.path === filename)) {
-          assets.push({ path: filename, content: readFileSync5(fallback.absolutePath) });
+        if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
+          assets.push(specAsset(filename, readFileSync5(fallback.absolutePath)));
         }
         docsConfig = injectOpenApiSpecs(docsConfig, [{ filename }]);
       }
@@ -7436,7 +8370,7 @@ function renderMigrationFiles(bundle, options = {}) {
       path: `src/content/${page.id}.mdx`,
       content: renderPage(bundle, page)
     })),
-    ...bundle.assets.map((asset) => ({ path: `public/${asset.path}`, content: asset.content })),
+    ...bundle.assets.map((asset) => ({ path: asset.projectRelative ? asset.path : `public/${asset.path}`, content: asset.content })),
     ...(bundle.componentFiles ?? []).flatMap((file) => file.path === "src/mdx/custom-components.tsx" && options.existingComponentRegistry !== void 0 && typeof file.content === "string" ? mergeComponentRegistry(options.existingComponentRegistry, file.content) : [file]),
     { path: "docs.json", content: `${JSON.stringify(config, null, 2)}
 ` }
@@ -7463,6 +8397,7 @@ var PORTABLE_MDX_COMPONENTS = /* @__PURE__ */ new Set([
   "Card",
   "CardGroup",
   "Check",
+  "CodeBlock",
   "CodeGroup",
   "Color",
   "Column",
@@ -7473,6 +8408,7 @@ var PORTABLE_MDX_COMPONENTS = /* @__PURE__ */ new Set([
   "Expandable",
   "Agent",
   "AgentPrompt",
+  "Banner",
   "BannerPreview",
   "Embed",
   "File",
@@ -7489,6 +8425,8 @@ var PORTABLE_MDX_COMPONENTS = /* @__PURE__ */ new Set([
   "InlineResponseExample",
   "Latex",
   "LegacyView",
+  "LiteYouTubeEmbed",
+  "MDX",
   "Mermaid",
   "Note",
   "Panel",
@@ -7512,9 +8450,11 @@ var PORTABLE_MDX_COMPONENTS = /* @__PURE__ */ new Set([
   "Tooltip",
   "Tree",
   "Update",
+  "Video",
   "View",
   "Visibility",
-  "Warning"
+  "Warning",
+  "YouTube"
 ]);
 var LOCALE_CODES = /* @__PURE__ */ new Set([
   "ar",
@@ -9172,10 +10112,10 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
       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}`;
-      assets.push({ path: filename, content: body });
+      assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });
       const tab = reference.tabLabel ? tabs.find((candidate) => candidate.tab === reference.tabLabel) : tabs.find((candidate) => candidate.tab.toLowerCase().includes("api"));
-      if (tab) tab.api = { source: `/${filename}` };
-      else tabs.push({ tab: reference.tabLabel ?? "API Reference", api: { source: `/${filename}` } });
+      if (tab) tab.api = { source: `openapi/${filename}` };
+      else insertApiTab(tabs, { tab: reference.tabLabel ?? "API Reference", ...reference.icon ? { icon: reference.icon } : {}, ...reference.hidden ? { hidden: true } : {}, api: { source: `openapi/${filename}` } }, reference.parentTab);
       const routes = /* @__PURE__ */ new Map();
       for (const operation of operations) {
         const key = `${slug(operation.tag)}/${slug(operation.summary)}`;