blume 1.7.2 → 2.0.0

package/src/components/islands/hooks.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import type { BlumeClientData } from "../../core/data.ts";
+import { track } from "../layout/analytics-client.ts";
 import type { SearchFn, SearchResult } from "../layout/search/types.ts";
 import { joinBase, stripBase } from "./base-path.ts";
 
@@ -160,6 +161,28 @@ export interface UseAskAIOptions {
 /** Shown as the assistant's answer when the request fails or throws. */
 const ASK_ERROR = "Something went wrong answering that. Please try again.";
 
+/** How the generated Ask AI route opens its missing-credential notice. */
+const NOT_CONFIGURED = /^Ask AI is not configured/u;
+
+/**
+ * The route's own explanation of a 503 — the generated route's "Ask AI is not
+ * configured: set AI_GATEWAY_API_KEY." — when the response is that notice, or
+ * null. It names only the variable to set, never a value, so it's safe to
+ * show, and it tells a site owner trying a fresh deploy what's missing instead
+ * of the generic failure; any other error body (an HTML error page, a proxy's
+ * message) still gets the generic notice.
+ */
+const unavailableNotice = async (
+  response: Response
+): Promise<string | null> => {
+  if (response.status !== 503) {
+    return null;
+  }
+  const body = await response.text();
+  const text = body.trim();
+  return NOT_CONFIGURED.test(text) && text.length <= 200 ? text : null;
+};
+
 /** The current route with the deployment base stripped, for page grounding. */
 const currentPath = (): string =>
   stripBase(import.meta.env.BASE_URL, window.location.pathname);
@@ -196,6 +219,42 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
       const controller = new AbortController();
       abortRef.current = controller;
       const live = () => current === generation.current;
+      const path = currentPath();
+      // Usage reaches the configured analytics providers the same way page
+      // feedback does: the question now, its outcome once the stream settles.
+      // A reset mid-answer revokes the outcome along with the UI update.
+      // Analytics keys on the raw pathname, like page feedback and the
+      // providers' own pageviews, so the events join under a `base`; the
+      // endpoint gets the base-stripped route for grounding. Providers receive
+      // the question's length only: its text is free-form reader input (pasted
+      // keys, error logs) that would breach their PII terms and their
+      // per-value size caps, so it rides the `blume:track` event alone for a
+      // site to bridge on its own terms.
+      const { pathname } = window.location;
+      const report = (
+        event: "ask" | "ask_answer" | "ask_error",
+        props: Record<string, number>
+      ) =>
+        track(
+          event,
+          { ...props, path: pathname, questionChars: trimmed.length },
+          { question: trimmed }
+        );
+      report("ask", {});
+      // A monotonic clock: the wall clock can jump mid-stream (NTP, sleep).
+      const startedAt = performance.now();
+      const outcome = (
+        event: "ask_answer" | "ask_error",
+        props: Record<string, number>
+      ) =>
+        report(event, {
+          ...props,
+          ms: Math.round(performance.now() - startedAt),
+        });
+      // The HTTP status once a response exists. `streamText` defers provider
+      // errors to stream consumption, so a 200 can still break mid-flight;
+      // that reports as a 200 error, not as "no response".
+      let status = 0;
       const history: AskMessage[] = [
         ...messages,
         { content: trimmed, role: "user" },
@@ -207,17 +266,20 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
         const response = await fetch(endpoint, {
           body: JSON.stringify({
             messages: history,
-            page: { path: currentPath() },
+            page: { path },
           }),
           headers: { "content-type": "application/json" },
           method: "POST",
           signal: controller.signal,
         });
+        ({ status } = response);
         if (!response.ok) {
           // An error body (JSON, HTML error page) must not stream in as the
-          // assistant's answer.
+          // assistant's answer — only the route's own not-configured notice.
+          const notice = await unavailableNotice(response).catch(() => null);
           if (live()) {
-            assistant.content = errorMessage;
+            outcome("ask_error", { status });
+            assistant.content = notice ?? errorMessage;
             setMessages([...history, { ...assistant }]);
           }
           return;
@@ -243,11 +305,21 @@ export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
             }
           }
         }
+        if (live()) {
+          // A 200 with nothing in it (no body, an empty stream) leaves the
+          // reader a blank bubble — that is not an answer.
+          if (assistant.content) {
+            outcome("ask_answer", { chars: assistant.content.length });
+          } else {
+            outcome("ask_error", { status });
+          }
+        }
       } catch {
         // A thrown fetch (offline, DNS failure, CORS) must not strand the
         // pre-appended empty assistant message as a stuck placeholder. A
         // reset's abort lands here too — the guard keeps it silent.
         if (live()) {
+          outcome("ask_error", { status });
           assistant.content = errorMessage;
           setMessages([...history, { ...assistant }]);
         }

package/src/components/layout/Analytics.astro

@@ -1,90 +1,32 @@
 ---
 import VercelAnalytics from "@vercel/analytics/astro";
 
-// Analytics scripts injected into <head>. PostHog and custom providers use the
-// inline-snippet house style (banner/theme/JSON-LD); Vercel uses its official
-// Astro component; Cloudflare is its beacon script tag. Loads ONLY in production builds so `blume dev` stays clean
-// and local traffic never reaches your analytics.
-interface AnalyticsScript {
-  attributes?: Record<string, string>;
-  content?: string;
-  src?: string;
-  strategy?: "async" | "defer";
-}
-
+import { analyticsHead } from "../../analytics/head.ts";
+import type { BlumeDataConfig } from "../../core/data.ts";
+
+// The analytics adapters' <head> output. Each adapter in `analytics` owns the
+// snippet it emits (src/analytics/*); `analyticsHead` collects them into one
+// list in declared order and this component renders it: the official Vercel
+// component for `vercel()`, one <script> for every other adapter. Loads ONLY
+// in production builds so `blume dev` stays clean and local traffic never
+// reaches your analytics.
 interface Props {
-  analytics?: {
-    cloudflare?: { token: string };
-    posthog?: { host?: string; key: string };
-    scripts?: AnalyticsScript[];
-    vercel?: boolean;
-  } | null;
+  analytics?: BlumeDataConfig["analytics"] | null;
 }
 
 const { analytics } = Astro.props;
-const enabled = import.meta.env.PROD && Boolean(analytics);
-
-// Vercel Web Analytics: rendered via the official @vercel/analytics/astro
-// component, which injects the first-party script Vercel serves at
-// /_vercel/insights once Web Analytics is enabled for the project.
-const vercelEnabled = enabled && analytics?.vercel === true;
-
-// PostHog: the official array.js loader snippet, keyed off config. The host
-// defaults to PostHog Cloud US; EU/self-hosted users override `posthog.host`.
-const POSTHOG_LOADER =
-  '!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagPayload isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug getPageViewId captureTraceFeedback captureTraceMetric".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);';
-const posthog = enabled ? analytics?.posthog : undefined;
-// PostHog's loader only captures a pageview per real page load, but the client
-// router turns link clicks into in-place swaps — capture those too, keyed off
-// `astro:page-load` with a pathname guard so the initial load (which the
-// loader already counted) and same-page hash moves aren't double-counted.
-// Vercel Web Analytics and GA4's enhanced measurement track history changes
-// on their own.
-const POSTHOG_SPA_PAGEVIEWS =
-  'document.addEventListener("astro:page-load",function(){var p=window.__blumePhPath;window.__blumePhPath=location.pathname;if(p!==undefined&&p!==location.pathname){posthog.capture("$pageview");}});';
-const posthogSnippet = posthog
-  ? `${POSTHOG_LOADER}posthog.init(${JSON.stringify(posthog.key)},{api_host:${JSON.stringify(posthog.host ?? "https://us.i.posthog.com")}});${POSTHOG_SPA_PAGEVIEWS}`
-  : null;
-
-// Cloudflare Web Analytics (manual setup): the beacon script keyed by the
-// site token, exactly as the dashboard's snippet renders it. It tracks
-// history changes itself, so client-router navigations need no extra hook.
-const cloudflareBeacon =
-  enabled && analytics?.cloudflare
-    ? JSON.stringify({ token: analytics.cloudflare.token })
-    : null;
-
-// Custom scripts: any other provider. Each is either external (`src`) or inline
-// (`content`). Explicit fields win over spread `attributes`.
-const customScripts = enabled ? (analytics?.scripts ?? []) : [];
-const externalScripts = customScripts
-  .filter((script) => script.src)
-  .map((script) => ({
-    ...script.attributes,
-    ...(script.strategy === "async" ? { async: true } : {}),
-    ...(script.strategy === "defer" ? { defer: true } : {}),
-    src: script.src,
-  }));
-const inlineScripts = customScripts
-  .filter((script) => script.content)
-  .map((script) => ({ attributes: script.attributes ?? {}, content: script.content }));
+const nodes = analyticsHead(import.meta.env.PROD ? (analytics ?? []) : []);
 ---
 
-{vercelEnabled && <VercelAnalytics />}
-{
-  cloudflareBeacon && (
-    <script
-      is:inline
-      defer
-      src="https://static.cloudflareinsights.com/beacon.min.js"
-      data-cf-beacon={cloudflareBeacon}
-    />
-  )
-}
-{posthogSnippet && <script is:inline set:html={posthogSnippet} />}
-{externalScripts.map((attrs) => <script is:inline {...attrs} />)}
 {
-  inlineScripts.map((script) => (
-    <script is:inline set:html={script.content} {...script.attributes} />
-  ))
+  nodes.map((node) => {
+    if (node.type === "vercel") {
+      return <VercelAnalytics {...node.props} />;
+    }
+    return node.content === null ? (
+      <script is:inline {...node.attributes} />
+    ) : (
+      <script is:inline set:html={node.content} {...node.attributes} />
+    );
+  })
 }

package/src/components/layout/Banner.astro

@@ -34,7 +34,9 @@ const b = { ...EN_UI.banner, ...strings };
       data-banner-key={banner.key}
       data-blume-banner
     >
-      <span>{banner.content}</span>
+      {/* The message is authored in one language, whatever the page's
+          direction: `dir="auto"` keeps its punctuation where it was typed. */}
+      <span dir="auto">{banner.content}</span>
       {banner.link && (
         <a
           class="inline-flex items-center gap-1 font-medium underline underline-offset-2"

package/src/components/layout/DiscoveryLinks.astro

@@ -0,0 +1,69 @@
+---
+import type { DiscoveryHeadLinks } from "../../core/data.ts";
+import { withBase } from "../islands/base-path.ts";
+// Emits the agent-discovery <link>s for the document <head>, on every page and
+// 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 (see
+// `ai/link-headers.ts`), so the head carries the same `describedby` resources,
+// the AI Catalog / ARD manifest pair, and — when the page has one — its own
+// raw-Markdown mirror as an `alternate`. This also reaches hosts where Blume
+// can't set response headers. Every shell (RootLayout, PageLayout,
+// ReferenceLayout) renders this one partial, so the "every page's head"
+// promise has a single definition. Both `describedby` and `alternate` are
+// IANA-registered relations.
+interface Props {
+  /**
+   * Which resources exist, from the `blume:data` snapshot; `null` drops every
+   * link this partial renders, the Markdown alternate included (a page opting
+   * out of the agent-facing surface).
+   */
+  discovery?: DiscoveryHeadLinks | null;
+  /**
+   * This page's raw-Markdown mirror (already under the deployment base), or
+   * `null` when the route has none — only content routes and the homepage do
+   * (see `markdownRoutePaths`). Advertised only while `discovery` is set.
+   */
+  markdownMirror?: string | null;
+}
+
+const { discovery, markdownMirror } = Astro.props;
+---
+
+{
+  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"
+      />
+    </>
+  )
+}
+{
+  discovery && markdownMirror && (
+    <link href={markdownMirror} rel="alternate" type="text/markdown" />
+  )
+}

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";
@@ -33,6 +33,11 @@ interface Props {
   navigation: Navigation;
   route: string;
   searchEnabled: boolean;
+  /**
+   * 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 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
@@ -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,6 +90,7 @@ const {
   navigation,
   route,
   searchEnabled,
+  locale,
   // `config.ask` is null whenever Ask AI 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.
@@ -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">
@@ -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"
@@ -290,3 +318,38 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
   </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>