blume 1.7.3 → 2.0.0

package/src/components/layout/PageFeedback.astro

@@ -34,7 +34,12 @@ const buttonClass =
       {f.no}
     </button>
   </div>
-  <p class="hidden text-muted-foreground text-sm" data-feedback-thanks>
+  <p
+    class="hidden text-muted-foreground text-sm focus:outline-none"
+    data-feedback-thanks
+    role="status"
+    tabindex="-1"
+  >
     {f.thanks}
   </p>
 </section>
@@ -61,6 +66,11 @@ const buttonClass =
         });
         actions?.classList.add("hidden");
         thanks?.classList.remove("hidden");
+        // The clicked button just disappeared under focus; hand focus to the
+        // (live) thanks line so the reader isn't dropped at the top of the page.
+        if (thanks instanceof HTMLElement) {
+          thanks.focus();
+        }
       });
     }
   };

package/src/components/layout/PageLayout.astro

@@ -23,10 +23,12 @@ import type {
   BlumeDataConfig,
   BlumeFavicon,
   BlumeLogo,
+  DiscoveryHeadLinks,
 } from "../../core/data.ts";
 import data from "blume:data";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { NEW_TAB_HINT_ID } from "../../core/new-tab.ts";
 import type { FontHead } from "../../theme/fonts.ts";
 import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
 import {
@@ -36,13 +38,14 @@ import {
 } from "../../og/dimensions.ts";
 import { buildStructuredData } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
-import { withBase } from "../islands/base-path.ts";
+import { stripBase, withBase } from "../islands/base-path.ts";
 import { pageDirection, pageLocale } from "./page-locale.ts";
 import { searchLocaleFor } from "./search-locale.ts";
 import "blume:theme";
 import { ClientRouter } from "astro:transitions";
 import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
+import DiscoveryLinks from "./DiscoveryLinks.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import {
@@ -65,7 +68,10 @@ interface Props {
   /**
    * Title/description/route for `<title>`, `og:*`, and the header active link.
    * Unlike RootLayout, `title` is used verbatim (no `- siteTitle` suffix), since
-   * marketing pages usually set their own complete document title.
+   * marketing pages usually set their own complete document title. An omitted
+   * `route` is read from the request URL (base-less), so a page that never
+   * passes one still gets its own canonical, OG card, and Markdown mirror
+   * rather than the homepage's.
    */
   page?: { title?: string; description?: string; route?: string };
   themeMode: "system" | "light" | "dark";
@@ -77,6 +83,13 @@ interface Props {
    * without wiring anything up.
    */
   askEnabled?: boolean;
+  /**
+   * Start the header see-through, with its chrome in white, so it can sit over
+   * a dark hero at the top of the page; it returns to the frosted bar as soon
+   * as the page scrolls. The hero has to run under the header for this to
+   * show: pull it up by the header's height (`-mt-16`) and pad its top.
+   */
+  transparentHeader?: boolean;
   /**
    * Absolute site URL (`data.config.site`). When set, `canonical` and the
    * generated `og:image` for this route are derived from it automatically;
@@ -105,6 +118,14 @@ interface Props {
    * matching RootLayout.
    */
   structuredDataEnabled?: boolean;
+  /**
+   * Which agent-discovery resources exist, advertised as `describedby` head
+   * links plus the AI Catalog/ARD pair — the same `DiscoveryLinks` partial
+   * RootLayout renders. A custom page gets this from the `blume:data` snapshot
+   * without wiring anything up; pass it to override, or `null` to drop the
+   * links.
+   */
+  discovery?: DiscoveryHeadLinks | null;
   /**
    * X (Twitter) attribution (`data.config.x`): the site's account and an author
    * handle, emitted as `twitter:site`/`twitter:creator`.
@@ -143,6 +164,7 @@ const {
   fontCssVars,
   searchEnabled,
   askEnabled,
+  transparentHeader,
   siteUrl,
   ogEnabled,
   ogImage,
@@ -150,6 +172,7 @@ const {
   ogImageSize,
   canonical,
   structuredDataEnabled,
+  discovery = data.config.discovery,
   x,
   noindex,
   locale: localeProp,
@@ -180,14 +203,30 @@ const navStrings = { ...EN_UI.nav, ...strings.nav };
 const searchLocale = searchLocaleFor(data.config.i18n, locale);
 const pageTitle = page?.title ?? site.title;
 const description = page?.description ?? site.description;
-const route = page?.route ?? "/";
+// An omitted `page.route` falls back to the request pathname with the
+// deployment base stripped, not to `/`: a non-root page that copies the
+// homepage example would otherwise claim the homepage's canonical, OG card,
+// and `/index.md` mirror. `trailingSlash: "never"` keeps the pathname bare.
+const route =
+  page?.route ??
+  stripBase(import.meta.env.BASE_URL ?? "/", Astro.url.pathname);
 const activeTab = currentTabForRoute(navigation.tabs, route, navigation.root);
 
+// A custom page has no raw-Markdown mirror — except the homepage: `/index.md`
+// always exists (see `markdownRoutePaths`; a landing page gets the synthesized
+// llms.txt index), and the homepage HTTP `Link` header already advertises it,
+// so the head is its HTML counterpart on hosts that can't set that header.
+// Advertising a mirror for any other custom route would 404.
+const markdownMirror = route === "/" ? withBase("/index.md") : null;
+
 // Derive canonical + og:image from the site URL the same way the catch-all does
 // for content pages, so a custom page gets both for free. The matching OG card
 // (`/og/<slug>.png`, `index` for the home) is generated for static custom pages
-// when `og.enabled`. Explicit props still win.
+// when `og.enabled` — not for a dynamic route (`[param]`), whose concrete URLs
+// can't be enumerated up front, so such a page advertises no generated card
+// rather than one that 404s. Explicit props still win.
 const ogSlug = route === "/" ? "index" : route.slice(1);
+const ogCardGenerated = !Astro.routePattern.includes("[");
 // Absolute URLs carry the deployment base too (`site + base + route`), since the
 // page is served under it. `withBase` handles a root base as a no-op.
 const basedRoute = withBase(route);
@@ -211,7 +250,7 @@ const absolutizeOgImage = (value: string): string =>
   value.startsWith("/") && siteBase ? `${siteBase}${withBase(value)}` : value;
 const resolvedOgImage = ogImage
   ? absolutizeOgImage(ogImage)
-  : ogEnabled && siteBase
+  : ogEnabled && ogCardGenerated && siteBase
     ? `${siteBase}${encodeURI(withBase(`/og/${ogSlug}.png`))}`
     : null;
 // Only the generated card has a known size and format, so its dimensions are
@@ -321,6 +360,9 @@ createIconSprite(Astro.locals);
     {description && <meta content={description} name="twitter:description" />}
     {xSite && <meta content={xSite} name="twitter:site" />}
     {xCreator && <meta content={xCreator} name="twitter:creator" />}
+    {/* Agent discovery on every page, so a custom page built on PageLayout is
+        covered without passing a prop, the same way the docs pages are. */}
+    <DiscoveryLinks discovery={discovery} markdownMirror={markdownMirror} />
     {
       structuredDataJson && (
         <script
@@ -343,11 +385,14 @@ createIconSprite(Astro.locals);
       class="absolute start-[-999px] top-0 z-[100] bg-accent px-4 py-2 text-accent-foreground focus:start-0"
       href="#blume-content">{strings.page.skipToContent}</a
     >
+    {/* Every new-tab link's aria-describedby target (see core/new-tab.ts). */}
+    <span hidden id={NEW_TAB_HINT_ID}>{navStrings.opensInNewTab}</span>
     <Banner banner={banner} strings={strings.banner} />
     <Header
       askEnabled={askEnabled}
       askStrings={strings.ask}
       hasSidebar={false}
+      locale={locale}
       localeSwitch={localeSwitch}
       logo={logo}
       navStrings={navStrings}
@@ -358,6 +403,7 @@ createIconSprite(Astro.locals);
       searchStrings={strings.search}
       site={site}
       switcherStrings={strings.languageSwitcher}
+      transparent={transparentHeader}
     />
     <main id="blume-content"><slot /></main>
     <slot name="footer" />
@@ -374,6 +420,7 @@ createIconSprite(Astro.locals);
             aria-label={navStrings.navigation}
             class="fixed top-[var(--blume-drawer-top,4rem)] start-0 z-[35] h-[calc(100dvh-var(--blume-drawer-top,4rem))] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:hidden"
             data-blume-nav-drawer
+            id="blume-nav-drawer"
           >
             <nav aria-label={navStrings.sections}>
               <ul class="m-0 list-none p-0">

package/src/components/layout/ReferenceLayout.astro

@@ -3,14 +3,20 @@ import IconSprite from "./IconSprite.astro";
 import { createIconSprite } from "../icon-sprite.ts";
 import "blume:theme";
 import data from "blume:data";
-import type { BlumeFavicon } from "../../core/data.ts";
+import type {
+  BlumeDataConfig,
+  BlumeFavicon,
+  DiscoveryHeadLinks,
+} from "../../core/data.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { NEW_TAB_HINT_ID } from "../../core/new-tab.ts";
 import type { FontHead } from "../../theme/fonts.ts";
 import type { Navigation } from "../../core/types.ts";
 import Analytics from "./Analytics.astro";
 import WebMcp from "./WebMcp.astro";
 import Banner from "./Banner.astro";
+import DiscoveryLinks from "./DiscoveryLinks.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import {
@@ -50,17 +56,7 @@ interface Props {
     dismissible: boolean;
     key: string;
   } | null;
-  analytics?: {
-    cloudflare?: { token: string };
-    posthog?: { host?: string; key: string };
-    scripts?: {
-      attributes?: Record<string, string>;
-      content?: string;
-      src?: string;
-      strategy?: "async" | "defer";
-    }[];
-    vercel?: boolean;
-  } | null;
+  analytics?: BlumeDataConfig["analytics"] | null;
   navigation: Navigation;
   route: string;
   themeMode: "system" | "light" | "dark";
@@ -69,6 +65,13 @@ interface Props {
   pageTitle: string;
   /** Keep the reference route out of crawler indexes. */
   noindex?: boolean;
+  /**
+   * Which agent-discovery resources exist, advertised in the head by the same
+   * `DiscoveryLinks` partial the docs shells render; defaults to the
+   * `blume:data` snapshot, `null` drops the links. A reference route has no
+   * raw-Markdown mirror, so no `alternate` is emitted here.
+   */
+  discovery?: DiscoveryHeadLinks | null;
   /**
    * Active locale code for `<html lang>`. Defaults to the locale Astro
    * resolved from the URL (`Astro.currentLocale`), then the site default.
@@ -94,6 +97,7 @@ const {
   searchEnabled,
   pageTitle,
   noindex = false,
+  discovery = data.config.discovery,
   locale: localeProp,
   dir: dirProp,
   ui,
@@ -106,6 +110,7 @@ const locale = pageLocale(data.config.i18n, localeProp, Astro.currentLocale);
 const dir = dirProp ?? pageDirection(data.config.i18n, locale);
 
 const strings = ui ?? EN_UI;
+const navStrings = { ...EN_UI.nav, ...strings.nav };
 // Scope search to the reference page's language on a multi-locale site.
 const searchLocale = searchLocaleFor(data.config.i18n, locale);
 
@@ -125,6 +130,7 @@ createIconSprite(Astro.locals);
     <title>{pageTitle}</title>
     <Favicon favicon={favicon} appleIcon={appleIcon} />
     <Fonts cssVars={fontCssVars ?? []} />
+    <DiscoveryLinks discovery={discovery} />
     {
       bannerKey && (
         <script data-key={bannerKey} is:inline set:html={BANNER_INIT_SCRIPT} />
@@ -138,11 +144,14 @@ createIconSprite(Astro.locals);
       class="absolute start-[-999px] top-0 z-[100] bg-accent px-4 py-2 text-accent-foreground focus:start-0"
       href="#blume-content">{strings.page.skipToContent}</a
     >
+    {/* Every new-tab link's aria-describedby target (see core/new-tab.ts). */}
+    <span hidden id={NEW_TAB_HINT_ID}>{navStrings.opensInNewTab}</span>
     <Banner banner={banner} strings={strings.banner} />
     <Header
       askStrings={strings.ask}
       hasDrawer={false}
       hasSidebar={false}
+      locale={locale}
       logo={logo}
       navigation={navigation}
       route={route}

package/src/components/layout/RootLayout.astro

@@ -7,7 +7,12 @@ import type { UIStrings } from "../../core/i18n-ui.ts";
 import { resolveDateFormatOptions } from "../../core/date-format.ts";
 import type { ResolvedDateFormat } from "../../core/schema.ts";
 import type { OpenInChatProvider } from "../../core/open-in-chat.ts";
-import type { BlumeClientData, BlumeFavicon } from "../../core/data.ts";
+import type {
+  BlumeClientData,
+  BlumeDataConfig,
+  BlumeFavicon,
+  DiscoveryHeadLinks,
+} from "../../core/data.ts";
 import type {
   Heading,
   LocaleSwitchOption,
@@ -36,11 +41,13 @@ import { buildStructuredData, toIso } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
 import { isExternalUrl } from "../../core/base-path.ts";
+import { NEW_TAB_HINT_ID, newTabAttrs } from "../../core/new-tab.ts";
 import Analytics from "./Analytics.astro";
 import WebMcp from "./WebMcp.astro";
 import Banner from "./Banner.astro";
 import Breadcrumbs from "./Breadcrumbs.astro";
 import Empty from "./Empty.astro";
+import DiscoveryLinks from "./DiscoveryLinks.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import {
@@ -87,17 +94,7 @@ interface Props {
     dismissible: boolean;
     key: string;
   } | null;
-  analytics?: {
-    cloudflare?: { token: string };
-    posthog?: { host?: string; key: string };
-    scripts?: {
-      attributes?: Record<string, string>;
-      content?: string;
-      src?: string;
-      strategy?: "async" | "defer";
-    }[];
-    vercel?: boolean;
-  } | null;
+  analytics?: BlumeDataConfig["analytics"] | null;
   navigation: Navigation;
   mcp?: { name: string; route: string } | null;
   page: { title: string; description?: string; route: string };
@@ -144,13 +141,11 @@ interface Props {
    * links on every page — so an agent entering on a deep page (a search
    * result, a shared link) finds the machine-readable surface without probing
    * the site root. The HTML counterpart of the homepage-only HTTP `Link`
-   * header (see `ai/link-headers.ts`).
+   * header (see `ai/link-headers.ts`). Defaults to the `blume:data` snapshot,
+   * so a custom page on this layout gets the links without passing a prop;
+   * `null` drops them for one page.
    */
-  discovery?: {
-    agentReadability: boolean;
-    aiCatalog: boolean;
-    llmsTxt: boolean;
-  } | null;
+  discovery?: DiscoveryHeadLinks | null;
   siteUrl?: string | null;
   pageType?: string;
   published?: string | Date | null;
@@ -170,6 +165,13 @@ interface Props {
    * article so prose punctuation reads correctly; the chrome still mirrors.
    */
   contentDir?: "ltr" | "rtl";
+  /**
+   * Language of the page content itself — the fallback locale on a fallback
+   * page (English content at `/ar/…`). Set as the article's `lang` when it
+   * differs from the page locale, so assistive tech reads the text in its own
+   * language rather than the chrome's.
+   */
+  contentLocale?: string;
   /** Resolved UI dictionary; English baseline when omitted. */
   ui?: UIStrings;
   /** `hreflang` alternates (absolute URLs) for this page's translations. */
@@ -252,7 +254,7 @@ const {
   exportEpub,
   openInChat,
   feeds,
-  discovery,
+  discovery = data.config.discovery,
   siteUrl,
   pageType,
   published,
@@ -262,6 +264,7 @@ const {
   locale: localeProp,
   dir: dirProp,
   contentDir,
+  contentLocale,
   ui,
   localeAlternates,
   xDefault,
@@ -349,7 +352,16 @@ if (isBare) {
 } else if (isApiOperation) {
   articleClass = "prose max-w-none";
 }
-const pageTitle = page.title ? `${page.title} - ${site.title}` : site.title;
+// A page titled like the site (a home page often is) takes the bare site title
+// rather than repeating it ("Acme Docs - Acme Docs").
+const pageTitle =
+  page.title && page.title !== site.title
+    ? `${page.title} - ${site.title}`
+    : site.title;
+// The article's own language, when a fallback page renders another locale's
+// content under this one.
+const articleLang =
+  contentLocale && contentLocale !== locale ? contentLocale : undefined;
 const description = page.description ?? site.description;
 // Blog posts and changelog entries are dated writing, so they take `og:type:
 // article` — the same split JSON-LD makes when it picks an article @type. Docs
@@ -534,48 +546,7 @@ createIconSprite(Astro.locals);
         />
       ))
     }
-    {/* Agent discovery on every page, not just the root: an agent that enters
-        on a deep page (a search result, a shared link) never sees the homepage
-        HTTP Link header, so the head carries the same describedby links plus
-        this page's own raw-Markdown mirror. Both rels are IANA-registered. */}
-    {
-      discovery?.agentReadability && (
-        <link
-          href={withBase("/agent-readability.json")}
-          rel="describedby"
-          type="application/json"
-        />
-      )
-    }
-    {
-      discovery?.llmsTxt && (
-        <link href={withBase("/llms.txt")} rel="describedby" type="text/plain" />
-      )
-    }
-    {/* The AI Catalog / ARD manifest under both relations its two specs
-        define: `ai-catalog` (ai-catalog spec) and `ard` (ARD v0.91), each
-        pointing at that spec's own well-known path. */}
-    {
-      discovery?.aiCatalog && (
-        <>
-          <link
-            href={withBase("/.well-known/ai-catalog.json")}
-            rel="ai-catalog"
-            type="application/ai-catalog+json"
-          />
-          <link
-            href={withBase("/.well-known/ard.json")}
-            rel="ard"
-            type="application/json"
-          />
-        </>
-      )
-    }
-    {
-      markdownMirror && (
-        <link href={markdownMirror} rel="alternate" type="text/markdown" />
-      )
-    }
+    <DiscoveryLinks discovery={discovery} markdownMirror={markdownMirror} />
     {
       structuredDataJson && (
         <script
@@ -606,12 +577,15 @@ createIconSprite(Astro.locals);
       class="absolute start-[-999px] top-0 z-[100] bg-accent px-4 py-2 text-accent-foreground focus:start-0"
       href="#blume-content">{strings.page.skipToContent}</a
     >
+    {/* Every new-tab link's aria-describedby target (see core/new-tab.ts). */}
+    <span hidden id={NEW_TAB_HINT_ID}>{navStrings.opensInNewTab}</span>
     <Banner banner={banner} strings={strings.banner} />
     <VersionBanner notice={versionNotice ?? null} />
     <HeaderSlot
       askEnabled={askEnabled}
       askStrings={strings.ask}
       layout={layout}
+      locale={locale}
       localeSwitch={localeSwitch}
       versionSelector={versionSelector}
       logo={logo}
@@ -632,6 +606,7 @@ createIconSprite(Astro.locals);
       <aside
         aria-label={navStrings.primary}
         data-blume-nav-drawer
+        id="blume-nav-drawer"
         class:list={[
           "fixed top-[var(--blume-drawer-top,4rem)] start-0 z-[35] h-[calc(100dvh-var(--blume-drawer-top,4rem))] w-64 max-w-[80vw] -translate-x-[105%] overflow-y-auto border-border border-e bg-background px-5 pt-4 pb-6 transition-transform rtl:translate-x-[105%] [:where([data-blume-nav-open])_&]:translate-x-0! lg:sticky lg:top-16 lg:z-auto lg:h-[calc(100dvh-4rem)] lg:w-auto lg:max-w-none lg:translate-x-0! lg:scrollbar-thin lg:scrollbar-thumb-border lg:scrollbar-track-transparent lg:border-e-0 lg:bg-transparent lg:px-4",
           // A "bare" landing (the changelog index) has no sidebar column on
@@ -657,8 +632,7 @@ createIconSprite(Astro.locals);
                       <a
                         class="block rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground"
                         href={withBase(link.href)}
-                        rel={external ? "noreferrer" : undefined}
-                        target={external ? "_blank" : undefined}
+                        {...newTabAttrs(link.href)}
                       >
                         <span class="flex items-center gap-2">
                           {link.icon && (
@@ -768,7 +742,18 @@ createIconSprite(Astro.locals);
           )
         }
         <PageHeaderSlot headings={tocHeadings} page={page} route={page.route} />
-        <article class:list={[articleClass]} dir={contentDir}>
+        {/* `data-pagefind-body` scopes Pagefind to the page's own text: without
+            it Pagefind indexes the whole <body>, so the header, sidebar, and
+            skip link lead every excerpt and match every query. Once any page
+            carries it, pages without it (landing pages, the 404, the
+            changelog index — none are content routes, which is what site
+            search indexes) drop out of the index entirely. */}
+        <article
+          class:list={[articleClass]}
+          data-pagefind-body={indexable && !isBare ? "" : undefined}
+          dir={contentDir}
+          lang={articleLang}
+        >
           <slot />
         </article>
         {
@@ -837,6 +822,7 @@ createIconSprite(Astro.locals);
       type="button"
     ></button>
     <script>
+      import type { Zoom } from "medium-zoom";
       import { copyText, createCopyFlash } from "../copy-feedback.ts";
       import { syncDrawerInert } from "./drawer-inert.ts";
       import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
@@ -938,6 +924,13 @@ createIconSprite(Astro.locals);
       // client-router swap (which replaces the body with server-rendered
       // markup that has none of this applied). Everything in here binds to
       // elements the swap just created, so nothing double-attaches.
+      // One medium-zoom instance per real page load, re-pointed at each page's
+      // images: every instance adds document keyup/scroll and window resize
+      // listeners it never removes and holds on to the images it was given, so
+      // a fresh instance per client-router swap stacked listeners and kept
+      // every earlier page's images alive.
+      let zoom: Zoom | undefined;
+
       const initPage = async () => {
         // Localized copy-button labels, stamped on <body> by the layout markup
         // (the Search.astro data-attribute channel) since this bundled script
@@ -1056,6 +1049,15 @@ createIconSprite(Astro.locals);
         // via medium-zoom: ESC/scroll/click dismissal, natural-size capping,
         // and the open/close transition races are its problem, not ours.
         // Opt out per-image with `data-no-zoom`.
+        // The previous page's images are gone after a swap; let go of them
+        // before looking at this page. A swap that lands while an image is
+        // zoomed (Back mid-zoom) leaves the instance mid-animation, its overlay
+        // gone with the old body and its close never finishing, so start over
+        // then instead.
+        if (zoom?.getZoomedImage()) {
+          zoom = undefined;
+        }
+        zoom?.detach();
         if (document.body.hasAttribute("data-blume-image-zoom")) {
           const zoomTargets = Array.from(
             document.querySelectorAll<HTMLImageElement>(
@@ -1071,11 +1073,12 @@ createIconSprite(Astro.locals);
             const { default: mediumZoom } = await import(
               "medium-zoom/dist/pure"
             );
-            mediumZoom(zoomTargets, {
+            zoom ??= mediumZoom({
               background:
                 "color-mix(in oklab, var(--color-background) 80%, transparent)",
               margin: 24,
             });
+            zoom.attach(...zoomTargets);
           }
         }
       };

package/src/components/layout/Search.astro

@@ -84,8 +84,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   >
     <Icon name="search" size={16} />
     <span class="flex-1 text-start max-lg:hidden">{s.button}</span>
-    <kbd class="font-mono text-[0.7rem] max-lg:hidden" data-blume-search-kbd
-      >⌘K</kbd
+    {/* A key chord reads left to right in every locale ("⌘K", never "K⌘"). */}
+    <kbd
+      class="font-mono text-[0.7rem] max-lg:hidden"
+      data-blume-search-kbd
+      dir="ltr">⌘K</kbd
     >
   </button>
 
@@ -195,8 +198,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           {s.open}
         </span>
         <span class="flex items-center gap-1 max-md:hidden">
-          <kbd class={`${kbd} text-[0.65rem]`} data-blume-search-preview-kbd
-            >⌘J</kbd
+          <kbd
+            class={`${kbd} text-[0.65rem]`}
+            data-blume-search-preview-kbd
+            dir="ltr">⌘J</kbd
           >
           {s.preview}
         </span>
@@ -271,6 +276,26 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       }
     };
 
+    // The generated client and the index it fetches are the same on every
+    // page (locale and version filters apply per query), but each client-router
+    // swap rebuilds the header, and this element with it. Loading once in
+    // module scope — bundled modules survive swaps — keeps the first search
+    // after a navigation from refetching the index and rebuilding it. A failed
+    // load clears the cache, so the next open retries.
+    let searchClient: Promise<SearchFn> | undefined;
+    const loadSearchClient = (): Promise<SearchFn> => {
+      searchClient ??= (async () => {
+        try {
+          const { createSearch } = await import("blume:search-client");
+          return await createSearch();
+        } catch (error) {
+          searchClient = undefined;
+          throw error;
+        }
+      })();
+      return searchClient;
+    };
+
     class BlumeSearch extends HTMLElement {
       dialog!: HTMLDialogElement;
       input!: HTMLInputElement;
@@ -481,8 +506,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         if (!this.loaded) {
           this.loading = true;
           try {
-            const { createSearch } = await import("blume:search-client");
-            this.searchFn = await createSearch();
+            this.searchFn = await loadSearchClient();
             // Only latch on success — a transient failure (flaky network
             // fetching the index) must retry on the next open, not disable
             // search until a full page reload.

package/src/components/layout/WebMcp.astro

@@ -2,7 +2,7 @@
 // WebMCP: expose the docs' read-only tools (search, page Markdown, the docs
 // index) to agentic browsers via the page's model context. Rendered by
 // PageLayout on every page; the marker element below both gates the script
-// (absent when `ai.webmcp` is off, so it returns immediately) and carries the
+// (absent when `agents.webmcp` is off, so it returns immediately) and carries the
 // two config flags the client needs — importing `blume:data` from the client
 // script would drag the whole navigation snapshot into the bundle.
 import data from "blume:data";