blume 2.0.2 → 2.1.0

package/src/components/islands/hooks.ts

@@ -1,9 +1,12 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
+import { captchaToken } from "../../captcha/client.ts";
+import type { CaptchaSettings } from "../../captcha/schema.ts";
 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";
+import { newThreadId } from "./support-link.ts";
 
 /**
  * React hooks for Blume islands.
@@ -23,27 +26,29 @@ import { joinBase, stripBase } from "./base-path.ts";
 
 export type { BlumeClientData } from "../../core/data.ts";
 
-let cachedData: BlumeClientData | null = null;
+/**
+ * The last parsed snapshot, keyed by the script text it came from. Each page
+ * renders its own snapshot (its route and title, its locale's navigation), and
+ * a client-router navigation swaps in the new page's tag, so the cache is only
+ * reused while the tag's text is unchanged.
+ */
+let cached: { data: BlumeClientData; text: string } | null = null;
 
-/** Read + parse the injected snapshot (memoized); null on the server. */
+/** Read + parse the current page's injected snapshot (memoized per text). */
 const readClientData = (): BlumeClientData | null => {
-  if (cachedData) {
-    return cachedData;
-  }
-  // `document` is undeclared on the server; probing `globalThis` avoids both
-  // the bare-reference ReferenceError and a `typeof` sniff.
-  if (!("document" in globalThis)) {
+  const text = document.querySelector("#blume-client-data")?.textContent;
+  if (!text) {
     return null;
   }
-  const element = document.querySelector("#blume-client-data");
-  if (!element?.textContent) {
-    return null;
+  if (cached?.text === text) {
+    return cached.data;
   }
   try {
     // SAFETY: the layout serialized this script tag's JSON from the same
     // `BlumeClientData` snapshot this reads back.
-    cachedData = JSON.parse(element.textContent) as BlumeClientData;
-    return cachedData;
+    const data = JSON.parse(text) as BlumeClientData;
+    cached = { data, text };
+    return data;
   } catch {
     return null;
   }
@@ -51,15 +56,29 @@ const readClientData = (): BlumeClientData | null => {
 
 /**
  * Read the injected snapshot after mount. `null` on the server and on the first
- * client render (so hydration matches), then the data once mounted.
+ * client render (so hydration matches), then the data once mounted, re-read
+ * after every client-router swap.
  */
 const useClientData = (): BlumeClientData | null => {
   const [data, setData] = useState<BlumeClientData | null>(null);
-  // Intentional post-mount hydration guard: `null` on the server and first
-  // client render so hydration matches, then the snapshot once mounted. The
-  // extra render is required; do not seed the initial value from the DOM.
-  // oxlint-disable-next-line react/react-compiler, react/set-state-in-effect, react-doctor/no-initialize-state -- deliberate SSR hydration guard
-  useEffect(() => setData(readClientData()), []);
+  useEffect(() => {
+    // `document` is undeclared on the server; probing `globalThis` avoids both
+    // the bare-reference ReferenceError and a `typeof` sniff.
+    if (!("document" in globalThis)) {
+      return;
+    }
+    const sync = () => setData(readClientData());
+    // Intentional post-mount hydration guard: `null` on the server and first
+    // client render so hydration matches, then the snapshot once mounted. The
+    // extra render is required; do not seed the initial value from the DOM.
+    // oxlint-disable-next-line react/react-compiler, react/set-state-in-effect, react-doctor/no-initialize-state -- deliberate SSR hydration guard
+    sync();
+    // An island kept across navigations (`transition:persist`) outlives the
+    // page it mounted on; the swap brings the next page's snapshot, so read
+    // it again or the hook keeps answering with the first page's data.
+    document.addEventListener("astro:after-swap", sync);
+    return () => document.removeEventListener("astro:after-swap", sync);
+  }, []);
   return data;
 };
 
@@ -143,11 +162,22 @@ export interface UseAssistant {
   loading: boolean;
   messages: AskMessage[];
   reset: () => void;
+  /**
+   * The conversation's id, new after every `reset()`. The `ask` analytics
+   * events carry it as `thread`, and the support link passes it along.
+   */
+  thread: string;
 }
 
 const DEFAULT_ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
 
 export interface UseAssistantOptions {
+  /**
+   * The site's bot check (`ai.assistant.captcha`), as `useBlume().config
+   * .assistant.captcha` holds it: each question gets a fresh token, sent as
+   * `captcha` in the request body.
+   */
+  captcha?: CaptchaSettings | null;
   /** Existing assistant endpoint; defaults to Blume's generated `/api/ask`. */
   endpoint?: string;
   /**
@@ -156,11 +186,38 @@ export interface UseAssistantOptions {
    * dictionary string.
    */
   errorMessage?: string;
+  /**
+   * Shown as the assistant's answer when the route's rate limit turns the
+   * question away (`429`). Defaults to an English notice; the built-in
+   * island passes its localized dictionary string.
+   */
+  rateLimitMessage?: string;
+  /**
+   * Shown as the assistant's answer when the bot check fails, in the browser
+   * or at the route (`403`). Defaults to an English notice; the built-in
+   * island passes its localized dictionary string.
+   */
+  verifyMessage?: string;
 }
 
 /** Shown as the assistant's answer when the request fails or throws. */
 const ASK_ERROR = "Something went wrong answering that. Please try again.";
 
+/** Shown as the assistant's answer when the rate limit turns a question away. */
+const ASK_RATE_LIMITED =
+  "You've asked a lot of questions. Try again in a few minutes.";
+
+/** Shown as the assistant's answer when the bot check fails. */
+const ASK_VERIFY_FAILED = "We couldn't check that you're human. Try again.";
+
+/** What the assistant sends the route. */
+interface AskPayload {
+  /** The bot check's token, when the site has one. */
+  captcha?: string;
+  messages: AskMessage[];
+  page: { path: string };
+}
+
 /** How the assistant's generated route opens its missing-credential notice. */
 const NOT_CONFIGURED = /^The assistant is not configured/u;
 
@@ -183,6 +240,26 @@ const unavailableNotice = async (
   return NOT_CONFIGURED.test(text) && text.length <= 200 ? text : null;
 };
 
+/** The notices the route's refusals map to. */
+interface RefusalNotices {
+  rateLimitMessage: string;
+  verifyMessage: string;
+}
+
+/**
+ * The reader-facing notice for the route turning a question away: the rate
+ * limit (`429`) or the bot check (`403`), or `null` for any other status.
+ */
+const refusalNotice = (
+  status: number,
+  notices: RefusalNotices
+): string | null => {
+  if (status === 429) {
+    return notices.rateLimitMessage;
+  }
+  return status === 403 ? notices.verifyMessage : 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,8 +273,12 @@ export const useAssistant = (
 ): UseAssistant => {
   const endpoint = options.endpoint ?? DEFAULT_ASK_ENDPOINT;
   const errorMessage = options.errorMessage ?? ASK_ERROR;
+  const rateLimitMessage = options.rateLimitMessage ?? ASK_RATE_LIMITED;
+  const verifyMessage = options.verifyMessage ?? ASK_VERIFY_FAILED;
+  const { captcha } = options;
   const [messages, setMessages] = useState<AskMessage[]>([]);
   const [loading, setLoading] = useState(false);
+  const [thread, setThread] = useState(newThreadId);
   // The stream writes into the conversation via state updates, so `reset()`
   // mid-answer must revoke the in-flight request's right to write — otherwise
   // its next chunk re-appends the assistant bubble onto the emptied list, and
@@ -239,7 +320,7 @@ export const useAssistant = (
       ) =>
         track(
           event,
-          { ...props, path: pathname, questionChars: trimmed.length },
+          { ...props, path: pathname, questionChars: trimmed.length, thread },
           { question: trimmed }
         );
       report("ask", {});
@@ -264,12 +345,32 @@ export const useAssistant = (
       const assistant: AskMessage = { content: "", role: "assistant" };
       setMessages([...history, assistant]);
       setLoading(true);
+      // Answer with a notice instead: an error, or the route turning the
+      // question away. Silent once a reset has revoked the question.
+      const fail = (notice: string) => {
+        if (live()) {
+          outcome("ask_error", { status });
+          assistant.content = notice;
+          setMessages([...history, { ...assistant }]);
+        }
+      };
       try {
+        // A fresh bot-check token per question, when the site has a check;
+        // `null` when the check didn't pass in the browser.
+        const token = captcha
+          ? await captchaToken(captcha).catch(() => null)
+          : undefined;
+        if (token === null) {
+          fail(verifyMessage);
+          return;
+        }
+        const payload: AskPayload = {
+          captcha: token,
+          messages: history,
+          page: { path },
+        };
         const response = await fetch(endpoint, {
-          body: JSON.stringify({
-            messages: history,
-            page: { path },
-          }),
+          body: JSON.stringify(payload),
           headers: { "content-type": "application/json" },
           method: "POST",
           signal: controller.signal,
@@ -278,12 +379,12 @@ export const useAssistant = (
         if (!response.ok) {
           // An error body (JSON, HTML error page) must not stream in as the
           // assistant's answer — only the route's own not-configured notice.
-          const notice = await unavailableNotice(response).catch(() => null);
-          if (live()) {
-            outcome("ask_error", { status });
-            assistant.content = notice ?? errorMessage;
-            setMessages([...history, { ...assistant }]);
-          }
+          const notice =
+            refusalNotice(status, {
+              rateLimitMessage,
+              verifyMessage,
+            }) ?? (await unavailableNotice(response).catch(() => null));
+          fail(notice ?? errorMessage);
           return;
         }
         const reader = response.body?.getReader();
@@ -316,20 +417,14 @@ export const useAssistant = (
           if (assistant.content) {
             outcome("ask_answer", { chars: assistant.content.length });
           } else {
-            outcome("ask_error", { status });
-            assistant.content = errorMessage;
-            setMessages([...history, { ...assistant }]);
+            fail(errorMessage);
           }
         }
       } 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 }]);
-        }
+        fail(errorMessage);
         // oxlint-disable-next-line react/todo -- React Compiler cannot lower try/finally; the hook stays manually memoized above
       } finally {
         if (live()) {
@@ -337,7 +432,16 @@ export const useAssistant = (
         }
       }
     },
-    [endpoint, errorMessage, loading, messages]
+    [
+      captcha,
+      endpoint,
+      errorMessage,
+      loading,
+      messages,
+      rateLimitMessage,
+      thread,
+      verifyMessage,
+    ]
   );
 
   // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
@@ -348,9 +452,10 @@ export const useAssistant = (
     abortRef.current?.abort();
     abortRef.current = null;
     setMessages([]);
+    setThread(newThreadId());
     // The in-flight `ask`'s finally is now stale and won't clear this.
     setLoading(false);
   }, []);
 
-  return { ask, loading, messages, reset };
+  return { ask, loading, messages, reset, thread };
 };

package/src/components/islands/support-link.ts

@@ -0,0 +1,68 @@
+/**
+ * The assistant's handoff to your support channel (`ai.assistant.support`).
+ * A `mailto:` link starts an email with the conversation as its body, so the
+ * reader doesn't have to repeat themselves; any other link gets the
+ * conversation's `thread` id in its query, the same id the assistant's
+ * analytics events carry, so a support team can find the conversation.
+ */
+
+/** One turn of the conversation. */
+export interface SupportMessage {
+  content: string;
+  role: "assistant" | "user";
+}
+
+/** What the link is built from. */
+export interface SupportContext {
+  /** The label the transcript gives the assistant's turns. */
+  ai: string;
+  messages: readonly SupportMessage[];
+  /** The email's subject. */
+  subject: string;
+  thread: string;
+  /** The label the transcript gives the reader's turns. */
+  you: string;
+}
+
+/**
+ * How much conversation an email carries: mail clients cut long `mailto:`
+ * links, so a long conversation is trimmed from the start, keeping the
+ * latest turns.
+ */
+export const MAX_TRANSCRIPT_CHARS = 1500;
+
+const transcriptOf = (context: SupportContext): string => {
+  const full = context.messages
+    .map(
+      (message) =>
+        `${message.role === "user" ? context.you : context.ai}: ${message.content}`
+    )
+    .join("\n\n");
+  return full.length > MAX_TRANSCRIPT_CHARS
+    ? `…${full.slice(-MAX_TRANSCRIPT_CHARS)}`
+    : full;
+};
+
+/** The support link for this conversation. */
+export const supportHref = (
+  support: string,
+  context: SupportContext
+): string => {
+  if (support.startsWith("mailto:")) {
+    // `mailto:` wants %20, not the `+` URLSearchParams writes for a space.
+    const body = `${transcriptOf(context)}\n\n(${context.thread})`;
+    const separator = support.includes("?") ? "&" : "?";
+    return `${support}${separator}subject=${encodeURIComponent(context.subject)}&body=${encodeURIComponent(body)}`;
+  }
+  const url = new URL(support, "https://blume.invalid");
+  url.searchParams.set("thread", context.thread);
+  return url.origin === "https://blume.invalid"
+    ? `${url.pathname}${url.search}${url.hash}`
+    : url.href;
+};
+
+/** A fresh conversation id: 16 hex characters. */
+export const newThreadId = (): string =>
+  Array.from(crypto.getRandomValues(new Uint8Array(8)), (byte) =>
+    byte.toString(16).padStart(2, "0")
+  ).join("");

package/src/components/islands/webmcp.ts

@@ -1,7 +1,7 @@
 import { unescape } from "html-escaper";
 
 import type { SearchFn } from "../layout/search/types.ts";
-import { joinBase, prefixBase } from "./base-path.ts";
+import { joinBase, mountBase, prefixBase } from "./base-path.ts";
 
 /**
  * WebMCP (W3C Web Machine Learning CG): in-page tools an agentic browser can
@@ -144,7 +144,7 @@ export const buildWebMcpTools = (options: WebMcpToolOptions): WebMcpTool[] => {
             hits
               .map(
                 (hit) =>
-                  `${plain(hit.title)} — ${prefixBase(options.base, hit.url)}\n${plain(hit.excerpt)}`
+                  `${plain(hit.title)} — ${mountBase(options.base, hit.url)}\n${plain(hit.excerpt)}`
               )
               .join("\n\n")
           );
@@ -175,6 +175,8 @@ export const buildWebMcpTools = (options: WebMcpToolOptions): WebMcpTool[] => {
       }
       const trimmed = route.length > 1 ? route.replace(/\/+$/u, "") : route;
       const target = trimmed === "/" ? "/index" : trimmed;
+      // The agent may hand back a served URL `search_docs` returned, base
+      // included, so a path already under the base keeps it (`prefixBase`).
       const response = await fetchFn(
         `${prefixBase(options.base, target)}.md`
       ).catch(() => null);

package/src/components/layout/Analytics.astro

@@ -1,5 +1,6 @@
 ---
 import VercelAnalytics from "@vercel/analytics/astro";
+import data from "blume:data";
 
 import { analyticsHead } from "../../analytics/head.ts";
 import type { BlumeDataConfig } from "../../core/data.ts";
@@ -10,12 +11,20 @@ import type { BlumeDataConfig } from "../../core/data.ts";
 // 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.
+//
+// With `consent` configured, every tag is held as inert `text/plain` until
+// the reader allows analytics, when the consent runtime runs it
+// (`consent/client.ts`); Vercel's component sends nothing until then instead
+// (`consent/init.ts`).
 interface Props {
   analytics?: BlumeDataConfig["analytics"] | null;
 }
 
 const { analytics } = Astro.props;
 const nodes = analyticsHead(import.meta.env.PROD ? (analytics ?? []) : []);
+const held = data.config.consent
+  ? { "data-blume-consent": "analytics", type: "text/plain" }
+  : {};
 ---
 
 {
@@ -24,9 +33,9 @@ const nodes = analyticsHead(import.meta.env.PROD ? (analytics ?? []) : []);
       return <VercelAnalytics {...node.props} />;
     }
     return node.content === null ? (
-      <script is:inline {...node.attributes} />
+      <script is:inline {...node.attributes} {...held} />
     ) : (
-      <script is:inline set:html={node.content} {...node.attributes} />
+      <script is:inline set:html={node.content} {...node.attributes} {...held} />
     );
   })
 }

package/src/components/layout/Banner.astro

@@ -1,7 +1,9 @@
 ---
 import data from "blume:data";
+import type { BlumeBanner } from "../../core/data.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { resolveLocalizable } from "../../core/localizable.ts";
 import { withBase } from "../islands/base-path.ts";
 import Icon from "../Icon.astro";
 
@@ -9,14 +11,11 @@ import Icon from "../Icon.astro";
 // every shell shows the same bar. The pre-paint hide for a dismissed banner and
 // the dismiss click handler live in the layout/Header, not here.
 interface Props {
-  banner:
-    | {
-        content: string;
-        link?: { text: string; href: string };
-        dismissible: boolean;
-        key: string;
-      }
-    | null;
+  /**
+   * The banner. Its `content` and link `text` may be per-locale maps, shown
+   * in `locale` (else the default locale, else the map's first entry).
+   */
+  banner: BlumeBanner | null;
   /** Localized banner labels. */
   strings?: UIStrings["banner"];
   /**
@@ -40,6 +39,11 @@ const b = { ...EN_UI.banner, ...strings };
 const navigation =
   (locale === undefined ? undefined : data.navigationByLocale[locale]) ??
   data.navigation;
+const defaultLocale = data.config.i18n?.defaultLocale;
+const content =
+  banner && resolveLocalizable(banner.content, locale, defaultLocale);
+const linkText =
+  banner?.link && resolveLocalizable(banner.link.text, locale, defaultLocale);
 const linkHref =
   banner?.link && banner.link.href === data.config.banner?.link?.href
     ? (navigation.bannerHref ?? banner.link.href)
@@ -55,13 +59,13 @@ const linkHref =
     >
       {/* 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>
+      <span dir="auto">{content}</span>
       {banner.link && linkHref && (
         <a
           class="inline-flex items-center gap-1 font-medium underline underline-offset-2"
           href={withBase(linkHref)}
         >
-          {banner.link.text}
+          {linkText}
           <Icon class="rtl:-scale-x-100" name="arrow-right" size={14} />
         </a>
       )}

package/src/components/layout/Breadcrumbs.astro

@@ -1,7 +1,7 @@
 ---
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
-import { withBase } from "../islands/base-path.ts";
+import { withMountedBase } from "../islands/base-path.ts";
 import type { Crumb } from "./nav-utils.ts";
 
 interface Props {
@@ -11,9 +11,11 @@ interface Props {
   strings?: UIStrings["nav"];
   /** Left-align full width (for the wide API layout) instead of the prose measure. */
   wide?: boolean;
+  /** Match a `center` page's wider centered column instead of the prose measure. */
+  centered?: boolean;
 }
 
-const { crumbs, strings, wide = false } = Astro.props;
+const { crumbs, strings, wide = false, centered = false } = Astro.props;
 
 // Merge over the English defaults so a label missing from a translation (or
 // from a not-yet-regenerated snapshot) still renders instead of coming out
@@ -31,11 +33,16 @@ const eyebrowCrumb = crumbs.length > 1 ? crumbs[crumbs.length - 2] : null;
       aria-label={n.breadcrumb}
       class:list={[
         "mb-2 text-muted-foreground text-sm",
-        wide ? "max-w-none" : "mx-auto max-w-content",
+        wide
+          ? "max-w-none"
+          : ["mx-auto", centered ? "max-w-[54rem]" : "max-w-content"],
       ]}
     >
       {eyebrowCrumb.route ? (
-        <a class="hover:text-foreground" href={withBase(eyebrowCrumb.route)}>
+        <a
+          class="hover:text-foreground"
+          href={withMountedBase(eyebrowCrumb.route)}
+        >
           {eyebrowCrumb.label}
         </a>
       ) : (

package/src/components/layout/ConsentBanner.astro

@@ -0,0 +1,62 @@
+---
+import { EN_UI } from "../../core/i18n-ui.ts";
+import type { UIStrings } from "../../core/i18n-ui.ts";
+import { newTabAttrs } from "../../core/new-tab.ts";
+import { withBase } from "../islands/base-path.ts";
+
+// The `native()` consent banner: a card at the foot of the viewport asking to
+// use analytics cookies. It renders hidden, and the consent runtime
+// (`consent/client.ts`) shows it until the reader answers, stores the answer,
+// and shows it again from the footer's Cookie settings link. Accept and
+// Decline carry the same weight, so declining is as easy as accepting.
+interface Props {
+  /** The privacy policy link: a page route or a URL. */
+  policy?: string;
+  /** Localized banner labels. */
+  strings?: UIStrings["consent"];
+}
+
+const { policy, strings } = Astro.props;
+const c = { ...EN_UI.consent, ...strings };
+const buttonClass =
+  "flex-1 rounded-blume border border-border px-4 py-2 text-foreground text-sm transition-colors hover:border-foreground";
+---
+
+<div
+  aria-label={c.label}
+  class="fixed inset-x-4 bottom-4 z-50 rounded-blume border border-border bg-background p-4 shadow-lg sm:start-auto sm:end-4 sm:w-96"
+  data-blume-consent-banner
+  hidden
+  role="region"
+>
+  <p class="text-foreground text-sm">
+    {c.message}{" "}
+    {
+      policy && (
+        <a
+          class="text-muted-foreground underline underline-offset-2 transition-colors hover:text-foreground"
+          href={withBase(policy)}
+          {...newTabAttrs(policy)}
+        >
+          {c.policy}
+        </a>
+      )
+    }
+  </p>
+  <div class="mt-3 flex gap-2">
+    <button
+      class={buttonClass}
+      data-blume-consent-choice="decline"
+      type="button"
+    >
+      {c.decline}
+    </button>
+    <button
+      class={buttonClass}
+      data-blume-consent-choice="accept"
+      type="button"
+    >
+      {c.accept}
+    </button>
+  </div>
+</div>

package/src/components/layout/ConsentHead.astro

@@ -0,0 +1,38 @@
+---
+import { consentHead } from "../../consent/head.ts";
+import { CONSENT_INIT_SCRIPT } from "../../consent/init.ts";
+import type { BlumeDataConfig } from "../../core/data.ts";
+
+// The consent layer's <head> output, rendered ahead of `Analytics.astro` by
+// every layout when `consent` is configured: the inline script that creates
+// `window.blumeConsent` (`consent/init.ts`), the adapter's own tags — a
+// hosted consent manager's loader and the bridge that reports its answers —
+// and the runtime that runs the held analytics (`consent/client.ts`), which
+// starts the adapter's browser module, if it has one (`blume:consent-client`,
+// see `consent/clients.ts`). Like analytics, a hosted manager loads in
+// production builds only; a browser module (`native()`'s banner) works in
+// `blume dev` too.
+interface Props {
+  consent: NonNullable<BlumeDataConfig["consent"]>;
+}
+
+const { consent } = Astro.props;
+const tags = import.meta.env.PROD ? consentHead(consent) : [];
+---
+
+<script data-kind={consent.kind} is:inline set:html={CONSENT_INIT_SCRIPT} />
+{
+  tags.map((tag) =>
+    tag.content === null ? (
+      <script is:inline {...tag.attributes} />
+    ) : (
+      <script is:inline set:html={tag.content} {...tag.attributes} />
+    )
+  )
+}
+<script>
+  import { startConsentClient } from "blume:consent-client";
+  import { startConsent } from "../../consent/client.ts";
+
+  startConsent(startConsentClient);
+</script>