@thallylabs/migrate 0.2.22 → 0.2.24

package/dist/index.js

@@ -16,13 +16,13 @@ import {
 } from "fs";
 import { createRequire } from "module";
 import { basename as basename3, dirname as dirname4, extname as extname6, isAbsolute as isAbsolute2, posix as posix3, relative as relative5, resolve as resolvePath, sep as sep2 } from "path";
-import { parse as parseYaml4 } from "yaml";
+import { parse as parseYaml5 } from "yaml";
 import * as ts4 from "typescript";
 
 // src/components.ts
 import { createHash } from "crypto";
 import { existsSync, lstatSync, readFileSync } from "fs";
-import { basename, dirname, extname, relative as relative2, resolve as resolve2 } from "path";
+import { basename, dirname, extname as extname2, relative as relative2, resolve as resolve2 } from "path";
 import postcss from "postcss";
 import selectorParser from "postcss-selector-parser";
 import remarkMdx2 from "remark-mdx";
@@ -157,6 +157,177 @@ function isThallyBuiltinComponent(name) {
   return THALLY_BUILTIN_COMPONENTS.has(name) || THALLY_BUILTIN_COMPONENTS.has(name.split(".")[0]);
 }
 
+// src/mintlify-extras.ts
+import { extname } from "path";
+
+// src/path.ts
+import { isAbsolute, relative, resolve, sep } from "path";
+var SAFE_SEGMENT = /[^a-z0-9._-]+/gi;
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end--;
+  return value.slice(0, end);
+}
+function trimEdgeSlashes(value) {
+  let start = 0;
+  let end = value.length;
+  while (start < end && value.charCodeAt(start) === 47) start++;
+  while (end > start && value.charCodeAt(end - 1) === 47) end--;
+  return value.slice(start, end);
+}
+function slugifySegment(value, preserveCase = false) {
+  let decoded = value;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+  }
+  const normalized = preserveCase ? decoded : decoded.toLowerCase();
+  return normalized.replace(/\.(?:html?|mdx?)$/i, "").replace(SAFE_SEGMENT, "-").replace(/(^-|-$)/g, "");
+}
+function pageIdFromReference(value, preserveCase = false) {
+  const withoutQuery = value.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!withoutQuery || withoutQuery.includes("\0")) return null;
+  const rawSegments = withoutQuery.split("/").filter(Boolean);
+  if (rawSegments.some((segment) => segment === ".." || segment === ".")) return null;
+  const last = rawSegments.at(-1)?.replace(/\.(?:mdx?|rst|txt)$/i, "") ?? "";
+  const isRootLevelReadme = rawSegments.length === 1 && /^readme$/i.test(last);
+  const collapsesToParent = /^index$/i.test(last) || isRootLevelReadme;
+  const baseSegments = collapsesToParent ? rawSegments.slice(0, -1) : rawSegments;
+  if (!collapsesToParent) {
+    baseSegments[baseSegments.length - 1] = last;
+  }
+  const segments = baseSegments.map((segment) => slugifySegment(segment, preserveCase)).filter(Boolean);
+  return segments.join("/") || "introduction";
+}
+function mintlifyLocalizedReference(value, locale, defaultPageIds = /* @__PURE__ */ new Set()) {
+  const reference = value.replace(/^\/+/, "");
+  const localePrefix = `${locale.toLowerCase()}/`;
+  if (reference.toLowerCase().startsWith(localePrefix)) return reference.slice(localePrefix.length);
+  const sectionPrefix = `${locale.toLowerCase()}-`;
+  if (reference.toLowerCase().startsWith(sectionPrefix)) {
+    const candidate = reference.slice(sectionPrefix.length);
+    const candidateId = pageIdFromReference(candidate, true);
+    if (candidateId && defaultPageIds.has(candidateId)) return candidate;
+  }
+  const segments = reference.split("/");
+  const localeIndex = segments.findIndex((segment) => segment.toLowerCase() === locale.toLowerCase());
+  if (localeIndex > 0) {
+    return [...segments.slice(0, localeIndex), ...segments.slice(localeIndex + 1)].join("/");
+  }
+  return value;
+}
+function resolveWithin(root, candidate) {
+  return resolveWithinRoot(root, candidate, root);
+}
+function resolveWithinRoot(baseDir, candidate, confineRoot) {
+  if (isAbsolute(candidate) || candidate.includes("\0")) {
+    throw new Error(`Unsafe migration path: ${candidate}`);
+  }
+  const target = resolve(baseDir, candidate);
+  const fromRoot = relative(resolve(confineRoot), target);
+  if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+    throw new Error(`Migration path escapes its root: ${candidate}`);
+  }
+  return target;
+}
+function normalizeAssetPath(value) {
+  const normalized = value.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized || normalized.includes("\0")) return null;
+  const segments = normalized.split("/").filter(Boolean);
+  if (segments.some((segment) => segment === "." || segment === "..")) return null;
+  return segments.join("/");
+}
+
+// src/mintlify-extras.ts
+function objectValue(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+var PUBLIC_FALSE_STRINGS = /* @__PURE__ */ new Set(["false", "no", "off", "0"]);
+function isPublicFalse(value) {
+  return value === false || value === 0 || typeof value === "string" && PUBLIC_FALSE_STRINGS.has(value.trim().toLowerCase());
+}
+function isPublicTrue(value) {
+  return value === true || typeof value === "string" && value.trim().toLowerCase() === "true";
+}
+function frontmatterGateReason(data) {
+  const groups = data.groups;
+  const hasGroups = Array.isArray(groups) ? groups.length > 0 : typeof groups === "string" ? groups.trim() !== "" : groups !== void 0 && groups !== null && groups !== false;
+  if (hasGroups) return "frontmatter `groups` restricts it to authenticated groups";
+  if (isPublicFalse(data.public)) return "frontmatter `public: false`";
+  return void 0;
+}
+function navigationGateReason(node) {
+  const groups = node.groups;
+  const isContainer = (entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry) && ["group", "pages", "tab", "groups", "page", "root", "menu", "href"].some((key) => key in entry);
+  const restricted = typeof groups === "string" ? groups.trim() !== "" : Array.isArray(groups) && groups.length > 0 && !groups.every(isContainer);
+  if (restricted) return "its navigation container sets `groups`";
+  if (isPublicFalse(node.public)) return "its navigation container sets `public: false`";
+  return void 0;
+}
+var CONFIG_BASENAME = /(?:^|[.-])(?:config|rc)\.[cm]?js$|^(?:tailwind|postcss|next|eslint|prettier|babel|webpack|vite|vitest|jest|rollup|gulpfile|gruntfile|stylelint|commitlint|lint-staged|svgo|metro)[.-]/i;
+var BUILD_OUTPUT_SEGMENTS = /* @__PURE__ */ new Set(["dist", "build", "coverage"]);
+var FONT_EXTENSIONS = /* @__PURE__ */ new Set([".woff", ".woff2", ".ttf", ".otf"]);
+function isMintlifyServedScriptOrStyle(relativePath) {
+  const extension = extname(relativePath).toLowerCase();
+  if (extension !== ".css" && extension !== ".js") return false;
+  const segments = relativePath.split("/");
+  if (segments.slice(0, -1).some((segment) => BUILD_OUTPUT_SEGMENTS.has(segment.toLowerCase()))) return false;
+  return extension === ".css" || !CONFIG_BASENAME.test(segments[segments.length - 1]);
+}
+function mintlifyFontSources(config) {
+  const fonts = objectValue(config?.fonts);
+  if (!fonts) return [];
+  const found = [];
+  for (const entry of [fonts, objectValue(fonts.heading), objectValue(fonts.body)]) {
+    if (!entry || typeof entry.source !== "string" || !entry.source.trim()) continue;
+    const source = entry.source.trim();
+    const family = typeof entry.family === "string" ? entry.family : "a font";
+    const remote = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(source);
+    const path = remote || /^[a-z]:[\\/]/i.test(source) ? null : normalizeAssetPath(source);
+    found.push({ family, source, path: path && FONT_EXTENSIONS.has(extname(path).toLowerCase()) ? path : null, remote });
+  }
+  return found;
+}
+function mintlifyAppearance(config, warnings) {
+  const appearance = objectValue(config.appearance);
+  const legacy = objectValue(config.modeToggle);
+  const result = {};
+  const isMode = (value) => value === "system" || value === "light" || value === "dark";
+  const skip = (field, value) => {
+    warnings.push({
+      code: "unsupported-config",
+      message: `Ignored invalid ${field} value ${JSON.stringify(value)?.slice(0, 40)}; the appearance default was left unchanged.`
+    });
+  };
+  if (appearance?.default !== void 0) {
+    if (isMode(appearance.default)) result.default = appearance.default;
+    else skip("appearance.default", appearance.default);
+  } else if (legacy?.default !== void 0) {
+    if (isMode(legacy.default)) result.default = legacy.default;
+    else skip("modeToggle.default", legacy.default);
+  }
+  if (appearance?.strict !== void 0) {
+    if (typeof appearance.strict === "boolean") {
+      if (appearance.strict) result.showToggle = false;
+    } else skip("appearance.strict", appearance.strict);
+  } else if (legacy?.isHidden !== void 0) {
+    if (typeof legacy.isHidden === "boolean") {
+      if (legacy.isHidden) result.showToggle = false;
+    } else skip("modeToggle.isHidden", legacy.isHidden);
+  }
+  return result;
+}
+function playgroundDisplay(value, where, warn) {
+  const mode = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (mode === "interactive" || mode === "simple" || mode === "none") return mode;
+  if (mode === "auth") {
+    warn?.(`${where} "auth" requires reader sign-in, which Thally does not support. Migrated as "simple" (no Try it). Set it to "interactive" to allow everyone.`);
+    return "simple";
+  }
+  warn?.(`${where} ${JSON.stringify(value)} is not one of interactive, simple, none, auth and was dropped.`);
+  return void 0;
+}
+
 // src/mdx.ts
 function titleFromId(id) {
   const value = id.split("/").at(-1) ?? id;
@@ -265,7 +436,7 @@ function unwrapDocusaurusMdxCodeBlocks(body) {
   return isMdxCodeBlock ? body : output.join("\n");
 }
 var HTML_ID = /^[^\s"'<>`{}&]+$/u;
-function normalizeExplicitHeadingIds(raw, warn) {
+function normalizeExplicitHeadingIds(raw, warn, options = {}) {
   const { front, body } = splitFrontmatterBlock(raw);
   return front + replaceOutsideCode(body, (segment) => segment.split("\n").map((line) => {
     if (!/^[ \t]{0,3}#{1,6}[ \t]+/.test(line)) return line;
@@ -276,13 +447,15 @@ function normalizeExplicitHeadingIds(raw, warn) {
         const id = trimmed.slice(marker + 3, -1);
         const heading = trimmed.slice(0, marker).trimEnd();
         if (/[{}]/.test(id)) return line;
-        if (HTML_ID.test(id)) return `<a id="${id}"></a>
+        const usable = options.headingMarkers ? id && !/\s/.test(id) && !id.includes("*/") : HTML_ID.test(id);
+        if (usable && options.headingMarkers) return `${heading} ${headingIdMarker(id)}`;
+        if (usable) return `<a id="${id}"></a>
 ${heading}`;
-        warn?.(`Heading anchor {#${id}} is not a valid HTML id and was removed from "${heading.replace(/^\s*#+\s*/, "")}".`);
+        warn?.(`Heading anchor {#${id}} ${options.headingMarkers ? 'contains whitespace or "*/"' : "is not a valid HTML id"} and was removed from "${heading.replace(/^\s*#+\s*/, "")}".`);
         return heading;
       }
     }
-    if (trimmed.endsWith("*/}")) {
+    if (!options.headingMarkers && !options.keepIdComments && trimmed.endsWith("*/}")) {
       const marker = trimmed.lastIndexOf(" {/*");
       if (marker >= 0) {
         const comment = trimmed.slice(marker + 4, -3).trim();
@@ -296,6 +469,44 @@ ${trimmed.slice(0, marker).trimEnd()}`;
     return line;
   }).join("\n"));
 }
+function headingIdMarker(id) {
+  return `{/* #${id} */}`;
+}
+function mintlifyHeadingSlug(text2) {
+  return text2.replace(/\u200b/g, "").normalize("NFC").trim().toLowerCase().replace(/[.\s]+/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "").replace(/[^\p{L}\p{M}\p{N}_\-+&/\u2019\u201c\u201d\u2014\u2013\u2192]/gu, "");
+}
+function thallyHeadingSlug(text2) {
+  return text2.normalize("NFC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/(^-|-$)/g, "");
+}
+function typesetQuotes(text2) {
+  return text2.split(/(`[^`]*`|<[^>]*>|\]\([^)]*\))/).map((part, index) => {
+    if (index % 2) return part;
+    return part.replace(/(^|[\s([{\u2014\u2013])"/g, "$1\u201C").replace(/"/g, "\u201D").replace(/(^|[\s([{\u2014\u2013\u201c])'(?=\S)/g, "$1\u2018").replace(/'/g, "\u2019");
+  }).join("");
+}
+function plainHeadingText(source) {
+  return source.replace(/\{\/\*[\s\S]*?\*\/\}/g, " ").replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/<\/?[A-Za-z][^>]*>/g, "").replace(/`([^`]*)`/g, "$1").replace(/(\*\*|__|~~|\*)/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/\\([\\`*_{}[\]()#+.!&<>|~-])/g, "$1");
+}
+function markMintlifyHeadings(body) {
+  let fence;
+  return body.split("\n").map((line) => {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (marker) {
+      if (!fence) fence = marker[1];
+      else if (marker[1][0] === fence[0] && marker[1].length >= fence.length && /^\s*$/.test(line.slice(marker[0].length))) fence = void 0;
+      return line;
+    }
+    if (fence) return line;
+    const heading = line.match(/^( {0,3}#{2,6}[ \t]+)(.+?)(?:[ \t]+#+)?[ \t]*$/);
+    if (!heading) return line;
+    const explicit = heading[2].match(/^(.*?)([ \t]*\{\/\*[ \t]*#\S+[ \t]*\*\/\})$/);
+    const source = typesetQuotes(explicit ? explicit[1] : heading[2]);
+    if (explicit) return `${heading[1]}${source}${explicit[2]}`;
+    const text2 = plainHeadingText(source);
+    const id = mintlifyHeadingSlug(text2);
+    return `${heading[1]}${source}${id && id !== thallyHeadingSlug(text2) ? ` ${headingIdMarker(id)}` : ""}`;
+  }).join("\n");
+}
 var GLOBAL_DOCUSARUS_COMPONENTS = /* @__PURE__ */ new Set([
   "Tabs",
   "TabItem",
@@ -1257,7 +1468,12 @@ function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   const runMintlify = platform === "mintlify";
   const runDocusaurus = platform === "docusaurus";
   const sourceBody = runDocusaurus && unwrapMdxCodeBlocks ? unwrapDocusaurusMdxCodeBlocks(body) : body;
-  let rewritten = normalizeDocusaurusAdmonitions(normalizeExplicitHeadingIds(runFern ? normalizeFernFileTrees(normalizeFernCallouts(normalizeNestedCodeFences(sourceBody))) : normalizeNestedCodeFences(sourceBody)));
+  let rewritten = normalizeDocusaurusAdmonitions(normalizeExplicitHeadingIds(
+    runFern ? normalizeFernFileTrees(normalizeFernCallouts(normalizeNestedCodeFences(sourceBody))) : normalizeNestedCodeFences(sourceBody),
+    void 0,
+    { headingMarkers: runMintlify }
+  ));
+  if (runMintlify) rewritten = markMintlifyHeadings(rewritten);
   if (runDocusaurus) {
     rewritten = replaceOutsideCode(rewritten, (segment) => segment.replace(
       /:([+\w-]+):/g,
@@ -1324,16 +1540,25 @@ function parseMarkdownPage(input) {
     body = `${body.slice(0, heading.start)}${body.slice(heading.end)}`.trim();
   }
   const navTitle = typeof parsed.data.sidebarTitle === "string" && parsed.data.sidebarTitle.trim() ? parsed.data.sidebarTitle.trim() : typeof parsed.data.navTitle === "string" && parsed.data.navTitle.trim() ? parsed.data.navTitle.trim() : void 0;
+  const icon = typeof parsed.data.icon === "string" && parsed.data.icon.trim() ? parsed.data.icon.trim() : void 0;
+  const iconType = icon && ["regular", "solid", "outline", "brands"].includes(String(parsed.data.iconType)) ? parsed.data.iconType : void 0;
+  const meta = {};
+  for (const [source, field] of PAGE_META_FIELDS) {
+    const value = parsed.data[source];
+    if (typeof value === "string" && value.trim()) meta[field] = value.trim();
+  }
   const badge = typeof parsed.data.tag === "string" && parsed.data.tag.trim() ? parsed.data.tag.trim() : typeof parsed.data.badge === "string" && parsed.data.badge.trim() ? parsed.data.badge.trim() : void 0;
   const sourceMode = typeof parsed.data.mode === "string" ? parsed.data.mode : void 0;
   const mode = sourceMode === "frame" ? "wide" : ["default", "wide", "custom", "center", "home"].includes(sourceMode ?? "") ? sourceMode : void 0;
-  const description = typeof parsed.data.description === "string" && parsed.data.description.trim() ? parsed.data.description.trim() : firstParagraph(body);
+  const description = typeof parsed.data.description === "string" && parsed.data.description.trim() ? parsed.data.description.trim() : typeof parsed.data.openapi === "string" && parsed.data.openapi.trim() ? "" : firstParagraph(body);
   return {
     id: identity.id,
     navigationId: identity.navigationId,
     locale: identity.locale,
     title,
     navTitle,
+    icon,
+    iconType,
     description,
     ...input.platform === "docusaurus" || input.platform === "fern" ? { descriptionPlacement: "body" } : {},
     badge,
@@ -1341,6 +1566,7 @@ function parseMarkdownPage(input) {
     mode,
     hidden: parsed.data.hidden === true ? true : void 0,
     noindex: parsed.data.noindex === true || parsed.data.noindex === "true" ? true : void 0,
+    ...Object.keys(meta).length > 0 ? { meta } : {},
     openapi: typeof parsed.data.openapi === "string" ? parsed.data.openapi.trim() : void 0,
     ...apiFrontmatter(parsed.data, input.warn),
     body,
@@ -1348,9 +1574,21 @@ function parseMarkdownPage(input) {
     ...parsed.error ? { frontmatterError: parsed.error } : {}
   };
 }
+var PAGE_META_FIELDS = [
+  ["og:title", "ogTitle"],
+  ["og:description", "ogDescription"],
+  ["og:image", "ogImage"],
+  ["twitter:title", "twitterTitle"],
+  ["twitter:description", "twitterDescription"],
+  ["twitter:image", "twitterImage"]
+];
 var AUTH_METHODS = /* @__PURE__ */ new Set(["bearer", "basic", "key", "none"]);
 function apiFrontmatter(data, warn) {
   const result = {};
+  if (data.playground !== void 0 && data.playground !== null) {
+    const display = playgroundDisplay(data.playground, `The page's "playground" frontmatter`, warn);
+    if (display) result.playground = display;
+  }
   if (data.api !== void 0 && data.api !== null) {
     if (typeof data.api === "string" && data.api.trim()) result.api = data.api.trim();
     else warn?.(`The page's "api" frontmatter is not a "METHOD url-or-path" string and was dropped.`);
@@ -1363,84 +1601,6 @@ function apiFrontmatter(data, warn) {
   return result;
 }
 
-// src/path.ts
-import { isAbsolute, relative, resolve, sep } from "path";
-var SAFE_SEGMENT = /[^a-z0-9._-]+/gi;
-function trimTrailingSlashes(value) {
-  let end = value.length;
-  while (end > 0 && value.charCodeAt(end - 1) === 47) end--;
-  return value.slice(0, end);
-}
-function trimEdgeSlashes(value) {
-  let start = 0;
-  let end = value.length;
-  while (start < end && value.charCodeAt(start) === 47) start++;
-  while (end > start && value.charCodeAt(end - 1) === 47) end--;
-  return value.slice(start, end);
-}
-function slugifySegment(value, preserveCase = false) {
-  let decoded = value;
-  try {
-    decoded = decodeURIComponent(value);
-  } catch {
-  }
-  const normalized = preserveCase ? decoded : decoded.toLowerCase();
-  return normalized.replace(/\.(?:html?|mdx?)$/i, "").replace(SAFE_SEGMENT, "-").replace(/(^-|-$)/g, "");
-}
-function pageIdFromReference(value, preserveCase = false) {
-  const withoutQuery = value.split(/[?#]/, 1)[0].replace(/\\/g, "/").replace(/^\/+/, "");
-  if (!withoutQuery || withoutQuery.includes("\0")) return null;
-  const rawSegments = withoutQuery.split("/").filter(Boolean);
-  if (rawSegments.some((segment) => segment === ".." || segment === ".")) return null;
-  const last = rawSegments.at(-1)?.replace(/\.(?:mdx?|rst|txt)$/i, "") ?? "";
-  const isRootLevelReadme = rawSegments.length === 1 && /^readme$/i.test(last);
-  const collapsesToParent = /^index$/i.test(last) || isRootLevelReadme;
-  const baseSegments = collapsesToParent ? rawSegments.slice(0, -1) : rawSegments;
-  if (!collapsesToParent) {
-    baseSegments[baseSegments.length - 1] = last;
-  }
-  const segments = baseSegments.map((segment) => slugifySegment(segment, preserveCase)).filter(Boolean);
-  return segments.join("/") || "introduction";
-}
-function mintlifyLocalizedReference(value, locale, defaultPageIds = /* @__PURE__ */ new Set()) {
-  const reference = value.replace(/^\/+/, "");
-  const localePrefix = `${locale.toLowerCase()}/`;
-  if (reference.toLowerCase().startsWith(localePrefix)) return reference.slice(localePrefix.length);
-  const sectionPrefix = `${locale.toLowerCase()}-`;
-  if (reference.toLowerCase().startsWith(sectionPrefix)) {
-    const candidate = reference.slice(sectionPrefix.length);
-    const candidateId = pageIdFromReference(candidate, true);
-    if (candidateId && defaultPageIds.has(candidateId)) return candidate;
-  }
-  const segments = reference.split("/");
-  const localeIndex = segments.findIndex((segment) => segment.toLowerCase() === locale.toLowerCase());
-  if (localeIndex > 0) {
-    return [...segments.slice(0, localeIndex), ...segments.slice(localeIndex + 1)].join("/");
-  }
-  return value;
-}
-function resolveWithin(root, candidate) {
-  return resolveWithinRoot(root, candidate, root);
-}
-function resolveWithinRoot(baseDir, candidate, confineRoot) {
-  if (isAbsolute(candidate) || candidate.includes("\0")) {
-    throw new Error(`Unsafe migration path: ${candidate}`);
-  }
-  const target = resolve(baseDir, candidate);
-  const fromRoot = relative(resolve(confineRoot), target);
-  if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
-    throw new Error(`Migration path escapes its root: ${candidate}`);
-  }
-  return target;
-}
-function normalizeAssetPath(value) {
-  const normalized = value.replace(/\\/g, "/").replace(/^\/+/, "");
-  if (!normalized || normalized.includes("\0")) return null;
-  const segments = normalized.split("/").filter(Boolean);
-  if (segments.some((segment) => segment === "." || segment === "..")) return null;
-  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"]);
@@ -2468,10 +2628,10 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
   }
   function expandCandidates(candidate) {
     const candidates = [candidate];
-    if (!extname(candidate)) {
+    if (!extname2(candidate)) {
       candidates.push(...[".tsx", ".jsx", ".ts", ".js", ".mjs", ".json"].map((extension) => candidate + extension));
       candidates.push(...["index.tsx", "index.jsx", "index.ts", "index.js"].map((name) => resolve2(candidate, name)));
-    } else if (extname(candidate) === ".js") {
+    } else if (extname2(candidate) === ".js") {
       candidates.push(candidate.slice(0, -3) + ".ts", candidate.slice(0, -3) + ".tsx");
     }
     return candidates;
@@ -2512,7 +2672,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
       checkedFile(path);
       const size = lstatSync(path).size;
       if (size > MAX_FILE_BYTES || copiedBytes + stagedBytes + size > MAX_COMPONENT_BYTES || copied.size + staged.size >= MAX_COMPONENT_FILES) throw new Error("component migration budget exceeded");
-      const extension = extname(path).toLowerCase();
+      const extension = extname2(path).toLowerCase();
       if (!CODE_EXTENSIONS.has(extension) && !DATA_EXTENSIONS.has(extension)) throw new Error(`unsupported dependency file type ${extension}`);
       stagedBytes += size;
       const content = readFileSync(path);
@@ -2608,7 +2768,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
     if (size > MAX_FILE_BYTES || copiedBytes + size > MAX_COMPONENT_BYTES || copied.size >= MAX_COMPONENT_FILES) {
       throw new Error("component migration budget exceeded");
     }
-    const publicName = `migrated-${hash(relative2(confined, path))}${extname(path).toLowerCase()}`;
+    const publicName = `migrated-${hash(relative2(confined, path))}${extname2(path).toLowerCase()}`;
     const destination = `public/${publicName}`;
     if (!copied.has(destination)) {
       copied.set(destination, { path: destination, content: readFileSync(path) });
@@ -2643,7 +2803,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
   function transform(raw, currentFile) {
     const parsedFrontmatter = parseFrontmatter(raw).content;
     const frontmatter = raw.slice(0, raw.length - parsedFrontmatter.length);
-    const content = normalizeExplicitHeadingIds(normalizeIndentedFences(normalizeHtmlComments(parsedFrontmatter)));
+    const content = normalizeExplicitHeadingIds(normalizeIndentedFences(normalizeHtmlComments(parsedFrontmatter)), void 0, { keepIdComments: true });
     let tree;
     try {
       tree = parser.parse(content);
@@ -2761,7 +2921,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           }
           continue;
         }
-        if (bindings.length && RESCUABLE_ASSET_EXTENSIONS.has(extname(specifier).toLowerCase()) && !bindings.some((binding) => usedAsJsxTagName(binding.local))) {
+        if (bindings.length && RESCUABLE_ASSET_EXTENSIONS.has(extname2(specifier).toLowerCase()) && !bindings.some((binding) => usedAsJsxTagName(binding.local))) {
           try {
             const href = copyPublicAsset(resolveDependency(specifier, currentFile));
             edits.push({
@@ -2792,7 +2952,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
         try {
           const sourcePath = resolveDependency(specifier, currentFile);
           const path = copyGraph(sourcePath);
-          const isSvgUsedAsTag = extname(path).toLowerCase() === ".svg" && bindings.some((binding) => usedAsJsxTagName(binding.local));
+          const isSvgUsedAsTag = extname2(path).toLowerCase() === ".svg" && bindings.some((binding) => usedAsJsxTagName(binding.local));
           for (const binding of bindings) {
             const registerPath = isSvgUsedAsTag ? wrapSvgAsComponent(path) : path;
             const registerImported = isSvgUsedAsTag ? "default" : binding.imported;
@@ -2831,7 +2991,7 @@ function createComponentMigrator(siteRoot, confinementRoot, warnings, sourceIden
           const importStart = node.position.start.offset + statement.getStart(ast);
           const importEnd = node.position.start.offset + statement.end;
           let rescuedAssetHref;
-          if (RESCUABLE_ASSET_EXTENSIONS.has(extname(specifier).toLowerCase())) {
+          if (RESCUABLE_ASSET_EXTENSIONS.has(extname2(specifier).toLowerCase())) {
             const usedAsJsxTag = bindings.some((binding) => hasExpressionReference(/* @__PURE__ */ new Set([binding.local]), { includeDirectTags: true }));
             if (!usedAsJsxTag) {
               try {
@@ -3206,6 +3366,21 @@ function withoutFencedCode(content) {
     return line;
   }).join("\n");
 }
+function navbarLinkButtons(css) {
+  const buttons = [];
+  postcss2.parse(css).walkRules((rule) => {
+    const match = /^(?:li)?\.navbar-link\s+a\[href(\*)?=["']([^"']+)["']\]$/.exec(rule.selector.trim());
+    if (!match) return;
+    let background;
+    let color;
+    rule.walkDecls((decl) => {
+      if (decl.prop === "background-color" || decl.prop === "background") background = decl.value;
+      else if (decl.prop === "color") color = decl.value;
+    });
+    if (background) buttons.push({ href: match[2], exact: !match[1], background, ...color ? { color } : {} });
+  });
+  return buttons;
+}
 function authoredStyleNames(contents) {
   const classes = /* @__PURE__ */ new Set();
   const ids = /* @__PURE__ */ new Set();
@@ -3295,89 +3470,6 @@ import { parse as parseYaml2 } from "yaml";
 // src/navigation.ts
 import { existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync2, realpathSync } from "fs";
 import { dirname as dirname2, extname as extname3, relative as relative3 } from "path";
-
-// src/mintlify-extras.ts
-import { extname as extname2 } from "path";
-function objectValue(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
-}
-var PUBLIC_FALSE_STRINGS = /* @__PURE__ */ new Set(["false", "no", "off", "0"]);
-function isPublicFalse(value) {
-  return value === false || value === 0 || typeof value === "string" && PUBLIC_FALSE_STRINGS.has(value.trim().toLowerCase());
-}
-function isPublicTrue(value) {
-  return value === true || typeof value === "string" && value.trim().toLowerCase() === "true";
-}
-function frontmatterGateReason(data) {
-  const groups = data.groups;
-  const hasGroups = Array.isArray(groups) ? groups.length > 0 : typeof groups === "string" ? groups.trim() !== "" : groups !== void 0 && groups !== null && groups !== false;
-  if (hasGroups) return "frontmatter `groups` restricts it to authenticated groups";
-  if (isPublicFalse(data.public)) return "frontmatter `public: false`";
-  return void 0;
-}
-function navigationGateReason(node) {
-  const groups = node.groups;
-  const isContainer = (entry) => typeof entry === "object" && entry !== null && !Array.isArray(entry) && ["group", "pages", "tab", "groups", "page", "root", "menu", "href"].some((key) => key in entry);
-  const restricted = typeof groups === "string" ? groups.trim() !== "" : Array.isArray(groups) && groups.length > 0 && !groups.every(isContainer);
-  if (restricted) return "its navigation container sets `groups`";
-  if (isPublicFalse(node.public)) return "its navigation container sets `public: false`";
-  return void 0;
-}
-var CONFIG_BASENAME = /(?:^|[.-])(?:config|rc)\.[cm]?js$|^(?:tailwind|postcss|next|eslint|prettier|babel|webpack|vite|vitest|jest|rollup|gulpfile|gruntfile|stylelint|commitlint|lint-staged|svgo|metro)[.-]/i;
-var BUILD_OUTPUT_SEGMENTS = /* @__PURE__ */ new Set(["dist", "build", "coverage"]);
-var FONT_EXTENSIONS = /* @__PURE__ */ new Set([".woff", ".woff2", ".ttf", ".otf"]);
-function isMintlifyServedScriptOrStyle(relativePath) {
-  const extension = extname2(relativePath).toLowerCase();
-  if (extension !== ".css" && extension !== ".js") return false;
-  const segments = relativePath.split("/");
-  if (segments.slice(0, -1).some((segment) => BUILD_OUTPUT_SEGMENTS.has(segment.toLowerCase()))) return false;
-  return extension === ".css" || !CONFIG_BASENAME.test(segments[segments.length - 1]);
-}
-function mintlifyFontSources(config) {
-  const fonts = objectValue(config?.fonts);
-  if (!fonts) return [];
-  const found = [];
-  for (const entry of [fonts, objectValue(fonts.heading), objectValue(fonts.body)]) {
-    if (!entry || typeof entry.source !== "string" || !entry.source.trim()) continue;
-    const source = entry.source.trim();
-    const family = typeof entry.family === "string" ? entry.family : "a font";
-    const remote = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(source);
-    const path = remote || /^[a-z]:[\\/]/i.test(source) ? null : normalizeAssetPath(source);
-    found.push({ family, source, path: path && FONT_EXTENSIONS.has(extname2(path).toLowerCase()) ? path : null, remote });
-  }
-  return found;
-}
-function mintlifyAppearance(config, warnings) {
-  const appearance = objectValue(config.appearance);
-  const legacy = objectValue(config.modeToggle);
-  const result = {};
-  const isMode = (value) => value === "system" || value === "light" || value === "dark";
-  const skip = (field, value) => {
-    warnings.push({
-      code: "unsupported-config",
-      message: `Ignored invalid ${field} value ${JSON.stringify(value)?.slice(0, 40)}; the appearance default was left unchanged.`
-    });
-  };
-  if (appearance?.default !== void 0) {
-    if (isMode(appearance.default)) result.default = appearance.default;
-    else skip("appearance.default", appearance.default);
-  } else if (legacy?.default !== void 0) {
-    if (isMode(legacy.default)) result.default = legacy.default;
-    else skip("modeToggle.default", legacy.default);
-  }
-  if (appearance?.strict !== void 0) {
-    if (typeof appearance.strict === "boolean") {
-      if (appearance.strict) result.showToggle = false;
-    } else skip("appearance.strict", appearance.strict);
-  } else if (legacy?.isHidden !== void 0) {
-    if (typeof legacy.isHidden === "boolean") {
-      if (legacy.isHidden) result.showToggle = false;
-    } else skip("modeToggle.isHidden", legacy.isHidden);
-  }
-  return result;
-}
-
-// src/navigation.ts
 var MAX_MINTLIFY_CONFIG_BYTES = 2e7;
 function addMintlifyDirectoryRedirects(config, pages) {
   const pageIds = new Set(pages.map((page) => page.id));
@@ -3448,34 +3540,37 @@ function addMintlifyHomepageRedirects(config, pages) {
     }
   }
   const homepage = config.tabs.filter((tab) => !tab.hidden).map((tab) => firstPage([...tab.pages ?? [], ...tab.groups ?? []])).find(Boolean);
-  if (!homepage || homepage === "introduction") return config;
+  if (!homepage) return config;
   const redirects = [...config.redirects ?? []];
   const sources = new Set(redirects.map((redirect) => redirect.source.replace(/\/$/, "") || "/"));
-  const roots = ["", ...(config.i18n?.locales ?? []).filter((locale) => locale.code !== config.i18n?.defaultLocale).map((locale) => locale.code)];
+  const roots = ["", ...(config.i18n?.locales ?? []).filter((locale) => locale.code !== config.i18n?.defaultLocale).filter((locale) => homepage !== "introduction" || pages.some((page) => page.locale === locale.code && page.navigationId === homepage)).map((locale) => locale.code)];
   for (const locale of roots) {
     const source = locale ? `/${locale}` : "/";
     if (sources.has(source)) continue;
-    redirects.push({ source, destination: `${locale ? `/${locale}` : ""}/${homepage}`, permanent: false });
+    redirects.push({ source, destination: `${locale ? `/${locale}` : ""}/${homepage}`, permanent: true });
   }
   return { ...config, redirects };
 }
 var LANGUAGE_LABELS = {
-  ar: "Arabic",
-  de: "German",
+  ar: "\u0627\u0644\u0639\u0631\u0628\u064A\u0629",
+  de: "Deutsch",
   en: "English",
-  es: "Spanish",
-  fr: "French",
-  hi: "Hindi",
-  it: "Italian",
-  ja: "Japanese",
-  ko: "Korean",
-  nl: "Dutch",
-  pl: "Polish",
-  pt: "Portuguese",
-  ru: "Russian",
-  tr: "Turkish",
-  uk: "Ukrainian",
-  zh: "Chinese"
+  es: "Espa\xF1ol",
+  fr: "Fran\xE7ais",
+  hi: "\u0939\u093F\u0928\u094D\u0926\u0940",
+  it: "Italiano",
+  ja: "\u65E5\u672C\u8A9E",
+  ko: "\uD55C\uAD6D\uC5B4",
+  nl: "Nederlands",
+  pl: "Polski",
+  pt: "Portugu\xEAs",
+  "pt-BR": "Portugu\xEAs (BR)",
+  ru: "\u0420\u0443\u0441\u0441\u043A\u0438\u0439",
+  tr: "T\xFCrk\xE7e",
+  uk: "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0430",
+  zh: "\u7B80\u4F53\u4E2D\u6587",
+  "zh-Hans": "\u7B80\u4F53\u4E2D\u6587",
+  "zh-Hant": "\u7E41\u9AD4\u4E2D\u6587"
 };
 function objectValue2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
@@ -3940,11 +4035,35 @@ function convertContainerToTabs(containerValue, context, fallbackTab, trace, dep
   }] : [];
 }
 function projectedTheme(value) {
-  if (value === "maple") return "maple";
-  if (["aspen", "luma", "sequoia"].includes(String(value))) return "sharp";
+  if (value === "maple" || value === "aspen") return "maple";
+  if (["luma", "sequoia"].includes(String(value))) return "sharp";
   if (["almond", "palm"].includes(String(value))) return "minimal";
   return typeof value === "string" ? "default" : void 0;
 }
+function projectedColors(value, warnings) {
+  const colors = objectValue2(value);
+  if (!colors) {
+    if (value !== void 0) warnings.push({ code: "unsupported-config", message: "colors is not an object with a primary hex colour and was dropped.", source: "docs.json" });
+    return void 0;
+  }
+  const hex = (entry, key) => {
+    const match = typeof entry === "string" ? /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(entry.trim()) : null;
+    if (!match) {
+      if (entry !== void 0) warnings.push({ code: "unsupported-config", message: `colors.${key} ${JSON.stringify(entry)} is not a 3- or 6-digit hex colour (for example #16a34a) and was dropped.`, source: "docs.json" });
+      return void 0;
+    }
+    const digits = match[1].length === 3 ? [...match[1]].map((digit) => digit + digit).join("") : match[1];
+    return `#${digits.toLowerCase()}`;
+  };
+  const primary = hex(colors.primary, "primary");
+  const light = hex(colors.light, "light") ?? primary;
+  const dark = hex(colors.dark, "dark") ?? primary;
+  if (!primary) {
+    if (colors.primary === void 0) warnings.push({ code: "unsupported-config", message: "colors has no primary hex colour, so none of its colours were migrated.", source: "docs.json" });
+    return void 0;
+  }
+  return { light: { accent: primary, primary: dark ?? primary }, dark: { accent: light ?? primary, primary: light ?? primary } };
+}
 function projectedNavbar(value) {
   const navbar = objectValue2(value);
   if (!navbar) return void 0;
@@ -3960,7 +4079,8 @@ function projectedNavbar(value) {
   const primaryHref = projectedHref(primaryValue?.href);
   const primary = primaryValue && primaryHref ? {
     label: typeof primaryValue.label === "string" ? primaryValue.label : primaryValue.type === "github" ? "GitHub" : "Get started",
-    href: primaryHref
+    href: primaryHref,
+    ...primaryValue.type === "github" ? { type: "github" } : {}
   } : void 0;
   return links.length > 0 || primary ? { ...links.length > 0 ? { links } : {}, ...primary ? { primary } : {} } : void 0;
 }
@@ -4040,8 +4160,24 @@ function projectedCompatibleConfig(config, warnings) {
   const headingFont = projectedFont(objectValue2(config.fonts)?.heading);
   const feedback = objectValue2(config.feedback);
   const seo = objectValue2(config.seo);
+  const contextualOptions = Array.isArray(objectValue2(config.contextual)?.options) ? objectValue2(config.contextual).options : [];
+  const projectedContextual = contextualOptions.filter((option) => typeof option === "string" && ["copy", "view", "chatgpt", "claude", "perplexity"].includes(option));
+  const droppedContextual = contextualOptions.filter((option) => !projectedContextual.includes(option));
+  if (droppedContextual.length > 0) {
+    warnings.push({ code: "unsupported-config", message: `contextual.options entries not supported by the page menu were dropped: ${droppedContextual.map((option) => typeof option === "string" ? option : "custom entry").join(", ")}.`, source: "docs.json" });
+  }
+  const rawMetatags = Object.entries(objectValue2(seo?.metatags) ?? {});
+  const httpEquivNames = /* @__PURE__ */ new Set(["refresh", "set-cookie", "location", "content-security-policy", "content-security-policy-report-only", "content-type", "default-style", "x-ua-compatible"]);
+  const validMetatag = (entry) => /^[\w:.-]+$/.test(entry[0]) && !entry[0].toLowerCase().startsWith("http-equiv") && !httpEquivNames.has(entry[0].toLowerCase()) && typeof entry[1] === "string" && entry[1].length <= 1e3 && ![...entry[1]].some((character) => character.charCodeAt(0) < 32);
+  const metatagEntries = rawMetatags.filter(validMetatag);
+  const droppedMetatags = rawMetatags.filter((entry) => !validMetatag(entry)).map(([key]) => key);
+  if (droppedMetatags.length > 0) {
+    warnings.push({ code: "unsupported-config", message: `seo.metatags entries were dropped because the name is not a plain meta name, is an http-equiv directive, or the value is not a string of at most 1000 characters: ${droppedMetatags.join(", ")}.`, source: "docs.json" });
+  }
+  const projectedMetatags = metatagEntries.length > 0 ? Object.fromEntries(metatagEntries) : void 0;
+  const projectedColorsValue = projectedColors(config.colors, warnings);
   const iconLibrary = objectValue2(config.icons)?.library;
-  const projectedIconLibrary = ["lucide", "fontawesome", "tabler"].includes(String(iconLibrary)) ? String(iconLibrary) : void 0;
+  const projectedIconLibrary = iconLibrary === void 0 ? "fontawesome" : ["lucide", "fontawesome", "tabler"].includes(String(iconLibrary)) ? String(iconLibrary) : void 0;
   const docsNavbar = projectedNavbar(config.navbar);
   const legacyRaw = legacyTopbarNavbar(config);
   const legacyNavbar = projectedNavbar(legacyRaw);
@@ -4069,6 +4205,8 @@ function projectedCompatibleConfig(config, warnings) {
   const projectedNavigation = navbarLinks.length > 0 || navbar?.primary ? { ...navbarLinks.length > 0 ? { links: navbarLinks } : {}, ...navbar?.primary ? { primary: navbar.primary } : {} } : void 0;
   return {
     ...projectedTheme(config.theme) ? { theme: projectedTheme(config.theme) } : {},
+    ...projectedContextual.length > 0 ? { contextual: { options: projectedContextual } } : {},
+    ...projectedColorsValue ? { colors: projectedColorsValue } : {},
     ...projectedIconLibrary ? { icons: { library: projectedIconLibrary } } : {},
     ...bannerContent ? {
       banner: {
@@ -4086,10 +4224,19 @@ function projectedCompatibleConfig(config, warnings) {
     ...projectedNavigation ? { navbar: projectedNavigation } : {},
     ...projectedFooter(config.footer) ? { footer: projectedFooter(config.footer) } : {},
     ...bodyFont || headingFont ? { fonts: { ...bodyFont ? { body: bodyFont } : {}, ...headingFont ? { heading: headingFont } : {} } } : {},
-    ...seo?.indexing === "all" ? { seo: { indexing: "all" } } : {},
+    // Mintlify titles pages "<title> - <site name>" unless `og:title` overrides them,
+    // and its sitemap lists navigation pages only.
+    seo: { ...seo?.indexing === "all" ? { indexing: "all" } : {}, titleSeparator: " - ", sitemap: "navigable", ...projectedMetatags ? { metatags: projectedMetatags } : {} },
     ...typeof feedback?.thumbsRating === "boolean" ? { feedback: { thumbsRating: feedback.thumbsRating } } : {}
   };
 }
+function projectedApi(config, warnings) {
+  const mdx = projectedApiMdx(config, warnings).api?.mdx;
+  const raw = objectValue2(objectValue2(config.api)?.playground)?.display;
+  const display = raw === void 0 ? void 0 : playgroundDisplay(raw, "api.playground.display", (message) => warnings.push({ code: "unsupported-config", message }));
+  if (!mdx && !display) return {};
+  return { api: { ...mdx ? { mdx } : {}, ...display ? { playground: { display } } : {} } };
+}
 function projectedApiMdx(config, warnings) {
   const mdx = objectValue2(objectValue2(config.api)?.mdx);
   if (!mdx) return {};
@@ -4319,7 +4466,7 @@ function projectMintlifyNavigation(config, options = {}) {
     if (!landing) return [];
     const firstSegment = landing.split("/")[0];
     const prefix = firstSegment === label ? label : "";
-    return [{ label, prefix, href: `/${landing}`, ...entry === defaultVersion ? { default: true } : {} }];
+    return [{ label, prefix, href: `/${landing}`, ...entry === defaultVersion ? { default: true } : {}, ...entry.hidden === true ? { hidden: true } : {} }];
   }) : [];
   if (versions.length > 1) {
     tabs = annotateVersions(tabs);
@@ -4355,7 +4502,7 @@ function projectMintlifyNavigation(config, options = {}) {
         ...shortcuts.length > 0 ? { shortcuts } : {}
       } } : {},
       ...projectedCompatibleConfig(config, warnings),
-      ...projectedApiMdx(config, warnings),
+      ...projectedApi(config, warnings),
       ...i18n ? { i18n } : {},
       ...redirects.length > 0 ? { redirects } : {}
     },
@@ -5945,6 +6092,68 @@ function withSpecRef(ref, specRef) {
   return `${specRef} ${ref.operation}`;
 }
 
+// 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];
+  if (!prefix) return isDefault;
+  const wanted = prefix.replace(/^\/+/, "").toLowerCase();
+  const lowerPath = specPath.toLowerCase();
+  return lowerPath === wanted || lowerPath.endsWith(`/${wanted}`) || specFilename.toLowerCase() === wanted;
+}
+function operationKey(operation) {
+  const [first, ...rest] = operation.trim().split(/\s+/);
+  return `${first.toLowerCase()} ${rest.join(" ")}`;
+}
+function keysFor(spec, refs) {
+  return [...new Set(
+    refs.filter((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true)).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 markExcluded(content, operationKeys, keptKeys = []) {
+  const untouched = { content, excluded: [] };
+  if (operationKeys.length === 0) return untouched;
+  const text2 = content.toString("utf8");
+  let doc;
+  try {
+    doc = parseYaml4(text2);
+  } catch {
+    return untouched;
+  }
+  if (!doc || typeof doc !== "object") return untouched;
+  const excluded = [];
+  for (const key of operationKeys) {
+    const [method, ...rest] = key.split(" ");
+    const name = rest.join(" ");
+    if (method === "webhook") {
+      const entry2 = doc.webhooks?.[name] ?? doc["x-webhooks"]?.[name];
+      if (entry2 && typeof entry2 === "object") {
+        entry2["x-excluded"] = true;
+        excluded.push(`WEBHOOK ${name}`);
+      }
+      continue;
+    }
+    const entry = doc.paths?.[name];
+    if (!entry || typeof entry !== "object") continue;
+    const target = typeof entry.$ref === "string" ? keptKeys.some((k) => k.slice(k.indexOf(" ") + 1) === name) ? void 0 : entry : entry[method];
+    if (target && typeof target === "object") {
+      target["x-excluded"] = true;
+      excluded.push(`${method.toUpperCase()} ${name}`);
+    }
+  }
+  if (excluded.length === 0) return untouched;
+  const out = text2.trimStart().startsWith("{") ? `${JSON.stringify(doc, null, 2)}
+` : stringifyYaml(doc);
+  return { content: Buffer.from(out), excluded };
+}
+function sharedSpecMessage(path, excluded = []) {
+  return excluded.length ? `OpenAPI spec ${path} is shared with access-restricted pages and is published, but ${excluded.length} operation(s) documented only on those pages were withheld from it (${excluded.join(", ")}). Review the rest of the spec before publishing.` : `OpenAPI spec ${path} is shared with access-restricted pages and is published; it may describe restricted endpoints. Review it before publishing.`;
+}
+
 // src/analytics.ts
 var GA4_ID = /^G-[A-Z0-9]{4,20}$/;
 var GTM_ID = /^GTM-[A-Z0-9]{4,12}$/;
@@ -6926,12 +7135,23 @@ function normalizedReferenceKey(value) {
 function exactReferenceKey(value) {
   return value.split(/[?#]/, 1)[0].replace(/^\/+/, "").replace(/\\/g, "/").replace(/\.(?:mdx?|rst|txt)$/i, "");
 }
-function specRefMatches(ref, specPath, specFilename, isDefault) {
-  const prefix = /^(?:(\S+)\s+)?(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|TRACE|WEBHOOK)\s/i.exec(`${ref} `)?.[1];
-  if (!prefix) return isDefault;
-  const wanted = prefix.replace(/^\/+/, "").toLowerCase();
-  const lowerPath = specPath.toLowerCase();
-  return lowerPath === wanted || lowerPath.endsWith(`/${wanted}`) || specFilename.toLowerCase() === wanted;
+function navigationOperationRefs(config) {
+  const refs = [];
+  const visit = (node) => {
+    if (typeof node === "string") {
+      if (splitOpenApiRef(node)) refs.push(node);
+    } else if (Array.isArray(node)) node.forEach(visit);
+    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);
+  return markExcluded(spec.content, withheld, kept);
 }
 var TOKEN_SEPARATORS = /[\s"'()<>[\]{}=,;:|\\/`*!?#&]+/;
 var PATH_SEPARATORS = /[\s"'()<>[\]{}=,;:|\\`*!?#&]+/;
@@ -7004,12 +7224,22 @@ function mintlifyTopLevelApiReferences(config) {
   }
   return references;
 }
-function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
+function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs, 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)));
+  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;
+    known.add(key);
+    references.push({ value: key, kind: "openapi", tabLabel: `OpenAPI: ${key}`, hidden: true, pageOnly: true });
+  }
   const seen = /* @__PURE__ */ new Set();
   const specs = [];
   for (const reference of references) {
@@ -7059,6 +7289,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
       parentTab: reference.parentTab,
       icon: reference.icon,
       hidden: reference.hidden,
+      ...reference.pageOnly ? { pageOnly: true } : {},
       sourcePath: match.relativePath,
       directory: reference.directory
     });
@@ -7080,7 +7311,7 @@ function resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteSpecs) {
   }
   return specs;
 }
-function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings) {
+function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings, explainMissing = () => "no such file was found") {
   for (const page of pages) {
     const ref = page.openapi ? splitOpenApiRef(page.openapi) : null;
     if (!ref?.specRef) continue;
@@ -7097,7 +7328,7 @@ function rewriteMintlifyPageSpecRefs(pages, specs, remoteUrls, warnings) {
     if (match) {
       page.openapi = withSpecRef(ref, specAssetPath(match.filename));
     } else {
-      warnings.push({ code: "unsupported-config", message: `Page "${page.id}" references the OpenAPI spec "${ref.specRef}", which is not referenced from docs.json and was not migrated; the page will not render an endpoint. Add the spec to a tab's api setting.`, source: page.source });
+      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 });
     }
   }
 }
@@ -7122,7 +7353,7 @@ function slugifyApiSpecId(value) {
 function parseOpenApiOperationsForLinking(content) {
   let document;
   try {
-    document = parseYaml4(content.toString("utf8"));
+    document = parseYaml5(content.toString("utf8"));
   } catch {
     return [];
   }
@@ -7254,7 +7485,7 @@ function fernGeneratorsUnsupportedSpecPaths(config) {
 }
 function readFernGeneratorsConfig(path) {
   if (!existsSync5(path) || !lstatSync5(path).isFile() || lstatSync5(path).size > MAX_FERN_GENERATORS_BYTES) return null;
-  const parsed = parseYaml4(readFileSync5(path, "utf8"));
+  const parsed = parseYaml5(readFileSync5(path, "utf8"));
   return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
 }
 function fernOpenApiCandidateDirs(fernRoot, apiName, apiNameExplicit) {
@@ -7568,11 +7799,12 @@ function preserveLinkedAnchors(pages) {
       const tableCell = line.match(/^ {0,3}\|\s*([^|]+?)\s*\|/);
       if (tableCell && !/^[:\s-]+$/.test(tableCell[1])) tableCells.push({ index, text: tableCell[1] });
       const match = line.match(/^ {0,3}#{1,6}\s+(.+?)\s*#*\s*$/);
-      return match ? { index, text: match[1] } : null;
+      return match ? { index, text: match[1].replace(/\s*\{\/\*\s*#\S+?\s*\*\/\}$/, "") } : null;
     }).filter((entry) => entry !== null);
     const existing = /* @__PURE__ */ new Set();
     replaceOutsideCode(page.body, (text2) => {
       for (const match of text2.matchAll(/\bid=(?:"([^"]+)"|'([^']+)')/g)) existing.add(match[1] ?? match[2]);
+      for (const match of text2.matchAll(/\{\/\*\s*#(\S+?)\s*\*\/\}/g)) existing.add(match[1]);
       return text2;
     });
     const candidateIndexes = /* @__PURE__ */ new Map();
@@ -7700,7 +7932,7 @@ function globalSnippetAliases(files, repositoryRoot, siteRoot) {
   }
   return aliases;
 }
-function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
+function repositoryAssetHref(value, currentFile, siteRoot, onReferenced, onRootFallback) {
   const isBracketed = value.startsWith("<") && value.endsWith(">");
   const raw = isBracketed ? value.slice(1, -1) : value;
   if (!raw || raw.startsWith("#") || /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(raw)) return null;
@@ -7715,7 +7947,15 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
   }
   if (!ASSET_EXTENSIONS.has(extname6(decodedPath).toLowerCase())) return null;
   try {
-    const candidate = decodedPath.startsWith("/") ? resolveWithin(siteRoot, decodedPath.replace(/^\/+/, "")) : resolveWithinRoot(dirname4(currentFile), decodedPath, siteRoot);
+    let usedRootFallback = false;
+    let candidate = decodedPath.startsWith("/") ? resolveWithin(siteRoot, decodedPath.replace(/^\/+/, "")) : resolveWithinRoot(dirname4(currentFile), decodedPath, siteRoot);
+    if (!decodedPath.startsWith("/") && !existsSync5(candidate)) {
+      const fromRoot = resolveWithin(siteRoot, decodedPath.replace(/^(?:\.\/)+/, ""));
+      if (existsSync5(fromRoot)) {
+        candidate = fromRoot;
+        usedRootFallback = true;
+      }
+    }
     const realRoot = realpathSync2(siteRoot);
     const realCandidate = realpathSync2(candidate);
     const realRelative = relative5(realRoot, realCandidate);
@@ -7728,6 +7968,7 @@ function repositoryAssetHref(value, currentFile, siteRoot, onReferenced) {
     const onDiskRelative = relative5(realRoot, realpathSync2.native(candidate)).replace(/\\/g, "/");
     const onDisk = onDiskRelative.toLowerCase() === siteRelative.toLowerCase() ? normalizeAssetPath(onDiskRelative) : null;
     onReferenced?.(normalized, onDisk ?? void 0);
+    if (usedRootFallback) onRootFallback?.(decodedPath, normalized);
     const rewritten = `/${normalized}${suffix}`;
     return isBracketed ? `<${rewritten}>` : rewritten;
   } catch {
@@ -7746,12 +7987,12 @@ function rewriteFernIdRenameLinks(body, renames) {
     return text2.replace(/(\]\()\/([^\s)]+)(?=[\s)]|$)/g, (_match, prefix, target) => `${prefix}${rewriteTarget(`/${target}`)}`).replace(/(\bhref=")\/([^"]+)(")/g, (_match, prefix, target, suffix) => `${prefix}${rewriteTarget(`/${target}`)}${suffix}`);
   });
 }
-function rewriteRepositoryAssetLinks(body, currentFile, siteRoot, onReferenced) {
+function rewriteRepositoryAssetLinks(body, currentFile, siteRoot, onReferenced, onRootFallback) {
   return body.replace(/(!?\[[^\]]*\]\()(<[^>]+>|[^)\s]+)([^)]*\))/g, (original, opening, destination, closing) => {
-    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot, onReferenced);
+    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot, onReferenced, onRootFallback);
     return rewritten ? `${opening}${rewritten}${closing}` : original;
   }).replace(/\b(src|img|image|href)=(['"])([^'"]+)\2/g, (original, property, quote, destination) => {
-    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot, onReferenced);
+    const rewritten = repositoryAssetHref(destination, currentFile, siteRoot, onReferenced, onRootFallback);
     return rewritten ? `${property}=${quote}${rewritten}${quote}` : original;
   });
 }
@@ -8469,7 +8710,11 @@ function migrateRepository(options) {
     const publishedText = trackPublishedRefs ? raw : void 0;
     const pageAssetReferences = [];
     if (platform === "fern" || platform === "mintlify" || platform === "docusaurus") {
-      raw = normalizeExplicitHeadingIds(raw, (message) => warnings.push({ code: "invalid-page", message, source: file.relativePath }));
+      raw = normalizeExplicitHeadingIds(
+        raw,
+        (message) => warnings.push({ code: "invalid-page", message, source: file.relativePath }),
+        { headingMarkers: platform === "mintlify" }
+      );
     }
     if (componentMigrator) {
       const warningsBeforeTransform = warnings.length;
@@ -8556,6 +8801,8 @@ function migrateRepository(options) {
     if (platform === "mintlify" && mintlifyProjectRoot) {
       page.body = rewriteRepositoryAssetLinks(page.body, file.absolutePath, mintlifyProjectRoot, (assetPath, onDiskSpelling) => {
         pageAssetReferences.push(publicAssetKey(onDiskSpelling ?? assetPath));
+      }, (spelled, used) => {
+        warnings.push({ code: "unsupported-config", message: `"${spelled}" was not found beside this page; the file "${used}" in the site root was used instead and will be published.`, source: file.relativePath });
       });
     }
     if (platform === "fern" && fernProjectRoot) {
@@ -8703,15 +8950,19 @@ function migrateRepository(options) {
   const rootStylesheetPath = platform === "mintlify" && mintlifyProjectRoot ? resolveWithin(mintlifyProjectRoot, "style.css") : void 0;
   const hasRootStylesheet = Boolean(rootStylesheetPath && existsSync5(rootStylesheetPath) && lstatSync5(rootStylesheetPath).isFile() && !lstatSync5(rootStylesheetPath).isSymbolicLink());
   let rootStyleProjection;
+  let rootNavbarButtons = [];
   let rootStyleProblem;
   if (hasRootStylesheet && rootStylesheetPath && lstatSync5(rootStylesheetPath).size <= MAX_ASSET_BYTES) {
     const css = readFileSync5(rootStylesheetPath, "utf8");
     if (/@import\b|url\s*\(\s*['"]?\s*(?:javascript:|file:)/i.test(css)) rootStyleProblem = "unsafe";
     else {
       try {
+        rootNavbarButtons = navbarLinkButtons(css);
         rootStyleProjection = projectAuthoredStyles(css, [
           ...pages.map((page) => page.body),
-          ...(componentMigrator?.files() ?? []).map((file) => typeof file.content === "string" ? file.content : "")
+          ...(componentMigrator?.files() ?? []).map((file) => typeof file.content === "string" ? file.content : ""),
+          // Site-wide scripts build markup of their own (a CTA card, say) that the stylesheet is meant for.
+          ...files.filter((file) => isMintlifyServedScriptOrStyle(file.relativePath) && extname6(file.relativePath).toLowerCase() === ".js" && lstatSync5(file.absolutePath).size <= MAX_PAGE_BYTES).map((file) => readFileSync5(file.absolutePath, "utf8"))
         ]);
       } catch {
         rootStyleProblem = "parse";
@@ -8849,6 +9100,18 @@ function migrateRepository(options) {
     } else if (rootStyleProblem === "parse" || !rootStyleProjection) {
       warnings.push({ code: "unsupported-config", message: "Mintlify root style.css could not be parsed and was not imported.", source: "style.css" });
     } else {
+      if (rootNavbarButtons.length > 0 && docsConfig.navbar?.links) {
+        docsConfig = {
+          ...docsConfig,
+          navbar: {
+            ...docsConfig.navbar,
+            links: docsConfig.navbar.links.map((link) => {
+              const rule = rootNavbarButtons.find((entry) => entry.exact ? link.href === entry.href : link.href.includes(entry.href));
+              return rule ? { ...link, button: { background: rule.background, ...rule.color ? { color: rule.color } : {} } } : link;
+            })
+          }
+        };
+      }
       if (rootStyleProjection.omittedSelectors > 0) warnings.push({
         code: "unsupported-config",
         source: "style.css",
@@ -8992,19 +9255,31 @@ function migrateRepository(options) {
       rewriteApiLinksInPages(pages, operationLinks, prefixLandings, warnings);
     }
   } else if (platform === "mintlify") {
-    const warnSharedSpec = (path) => {
-      warnings.push({
-        code: "gated-page",
-        message: `OpenAPI spec ${path} is shared with access-restricted pages and is published; it may describe restricted endpoints. Review it before publishing.`,
-        source: path
-      });
+    const warnSharedSpec = (path, excluded = []) => {
+      warnings.push({ code: "gated-page", message: sharedSpecMessage(path, excluded), source: path });
     };
-    const resolvedSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs);
+    const keptSpecRefs = [...publishedSpecRefs, ...navigationOperationRefs(mintlifyConfig)];
+    const allSpecs = resolveMintlifyApiSpecs(mintlifyConfig, files, warnings, remoteApiSpecs, pages);
+    for (const remote of remoteApiSpecs) {
+      const { withheld, kept } = withheldOperationKeys({ sourcePath: remote.url, filename: remote.url }, withheldSpecRefs, keptSpecRefs);
+      if (withheld.length > 0) {
+        remote.withheldOperations = withheld;
+        remote.keptOperations = kept;
+      }
+    }
+    const withheldOperations = /* @__PURE__ */ new Map();
+    for (const spec of allSpecs) {
+      const result = excludeWithheldOperations(spec, withheldSpecRefs, keptSpecRefs);
+      spec.content = result.content;
+      withheldOperations.set(spec, result.excluded);
+    }
+    const resolvedSpecs = allSpecs.filter((spec) => !spec.pageOnly);
+    const pageOnlySpecs = allSpecs.filter((spec) => spec.pageOnly);
     for (const spec of resolvedSpecs) {
       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);
+      if (withheldSpecRefs.some((ref) => specRefMatches(ref, spec.sourcePath, spec.filename, true))) warnSharedSpec(spec.sourcePath, withheldOperations.get(spec));
     }
     let pageSpecs = resolvedSpecs;
     if (resolvedSpecs.length > 0) {
@@ -9023,16 +9298,35 @@ function migrateRepository(options) {
           quarantinedFiles.push({ path: `${QUARANTINE_DIRECTORY}/assets/${specAssetPath(filename)}`, content: readFileSync5(fallback.absolutePath) });
           withheldAssetCount++;
         } else {
+          const pruned = excludeWithheldOperations({ sourcePath: fallback.relativePath, filename, content: readFileSync5(fallback.absolutePath) }, withheldSpecRefs, keptSpecRefs);
           if (!assets.some((asset) => asset.path === specAssetPath(filename))) {
-            assets.push(specAsset(filename, readFileSync5(fallback.absolutePath)));
+            assets.push(specAsset(filename, pruned.content));
           }
           docsConfig = injectOpenApiSpecs(docsConfig, [{ filename }]);
           pageSpecs = [{ filename, sourcePath: fallback.relativePath }];
-          if (withheldSpecRefs.some(matches)) warnSharedSpec(fallback.relativePath);
+          if (withheldSpecRefs.some(matches)) warnSharedSpec(fallback.relativePath, pruned.excluded);
         }
       }
     }
-    rewriteMintlifyPageSpecRefs(pages, pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings);
+    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 (pageOnlySpecs.length > 0) {
+      docsConfig = injectOpenApiSpecs(docsConfig, pageOnlySpecs, warnings);
+      pageSpecs = [...pageSpecs, ...pageOnlySpecs];
+    }
+    const explainMissingSpec = (key) => {
+      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";
+      try {
+        if (lstatSync5(resolvePath(repositoryDir, key)).isSymbolicLink()) return "the file is a symbolic link, which is never followed";
+      } catch {
+      }
+      return sameName ? "the file could not be read as an OpenAPI document" : `no file exists at "${key}"`;
+    };
+    rewriteMintlifyPageSpecRefs(pages, pageSpecs, new Set(remoteApiSpecs.map((spec) => spec.url)), warnings, explainMissingSpec);
   }
   if (platform === "mintlify") {
     const sources = new Set((docsConfig.redirects ?? []).map((redirect) => redirect.source));
@@ -9447,6 +9741,8 @@ function renderPage(bundle, page) {
     "---",
     `title: ${yamlString(page.title)}`,
     page.navTitle ? `navTitle: ${yamlString(page.navTitle)}` : null,
+    page.icon ? `icon: ${yamlString(page.icon)}` : null,
+    page.iconType ? `iconType: ${yamlString(page.iconType)}` : null,
     `description: ${yamlString(page.description)}`,
     page.descriptionPlacement === "body" ? "descriptionPlacement: body" : null,
     page.badge ? `badge: ${yamlString(page.badge)}` : null,
@@ -9454,9 +9750,11 @@ function renderPage(bundle, page) {
     page.mode ? `mode: ${yamlString(page.mode)}` : null,
     page.hidden ? "hidden: true" : null,
     page.noindex ? "noindex: true" : null,
+    ...Object.entries(page.meta ?? {}).map(([field, value]) => `${field}: ${yamlString(value)}`),
     page.openapi ? `openapi: ${yamlString(page.openapi)}` : null,
     page.api ? `api: ${yamlString(page.api)}` : null,
     page.authMethod ? `authMethod: ${yamlString(page.authMethod)}` : null,
+    page.playground ? `playground: ${yamlString(page.playground)}` : null,
     bundle.sourceKind === "url" ? `source: ${yamlString(page.source)}` : null,
     "---",
     "",
@@ -9570,7 +9868,7 @@ import remarkMdx3 from "remark-mdx";
 import remarkParse3 from "remark-parse";
 import TurndownService from "turndown";
 import { unified as unified3 } from "unified";
-import { parse as parseYaml5, stringify as stringifyYaml } from "yaml";
+import { parse as parseYaml6, stringify as stringifyYaml2 } from "yaml";
 var DEFAULT_MAX_PAGES = 1e3;
 var DEFAULT_MAX_TOTAL_BYTES = 1e8;
 var MAX_DISCOVERED_URLS = 5e3;
@@ -10295,7 +10593,7 @@ function extractEmbeddedOpenApi(content) {
   const match = fencePattern.exec(content);
   if (!match) return { content };
   try {
-    const parsed = parseYaml5(match[5], { maxAliasCount: 50 });
+    const parsed = parseYaml6(match[5], { maxAliasCount: 50 });
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { content };
     const document = parsed;
     if (typeof document.openapi !== "string" && typeof document.swagger !== "string") return { content };
@@ -10409,7 +10707,7 @@ function mergeEmbeddedOpenApi(fragments) {
   if (Object.keys(combinedPaths).length === 0) return null;
   if (Object.keys(combinedComponents).length === 0) delete combined.components;
   if (tags.size > 0) combined.tags = [...tags.values()];
-  return new TextEncoder().encode(stringifyYaml(combined));
+  return new TextEncoder().encode(stringifyYaml2(combined));
 }
 function htmlPage(document, id) {
   const $ = load2(document.body);
@@ -11148,7 +11446,7 @@ import { createHash as createHash3 } from "crypto";
 import { lookup } from "dns/promises";
 import { request } from "https";
 import { isIP } from "net";
-import { parse as parseYaml6 } from "yaml";
+import { parse as parseYaml7 } from "yaml";
 var MAX_SPEC_BYTES = 25e6;
 var MAX_REDIRECTS = 3;
 function isPublicAddress(address, family) {
@@ -11244,7 +11542,7 @@ async function downloadSpec(value, fetcher) {
 }
 function parseOpenApi(content, extension) {
   const text2 = content.toString("utf8");
-  const parsed = extension === "yaml" || !text2.trimStart().startsWith("{") ? parseYaml6(text2) : JSON.parse(text2);
+  const parsed = extension === "yaml" || !text2.trimStart().startsWith("{") ? parseYaml7(text2) : JSON.parse(text2);
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("OpenAPI spec is not an object.");
   const document = parsed;
   if (typeof document.openapi !== "string" || !/^3\./.test(document.openapi)) {
@@ -11302,7 +11600,10 @@ async function hydrateRemoteApiSpecs(bundle, fetcher) {
     try {
       const url = validatedSpecUrl(reference.url);
       const extension = /\.ya?ml$/i.test(url.pathname) ? "yaml" : "json";
-      const body = await downloadSpec(reference.url, fetcher);
+      const downloaded = await downloadSpec(reference.url, fetcher);
+      const pruned = markExcluded(downloaded, reference.withheldOperations ?? [], reference.keptOperations);
+      const body = pruned.content;
+      if (reference.withheldOperations?.length) warnings.push({ code: "gated-page", message: sharedSpecMessage(reference.url, pruned.excluded), source: reference.url });
       const operations = parseOpenApi(body, extension);
       const filename = `openapi-${createHash3("sha256").update(reference.url).digest("hex").slice(0, 12)}.${extension}`;
       assets.push({ path: `openapi/${filename}`, content: body, projectRelative: true });