@thallylabs/migrate 0.2.38 → 0.2.39

package/dist/url-migration.js

@@ -1,6 +1,6 @@
 // src/url-run.ts
 import { createHash } from "crypto";
-import { load as load3 } from "cheerio";
+import { load as load5 } from "cheerio";
 import remarkParse3 from "remark-parse";
 import remarkMdx3 from "remark-mdx";
 import { unified as unified3 } from "unified";
@@ -531,7 +531,53 @@ function cloneUrlMigrationCheckpoint(checkpoint) {
 }
 
 // src/url-navigation.ts
+import { load as load2 } from "cheerio";
+
+// src/url-scope.ts
 import { load } from "cheerio";
+function inferUrlMigrationScope(capture) {
+  const source = capture.finalUrl;
+  let end = source.pathname.length;
+  while (end > 0 && source.pathname.charCodeAt(end - 1) === 47) end--;
+  const parent = end < source.pathname.length ? source.pathname.slice(0, end) || "/" : source.pathname.slice(0, source.pathname.lastIndexOf("/")) || "/";
+  if (!/html/i.test(capture.contentType) || Buffer.byteLength(capture.body) > 8e6) return { scopePath: parent, evidence: "source-parent" };
+  const $ = load(capture.body);
+  const ancestor = (path) => path === "/" || source.pathname === path || source.pathname.startsWith(`${path}/`);
+  const observed = (reference) => {
+    if (!reference || reference.length > 8192) return void 0;
+    try {
+      const url = new URL(reference, source);
+      if (url.origin !== source.origin || url.username || url.password || url.search || url.hash || /%2f|%5c/i.test(url.pathname)) return void 0;
+      return url;
+    } catch {
+      return void 0;
+    }
+  };
+  const indexes = [];
+  $("link[href],a[href]").slice(0, 1e4).each((_, node) => {
+    const url = observed($(node).attr("href"));
+    if (!url || !/\/(?:llms(?:-full)?\.txt|sitemap(?:[-_][^/]*)?\.xml)$/i.test(url.pathname)) return;
+    const path = url.pathname.slice(0, url.pathname.lastIndexOf("/")) || "/";
+    if (ancestor(path)) indexes.push(path);
+  });
+  if (indexes.length) return { scopePath: indexes.sort((a, b) => b.length - a.length)[0], evidence: "discovery-index" };
+  const paths = [];
+  $('nav a[href],aside a[href],[role="navigation"] a[href]').slice(0, 1e4).each((_, node) => {
+    if ($(node).closest("header,footer").length) return;
+    const url = observed($(node).attr("href"));
+    if (url && !/\.[a-z0-9]+$/i.test(url.pathname)) paths.push(url.pathname);
+  });
+  if (new Set(paths).size >= 2 && paths.some((path) => path === source.pathname)) {
+    const segments = paths.map((path) => path.split("/").filter(Boolean));
+    let count = 0;
+    while (segments.every((parts) => parts[count] !== void 0 && parts[count] === segments[0][count])) count++;
+    const common = "/" + segments[0].slice(0, count).join("/");
+    if (ancestor(common)) return { scopePath: common, evidence: "navigation" };
+  }
+  return { scopePath: parent, evidence: "source-parent" };
+}
+
+// src/url-navigation.ts
 var MAX_CAPTURE_BYTES = 8e6;
 var MAX_JSON_BYTES = 2e6;
 var MAX_NODES = 1e4;
@@ -598,8 +644,18 @@ function flightRecords(stream) {
   }
   return records;
 }
-function mintlifyNavigation(body, base, locale) {
-  const $ = load(body);
+function mintlifyNavigation(body, base, locale, selectedScope) {
+  const $ = load2(body);
+  const scope = inferUrlMigrationScope({ body, contentType: "text/html", finalUrl: base });
+  const mount = scope.evidence === "source-parent" ? selectedScope ?? "/" : scope.scopePath;
+  const configTarget = (value) => {
+    const reference = text(value);
+    if (!reference) return void 0;
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(reference)) return target(reference, base);
+    const path = reference.replace(/^\/+/, "");
+    const prefix = mount.replace(/^\/|\/$/g, "");
+    return target(prefix && path !== prefix && !path.startsWith(`${prefix}/`) ? `${prefix}/${path}` : path, new URL("/", base));
+  };
   let stream = "";
   const records = [];
   $("script").each((_index, script) => {
@@ -636,7 +692,7 @@ function mintlifyNavigation(body, base, locale) {
     const walk = (value, depth = 0, activeLocale) => {
       if (depth > MAX_DEPTH || ++count > MAX_NODES) throw new Error("Source navigation exceeds its safety bound.");
       if (typeof value === "string") {
-        const url2 = target(value, new URL("/", base));
+        const url2 = configTarget(value);
         return url2 ? [{ kind: "page", label: value, url: url2 }] : [];
       }
       if (Array.isArray(value)) return value.flatMap((child) => walk(child, depth + 1, activeLocale));
@@ -656,7 +712,7 @@ function mintlifyNavigation(body, base, locale) {
               return;
             }
             if (!object(node)) return;
-            const href = target(node.href, base);
+            const href = configTarget(node.href);
             if (href) {
               populated++;
               const url2 = new URL(href);
@@ -674,10 +730,10 @@ function mintlifyNavigation(body, base, locale) {
         const selected = matching[0]?.item ?? languages.find((item) => text(item.language)?.toLowerCase() === language?.toLowerCase()) ?? languages.find((item) => text(item.language)?.toLowerCase() === "en") ?? languages[0];
         return selected ? walk({ ...selected, languages: void 0 }, depth + 1, text(selected.language)) : [];
       }
-      const label = text(value.tab) ?? text(value.group) ?? text(value.title) ?? text(value.label);
-      const kind = text(value.tab) ? "tab" : text(value.group) ? "group" : "page";
+      const label = text(value.tab) ?? text(value.dropdown) ?? text(value.group) ?? text(value.sidebarTitle) ?? text(value.title) ?? text(value.label);
+      const kind = text(value.tab) || text(value.dropdown) ? "tab" : text(value.group) ? "group" : "page";
       const children = ["tabs", "groups", "pages", "dropdowns", "anchors", "versions"].flatMap((key) => Array.isArray(value[key]) ? walk(value[key], depth + 1, activeLocale) : []);
-      const url = target(value.href, base);
+      const url = configTarget(value.href);
       if (!label) return children;
       if (!url && !children.length) return [];
       return [{
@@ -685,6 +741,7 @@ function mintlifyNavigation(body, base, locale) {
         label,
         ...url ? { url } : {},
         ...children.length ? { children } : {},
+        ...text(value.dropdown) ? { presentation: "dropdown" } : {},
         ...kind === "tab" && activeLocale ? { locale: activeLocale } : {}
       }];
     };
@@ -711,18 +768,19 @@ function resolveNavigation(nodes, base) {
         ...url ? { url } : {},
         ...children.length ? { children } : {},
         ...["tab", "group", "page"].includes(node.kind ?? "") ? { kind: node.kind } : {},
+        ...node.presentation === "dropdown" ? { presentation: "dropdown" } : {},
         ...text(node.locale) ? { locale: text(node.locale) } : {}
       }];
     });
   };
   return walk(nodes);
 }
-function extractSourceNavigation(capture) {
+function extractSourceNavigation(capture, selectedScope) {
   if (capture.navigation) return resolveNavigation(capture.navigation, capture.finalUrl);
   if (!/html/i.test(capture.contentType) || Buffer.byteLength(capture.body) > MAX_CAPTURE_BYTES) return [];
-  const mintlify = mintlifyNavigation(capture.body, capture.finalUrl, capture.locale);
+  const mintlify = mintlifyNavigation(capture.body, capture.finalUrl, capture.locale, selectedScope);
   if (mintlify.length) return mintlify;
-  const $ = load(capture.body);
+  const $ = load2(capture.body);
   const candidates = ['.theme-doc-sidebar-menu,[aria-label*="sidebar" i]', "aside", '[role="navigation"],nav'];
   const root = candidates.map((selector) => $(selector).filter((_index, node) => $(node).find("a[href]").length > 0 && $(node).closest("header").length === 0).first()).find((candidate) => candidate.length);
   if (!root) return [];
@@ -804,7 +862,7 @@ function migrationImageUrl(value, base) {
   if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error("Responsive image URL is not a credential-free HTTP(S) URL.");
   return url.toString();
 }
-function migrationImageCandidates(value, base, resolve3 = true) {
+function migrationImageCandidates(value, base, resolve4 = true) {
   if (value.length > 64e3) throw new Error("Responsive image candidate list exceeds its safety bound.");
   const result = [];
   let index = 0;
@@ -822,7 +880,7 @@ function migrationImageCandidates(value, base, resolve3 = true) {
     if (descriptor && !/^(?:[1-9]\d*w|(?:\d+(?:\.\d+)?|\.\d+)x)$/.test(descriptor)) throw new Error("Responsive image has an unsupported descriptor.");
     if (descriptor.endsWith("x") && Number(descriptor.slice(0, -1)) <= 0) throw new Error("Responsive image density must be positive.");
     const resolved = migrationImageUrl(url, base);
-    result.push({ url: resolve3 ? resolved : url, descriptor });
+    result.push({ url: resolve4 ? resolved : url, descriptor });
     if (result.length > 128) throw new Error("Responsive image has too many candidates.");
     if (value[index] === ",") index++;
   }
@@ -836,8 +894,88 @@ function migrationImageAttribute(value) {
   return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\{/g, "&#123;").replace(/\}/g, "&#125;").replace(/\r/g, "&#13;").replace(/\n/g, "&#10;");
 }
 
+// src/url-media.ts
+import { load as load3 } from "cheerio";
+var VIDEO_ATTRIBUTES = /* @__PURE__ */ new Set([
+  "src",
+  "title",
+  "poster",
+  "controls",
+  "muted",
+  "autoplay",
+  "loop",
+  "playsinline",
+  "class",
+  "id",
+  "width",
+  "height",
+  "preload",
+  "aria-label"
+]);
+var YOUTUBE_ATTRIBUTES = /* @__PURE__ */ new Set([
+  "src",
+  "title",
+  "width",
+  "height",
+  "allow",
+  "allowfullscreen",
+  "referrerpolicy",
+  "frameborder",
+  "loading",
+  "class",
+  "id",
+  "aria-label"
+]);
+var YOUTUBE_HOSTS = /* @__PURE__ */ new Set([
+  "youtube.com",
+  "www.youtube.com",
+  "youtube-nocookie.com",
+  "www.youtube-nocookie.com"
+]);
+function projectMigrationMedia(html, base) {
+  const $ = load3(html, void 0, false);
+  const nodes = $.root().contents().filter((_index, node2) => node2.type !== "text" || Boolean(node2.data.trim()));
+  if (nodes.length !== 1) return null;
+  const element = nodes.first();
+  const node = element[0];
+  if (node.type !== "tag" || !["video", "iframe"].includes(node.name)) return null;
+  if (element.children().length || element.text().trim()) return null;
+  const allowed = node.name === "video" ? VIDEO_ATTRIBUTES : YOUTUBE_ATTRIBUTES;
+  if (Object.keys(node.attribs).some((name) => !allowed.has(name))) return null;
+  const source = element.attr("src");
+  if (!source) return null;
+  try {
+    let src = migrationImageUrl(source, base);
+    let component = "Video";
+    const props = [];
+    if (node.name === "video") {
+      if (!/\.(?:mp4|webm|ogg|mov|m4v)(?:[?#]|$)/i.test(src)) component = "video";
+      const isMuted = element.attr("muted") !== void 0;
+      const hasAutoplay = element.attr("autoplay") !== void 0;
+      if (hasAutoplay && !isMuted) return null;
+      props.push("controls={true}");
+      for (const [attribute, prop] of [["muted", "muted"], ["loop", "loop"], ["playsinline", "playsInline"], ["autoplay", "autoPlay"]]) {
+        if (element.attr(attribute) !== void 0) props.push(`${prop}={true}`);
+      }
+      const poster = element.attr("poster");
+      if (poster) props.push(`poster="${migrationImageAttribute(migrationImageUrl(poster, base))}"`);
+    } else {
+      const url = new URL(src);
+      if (url.protocol !== "https:" || url.port || !YOUTUBE_HOSTS.has(url.hostname)) return null;
+      const id = url.pathname.match(/^\/embed\/([A-Za-z0-9_-]{11})$/)?.[1];
+      if (!id || url.hash || [...url.searchParams.keys()].some((name) => name !== "si")) return null;
+      src = `https://www.youtube-nocookie.com/embed/${id}`;
+    }
+    const title = element.attr("title") ?? element.attr("aria-label");
+    if (title !== void 0) props.push(`title="${migrationImageAttribute(title)}"`);
+    return `<${component} src="${migrationImageAttribute(src)}"${props.length ? ` ${props.join(" ")}` : ""} />`;
+  } catch {
+    return null;
+  }
+}
+
 // src/url.ts
-import { load as load2 } from "cheerio";
+import { load as load4 } from "cheerio";
 import remarkMdx2 from "remark-mdx";
 import remarkParse2 from "remark-parse";
 import TurndownService from "turndown";
@@ -2470,9 +2608,10 @@ var PORTABLE_MDX_COMPONENTS = /* @__PURE__ */ new Set([
   "Warning",
   "YouTube",
   "picture",
-  "source"
+  "source",
+  "video"
 ]);
-var PORTABLE_URL_PROPS = "href|src|img|primaryHref|secondaryHref";
+var PORTABLE_URL_PROPS = "href|src|poster|img|primaryHref|secondaryHref";
 var PORTABLE_URL_PROP_NAMES = new Set(PORTABLE_URL_PROPS.split("|"));
 var MINTLIFY_ARTICLE_LABELS = [
   { baseUrl: "Select base URL", permalink: "Navigate to header" },
@@ -2612,7 +2751,7 @@ function isSafePortableUrl(value) {
   }
 }
 function decodeHtmlAttribute(value) {
-  const document = load2(`<i data-thally-value="${value.replace(/"/g, "&quot;")}"></i>`);
+  const document = load4(`<i data-thally-value="${value.replace(/"/g, "&quot;")}"></i>`);
   return document("i").attr("data-thally-value") ?? "";
 }
 function escapeMarkdownText(value, escapeTableSeparator = false) {
@@ -2698,7 +2837,7 @@ function replacePortableHtmlImages(value) {
     if (start < cursor) continue;
     const end = htmlOpeningTagEnd(value, start + match[0].length);
     if (end === null) continue;
-    const fragment = load2(value.slice(start, end));
+    const fragment = load4(value.slice(start, end));
     const image = fragment("img").first();
     const source = image.attr("src");
     const destination = source && isSafePortableUrl(source) ? markdownLinkDestination(source) : null;
@@ -2723,7 +2862,7 @@ function replacePortableHtmlAnchors(value) {
     const closing = closingMatch.exec(value);
     if (!closing) continue;
     const end = closing.index + closing[0].length;
-    const fragment = load2(value.slice(start, end));
+    const fragment = load4(value.slice(start, end));
     const anchor = fragment("a").first();
     const href = anchor.attr("href");
     const label = escapeMarkdownText(anchor.text().replace(/\s+/g, " ").trim());
@@ -2758,6 +2897,10 @@ function sanitizeMarkdownUrls(value) {
         hasUnsafeMdxSyntax = true;
         return;
       }
+      if (node.name === "video" && node.children?.length) {
+        hasUnsafeMdxSyntax = true;
+        return;
+      }
       for (const attribute of node.attributes ?? []) {
         if (attribute.type !== "mdxJsxAttribute" || !attribute.name || /^on[A-Z]/.test(attribute.name)) {
           hasUnsafeMdxSyntax = true;
@@ -2794,6 +2937,22 @@ function sanitizeMarkdownUrls(value) {
             return;
           }
         }
+        if (node.name === "video") {
+          const isBoolean = ["controls", "muted", "autoPlay", "loop", "playsInline"].includes(attribute.name);
+          const isText = ["src", "poster", "title"].includes(attribute.name);
+          if (isBoolean && typeof staticValue !== "boolean" || isText && typeof attribute.value !== "string" || !isBoolean && !isText) {
+            hasUnsafeMdxSyntax = true;
+            return;
+          }
+          if (attribute.name === "src" || attribute.name === "poster") {
+            try {
+              migrationImageUrl(decodeHtmlAttribute(attribute.value), new URL("https://migration.invalid"));
+            } catch {
+              hasUnsafeMdxSyntax = true;
+              return;
+            }
+          }
+        }
       }
     }
     for (const child of node.children ?? []) validateMdxSyntax(child);
@@ -2906,7 +3065,7 @@ function sanitizeRemoteMarkdown(body) {
   const urlSafeMarkdown = sanitizeMarkdownUrls(sanitized);
   if (urlSafeMarkdown === null) return null;
   const executable = withoutFencedCode(urlSafeMarkdown).replace(/\{\/\*[\s\S]*?\*\/\}/g, "").replace(/<(?:https?:\/\/|mailto:)[^>]+>/gi, "").replace(/(`+)[\s\S]*?\1/g, "");
-  if (/^\s*(?:import|export)\s/m.test(executable)) return null;
+  if (/^[\t ]*(?:import|export)[\t ]/m.test(executable)) return null;
   let hasUnsafeExpression = false;
   const withoutStaticProps = executable.replace(/=\{([^{}\n]*)\}/g, (original, value) => {
     try {
@@ -2964,7 +3123,7 @@ function extractEmbeddedOpenApi(content) {
     const root = embeddedOpenApiParser.parse(content);
     const candidates = (root.children ?? []).flatMap((node2) => {
       if (node2.type !== "code" || !/^(?:yaml|yml|json)$/i.test(node2.lang ?? "")) return [];
-      const metadata = node2.meta?.match(/^(?:(\S+\.(?:yaml|yml|json))\s+)?(delete|get|head|options|patch|post|put|trace)\s+(\/\S+)\s*$/i);
+      const metadata = node2.meta?.match(/^(?:((?:\S+\.(?:yaml|yml|json)|[A-Za-z][A-Za-z0-9_-]{0,127}))\s+)?(delete|get|head|options|patch|post|put|trace)\s+(\/\S+)\s*$/i);
       return metadata ? [{ node: node2, method: metadata[2].toUpperCase(), path: metadata[3] }] : [];
     });
     if (candidates.length !== 1) return { content };
@@ -3049,7 +3208,7 @@ function markdownPage(document, id, platform, warn) {
   };
 }
 function migrationHtmlArticle(body) {
-  const $ = load2(body);
+  const $ = load4(body);
   const root = ["main article", "article", "main", '[role="main"]', "body"].map((selector) => $(selector).first()).find((candidate) => candidate.length);
   root.find([
     "script",
@@ -3067,7 +3226,10 @@ function migrationHtmlArticle(body) {
     "#chat-assistant-sheet",
     "#chat-assistant-textarea"
   ].join(",")).remove();
-  const permalinkSelectors = MINTLIFY_ARTICLE_LABELS.map((labels) => `a[aria-label="${labels.permalink}"]`);
+  root.find('div[data-component-part="code-group-tab-content"]').each((_index, element) => {
+    if ($(element).parents("pre").length === 0 && $(element).find("pre").length === 0) element.name = "pre";
+  });
+  const permalinkSelectors = MINTLIFY_ARTICLE_LABELS.map((labels2) => `a[aria-label="${labels2.permalink}"]`);
   root.find([...permalinkSelectors, "h1 .hash-link", "h2 .hash-link", "h3 .hash-link", "h4 .hash-link", "h5 .hash-link", "h6 .hash-link"].join(",")).each((_index, link) => {
     const parent = $(link).parent();
     $(link).remove();
@@ -3078,7 +3240,7 @@ function migrationHtmlArticle(body) {
     const isChecked = $(element).attr("checked") !== void 0;
     $(element).replaceWith($("<span></span>").attr("data-thally-static-task-checkbox", isChecked ? "checked" : "unchecked").text(isChecked ? "[x] " : "[ ] "));
   });
-  root.find(MINTLIFY_ARTICLE_LABELS.map((labels) => `select[aria-label="${labels.baseUrl}"]`).join(",")).each((_index, element) => {
+  root.find(MINTLIFY_ARTICLE_LABELS.map((labels2) => `select[aria-label="${labels2.baseUrl}"]`).join(",")).each((_index, element) => {
     const select = $(element);
     const options = select.children("option").toArray();
     if (!options.length || options.length !== select.children().length) return;
@@ -3117,7 +3279,7 @@ function htmlPage(document, id, options = {}) {
   const title = scopedTitle || $("main h1, article h1, h1").first().text().trim() || $('meta[property="og:title"]').attr("content")?.trim() || $("title").text().split("|")[0].trim();
   const description = $('meta[name="description"]').attr("content")?.trim() || $('meta[property="og:description"]').attr("content")?.trim();
   let documentHeadingAnchor = "";
-  const excludedElements = options.omitDocumentHeading ? "script,style,noscript,nav,footer,aside,form,button,svg,iframe,object,embed,link,meta" : "script,style,noscript,nav,header,footer,aside,form,button,svg,iframe,object,embed,link,meta";
+  const excludedElements = options.omitDocumentHeading ? "script,style,noscript,nav,footer,aside,form,button,svg,object,embed,link,meta" : "script,style,noscript,nav,header,footer,aside,form,button,svg,object,embed,link,meta";
   root.find(excludedElements).remove();
   root.find(".theme-doc-version-badge,.theme-doc-breadcrumbs,.theme-doc-toc-mobile,.table-of-contents,.hash-link").remove();
   if (options.omitDocumentHeading) {
@@ -3175,6 +3337,18 @@ function htmlPage(document, id, options = {}) {
     // Emit literal task-list syntax rather than escaping its brackets as copy.
     replacement: (_content, node) => node.getAttribute("data-thally-static-task-checkbox") === "checked" ? "[x] " : "[ ] "
   });
+  turndown.addRule("migration-authored-paragraph", {
+    filter: (node) => node.nodeName === "SPAN" && node.getAttribute("data-as") === "p",
+    // Some publishers render authored paragraphs as spans. Their explicit
+    // semantic hint must retain a block boundary: otherwise following copy
+    // joins a picture's closing tag or an accordion's source anchor and can
+    // change the resulting MDX grammar. Ordinary spans remain inline.
+    replacement: (content) => `
+
+${content}
+
+`
+  });
   const anchor = (element) => {
     const value = element.getAttribute("id");
     return options.preserveAnchors && value ? `<a id="${value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/\{/g, "&#123;")}" />
@@ -3193,6 +3367,18 @@ ${anchor(element)}${heading ? `${"#".repeat(Number(heading[1]))} ${content.trim(
 `;
     }
   });
+  turndown.addRule("migration-static-media", {
+    filter: (node) => node.nodeName === "VIDEO" || node.nodeName === "IFRAME",
+    replacement: (_content, node) => {
+      const element = node;
+      const projected = projectMigrationMedia(element.outerHTML, document.finalUrl);
+      return projected ? `
+
+${anchor(element)}${projected}
+
+` : "";
+    }
+  });
   if (options.preserveResponsiveImages) {
     const image = (element) => {
       const tag = element.nodeName.toLowerCase();
@@ -3228,7 +3414,7 @@ ${content.trim()}
       const element = node;
       const className = element.className;
       const tag = /admonition-(?:danger)/.test(className) ? "Error" : /admonition-(?:caution|warning)/.test(className) ? "Warning" : /admonition-info/.test(className) ? "Info" : "Note";
-      const fragment = load2(element.outerHTML);
+      const fragment = load4(element.outerHTML);
       const clone = fragment(".theme-admonition").first();
       const title2 = clone.find('[class*="admonitionHeading"],.admonition-heading').first();
       const titleText = title2.text().trim();
@@ -3249,15 +3435,15 @@ ${titleText ? `**${escapeMarkdownText(titleText)}**
     filter: (node) => node.nodeName === "DIV" && node.classList.contains("tabs-container"),
     replacement: (_content, node) => {
       const element = node;
-      const fragment = load2(element.outerHTML);
+      const fragment = load4(element.outerHTML);
       const container = fragment(".tabs-container").first();
-      const labels = container.children("ul.tabs").children("li").toArray().map((item) => fragment(item).text().trim() || "Tab");
+      const labels2 = container.children("ul.tabs").children("li").toArray().map((item) => fragment(item).text().trim() || "Tab");
       const panels = container.find('[role="tabpanel"]').toArray().filter((panel) => fragment(panel).closest(".tabs-container")[0] === container[0]);
       if (panels.length === 0) return _content;
       const tabs = panels.map((panel, index) => {
         const panelId = fragment(panel).attr("id");
         const tab = panelId ? container.find('[role="tab"]').toArray().find((item) => fragment(item).attr("aria-controls") === panelId) : void 0;
-        const title2 = migrationImageAttribute((tab ? fragment(tab).text().trim() : labels[index]) || `Tab ${index + 1}`);
+        const title2 = migrationImageAttribute((tab ? fragment(tab).text().trim() : labels2[index]) || `Tab ${index + 1}`);
         const panelAnchor = options.preserveAnchors && panelId ? `<a id="${migrationImageAttribute(panelId)}" />
 
 ` : "";
@@ -3277,7 +3463,7 @@ ${tabs.join("\n\n")}
   turndown.addRule("gfm-table", {
     filter: "table",
     replacement: (_content, node) => {
-      const fragment = load2(node.outerHTML);
+      const fragment = load4(node.outerHTML);
       const rows = fragment("tr").toArray().map((row) => fragment(row).children("th,td").toArray().map((cell) => {
         const wasConvertingTableCell = isConvertingTableCell;
         isConvertingTableCell = true;
@@ -3303,7 +3489,7 @@ ${normalized.slice(1).map((row) => `| ${row.join(" | ")} |`).join("\n")}
     filter: (node) => node.nodeName === "PRE",
     replacement: (_content, node) => {
       const element = node;
-      const fragment = load2(element.outerHTML);
+      const fragment = load4(element.outerHTML);
       const tokenLines = fragment(".token-line").toArray();
       const code = (tokenLines.length > 0 ? tokenLines.map((line) => fragment(line).text()).join("\n") : fragment("pre").text()).replace(/\n$/, "");
       const language = ["code", "pre"].flatMap((selector) => {
@@ -3343,8 +3529,127 @@ ${fence}
   };
 }
 
+// src/url-api-schema-controls.ts
+var MAX_CAPTURE_BYTES2 = 8e6;
+var MAX_TAB_GROUPS = 256;
+var MAX_TABS = 1024;
+function object2(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function localReference(document, reference) {
+  if (typeof reference !== "string" || !reference.startsWith("#/")) return void 0;
+  let target2 = document;
+  try {
+    for (const part of reference.slice(2).split("/")) {
+      const key = decodeURIComponent(part).replace(/~1/g, "/").replace(/~0/g, "~");
+      if (!target2 || typeof target2 !== "object" || !Object.hasOwn(target2, key)) return void 0;
+      target2 = target2[key];
+    }
+  } catch {
+    return void 0;
+  }
+  return target2;
+}
+function resolve2(document, value) {
+  const seen = /* @__PURE__ */ new Set();
+  for (let depth = 0; depth < 32; depth += 1) {
+    const schema = object2(value);
+    if (!schema || seen.has(schema)) return void 0;
+    seen.add(schema);
+    if (!Object.hasOwn(schema, "$ref")) return schema;
+    value = localReference(document, schema.$ref);
+  }
+  return void 0;
+}
+function complete(document) {
+  let visited = 0;
+  const active = /* @__PURE__ */ new Set();
+  const visit = (value, depth) => {
+    if (++visited > 1e5 || depth > 96) return false;
+    if (typeof value === "number" && !Number.isFinite(value)) return false;
+    if (!value || typeof value !== "object") return true;
+    if (active.has(value)) return false;
+    active.add(value);
+    const schema = object2(value);
+    const valid = (!schema || !Object.hasOwn(schema, "$ref") || Boolean(object2(localReference(document, schema.$ref)))) && Object.values(value).every((child) => visit(child, depth + 1));
+    active.delete(value);
+    return valid;
+  };
+  return visit(document, 0);
+}
+function labels(document, value) {
+  const schema = resolve2(document, value);
+  if (!Array.isArray(schema?.oneOf) || schema.oneOf.length < 2 || schema.oneOf.length > 64) return void 0;
+  const result = [];
+  for (const [index, branch] of schema.oneOf.entries()) {
+    const target2 = resolve2(document, branch);
+    if (!target2) return void 0;
+    const title = object2(branch)?.title ?? target2.title;
+    result.push(typeof title === "string" && title.trim() ? title.trim().replace(/\s+/g, " ") : `Option ${index + 1}`);
+  }
+  return new Set(result).size === result.length ? result : void 0;
+}
+function apiSchemaTabGroups(body, document, operation) {
+  if (Buffer.byteLength(body) > MAX_CAPTURE_BYTES2 || !complete(document)) return [];
+  const path = object2(document.paths)?.[operation.path];
+  const method = operation.method.toLowerCase();
+  if (!/^(?:get|post|put|patch|delete|head|options|trace)$/.test(method)) return [];
+  const selected = object2(object2(path)?.[method]);
+  if (!selected) return [];
+  const { $, root } = migrationHtmlArticle(body);
+  const groups = root.find('[role="tablist"],[data-component-part="tabs-list"]');
+  if (groups.length > MAX_TAB_GROUPS || root.find('[role="tab"]').length > MAX_TABS) return [];
+  const idCounts = /* @__PURE__ */ new Map();
+  root.find("[id]").each((_index, node) => {
+    const id = $(node).attr("id");
+    idCounts.set(id, (idCounts.get(id) ?? 0) + 1);
+  });
+  const proofs = [];
+  groups.each((index, node) => {
+    const group = $(node);
+    const container = group.parent(".tabs.tab-container");
+    const field = group.closest(".object-param-field");
+    const section = field.parent(".api-section");
+    if (!group.is('[role="tablist"][data-component-part="tabs-list"]') || !container.length || !section.length || !section.closest('[id^="api-playground-"][id$="-operation-page"]').length) return;
+    if (field.parents(".object-param-field").length) return;
+    const heading = section.children(".api-section-heading");
+    const title = heading.find(".api-section-heading-title").text().trim().toLowerCase();
+    const media = heading.find("*").toArray().filter((element) => $(element).children().length === 0).map((element) => $(element).text().trim()).filter((text2) => /^[a-z][a-z\d.+-]*\/[a-z\d.+-]+$/i.test(text2));
+    if (heading.length !== 1 || !media || media.length !== 1) return;
+    let schema;
+    let scope;
+    if (title === "body") {
+      const request = resolve2(document, selected.requestBody);
+      schema = object2(object2(request?.content)?.[media[0]])?.schema;
+      scope = `request:${media[0]}`;
+    } else if (title === "response") {
+      const statuses = heading.find('button[aria-haspopup="menu"]').toArray().map((button) => $(button).text().trim()).filter((text2) => /^(?:[1-5]\d{2}|default)$/.test(text2));
+      if (statuses.length !== 1) return;
+      const response = resolve2(document, object2(selected.responses)?.[statuses[0]]);
+      schema = object2(object2(response?.content)?.[media[0]])?.schema;
+      scope = `response:${statuses[0]}:${media[0]}`;
+    } else return;
+    const expected = labels(document, schema);
+    const tabs = group.children('[role="tab"][data-component-part="tab"]');
+    if (!expected || tabs.length !== expected.length || group.children().length !== tabs.length) return;
+    const panels = container.children('[data-component-part="tabs-panels"]').children('[role="tabpanel"][data-component-part="tab-content"]');
+    if (panels.length !== tabs.length) return;
+    const ids = /* @__PURE__ */ new Set();
+    for (const [position, tab] of tabs.toArray().entries()) {
+      const control = $(tab).attr("aria-controls");
+      const panel = panels.eq(position);
+      if ($(tab).text().trim().replace(/\s+/g, " ") !== expected[position] || !control || ids.has(control) || panel.attr("id") !== control || !$(tab).attr("id") || panel.attr("aria-labelledby") !== $(tab).attr("id") || idCounts.get(control) !== 1 || panel.text().trim() || panel.children().length) return;
+      ids.add(control);
+    }
+    proofs.push({ index, scope });
+  });
+  const scopeCounts = /* @__PURE__ */ new Map();
+  for (const proof of proofs) scopeCounts.set(proof.scope, (scopeCounts.get(proof.scope) ?? 0) + 1);
+  return proofs.filter((proof) => scopeCounts.get(proof.scope) === 1).map((proof) => proof.index);
+}
+
 // src/url-run.ts
-var CONVERTER_VERSION = "url-evidence-v4";
+var CONVERTER_VERSION = "url-evidence-v5";
 var parser = unified3().use(remarkParse3).use(remarkMdx3);
 var ACCEPT = "text/markdown,text/html,application/xhtml+xml;q=0.9";
 var MAX_RESPONSE_BYTES = 8e6;
@@ -3407,7 +3712,7 @@ function linksOf(document) {
     return [...root.find("a[href]").toArray(), ...$('link[rel="sitemap"][href],link[rel="alternate"][href]').toArray()].map((node) => $(node).attr("href")).filter(Boolean);
   }
   if (/xml/i.test(document.contentType) || /<urlset|<sitemapindex/i.test(document.body)) {
-    const $ = load3(document.body, { xmlMode: true });
+    const $ = load5(document.body, { xmlMode: true });
     return $("loc").toArray().map((node) => $(node).text().trim());
   }
   return [
@@ -3450,8 +3755,8 @@ function markdownHeadingAnchors(body) {
     return occurrence ? `${base}-${occurrence}` : base;
   });
 }
-function sourceNavigation(capture) {
-  return extractSourceNavigation(capture);
+function sourceNavigation(capture, selectedScope) {
+  return extractSourceNavigation(capture, selectedScope);
 }
 function idForUrl(url, scope) {
   const relative4 = scope === "/" ? url.pathname.slice(1) : url.pathname.slice(scope.length).replace(/^\//, "");
@@ -3460,7 +3765,7 @@ function idForUrl(url, scope) {
 }
 function articleIdentity(document) {
   if (!/html/i.test(document.contentType)) return document.finalUrl;
-  const $ = load3(document.body);
+  const $ = load5(document.body);
   const reference = $('link[rel="canonical"][href]').first().attr("href");
   if (!reference) return document.finalUrl;
   try {
@@ -3516,16 +3821,24 @@ function assetReferences(capture) {
   }
   const { $, root } = migrationHtmlArticle(capture.body);
   return [
-    ...root.find("img[src],video[poster],a[download][href]").toArray().map((node) => $(node).attr("src") ?? $(node).attr("poster") ?? $(node).attr("href")),
+    ...root.find("img[src],video[poster],a[download][href]").toArray().map((node) => $(node).is("video") ? $(node).attr("poster") : $(node).is("a") ? $(node).attr("href") : $(node).attr("src")),
     ...root.find("[srcset]").toArray().flatMap((node) => migrationImageCandidates($(node).attr("srcset") ?? "", capture.finalUrl).map((candidate) => candidate.url))
   ].filter(Boolean);
 }
-function unresolvedStaticControls(body, hasApiSchema = false) {
+function unresolvedStaticControls(body, hasApiSchema = false, coveredSchemaGroups = []) {
   const { $, root } = migrationHtmlArticle(body);
+  root.find('[role="tablist"],[data-component-part="tabs-list"]').each((index, node) => {
+    if (coveredSchemaGroups.includes(index)) $(node).remove();
+  });
   const tabs = root.find('[role="tab"]').toArray();
   for (const tab of tabs) {
     const controls = $(tab).attr("aria-controls");
-    const panels = controls ? root.find("[id]").filter((_index, node) => $(node).attr("id") === controls) : root.find('[role="tabpanel"]').eq(tabs.indexOf(tab));
+    const group = $(tab).closest('[role="tablist"]');
+    const container = group.closest(".code-group,.tabs-container,.tabs.tab-container");
+    const peers = group.find('[role="tab"]').toArray().filter((node) => $(node).closest('[role="tablist"]')[0] === group[0]);
+    const localPanels = container.find('[role="tabpanel"]').toArray().filter((node) => $(node).closest(".code-group,.tabs-container,.tabs.tab-container")[0] === container[0]);
+    const owners = container.find('[role="tablist"]').toArray().filter((node) => $(node).closest(".code-group,.tabs-container,.tabs.tab-container")[0] === container[0]);
+    const panels = controls ? root.find("[id]").filter((_index, node) => $(node).attr("id") === controls) : owners.length === 1 && peers.length === localPanels.length ? $(localPanels).eq(peers.indexOf(tab)) : $([]);
     if (panels.length !== 1 || !panels.text().trim() && !panels.find("pre,img,table,svg").length || panels.find('[aria-busy="true"],[role="progressbar"]').length) return true;
   }
   return root.find("details:not([open])").toArray().some((node) => {
@@ -3576,12 +3889,12 @@ function hasCompleteLocalApiSchema(document) {
     if (typeof value === "number" && !Number.isFinite(value)) return false;
     if (!value || typeof value !== "object") return true;
     if (Array.isArray(value)) return value.every((child) => visit(child, depth + 1));
-    const object2 = value;
-    if (Object.prototype.hasOwnProperty.call(object2, "$ref")) {
-      if (typeof object2.$ref !== "string" || !object2.$ref.startsWith("#/")) return false;
+    const object3 = value;
+    if (Object.prototype.hasOwnProperty.call(object3, "$ref")) {
+      if (typeof object3.$ref !== "string" || !object3.$ref.startsWith("#/")) return false;
       let target2 = document;
       try {
-        for (const encoded of object2.$ref.slice(2).split("/")) {
+        for (const encoded of object3.$ref.slice(2).split("/")) {
           const key = decodeURIComponent(encoded).replace(/~1/g, "/").replace(/~0/g, "~");
           if (!target2 || typeof target2 !== "object" || !Object.prototype.hasOwnProperty.call(target2, key)) return false;
           target2 = target2[key];
@@ -3590,7 +3903,7 @@ function hasCompleteLocalApiSchema(document) {
         return false;
       }
     }
-    return Object.values(object2).every((child) => visit(child, depth + 1));
+    return Object.values(object3).every((child) => visit(child, depth + 1));
   };
   return visit(document);
 }
@@ -3605,6 +3918,25 @@ function resolveMigrationRecord(records, record) {
 }
 function navigationConfig(checkpoint, records) {
   const navigation = checkpoint.navigation;
+  const shortcuts = [];
+  const collectShortcuts = (nodes) => {
+    for (const node of nodes) {
+      if (node.url) {
+        const record = records.get(canonical(node.url, checkpoint.sourceUrl) ?? "");
+        const href = record?.redirectTo ?? node.url;
+        const identity = canonical(href, checkpoint.sourceUrl);
+        const target2 = identity ? new URL(href, checkpoint.sourceUrl).href : null;
+        if (target2 && !inScope(new URL(target2), new URL(checkpoint.sourceUrl), checkpoint.scopePath) && !shortcuts.some((link) => link.label === node.label && link.href === target2)) shortcuts.push({ label: node.label, href: target2 });
+      }
+      collectShortcuts(node.children ?? []);
+    }
+  };
+  collectShortcuts(navigation);
+  const hasDropdown = navigation.some((node) => node.presentation === "dropdown");
+  const externalNavigation = shortcuts.length || hasDropdown ? { navigation: {
+    ...shortcuts.length ? { shortcuts } : {},
+    ...hasDropdown ? { display: "dropdown" } : {}
+  } } : {};
   const projection = localeProjection(checkpoint);
   const project = (nodes) => nodes.flatMap((node) => {
     const record = node.url ? records.get(canonical(node.url, node.url) ?? "") : void 0;
@@ -3625,7 +3957,7 @@ function navigationConfig(checkpoint, records) {
       return pages2.length || tab.url ? [{ tab: tab.label, ...pages2.length ? { pages: pages2 } : {}, ...tab.url ? { href: tab.url } : {} }] : [];
     });
     const primary = localizedTabs(projection.defaultLocale);
-    return { tabs: primary.length ? primary : localizedTabs(locales[0]), ...locales.length > 1 ? {
+    return { ...externalNavigation, tabs: primary.length ? primary : localizedTabs(locales[0]), ...locales.length > 1 ? {
       i18n: {
         defaultLocale: projection.defaultLocale,
         locales: locales.map((code) => ({ code, label: code === "en" ? "English" : code })),
@@ -3634,7 +3966,7 @@ function navigationConfig(checkpoint, records) {
     } : {} };
   }
   const pages = project(navigation);
-  return pages.length ? { tabs: [{ tab: "Documentation", pages }] } : null;
+  return pages.length || shortcuts.length ? { ...externalNavigation, tabs: [{ tab: "Documentation", pages }] } : null;
 }
 function canonicalLanguage(value) {
   if (!/^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,4}$/i.test(value)) return void 0;
@@ -3654,7 +3986,7 @@ function observedLocale(document, id, scopePath) {
   }
   const urlLocale = [id.split("/", 1)[0], ...scopePath.split("/"), document.finalUrl.pathname.split("/").filter(Boolean)[0]].find((segment) => segment && LOCALES.has(segment.toLowerCase()));
   if (urlLocale) candidates.push({ source: "URL", value: canonicalLanguage(urlLocale) });
-  const declared = /html/i.test(document.contentType) ? load3(document.body)("html").attr("lang")?.trim() : void 0;
+  const declared = /html/i.test(document.contentType) ? load5(document.body)("html").attr("lang")?.trim() : void 0;
   if (declared) {
     const locale = canonicalLanguage(declared);
     if (locale) candidates.push({ source: "html lang", value: locale });
@@ -3731,13 +4063,15 @@ function validateUrlMigration(checkpoint, cancelled = false) {
   const projection = localeProjection(checkpoint);
   const primaryIds = new Set(checkpoint.records.flatMap((record) => record.page && (!projection.canonicalLocale(record.page) || projection.canonicalLocale(record.page) === projection.defaultLocale) ? [projection.navigationId(record.page)] : []));
   const outputIds = /* @__PURE__ */ new Set();
-  const resolve3 = (url) => {
+  const resolve4 = (url) => {
     const record = records.get(canonical(url, checkpoint.sourceUrl) ?? "");
     return resolveMigrationRecord(records, record);
   };
   for (const record of checkpoint.records) {
     counts[record.outcome]++;
     issues.push(...record.issues ?? []);
+    warnings.push(...record.warnings ?? []);
+    if (record.outcome === "alias" && !resolveMigrationRecord(records, record)?.page) issues.push({ code: "missing-page", source: record.url, message: "An alias does not resolve to an imported source page." });
     if (record.outcome === "pending" || record.outcome === "failed") issues.push({ code: "missing-page", source: record.url, message: record.reason ?? `Inventory entry is ${record.outcome}.` });
     if (!record.page || !record.evidence) continue;
     const outputId = projection.pageId(record.page);
@@ -3756,8 +4090,9 @@ function validateUrlMigration(checkpoint, cancelled = false) {
         continue;
       }
       if (!inScope(link, source, checkpoint.scopePath)) continue;
+      if (isDiscoveryIndex(link, source)) continue;
       if (/\.(?:png|jpe?g|gif|svg|webp|avif|pdf|zip|mp4|webm|css|js|json|ya?ml)$/i.test(link.pathname)) continue;
-      const destination = resolve3(link.toString());
+      const destination = resolve4(link.toString());
       if (!destination || !["imported", "excluded"].includes(destination.outcome)) {
         issues.push({ code: "missing-page", source: record.url, message: `Unresolved internal destination: ${link}` });
       } else if (link.hash && destination.outcome === "imported") {
@@ -3784,7 +4119,9 @@ function validateUrlMigration(checkpoint, cancelled = false) {
       if (node.url) {
         const url = new URL(node.url, source);
         if (inScope(url, source, checkpoint.scopePath)) {
-          const page = resolve3(url.toString())?.page;
+          const destination = resolve4(url.toString());
+          if (destination?.outcome === "excluded" && destination.redirectTo) continue;
+          const page = destination?.page;
           if (!page) issues.push({ code: "navigation-missing", source: node.url, message: `Source navigation target ${node.label} was not imported.` });
           else if (locale && locale !== projection.defaultLocale && !outputIds.has(`${locale}/${projection.navigationId(page)}`)) {
             issues.push({ code: "navigation-missing", source: node.url, message: `The ${locale} sidebar target ${node.label} has no authored localized runtime page.` });
@@ -3801,16 +4138,32 @@ function validateUrlMigration(checkpoint, cancelled = false) {
 async function runUrlMigration(options) {
   const source = validateMigrationUrl(options.sourceUrl);
   const sourceUrl = canonical(source.toString(), source.toString());
-  const requestedScope = options.scopePath ?? (source.pathname.endsWith("/") ? source.pathname : source.pathname.slice(0, source.pathname.lastIndexOf("/")) || "/");
-  let scopeEnd = requestedScope.length;
-  while (scopeEnd > 0 && requestedScope.charCodeAt(scopeEnd - 1) === 47) scopeEnd--;
-  const scopePath = requestedScope.slice(0, scopeEnd) || "/";
-  if (!scopePath.startsWith("/") || scopePath.includes("?") || scopePath.includes("#") || !inScope(source, source, scopePath)) throw new Error("The selected documentation scope must contain the source URL.");
   const maxPages = options.maxPages ?? 1e3;
   if (!Number.isInteger(maxPages) || maxPages < 1 || maxPages > 1e4) throw new Error("maxPages must be between 1 and 10000.");
   const concurrency = Math.max(1, Math.min(32, Math.floor(options.concurrency ?? 5)));
   const batchSize = Math.max(1, Math.min(500, Math.floor(options.batchSize ?? 50)));
   if (!Number.isFinite(concurrency) || !Number.isFinite(batchSize) || options.maxCaptures !== void 0 && (!Number.isInteger(options.maxCaptures) || options.maxCaptures < 1) || options.maxTotalBytes !== void 0 && (!Number.isFinite(options.maxTotalBytes) || options.maxTotalBytes < 1)) throw new Error("Migration batch, concurrency and byte limits must be positive finite numbers.");
+  const fetcher = options.fetcher ?? defaultMigrationFetcher;
+  const acquire = options.captureProvider?.capture.bind(options.captureProvider) ?? (async ({ url }) => fetcher(url, { accept: ACCEPT }));
+  let initial;
+  let inferredScope;
+  if (options.scopePath === void 0 && !options.checkpoint && !options.signal?.aborted) {
+    initial = Promise.resolve().then(() => acquire({ url: source, signal: options.signal }));
+    try {
+      const document = await initial;
+      if (document.finalUrl.origin === source.origin) {
+        const inferred = inferUrlMigrationScope(document).scopePath;
+        if (inScope(source, source, inferred)) inferredScope = inferred;
+      }
+    } catch {
+    }
+  }
+  const capture = (request) => initial && canonical(request.url.href, sourceUrl) === sourceUrl ? initial : acquire(request);
+  const requestedScope = options.scopePath ?? options.checkpoint?.scopePath ?? inferredScope ?? (source.pathname.endsWith("/") ? source.pathname : source.pathname.slice(0, source.pathname.lastIndexOf("/")) || "/");
+  let scopeEnd = requestedScope.length;
+  while (scopeEnd > 0 && requestedScope.charCodeAt(scopeEnd - 1) === 47) scopeEnd--;
+  const scopePath = requestedScope.slice(0, scopeEnd) || "/";
+  if (!scopePath.startsWith("/") || scopePath.includes("?") || scopePath.includes("#") || !inScope(source, source, scopePath)) throw new Error("The selected documentation scope must contain the source URL.");
   const captureVersion = options.captureVersion ?? "fetch-v1";
   if (options.checkpoint && options.checkpoint.records.length > MAX_RECORDS) throw new Error("Checkpoint inventory exceeds its bound.");
   const checkpoint = options.checkpoint ? cloneUrlMigrationCheckpoint(options.checkpoint) : { schemaVersion: 1, converterVersion: CONVERTER_VERSION, sourceUrl, scopePath, captureVersion, records: [], navigation: [] };
@@ -3829,6 +4182,8 @@ async function runUrlMigration(options) {
       delete record.apiSpecification;
       delete record.version;
       delete record.issues;
+      delete record.warnings;
+      delete record.redirectTo;
       delete record.reason;
       delete record.aliasOf;
     }
@@ -3841,6 +4196,7 @@ async function runUrlMigration(options) {
   const enqueue = (value, base, discoveredBy) => {
     const url = canonical(value, base);
     if (!url || !inScope(new URL(url), source, scopePath) && !isDiscoveryIndex(new URL(url), source)) return;
+    const isAttachment = discoveredBy !== "submitted" && /\.(?:json|ya?ml)$/i.test(new URL(url).pathname);
     const existing = records.get(url);
     if (existing) {
       if (!existing.discoveredBy.includes(discoveredBy)) {
@@ -3850,10 +4206,15 @@ async function runUrlMigration(options) {
       return;
     }
     if (records.size >= MAX_RECORDS) throw new Error("Discovered URL inventory exceeded the 100000 URL safety bound.");
-    const record = { url, discoveredBy: [discoveredBy], outcome: "pending" };
+    const record = {
+      url,
+      discoveredBy: [discoveredBy],
+      outcome: isAttachment ? "excluded" : "pending",
+      ...isAttachment ? { reason: "Machine-readable attachment, not an authored article." } : {}
+    };
     records.set(url, record);
     checkpoint.records.push(record);
-    pending.push(record);
+    if (!isAttachment) pending.push(record);
     changed.push(record);
   };
   enqueue(sourceUrl, sourceUrl, "submitted");
@@ -3886,8 +4247,6 @@ async function runUrlMigration(options) {
     }
   }
   enqueueNavigation(checkpoint.navigation, sourceUrl);
-  const fetcher = options.fetcher ?? defaultMigrationFetcher;
-  const capture = options.captureProvider?.capture.bind(options.captureProvider) ?? (async ({ url }) => fetcher(url, { accept: ACCEPT }));
   const assetFetcher = options.assetFetcher ?? (!options.fetcher && !options.captureProvider ? defaultAssetFetcher : void 0);
   const usedIds = new Map([...records.values()].filter((record) => record.page).map((record) => [record.page.id, record.url]));
   const finalUrls = new Map([...records.values()].filter((record) => record.evidence && record.page).map((record) => [canonical(record.evidence.finalUrl, sourceUrl), record.url]));
@@ -3895,6 +4254,10 @@ async function runUrlMigration(options) {
   const assetPayloads = new Map(checkpoint.records.flatMap((record) => (record.assets ?? []).map((asset) => [asset.sha256, asset])));
   const assetBytes = /* @__PURE__ */ new Map();
   const retainAsset = (asset) => {
+    if (asset.unavailable) {
+      if ([404, 410].includes(asset.unavailable.status) && asset.content.byteLength === 0) return asset;
+      throw new Error("Invalid source asset availability evidence.");
+    }
     if (!acceptedAsset(asset)) throw new Error("Asset MIME/signature is unsupported or unsafe to serve.");
     const sha256 = hash(asset.content);
     const content = assetBytes.get(sha256) ?? Buffer.from(asset.content);
@@ -3927,6 +4290,11 @@ async function runUrlMigration(options) {
     let markdownRepresentation;
     try {
       delete record.reason;
+      if (/\/llms-full\.txt$/i.test(new URL(record.url).pathname)) {
+        record.outcome = "excluded";
+        record.reason = "Aggregate documentation corpus; individual articles are inventoried separately.";
+        return;
+      }
       delete record.apiSpecification;
       const represented = resolveMigrationRecord(records, record.representationOf ? records.get(record.representationOf) : void 0);
       if (represented?.outcome === "imported") {
@@ -3936,6 +4304,16 @@ async function runUrlMigration(options) {
       }
       const document = await capture({ url: new URL(record.url), signal: options.signal });
       if (options.signal?.aborted) return;
+      if (document.status && document.status >= 300 && document.status < 400 && document.headers?.location) {
+        const destination = canonical(document.headers.location, document.finalUrl.href);
+        if (destination && new URL(destination).origin !== source.origin) {
+          record.outcome = "excluded";
+          record.redirectTo = new URL(document.headers.location, document.finalUrl).href;
+          record.reason = "The source entry is a redirect to an external public resource, retained as a link.";
+          return;
+        }
+        throw new Error("Capture returned an unresolved redirect.");
+      }
       if (Buffer.byteLength(document.body) > MAX_RESPONSE_BYTES) throw new Error("Captured response exceeds the 8 MB safety bound.");
       const identity = articleIdentity(document);
       const final = canonical(identity.toString(), sourceUrl);
@@ -3943,6 +4321,7 @@ async function runUrlMigration(options) {
       if (!inScope(document.finalUrl, source, scopePath) && !(role === "index" && isDiscoveryIndex(document.finalUrl, source))) {
         record.outcome = "excluded";
         record.reason = "Redirected outside the selected origin/path.";
+        if (document.finalUrl.origin === source.origin && (!document.status || document.status >= 200 && document.status < 300)) record.redirectTo = document.finalUrl.href;
         return;
       }
       if (document.status && document.status >= 400) throw new Error(`Source page returned HTTP ${document.status}.`);
@@ -3960,7 +4339,7 @@ async function runUrlMigration(options) {
         return;
       }
       if (/html/i.test(document.contentType)) {
-        const $ = load3(document.body);
+        const $ = load5(document.body);
         $('link[rel="alternate"][type="text/markdown"][href]').each((_index, node) => {
           const alternate = canonical($(node).attr("href"), final);
           if (!alternate) return;
@@ -3974,7 +4353,7 @@ async function runUrlMigration(options) {
           changed.push(sibling);
         });
       }
-      const observedNavigation = sourceNavigation(document);
+      const observedNavigation = sourceNavigation(document, scopePath);
       if (observedNavigation.length && !(checkpoint.navigation.some((node) => node.kind === "tab") && !observedNavigation.some((node) => node.kind === "tab"))) {
         const merged = mergeSourceNavigation(checkpoint.navigation, observedNavigation);
         if (JSON.stringify(merged) !== JSON.stringify(checkpoint.navigation)) {
@@ -4016,6 +4395,7 @@ async function runUrlMigration(options) {
         record.reason = "Content could not be represented as safe inert MDX.";
         return;
       }
+      let coveredSchemaGroups = [];
       const hasSchemaChoice = /html/i.test(document.contentType) && migrationHtmlArticle(document.body).root.find('select[aria-label="Select schema type"],select[aria-label="\u9009\u62E9\u67B6\u6784\u7C7B\u578B"]').length > 0;
       if (/html/i.test(document.contentType) && markdownRepresentation && (unresolvedStaticControls(document.body) || hasSchemaChoice)) {
         const schemaCapture = await capture({ url: new URL(markdownRepresentation), signal: options.signal });
@@ -4031,6 +4411,7 @@ async function runUrlMigration(options) {
           const path = `openapi/migration-${sha256}.json`;
           record.apiSpecification = { path, sha256, document: fragment.document };
           page.openapi = `${path} ${fragment.method} ${fragment.path}`;
+          coveredSchemaGroups = apiSchemaTabGroups(document.body, fragment.document, fragment);
         }
       }
       const states = document.states ?? [];
@@ -4060,17 +4441,24 @@ ${difference}`;
       }
       record.assets = [];
       record.issues = [];
+      record.warnings = [];
       if (/html/i.test(document.contentType)) {
         const { $, root } = migrationHtmlArticle(document.body);
         root.find("nav,footer,aside,.theme-doc-breadcrumbs,.theme-doc-toc-mobile,.table-of-contents,.hash-link").remove();
         root.find('button svg,a.hash-link svg,[aria-hidden="true"] svg,svg[aria-hidden="true"],svg[data-lucide],svg[data-icon]').remove();
+        root.find("video,iframe").each((_index, node) => {
+          if (projectMigrationMedia($.html(node), document.finalUrl) !== null) {
+            record.warnings.push({ code: "source-asset-warning", source: record.url, message: "Embedded video is preserved at its original public media URL; playback depends on the original host." });
+            $(node).remove();
+          }
+        });
         if (record.apiSpecification) {
           root.find('select[aria-label="Select schema type"],select[aria-label="\u9009\u62E9\u67B6\u6784\u7C7B\u578B"]').remove();
           root.find('.option-dropdown svg[data-component-part="icon-svg"]').remove();
         }
         const unsupported = [...new Set(root.find("iframe,object,embed,canvas,svg,form,input,textarea,select,math,video,audio").toArray().map((node) => node.tagName))];
         if (unsupported.length) record.issues.push({ code: "unsupported-component", source: record.url, message: `Rendered content requires explicit review for: ${unsupported.join(", ")}.` });
-        if (!states.length && unresolvedStaticControls(document.body, Boolean(record.apiSpecification))) record.issues.push({ code: "unsupported-component", source: record.url, message: "An interactive alternative has no complete captured panel or disclosure content." });
+        if (!states.length && unresolvedStaticControls(document.body, Boolean(record.apiSpecification), coveredSchemaGroups)) record.issues.push({ code: "unsupported-component", source: record.url, message: "An interactive alternative has no complete captured panel or disclosure content." });
       }
       const suppliedAssets = new Map((document.assets ?? []).map((asset) => [canonical(asset.url, final), asset]));
       const assetUrls = [...new Set([...assetReferences(document), ...states.flatMap((state) => assetReferences(state.response))].map((url) => canonical(url, final)).filter((url) => Boolean(url)))];
@@ -4084,6 +4472,11 @@ ${difference}`;
           const supplied = suppliedAssets.get(url);
           const asset = supplied ? retainAsset(supplied) : assetRequest ? await assetRequest : null;
           if (!asset) throw new Error("Capture host did not supply asset bytes or a binary fetch boundary.");
+          if (asset.unavailable && [404, 410].includes(asset.unavailable.status) && asset.content.byteLength === 0) {
+            record.warnings.push({ code: "asset-failed", source: record.url, message: `The original source asset is unavailable (HTTP ${asset.unavailable.status}); its original URL was retained: ${url}` });
+            page.body = rewriteMarkdownDestinations(page.body, (destination) => canonical(destination, final) === url ? url : destination);
+            continue;
+          }
           const extension = acceptedAsset(asset);
           if (!extension) throw new Error("Asset MIME/signature is unsupported or unsafe to serve.");
           const sha256 = hash(asset.content);
@@ -4125,7 +4518,7 @@ ${difference}`;
     } catch (error) {
       if (options.signal?.aborted) return;
       const wasImported = record.outcome === "imported";
-      record.outcome = record.discoveredBy.every((origin) => origin === "discovery-index") ? "excluded" : "failed";
+      record.outcome = isDiscoveryIndex(new URL(record.url), source) || record.discoveredBy.every((origin) => origin === "discovery-index") ? "excluded" : "failed";
       record.reason = error instanceof Error ? error.message : String(error);
       if (record.page) {
         if (wasImported) imported--;
@@ -4150,7 +4543,7 @@ ${difference}`;
     for (const record of records.values()) {
       if (!record.representationOf) continue;
       const primary = resolveMigrationRecord(records, records.get(record.representationOf));
-      if (!primary) continue;
+      if (!primary || primary === record) continue;
       const winner = primary.outcome === "imported" ? primary : record.outcome === "imported" && primary.outcome === "failed" ? record : void 0;
       if (!winner) continue;
       const alternate = winner === primary ? record : primary;
@@ -4276,7 +4669,7 @@ function rewriteMarkdownDestinations(body, rewrite) {
     return { start: start + index, end: start + index + node.url.length, replacement };
   }).filter((edit) => edit !== null).sort((a, b) => b.start - a.start);
   for (const node of markdownNodes(body)) for (const attribute of node.attributes ?? []) {
-    if (!attribute.name || !["src", "href", "srcSet", "srcset", "img", "primaryHref", "secondaryHref"].includes(attribute.name) || !attribute.position) continue;
+    if (!attribute.name || !["src", "poster", "href", "srcSet", "srcset", "img", "primaryHref", "secondaryHref"].includes(attribute.name) || !attribute.position) continue;
     let value = attribute.value;
     if (typeof value !== "string") {
       try {
@@ -4307,7 +4700,7 @@ function rewriteMarkdownDestinations(body, rewrite) {
 // src/components.ts
 import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync2, lstatSync as lstatSync2, readFileSync as readFileSync2 } from "fs";
-import { basename, dirname as dirname2, extname as extname3, posix as posix2, relative as relative3, resolve as resolve2 } from "path";
+import { basename, dirname as dirname2, extname as extname3, posix as posix2, relative as relative3, resolve as resolve3 } from "path";
 import postcss from "postcss";
 import selectorParser from "postcss-selector-parser";
 import remarkMdx4 from "remark-mdx";
@@ -4529,6 +4922,7 @@ function renderMigrationFiles(bundle, options = {}) {
 }
 export {
   classifyMigrationResponse,
+  inferUrlMigrationScope,
   renderMigrationFiles,
   runUrlMigration,
   validateUrlMigration