@thallylabs/migrate 0.2.30 → 0.2.32

package/dist/url-migration.js

@@ -1,6 +1,6 @@
 // src/url-run.ts
 import { createHash } from "crypto";
-import { load as load2 } from "cheerio";
+import { load as load3 } from "cheerio";
 import remarkParse3 from "remark-parse";
 import remarkMdx3 from "remark-mdx";
 import { unified as unified3 } from "unified";
@@ -390,20 +390,20 @@ function utf8SvgText(content) {
   if (body[0] === 254 && body[1] === 255 || body[0] === 255 && body[1] === 254 || body[0] === 0 && body[1] === 0 || body.includes(0)) {
     return null;
   }
-  const text = body.toString("utf8");
-  if (text.includes("\uFFFD")) return null;
-  const declaration = /^<\?xml\b[^>]*\?>/iu.exec(text);
+  const text2 = body.toString("utf8");
+  if (text2.includes("\uFFFD")) return null;
+  const declaration = /^<\?xml\b[^>]*\?>/iu.exec(text2);
   if (declaration) {
     const encoding = /\bencoding\s*=\s*["']([^"']*)["']/iu.exec(declaration[0]);
     if (encoding && !/^utf-?8$/iu.test(encoding[1].trim())) return null;
-  } else if (/<\?xml\b/iu.test(text)) {
+  } else if (/<\?xml\b/iu.test(text2)) {
     return null;
   }
-  return text;
+  return text2;
 }
 function isPassiveSvg(content) {
-  const text = utf8SvgText(Buffer.from(content.buffer, content.byteOffset, content.byteLength));
-  if (text === null) return false;
+  const text2 = utf8SvgText(Buffer.from(content.buffer, content.byteOffset, content.byteLength));
+  if (text2 === null) return false;
   let isPassive = true;
   let depth = 0;
   let sawRoot = false;
@@ -455,7 +455,7 @@ function isPassiveSvg(content) {
     { xmlMode: true, decodeEntities: true, recognizeSelfClosing: true }
   );
   try {
-    parser3.write(text);
+    parser3.write(text2);
     parser3.end();
   } catch {
     return false;
@@ -530,6 +530,274 @@ function cloneUrlMigrationCheckpoint(checkpoint) {
   return clone(checkpoint);
 }
 
+// src/url-navigation.ts
+import { load } from "cheerio";
+var MAX_CAPTURE_BYTES = 8e6;
+var MAX_JSON_BYTES = 2e6;
+var MAX_NODES = 1e4;
+var MAX_DEPTH = 32;
+var MAX_STRING_LENGTH = 8192;
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function text(value) {
+  return typeof value === "string" && value.length <= MAX_STRING_LENGTH && value.trim() ? value.trim() : void 0;
+}
+function target(value, base) {
+  const reference = text(value);
+  if (!reference) return void 0;
+  try {
+    const url = new URL(reference, base);
+    return ["https:", "http:"].includes(url.protocol) && !url.username && !url.password ? url.toString() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function readJson(value) {
+  if (Buffer.byteLength(value) > MAX_JSON_BYTES) return void 0;
+  let depth = 0;
+  let quoted = false;
+  let escaped = false;
+  for (const char of value) {
+    if (quoted) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') quoted = false;
+    } else if (char === '"') quoted = true;
+    else if (char === "[" || char === "{") {
+      if (++depth > 96) return void 0;
+    } else if (char === "]" || char === "}") depth--;
+  }
+  try {
+    return JSON.parse(value);
+  } catch {
+    return void 0;
+  }
+}
+function flightRecords(stream) {
+  const bytes = Buffer.from(stream);
+  const records = [];
+  let cursor = 0;
+  while (cursor < bytes.length) {
+    const colon = bytes.indexOf(58, cursor);
+    if (colon < 0 || colon - cursor > 16 || !/^[a-f\d]*$/i.test(bytes.toString("utf8", cursor, colon))) break;
+    cursor = colon + 1;
+    if (bytes[cursor] === 84) {
+      const comma = bytes.indexOf(44, cursor + 1);
+      const length = comma < 0 ? "" : bytes.toString("utf8", cursor + 1, comma);
+      if (!/^[a-f\d]{1,8}$/i.test(length)) break;
+      const end2 = comma + 1 + Number.parseInt(length, 16);
+      if (end2 > bytes.length) break;
+      cursor = end2;
+      continue;
+    }
+    const newline = bytes.indexOf(10, cursor);
+    const end = newline < 0 ? bytes.length : newline;
+    if (bytes[cursor] === 91 || bytes[cursor] === 123) records.push(readJson(bytes.toString("utf8", cursor, end)));
+    cursor = end + 1;
+  }
+  return records;
+}
+function mintlifyNavigation(body, base, locale) {
+  const $ = load(body);
+  let stream = "";
+  const records = [];
+  $("script").each((_index, script) => {
+    const source = $(script).text();
+    const call = /^\s*self\.__next_f\.push\(\s*(\[[\s\S]*\])\s*\)\s*;?\s*$/.exec(source);
+    if (call) {
+      const value = readJson(call[1]);
+      if (Array.isArray(value) && value[0] === 1 && typeof value[1] === "string") stream += value[1];
+    } else if ($(script).attr("type") === "application/json") {
+      records.push(readJson(source));
+    }
+  });
+  records.push(...flightRecords(stream));
+  const candidates = [];
+  let visited = 0;
+  const visit = (value, depth = 0) => {
+    if (++visited > MAX_NODES * 5 || depth > 96) return;
+    if (Array.isArray(value)) {
+      for (const child of value) visit(child, depth + 1);
+    } else if (object(value)) {
+      for (const key of ["scopedNav", "docsNavWithMetadata", "anonymizedNav"]) {
+        if (object(value[key])) candidates.push({ value: value[key], rank: key === "scopedNav" ? 3 : 2 });
+      }
+      if (object(value.docsConfig) && object(value.docsConfig.navigation)) {
+        candidates.push({ value: value.docsConfig.navigation, rank: 1 });
+      }
+      for (const child of Object.values(value)) visit(child, depth + 1);
+    }
+  };
+  records.forEach((record) => visit(record));
+  const language = locale ?? text($("html").attr("lang"));
+  for (const candidate of candidates.sort((a, b) => b.rank - a.rank)) {
+    let count = 0;
+    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));
+        return url2 ? [{ kind: "page", label: value, url: url2 }] : [];
+      }
+      if (Array.isArray(value)) return value.flatMap((child) => walk(child, depth + 1, activeLocale));
+      if (!object(value)) return [];
+      if (Array.isArray(value.languages)) {
+        const languages = value.languages.filter(object);
+        const current = new URL(base);
+        current.hash = "";
+        const routeScore = (item) => {
+          let visited2 = 0;
+          let matches = false;
+          let populated = 0;
+          const scan = (node, depth2 = 0) => {
+            if (++visited2 > MAX_NODES || depth2 > MAX_DEPTH) return;
+            if (Array.isArray(node)) {
+              for (const child of node) scan(child, depth2 + 1);
+              return;
+            }
+            if (!object(node)) return;
+            const href = target(node.href, base);
+            if (href) {
+              populated++;
+              const url2 = new URL(href);
+              url2.hash = "";
+              if (url2.toString() === current.toString()) matches = true;
+            }
+            for (const key of ["tabs", "groups", "pages", "dropdowns", "anchors", "versions"]) {
+              if (Array.isArray(node[key])) scan(node[key], depth2 + 1);
+            }
+          };
+          scan(item);
+          return matches ? populated : 0;
+        };
+        const matching = languages.map((item) => ({ item, score: routeScore(item) })).filter((candidate2) => candidate2.score > 0).sort((a, b) => b.score - a.score);
+        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 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);
+      if (!label) return children;
+      if (!url && !children.length) return [];
+      return [{
+        kind,
+        label,
+        ...url ? { url } : {},
+        ...children.length ? { children } : {},
+        ...kind === "tab" && activeLocale ? { locale: activeLocale } : {}
+      }];
+    };
+    try {
+      const nodes = walk(candidate.value);
+      if (nodes.length) return nodes;
+    } catch {
+    }
+  }
+  return [];
+}
+function resolveNavigation(nodes, base) {
+  let count = 0;
+  const walk = (items, depth = 0) => {
+    if (depth > MAX_DEPTH || !Array.isArray(items)) throw new Error("Invalid source navigation.");
+    return items.flatMap((node) => {
+      if (++count > MAX_NODES || !object(node)) throw new Error("Source navigation exceeds its safety bound.");
+      const label = text(node.label);
+      if (!label) return [];
+      const url = target(node.url, base);
+      const children = node.children ? walk(node.children, depth + 1) : [];
+      return [{
+        label,
+        ...url ? { url } : {},
+        ...children.length ? { children } : {},
+        ...["tab", "group", "page"].includes(node.kind ?? "") ? { kind: node.kind } : {},
+        ...text(node.locale) ? { locale: text(node.locale) } : {}
+      }];
+    });
+  };
+  return walk(nodes);
+}
+function extractSourceNavigation(capture) {
+  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);
+  if (mintlify.length) return mintlify;
+  const $ = load(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 [];
+  let count = 0;
+  const walk = (element, excluded, depth = 0) => {
+    if (depth > MAX_DEPTH) throw new Error("Source navigation exceeds its safety bound.");
+    const result = [];
+    $(element).children().each((_index, node) => {
+      if (++count > MAX_NODES) throw new Error("Source navigation exceeds its safety bound.");
+      if (node === excluded) return;
+      const item = $(node);
+      if (item.is("a[href]")) {
+        const label = item.text().replace(/\s+/g, " ").trim();
+        const url = target(item.attr("href"), capture.finalUrl);
+        if (label && url) result.push({ label, url });
+      } else if (item.is("li,details") || item.attr("data-migration-group") !== void 0 || item.children("h2,h3,h4,h5,h6").length > 0) {
+        const directLink = item.children("a[href]").first();
+        const direct = directLink.length ? directLink : item.children("div").children("a[href]").first();
+        const label = direct.text().trim() || item.children("summary,button,span,h2,h3,h4,h5,h6").first().text().trim();
+        const children = walk(node, direct[0], depth + 1);
+        const url = target(direct.attr("href"), capture.finalUrl);
+        if (label && (url || children.length)) result.push({ label, ...url ? { url } : {}, ...children.length ? { children } : {} });
+        else result.push(...children);
+      } else result.push(...walk(node, excluded, depth + 1));
+    });
+    return result;
+  };
+  try {
+    return walk(root);
+  } catch {
+    return [];
+  }
+}
+function placeholder(node) {
+  const children = node.children ?? [];
+  return node.kind === "tab" && children.length === 1 && children[0].kind === "page" && children[0].label === node.label && !children[0].children?.length;
+}
+function mergeSourceNavigation(existing, incoming) {
+  let count = 0;
+  const merge = (left, right, depth = 0) => {
+    if (depth > MAX_DEPTH || (count += left.length + right.length) > MAX_NODES * 4) throw new Error("Source navigation exceeds its safety bound.");
+    const result = left.map((node) => ({ ...node }));
+    const identity = (node) => JSON.stringify([
+      node.kind,
+      node.label,
+      node.locale,
+      node.kind === "tab" || node.kind === "group" ? void 0 : node.url
+    ]);
+    const positions = /* @__PURE__ */ new Map();
+    result.forEach((node, index) => {
+      const key = identity(node);
+      const siblings = positions.get(key) ?? [];
+      siblings.push(index);
+      positions.set(key, siblings);
+    });
+    const offsets = /* @__PURE__ */ new Map();
+    for (const next of right) {
+      const key = identity(next);
+      const offset = offsets.get(key) ?? 0;
+      const index = positions.get(key)?.[offset];
+      offsets.set(key, offset + 1);
+      if (index === void 0) {
+        result.push({ ...next });
+        continue;
+      }
+      const previous = result[index];
+      if (placeholder(previous) && !placeholder(next)) result[index] = { ...next };
+      else if (!placeholder(previous) && placeholder(next)) continue;
+      else result[index] = { ...previous, ...next, ...previous.children || next.children ? { children: merge(previous.children ?? [], next.children ?? [], depth + 1) } : {} };
+    }
+    return result;
+  };
+  return merge(existing, incoming);
+}
+
 // src/url-images.ts
 function migrationImageUrl(value, base) {
   const url = new URL(value, base);
@@ -569,7 +837,7 @@ function migrationImageAttribute(value) {
 }
 
 // src/url.ts
-import { load } from "cheerio";
+import { load as load2 } from "cheerio";
 import remarkMdx2 from "remark-mdx";
 import remarkParse2 from "remark-parse";
 import TurndownService from "turndown";
@@ -845,9 +1113,9 @@ function collectRefs(root) {
       return;
     }
     if (ts.isAwaitExpression(node) && !inAsync) awaitOutsideAsync = true;
-    const target = ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment ? node.left : (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) && (node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken) ? node.operand : void 0;
-    if (target) {
-      let base = target;
+    const target2 = ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && node.operatorToken.kind <= ts.SyntaxKind.LastAssignment ? node.left : (ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) && (node.operator === ts.SyntaxKind.PlusPlusToken || node.operator === ts.SyntaxKind.MinusMinusToken) ? node.operand : void 0;
+    if (target2) {
+      let base = target2;
       while (ts.isPropertyAccessExpression(base) || ts.isElementAccessExpression(base)) base = base.expression;
       if (ts.isIdentifier(base) && !bound(base.text, scopes)) assigned.push(base.text);
     }
@@ -968,8 +1236,8 @@ function pageScopeNames(esmSources) {
     for (const statement of parse(source).statements) {
       for (const local of importLocals(statement.getText())) names.add(local);
       if (ts.isImportDeclaration(statement)) continue;
-      const target = ts.isExportDeclaration(statement) || ts.isExportAssignment(statement) ? void 0 : statement;
-      if (target) for (const name of declaredNames(target).names) names.add(name);
+      const target2 = ts.isExportDeclaration(statement) || ts.isExportAssignment(statement) ? void 0 : statement;
+      if (target2) for (const name of declaredNames(target2).names) names.add(name);
     }
   }
   return names;
@@ -1265,14 +1533,14 @@ ${trimmed.slice(0, marker).trimEnd()}`;
 function headingIdMarker(id) {
   return `{/* #${id} */}`;
 }
-function mintlifyHeadingSlug(text) {
-  return text.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 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(text) {
-  return text.normalize("NFC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/(^-|-$)/g, "");
+function thallyHeadingSlug(text2) {
+  return text2.normalize("NFC").toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/(^-|-$)/g, "");
 }
-function typesetQuotes(text) {
-  return text.split(/(`[^`]*`|<[^>]*>|\]\([^)]*\))/).map((part, index) => {
+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("");
@@ -1295,9 +1563,9 @@ function markMintlifyHeadings(body) {
     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 text = plainHeadingText(source);
-    const id = mintlifyHeadingSlug(text);
-    return `${heading[1]}${source}${id && id !== thallyHeadingSlug(text) ? ` ${headingIdMarker(id)}` : ""}`;
+    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([
@@ -1319,8 +1587,8 @@ function leadingPageHeading(body) {
     const root = descriptionParser.parse(body);
     const first = root.children?.find((node) => node.type !== "mdxjsEsm" && node.type !== "html" && !(node.type === "mdxFlowExpression" && node.data?.estree?.body.length === 0));
     if (first?.type !== "heading" || first.depth !== 1) return void 0;
-    const text = (node) => node.type === "mdxTextExpression" || node.type === "mdxFlowExpression" ? "" : node.value ?? (node.children ?? []).map(text).join("");
-    const title = text(first).replace(/\s+/g, " ").trim();
+    const text2 = (node) => node.type === "mdxTextExpression" || node.type === "mdxFlowExpression" ? "" : node.value ?? (node.children ?? []).map(text2).join("");
+    const title = text2(first).replace(/\s+/g, " ").trim();
     const start = first.position?.start.offset;
     const end = first.position?.end.offset;
     return title && start !== void 0 && end !== void 0 ? { title, start, end } : void 0;
@@ -1349,8 +1617,8 @@ function splitFrontmatterBlock(raw) {
 function maskCode(body) {
   const source = body.replace(/\u0000/g, "");
   const blocks = [];
-  const stash = (text) => {
-    blocks.push(text);
+  const stash = (text2) => {
+    blocks.push(text2);
     return `\0${blocks.length - 1}\0`;
   };
   const lines = [];
@@ -1377,7 +1645,7 @@ function maskCode(body) {
   if (fenceBuffer.length) lines.push(stash(fenceBuffer.join("\n")));
   return {
     masked: lines.join("\n"),
-    unmask: (text) => text.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)]),
+    unmask: (text2) => text2.replace(/\u0000(\d+)\u0000/g, (_match, index) => blocks[Number(index)]),
     openFence: codeFence
   };
 }
@@ -1385,8 +1653,8 @@ function replaceOutsideCode(body, transform) {
   const { masked, unmask } = maskCode(body);
   return unmask(transform(masked));
 }
-function mdxComment(text) {
-  return `{/*${text.replace(/\*\//g, "* /")}*/}`;
+function mdxComment(text2) {
+  return `{/*${text2.replace(/\*\//g, "* /")}*/}`;
 }
 function normalizeFernFileTrees(body) {
   return replaceOutsideCode(body, (whole) => whole.replace(
@@ -1793,12 +2061,12 @@ function maskCodeRegions(body) {
   }).join("\n");
 }
 var UNTERMINATED = "unterminated";
-function readTagEnd(text, from) {
-  if (from < text.length && !/[\s/>]/.test(text[from])) return null;
+function readTagEnd(text2, from) {
+  if (from < text2.length && !/[\s/>]/.test(text2[from])) return null;
   let depth = 0;
   let quote = "";
-  for (let i = from; i < text.length; i++) {
-    const char = text[i];
+  for (let i = from; i < text2.length; i++) {
+    const char = text2[i];
     if (quote) {
       if (char === "\\" && depth > 0) i++;
       else if (char === quote) quote = "";
@@ -1811,8 +2079,8 @@ function readTagEnd(text, from) {
     } else if (depth === 0) {
       if (char === "<") return null;
       if (char === ">") {
-        const selfClosing = text[i - 1] === "/" && i > from;
-        return { end: i + 1, selfClosing, attributes: text.slice(from, selfClosing ? i - 1 : i) };
+        const selfClosing = text2[i - 1] === "/" && i > from;
+        return { end: i + 1, selfClosing, attributes: text2.slice(from, selfClosing ? i - 1 : i) };
       }
     }
   }
@@ -1925,7 +2193,7 @@ function removeUndefinedExpressions(body, warn) {
   visit(tree);
   if (edits.length === 0) return body;
   warn?.(`Expressions that use ${[...removed].map((name) => `"${name}"`).join(", ")} were removed so the page builds: ${removed.size === 1 ? "the name is" : "the names are"} not defined on this page. Define ${removed.size === 1 ? "the name" : "the names"} or escape the braces as \\{ \\} to show the text.`);
-  return edits.sort((a, b) => b.start - a.start).reduce((text, edit) => text.slice(0, edit.start) + text.slice(edit.end), body);
+  return edits.sort((a, b) => b.start - a.start).reduce((text2, edit) => text2.slice(0, edit.start) + text2.slice(edit.end), body);
 }
 function normalizeFlowParagraphContainers(body) {
   if (!body.includes("<p")) return body;
@@ -1951,7 +2219,7 @@ function normalizeFlowParagraphContainers(body) {
     for (const child of node.children ?? []) visit(child);
   }
   visit(tree);
-  return edits.sort((a, b) => b.offset - a.offset).reduce((text, edit) => text.slice(0, edit.offset) + edit.value + text.slice(edit.offset + 1), body);
+  return edits.sort((a, b) => b.offset - a.offset).reduce((text2, edit) => text2.slice(0, edit.offset) + edit.value + text2.slice(edit.offset + 1), body);
 }
 function normalizeMdx(body, platform, unwrapMdxCodeBlocks = true) {
   const runFern = platform === "fern";
@@ -2168,7 +2436,12 @@ var PORTABLE_MDX_COMPONENTS = /* @__PURE__ */ new Set([
 ]);
 var PORTABLE_URL_PROPS = "href|src|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" },
+  { baseUrl: "\u9009\u62E9\u57FA\u7840URL", permalink: "\u5BFC\u822A\u5230\u6807\u9898" }
+];
 var remoteMarkdownParser = unified2().use(remarkParse2).use(remarkMdx2);
+var embeddedOpenApiParser = unified2().use(remarkParse2);
 function validateMigrationUrl(value) {
   let url;
   try {
@@ -2301,7 +2574,7 @@ function isSafePortableUrl(value) {
   }
 }
 function decodeHtmlAttribute(value) {
-  const document = load(`<i data-thally-value="${value.replace(/"/g, "&quot;")}"></i>`);
+  const document = load2(`<i data-thally-value="${value.replace(/"/g, "&quot;")}"></i>`);
   return document("i").attr("data-thally-value") ?? "";
 }
 function escapeMarkdownText(value, escapeTableSeparator = false) {
@@ -2318,6 +2591,43 @@ function escapeMarkdownText(value, escapeTableSeparator = false) {
   }
   return escaped;
 }
+function portableMarkdownTableCell(value) {
+  let output = "";
+  let hasOddBackslashes = false;
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (character === "\\") {
+      output += character;
+      hasOddBackslashes = !hasOddBackslashes;
+      continue;
+    }
+    if (character === "|" && !hasOddBackslashes) output += "\\";
+    if (character === "\r" || character === "\n") {
+      output += " ";
+      if (character === "\r" && value[index + 1] === "\n") index += 1;
+    } else output += character;
+    hasOddBackslashes = false;
+  }
+  return output.trim();
+}
+function needsLiteralTableCode(value) {
+  let hasOddBackslashes = false;
+  for (const character of value) {
+    if (character === "\\") hasOddBackslashes = !hasOddBackslashes;
+    else {
+      if (character === "|" && hasOddBackslashes) return true;
+      hasOddBackslashes = false;
+    }
+  }
+  return false;
+}
+function literalMdxCodeText(value) {
+  let output = "";
+  for (const character of value) {
+    output += /[A-Za-z0-9 ]/.test(character) ? character : `&#${character.codePointAt(0)};`;
+  }
+  return output;
+}
 function markdownLinkDestination(value) {
   try {
     return encodeURI(value).replace(/\(/g, "%28").replace(/\)/g, "%29").replace(/&/g, "&amp;");
@@ -2350,7 +2660,7 @@ function replacePortableHtmlImages(value) {
     if (start < cursor) continue;
     const end = htmlOpeningTagEnd(value, start + match[0].length);
     if (end === null) continue;
-    const fragment = load(value.slice(start, end));
+    const fragment = load2(value.slice(start, end));
     const image = fragment("img").first();
     const source = image.attr("src");
     const destination = source && isSafePortableUrl(source) ? markdownLinkDestination(source) : null;
@@ -2375,7 +2685,7 @@ function replacePortableHtmlAnchors(value) {
     const closing = closingMatch.exec(value);
     if (!closing) continue;
     const end = closing.index + closing[0].length;
-    const fragment = load(value.slice(start, end));
+    const fragment = load2(value.slice(start, end));
     const anchor = fragment("a").first();
     const href = anchor.attr("href");
     const label = escapeMarkdownText(anchor.text().replace(/\s+/g, " ").trim());
@@ -2405,6 +2715,11 @@ function sanitizeMarkdownUrls(value) {
       return;
     }
     if (node.type === "mdxJsxTextElement" || node.type === "mdxJsxFlowElement") {
+      const isLiteralCode = node.type === "mdxJsxTextElement" && node.name === "code" && !node.attributes?.length && (node.children ?? []).every((child) => child.type === "text");
+      if (!isLiteralCode && (!node.name || !PORTABLE_MDX_COMPONENTS.has(node.name))) {
+        hasUnsafeMdxSyntax = true;
+        return;
+      }
       for (const attribute of node.attributes ?? []) {
         if (attribute.type !== "mdxJsxAttribute" || !attribute.name || /^on[A-Z]/.test(attribute.name)) {
           hasUnsafeMdxSyntax = true;
@@ -2565,10 +2880,6 @@ function sanitizeRemoteMarkdown(body) {
     }
   }).replace(/\\[{}]/g, "");
   if (hasUnsafeExpression || /[{}]/.test(withoutStaticProps) || /\bon[A-Z][A-Za-z]*\s*=/g.test(withoutStaticProps) || hasUnsafePortableUrlProp(executable)) return null;
-  for (const match of withoutStaticProps.matchAll(/<\/?([A-Za-z][A-Za-z0-9.]*)(?:\s|>|\/)/g)) {
-    const component = match[1].split(".", 1)[0];
-    if (!PORTABLE_MDX_COMPONENTS.has(component)) return null;
-  }
   return urlSafeMarkdown;
 }
 function remoteMarkdownMetadata(body) {
@@ -2610,22 +2921,45 @@ function stripMintlifyDocumentationIndex(body) {
   return lines.slice(index).join("\n");
 }
 function extractEmbeddedOpenApi(content) {
-  const fencePattern = /^\s{0,3}(`{3,}|~{3,})(?:yaml|yml|json)\s+(\S+\.(?:yaml|yml|json))\s+(delete|get|head|options|patch|post|put|trace)\s+(\/\S+)\s*\r?\n([\s\S]*?)^\s{0,3}\1\s*$/im;
-  const match = fencePattern.exec(content);
-  if (!match) return { content };
+  if (Buffer.byteLength(content, "utf8") > MAX_LOCAL_RESPONSE_BYTES) return { content };
   try {
-    const parsed = parseYaml2(match[5], { maxAliasCount: 50 });
+    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);
+      return metadata ? [{ node: node2, method: metadata[2].toUpperCase(), path: metadata[3] }] : [];
+    });
+    if (candidates.length !== 1) return { content };
+    const { node, method, path } = candidates[0];
+    const start = node.position?.start.offset;
+    const end = node.position?.end.offset;
+    if (start === void 0 || end === void 0) return { content };
+    const lines = content.slice(start, end).split(/\r?\n/);
+    const opening = lines[0].match(/^ {0,3}(`{3,}|~{3,})/);
+    const closing = lines.at(-1)?.match(/^ {0,3}(`{3,}|~{3,})[\t ]*$/);
+    if (!opening || !closing || opening[1][0] !== closing[1][0] || closing[1].length < opening[1].length) return { content };
+    const parsed = parseYaml2(node.value ?? "", { 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 };
-    const method = match[3].toUpperCase();
-    const path = match[4];
     const paths = document.paths;
     if (!paths || typeof paths !== "object" || Array.isArray(paths)) return { content };
+    if (!Object.prototype.hasOwnProperty.call(paths, path)) return { content };
     const pathItem = paths[path];
-    if (!pathItem || typeof pathItem !== "object" || Array.isArray(pathItem) || !(match[3].toLowerCase() in pathItem)) return { content };
-    const before = content.slice(0, match.index).replace(/(?:^|\n)##\s+OpenAPI\s*\n\s*$/i, "\n");
-    const after = content.slice(match.index + match[0].length);
+    if (!pathItem || typeof pathItem !== "object" || Array.isArray(pathItem) || !Object.prototype.hasOwnProperty.call(pathItem, method.toLowerCase())) return { content };
+    const operation = pathItem[method.toLowerCase()];
+    if (!operation || typeof operation !== "object" || Array.isArray(operation)) return { content };
+    let values = 0;
+    let textLength = 0;
+    const serialized = JSON.stringify(document, (_key, value) => {
+      values += 1;
+      if (typeof value === "string") textLength += value.length;
+      if (values > 1e5 || textLength > MAX_LOCAL_RESPONSE_BYTES || typeof value === "number" && !Number.isFinite(value)) throw new Error("OpenAPI document exceeds portable data limits.");
+      return value;
+    });
+    if (Buffer.byteLength(serialized, "utf8") > MAX_LOCAL_RESPONSE_BYTES) return { content };
+    const before = content.slice(0, start).replace(/(?:^|\n)##\s+OpenAPI\s*\n\s*$/i, "\n");
+    const after = content.slice(end);
     return {
       content: `${before}${after}`.trim(),
       openapi: `${method} ${path}`,
@@ -2676,14 +3010,74 @@ function markdownPage(document, id, platform, warn) {
     openApiFragment: embeddedOpenApi.fragment
   };
 }
+function migrationHtmlArticle(body) {
+  const $ = load2(body);
+  const root = ["main article", "article", "main", '[role="main"]', "body"].map((selector) => $(selector).first()).find((candidate) => candidate.length);
+  root.find([
+    "script",
+    "style",
+    "noscript",
+    "nav",
+    "footer",
+    "aside",
+    ".theme-doc-version-badge",
+    ".theme-doc-breadcrumbs",
+    ".theme-doc-toc-mobile",
+    ".table-of-contents",
+    ".chat-assistant-floating-input",
+    ".chat-assistant-sheet",
+    "#chat-assistant-sheet",
+    "#chat-assistant-textarea"
+  ].join(",")).remove();
+  const permalinkSelectors = MINTLIFY_ARTICLE_LABELS.map((labels) => `a[aria-label="${labels.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();
+    if (parent.is("div") && !parent.text().trim() && parent.children().length === 0) parent.remove();
+  });
+  root.find('svg.lucide-chevrons-up-down,summary[data-component-part="expandable-button"] svg[data-component-part="icon-svg"]').remove();
+  root.find('li.task-list-item > input[type="checkbox"][disabled]').each((_index, element) => {
+    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) => {
+    const select = $(element);
+    const options = select.children("option").toArray();
+    if (!options.length || options.length !== select.children().length) return;
+    const urls = [];
+    for (const option of options) {
+      if ($(option).children().length) return;
+      const label = $(option).text().trim();
+      if (!/^https:\/\//i.test(label) || /[\s\u0000-\u001f\u007f]/.test(label)) return;
+      try {
+        const url = new URL(label);
+        if (url.protocol !== "https:" || url.username || url.password) return;
+        urls.push({ label, href: url.href, isSelected: $(option).attr("selected") !== void 0 });
+      } catch {
+        return;
+      }
+    }
+    const projection = $("<div data-thally-static-base-urls></div>");
+    const sourceId = select.attr("id");
+    if (sourceId) projection.attr("id", sourceId);
+    projection.append($("<p></p>").text(select.attr("aria-label")));
+    const list = $("<ul></ul>");
+    for (const url of urls) {
+      const item = $("<li></li>").append($("<a></a>").attr("href", url.href).text(url.label));
+      if (url.isSelected) item.append(" (selected)");
+      list.append(item);
+    }
+    projection.append(list);
+    select.replaceWith(projection);
+  });
+  return { $, root };
+}
 function htmlPage(document, id, options = {}) {
-  const $ = load(document.body);
-  const links = $('nav a[href], main a[href], article a[href], [role="main"] a[href]').map((_index, element) => $(element).attr("href") ?? "").get().filter(Boolean);
-  const scopedTitle = options.omitDocumentHeading ? $('main article, article, main, [role="main"]').first().find("h1").first().text().trim() : "";
+  const { $, root } = migrationHtmlArticle(document.body);
+  const links = root.find("a[href]").map((_index, element) => $(element).attr("href") ?? "").get().filter(Boolean);
+  const scopedTitle = options.omitDocumentHeading ? root.find("h1").first().text().trim() : "";
   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();
-  const content = $('main article, article, main, [role="main"]').first();
-  const root = content.length ? content : $("body");
   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";
   root.find(excludedElements).remove();
@@ -2697,6 +3091,9 @@ function htmlPage(document, id, options = {}) {
 `;
       heading.remove();
     }
+    root.find("h1").each((_index, element) => {
+      element.name = "h2";
+    });
   }
   root.find("a[href]").each((_index, element) => {
     const href = $(element).attr("href");
@@ -2726,8 +3123,20 @@ function htmlPage(document, id, options = {}) {
       $(element).removeAttr("src");
     }
   });
-  const turndown = new TurndownService({ codeBlockStyle: "fenced", emDelimiter: "_", headingStyle: "atx" });
+  const turndown = new TurndownService({ codeBlockStyle: "fenced", emDelimiter: "_", headingStyle: "atx", preformattedCode: true });
+  let isConvertingTableCell = false;
   turndown.remove(["script", "style", "noscript"]);
+  turndown.addRule("migration-literal-table-code", {
+    filter: (node) => isConvertingTableCell && node.nodeName === "CODE" && node.parentNode?.nodeName !== "PRE" && needsLiteralTableCode(node.textContent ?? ""),
+    // A strict, attribute-free text leaf preserves the payload that GFM's
+    // escaped-pipe code-span grammar cannot represent without changing it.
+    replacement: (_content, node) => `<code>${literalMdxCodeText(node.textContent ?? "")}</code>`
+  });
+  turndown.addRule("migration-static-task-checkbox", {
+    filter: (node) => node.nodeName === "SPAN" && ["checked", "unchecked"].includes(node.getAttribute("data-thally-static-task-checkbox") ?? ""),
+    // Emit literal task-list syntax rather than escaping its brackets as copy.
+    replacement: (_content, node) => node.getAttribute("data-thally-static-task-checkbox") === "checked" ? "[x] " : "[ ] "
+  });
   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;")}" />
@@ -2736,12 +3145,12 @@ function htmlPage(document, id, options = {}) {
   };
   if (options.preserveAnchors) turndown.addRule("migration-source-anchor", {
     filter: (node) => node.hasAttribute("id") && node.nodeName !== "PRE",
-    replacement: (content2, node) => {
+    replacement: (content, node) => {
       const element = node;
       const heading = element.nodeName.match(/^H([1-6])$/);
       return `
 
-${anchor(element)}${heading ? `${"#".repeat(Number(heading[1]))} ` : ""}${content2}
+${anchor(element)}${heading ? `${"#".repeat(Number(heading[1]))} ${content.trim()}` : content}
 
 `;
     }
@@ -2766,10 +3175,10 @@ ${anchor(element)}${heading ? `${"#".repeat(Number(heading[1]))} ` : ""}${conten
     });
     turndown.addRule("migration-responsive-picture", {
       filter: "picture",
-      replacement: (content2) => `
+      replacement: (content) => `
 
 <picture>
-${content2.trim()}
+${content.trim()}
 </picture>
 
 `
@@ -2781,7 +3190,7 @@ ${content2.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 = load(element.outerHTML);
+      const fragment = load2(element.outerHTML);
       const clone = fragment(".theme-admonition").first();
       const title2 = clone.find('[class*="admonitionHeading"],.admonition-heading').first();
       const titleText = title2.text().trim();
@@ -2802,7 +3211,7 @@ ${titleText ? `**${escapeMarkdownText(titleText)}**
     filter: (node) => node.nodeName === "DIV" && node.classList.contains("tabs-container"),
     replacement: (_content, node) => {
       const element = node;
-      const fragment = load(element.outerHTML);
+      const fragment = load2(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 panels = container.find('[role="tabpanel"]').toArray().filter((panel) => fragment(panel).closest(".tabs-container")[0] === container[0]);
@@ -2830,11 +3239,16 @@ ${tabs.join("\n\n")}
   turndown.addRule("gfm-table", {
     filter: "table",
     replacement: (_content, node) => {
-      const fragment = load(node.outerHTML);
-      const rows = fragment("tr").toArray().map((row) => fragment(row).children("th,td").toArray().map((cell) => escapeMarkdownText(
-        fragment(cell).text().replace(/\s+/g, " ").trim(),
-        true
-      ))).filter((row) => row.length > 0);
+      const fragment = load2(node.outerHTML);
+      const rows = fragment("tr").toArray().map((row) => fragment(row).children("th,td").toArray().map((cell) => {
+        const wasConvertingTableCell = isConvertingTableCell;
+        isConvertingTableCell = true;
+        try {
+          return portableMarkdownTableCell(turndown.turndown(fragment(cell).html() ?? ""));
+        } finally {
+          isConvertingTableCell = wasConvertingTableCell;
+        }
+      })).filter((row) => row.length > 0);
       if (rows.length === 0) return "";
       const width = Math.max(...rows.map((row) => row.length));
       const normalized = rows.map((row) => [...row, ...Array(width - row.length).fill("")]);
@@ -2851,7 +3265,7 @@ ${normalized.slice(1).map((row) => `| ${row.join(" | ")} |`).join("\n")}
     filter: (node) => node.nodeName === "PRE",
     replacement: (_content, node) => {
       const element = node;
-      const fragment = load(element.outerHTML);
+      const fragment = load2(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 = fragment("code").attr("class")?.match(/(?:language-|lang-)([A-Za-z0-9_+-]+)/)?.[1] ?? "";
@@ -2867,7 +3281,7 @@ ${fence}
     }
   });
   const escape = turndown.escape.bind(turndown);
-  turndown.escape = (text) => escape(text).replace(/[<{}]/g, (match) => `\\${match}`);
+  turndown.escape = (text2) => isConvertingTableCell ? escape(text2.replace(/[<>{}]/g, (character) => ({ "<": "&lt;", ">": "&gt;", "{": "&#123;", "}": "&#125;" })[character])) : escape(text2).replace(/[<{}]/g, (match) => `\\${match}`);
   const body = `${documentHeadingAnchor}${turndown.turndown(root.html() ?? "").trim()}`;
   if (!title || body.length < 40 && $("article").length === 0) return { page: null, links };
   return {
@@ -2885,7 +3299,7 @@ ${fence}
 }
 
 // src/url-run.ts
-var CONVERTER_VERSION = "url-evidence-v2";
+var CONVERTER_VERSION = "url-evidence-v4";
 var parser = unified3().use(remarkParse3).use(remarkMdx3);
 var ACCEPT = "text/markdown,text/html,application/xhtml+xml;q=0.9";
 var MAX_RESPONSE_BYTES = 8e6;
@@ -2895,9 +3309,12 @@ var LOCALES = /* @__PURE__ */ new Set(["ar", "cs", "da", "de", "el", "en", "es",
 function hash(value) {
   return createHash("sha256").update(value).digest("hex");
 }
+function canonicalJson(value) {
+  const canonical2 = (value2) => Array.isArray(value2) ? value2.map(canonical2) : value2 !== null && typeof value2 === "object" ? Object.fromEntries(Object.entries(value2).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, field]) => [key, canonical2(field)])) : value2;
+  return JSON.stringify(canonical2(value));
+}
 function pageHash(page) {
-  const canonical2 = (value) => Array.isArray(value) ? value.map(canonical2) : value !== null && typeof value === "object" ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, field]) => [key, canonical2(field)])) : value;
-  return hash(JSON.stringify(canonical2(page)));
+  return hash(canonicalJson(page));
 }
 function inScope(url, source, scope) {
   return url.origin === source.origin && !url.username && !url.password && (scope === "/" || url.pathname === scope || url.pathname.startsWith(`${scope}/`));
@@ -2916,7 +3333,7 @@ function canonical(value, base) {
 }
 function classifyMigrationResponse(document) {
   if (document.status && document.status >= 400) return "unsupported";
-  if (/\/(?:llms(?:-full)?|robots)\.txt$|\/sitemap[^/]*\.xml$|\/search(?:\.html)?$/i.test(document.finalUrl.pathname) || /(?:xml|json)/i.test(document.contentType)) return "index";
+  if (/\/(?:llms(?:-full)?|robots)\.txt$|\/sitemap[^/]*\.xml$|\/search(?:\.html)?$/i.test(document.finalUrl.pathname) || /\.(?:json|ya?ml)$/i.test(document.finalUrl.pathname) || /(?:xml|json)/i.test(document.contentType)) return "index";
   if (/^(?:image|audio|video)\//i.test(document.contentType) || /\.(?:pdf|zip|png|jpe?g|webp|gif|svg|ico|mp4|webm)$/i.test(document.finalUrl.pathname)) return "asset";
   return /(?:html|markdown|text\/plain)/i.test(document.contentType) || /\.mdx?$/i.test(document.finalUrl.pathname) ? "page" : "unsupported";
 }
@@ -2938,14 +3355,14 @@ function alternativeBlocks(body, baseline) {
   return blocks(body).filter((block) => !originals.has(block)).join("\n\n");
 }
 function linksOf(document) {
+  if (/json|ya?ml/i.test(document.contentType) || /\.(?:json|ya?ml)$/i.test(document.finalUrl.pathname)) return [];
   if (/html/i.test(document.contentType)) {
-    const $ = load2(document.body);
-    const root = $('main article,article,main,[role="main"]').first();
+    const { $, root } = migrationHtmlArticle(document.body);
     root.find("nav,footer,aside").remove();
     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 $ = load2(document.body, { xmlMode: true });
+    const $ = load3(document.body, { xmlMode: true });
     return $("loc").toArray().map((node) => $(node).text().trim());
   }
   return [
@@ -2954,8 +3371,7 @@ function linksOf(document) {
   ];
 }
 function htmlEvidence(document) {
-  const $ = load2(document.body);
-  const root = $('main article,article,main,[role="main"]').first();
+  const { $, root } = migrationHtmlArticle(document.body);
   const article = root.length ? root : $("body");
   article.find("nav,footer,aside,form,script,style").remove();
   return {
@@ -2982,55 +3398,35 @@ function evidenceOf(capture) {
 function markdownHeadingAnchors(body) {
   const seen = /* @__PURE__ */ new Map();
   return markdownNodes(body).filter((node) => node.type === "heading").map((node) => {
-    const text = (value) => value.value ?? (value.children ?? []).map(text).join("");
-    const base = text(node).toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s/g, "-");
+    const text2 = (value) => value.value ?? (value.children ?? []).map(text2).join("");
+    const base = text2(node).toLowerCase().replace(/[^\p{L}\p{N}\s_-]/gu, "").replace(/\s/g, "-");
     const occurrence = seen.get(base) ?? 0;
     seen.set(base, occurrence + 1);
     return occurrence ? `${base}-${occurrence}` : base;
   });
 }
 function sourceNavigation(capture) {
-  if (capture.navigation) {
-    const resolve3 = (nodes, depth = 0) => {
-      if (depth > 32 || nodes.length > 1e4) throw new Error("Source navigation exceeds its depth or width safety bound.");
-      return nodes.map((node) => ({ label: node.label, ...node.url ? { url: new URL(node.url, capture.finalUrl).toString() } : {}, ...node.children ? { children: resolve3(node.children, depth + 1) } : {} }));
-    };
-    return resolve3(capture.navigation);
-  }
-  if (!/html/i.test(capture.contentType)) return [];
-  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) ?? $("aside").first();
-  if (!root.length) return [];
-  const walk = (element, excluded) => {
-    const result = [];
-    $(element).children().each((_index, node) => {
-      if (node === excluded) return;
-      const item = $(node);
-      if (item.is("a[href]")) {
-        result.push({ label: item.text().replace(/\s+/g, " ").trim(), url: new URL(item.attr("href"), capture.finalUrl).toString() });
-      } else if (item.is("li,details") || item.attr("data-migration-group") !== void 0 || item.children("h2,h3,h4,h5,h6").length > 0) {
-        const directLink = item.children("a[href]").first();
-        const direct = directLink.length ? directLink : item.children("div").children("a[href]").first();
-        const label = direct.text().trim() || item.children("summary,button,span,h2,h3,h4,h5,h6").first().text().trim();
-        const children = walk(node, direct[0]);
-        if (label) result.push({ label, ...direct.length ? { url: new URL(direct.attr("href"), capture.finalUrl).toString() } : {}, ...children.length ? { children } : {} });
-        else result.push(...children);
-      } else result.push(...walk(node, excluded));
-    });
-    return result;
-  };
-  try {
-    return walk(root);
-  } catch {
-    return [];
-  }
+  return extractSourceNavigation(capture);
 }
 function idForUrl(url, scope) {
   const relative4 = scope === "/" ? url.pathname.slice(1) : url.pathname.slice(scope.length).replace(/^\//, "");
   const id = pageIdFromReference(relative4 || "introduction", true);
   return id && `${id}${url.search ? `--${hash(url.search).slice(0, 12)}` : ""}`;
 }
+function articleIdentity(document) {
+  if (!/html/i.test(document.contentType)) return document.finalUrl;
+  const $ = load3(document.body);
+  const reference = $('link[rel="canonical"][href]').first().attr("href");
+  if (!reference) return document.finalUrl;
+  try {
+    const target2 = new URL(reference, document.finalUrl);
+    const source = document.finalUrl;
+    const directory = (path) => path.replace(/\/index\/?$/i, "").replace(/\/$/, "");
+    return target2.origin === source.origin && !target2.username && !target2.password && target2.search === source.search && directory(target2.pathname) === directory(source.pathname) ? target2 : source;
+  } catch {
+    return document.finalUrl;
+  }
+}
 function convert(document, id) {
   if (/html/i.test(document.contentType)) {
     const technical = htmlEvidence(document);
@@ -3048,9 +3444,20 @@ function convert(document, id) {
         const info = original.split("\n", 1)[0].replace(/^`+|^~+/, "");
         const code = technical.code[index];
         const fence = "`".repeat(Math.max(3, ...[...code.matchAll(/`+/g)].map((match) => match[0].length + 1)));
+        const lineStart = page.body.lastIndexOf("\n", start - 1) + 1;
+        const prefix = page.body.slice(lineStart, start);
+        let hasContainerPrefix = true;
+        for (const character of prefix) {
+          if (character !== " " && character !== "	" && character !== ">") {
+            hasContainerPrefix = false;
+            break;
+          }
+        }
+        const indent = hasContainerPrefix ? prefix : "";
+        const payload = code.split("\n").map((line) => `${indent}${line}`).join("\n");
         page.body = `${page.body.slice(0, start)}${fence}${info}
-${code}
-${fence}${page.body.slice(end)}`;
+${payload}
+${indent}${fence}${page.body.slice(end)}`;
       }
     }
     return page;
@@ -3062,16 +3469,14 @@ function assetReferences(capture) {
   if (!/html/i.test(capture.contentType)) {
     return markdownNodes(capture.body).filter((node) => node.type === "image").flatMap((node) => node.url ? [node.url] : []);
   }
-  const $ = load2(capture.body);
-  const root = $('main article,article,main,[role="main"]').first();
+  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("[srcset]").toArray().flatMap((node) => migrationImageCandidates($(node).attr("srcset") ?? "", capture.finalUrl).map((candidate) => candidate.url))
   ].filter(Boolean);
 }
-function unresolvedStaticControls(body) {
-  const $ = load2(body);
-  const root = $('main article,article,main,[role="main"]').first();
+function unresolvedStaticControls(body, hasApiSchema = false) {
+  const { $, root } = migrationHtmlArticle(body);
   const tabs = root.find('[role="tab"]').toArray();
   for (const tab of tabs) {
     const controls = $(tab).attr("aria-controls");
@@ -3079,6 +3484,7 @@ function unresolvedStaticControls(body) {
     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) => {
+    if (hasApiSchema && $(node).is(".expandable") && $(node).children('summary[data-component-part="expandable-button"]').length) return false;
     const clone = $(node).clone();
     clone.children("summary").remove();
     return !clone.text().trim() && !clone.find("pre,img,table,svg").length;
@@ -3116,33 +3522,85 @@ function acceptedAsset(asset) {
 }
 function validRecord(record) {
   if (record.outcome !== "imported") return true;
-  return Boolean(record.page && record.pageSha256 === pageHash(record.page) && record.evidence && pageIdFromReference(record.page.id, true) === record.page.id && pageIdFromReference(record.page.navigationId, true) === record.page.navigationId && sanitizeRemoteMarkdown(record.page.body.replace(/^<a id="[^"<]*" \/>$/gm, "")) !== null && /^[a-f0-9]{64}$/.test(record.evidence.sha256) && record.assets?.every((asset) => /^migration-assets\/[a-f0-9]{64}\.[a-z0-9]+$/.test(asset.path) && hash(Buffer.from(asset.base64, "base64")) === asset.sha256));
+  return Boolean(record.page && record.pageSha256 === pageHash(record.page) && record.evidence && pageIdFromReference(record.page.id, true) === record.page.id && pageIdFromReference(record.page.navigationId, true) === record.page.navigationId && sanitizeRemoteMarkdown(record.page.body.replace(/^<a id="[^"<]*" \/>$/gm, "")) !== null && /^[a-f0-9]{64}$/.test(record.evidence.sha256) && (!record.apiSpecification || hasCompleteLocalApiSchema(record.apiSpecification.document) && record.apiSpecification.path === `openapi/migration-${record.apiSpecification.sha256}.json` && hash(canonicalJson(record.apiSpecification.document)) === record.apiSpecification.sha256) && record.assets?.every((asset) => /^migration-assets\/[a-f0-9]{64}\.[a-z0-9]+$/.test(asset.path) && hash(Buffer.from(asset.base64, "base64")) === asset.sha256));
+}
+function hasCompleteLocalApiSchema(document) {
+  let visited = 0;
+  const visit = (value, depth = 0) => {
+    if (++visited > 1e5 || depth > 96) return false;
+    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;
+      let target2 = document;
+      try {
+        for (const encoded of object2.$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];
+        }
+      } catch {
+        return false;
+      }
+    }
+    return Object.values(object2).every((child) => visit(child, depth + 1));
+  };
+  return visit(document);
+}
+function resolveMigrationRecord(records, record) {
+  const seen = /* @__PURE__ */ new Set();
+  while (record?.outcome === "alias") {
+    if (seen.has(record.url) || seen.size >= 32) return void 0;
+    seen.add(record.url);
+    record = records.get(record.aliasOf ?? "");
+  }
+  return record;
 }
-function navigationConfig(navigation, records) {
+function navigationConfig(checkpoint, records) {
+  const navigation = checkpoint.navigation;
+  const projection = localeProjection(checkpoint);
   const project = (nodes) => nodes.flatMap((node) => {
     const record = node.url ? records.get(canonical(node.url, node.url) ?? "") : void 0;
-    const target = record?.outcome === "alias" ? records.get(record.aliasOf ?? "") : record;
-    const page = target?.page;
+    const target2 = resolveMigrationRecord(records, record);
+    const page = target2?.page;
     const children = project(node.children ?? []);
     if (children.length) {
-      const contains = (entries) => entries.some((entry) => typeof entry === "string" ? entry === page?.navigationId : contains(entry.pages));
-      return [{ group: node.label || "Documentation", pages: [...page && !contains(children) ? [page.navigationId] : [], ...children] }];
+      const contains = (entries) => entries.some((entry) => typeof entry === "string" ? entry === (page && projection.navigationId(page)) : contains(entry.pages));
+      return [{ group: node.label || "Documentation", pages: [...page && !contains(children) ? [projection.navigationId(page)] : [], ...children] }];
     }
-    return page ? [page.navigationId] : [];
+    return page ? [projection.navigationId(page)] : [];
   });
+  const tabs = navigation.filter((node) => node.kind === "tab");
+  if (tabs.length) {
+    const locales = [...new Set(tabs.map((tab) => tab.locale ?? projection.defaultLocale))];
+    const localizedTabs = (locale) => tabs.filter((tab) => (tab.locale ?? projection.defaultLocale) === locale).flatMap((tab) => {
+      const pages2 = project(tab.children ?? []);
+      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 ? {
+      i18n: {
+        defaultLocale: projection.defaultLocale,
+        locales: locales.map((code) => ({ code, label: code === "en" ? "English" : code })),
+        navigation: Object.fromEntries(locales.map((locale) => [locale, localizedTabs(locale)]))
+      }
+    } : {} };
+  }
   const pages = project(navigation);
   return pages.length ? { 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;
+  try {
+    return Intl.getCanonicalLocales(value)[0];
+  } catch {
+    return void 0;
+  }
+}
 function observedLocale(document, id, scopePath) {
   const issues = [];
-  const canonicalLanguage = (value) => {
-    if (!/^[a-z]{2,3}(?:-[a-z0-9]{2,8}){0,4}$/i.test(value)) return void 0;
-    try {
-      return Intl.getCanonicalLocales(value)[0];
-    } catch {
-      return void 0;
-    }
-  };
   const candidates = [];
   if (document.locale) {
     const locale = canonicalLanguage(document.locale);
@@ -3151,7 +3609,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) ? load2(document.body)("html").attr("lang")?.trim() : void 0;
+  const declared = /html/i.test(document.contentType) ? load3(document.body)("html").attr("lang")?.trim() : void 0;
   if (declared) {
     const locale = canonicalLanguage(declared);
     if (locale) candidates.push({ source: "html lang", value: locale });
@@ -3164,37 +3622,73 @@ function observedLocale(document, id, scopePath) {
 }
 function localeProjection(checkpoint) {
   const pages = checkpoint.records.flatMap((record) => record.page ? [record.page] : []);
-  const canonicalLocale = (page) => {
+  const declaredLocale = (page) => {
     try {
       return page.locale ? Intl.getCanonicalLocales(page.locale)[0] : void 0;
     } catch {
       return void 0;
     }
   };
+  const declaredLocales = [...new Set(pages.map(declaredLocale).filter((locale) => Boolean(locale)))];
+  const defaultLocale = pages.some((page) => !page.locale) || declaredLocales.includes("en") ? "en" : declaredLocales[0] ?? "en";
+  const records = new Map(checkpoint.records.map((record) => [record.url, record]));
+  const memberships = /* @__PURE__ */ new Map();
+  const observe = (nodes, parentLocale) => {
+    for (const node of nodes) {
+      const locale = node.locale ? canonicalLanguage(node.locale) : parentLocale;
+      const entry = node.url ? records.get(canonical(node.url, checkpoint.sourceUrl) ?? "") : void 0;
+      const page = resolveMigrationRecord(records, entry)?.page;
+      if (page && locale) {
+        const languages = memberships.get(page) ?? /* @__PURE__ */ new Set();
+        languages.add(locale);
+        memberships.set(page, languages);
+      }
+      observe(node.children ?? [], locale);
+    }
+  };
+  observe(checkpoint.navigation);
+  const primaryIds = new Set(pages.filter((page) => !declaredLocale(page) || declaredLocale(page) === defaultLocale).filter((page) => memberships.get(page)?.has(defaultLocale)).map((page) => page.navigationId));
+  const remapped = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const languages = memberships.get(page);
+    if (languages?.size !== 1) continue;
+    const locale = [...languages][0];
+    const prefix = `${locale.toLowerCase()}-`;
+    if (locale === defaultLocale || !page.navigationId.toLowerCase().startsWith(prefix)) continue;
+    const navigationId2 = page.navigationId.slice(prefix.length);
+    if (primaryIds.has(navigationId2)) remapped.set(page, { locale, navigationId: navigationId2 });
+  }
+  const canonicalLocale = (page) => remapped.get(page)?.locale ?? declaredLocale(page);
+  const navigationId = (page) => remapped.get(page)?.navigationId ?? page.navigationId;
   const locales = [...new Set(pages.map(canonicalLocale).filter((locale) => Boolean(locale)))];
-  const defaultLocale = pages.some((page) => !page.locale) || locales.includes("en") ? "en" : locales[0] ?? "en";
   const pageId = (page) => {
     const locale = canonicalLocale(page);
-    return locale ? `${locale === defaultLocale ? "" : `${locale}/`}${page.navigationId}` : page.id;
+    return locale ? `${locale === defaultLocale ? "" : `${locale}/`}${navigationId(page)}` : page.id;
   };
   const route = (page) => {
     const locale = canonicalLocale(page);
     const prefix = locale && locale !== defaultLocale ? `/${locale}` : "";
-    return `${prefix}${page.navigationId === "introduction" ? "/" : `/${page.navigationId}`}`;
+    return `${prefix}${navigationId(page) === "introduction" ? "/" : `/${navigationId(page)}`}`;
   };
-  return { canonicalLocale, locales, defaultLocale, pageId, route };
+  const redirects = checkpoint.records.flatMap((record) => {
+    if (!record.page || !remapped.has(record.page)) return [];
+    const source = new URL(record.url);
+    return source.search || !/^\/[A-Za-z0-9/_~.%+-]*$/.test(source.pathname) ? [] : [{ source: source.pathname, destination: route(record.page), permanent: true }];
+  });
+  return { canonicalLocale, navigationId, locales, defaultLocale, pageId, route, redirects };
 }
 function validateUrlMigration(checkpoint, cancelled = false) {
   const issues = [];
+  const warnings = [];
   const counts = { pending: 0, imported: 0, excluded: 0, failed: 0, alias: 0 };
   const records = new Map(checkpoint.records.map((record) => [record.url, record]));
   const source = new URL(checkpoint.sourceUrl);
   const projection = localeProjection(checkpoint);
-  const primaryIds = new Set(checkpoint.records.flatMap((record) => record.page && (!record.page.locale || projection.canonicalLocale(record.page) === projection.defaultLocale) ? [record.page.navigationId] : []));
+  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 record = records.get(canonical(url, checkpoint.sourceUrl) ?? "");
-    return record?.outcome === "alias" ? records.get(record.aliasOf ?? "") : record;
+    return resolveMigrationRecord(records, record);
   };
   for (const record of checkpoint.records) {
     counts[record.outcome]++;
@@ -3204,8 +3698,8 @@ function validateUrlMigration(checkpoint, cancelled = false) {
     const outputId = projection.pageId(record.page);
     if (outputIds.has(outputId)) issues.push({ code: "collision", source: record.url, message: `Multiple source pages map to runtime path ${outputId}.` });
     outputIds.add(outputId);
-    if (record.page.locale && projection.canonicalLocale(record.page) !== projection.defaultLocale && !primaryIds.has(record.page.navigationId)) {
-      issues.push({ code: "missing-page", source: record.url, message: `Secondary locale ${record.page.locale} requires a primary ${projection.defaultLocale} page at ${record.page.navigationId}; the runtime cannot serve an orphan translation.` });
+    if (projection.canonicalLocale(record.page) && projection.canonicalLocale(record.page) !== projection.defaultLocale && !primaryIds.has(projection.navigationId(record.page))) {
+      issues.push({ code: "missing-page", source: record.url, message: `Secondary locale ${projection.canonicalLocale(record.page)} requires a primary ${projection.defaultLocale} page at ${projection.navigationId(record.page)}; the runtime cannot serve an orphan translation.` });
     }
     const actual = markdownCode(record.page.body);
     if (JSON.stringify(actual) !== JSON.stringify(record.evidence.code)) issues.push({ code: "code-mismatch", source: record.url, message: "Source code payloads differ from converted code payloads." });
@@ -3227,22 +3721,37 @@ function validateUrlMigration(checkpoint, cancelled = false) {
           anchor = decodeURIComponent(anchor);
         } catch {
         }
-        if (!destination.evidence?.anchors.includes(anchor)) issues.push({ code: "missing-anchor", source: record.url, message: `Missing source anchor: ${link}` });
+        if (!destination.evidence?.anchors.includes(anchor)) {
+          warnings.push({ code: "source-link-warning", source: record.url, message: `The original source link refers to an absent source anchor: ${link}` });
+        } else if (destination.page) {
+          const nodes = markdownNodes(destination.page.body);
+          const explicit = nodes.flatMap((node) => node.name === "a" ? (node.attributes ?? []).flatMap((attribute) => attribute.name === "id" && typeof attribute.value === "string" ? [attribute.value] : []) : []);
+          if (!explicit.includes(anchor) && !markdownHeadingAnchors(destination.page.body).includes(anchor)) {
+            issues.push({ code: "missing-anchor", source: record.url, message: `Conversion lost a source anchor: ${link}` });
+          }
+        }
       }
     }
   }
-  const visit = (nodes) => {
+  const visit = (nodes, parentLocale) => {
     for (const node of nodes) {
+      const locale = node.locale ? canonicalLanguage(node.locale) : parentLocale;
       if (node.url) {
         const url = new URL(node.url, source);
-        if (inScope(url, source, checkpoint.scopePath) && !resolve3(url.toString())?.page) issues.push({ code: "navigation-missing", source: node.url, message: `Source navigation target ${node.label} was not imported.` });
+        if (inScope(url, source, checkpoint.scopePath)) {
+          const page = resolve3(url.toString())?.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.` });
+          }
+        }
       }
-      visit(node.children ?? []);
+      visit(node.children ?? [], locale);
     }
   };
   visit(checkpoint.navigation);
   if (!counts.imported) issues.push({ code: "missing-page", source: checkpoint.sourceUrl, message: "No readable article pages were imported." });
-  return { status: cancelled ? "cancelled" : issues.length ? "partial" : "passed", issues, counts };
+  return { status: cancelled ? "cancelled" : issues.length ? "partial" : "passed", issues, counts, ...warnings.length ? { warnings } : {} };
 }
 async function runUrlMigration(options) {
   const source = validateMigrationUrl(options.sourceUrl);
@@ -3272,6 +3781,11 @@ async function runUrlMigration(options) {
       delete record.pageSha256;
       delete record.evidence;
       delete record.assets;
+      delete record.apiSpecification;
+      delete record.version;
+      delete record.issues;
+      delete record.reason;
+      delete record.aliasOf;
     }
     if (record.page && pageIdFromReference(record.page.id, true) !== record.page.id) throw new Error("Checkpoint contains an unsafe page path.");
     records.set(record.url, record);
@@ -3362,13 +3876,24 @@ async function runUrlMigration(options) {
     navigationChanged = false;
   };
   const process = async (record) => {
-    if (options.signal?.aborted) return;
+    if (options.signal?.aborted || record.outcome !== "pending") return;
+    let claimedId;
+    let claimedFinal;
+    let markdownRepresentation;
     try {
       delete record.reason;
+      delete record.apiSpecification;
+      const represented = resolveMigrationRecord(records, record.representationOf ? records.get(record.representationOf) : void 0);
+      if (represented?.outcome === "imported") {
+        record.outcome = "alias";
+        record.aliasOf = represented.url;
+        return;
+      }
       const document = await capture({ url: new URL(record.url), signal: options.signal });
       if (options.signal?.aborted) return;
       if (Buffer.byteLength(document.body) > MAX_RESPONSE_BYTES) throw new Error("Captured response exceeds the 8 MB safety bound.");
-      const final = canonical(document.finalUrl.toString(), sourceUrl);
+      const identity = articleIdentity(document);
+      const final = canonical(identity.toString(), sourceUrl);
       const role = classifyMigrationResponse(document);
       if (!inScope(document.finalUrl, source, scopePath) && !(role === "index" && isDiscoveryIndex(document.finalUrl, source))) {
         record.outcome = "excluded";
@@ -3389,6 +3914,30 @@ async function runUrlMigration(options) {
         for (const link of links) enqueue(link, final, record.url);
         return;
       }
+      if (/html/i.test(document.contentType)) {
+        const $ = load3(document.body);
+        $('link[rel="alternate"][type="text/markdown"][href]').each((_index, node) => {
+          const alternate = canonical($(node).attr("href"), final);
+          if (!alternate) return;
+          const target2 = new URL(alternate), primary = new URL(final);
+          const directory = (path) => path.replace(/\.mdx?$/i, "").replace(/\/index\/?$/i, "").replace(/\/$/, "");
+          if (target2.origin !== primary.origin || target2.search !== primary.search || directory(target2.pathname) !== directory(primary.pathname) || !/\.mdx?$/i.test(target2.pathname)) return;
+          enqueue(alternate, final, "declared-markdown-representation");
+          const sibling = records.get(alternate);
+          sibling.representationOf = record.url;
+          markdownRepresentation ??= alternate;
+          changed.push(sibling);
+        });
+      }
+      const observedNavigation = sourceNavigation(document);
+      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)) {
+          checkpoint.navigation = merged;
+          navigationChanged = true;
+        }
+        enqueueNavigation(observedNavigation, final);
+      }
       if (imported >= maxPages) {
         record.outcome = "excluded";
         record.reason = "A discovery endpoint resolved to an article after the selected page limit.";
@@ -3401,14 +3950,20 @@ async function runUrlMigration(options) {
         return;
       }
       finalUrls.set(final, record.url);
-      const id = idForUrl(document.finalUrl, scopePath);
+      claimedFinal = final;
+      const id = idForUrl(identity, scopePath);
       if (!id) throw new Error("Source URL has no safe destination path.");
-      if (usedIds.has(id) && usedIds.get(id) !== record.url) {
+      const language = observedLocale(document, id, scopePath);
+      const locale = language.locale;
+      const navigationId = locale ? id.split("/").filter((segment) => segment.toLowerCase() !== locale.toLowerCase()).join("/") || "introduction" : id;
+      const identityId = locale ? `${locale}/${navigationId}` : id;
+      if (usedIds.has(identityId) && usedIds.get(identityId) !== record.url) {
         record.outcome = "failed";
-        record.reason = `Destination collision for ${id}.`;
+        record.reason = `Destination collision for ${identityId}.`;
         return;
       }
-      usedIds.set(id, record.url);
+      usedIds.set(identityId, record.url);
+      claimedId = identityId;
       const evidence = evidenceOf(document);
       const page = convert(document, id);
       if (!page) {
@@ -3416,6 +3971,23 @@ async function runUrlMigration(options) {
         record.reason = "Content could not be represented as safe inert MDX.";
         return;
       }
+      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 });
+        if (options.signal?.aborted) return;
+        if (schemaCapture.status && schemaCapture.status >= 400 || !/text\/(?:markdown|plain)/i.test(schemaCapture.contentType)) throw new Error("API schema representation is not a successful Markdown response.");
+        totalBytes += Buffer.byteLength(schemaCapture.body);
+        if (Buffer.byteLength(schemaCapture.body) > MAX_RESPONSE_BYTES || totalBytes > (options.maxTotalBytes ?? 5e8)) throw new Error("API schema capture exceeds its content byte budget.");
+        const expected = new URL(markdownRepresentation);
+        if (schemaCapture.finalUrl.origin !== expected.origin || schemaCapture.finalUrl.pathname !== expected.pathname || schemaCapture.finalUrl.search !== expected.search) throw new Error("API schema representation escaped its declared identity.");
+        const fragment = extractEmbeddedOpenApi(schemaCapture.body).fragment;
+        if (fragment && hasCompleteLocalApiSchema(fragment.document)) {
+          const sha256 = hash(canonicalJson(fragment.document));
+          const path = `openapi/migration-${sha256}.json`;
+          record.apiSpecification = { path, sha256, document: fragment.document };
+          page.openapi = `${path} ${fragment.method} ${fragment.path}`;
+        }
+      }
       const states = document.states ?? [];
       if (states.length > 64) throw new Error("Capture contains too many alternative states.");
       for (const state of states) {
@@ -3444,14 +4016,16 @@ ${difference}`;
       record.assets = [];
       record.issues = [];
       if (/html/i.test(document.contentType)) {
-        const $ = load2(document.body);
-        const root = $('main article,article,main,[role="main"]').first();
+        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();
-        if (root.find("h1").length > 1) record.issues.push({ code: "unsupported-component", source: record.url, message: "The article contains multiple level-one headings; review their hierarchy." });
+        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)) 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))) 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)))];
@@ -3491,30 +4065,18 @@ ${difference}`;
       if (sanitizeRemoteMarkdown(page.body.replace(/^<a id="[^"<]*" \/>$/gm, "")) === null) throw new Error("Converted content did not pass inert MDX validation.");
       record.evidence = evidence;
       record.page = page;
-      const language = observedLocale(document, page.id, scopePath);
       record.issues.push(...language.issues);
       const canonicalLocale = language.locale;
       if (canonicalLocale) {
         page.locale = canonicalLocale;
-        const segments = page.id.split("/");
-        const localeIndex = segments.findIndex((segment) => segment.toLowerCase() === canonicalLocale.toLowerCase());
-        page.navigationId = segments.filter((_segment, index) => index !== localeIndex).join("/") || "introduction";
+        page.navigationId = navigationId;
         page.id = `${canonicalLocale}/${page.navigationId}`;
-        if (usedIds.has(page.id) && usedIds.get(page.id) !== record.url) throw new Error(`Destination collision for locale page ${page.id}.`);
-        usedIds.delete(id);
-        usedIds.set(page.id, record.url);
       }
       record.version = document.version ?? [...page.id.split("/"), ...document.finalUrl.pathname.split("/")].find((segment) => /^v\d+(?:\.\d+)*$/i.test(segment));
       record.pageSha256 = pageHash(page);
       record.outcome = "imported";
       imported++;
-      const navigation = checkpoint.navigation.length ? [] : sourceNavigation(document);
-      if (!checkpoint.navigation.length && navigation.length) {
-        checkpoint.navigation = navigation;
-        navigationChanged = true;
-      }
       enqueueArticleLinks(evidence.links, final, record.url);
-      enqueueNavigation(navigation, final);
     } catch (error) {
       if (options.signal?.aborted) return;
       const wasImported = record.outcome === "imported";
@@ -3527,13 +4089,43 @@ ${difference}`;
       delete record.page;
       delete record.pageSha256;
       delete record.assets;
+      delete record.apiSpecification;
     } finally {
+      if (record.outcome !== "imported") {
+        if (claimedId && usedIds.get(claimedId) === record.url) usedIds.delete(claimedId);
+        if (claimedFinal && finalUrls.get(claimedFinal) === record.url) finalUrls.delete(claimedFinal);
+      }
       if (record.outcome !== "pending") {
         if (options.onRecord) await options.onRecord(record);
         changed.push(record);
       }
     }
   };
+  const settleRepresentations = () => {
+    for (const record of records.values()) {
+      if (!record.representationOf) continue;
+      const primary = resolveMigrationRecord(records, records.get(record.representationOf));
+      if (!primary) 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;
+      if (alternate.outcome === "alias" && alternate.aliasOf === winner.url) continue;
+      if (alternate.outcome === "imported") {
+        imported--;
+        if (alternate.page && usedIds.get(alternate.page.id) === alternate.url) usedIds.delete(alternate.page.id);
+      }
+      alternate.outcome = "alias";
+      alternate.aliasOf = winner.url;
+      delete alternate.reason;
+      delete alternate.page;
+      delete alternate.pageSha256;
+      delete alternate.assets;
+      delete alternate.issues;
+      delete alternate.apiSpecification;
+      changed.push(alternate);
+    }
+  };
+  settleRepresentations();
   while (cursor < pending.length && !options.signal?.aborted && !budgetExhausted && cursor < (options.maxCaptures ?? Infinity)) {
     if (imported >= maxPages) {
       const index = pending.findIndex((record, position) => position >= cursor && isDiscoveryIndex(new URL(record.url), source));
@@ -3543,17 +4135,18 @@ ${difference}`;
     const batch = pending.slice(cursor, cursor + Math.min(concurrency, imported >= maxPages ? 1 : maxPages - imported, (options.maxCaptures ?? Infinity) - cursor));
     cursor += batch.length;
     await Promise.all(batch.map(process));
+    settleRepresentations();
     if (changed.length >= batchSize) await flush();
   }
   await flush();
   const projection = localeProjection(checkpoint);
   const routeMap = /* @__PURE__ */ new Map();
   for (const record of checkpoint.records) {
-    const target = record.outcome === "alias" ? records.get(record.aliasOf ?? "") : record;
-    if (target?.page) {
-      const route = projection.route(target.page);
+    const target2 = resolveMigrationRecord(records, record);
+    if (target2?.page) {
+      const route = projection.route(target2.page);
       routeMap.set(record.url, route);
-      if (target.evidence) routeMap.set(canonical(target.evidence.finalUrl, sourceUrl), route);
+      if (target2.evidence) routeMap.set(canonical(target2.evidence.finalUrl, sourceUrl), route);
     }
   }
   const navigationLabels = /* @__PURE__ */ new Map();
@@ -3561,17 +4154,17 @@ ${difference}`;
   const labelPages = (nodes) => {
     for (const node of nodes) {
       const entry = node.url ? records.get(canonical(node.url, sourceUrl) ?? "") : void 0;
-      const target = entry?.outcome === "alias" ? records.get(entry.aliasOf ?? "") : entry;
-      if (target?.page && node.label && !node.children?.length) {
-        const previous = navigationLabels.get(target.url);
-        if (previous && previous !== node.label) navigationIssues.push({ code: "unsupported-component", source: target.url, message: `This page has multiple source navigation labels (${previous}, ${node.label}); review the shared sidebar title.` });
-        else navigationLabels.set(target.url, node.label);
+      const target2 = resolveMigrationRecord(records, entry);
+      if (target2?.page && node.label && !node.children?.length) {
+        const previous = navigationLabels.get(target2.url);
+        if (previous && previous !== node.label) navigationIssues.push({ code: "unsupported-component", source: target2.url, message: `This page has multiple source navigation labels (${previous}, ${node.label}); review the shared sidebar title.` });
+        else navigationLabels.set(target2.url, node.label);
       }
       labelPages(node.children ?? []);
     }
   };
   labelPages(checkpoint.navigation);
-  const pages = checkpoint.records.flatMap((record) => record.page ? [{ ...record.page, id: projection.pageId(record.page), ...record.page.locale ? { locale: projection.canonicalLocale(record.page) } : {}, ...navigationLabels.has(record.url) ? { navTitle: navigationLabels.get(record.url) } : {}, body: rewriteMarkdownDestinations(record.page.body, (value) => {
+  const pages = checkpoint.records.flatMap((record) => record.page ? [{ ...record.page, id: projection.pageId(record.page), navigationId: projection.navigationId(record.page), ...projection.canonicalLocale(record.page) ? { locale: projection.canonicalLocale(record.page) } : {}, ...navigationLabels.has(record.url) ? { navTitle: navigationLabels.get(record.url) } : {}, body: rewriteMarkdownDestinations(record.page.body, (value) => {
     let url;
     try {
       url = new URL(value, record.evidence.finalUrl);
@@ -3591,20 +4184,28 @@ ${difference}`;
       assets.set(asset.path, { path: asset.path, content: Buffer.from(content.buffer, content.byteOffset, content.byteLength) });
     }
   }
+  for (const record of checkpoint.records) if (record.page && record.apiSpecification) {
+    const spec = record.apiSpecification;
+    assets.set(spec.path, { path: spec.path, projectRelative: true, content: Buffer.from(canonicalJson(spec.document)) });
+  }
   const bundle = {
     sourceUrl,
     sourceKind: "url",
     platform: options.platform ?? "generic",
     pages,
     assets: [...assets.values()],
-    docsConfig: navigationConfig(checkpoint.navigation, records) ?? buildNavigationFromPages(pages),
-    warnings: validation.issues.map((issue) => ({ code: issue.code === "missing-page" ? "missing-page" : "unsupported-config", message: issue.message, source: issue.source })),
+    docsConfig: navigationConfig(checkpoint, records) ?? buildNavigationFromPages(pages),
+    warnings: [...validation.issues, ...validation.warnings ?? []].map((issue) => ({ code: issue.code === "missing-page" ? "missing-page" : "unsupported-config", message: issue.message, source: issue.source })),
     urlMigrationValidation: validation,
     stats: { discovered: records.size, imported: pages.length, skipped: records.size - pages.length }
   };
+  if (projection.redirects.length) bundle.docsConfig.redirects = projection.redirects;
   if (projection.locales.length) {
     const locales = [.../* @__PURE__ */ new Set([projection.defaultLocale, ...projection.locales])];
-    bundle.docsConfig.i18n = { defaultLocale: projection.defaultLocale, locales: locales.map((code) => ({ code, label: code === "en" ? "English" : code })) };
+    bundle.docsConfig.i18n = { ...bundle.docsConfig.i18n, defaultLocale: projection.defaultLocale, locales: locales.map((code) => ({ code, label: code === "en" ? "English" : code })) };
+  }
+  for (const spec of assets.values()) if (spec.projectRelative && spec.path.startsWith("openapi/")) {
+    bundle.docsConfig.tabs.push({ tab: `Migration API ${spec.path.slice(-69, -5)}`, hidden: true, api: { source: spec.path, navigation: false } });
   }
   const stopReason = options.signal?.aborted ? "cancelled" : budgetExhausted ? "byte-limit" : cursor < pending.length && cursor >= (options.maxCaptures ?? Infinity) ? "capture-limit" : imported >= maxPages && cursor < pending.length ? "page-limit" : cursor < pending.length ? "capture-limit" : "complete";
   return { bundle, checkpoint, validation, stopReason };
@@ -3694,7 +4295,7 @@ var DOCUSAURUS_THEME_SHIMS = {
 };
 function applyReplacements(source, replacements) {
   return replacements.sort((a, b) => b.start - a.start).reduce(
-    (text, edit) => text.slice(0, edit.start) + edit.value + text.slice(edit.end),
+    (text2, edit) => text2.slice(0, edit.start) + edit.value + text2.slice(edit.end),
     source
   );
 }
@@ -3823,18 +4424,18 @@ function mergeMigrationConfig(existing, incoming) {
       names.add(tab.tab.toLowerCase());
       continue;
     }
-    const target = tabs.find((item) => item.tab.toLowerCase() === tab.tab.toLowerCase());
-    if (!target) continue;
+    const target2 = tabs.find((item) => item.tab.toLowerCase() === tab.tab.toLowerCase());
+    if (!target2) continue;
     const incomingRootNodes = [
       ...uniqueTab.pages ?? [],
       ...uniqueTab.groups ?? []
     ];
     if (uniqueTab.pages?.length) {
-      target.pages = [...target.pages ?? target.groups ?? [], ...incomingRootNodes];
-      delete target.groups;
+      target2.pages = [...target2.pages ?? target2.groups ?? [], ...incomingRootNodes];
+      delete target2.groups;
     } else if (uniqueTab.groups?.length) {
-      if (target.pages) target.pages = [...target.pages, ...uniqueTab.groups];
-      else target.groups = [...target.groups ?? [], ...uniqueTab.groups];
+      if (target2.pages) target2.pages = [...target2.pages, ...uniqueTab.groups];
+      else target2.groups = [...target2.groups ?? [], ...uniqueTab.groups];
     }
   }
   const changelog = existing.tabs.find((tab) => tab.tab.toLowerCase() === "changelog") ?? incoming.tabs.find((tab) => tab.tab.toLowerCase() === "changelog");