blume 1.7.2 → 2.0.0

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";

package/src/components/layout/analytics-client.ts

@@ -1,25 +1,108 @@
 /**
  * Send a custom analytics event to every analytics platform configured in
- * `blume.config.ts`. Mirrors the providers wired by `Analytics.astro`: Vercel
- * Web Analytics and PostHog are first-class (Cloudflare Web Analytics is too,
- * but has no custom-event API to forward to); any other provider added through
- * `analytics.scripts` is reached via best-effort global detection or the
- * `blume:track` CustomEvent, which fires unconditionally so a project can bridge
- * the event to anything. Every call no-ops cleanly when a provider isn't present
- * — for example during `blume dev`, where `Analytics.astro` injects nothing.
+ * `blume.config.ts`. Mirrors the adapters `Analytics.astro` wires
+ * (`src/analytics/*`): each one with a custom-event API is called through the
+ * global its snippet defines (Cloudflare and Clearbit have none to forward
+ * to), and the `blume:track` CustomEvent fires unconditionally so a project
+ * can bridge the event to anything else — a `script()` adapter, say. Every
+ * call no-ops cleanly when a provider isn't present — for example during
+ * `blume dev`, where `Analytics.astro` injects nothing — and a provider that
+ * throws (a consent shim that stubs `gtag` with a raise, a broken snippet) is
+ * isolated so it neither starves the providers after it nor surfaces in the
+ * feature that reported the event.
  */
 import { track as vercelTrack } from "@vercel/analytics";
 
 /** Flat, serializable event properties. */
 export type TrackProps = Record<string, boolean | number | string>;
 
+/** A Tag Manager data layer: a queue the container drains. */
+interface DataLayer {
+  push: (entry: TrackProps & { event: string }) => number;
+}
+
 interface AnalyticsWindow {
+  /** The data layer a `googleTagManager()` snippet's container reads. */
+  __blumeGtmLayer?: DataLayer;
+  _satellite?: { track?: (event: string, props?: TrackProps) => void };
+  amplitude?: { track?: (event: string, props?: TrackProps) => void };
+  analytics?: { track?: (event: string, props?: TrackProps) => void };
+  clarity?: (command: "event", event: string) => void;
+  dataLayer?: DataLayer;
+  fathom?: { trackEvent?: (event: string) => void };
   gtag?: (command: "event", event: string, props?: TrackProps) => void;
+  heap?: { track?: (event: string, props?: TrackProps) => void };
+  hj?: (command: "event", event: string) => void;
+  htevents?: { track?: (event: string, props?: TrackProps) => void };
+  LogRocket?: { track?: (event: string, props?: TrackProps) => void };
+  mixpanel?: { track?: (event: string, props?: TrackProps) => void };
+  pirsch?: (event: string, options?: { meta?: TrackProps }) => void;
   plausible?: (event: string, options?: { props?: TrackProps }) => void;
   posthog?: { capture?: (event: string, props?: TrackProps) => void };
 }
 
-export const track = (event: string, props: TrackProps): void => {
+/** Run one provider call; its failure must not reach the others or the caller. */
+const attempt = (send: () => void): void => {
+  try {
+    send();
+  } catch {
+    // Analytics never breaks the feature that reported the event.
+  }
+};
+
+// The SDKs whose loader stub queues calls until the library lands, so the
+// method is there to call from the first paint on.
+const trackQueued = (
+  w: AnalyticsWindow,
+  event: string,
+  props: TrackProps
+): void => {
+  attempt(() => w.posthog?.capture?.(event, props));
+  attempt(() => w.mixpanel?.track?.(event, props));
+  attempt(() => w.heap?.track?.(event, props));
+  attempt(() => w.analytics?.track?.(event, props));
+  attempt(() => w.htevents?.track?.(event, props));
+  attempt(() => w.amplitude?.track?.(event, props));
+  attempt(() => w.LogRocket?.track?.(event, props));
+  attempt(() => w._satellite?.track?.(event, props));
+};
+
+// The providers reached through a global function or a data layer rather
+// than a queued SDK object.
+const trackGlobals = (
+  w: AnalyticsWindow,
+  event: string,
+  props: TrackProps
+): void => {
+  // Google: `gtag('event')` for the Google tag, and a plain `{ event }` push
+  // for a Tag Manager custom-event trigger, into the container's own data
+  // layer. Each reads only its own shape, so a site with both configured
+  // still sees the event once per product.
+  attempt(() => w.gtag?.("event", event, props));
+  attempt(() => (w.__blumeGtmLayer ?? w.dataLayer)?.push({ ...props, event }));
+  // Privacy-first counters take a name, some with properties.
+  attempt(() => w.plausible?.(event, { props }));
+  attempt(() => w.fathom?.trackEvent?.(event));
+  // Pirsch stringifies `meta` values in place, so it gets its own copy and
+  // the `blume:track` listeners still see the original types.
+  attempt(() => w.pirsch?.(event, { meta: { ...props } }));
+  // Behavior tools take a bare name.
+  attempt(() => w.clarity?.("event", event));
+  attempt(() => w.hj?.("event", event));
+};
+
+/**
+ * @param event The event name.
+ * @param props Properties every provider receives.
+ * @param local Properties only the `blume:track` CustomEvent carries — free
+ *   text a site may bridge to a provider on its own terms, but that must not
+ *   reach third parties unasked (a reader's Ask AI question, for instance).
+ */
+export const track = (
+  event: string,
+  props: TrackProps,
+  local: TrackProps = {}
+): void => {
   // Read through `globalThis` so an SSR/import-time call sees `undefined`
   // instead of a bare-identifier ReferenceError.
   const browserWindow = globalThis.window;
@@ -31,12 +114,15 @@ export const track = (event: string, props: TrackProps): void => {
   const w = browserWindow as typeof browserWindow & AnalyticsWindow;
 
   // Vercel Web Analytics — self-gates to a no-op until `window.va` is set up.
-  vercelTrack(event, props);
-  // PostHog — the injected array.js stub queues calls until the lib loads.
-  w.posthog?.capture?.(event, props);
-  // Popular providers wired through `analytics.scripts` (GA4/GTM, Plausible).
-  w.gtag?.("event", event, props);
-  w.plausible?.(event, { props });
+  attempt(() => vercelTrack(event, props));
+  trackQueued(w, event, props);
+  trackGlobals(w, event, props);
   // Universal hook for any other integration.
-  w.dispatchEvent(new CustomEvent("blume:track", { detail: { event, props } }));
+  attempt(() =>
+    w.dispatchEvent(
+      new CustomEvent("blume:track", {
+        detail: { event, props: { ...props, ...local } },
+      })
+    )
+  );
 };

package/src/components/layout/drawer-inert.ts

@@ -1,36 +1,134 @@
 /**
- * Keep the mobile nav drawer out of the tab order while it is closed. The
- * closed drawer is only translated off-canvas, so its links would otherwise
- * stay focusable on every page. Mirrors the header's `data-blume-nav-open`
- * toggle into `inert`/`aria-hidden` — but only below `lg` (64rem), where the
- * same element isn't the static sidebar (RootLayout) or is display-hidden
- * anyway (PageLayout). Shared by both layouts' bundled scripts, which run once
- * per real page load; the drawer element is rebuilt by every client-router
- * swap, so `sync` re-queries it each time and re-runs on `astro:after-swap`.
+ * The mobile nav drawer's accessibility. The header's click script opens and
+ * closes the drawer by toggling `data-blume-nav-open` on `<html>`; everything
+ * here follows that attribute, only below `lg` (64rem) — at `lg` and up the same
+ * element is the static sidebar (RootLayout) or display-hidden (PageLayout):
+ *
+ * - Closed, the drawer is only translated off-canvas, so its links would stay
+ *   focusable on every page: it's `inert`/`aria-hidden` instead.
+ * - Open, it's a modal panel over the page: the page behind it (everything but
+ *   the header, which holds the toggle, and the overlay button) goes `inert`,
+ *   so Tab can't wander into content the overlay covers, and the header's
+ *   toggle reports `aria-expanded`.
+ * - Escape closes it, and closing it with focus inside (or on the overlay's
+ *   close button, which disappears) returns focus to the toggle.
+ *
+ * Shared by both layouts' bundled scripts, which run once per real page load;
+ * the drawer and the page behind it are rebuilt by every client-router swap, so
+ * `sync` re-queries them each time and re-runs on `astro:after-swap`.
  */
+
+const OPEN_ATTRIBUTE = "data-blume-nav-open";
+
+/**
+ * Marks what `sync` made inert behind the open drawer, so closing it restores
+ * only those — never an element something else made inert.
+ */
+const BACKDROP_ATTRIBUTE = "data-blume-drawer-backdrop";
+
+/** What stays live beside the open drawer: the header and the overlay. */
+const KEEP_LIVE =
+  "[data-blume-header], [data-blume-nav-toggle], script, style, template";
+
+const drawerElement = (): HTMLElement | null =>
+  document.querySelector<HTMLElement>("[data-blume-nav-drawer]");
+
+const headerToggle = (): HTMLElement | null =>
+  document.querySelector<HTMLElement>(
+    "[data-blume-header] [data-blume-nav-toggle]"
+  );
+
+/**
+ * The page behind the drawer: every sibling along the drawer's path up to
+ * `<body>`, minus what stays live.
+ */
+const backdropOf = (drawer: Element): Element[] => {
+  const backdrop: Element[] = [];
+  let node = drawer;
+  while (node !== document.body && node.parentElement) {
+    for (const sibling of node.parentElement.children) {
+      if (sibling !== node && !sibling.matches(KEEP_LIVE)) {
+        backdrop.push(sibling);
+      }
+    }
+    node = node.parentElement;
+  }
+  return backdrop;
+};
+
+const restoreBackdrop = (): void => {
+  for (const element of document.querySelectorAll(`[${BACKDROP_ATTRIBUTE}]`)) {
+    element.removeAttribute("inert");
+    element.removeAttribute(BACKDROP_ATTRIBUTE);
+  }
+};
+
+const inertBackdrop = (drawer: Element): void => {
+  for (const element of backdropOf(drawer)) {
+    // Already inert for another reason: leave it, and leave it unmarked.
+    if (!element.hasAttribute("inert")) {
+      element.setAttribute("inert", "");
+      element.setAttribute(BACKDROP_ATTRIBUTE, "");
+    }
+  }
+};
+
 export const syncDrawerInert = (): void => {
   const desktop = window.matchMedia("(min-width: 64rem)");
+  const isOpen = () =>
+    !desktop.matches && document.documentElement.hasAttribute(OPEN_ATTRIBUTE);
+  let wasOpen = false;
+
   const sync = () => {
-    const drawer = document.querySelector<HTMLElement>(
-      "[data-blume-nav-drawer]"
-    );
+    const open = isOpen();
+    headerToggle()?.setAttribute("aria-expanded", open ? "true" : "false");
+    const drawer = drawerElement();
     if (!drawer) {
+      restoreBackdrop();
+      wasOpen = open;
       return;
     }
-    const hidden =
-      !desktop.matches &&
-      !Object.hasOwn(document.documentElement.dataset, "blumeNavOpen");
+    const hidden = !(desktop.matches || open);
     drawer.inert = hidden;
     if (hidden) {
       drawer.setAttribute("aria-hidden", "true");
     } else {
       drawer.removeAttribute("aria-hidden");
     }
+    if (open) {
+      inertBackdrop(drawer);
+    } else {
+      restoreBackdrop();
+      const active = document.activeElement;
+      if (
+        wasOpen &&
+        !desktop.matches &&
+        active &&
+        (drawer.contains(active) || active.matches("[data-blume-nav-toggle]"))
+      ) {
+        headerToggle()?.focus();
+      }
+    }
+    wasOpen = open;
   };
+
   sync();
   desktop.addEventListener("change", sync);
   new MutationObserver(sync).observe(document.documentElement, {
-    attributeFilter: ["data-blume-nav-open"],
+    attributeFilter: [OPEN_ATTRIBUTE],
   });
   document.addEventListener("astro:after-swap", sync);
+  document.addEventListener("keydown", (event) => {
+    // An open dialog (search, Ask AI) closes itself on Escape first.
+    if (
+      event.key !== "Escape" ||
+      !isOpen() ||
+      document.querySelector("dialog[open]")
+    ) {
+      return;
+    }
+    document.documentElement.removeAttribute(OPEN_ATTRIBUTE);
+    sync();
+    headerToggle()?.focus();
+  });
 };

package/src/components/layout/dropdown-clamp.ts

@@ -0,0 +1,105 @@
+/**
+ * Keep a header selector's dropdown panel inside the viewport. The panel is
+ * absolutely positioned against its trigger (`end-0` for the version
+ * selector), which is right on desktop, where the trigger sits at the header's
+ * trailing edge — but on a phone the trigger lands mid-header, so a 14rem
+ * panel anchored to its end runs off the leading edge (and, mirrored, off the
+ * trailing edge in a right-to-left locale). When a panel opens, it is measured
+ * and nudged back inside with `translate`, which leaves the anchoring classes
+ * — and the desktop layout — untouched.
+ *
+ * One capture-phase `toggle` listener on `document` (the event doesn't bubble)
+ * serves every opted-in dropdown, installed once per real page load: the
+ * client router rebuilds the header markup on each swap, and delegation needs
+ * no re-binding.
+ */
+
+/** Gap kept between a clamped panel and the viewport edge, in pixels. */
+const MARGIN = 8;
+
+/** The panel an opted-in `<details>` dropdown clamps. */
+export const CLAMPED_PANEL = "[data-blume-dropdown-panel]";
+
+/**
+ * The horizontal shift that brings a panel spanning `left`…`right` inside a
+ * viewport `width` wide, keeping `margin` at each edge. A panel wider than the
+ * room available pins its leading edge (the one reading starts from) to the
+ * margin.
+ */
+export const clampShift = (
+  left: number,
+  right: number,
+  width: number,
+  rtl: boolean,
+  margin = MARGIN
+): number => {
+  const tooWide = right - left > width - 2 * margin;
+  if (tooWide) {
+    return rtl ? width - margin - right : margin - left;
+  }
+  if (left < margin) {
+    return margin - left;
+  }
+  if (right > width - margin) {
+    return width - margin - right;
+  }
+  return 0;
+};
+
+/** The slice of a panel element the clamp measures and moves. */
+export interface PanelBox {
+  getBoundingClientRect: () => { left: number; right: number };
+  style: { translate: string };
+}
+
+/** Measure `panel` in place and shift it back inside the viewport. */
+export const clampPanel = (panel: PanelBox): void => {
+  panel.style.translate = "";
+  const { left, right } = panel.getBoundingClientRect();
+  const root = document.documentElement;
+  const shift = clampShift(
+    left,
+    right,
+    root.clientWidth,
+    root.getAttribute("dir") === "rtl"
+  );
+  if (shift !== 0) {
+    panel.style.translate = `${shift}px 0`;
+  }
+};
+
+/** The clamped panel of the dropdown a `toggle` event opened, if any. */
+const openedPanel = (target: EventTarget | null): HTMLElement | null =>
+  target instanceof HTMLDetailsElement && target.open
+    ? target.querySelector<HTMLElement>(CLAMPED_PANEL)
+    : null;
+
+/** Clamp every open panel again, after the viewport changed size. */
+const reclampOpen = (): void => {
+  for (const panel of document.querySelectorAll<HTMLElement>(
+    `details[open] > ${CLAMPED_PANEL}`
+  )) {
+    clampPanel(panel);
+  }
+};
+
+let installed = false;
+
+/** Clamp opted-in dropdown panels on open (and on resize while open). */
+export const installDropdownClamp = (): void => {
+  if (installed) {
+    return;
+  }
+  installed = true;
+  document.addEventListener(
+    "toggle",
+    (event) => {
+      const panel = openedPanel(event.target);
+      if (panel) {
+        clampPanel(panel);
+      }
+    },
+    true
+  );
+  window.addEventListener("resize", reclampOpen);
+};

package/src/components/layout/head-scripts.ts

@@ -39,9 +39,13 @@
  * the `after-swap` re-apply stays as the fallback that also picks up a
  * preference changed in another tab.
  *
- * Reads `data-mode` — `"system" | "light" | "dark"`.
+ * Reads `data-mode` — `"system" | "light" | "dark"`. Blocked storage (Safari
+ * "Block All Cookies", sandboxed iframes) throws on read. That reads as no
+ * stored preference instead of aborting before the swap listeners exist, and
+ * after a swap the theme the `before-swap` stamp carried over stands, so a
+ * toggle the reader made still holds for the rest of their visit.
  */
-export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const apply=()=>{const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);};apply();document.addEventListener("astro:before-swap",(e)=>{const t=document.documentElement.dataset.theme;if(t){e.newDocument.documentElement.dataset.theme=t;}});document.addEventListener("astro:after-swap",apply);})();`;
+export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const apply=()=>{const r=document.documentElement;let s=null;let blocked=false;try{s=localStorage.getItem("blume-theme");}catch{blocked=true;}const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";r.dataset.theme=s??(blocked&&r.dataset.theme?r.dataset.theme:m==="system"?sys:m);};apply();document.addEventListener("astro:before-swap",(e)=>{const t=document.documentElement.dataset.theme;if(t){e.newDocument.documentElement.dataset.theme=t;}});document.addEventListener("astro:after-swap",apply);})();`;
 
 /**
  * Keep an embedded Scalar reference on Blume's theme. Scalar picks its own
@@ -63,12 +67,17 @@ export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.
 export const SCALAR_THEME_INIT_SCRIPT = `(()=>{const d=document.documentElement;const mode=()=>d.dataset.theme==="dark"?"dark":"light";let pinned=0;for(const el of document.querySelectorAll("[data-scalar-client]")){let c;try{c=JSON.parse(el.dataset.configuration||"{}");}catch{continue;}if("forceDarkModeState" in c||"darkMode" in c){continue;}c.forceDarkModeState=mode();el.dataset.configuration=JSON.stringify(c);pinned+=1;}if(!pinned){return;}new MutationObserver(()=>{const dark=mode()==="dark";document.body.classList.toggle("dark-mode",dark);document.body.classList.toggle("light-mode",!dark);}).observe(d,{attributes:true,attributeFilter:["data-theme"]});})();`;
 
 /**
- * Hide a previously-dismissed banner before it can flash in — and again after
- * every client-router swap, which wipes the `<html>` marker attribute.
+ * Hide a previously-dismissed banner before it can flash in — and keep it
+ * hidden across client-router swaps, which replace the `<html>` attributes with
+ * the incoming page's: `astro:before-swap` carries the marker onto the incoming
+ * root (as the theme script does with `data-theme`), and `after-swap` re-reads
+ * storage as the fallback.
  *
- * Reads `data-key` — the banner's dismissal key.
+ * Reads `data-key` — the banner's dismissal key. A storage read that throws
+ * (blocked storage) reads as not dismissed; a dismissal made on this visit
+ * still holds across its swaps through the carried-over marker.
  */
-export const BANNER_INIT_SCRIPT = `(()=>{const k=document.currentScript?.dataset.key;if(!k){return;}const apply=()=>{if(localStorage.getItem("blume-banner:"+k)){document.documentElement.setAttribute("data-blume-banner-hidden","");}};apply();document.addEventListener("astro:after-swap",apply);})();`;
+export const BANNER_INIT_SCRIPT = `(()=>{const k=document.currentScript?.dataset.key;if(!k){return;}const apply=()=>{let hidden=null;try{hidden=localStorage.getItem("blume-banner:"+k);}catch{}if(hidden){document.documentElement.setAttribute("data-blume-banner-hidden","");}};apply();document.addEventListener("astro:before-swap",(e)=>{if(document.documentElement.hasAttribute("data-blume-banner-hidden")){e.newDocument.documentElement.setAttribute("data-blume-banner-hidden","");}});document.addEventListener("astro:after-swap",apply);})();`;
 
 /**
  * Keep the page styled across client-router swaps. Astro hoists the CSS of a

package/src/components/layout/nav-utils.ts

@@ -14,6 +14,23 @@ export interface Crumb {
   route?: string;
 }
 
+/**
+ * Whether a group's header row reads as the current page. A routed group links
+ * to its folder's index page; when that index is also listed as one of the
+ * group's own rows (kept under a different label), the row is the more
+ * specific indicator, so the header stays quiet rather than lighting up beside
+ * it. With the index row hidden the header is the only link and takes the
+ * highlight.
+ */
+export const isGroupRowCurrent = (
+  group: Extract<NavNode, { kind: "group" }>,
+  currentRoute: string
+): boolean =>
+  group.route === currentRoute &&
+  !group.children.some(
+    (child) => child.kind === "page" && child.route === currentRoute
+  );
+
 /** Flatten the sidebar tree into ordered internal page links. */
 export const flattenPages = (nodes: NavNode[]): FlatPage[] => {
   const out: FlatPage[] = [];

package/src/components/layout/search/algolia.ts

@@ -1,5 +1,6 @@
 import { liteClient } from "algoliasearch/lite";
 
+import type { AlgoliaOptions } from "../../../search/adapters/algolia.ts";
 import { excerptFor, highlight, SEARCH_LIMIT } from "./types.ts";
 import type { SearchFn } from "./types.ts";
 
@@ -13,20 +14,19 @@ interface AlgoliaRecord {
 
 /**
  * Algolia: the browser queries the index directly with the public,
- * search-only key. Records are uploaded at build time by the sync step.
+ * search-only key. Records are uploaded at build time by the sync step. Every
+ * adapter option Blume doesn't read (`hosts`, `timeouts`, `baseHeaders`, …) is
+ * the site's own client option and goes to `liteClient` untouched.
  */
-export const createSearch = (opts: {
-  appId: string;
-  indexName: string;
-  searchApiKey: string;
-}): SearchFn => {
-  const client = liteClient(opts.appId, opts.searchApiKey);
+export const createSearch = (opts: AlgoliaOptions): SearchFn => {
+  const { apiKey, appId, indexName, ...clientOptions } = opts;
+  const client = liteClient(appId, apiKey, clientOptions);
   return async (query, options) => {
     const { results } = await client.search<AlgoliaRecord>({
       requests: [
         {
           hitsPerPage: SEARCH_LIMIT,
-          indexName: opts.indexName,
+          indexName,
           query,
           // The sync uploads `locale` and `version` on every record so a
           // site can scope hosted results to the active language and the

package/src/components/layout/search/orama-cloud.ts

@@ -1,5 +1,6 @@
 import { OramaClient } from "@oramacloud/client";
 
+import type { OramaCloudOptions } from "../../../search/adapters/orama-cloud.ts";
 import { excerptFor, highlight, SEARCH_LIMIT } from "./types.ts";
 import type { SearchFn } from "./types.ts";
 
@@ -12,15 +13,16 @@ interface OramaCloudRecord {
 
 /**
  * Orama Cloud: the browser queries the hosted index directly with the public
- * endpoint + API key. Records are pushed at build time by the sync step.
+ * endpoint + API key. Records are pushed at build time by the sync step. Every
+ * adapter option Blume doesn't read is the site's own client option and goes
+ * to `OramaClient` untouched; `indexId` belongs to the sync and stays out.
  */
-export const createSearch = (opts: {
-  endpoint: string;
-  apiKey: string;
-}): SearchFn => {
+export const createSearch = (opts: OramaCloudOptions): SearchFn => {
+  const { apiKey, endpoint, indexId: _syncOnly, ...clientOptions } = opts;
   const client = new OramaClient({
-    api_key: opts.apiKey,
-    endpoint: opts.endpoint,
+    ...clientOptions,
+    api_key: apiKey,
+    endpoint,
   });
   return async (query, options) => {
     const results = await client.search({

package/src/components/layout/search/typesense.ts

@@ -1,5 +1,6 @@
 import { Client } from "typesense";
 
+import type { TypesenseOptions } from "../../../search/adapters/typesense.ts";
 import { excerptFor, highlight, SEARCH_LIMIT } from "./types.ts";
 import type { SearchFn } from "./types.ts";
 
@@ -13,28 +14,21 @@ interface TypesenseRecord extends Record<string, unknown> {
 
 /**
  * Typesense: the browser queries the collection directly with the search-only
- * key. Documents are imported at build time by the sync step.
+ * key. Documents are imported at build time by the sync step. Every adapter
+ * option Blume doesn't read (`connectionTimeoutSeconds`, `numRetries`, …) is
+ * the site's own client option and goes to the `Client` untouched; the named
+ * connection options still decide `apiKey` and `nodes`.
  */
-export const createSearch = (opts: {
-  collection: string;
-  host: string;
-  port?: number;
-  protocol?: string;
-  searchApiKey: string;
-}): SearchFn => {
+export const createSearch = (opts: TypesenseOptions): SearchFn => {
+  const { apiKey, collection, host, port, protocol, ...clientOptions } = opts;
   const client = new Client({
-    apiKey: opts.searchApiKey,
-    nodes: [
-      {
-        host: opts.host,
-        port: opts.port ?? 443,
-        protocol: opts.protocol ?? "https",
-      },
-    ],
+    ...clientOptions,
+    apiKey,
+    nodes: [{ host, port: port ?? 443, protocol: protocol ?? "https" }],
   });
   return async (query, options) => {
     const response = await client
-      .collections<TypesenseRecord>(opts.collection)
+      .collections<TypesenseRecord>(collection)
       .documents()
       .search(
         {

package/src/components/openapi/MessageComposer.astro

@@ -1,5 +1,5 @@
 ---
-import { randomUUID } from "node:crypto";
+import { stableId } from "../content/tooltip-id.ts";
 
 import type { MessageModel } from "./message.ts";
 
@@ -28,7 +28,7 @@ const modelJson = JSON.stringify(model).replaceAll("<", "\\u003c");
 
 // Unique per rendered composer (a page can hold several), so the textarea's
 // aria-describedby can point at ITS error container and no other.
-const payloadErrorsId = `blume-payload-errors-${randomUUID()}`;
+const payloadErrorsId = stableId(Astro.locals, "blume-payload-errors", [modelJson]);
 
 const LABEL_ROW =
   "mb-1 flex flex-wrap items-baseline gap-x-1.5 font-medium text-foreground text-xs";