blume 1.6.3 → 1.6.4

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # blume
 
+## 1.6.4
+
+### Patch Changes
+
+- 623fe85: Remove the extra vertical space at the bottom of code blocks. The scrolling code element carries a small bottom inset so a horizontal scrollbar thumb stays off the last line's descenders, but that inset was added on top of the block's padding, so every block, including a one-line install command, sat 0.375rem taller than the space above the text. The block now gives up the same amount below the code element, so the text sits an even 1rem from the top and bottom edges and the scrollbar gap is unchanged.
+- 6edd17b: Fix a `ReferenceError: rafThrottle is not defined` thrown on pages that render `<Component>`: the script block used `rafThrottle` without importing it. Preview panes now cap at the viewport with CSS (`max-height: 100lvh`) instead of a resize listener, so a pane capped by a small window grows back when the window does, mobile toolbar collapse no longer resizes it, and the docs page asks already-loaded frames to re-report their height so a report sent before the listener registered isn't lost.
+- ec879ad: Keep content links inside the reader's language on multi-locale sites. Markdown links and `Card`, `Tile`, `Tooltip`, and `Update` hrefs written as `/guides/setup` rendered verbatim on translated pages, so a reader on `/fr/…` was sent back to the default locale on the first click. Root-relative page links now resolve to the same-locale route when one is served — a translation or a fallback page — and keep their authored target otherwise, so custom pages and explicit cross-locale links are untouched. `blume check` resolves links the same way, so an anchor is validated against the translated page a reader actually lands on.
+  
+  Because anchors now travel with the link, `blume translate` pins every translated heading to its source heading's anchor id with a trailing `[#id]` marker (unless the translation already pins one), so `#fragment` links resolve identically in every language.
+- 5efd05e: Fix the language switcher's fallback target under a `basePath`. A switcher entry for a locale with no real translation derives its href by stripping the page's own locale from its route and re-adding the target locale, but `route` arrives with the base path already applied (`/docs/ja/reference`) while locale prefixes are base-less (`/ja`) — so the strip matched nothing and the re-add produced a second prefix, linking `/docs/ja/reference` at `/ja/docs/ja/reference`, `/ko/docs/ja/reference` and so on. None of those routes are built, so every affected entry was a dead link, and an audit that follows them reported the page as linking to broken routes. The route is now moved into base-less space before the locale is swapped and the base is re-applied to the result, using the same helpers the manifest composes real routes with. This affects any locale without a real translation of the page: a partially translated hand-written page for its missing locales, and, most visibly, a generated OpenAPI or GraphQL reference under a base path for every locale but its own.
+- 4de1d37: Downlevel `<Operation>`, `<ApiTagOperations>` and `<ApiOverview>` on the agent-facing surfaces. A generated reference page is its description as Markdown plus one of those components, so with no serializer for them an operation page reached `/<route>.md`, `llms-full.txt`, MCP `get_page` and the Ask AI corpus as its description followed by a bare tag — no method, no path, nowhere to go. On a site whose reference is most of the corpus, that is most of the corpus: measured on one 449-page site, 266 pages and 266 raw `<Operation>` in `llms-full.txt`, so "which endpoint do I call?" had no answer anywhere an agent could read. An operation now downlevels to its endpoint in the spec kind's own notation — `GET /pets/{id}`, `SEND user/signup`, `query pets` or `type Pet` — plus a deprecation marker; a tag section to its operations as links with their summaries; and the overview to the version and base URLs the rendered page shows. Site search indexes the same text, so a query for an endpoint's path now matches its page. Parameters and schemas stay with the component, which owns that rendering. The components and the serializers also share one own-property lookup, so a `source` or `id` that names an inherited property like `toString` renders the not-found state instead of throwing.
+- 830bd4e: Update the oxfmt directive-preservation patch documented in the FAQ for oxfmt 0.67.0. The patch body is unchanged; it now targets the renamed Markdown formatter chunk so `:::` container directives keep their fences on their own lines under the latest oxfmt, oxlint 1.82, and Ultracite 7.11.
+- a919bac: Add `nub` and `aube` tabs to the `package-install` block, alongside npm, pnpm, yarn, and bun. The commands come from the same maintained agent tables as the existing tabs, so `npx …` becomes `nubx …` and `aube dlx …`, `npm ci` becomes a frozen install, and global installs keep their `-g` form. An install block may also be written with a `nub`, `nubx`, or `aube` command as its input.
+- ecbb199: Stop the llms.txt audit reporting the MCP route as a stale entry. `llms.txt` advertises `ai.mcp.route` whenever the MCP server is on, but that endpoint is streamable HTTP — a route the server answers, not a file the build writes — so it appears in neither the page snapshots nor the static file index and the stale-entry check read the site's own index as broken. Every server-output site with `ai.mcp` enabled raised `BLUME_AUDIT_LLMS_TXT_STALE_ENTRY` for a file that was never meant to exist, and under `--fail-on warning` that failed the audit and blocked publishing. The configured route is now exempt while the server is enabled, and only then: with `ai.mcp` off, a listed `/mcp` is as stale as any other dead entry. The other targets llms.txt lists — `llms-full.txt`, `/index.md`, `agent-readability.json`, `sitemap.xml` — are real files and are unaffected.
+  
+  The link, llms.txt, and redirect checks now share one definition of what the build serves, so a page link or a configured redirect that lands on the MCP route is no longer reported as broken either, and an llms.txt entry that points at a directory served from its `index.html` is accepted the way the link check already did.
+- bbb6792: Scope search to the active language on every page of a multi-locale site. The search dialog derived its locale filter from the header's language-switcher entries, which only content pages receive, so custom pages built on `PageLayout`, the changelog index, the 404 page, and the API reference shell searched every language and hid the "All languages" toggle. The filter now reads the resolved i18n settings directly.
+- d7462bf: Update dependencies: Astro 7.3.2 with `@astrojs/mdx` 8.0.1 and `@astrojs/markdown-satteri` 0.4.1, plus the latest patch releases of the remaining runtime dependencies (`@clack/prompts`, `@scalar/astro`, `ai`, `dompurify`, `katex`, `marked`, `node-html-parser`, `simple-icons`, `takumi-js`). Astro's default image service already resolves to Sharp 0.35.4, the release that patches the AVIF remote code execution advisory (GHSA-26w7-cxv4-gfx2).
+
 ## 1.6.3
 
 ### Patch Changes

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);
@@ -20290,6 +20437,7 @@ var resolveSearchPopular = (popular, basePath) => popular.map(({ href, icon, lab
 var CODE_PADDING_BLOCK_REM = 1;
 
 // 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 {
@@ -20747,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
@@ -20757,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"]
@@ -26151,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;
@@ -26202,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 };
   }
@@ -26784,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 {
@@ -26856,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;
   }
@@ -26941,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;
@@ -26961,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())
@@ -27050,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
       }));
@@ -27368,5 +27616,5 @@ process.on("unhandledRejection", (error) => {
 });
 runMain(main, { rawArgs: normalizeHostArgs(process.argv.slice(2)) });
 
-//# debugId=91C1BFDA6463CA2664756E2164756E21
+//# debugId=4199DBFD57FB41A964756E2164756E21
 //# sourceMappingURL=index.js.map