blume 1.7.2 → 2.0.0

package/src/components/layout/NavTree.astro

@@ -8,6 +8,7 @@ import { withBase } from "../islands/base-path.ts";
 import Self from "./NavTree.astro";
 import NavTreeCache from "./NavTreeCache.astro";
 import NavTreeScript from "./NavTreeScript.astro";
+import { isGroupRowCurrent } from "./nav-utils.ts";
 
 interface PagePanel {
   id: string;
@@ -180,7 +181,11 @@ const initialId =
                   <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
                 </button>
                 <a
-                  aria-current={panel.route === currentRoute ? "page" : undefined}
+                  aria-current={
+                    isGroupRowCurrent(panel.node, currentRoute)
+                      ? "page"
+                      : undefined
+                  }
                   class="flex-1 truncate rounded-[0.65rem] px-1 py-1 font-semibold text-foreground text-sm transition-colors hover:bg-muted"
                   href={withBase(panel.route)}
                 >
@@ -329,7 +334,9 @@ const initialId =
                   {item.route ? (
                     <a
                       aria-current={
-                        item.route === currentRoute ? "page" : undefined
+                        isGroupRowCurrent(item, currentRoute)
+                          ? "page"
+                          : undefined
                       }
                       class="blume-nav-summary-link"
                       href={withBase(item.route)}
@@ -412,7 +419,9 @@ const initialId =
             <p class="blume-nav-heading">
               {item.route ? (
                 <a
-                  aria-current={item.route === currentRoute ? "page" : undefined}
+                  aria-current={
+                    isGroupRowCurrent(item, currentRoute) ? "page" : undefined
+                  }
                   class="blume-nav-heading-link"
                   href={withBase(item.route)}
                 >

package/src/components/layout/NavTreeScript.astro

@@ -77,7 +77,12 @@
         }
         const slot = deferredIn(details.querySelector(":scope > [data-nav-src]"));
         if (slot) {
-          void fillDeferred(slot);
+          // A fragment that can't load (offline, a deploy that dropped it)
+          // closes the group again instead of leaving it open and empty; the
+          // slot keeps its `data-nav-src`, so the next open retries.
+          fillDeferred(slot).catch(() => {
+            details.open = false;
+          });
         }
       },
       true
@@ -159,8 +164,17 @@
       if (!next) {
         return;
       }
-      // A deferred panel loads its contents before it slides in.
-      await fillDeferred(next);
+      // A deferred panel loads its contents before it slides in. When its
+      // fragment can't load (offline, a deploy that dropped it), the drill-in
+      // follows the section's own page link — the panel's title — instead of
+      // leaving the click dead. A section with no page stays put, and the next
+      // drill-in retries the fetch.
+      try {
+        await fillDeferred(next);
+      } catch {
+        next.querySelector<HTMLAnchorElement>("a[href]")?.click();
+        return;
+      }
       const prev = this.active;
       if (prev === next) {
         return;

package/src/components/layout/PageActions.astro

@@ -1,6 +1,7 @@
 ---
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { NEW_TAB_ATTRS } from "../../core/new-tab.ts";
 import { openInChatProviders } from "../../core/open-in-chat.ts";
 import type { OpenInChatProvider } from "../../core/open-in-chat.ts";
 import { GITHUB_MARK } from "../github-mark.ts";
@@ -112,7 +113,7 @@ const menuRowClass =
 >
   {
     editUrl && (
-      <a class={rowClass} href={editUrl} rel="noreferrer" target="_blank">
+      <a class={rowClass} href={editUrl} {...NEW_TAB_ATTRS}>
         <span set:html={GITHUB_LOGO} />
         {a.edit}
       </a>
@@ -192,8 +193,7 @@ const menuRowClass =
               <a
                 class={menuRowClass}
                 data-open-in={provider.key}
-                rel="noreferrer"
-                target="_blank"
+                {...NEW_TAB_ATTRS}
               >
                 <span set:html={LOGOS[provider.key]} />
                 <span class="flex-1">{provider.label}</span>

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,9 +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; llmsTxt: boolean } | null;
+  discovery?: DiscoveryHeadLinks | null;
   siteUrl?: string | null;
   pageType?: string;
   published?: string | Date | null;
@@ -166,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. */
@@ -248,7 +254,7 @@ const {
   exportEpub,
   openInChat,
   feeds,
-  discovery,
+  discovery = data.config.discovery,
   siteUrl,
   pageType,
   published,
@@ -258,6 +264,7 @@ const {
   locale: localeProp,
   dir: dirProp,
   contentDir,
+  contentLocale,
   ui,
   localeAlternates,
   xDefault,
@@ -345,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
@@ -530,29 +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" />
-      )
-    }
-    {
-      markdownMirror && (
-        <link href={markdownMirror} rel="alternate" type="text/markdown" />
-      )
-    }
+    <DiscoveryLinks discovery={discovery} markdownMirror={markdownMirror} />
     {
       structuredDataJson && (
         <script
@@ -583,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}
@@ -609,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
@@ -634,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 && (
@@ -745,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>
         {
@@ -814,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";
@@ -915,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
@@ -1033,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>(
@@ -1048,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);
           }
         }
       };