@thallylabs/migrate 0.2.33 → 0.2.34

package/dist/index.js

@@ -230,8 +230,11 @@ var JS_GLOBALS = /* @__PURE__ */ new Set([
   "BroadcastChannel"
 ]);
 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 scriptKindFor(fileName) {
+  return /\.[cm]?ts$/.test(fileName) ? ts.ScriptKind.TS : ts.ScriptKind.TSX;
+}
+function parse(source, fileName = "inline.tsx") {
+  return ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, true, scriptKindFor(fileName));
 }
 function bindingNames(name, into) {
   if (ts.isIdentifier(name)) into.add(name.text);
@@ -240,20 +243,44 @@ function bindingNames(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 hoistedVarNames(root, into) {
+  const collect = (node) => {
+    if (isFunctionLike(node) || ts.isClassLike(node) || ts.isModuleDeclaration(node)) return;
+    if (ts.isVariableDeclaration(node) && !ts.isCatchClause(node.parent) && !(ts.getCombinedNodeFlags(node) & ts.NodeFlags.BlockScoped)) bindingNames(node.name, into);
+    ts.forEachChild(node, collect);
+  };
+  collect(root);
+}
 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 lexicalNames(statements) {
+  const names = /* @__PURE__ */ new Set();
+  for (const statement of statements) {
+    if (ts.isVariableStatement(statement)) {
+      if (statement.declarationList.flags & ts.NodeFlags.BlockScoped) for (const declaration of statement.declarationList.declarations) bindingNames(declaration.name, names);
+    } else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) && statement.name) names.add(statement.name.text);
+  }
+  return names;
+}
+function ownScope(node) {
+  if (ts.isBlock(node)) return lexicalNames(node.statements);
+  if (ts.isCaseBlock(node)) return lexicalNames(node.clauses.flatMap((clause) => [...clause.statements]));
+  if ((ts.isForStatement(node) || ts.isForInStatement(node) || ts.isForOfStatement(node)) && node.initializer && ts.isVariableDeclarationList(node.initializer)) {
+    const names = /* @__PURE__ */ new Set();
+    if (node.initializer.flags & ts.NodeFlags.BlockScoped) for (const declaration of node.initializer.declarations) bindingNames(declaration.name, names);
+    return names;
+  }
+  if (ts.isCatchClause(node) && node.variableDeclaration) {
+    const names = /* @__PURE__ */ new Set();
+    bindingNames(node.variableDeclaration.name, names);
+    return names;
+  }
+  return void 0;
+}
 function collectRefs(root) {
   const refs = [];
   const assigned = [];
@@ -268,13 +295,22 @@ function collectRefs(root) {
   function walkNode(node, scopes, inAsync) {
     if (ts.isTypeNode(node)) return;
     if (isFunctionLike(node)) {
-      const nextScopes = [...scopes, functionScope(node)];
+      const parameterScopes = [...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 (!ts.isIdentifier(parameter.name)) walkNode(parameter.name, parameterScopes, async);
+        if (parameter.initializer) walkNode(parameter.initializer, parameterScopes, async);
+      }
+      if (node.body) {
+        const hoisted = /* @__PURE__ */ new Set();
+        hoistedVarNames(node.body, hoisted);
+        walkNode(node.body, [...parameterScopes, hoisted], async);
       }
-      if (node.body) walkNode(node.body, nextScopes, async);
+      return;
+    }
+    const own2 = ownScope(node);
+    if (own2) {
+      ts.forEachChild(node, (child) => walkNode(child, [...scopes, own2], inAsync));
       return;
     }
     if (ts.isAwaitExpression(node) && !inAsync) awaitOutsideAsync = true;
@@ -651,6 +687,23 @@ function unboundTags(moduleSource, boundNames) {
   }
   return [...tags].sort();
 }
+function unboundBuiltinTags(moduleSource, boundNames, fileName) {
+  const tags = /* @__PURE__ */ new Set();
+  const values = /* @__PURE__ */ new Set();
+  for (const statement of parse(moduleSource, fileName).statements) {
+    if (ts.isImportDeclaration(statement)) continue;
+    for (const { name, kind } of collectRefs(statement).refs) {
+      if (boundNames.has(name)) continue;
+      if (kind === "tag" || kind === "member") tags.add(name);
+      else values.add(name);
+    }
+  }
+  const isGlobal = (name) => JS_GLOBALS.has(name) || BROWSER_IDENTIFIERS.has(name) || SERVER_ONLY_IDENTIFIERS.has(name);
+  const builtinTags = [...tags].filter(isThallyBuiltinComponent);
+  const shadowed = builtinTags.filter((name) => JS_GLOBALS.has(name) && values.has(name)).sort();
+  const builtinValues = [...values].filter((name) => isThallyBuiltinComponent(name) && !isGlobal(name));
+  return { bind: [.../* @__PURE__ */ new Set([...builtinTags.filter((name) => !shadowed.includes(name)), ...builtinValues])].sort(), shadowed };
+}
 var INLINE_SAFE_GLOBALS = /* @__PURE__ */ new Set([
   "undefined",
   "NaN",
@@ -719,12 +772,14 @@ function isSelfContainedFunction(node) {
 function pageScopeNames(esmSources) {
   const names = /* @__PURE__ */ new Set();
   for (const source of esmSources) {
-    for (const statement of parse(source).statements) {
+    const sf = parse(source);
+    for (const statement of sf.statements) {
       for (const local of importLocals(statement.getText())) names.add(local);
       if (ts.isImportDeclaration(statement)) continue;
       const target2 = ts.isExportDeclaration(statement) || ts.isExportAssignment(statement) ? void 0 : statement;
       if (target2) for (const name of declaredNames(target2).names) names.add(name);
     }
+    hoistedVarNames(sf, names);
   }
   return names;
 }
@@ -2934,13 +2989,7 @@ function sanitizeCssModuleSelectors(css) {
   return { css: root.toString(), omitted };
 }
 function sourceFile(source, filename) {
-  return ts2.createSourceFile(
-    filename,
-    source,
-    ts2.ScriptTarget.Latest,
-    true,
-    /\.[cm]?ts$/.test(filename) ? ts2.ScriptKind.TS : ts2.ScriptKind.TSX
-  );
+  return ts2.createSourceFile(filename, source, ts2.ScriptTarget.Latest, true, scriptKindFor(filename));
 }
 function walk(node, visitor) {
   visitor(node);
@@ -2997,7 +3046,7 @@ function needsClientBoundary(source) {
   visitNode(source);
   return needed;
 }
-function implicitReactImports(source) {
+function implicitReactImports(source, onShadowed) {
   const bindings = /* @__PURE__ */ new Set();
   const references = /* @__PURE__ */ new Set();
   function bind(name) {
@@ -3015,7 +3064,9 @@ function implicitReactImports(source) {
     }
     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);
+    if ((ts2.isEnumDeclaration(statement) || ts2.isModuleDeclaration(statement) || ts2.isImportEqualsDeclaration(statement)) && ts2.isIdentifier(statement.name)) bindings.add(statement.name.text);
   }
+  hoistedVarNames(source, bindings);
   function visit(node) {
     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);
@@ -3023,26 +3074,50 @@ function implicitReactImports(source) {
   visit(source);
   const hooks = [...REACT_GLOBALS].filter((name) => references.has(name) && !bindings.has(name)).sort();
   const usesMintlifyComponents = references.has("MintlifyComponents") && !bindings.has("MintlifyComponents");
+  const leafBound = /* @__PURE__ */ new Set();
   const implicitComponents = MINTLIFY_COMPONENT_MODULES.map(({ module, names }) => {
-    const needed = names.filter((name) => references.has(name) && !bindings.has(name));
+    const needed = names.filter((name) => name !== "Note" && references.has(name) && !bindings.has(name));
+    for (const name of needed) leafBound.add(name);
     return needed.length ? `import { ${needed.join(", ")} } from '${module}';` : "";
   }).filter(Boolean);
+  const { bind: builtinTags, shadowed } = unboundBuiltinTags(source.text, bindings, source.fileName);
+  const registryNames = builtinTags.filter((name) => !leafBound.has(name));
+  if (shadowed.length) onShadowed?.(shadowed);
   return [
     references.has("React") && !bindings.has("React") ? "import * as React from 'react';" : "",
     hooks.length ? `import { ${hooks.join(", ")} } from 'react';` : "",
     ...implicitComponents,
+    registryNames.length ? builtinRegistryBindings(registryNames, identifierNames(source)) : "",
     usesMintlifyComponents ? mintlifyComponentsShim() : ""
   ].filter(Boolean).join("\n");
 }
 function resolveInlineBuiltinReferences(source, moduleNames) {
   const unresolved = unboundTags(source, moduleNames);
   if (unresolved.length === 0) return source;
+  return [builtinRegistryBindings(unresolved, identifierNames(sourceFile(source, "inline.jsx"))), source].join("\n");
+}
+function identifierNames(root) {
+  const names = /* @__PURE__ */ new Set();
+  const visit = (node) => {
+    if (ts2.isIdentifier(node)) names.add(node.text);
+    ts2.forEachChild(node, visit);
+  };
+  visit(root);
+  return names;
+}
+function builtinRegistryBindings(names, used) {
+  const registry = "builtinMdxComponents";
+  let alias = registry;
+  for (let suffix = 2; used.has(alias); suffix++) alias = `${registry}${suffix}`;
   return [
-    "import { builtinMdxComponents } from '@/components/mdx/builtin-components';",
-    `const { ${unresolved.join(", ")} } = builtinMdxComponents;`,
-    source
+    `import { ${alias === registry ? registry : `${registry} as ${alias}`} } from '@/components/mdx/builtin-components';`,
+    `const { ${names.join(", ")} } = ${alias};`
   ].join("\n");
 }
+function shadowedBuiltinMessage(file, names) {
+  const tags = names.map((name) => `<${name}>`).join(", ");
+  return `${file} renders ${tags} as a Thally built-in component but also uses the JavaScript global of the same name, so the tag was left unbound. Rename the component or the global use in the source.`;
+}
 function imports(statement) {
   if (!ts2.isStringLiteral(statement.moduleSpecifier) || !statement.importClause) return [];
   const clause = statement.importClause;
@@ -3269,6 +3344,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
   function copyGraph(entry) {
     const staged = /* @__PURE__ */ new Map();
     const stagedWarnings = [];
+    const stagedShadowed = [];
     const modules = /* @__PURE__ */ new Map();
     let stagedBytes = 0;
     function stageShim(filename, content) {
@@ -3373,7 +3449,8 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           const prologue = `// @ts-nocheck
 ${client ? "'use client';\n" : ""}
 `;
-          return shebangMatch ? shebangMatch[0] + prologue + implicitReactImports(ast) + "\n" + replaced.slice(shebangMatch[0].length) : prologue + implicitReactImports(ast) + "\n" + replaced;
+          const implicit = implicitReactImports(ast, (names) => stagedShadowed.push({ path, names }));
+          return shebangMatch ? shebangMatch[0] + prologue + implicit + "\n" + replaced.slice(shebangMatch[0].length) : prologue + implicit + "\n" + replaced;
         }
       });
     }
@@ -3391,6 +3468,7 @@ ${client ? "'use client';\n" : ""}
     }
     for (const [path, module] of modules) staged.set(path, { path, content: module.render(clientModules.has(path)) });
     for (const [path, file] of staged) copied.set(path, file);
+    for (const { path, names } of stagedShadowed) warn(shadowedBuiltinMessage(relative2(root, path).replace(/\\/g, "/"), names), path);
     for (const { path, omitted } of stagedWarnings) {
       warn(`Site-authored CSS module ${relative2(root, path).replace(/\\/g, "/")} has ${omitted} global-only selector branch(es) that cannot be copied into Thally CSS Modules; those styles were omitted.`, path);
     }
@@ -3845,8 +3923,12 @@ ${inlineSource}` });
 }`),
         ""
       ].join("\n");
+      const implicit = implicitReactImports(
+        sourceFile(inlineSource, "inline.jsx"),
+        (names) => warn(shadowedBuiltinMessage(relative2(root, currentFile).replace(/\\/g, "/"), names), currentFile)
+      );
       copied.set(path, { path, content: `'use client';
-${implicitReactImports(sourceFile(inlineSource, "inline.jsx"))}
+${implicit}
 ${inlineSource}` });
       copiedBytes += Buffer.byteLength(inlineSource);
       for (const { node, name } of extracted) {
@@ -7196,8 +7278,49 @@ function splitOpenApiRef(raw) {
   const specRef = match[1] ? unquote(match[1]) : void 0;
   return { ...specRef ? { specRef } : {}, operation: match[2] };
 }
+function canonicalSpecRef(specRef) {
+  return specRef.trim().split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^(?:\.?\/+)+/, "");
+}
+function isRemoteSpecRef(specRef) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(specRef);
+}
 function specRefBaseName(specRef) {
-  return specRef.trim().replace(/\\/g, "/").split(/[?#]/, 1)[0].split("/").filter(Boolean).pop()?.toLowerCase() ?? "";
+  return canonicalSpecRef(specRef).split("/").filter(Boolean).pop()?.toLowerCase() ?? "";
+}
+function withoutSpecExtension(value) {
+  return value.replace(/\.(?:json|ya?ml)$/i, "");
+}
+function resolveSpecRef(specRef, candidates, anyFolder = true) {
+  const key = canonicalSpecRef(specRef);
+  const byId = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    const id = candidate.sourcePath ?? candidate.filename;
+    if (!byId.has(id)) byId.set(id, candidate);
+  }
+  const unique = [...byId.values()];
+  const exact = unique.find((candidate) => candidate.sourcePath === key);
+  if (exact) return { kind: "match", spec: exact };
+  if (!anyFolder && key.includes("/")) return { kind: "none" };
+  const name = specRefBaseName(key);
+  const names = unique.map((candidate) => specRefBaseName(candidate.sourcePath ?? candidate.filename));
+  for (const fits of [unique.filter((_, index) => names[index] === name), unique.filter((_, index) => withoutSpecExtension(names[index]) === name)]) {
+    if (fits.length === 1) return { kind: "match", spec: fits[0] };
+    if (fits.length > 1) return { kind: "ambiguous", candidates: fits };
+  }
+  return { kind: "none" };
+}
+function localSpecRef(openapi) {
+  const specRef = openapi ? splitOpenApiRef(openapi)?.specRef : void 0;
+  return specRef && !isRemoteSpecRef(specRef) ? specRef : void 0;
+}
+function specNamedByPage(openapi, specs) {
+  const specRef = localSpecRef(openapi);
+  const resolved = specRef ? resolveSpecRef(specRef, specs) : void 0;
+  return resolved?.kind === "match" ? resolved.spec : void 0;
+}
+function namesSeveralSpecs(openapi, specs) {
+  const specRef = localSpecRef(openapi);
+  return Boolean(specRef) && resolveSpecRef(specRef, specs).kind === "ambiguous";
 }
 function withSpecRef(ref, specRef) {
   return `${specRef} ${ref.operation}`;
@@ -7205,25 +7328,44 @@ function withSpecRef(ref, specRef) {
 
 // src/spec-exclude.ts
 import { parse as parseYaml4, stringify as stringifyYaml } from "yaml";
-function specRefMatches(ref, specPath, specFilename, isDefault) {
-  const prefix = /^(?:(\S+)\s+)?(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|WEBHOOK)\s/i.exec(`${ref} `)?.[1];
+function specRefMatches(ref, specPath, isDefault) {
+  const prefix = splitOpenApiRef(ref)?.specRef;
   if (!prefix) return isDefault;
-  const wanted = prefix.replace(/^\/+/, "").toLowerCase();
+  const wanted = (isRemoteSpecRef(prefix) ? prefix.trim() : canonicalSpecRef(prefix)).toLowerCase();
   const lowerPath = specPath.toLowerCase();
-  return lowerPath === wanted || lowerPath.endsWith(`/${wanted}`) || specFilename.toLowerCase() === wanted;
+  const stem = withoutSpecExtension(lowerPath);
+  return lowerPath === wanted || lowerPath.endsWith(`/${wanted}`) || stem === wanted || stem.endsWith(`/${wanted}`);
+}
+function resolvedSources(ref, specs) {
+  const specRef = splitOpenApiRef(ref)?.specRef;
+  if (!specRef || isRemoteSpecRef(specRef)) return { unique: false, sources: [] };
+  const resolved = resolveSpecRef(specRef, specs);
+  if (resolved.kind === "match") return { unique: true, sources: [resolved.spec.sourcePath] };
+  return { unique: false, sources: resolved.kind === "ambiguous" ? resolved.candidates.map((candidate) => candidate.sourcePath) : [] };
+}
+function refWithholdsFrom(ref, spec, specs) {
+  const { unique, sources } = resolvedSources(ref, specs);
+  return unique ? sources[0] === spec.sourcePath : specRefMatches(ref, spec.sourcePath, true) || sources.includes(spec.sourcePath);
+}
+function refKeepsIn(ref, spec, specs) {
+  const specRef = splitOpenApiRef(ref)?.specRef;
+  if (!specRef) return false;
+  if (isRemoteSpecRef(specRef)) return specRefMatches(ref, spec.sourcePath, false);
+  const { unique, sources } = resolvedSources(ref, specs);
+  return unique && sources[0] === spec.sourcePath;
 }
 function operationKey(operation) {
   const [first, ...rest] = operation.trim().split(/\s+/);
   return `${first.toLowerCase()} ${rest.join(" ")}`;
 }
-function keysFor(spec, refs) {
+function keysFor(refs, names) {
   return [...new Set(
-    refs.filter((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true)).map((ref) => splitOpenApiRef(ref)?.operation).filter((op) => !!op).map(operationKey)
+    refs.filter(names).map((ref) => splitOpenApiRef(ref)?.operation).filter((op) => !!op).map(operationKey)
   )];
 }
-function withheldOperationKeys(spec, withheldRefs, keptRefs) {
-  const kept = keysFor(spec, keptRefs);
-  return { withheld: keysFor(spec, withheldRefs).filter((key) => !kept.includes(key)), kept };
+function withheldOperationKeys(spec, withheldRefs, keptRefs, specs = [spec]) {
+  const kept = keysFor(keptRefs, (ref) => refKeepsIn(ref, spec, specs));
+  return { withheld: keysFor(withheldRefs, (ref) => refWithholdsFrom(ref, spec, specs)).filter((key) => !kept.includes(key)), kept };
 }
 function withoutByteOrderMark(content) {
   return content.length >= 3 && content[0] === 239 && content[1] === 187 && content[2] === 191 ? content.subarray(3) : content;
@@ -10474,22 +10616,56 @@ function normalizedReferenceKey(value) {
 function exactReferenceKey(value) {
   return value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/").replace(/\.(?:mdx?|rst|txt)$/i, "");
 }
-function navigationOperationRefs(config) {
-  const refs = [];
-  const visit = (node) => {
+function containerSpec(node) {
+  const value = node.openapi;
+  if (value === void 0) return void 0;
+  const source = value && typeof value === "object" && !Array.isArray(value) ? value.source : value;
+  return typeof source === "string" && source.trim() && !splitOpenApiRef(source) ? source.trim() : null;
+}
+function navigationSpecContext(config, pageIdentity) {
+  const context = { operations: [], pageOwners: /* @__PURE__ */ new Map(), pageIdentity };
+  const visit = (node, owner, listed) => {
     if (typeof node === "string") {
-      if (splitOpenApiRef(node)) refs.push(node);
-    } else if (Array.isArray(node)) node.forEach(visit);
+      if (splitOpenApiRef(node)) context.operations.push({ ref: node, owner });
+      else if (listed) {
+        const page = pageIdentity(node);
+        if (page !== null) context.pageOwners.set(page, (context.pageOwners.get(page) ?? /* @__PURE__ */ new Set()).add(owner));
+      }
+    } else if (Array.isArray(node)) node.forEach((child) => visit(child, owner, true));
     else if (node && typeof node === "object") {
       if (navigationGateReason(node)) return;
-      Object.values(node).forEach(visit);
-    }
-  };
-  visit(config?.navigation);
-  return refs;
-}
-function excludeWithheldOperations(spec, withheldRefs, keptRefs) {
-  const { withheld, kept } = withheldOperationKeys(spec, withheldRefs, keptRefs);
+      const own2 = containerSpec(node);
+      Object.values(node).forEach((child) => visit(child, own2 === void 0 ? owner : own2, false));
+    }
+  };
+  visit(config?.navigation, void 0, false);
+  return context;
+}
+function keptOperationRefs(published, navigation, defaultSpec, specs) {
+  const kept = [];
+  const unowned = [];
+  const source = (owner) => {
+    if (!owner || isRemoteSpecRef(owner)) return owner;
+    const resolved = resolveSpecRef(owner, specs);
+    return resolved.kind === "match" ? resolved.spec.sourcePath ?? resolved.spec.filename : owner;
+  };
+  const add = (raw, owner) => {
+    const ref = splitOpenApiRef(raw);
+    if (!ref) return;
+    if (ref.specRef) kept.push(raw);
+    else if (owner) kept.push(withSpecRef(ref, owner));
+    else unowned.push(ref.operation);
+  };
+  for (const { ref, file } of published) {
+    const page = navigation.pageIdentity(file);
+    const owners = new Set([...(page === null ? void 0 : navigation.pageOwners.get(page)) ?? [void 0]].map((owner) => source(owner === void 0 ? defaultSpec : owner)));
+    add(ref, owners.size === 1 ? [...owners][0] : null);
+  }
+  for (const { ref, owner } of navigation.operations) add(ref, source(owner === void 0 ? defaultSpec : owner));
+  return { kept, unowned };
+}
+function excludeWithheldOperations(spec, withheldRefs, keptRefs, specs) {
+  const { withheld, kept } = withheldOperationKeys(spec, withheldRefs, keptRefs, specs);
   return markExcluded(spec.content, withheld, kept);
 }
 var TOKEN_SEPARATORS = /[\s"'()<>[\]{}=,;:|\\/`*!?#&]+/;
@@ -10590,6 +10766,23 @@ function specAssetPath(filename) {
 function specAsset(filename, content) {
   return { path: specAssetPath(filename), content, projectRelative: true };
 }
+function createSpecAssetNamer() {
+  const nameBySource = /* @__PURE__ */ new Map();
+  const sourceByName = /* @__PURE__ */ new Map();
+  return ({ sourcePath, filename, tabLabel }) => {
+    let name = nameBySource.get(sourcePath);
+    if (name === void 0) {
+      name = filename;
+      if (sourceByName.has(name.toLowerCase())) {
+        name = sourcePath.replace(/\//g, "-");
+        while (sourceByName.has(name.toLowerCase())) name = `${(tabLabel ?? "default").replace(/\W+/g, "-")}-${name}`;
+      }
+      nameBySource.set(sourcePath, name);
+      sourceByName.set(name.toLowerCase(), sourcePath);
+    }
+    return name;
+  };
+}
 function mintlifyTopLevelApiReferences(config) {
   const api = config?.api && typeof config.api === "object" && !Array.isArray(config.api) ? config.api : null;
   if (!api) return [];
@@ -10601,19 +10794,25 @@ function mintlifyTopLevelApiReferences(config) {
   }
   return references;
 }
-function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, pages = []) {
+function specFileCandidates(files) {
+  return files.filter((file) => /\.(?:json|ya?ml)$/i.test(file.relativePath)).map((file) => ({ sourcePath: file.relativePath, filename: specRefBaseName(file.relativePath) }));
+}
+function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, nameSpec, pages = []) {
   if (!mintlifyConfig) return [];
   const references = [
     ...mintlifyTopLevelApiReferences(mintlifyConfig),
     ...mintlifyNavigationApiReferences(mintlifyConfig)
   ];
-  const specKey = (value) => value.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^(?:\.\/)+/, "").replace(/^\/+/, "");
-  const known = new Set(references.map((reference) => specKey(reference.value)));
+  const known = new Set(references.map((reference) => canonicalSpecRef(reference.value)));
+  const specFiles = specFileCandidates(files);
+  const namedFiles = /* @__PURE__ */ new Map();
   for (const page of pages) {
     const specRef = page.openapi ? splitOpenApiRef(page.openapi)?.specRef : void 0;
     if (!specRef || /^[a-z][a-z0-9+.-]*:/i.test(specRef)) continue;
-    const key = specKey(specRef);
-    if (known.has(key) || !files.some((file) => file.relativePath === key)) continue;
+    const named = namedFiles.get(specRef) ?? resolveSpecRef(specRef, specFiles, false);
+    namedFiles.set(specRef, named);
+    const key = named.kind === "match" ? named.spec.sourcePath : "";
+    if (!key || known.has(key)) continue;
     known.add(key);
     references.push({ value: key, kind: "openapi", tabLabel: `OpenAPI: ${key}`, hidden: true, pageOnly: true });
   }
@@ -10663,7 +10862,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
       warnings.push({ code: "unsupported-config", message: `The OpenAPI spec "${reference.value}"${tabSuffix} uses insecure HTTP and was not imported.`, source: reference.value });
       continue;
     }
-    const key = reference.value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/");
+    const key = canonicalSpecRef(reference.value);
     const match = files.find((file) => file.relativePath === key);
     if (!match) {
       warnings.push({
@@ -10692,21 +10891,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, p
       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 && 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}`;
-      }
-      spec.filename = disambiguated;
-    }
-    filenameOwners.set(spec.filename, groupKey);
-    filenameSources.set(spec.filename, spec.sourcePath);
-  }
+  for (const spec of specs) spec.filename = nameSpec(spec);
   return specs;
 }
 function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings, explainMissing = () => "no such file was found") {
@@ -10719,12 +10904,13 @@ function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings, explain
       }
       continue;
     }
-    const key = ref.specRef.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^(?:\.\/)+/, "").replace(/^\/+/, "");
-    const byPath = specs.find((spec) => spec.sourcePath === key);
-    const byName = specs.filter((spec) => spec.filename.toLowerCase() === specRefBaseName(key));
-    const match = byPath ?? (byName.length === 1 ? byName[0] : void 0);
-    if (match) {
-      page.openapi = withSpecRef(ref, specAssetPath(match.filename));
+    const key = canonicalSpecRef(ref.specRef);
+    const resolved = resolveSpecRef(ref.specRef, specs);
+    if (resolved.kind === "match") {
+      page.openapi = withSpecRef(ref, specAssetPath(resolved.spec.filename));
+    } else if (resolved.kind === "ambiguous") {
+      const candidates = resolved.candidates.map((spec) => spec.sourcePath ?? spec.filename).join(", ");
+      warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the OpenAPI spec "${ref.specRef}", which fits more than one spec (${candidates}), so it was left as written and the page will not render an endpoint. Write the full path of the spec in the page's openapi frontmatter.`, source: page.source });
     } else {
       warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the OpenAPI spec "${ref.specRef}", which was not migrated (${explainMissing(key)}); the page will not render an endpoint.`, source: page.source });
     }
@@ -12055,9 +12241,12 @@ function injectOpenApiSpecs(config, specs, warnings) {
     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) {
+        const source = specAssetPath(spec.filename);
+        const pageBound = spec.pageReferenced && !tabs.some((tab) => tab.api?.source === source);
+        if (pageBound) insertApiTab(tabs, { tab: `OpenAPI: ${spec.sourcePath ?? spec.filename}`, hidden: true, api: { source } });
         warnings.push({
           code: "unsupported-config",
-          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.`
+          message: `Tab "${apiTab.tab}" already uses another OpenAPI spec, and Thally supports one API spec per tab, so "${source}" ${pageBound ? "gets no endpoint list of its own; the pages that name it still show their endpoint. Put it in its own tab to list all its endpoints." : "was not added. Put it in its own tab to include it."}`
         });
         continue;
       }
@@ -12316,6 +12505,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
   const gateByPath = /* @__PURE__ */ new Map();
   const withheldSpecRefs = [];
   const publishedSpecRefs = [];
+  const publishedSpecPages = [];
   const withheldPaths = /* @__PURE__ */ new Set();
   const isDocFile = (file) => [".md", ".mdx"].includes(extname6(file.relativePath).toLowerCase());
   const isGateCandidate = (file) => isDocFile(file) && !file.relativePath.split("/").some((segment) => SNIPPET_DIRECTORIES.has(segment.toLowerCase()));
@@ -12352,6 +12542,7 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       const verdict = classifyPageGate(file);
       gateByPath.set(file.absolutePath, verdict);
       if (verdict.openapi) (verdict.reason ? withheldSpecRefs : publishedSpecRefs).push(verdict.openapi);
+      if (verdict.openapi && !verdict.reason) publishedSpecPages.push({ ref: verdict.openapi, file: file.relativePath });
       if (verdict.reason) withheldPaths.add(file.absolutePath);
     }
     for (const file of mintignoreFilteredFiles) {
@@ -12455,6 +12646,23 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
   let discovered = files.length;
   const localeConfig = docsConfig.i18n;
   const defaultPageIds = new Set([...referenceMap.values()].filter((reference) => !reference.locale || reference.locale === localeConfig?.defaultLocale).map((reference) => reference.navigationId));
+  const resolvePageIdentity = (path) => {
+    const referenced = exactReferenceMap.get(exactReferenceKey(path)) ?? referenceMap.get(normalizedReferenceKey(path));
+    let locale = referenced?.locale;
+    let navigationId = referenced?.navigationId ?? pageIdFromReference(path, platform === "mintlify");
+    if (!referenced && localeConfig) {
+      for (const entry of localeConfig.locales) {
+        const localized = mintlifyLocalizedReference(path, entry.code, defaultPageIds);
+        if (localized === path) continue;
+        locale = entry.code;
+        navigationId = pageIdFromReference(localized, platform === "mintlify");
+        break;
+      }
+    }
+    if (!navigationId) return null;
+    const isDefaultLocale = !locale || locale === localeConfig?.defaultLocale;
+    return { locale, navigationId, id: isDefaultLocale ? navigationId : `${locale}/${navigationId}` };
+  };
   const routeAliases = [];
   const pageFiles = [...files].sort((left, right) => {
     const leftOrder = referenceOrder.get(normalizedReferenceKey(left.relativePath)) ?? Number.MAX_SAFE_INTEGER;
@@ -12550,7 +12758,6 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       }
       continue;
     }
-    const key = normalizedReferenceKey(file.relativePath);
     let pageGate;
     {
       pageGate = gateByPath.get(file.absolutePath);
@@ -12600,25 +12807,13 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       }
     }
     const isRestrictedPage = Boolean(pageGate?.reason);
-    const referenced = exactReferenceMap.get(exactReferenceKey(file.relativePath)) ?? referenceMap.get(key);
-    let locale = referenced?.locale;
-    let navigationId = referenced?.navigationId ?? pageIdFromReference(file.relativePath, platform === "mintlify");
-    if (!referenced && localeConfig) {
-      for (const entry of localeConfig.locales) {
-        const localized = mintlifyLocalizedReference(file.relativePath, entry.code, defaultPageIds);
-        if (localized === file.relativePath) continue;
-        locale = entry.code;
-        navigationId = pageIdFromReference(localized, platform === "mintlify");
-        break;
-      }
-    }
-    if (!navigationId) {
+    const identity = resolvePageIdentity(file.relativePath);
+    if (!identity) {
       skipped++;
       warnings.push({ code: "invalid-page", message: "Page path could not be normalized safely.", source: file.relativePath });
       continue;
     }
-    const isDefaultLocale = !locale || locale === localeConfig?.defaultLocale;
-    const id = isDefaultLocale ? navigationId : `${locale}/${navigationId}`;
+    const { locale, navigationId, id } = identity;
     let raw = inlineMdxSnippets(
       mintlifyProjectRoot ? importUndeclaredSnippetComponents(readFileSync6(file.absolutePath, "utf8"), file.absolutePath, repositoryDir, mintlifyProjectRoot, snippetExports, snippetAliases, inlineGate, warnings) : injectDocusaurusGlobalImports(readFileSync6(file.absolutePath, "utf8"), globalDocusaurusImports),
       file.absolutePath,
@@ -13267,8 +13462,21 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
     const warnSharedSpec = (path, excluded = []) => {
       warnings.push({ code: "gated-page", message: sharedSpecMessage(path, excluded), source: path });
     };
-    const keptSpecRefs = [...publishedSpecRefs, ...navigationOperationRefs(mintlifyConfig)];
-    const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, pages.filter((page) => !restrictedPages.has(page)));
+    const nameSpec = createSpecAssetNamer();
+    const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, nameSpec, pages.filter((page) => !restrictedPages.has(page)));
+    const navigation = navigationSpecContext(mintlifyConfig, (path) => resolvePageIdentity(path)?.id ?? null);
+    const defaultSources = /* @__PURE__ */ new Set([
+      ...allSpecs.filter((spec) => !spec.pageOnly && spec.tabLabel === void 0).map((spec) => spec.sourcePath),
+      ...remoteApiSpecs.filter((spec) => spec.tabLabel === void 0).map((spec) => spec.url)
+    ]);
+    const keptOperations = (fallbackSource) => {
+      const defaultSpec = defaultSources.size === 0 ? fallbackSource : defaultSources.size === 1 ? [...defaultSources][0] : void 0;
+      const candidates = fallbackSource ? [{ sourcePath: fallbackSource, filename: basename3(fallbackSource) }, ...allSpecs] : allSpecs;
+      const { kept, unowned } = keptOperationRefs(publishedSpecPages, navigation, defaultSpec, candidates);
+      return { kept: kept.filter((ref) => !namesSeveralSpecs(ref, allSpecs)), unowned };
+    };
+    let { kept: keptSpecRefs, unowned: unownedOperations } = keptOperations();
+    const withheldKeys = /* @__PURE__ */ new Set();
     for (const remote of remoteApiSpecs) {
       const { withheld, kept } = withheldOperationKeys({ sourcePath: remote.url, filename: remote.url }, withheldSpecRefs, keptSpecRefs);
       if (withheld.length > 0) {
@@ -13278,9 +13486,10 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
     }
     const withheldOperations = /* @__PURE__ */ new Map();
     for (const spec of allSpecs) {
-      const result = excludeWithheldOperations(spec, withheldSpecRefs, keptSpecRefs);
+      const result = excludeWithheldOperations(spec, withheldSpecRefs, keptSpecRefs, allSpecs);
       spec.content = result.content;
       withheldOperations.set(spec, result.excluded);
+      result.excluded.forEach((operation) => withheldKeys.add(operationKey(operation)));
     }
     const resolvedSpecs = allSpecs.filter((spec) => !spec.pageOnly);
     const pageOnlySpecs = allSpecs.filter((spec) => spec.pageOnly);
@@ -13288,12 +13497,14 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       if (!assets.some((asset) => asset.path === specAssetPath(spec.filename))) {
         assets.push(specAsset(spec.filename, spec.content));
       }
-      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
+      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
     }
     let pageSpecs = resolvedSpecs;
     if (resolvedSpecs.length > 0) {
+      const namedByPages = new Set(pages.filter((page) => !restrictedPages.has(page)).map((page) => specNamedByPage(page.openapi, resolvedSpecs)));
       for (const spec of resolvedSpecs) {
-        spec.generatedNavigation = Boolean(spec.directory) && !publishedSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true));
+        spec.pageReferenced = namedByPages.has(spec);
+        spec.generatedNavigation = Boolean(spec.directory) && !publishedSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, true));
       }
       docsConfig = injectOpenApiSpecs(docsConfig, resolvedSpecs, warnings);
       if (remoteApiSpecs.length > 0) {
@@ -13311,13 +13522,16 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
       const fallback = findOpenApi(files);
       const fallbackContent = fallback ? readSpecFile(fallback.absolutePath, fallback.relativePath, warnings) : void 0;
       if (fallback && fallbackContent) {
-        const filename = basename3(fallback.relativePath);
-        const matches = (ref) => specRefMatches(ref, fallback.relativePath, filename, true);
+        const matches = (ref) => specRefMatches(ref, fallback.relativePath, true);
         if (withheldSpecRefs.some(matches) && !publishedSpecRefs.some(matches)) {
-          quarantinedFiles.push({ path: `${QUARANTINE_DIRECTORY}/assets/${specAssetPath(filename)}`, content: fallbackContent });
+          quarantinedFiles.push({ path: `${QUARANTINE_DIRECTORY}/assets/${specAssetPath(basename3(fallback.relativePath))}`, content: fallbackContent });
           withheldAssetCount++;
         } else {
-          const pruned = excludeWithheldOperations({ sourcePath: fallback.relativePath, filename, content: fallbackContent }, withheldSpecRefs, keptSpecRefs);
+          const filename = nameSpec({ sourcePath: fallback.relativePath, filename: basename3(fallback.relativePath) });
+          const fallbackSpec = { sourcePath: fallback.relativePath, filename, content: fallbackContent };
+          ({ kept: keptSpecRefs, unowned: unownedOperations } = keptOperations(fallback.relativePath));
+          const pruned = excludeWithheldOperations(fallbackSpec, withheldSpecRefs, keptSpecRefs, [fallbackSpec, ...allSpecs]);
+          pruned.excluded.forEach((operation) => withheldKeys.add(operationKey(operation)));
           if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
             assets.push(specAsset(filename, pruned.content));
           }
@@ -13329,13 +13543,22 @@ ${warnings.map((warning) => `- ${warning.message}`).join("\n")}`);
     }
     for (const spec of pageOnlySpecs) {
       if (!assets.some((asset) => asset.path === specAssetPath(spec.filename))) assets.push(specAsset(spec.filename, spec.content));
-      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
+      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
     }
     if (pageOnlySpecs.length > 0) {
       docsConfig = injectOpenApiSpecs(docsConfig, pageOnlySpecs, warnings);
       pageSpecs = [...pageSpecs, ...pageOnlySpecs];
     }
+    const notKeptPublic = [...new Set(unownedOperations.filter((operation) => withheldKeys.has(operationKey(operation))))];
+    if (notKeptPublic.length > 0) {
+      warnings.push({
+        code: "gated-page",
+        message: `${notKeptPublic.length} operation(s) withheld from a published OpenAPI spec (${notKeptPublic.join(", ")}) are also named by a published page or navigation entry that does not say which spec it means, so that reference did not keep them public. Write the spec in its openapi value (for example "openapi.json GET /x") to publish the operation.`
+      });
+    }
     const explainMissingSpec = (key) => {
+      const fits = resolveSpecRef(key, specFileCandidates(files), false);
+      if (fits.kind === "ambiguous") return `several spec files fit that name (${fits.candidates.map((spec) => spec.sourcePath).join(", ")}); write the full path in the page's openapi frontmatter`;
       const sameName = scannedFiles.find((file) => file.relativePath.toLowerCase() === key.toLowerCase());
       if (sameName && sameName.relativePath !== key) return `paths are case-sensitive; the file is at "${sameName.relativePath}"`;
       if (sameName && mintignoreMatcher?.ignores(sameName.relativePath)) return "the file is excluded by .mintignore";
@@ -13675,10 +13898,10 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
   const sourceFavicon = mintlifyConfig?.favicon ?? fernRawConfig?.favicon ?? docusaurusSettings?.favicon;
   const logo = brandVariants(sourceLogo);
   const favicon = brandVariants(sourceFavicon);
-  const logoLight = publicBrandPath(logo.light);
   const logoDark = publicBrandPath(logo.dark);
-  const faviconLight = publicBrandPath(favicon.light);
+  const logoLight = publicBrandPath(logo.light) ?? logoDark;
   const faviconDark = publicBrandPath(favicon.dark);
+  const faviconLight = publicBrandPath(favicon.light) ?? faviconDark;
   if (logoLight) docsConfig = {
     ...docsConfig,
     navbar: {
@@ -13707,15 +13930,30 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
       const decoration = background.decoration;
       const image = publicBrandPath(background.image);
       const imageDark = publicBrandPath(background.imageDark);
-      docsConfig = {
-        ...docsConfig,
-        background: {
-          ...docsConfig.background,
-          ...decoration === "none" || decoration === "grid" || decoration === "gradient" ? { decoration } : {},
-          ...image ? { image } : {},
-          ...imageDark ? { imageDark } : {}
-        }
+      const mapped = {
+        ...docsConfig.background,
+        ...decoration === "none" || decoration === "grid" || decoration === "gradient" ? { decoration } : {},
+        ...image ? { image } : {},
+        ...imageDark ? { imageDark } : {}
       };
+      if (Object.keys(mapped).length > 0) docsConfig = { ...docsConfig, background: mapped };
+      const canvas = background.color && typeof background.color === "object" ? background.color : {};
+      for (const mode of ["light", "dark"]) {
+        if (canvas[mode] === void 0) continue;
+        const hex = typeof canvas[mode] === "string" ? cssColorToHex(canvas[mode]) : void 0;
+        if (!hex) {
+          warnings.push({
+            code: "unsupported-config",
+            message: `background.color.${mode} ${JSON.stringify(canvas[mode])?.slice(0, 40)} is not a hex or rgb() colour (for example #121317) and was dropped, so that mode keeps Thally's default canvas. Use a hex value in docs.json to set it.`,
+            source: "docs.json"
+          });
+          continue;
+        }
+        docsConfig = {
+          ...docsConfig,
+          colors: { ...docsConfig.colors, [mode]: { ...docsConfig.colors?.[mode], background: hex } }
+        };
+      }
     }
   }
   if (platform === "docusaurus") {
@@ -13725,13 +13963,23 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     ...docsConfig,
     favicon: { light: faviconLight, ...faviconDark ? { dark: faviconDark } : {} }
   };
-  const missingBrand = [
-    ...[logo.light, logo.dark].filter((value) => typeof value === "string" && !publicBrandPath(value)),
-    ...[favicon.light, favicon.dark].filter((value) => typeof value === "string" && !publicBrandPath(value))
-  ];
+  const notImported = (variants) => [variants.light, variants.dark].filter((value) => typeof value === "string" && !publicBrandPath(value));
+  const missingLogo = notImported(logo);
+  const missingFavicon = notImported(favicon);
+  const missingBrand = [...missingLogo, ...missingFavicon];
+  const substituted = [
+    ...missingLogo.length > 0 && logoLight ? [`logo (${logoLight})`] : [],
+    ...missingFavicon.length > 0 && faviconLight ? [`favicon (${faviconLight})`] : []
+  ].map((asset) => ` The imported ${asset} is used for both light and dark mode.`).join("");
   if (missingBrand.length > 0) warnings.push({
     code: "unsupported-config",
-    message: `Brand asset(s) were referenced but not imported: ${[...new Set(missingBrand)].join(", ")}. Add these files under public/ or update docs.json.`
+    message: `Brand asset(s) were referenced but not imported: ${[...new Set(missingBrand)].join(", ")}. Add these files under public/ or update docs.json.${substituted}`
+  });
+  const logoHref = sourceLogo && typeof sourceLogo === "object" ? sourceLogo.href : void 0;
+  if (typeof logoHref === "string" && logoHref.trim() && logoHref.trim() !== "/") warnings.push({
+    code: "unsupported-config",
+    message: `logo.href ${JSON.stringify(logoHref.trim().slice(0, 120))} was dropped: the header logo always links to the docs home page. Add it as a navbar link in docs.json if readers need it.`,
+    source: mintlifyConfig ? "docs.json" : "docs.yml"
   });
   if (platform === "mintlify") {
     docsConfig = { ...docsConfig, markdown: { enabled: true } };
@@ -13764,7 +14012,7 @@ ${reasons.map((reason) => `- ${reason}`).join("\n")}` : "No importable Markdown
     message: `Fern global theme ${JSON.stringify(fernRawConfig["global-theme"])} could not be fetched during local migration; local overrides and Thally default styling tokens were applied.`,
     source: "global-theme"
   });
-  if (fernRawConfig?.logo && !fernRawConfig["global-theme"] && !logoLight && !logo.light) warnings.push({
+  if (fernRawConfig?.logo && !fernRawConfig["global-theme"] && !logoLight && !logo.light && !logo.dark) warnings.push({
     code: "unsupported-config",
     message: "Fern supplied a logo through its global theme without a local asset; add a logo path to docs.json after import."
   });