blume 1.7.3 → 2.0.1

package/src/components/layout/Header.astro

@@ -2,7 +2,7 @@
 import Ask from "blume:ask";
 import data from "blume:data";
 import { withBase } from "../islands/base-path.ts";
-import { isExternalUrl } from "../../core/base-path.ts";
+import { NEW_TAB_ATTRS, newTabAttrs } from "../../core/new-tab.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
@@ -34,13 +34,18 @@ interface Props {
   route: string;
   searchEnabled: boolean;
   /**
-   * Whether the search modal offers an "Ask AI" hand-off. Defaults to whether
-   * Ask AI is configured, so no page has to pass it; a layout can still opt a
+   * Active locale of the page, forwarded to the `Logo` slot so the brand link
+   * resolves to the locale's root like the tabs beside it.
+   */
+  locale?: string;
+  /**
+   * Whether the search modal offers a hand-off to the assistant. Defaults to whether
+   * the assistant is configured, so no page has to pass it; a layout can still opt a
    * shell out explicitly.
    */
-  askEnabled?: boolean;
-  /** Localized Ask AI strings for the active locale. */
-  askStrings?: UIStrings["ask"];
+  assistantEnabled?: boolean;
+  /** Localized assistant strings for the active locale. */
+  assistantStrings?: UIStrings["assistant"];
   // The mobile menu button toggles the docs sidebar drawer; custom pages
   // without a sidebar (e.g. a landing page) pass `false` to hide it.
   hasSidebar?: boolean;
@@ -71,6 +76,12 @@ interface Props {
    * the whole header.
    */
   layout?: Record<string, ComponentOverride>;
+  /**
+   * 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 (`PageLayout`'s `transparentHeader`).
+   */
+  transparent?: boolean;
 }
 
 const {
@@ -79,11 +90,12 @@ const {
   navigation,
   route,
   searchEnabled,
-  // `config.ask` is null whenever Ask AI is off, so the header is the one place
+  locale,
+  // `config.assistant` is null whenever the assistant is off, so the header is the one place
   // that has to know — the Ask trigger below and the search modal's hand-off to
   // it both switch on this, and every page gets both for free.
-  askEnabled = Boolean(data.config.ask),
-  askStrings,
+  assistantEnabled = Boolean(data.config.assistant),
+  assistantStrings,
   hasSidebar = true,
   hasDrawer = true,
   searchStrings,
@@ -94,6 +106,7 @@ const {
   searchLocale,
   searchVersion = null,
   layout = {},
+  transparent = false,
 } = Astro.props;
 
 // Merge over the English defaults so a label missing from a translation (or
@@ -143,6 +156,12 @@ const ctaClass = [
 // for the swap (next-themes' disableTransitionOnChange trick), force a
 // synchronous style flush, then restore them on the next tick.
 //
+// Both the theme toggle and the banner dismiss change the page first and only
+// then remember the choice: localStorage throws where storage is blocked
+// (Safari "Block All Cookies", sandboxed iframes), and a throw before the DOM
+// change would leave the toggle dead with transitions switched off for good.
+// There the choice simply isn't remembered.
+//
 // The mobile drawer sits below the sticky header, but the banner above the
 // header has no fixed height (its text wraps), so the drawer's top offset can't
 // be static: on open we measure the header's on-screen bottom edge into
@@ -150,16 +169,31 @@ const ctaClass = [
 // so the offset can't drift while open, and re-measure when a banner dismiss or
 // a resize/rotation moves the header. Crossing into the desktop breakpoint
 // (64rem, Tailwind `lg`) closes the drawer so the scroll lock can't outlive it.
-const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-blume-header]");if(h){document.documentElement.style.setProperty("--blume-drawer-top",h.getBoundingClientRect().bottom+"px");}};document.addEventListener("click",(e)=>{const t=e.target.closest("[data-blume-theme-toggle]");if(t){const d=document.documentElement;const next=d.dataset.theme==="dark"?"light":"dark";const s=document.createElement("style");s.appendChild(document.createTextNode("*,*::before,*::after{transition:none!important}"));document.head.appendChild(s);d.dataset.theme=next;localStorage.setItem("blume-theme",next);window.getComputedStyle(d).opacity;setTimeout(()=>document.head.removeChild(s),1);}const n=e.target.closest("[data-blume-nav-toggle]");if(n){const d=document.documentElement;const open=d.toggleAttribute("data-blume-nav-open");if(open){dr();}}const b=e.target.closest("[data-blume-banner-dismiss]");if(b){const bar=b.closest("[data-blume-banner]");const k=bar&&bar.getAttribute("data-banner-key");if(k){localStorage.setItem("blume-banner:"+k,"1");}document.documentElement.setAttribute("data-blume-banner-hidden","");requestAnimationFrame(dr);}});addEventListener("resize",()=>{const d=document.documentElement;if(!d.hasAttribute("data-blume-nav-open")){return;}if(matchMedia("(min-width:64rem)").matches){d.removeAttribute("data-blume-nav-open");}else{dr();}});})();`;
+// The rest of the drawer's behavior — the toggle's `aria-expanded`, Escape to
+// close, and the inert page behind it — follows the same attribute from the
+// layouts' drawer-inert.ts.
+// Transparent header: flag the bar as scrolled once the page moves off the
+// top so the stylesheet below can swap it back to the frosted look. `sync`
+// re-queries the header each time, so the one listener a real load installs
+// keeps working across client-router swaps (and no-ops on pages without it).
+// The router re-runs this inline script on every swap into a transparent-header
+// page, so it syncs that page each time but installs the listeners only once
+// per real load, behind a window flag.
+const transparentScript = `(()=>{const sync=()=>{const h=document.querySelector("[data-blume-header-transparent]");if(h){h.toggleAttribute("data-blume-header-scrolled",scrollY>8);}};sync();if(window.__blumeTransparentHeader){return;}window.__blumeTransparentHeader=true;addEventListener("scroll",sync,{passive:true});document.addEventListener("astro:after-swap",sync);})();`;
+
+const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-blume-header]");if(h){document.documentElement.style.setProperty("--blume-drawer-top",h.getBoundingClientRect().bottom+"px");}};const save=(k,v)=>{try{localStorage.setItem(k,v);}catch{}};document.addEventListener("click",(e)=>{const t=e.target.closest("[data-blume-theme-toggle]");if(t){const d=document.documentElement;const next=d.dataset.theme==="dark"?"light":"dark";const s=document.createElement("style");s.appendChild(document.createTextNode("*,*::before,*::after{transition:none!important}"));document.head.appendChild(s);d.dataset.theme=next;window.getComputedStyle(d).opacity;setTimeout(()=>document.head.removeChild(s),1);save("blume-theme",next);}const n=e.target.closest("[data-blume-nav-toggle]");if(n){const d=document.documentElement;const open=d.toggleAttribute("data-blume-nav-open");if(open){dr();}}const b=e.target.closest("[data-blume-banner-dismiss]");if(b){document.documentElement.setAttribute("data-blume-banner-hidden","");requestAnimationFrame(dr);const bar=b.closest("[data-blume-banner]");const k=bar&&bar.getAttribute("data-banner-key");if(k){save("blume-banner:"+k,"1");}}});addEventListener("resize",()=>{const d=document.documentElement;if(!d.hasAttribute("data-blume-nav-open")){return;}if(matchMedia("(min-width:64rem)").matches){d.removeAttribute("data-blume-nav-open");}else{dr();}});})();`;
 ---
 
 <header
   class="sticky top-0 z-40 flex h-16 items-center gap-3 bg-background/90 px-4 backdrop-blur md:px-6"
   data-blume-header
+  data-blume-header-transparent={transparent ? "" : undefined}
 >
   {
     showNavToggle && (
       <button
+        aria-controls="blume-nav-drawer"
+        aria-expanded="false"
         aria-label={n.toggleNavigation}
         class={`${iconButton} lg:hidden`}
         data-blume-nav-toggle
@@ -169,7 +203,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
       </button>
     )
   }
-  <LogoSlot logo={logo} site={site} />
+  <LogoSlot locale={locale} logo={logo} site={site} />
   {
     navigation.selectors.length > 0 && (
       <div class="flex items-center gap-1.5">
@@ -216,7 +250,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
   {
     searchEnabled && (
       <SearchSlot
-        askEnabled={askEnabled}
+        assistantEnabled={assistantEnabled}
         locale={searchLocale}
         navigation={navigation}
         popularPages={data.config.search.popular}
@@ -229,27 +263,22 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
     {
       /* Plain links first, then the one filled button: the reader's eye lands
          on the button because nothing beside it competes. */
-      (navigation.actions ?? []).map((action) => {
-        const external = isExternalUrl(action.href);
-        return (
-          <a
-            class={actionClass}
-            href={withBase(action.href)}
-            rel={external ? "noreferrer" : undefined}
-            target={external ? "_blank" : undefined}
-          >
-            {action.label}
-          </a>
-        );
-      })
+      (navigation.actions ?? []).map((action) => (
+        <a
+          class={actionClass}
+          href={withBase(action.href)}
+          {...newTabAttrs(action.href)}
+        >
+          {action.label}
+        </a>
+      ))
     }
     {
       navigation.cta && (
         <a
           class={ctaClass}
           href={withBase(navigation.cta.href)}
-          rel={isExternalUrl(navigation.cta.href) ? "noreferrer" : undefined}
-          target={isExternalUrl(navigation.cta.href) ? "_blank" : undefined}
+          {...newTabAttrs(navigation.cta.href)}
         >
           {navigation.cta.label}
           <Icon name="chevron-right" size={14} />
@@ -262,8 +291,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
           aria-label={n.githubRepository}
           class={iconButton}
           href={navigation.repoUrl}
-          rel="noreferrer"
-          target="_blank"
+          {...NEW_TAB_ATTRS}
         >
           <svg
             aria-hidden="true"
@@ -286,7 +314,42 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
       <span class="inline-flex dark:hidden"><Icon name="sun" size={18} /></span>
       <span class="hidden dark:inline-flex"><Icon name="moon" size={18} /></span>
     </button>
-    {askEnabled && <Ask strings={askStrings} />}
+    {assistantEnabled && <Ask strings={assistantStrings} />}
   </div>
 </header>
 <script is:inline set:html={clickScript} />
+{transparent && <script is:inline set:html={transparentScript} />}
+
+<style is:global>
+  /* Transparent header (PageLayout `transparentHeader`): at the top of the
+     page the bar has no background and its chrome renders in white so it can
+     sit over a dark hero; once scrolled it is the frosted bar again. The color
+     tokens are re-declared on the header so every utility inside follows, and
+     the search dialog gets the page's own values back so it isn't inverted. */
+  :root {
+    --blume-header-background: var(--blume-background);
+    --blume-header-foreground: var(--blume-foreground);
+    --blume-header-muted: var(--blume-muted);
+    --blume-header-muted-foreground: var(--blume-muted-foreground);
+    --blume-header-border: var(--blume-border);
+  }
+  [data-blume-header-transparent] {
+    transition: background-color 200ms;
+  }
+  [data-blume-header-transparent]:not([data-blume-header-scrolled]) {
+    --blume-background: transparent;
+    --blume-foreground: #fff;
+    --blume-muted: rgb(255 255 255 / 0.12);
+    --blume-muted-foreground: rgb(255 255 255 / 0.75);
+    --blume-border: rgb(255 255 255 / 0.25);
+    background-color: transparent;
+    backdrop-filter: none;
+  }
+  [data-blume-header-transparent]:not([data-blume-header-scrolled]) dialog {
+    --blume-background: var(--blume-header-background);
+    --blume-foreground: var(--blume-header-foreground);
+    --blume-muted: var(--blume-header-muted);
+    --blume-muted-foreground: var(--blume-header-muted-foreground);
+    --blume-border: var(--blume-header-border);
+  }
+</style>

package/src/components/layout/LanguageSwitcher.astro

@@ -11,6 +11,9 @@ interface Props {
 
 const { options, label, untranslatedLabel } = Astro.props;
 const current = options.find((option) => option.current);
+// The accessible name carries the visible language name too (WCAG 2.5.3,
+// label in name), so a voice-control user can say "English" to open it.
+const summaryLabel = current ? `${label}: ${current.label}` : label;
 
 const iconButton =
   "inline-flex h-9 cursor-pointer items-center gap-1.5 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground";
@@ -22,7 +25,7 @@ const menuRowClass =
   options.length > 1 && (
     <details class="group relative" data-blume-dropdown>
       <summary
-        aria-label={label}
+        aria-label={summaryLabel}
         class={`${iconButton} list-none [&::-webkit-details-marker]:hidden`}
       >
         <Icon name="globe" size={16} />

package/src/components/layout/Logo.astro

@@ -1,17 +1,26 @@
 ---
+import data from "blume:data";
 import { withBase } from "../islands/base-path.ts";
 // The site brand: the logo mark (inline SVG so a `currentColor` mark follows the
 // theme, or light/dark `<img>` variants) followed by the site title, wrapped in
 // a link to the brand href. Extracted from the header so it can be replaced on
 // its own through the `Logo` layout slot (`defineComponents({ layout: { Logo } })`).
 import type { BlumeLogo } from "../../core/data.ts";
+import { localizeInternalPath } from "../../core/i18n.ts";
 
 interface Props {
   site: { title: string };
   logo?: BlumeLogo | null;
+  /**
+   * Active locale of the page. The brand link follows it the way the header
+   * tabs do (`/` -> `/en` under a prefixed locale), so clicking the logo never
+   * drops a reader out of the language they were reading. Absent, the link is
+   * emitted as configured.
+   */
+  locale?: string;
 }
 
-const { site, logo } = Astro.props;
+const { site, logo, locale } = Astro.props;
 
 // The logo is resolved upstream: an inline `svg` (so a currentColor mark follows
 // the theme) or image URL(s) for an <img>.
@@ -21,7 +30,19 @@ const logoDark = logo?.dark ?? logo?.light;
 const logoLightDimensions = logo?.dimensions?.light;
 const logoDarkDimensions = logo?.dimensions?.dark ?? logo?.dimensions?.light;
 const logoAlt = logo?.alt ?? "";
-const brandHref = logo?.href ?? "/";
+// The configured `logo.href` (default `/`) is authored in the default locale's
+// path space, like a tab path; localize it for the page's locale. The locale's
+// navigation carries it resolved against the routes the build serves (a custom
+// home page exists only at `/`, so it isn't moved to `/fr`). External and
+// protocol-relative hrefs pass through, and `withBase` layers the deployment
+// base on afterwards, so the locale prefix sits inside the base like every
+// other localized route.
+const configuredHref = logo?.href ?? "/";
+const brandHref =
+  locale === undefined
+    ? configuredHref
+    : (data.navigationByLocale[locale]?.brandHref ??
+      localizeInternalPath(configuredHref, locale, data.config.i18n));
 // Wordmark beside the mark: the configured `logo.text`, or the site title when
 // it's omitted. An explicit `""` hides it (an image-only logo whose mark already
 // carries the wordmark).

package/src/components/layout/NavSelector.astro

@@ -33,6 +33,12 @@ const active =
     .toSorted((a, b) => b.path.length - a.path.length)[0] ??
   selector.items[0];
 
+// The active label rides in the trigger on every screen when it's short (a
+// version like "v2" or "Latest"): on a phone a bare chevron doesn't say what
+// it switches. Longer product names still collapse to the icon there.
+const label = active?.label ?? selector.label;
+const labelClass = label.length <= 6 ? undefined : "max-sm:hidden";
+
 const iconButton =
   "inline-flex h-9 cursor-pointer items-center gap-1.5 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground";
 const menuRowClass =
@@ -47,7 +53,7 @@ const menuRowClass =
         class={`${iconButton} list-none [&::-webkit-details-marker]:hidden`}
       >
         {active?.icon && <Icon name={active.icon} size={16} />}
-        <span class="max-sm:hidden">{active?.label ?? selector.label}</span>
+        <span class={labelClass}>{label}</span>
         <Icon
           class="transition-transform group-open:rotate-180"
           name="chevron-down"
@@ -55,7 +61,8 @@ const menuRowClass =
         />
       </summary>
       <div
-        class={`absolute z-50 mt-2 min-w-56 rounded-blume border border-border bg-background p-1 shadow-xl ${align === "end" ? "end-0" : "start-0"}`}
+        class={`absolute z-50 mt-2 min-w-56 max-w-[calc(100vw-1rem)] rounded-blume border border-border bg-background p-1 shadow-xl ${align === "end" ? "end-0" : "start-0"}`}
+        data-blume-dropdown-panel
       >
         {selector.items.map((item) => (
           <a
@@ -89,8 +96,12 @@ const menuRowClass =
 
 <script>
   import { installDropdownDismiss } from "../dropdown-dismiss.ts";
+  import { installDropdownClamp } from "./dropdown-clamp.ts";
 
   // Outside-click / Escape / focus-out dismissal, shared with the language
   // switcher and the page actions.
   installDropdownDismiss();
+  // On a phone the trigger sits mid-header, so an edge-anchored panel can
+  // run off the screen; shift it back inside when it opens.
+  installDropdownClamp();
 </script>

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,18 +68,28 @@ 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";
   fontCssVars?: (string | FontHead)[];
   searchEnabled: boolean;
   /**
-   * Opt this page out of the header's Ask AI trigger. Defaults to whether Ask
-   * AI is configured, so a custom page gets the same trigger the docs pages have
+   * Opt this page out of the header's assistant trigger. Defaults to whether the
+   * assistant is configured, so a custom page gets the same trigger the docs pages have
    * without wiring anything up.
    */
-  askEnabled?: boolean;
+  assistantEnabled?: 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`.
@@ -142,7 +163,8 @@ const {
   themeMode,
   fontCssVars,
   searchEnabled,
-  askEnabled,
+  assistantEnabled,
+  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}
+      assistantEnabled={assistantEnabled}
+      assistantStrings={strings.assistant}
       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">