blume 1.6.2 → 1.6.4

package/dist/cli/index.js

@@ -1619,6 +1619,11 @@ var pageSite = (context, page, key) => {
 };
 
 // src/audit/url.ts
+var serverRoutes = (context) => {
+  const mcp = context.project.config.ai?.mcp;
+  return mcp?.enabled ? [normalizePath(mcp.route)] : [];
+};
+var isServed = (context, path) => context.byUrl.has(path) || context.files.has(path) || context.files.has(`${path}/index.html`) || serverRoutes(context).includes(path);
 var NON_HTTP_SCHEME = /^(?!https?:)[a-z][a-z0-9+.-]*:/iu;
 var decodePath = (path) => {
   try {
@@ -2349,7 +2354,6 @@ var buildGraph = (pages, origin, deployBase = "") => {
 var orphanPages = (pages, graph, homeUrl = "/") => pages.filter((page) => page.indexable && page.url !== "/" && page.url !== homeUrl && (graph.contentIn.get(page.url)?.size ?? 0) === 0);
 
 // src/audit/checks/links.ts
-var isServed = (context, path) => context.byUrl.has(path) || context.files.has(path) || context.files.has(`${path}/index.html`);
 var MAGIC_FRAGMENTS = new Set(["", "top"]);
 var anchorResolves = (target, fragment) => {
   if (MAGIC_FRAGMENTS.has(fragment)) {
@@ -2500,7 +2504,7 @@ var llmsChecks = {
         continue;
       }
       listed.add(path);
-      if (!context.byUrl.has(path) && !context.files.has(path)) {
+      if (!isServed(context, path)) {
         found.push(finding("BLUME_AUDIT_LLMS_TXT_STALE_ENTRY", { file: llms.file, line: entry.line, url: entry.url }, `llms.txt lists ${path}, which the build does not serve.`));
       }
     }
@@ -4915,6 +4919,7 @@ import { getEntry, render } from "astro:content";
 import type { CollectionKey } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
+import { stripBasePath, withBasePath } from "blume/core/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import Accordion from "blume/components/content/Accordion.astro";
 import AccordionItem from "blume/components/content/AccordionItem.astro";
@@ -4951,6 +4956,7 @@ import TypeTable from "blume/components/content/TypeTable.astro";
 import Visibility from "blume/components/content/Visibility.astro";
 import YouTube from "blume/components/content/YouTube.astro";
 import Icon from "blume/components/Icon.astro";
+import LocaleLinks from "blume/components/layout/LocaleLinks.astro";
 import ApiOverview from "blume/components/openapi/ApiOverview.astro";
 import ApiTagOperations from "blume/components/openapi/ApiTagOperations.astro";
 import Operation from "blume/components/openapi/Operation.astro";
@@ -5138,7 +5144,22 @@ const localeAlternates =
 const defaultAlt = i18n ? (alternates ?? []).find((alt) => alt.locale === i18n.defaultLocale) : null;
 const xDefault = defaultAlt && base ? absolute(defaultAlt.path) : null;
 
-const logicalRoute = i18n ? stripLocale(route, locale) : route;
+// \`route\` arrives with \`basePath\` already applied, so the locale segment it
+// carries sits *after* the base (\`/docs/ja/guide\`), while \`localePrefix\` is
+// base-less (\`/ja\`). Stripping and re-adding a locale therefore happen in
+// base-less space, with the base re-applied at the end — the same
+// \`withBasePath(basePath, localizeRoute(...))\` composition the manifest uses to
+// build every real route. Done in based space, \`stripLocale\` matches nothing
+// and \`localizeRoute\` prepends a second prefix (\`/ja/docs/ja/guide\`). Only a
+// switcher entry for a locale with no real translation reaches this fallback:
+// a partially translated hand-written page for its missing locales, or a
+// generated reference (which has no \`alternates\` at all) for every locale
+// but its own.
+const mountLocalized = (logical: string, codeArg: string) =>
+  withBasePath(data.config.basePath, localizeRoute(logical, codeArg));
+const logicalRoute = i18n
+  ? stripLocale(stripBasePath(data.config.basePath, route), locale)
+  : route;
 const localeSwitch = i18n
   ? i18n.locales.map((l) => {
       const alt = (alternates ?? []).find((x) => x.locale === l.code);
@@ -5146,7 +5167,7 @@ const localeSwitch = i18n
         code: l.code,
         current: l.code === locale,
         dir: l.dir,
-        href: alt ? alt.path : localizeRoute(logicalRoute, l.code),
+        href: alt ? alt.path : mountLocalized(logicalRoute, l.code),
         label: l.label,
         untranslated: !alt,
       };
@@ -5160,12 +5181,9 @@ const localeSwitch = i18n
 // (manifest \`versionAlternates\` paths arrive with the base already applied).
 const versionRootFor = (id: string) => {
   const logical = id ? \`/\${id}\` : "/";
-  const localized = i18n ? localizeRoute(logical, locale) : logical;
-  const mount = data.config.basePath;
-  if (!mount) {
-    return localized;
-  }
-  return localized === "/" ? mount : \`\${mount}\${localized}\`;
+  return i18n
+    ? mountLocalized(logical, locale)
+    : withBasePath(data.config.basePath, logical);
 };
 const samePageSwitch = versionsConfig
   ? versionsConfig.switcher.redirect === "same-page"
@@ -5274,7 +5292,9 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 >
   <h1>{title}</h1>
   {frontmatter.description && <p class="text-lg text-muted-foreground">{frontmatter.description}</p>}
-  <Content components={components} />
+  <LocaleLinks locale={locale}>
+    <Content components={components} />
+  </LocaleLinks>
 </LayoutComponent>
 `;
 };
@@ -5956,7 +5976,7 @@ const Example = entry.Component;
         const bodyStyle = getComputedStyle(document.body);
         const paddingPx =
           parseFloat(bodyStyle.paddingTop) + parseFloat(bodyStyle.paddingBottom);
-        new ResizeObserver(() => {
+        const report = () => {
           window.parent.postMessage(
             {
               height:
@@ -5965,7 +5985,19 @@ const Example = entry.Component;
             },
             window.location.origin
           );
-        }).observe(wrapper);
+        };
+        new ResizeObserver(report).observe(wrapper);
+        // The parent asks for a fresh report when its listener comes up, in
+        // case the first one above was posted before anyone was listening.
+        window.addEventListener("message", (event) => {
+          if (
+            event.source === window.parent &&
+            event.origin === window.location.origin &&
+            event.data?.type === "blume:example-height-request"
+          ) {
+            report();
+          }
+        });
       })();
     </script>
   </body>
@@ -6341,7 +6373,7 @@ var pathOnly = (value) => {
   const cut = value.search(/[?#]/u);
   return cut === -1 ? value : value.slice(0, cut);
 };
-var resolveRedirects = (redirects, pageUrls) => {
+var resolveRedirects = (redirects, served) => {
   const byFrom = new Map;
   for (const redirect of redirects) {
     byFrom.set(normalizePath(redirect.from), redirect);
@@ -6375,7 +6407,7 @@ var resolveRedirects = (redirects, pageUrls) => {
     }
     const destination = chain.at(-1) ?? from;
     const external = /^https?:\/\//iu.test(destination);
-    if (!(external || pageUrls.has(destination))) {
+    if (!(external || served(destination))) {
       return { ...redirect, chain, outcome: "broken" };
     }
     return {
@@ -6463,7 +6495,7 @@ var runAudit = async (options) => {
       ...redirect,
       from: withBasePath(basePath, redirect.from),
       to: withBasePath(basePath, redirect.to)
-    })), new Set([...byUrl.keys(), ...crawl.files.keys()].map((path) => normalizePath(path)))),
+    })), (path) => isServed({ byUrl, files: crawl.files, project }, path)),
     robots: crawl.robots,
     sitemap: crawl.sitemap,
     sources: await readSources(crawl.pages),
@@ -12386,13 +12418,20 @@ var toHeading = (depth, raw, slugger, isRefDefined) => {
   const markers = parseHeadingMarkers(unescaped, isRefDefined);
   const text = markers.text.trim();
   if (text === "" && (markers.id !== undefined || markers.toc !== undefined)) {
-    return { depth, slug: slugger.slug(unescaped), text: unescaped };
+    return {
+      heading: { depth, slug: slugger.slug(unescaped), text: unescaped },
+      pinned: false
+    };
   }
   if (markers.id !== undefined) {
     occupySlug(slugger, markers.id);
-    return { depth, slug: markers.id, text };
+    return { heading: { depth, slug: markers.id, text }, pinned: true };
   }
-  return { depth, slug: slugger.slug(text), text };
+  return { heading: { depth, slug: slugger.slug(text), text }, pinned: false };
+};
+var pushHeading = (headings, state, scanned, line) => {
+  headings.push(scanned.heading);
+  state.sites.push({ line, pinned: scanned.pinned });
 };
 var noteCurlyMarker = (text, line, state) => {
   const id2 = text.match(BARE_CURLY_MARKER)?.groups?.id;
@@ -12406,7 +12445,7 @@ var scanContentLine = (line, state, slugger, headings, isRefDefined) => {
   if (atx?.groups) {
     const depth = atx.groups.hashes?.length ?? 1;
     const text = (atx.groups.text ?? "").trim();
-    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    pushHeading(headings, state, toHeading(depth, text, slugger, isRefDefined), state.line);
     noteCurlyMarker(text, state.line, state);
     state.paragraph = [];
     return;
@@ -12415,7 +12454,7 @@ var scanContentLine = (line, state, slugger, headings, isRefDefined) => {
   if (setext?.groups && state.paragraph.length > 0) {
     const depth = setext.groups.marker?.startsWith("=") ? 1 : 2;
     const text = state.paragraph.join(" ").trim();
-    headings.push(toHeading(depth, text, slugger, isRefDefined));
+    pushHeading(headings, state, toHeading(depth, text, slugger, isRefDefined), state.line - 1);
     noteCurlyMarker(text, state.paragraphStart, state);
     state.paragraph = [];
     return;
@@ -12467,7 +12506,8 @@ var scanBody = (body) => {
     paragraph: [],
     paragraphStart: 0,
     promptDepth: 0,
-    promptTag: false
+    promptTag: false,
+    sites: []
   };
   const { lines, offset } = linesWithoutFrontMatter(body);
   const definedLabels = refDefinitionLabels(lines);
@@ -12485,7 +12525,12 @@ var scanBody = (body) => {
       anchors.add(id2);
     }
   }
-  return { anchors: [...anchors], curlyMarkers: state.curlyMarkers, headings };
+  return {
+    anchors: [...anchors],
+    curlyMarkers: state.curlyMarkers,
+    headings,
+    sites: state.sites
+  };
 };
 var extractHeadings = (body) => scanBody(body).headings;
 var MD_LINK = /\[(?<label>(?:[^[\]]|\[[^\]]*\])*)\]\((?<target>(?:[^()\s]|\([^()\s]*\))+)(?<title>\s+"[^"]*")?\)/gu;
@@ -13415,6 +13460,33 @@ var operationKey = (method, path, operationId) => {
   const fromId = operationId ? slugify(splitIdentifier(operationId)) : "";
   return fromId || slugify(`${method}-${path}`);
 };
+var specOf = (specs, source) => Object.hasOwn(specs, source) ? specs[source] : undefined;
+var operationOf = (spec, id2) => Object.hasOwn(spec.operations, id2) ? spec.operations[id2] : undefined;
+var specAddresses = (spec) => {
+  const addresses = [];
+  if (spec.kind === "graphql") {
+    if (spec.endpoint) {
+      addresses.push(spec.endpoint);
+    }
+    return { addresses, label: "Endpoint" };
+  }
+  if (spec.kind === "asyncapi") {
+    const servers = spec.document.servers ?? {};
+    for (const server of Object.values(servers)) {
+      if (server?.host) {
+        addresses.push(`${server.protocol ? `${server.protocol}://` : ""}${server.host}${server.pathname ?? ""}`);
+      }
+    }
+    return { addresses, label: "Servers" };
+  }
+  const declared = spec.document.servers;
+  for (const server of Array.isArray(declared) ? declared : []) {
+    if (server.url) {
+      addresses.push(server.url);
+    }
+  }
+  return { addresses, label: "Base URL" };
+};
 var isOperation = (value) => typeof value === "object" && value !== null;
 var hasTagName = (tag) => typeof tag.name === "string";
 var tagSlugger = () => {
@@ -13673,6 +13745,19 @@ var GRAPHQL_GROUP_LABELS = {
   union: "Unions"
 };
 var isGraphqlOperationKind = (method) => GRAPHQL_OPERATION_KINDS.some((kind) => kind === method);
+var GRAPHQL_TYPE_KEYWORDS = {
+  enum: "enum",
+  input: "input",
+  interface: "interface",
+  object: "type",
+  scalar: "scalar",
+  union: "union"
+};
+var graphqlSignature = (operation) => {
+  const member = operation.method;
+  const keyword = isGraphqlOperationKind(member) ? member : GRAPHQL_TYPE_KEYWORDS[member];
+  return `${keyword} ${operation.path}`;
+};
 var byName = (a, b) => a.name < b.name ? -1 : 1;
 var extractGraphqlOperations = (document, baseRoute) => {
   const collector = operationCollector(baseRoute, new Map);
@@ -14115,6 +14200,9 @@ var columnsPrefix = (text, max) => {
   return text.slice(0, end);
 };
 
+// src/openapi/signature.ts
+var operationSignature = (spec, operation) => spec.kind === "graphql" ? graphqlSignature(operation) : `${operation.method.toUpperCase()} ${operation.path}`;
+
 // src/openapi/render-mdx.ts
 var MDX_UNSAFE = /[<{}]/gu;
 var ENTITIES = new Map([
@@ -14207,7 +14295,7 @@ ${component}` : component;
 var operationMdx = (spec, operation, reference) => {
   const method = operation.method.toUpperCase();
   const graphql = spec.kind === "graphql";
-  const fallbackTitle = graphql ? operation.path : `${method} ${operation.path}`;
+  const fallbackTitle = graphql ? operation.path : operationSignature(spec, operation);
   const title = operation.summary || fallbackTitle;
   const description = operation.description.trim() === operation.summary.trim() ? "" : operation.description;
   const flags = {};
@@ -16989,6 +17077,13 @@ var youtube = ({ props }) => {
   const title = isString4(props.title) && props.title !== "" ? props.title : "Watch on YouTube";
   return `[${title}](https://www.youtube.com/watch?v=${videoId}${start})`;
 };
+var inlineCode = (text) => {
+  const runs = text.match(/`+/gu);
+  const longest = runs ? Math.max(...runs.map((run) => run.length)) : 0;
+  const delimiter = "`".repeat(longest + 1);
+  const padded = text.startsWith("`") || text.endsWith("`") ? ` ${text} ` : text;
+  return `${delimiter}${padded}${delimiter}`;
+};
 var fencedBlock = (lang, code) => {
   const trimmed = code.replace(/(?<!\n)\n+$/u, "");
   const runs = trimmed.match(/`+/gu);
@@ -17090,6 +17185,67 @@ var downlevelComponents = (source, components, frontmatter) => {
   return splices.length > 0 ? applySplices(source, splices) : source;
 };
 
+// src/ai/openapi-components.ts
+var inlineText = (text) => text.trim().replaceAll(/\s+/gu, " ").replaceAll(/[\\`*_[\]<>~]/gu, String.raw`\$&`);
+var listItem2 = (signature, operation) => {
+  const tail = [
+    inlineText(operation.summary),
+    operation.deprecated ? "Deprecated." : ""
+  ].filter(Boolean).join(" ");
+  return `- [${inlineCode(signature)}](${linkDestination(operation.route)})${tail ? ` — ${tail}` : ""}`;
+};
+var openapiComponentSerializers = (specs) => {
+  const spec = (source) => isString4(source) ? specOf(specs, source) : undefined;
+  return {
+    ApiOverview: ({ props }) => {
+      const data = spec(props.source);
+      if (!data) {
+        return null;
+      }
+      const { addresses, label } = specAddresses(data);
+      const lines = [
+        data.version ? `Version ${inlineText(data.version)}` : "",
+        addresses.length > 0 ? `${label}: ${addresses.map(inlineCode).join(", ")}` : ""
+      ].filter(Boolean);
+      return lines.length > 0 ? lines.join(`
+
+`) : null;
+    },
+    ApiTagOperations: ({ props }) => {
+      const { tag } = props;
+      const data = spec(props.source);
+      if (!(data && isString4(tag))) {
+        return null;
+      }
+      const items = Object.values(data.operations).filter((operation) => operation.tagSlug === tag).map((operation) => listItem2(operationSignature(data, operation), operation));
+      return items.length > 0 ? items.join(`
+`) : null;
+    },
+    Operation: ({ props }) => {
+      const { id: id2 } = props;
+      const data = spec(props.source);
+      if (!(data && isString4(id2))) {
+        return null;
+      }
+      const operation = operationOf(data, id2);
+      if (!operation) {
+        return null;
+      }
+      const signature = inlineCode(operationSignature(data, operation));
+      return operation.deprecated ? `${signature}
+
+**Deprecated.**` : signature;
+    }
+  };
+};
+
+// src/ai/serializers.ts
+var projectComponentSerializers = (project) => ({
+  ...exampleComponentSerializers(project.examples ?? {}),
+  ...openapiComponentSerializers(project.sources.find(isOpenApiSource)?.openApiData() ?? {}),
+  ...project.config.ai.markdownComponents
+});
+
 // src/ai/skills.ts
 import { createHash as createHash3 } from "node:crypto";
 import { readdir as readdir2, readFile as readFile12, stat as stat3 } from "node:fs/promises";
@@ -17405,10 +17561,7 @@ ${details}` : header;
 var buildFull = async (project) => {
   const { config } = project;
   const pages = eligiblePages(project, { versions: "current" }).toSorted((a, b) => a.route.localeCompare(b.route));
-  const components = {
-    ...exampleComponentSerializers(project.examples ?? {}),
-    ...config.ai.markdownComponents
-  };
+  const components = projectComponentSerializers(project);
   const sections = await Promise.all(pages.map(async (page) => {
     let raw = await readExpandedEntryText(project, page);
     if (page.sourcePath) {
@@ -17449,10 +17602,7 @@ var agentMarkdown = (entry) => entry.md ?? entry.mdx;
 var markdownTokenCount = (text) => Math.ceil(text.length / 4);
 var buildRawMarkdown = async (project) => {
   const pageById = new Map(project.graph.pages.map((page) => [page.id, page]));
-  const components = {
-    ...exampleComponentSerializers(project.examples ?? {}),
-    ...project.config.ai.markdownComponents
-  };
+  const components = projectComponentSerializers(project);
   const readRoute = async (route) => {
     const page = pageById.get(route.id);
     if (page) {
@@ -18594,10 +18744,7 @@ var buildSearchDocuments = async (project, options) => {
     const page = pageById.get(route.id);
     return page ? contentIndexable(page, project.config) : false;
   });
-  const components = {
-    ...exampleComponentSerializers(project.examples ?? {}),
-    ...project.config.ai.markdownComponents
-  };
+  const components = projectComponentSerializers(project);
   return await Promise.all(indexable.map(async (route) => {
     const page = pageById.get(route.id);
     const body = await pageBody(project, page, options, components);
@@ -20288,9 +20435,9 @@ var resolveSearchPopular = (popular, basePath) => popular.map(({ href, icon, lab
 
 // src/theme/code-block-padding.ts
 var CODE_PADDING_BLOCK_REM = 1;
-var FLUSH_CODE_PADDING_TOP_REM = 2.5;
 
 // src/theme/entry.ts
+var CODE_SCROLL_INSET_REM = 0.375;
 var DARK_VARIANT = `/* Dark mode is driven by data-theme on the <html> element. */
 @custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));`;
 var COLOR_SCHEME_DEFAULTS = `:root {
@@ -20748,8 +20895,9 @@ blume-diff {
   max-height: 24rem;
   overflow: auto;
   /* The small bottom inset keeps the horizontal thumb off the last line's
-     descenders now that scrollbars are visible. */
-  padding: 0 1.25rem 0.375rem;
+     descenders now that scrollbars are visible. The pre gives up the same
+     amount below (next rule), so the inset adds no height to the block. */
+  padding: 0 1.25rem ${CODE_SCROLL_INSET_REM}rem;
   /* Thin theme-colored scrollbars, matching the sidebar treatment, so a
      height-capped block reads as scrollable instead of simply ending.
      Safari before 18.2 supports neither property and falls back to the
@@ -20758,6 +20906,14 @@ blume-diff {
   scrollbar-width: thin;
 }
 
+/* The scroller's bottom inset comes out of the pre's own block padding: the
+   text still sits one full inset above the frame's bottom edge, the thumb sits
+   in the gap, and a one-line command is no taller than it was before the
+   scroller existed. */
+.prose :where(pre:not(.twoslash, .twoslash pre, blume-panel-tabs *):has(> code)) {
+  padding-bottom: calc(${CODE_PADDING_BLOCK_REM}rem - ${CODE_SCROLL_INSET_REM}rem);
+}
+
 /* The dark border token is too close to the page background to read as a
    scrollbar thumb; derive a brighter one from the muted foreground instead. */
 :root[data-theme="dark"]
@@ -20864,27 +21020,19 @@ blume-tabs pre[data-language],
   padding-top: ${CODE_PADDING_BLOCK_REM}rem;
 }
 
-/* Room for the copy button. The docs layout injects it into every \`.prose pre\`
-   — absolutely positioned against the pre's border box, 1.875rem tall, at
-   \`top-2.5\` in the flush contexts above and \`top-2\` elsewhere — and it is
-   unconditional, so wherever no language bar exists to hold it, it painted
-   over the first line of code: any line long enough to reach the button's
-   strip (a curl invocation, an install command, an import path) went under
-   it. Keyed on the attribute the docs layout stamps on <body>, so the strip
-   only appears where the injector runs (PageLayout pages run none), and on
-   \`.astro-code\` so the playground's response pre — created after the
-   injector ran, never given a button — keeps its plain inset. The first
-   selector is the injector's own flush predicate; the second covers the
-   remaining bar-less Shiki case, an untitled <CodeBlock> in plain prose, from
-   first paint. The third covers a raw \`<pre><code>\` written in prose — no
-   \`.astro-code\`, no language bar, but the injector gives it a button all
-   the same — keyed on that injected button, which is exactly what separates
-   it from the playground's pre. API panel blocks match, but their own
-   !important padding wins and they hide the injected button. */
-[data-blume-code-copy] :is(blume-tabs, .not-prose) pre.astro-code,
-[data-blume-code-copy] .prose pre.astro-code:not([data-language]),
-[data-blume-code-copy] .prose pre:not([data-language]):has(> [data-blume-copy]) {
-  padding-top: ${FLUSH_CODE_PADDING_TOP_REM}rem;
+/* Where no language bar holds the copy button — a flush block in tabs or a
+   not-prose component, a bar-less block in prose — the docs layout still pins
+   one over the block's top-right corner, so a first line long enough to reach
+   it would end underneath. A code switcher (CodeGroup, ts2js) hosts the button
+   in its tab strip instead and needs nothing here; for every block that keeps
+   an overlay button, give the scrolling code element enough end padding that
+   the line's tail clears the button at the end of its scroll. Keyed on the
+   injected button itself (which the playground's client-created response pre
+   never gets), and \`.prose\`-scoped to outrank the base \`:where(pre code)\`
+   inset. Not a vertical inset — that reserved a strip above every one-line
+   command and read as a rendering bug. */
+.prose :is(blume-tabs pre, .not-prose pre, pre:not([data-language])):not(.twoslash, .twoslash pre, blume-panel-tabs *):has(> [data-blume-copy]) > code {
+  padding-inline-end: 3.5rem;
 }
 
 blume-tabs pre[data-language]::before,
@@ -26160,6 +26308,57 @@ Write the titles in this style: ${target.style}`}
 
 ${JSON.stringify(titles, null, 2)}`;
 
+// src/translate/anchors.ts
+var ATX_CLOSE = /\s+#+$/u;
+var structureOf = (headings) => headings.map((heading) => heading.depth).join(",");
+var pinLine = (line, id2) => {
+  const eol = line.endsWith("\r") ? "\r" : "";
+  const body = line.slice(0, line.length - eol.length).trimEnd();
+  const close = body.match(ATX_CLOSE)?.[0] ?? "";
+  const head = body.slice(0, body.length - close.length);
+  return `${head} [#${id2}]${close}${eol}`;
+};
+var pinHeadingAnchors = (sourceText, translatedText) => {
+  const source = scanBody(sourceText);
+  const translated = scanBody(translatedText);
+  if (structureOf(source.headings) !== structureOf(translated.headings)) {
+    return {
+      pinned: 0,
+      skipped: `heading structure differs (source has ${source.headings.length} headings, translation has ${translated.headings.length})`,
+      text: translatedText
+    };
+  }
+  const lines = translatedText.split(`
+`);
+  let pinned = 0;
+  for (const [index, heading] of translated.headings.entries()) {
+    const site = translated.sites[index];
+    const sourceId = source.headings[index]?.slug;
+    if (!site || site.pinned || sourceId === undefined || heading.slug === sourceId) {
+      continue;
+    }
+    lines[site.line - 1] = pinLine(lines[site.line - 1] ?? "", sourceId);
+    pinned += 1;
+  }
+  if (pinned === 0) {
+    return { pinned, text: translatedText };
+  }
+  const text2 = lines.join(`
+`);
+  const rendered = scanBody(text2).headings.map((heading) => heading.slug);
+  const expected = source.headings.map((heading) => heading.slug);
+  if (rendered.join(`
+`) !== expected.join(`
+`)) {
+    return {
+      pinned: 0,
+      skipped: "pinned anchors did not reproduce the source heading ids",
+      text: translatedText
+    };
+  }
+  return { pinned, text: text2 };
+};
+
 // src/translate/validate.ts
 var FRONTMATTER_OPEN = /^---\r?\n/u;
 var FENCE_LINE = /^\s*(?:```|~~~)/u;
@@ -26211,18 +26410,19 @@ var validateTranslation = (sourceText, agentText) => {
   } catch {
     return { ok: false, reason: "frontmatter does not parse as YAML" };
   }
-  const body = ensureTrailingNewline(parsed.content.replace(/^\r?\n/u, ""));
-  if (body.trim() === "") {
+  const rawBody = ensureTrailingNewline(parsed.content.replace(/^\r?\n/u, ""));
+  if (rawBody.trim() === "") {
     return { ok: false, reason: "translation has an empty body" };
   }
   const sourceFences = countFenceLines(source.content);
-  const candidateFences = countFenceLines(body);
+  const candidateFences = countFenceLines(rawBody);
   if (sourceFences !== candidateFences) {
     return {
       ok: false,
       reason: `code fence count changed (source has ${sourceFences}, translation has ${candidateFences})`
     };
   }
+  const body = pinHeadingAnchors(source.content, rawBody).text;
   if (!sourceHasFrontmatter) {
     return { ok: true, text: body };
   }
@@ -26793,10 +26993,38 @@ import { join as join50 } from "pathe";
 // src/core/links.ts
 import { existsSync as existsSync27 } from "node:fs";
 import { basename as basename8, dirname as dirname20, join as join49, relative as relative25, resolve as resolve16 } from "pathe";
+
+// src/core/locale-links.ts
+var decodePercent = (value) => {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+};
+var hasLocalePrefix = (path, i18n) => i18n.locales.some((locale) => {
+  const prefix = localePrefix(locale.code, i18n);
+  return prefix !== "" && (path === prefix || path.startsWith(`${prefix}/`));
+});
+var localizeLinkPath = (path, options) => {
+  const { basePath, i18n, locale, routes } = options;
+  if (localePrefix(locale, i18n) === "") {
+    return path;
+  }
+  const rest = normalizePath(stripBasePath(basePath, path));
+  if (hasLocalePrefix(rest, i18n)) {
+    return path;
+  }
+  const localized = withBasePath(basePath, localizeRoute(rest, locale, i18n));
+  return routes.has(localized) || routes.has(decodePercent(localized)) ? localized : path;
+};
+var routeSets = new WeakMap;
+
+// src/core/links.ts
 var HTTP = /^https?:\/\//iu;
 var PROTOCOL_RELATIVE = /^\/\//u;
 var SCHEME = /^[a-z][a-z0-9+.-]*:/iu;
-var decodePercent = (value) => {
+var decodePercent2 = (value) => {
   try {
     return decodeURIComponent(value);
   } catch {
@@ -26865,8 +27093,17 @@ var checkAnchor = (route, fragment, site, ctx, via = "") => {
     severity: "warning"
   };
 };
+var servedRoute = (authored, page2, ctx) => ctx.i18n ? localizeLinkPath(authored, {
+  basePath: ctx.basePath,
+  i18n: ctx.i18n,
+  locale: page2.locale,
+  routes: {
+    has: (route) => ctx.routes.has(route) || ctx.extraRoutes.has(route)
+  }
+}) : authored;
 var checkPathLink = (resolved, fragment, page2, link, site, ctx, via = "") => {
-  const route = toRoute(withBasePath(ctx.basePath, resolved));
+  const authoredRoute = toRoute(withBasePath(ctx.basePath, resolved));
+  const route = servedRoute(authoredRoute, page2, ctx);
   if (ctx.routes.has(route)) {
     return fragment ? checkAnchor(route, fragment, site, ctx, via) : null;
   }
@@ -26950,13 +27187,13 @@ var classifyLink = (page2, link, ctx, onExternal) => {
     return null;
   }
   const hashIndex = target.indexOf("#");
-  const fragment = decodePercent(hashIndex === -1 ? "" : target.slice(hashIndex + 1));
+  const fragment = decodePercent2(hashIndex === -1 ? "" : target.slice(hashIndex + 1));
   let rawPath = hashIndex === -1 ? target : target.slice(0, hashIndex);
   const queryIndex = rawPath.indexOf("?");
   if (queryIndex !== -1) {
     rawPath = rawPath.slice(0, queryIndex);
   }
-  rawPath = decodePercent(rawPath);
+  rawPath = decodePercent2(rawPath);
   const via = rawPath.startsWith("/") ? "" : includedBySuffix(link, page2);
   if (rawPath === "") {
     return fragment ? checkAnchor(page2.route, fragment, site, ctx, via) : null;
@@ -26970,6 +27207,7 @@ var validateLinks = async (graph, options) => {
     anchors: buildAnchorIndex(graph.pages),
     basePath,
     extraRoutes: new Set((options.extraRoutes ?? []).map(toRoute)),
+    i18n: options.i18n ?? null,
     publicDir: options.publicDir,
     redirects: new Set((options.redirects ?? []).map((redirect) => toRoute(withBasePath(basePath, redirect.from)))),
     routes: new Set(graph.routes.keys())
@@ -27059,6 +27297,7 @@ var validateCommand = defineCommand14({
         basePath: project.config.basePath,
         checkExternal: Boolean(args.external),
         extraRoutes,
+        i18n: project.config.i18n,
         publicDir: existsSync28(publicDir) ? publicDir : null,
         redirects: project.config.redirects
       }));
@@ -27377,5 +27616,5 @@ process.on("unhandledRejection", (error) => {
 });
 runMain(main, { rawArgs: normalizeHostArgs(process.argv.slice(2)) });
 
-//# debugId=9AB8E5F1D71CCEF764756E2164756E21
+//# debugId=4199DBFD57FB41A964756E2164756E21
 //# sourceMappingURL=index.js.map