blume 1.1.3 → 1.2.0

package/src/components/islands/hooks.ts

@@ -139,7 +139,12 @@ export interface UseAskAI {
   reset: () => void;
 }
 
-const ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
+const DEFAULT_ASK_ENDPOINT = joinBase(import.meta.env.BASE_URL, "api/ask");
+
+export interface UseAskAIOptions {
+  /** Existing Ask AI endpoint; defaults to Blume's generated `/api/ask`. */
+  endpoint?: string;
+}
 
 /** Shown as the assistant's answer when the request fails or throws. */
 const ASK_ERROR = "Something went wrong answering that. Please try again.";
@@ -152,9 +157,17 @@ const currentPath = (): string =>
  * Stream answers from the Ask AI endpoint. Mirrors the built-in Ask AI island so
  * a custom chat UI shares the same grounded, page-aware backend.
  */
-export const useAskAI = (): UseAskAI => {
+export const useAskAI = (options: UseAskAIOptions = {}): UseAskAI => {
+  const endpoint = options.endpoint ?? DEFAULT_ASK_ENDPOINT;
   const [messages, setMessages] = useState<AskMessage[]>([]);
   const [loading, setLoading] = useState(false);
+  // 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
+  // its error path resurrects the entire pre-reset history. Mirrors the
+  // built-in island's generation/abort guard.
+  const generation = useRef(0);
+  const abortRef = useRef<AbortController | null>(null);
 
   // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
   // preserves a stable `ask` identity for consumers that depend on it. With the
@@ -166,6 +179,11 @@ export const useAskAI = (): UseAskAI => {
       if (!trimmed || loading) {
         return;
       }
+      generation.current += 1;
+      const { current } = generation;
+      const controller = new AbortController();
+      abortRef.current = controller;
+      const live = () => current === generation.current;
       const history: AskMessage[] = [
         ...messages,
         { content: trimmed, role: "user" },
@@ -174,37 +192,40 @@ export const useAskAI = (): UseAskAI => {
       setMessages([...history, assistant]);
       setLoading(true);
       try {
-        const response = await fetch(ASK_ENDPOINT, {
+        const response = await fetch(endpoint, {
           body: JSON.stringify({
             messages: history,
             page: { path: currentPath() },
           }),
           headers: { "content-type": "application/json" },
           method: "POST",
+          signal: controller.signal,
         });
         if (!response.ok) {
           // An error body (JSON, HTML error page) must not stream in as the
           // assistant's answer.
-          assistant.content = ASK_ERROR;
-          setMessages([...history, { ...assistant }]);
+          if (live()) {
+            assistant.content = ASK_ERROR;
+            setMessages([...history, { ...assistant }]);
+          }
           return;
         }
         const reader = response.body?.getReader();
         const decoder = new TextDecoder();
         if (reader) {
           let done = false;
-          while (!done) {
+          while (!done && live()) {
             // oxlint-disable-next-line no-await-in-loop, react-doctor/async-await-in-loop -- sequential stream consumption; iterations are not independent
             const chunk = await reader.read();
             ({ done } = chunk);
-            if (chunk.value) {
+            if (chunk.value && live()) {
               // Streaming mode: a multi-byte UTF-8 sequence split across
               // chunks must not flush as U+FFFD garbage.
               assistant.content += decoder.decode(chunk.value, {
                 stream: true,
               });
-              setMessages((current) => [
-                ...current.slice(0, -1),
+              setMessages((currentMessages) => [
+                ...currentMessages.slice(0, -1),
                 { ...assistant },
               ]);
             }
@@ -212,20 +233,32 @@ export const useAskAI = (): UseAskAI => {
         }
       } catch {
         // A thrown fetch (offline, DNS failure, CORS) must not strand the
-        // pre-appended empty assistant message as a stuck placeholder.
-        assistant.content = ASK_ERROR;
-        setMessages([...history, { ...assistant }]);
+        // pre-appended empty assistant message as a stuck placeholder. A
+        // reset's abort lands here too — the guard keeps it silent.
+        if (live()) {
+          assistant.content = ASK_ERROR;
+          setMessages([...history, { ...assistant }]);
+        }
       } finally {
-        setLoading(false);
+        if (live()) {
+          setLoading(false);
+        }
       }
     },
-    [loading, messages]
+    [endpoint, loading, messages]
   );
 
   // Retained for the compiler-off opt-out path (`react: { compiler: false }`):
   // keeps a stable `reset` identity. With the compiler on it's redundant but inert.
   // oxlint-disable-next-line react-doctor/react-compiler-no-manual-memoization -- see above
-  const reset = useCallback(() => setMessages([]), []);
+  const reset = useCallback(() => {
+    generation.current += 1;
+    abortRef.current?.abort();
+    abortRef.current = null;
+    setMessages([]);
+    // The in-flight `ask`'s finally is now stale and won't clear this.
+    setLoading(false);
+  }, []);
 
   return { ask, loading, messages, reset };
 };

package/src/components/layout/NavTree.astro

@@ -129,29 +129,43 @@ const initialId =
       </div>
       {panels.map((panel) => (
         <div data-nav-panel={panel.id} hidden={panel.id !== initialId}>
-          <div class="mb-3 flex items-center gap-1.5">
-            <button
-              aria-label={n.back}
-              class="-ml-1 flex shrink-0 items-center justify-center rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
-              data-nav-back={panel.parentId}
-              type="button"
-            >
-              <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
-            </button>
-            {panel.route ? (
+          {/* The title is the only sidebar link to the section's own page, so
+              a routed panel keeps it as a link; without a route the whole row
+              becomes the back button. Either way every part of the row is
+              interactive. */}
+          {panel.route ? (
+            <div class="mb-3 flex items-center gap-0.5">
+              <button
+                aria-label={n.back}
+                class="-ml-1 flex shrink-0 items-center justify-center self-stretch rounded px-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                data-nav-back={panel.parentId}
+                type="button"
+              >
+                <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
+              </button>
               <a
                 aria-current={panel.route === currentRoute ? "page" : undefined}
-                class="flex-1 truncate font-semibold text-foreground text-sm hover:underline"
+                class="flex-1 truncate rounded px-1 py-1 font-semibold text-foreground text-sm transition-colors hover:bg-muted"
                 href={withBase(panel.route)}
               >
                 {panel.label}
               </a>
-            ) : (
-              <span class="flex-1 truncate font-semibold text-foreground text-sm">
-                {panel.label}
-              </span>
-            )}
-          </div>
+            </div>
+          ) : (
+            <button
+              aria-label={`${n.back}: ${panel.label}`}
+              class="-ml-1 mb-3 flex w-full items-center gap-1.5 rounded p-1 text-left font-semibold text-foreground text-sm transition-colors hover:bg-muted"
+              data-nav-back={panel.parentId}
+              type="button"
+            >
+              <Icon
+                class="shrink-0 text-muted-foreground rtl:-scale-x-100"
+                name="arrow-left"
+                size={16}
+              />
+              <span class="flex-1 truncate">{panel.label}</span>
+            </button>
+          )}
           <Self
             currentRoute={currentRoute}
             depth={1}
@@ -236,7 +250,7 @@ const initialId =
           const open = active || item.collapsed === false;
           return (
             <li class={spacing}>
-              <details class="group" open={open}>
+              <details open={open}>
                 <summary class="flex cursor-pointer list-none items-center gap-1.5 rounded-[0.65rem] px-2.5 py-1.5 text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground [&::-webkit-details-marker]:hidden">
                   {item.route ? (
                     <a
@@ -273,7 +287,11 @@ const initialId =
                       )}
                     </>
                   )}
-                  <span class="shrink-0 text-muted-foreground transition-transform group-open:rotate-90">
+                  {/* Scope the rotation to this group's own `details` — the
+                      `group-open` variant matches any open ancestor `.group`,
+                      so nested chevrons rotated while their own group stayed
+                      closed. */}
+                  <span class="shrink-0 text-muted-foreground transition-transform [details[open]>summary_&]:rotate-90">
                     <Icon name="chevron-right" size={13} />
                   </span>
                 </summary>

package/src/components/layout/ReferenceLayout.astro

@@ -53,6 +53,8 @@ interface Props {
   fontCssVars?: string[];
   searchEnabled: boolean;
   pageTitle: string;
+  /** Keep the reference route out of crawler indexes. */
+  noindex?: boolean;
   /** Active locale code for `<html lang>` (defaults to `en`). */
   locale?: string;
   /** Text direction for `<html dir>` (defaults to `ltr`). */
@@ -74,6 +76,7 @@ const {
   fontCssVars,
   searchEnabled,
   pageTitle,
+  noindex = false,
   locale = "en",
   dir = "ltr",
   ui,
@@ -89,6 +92,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {noindex && <meta name="robots" content="noindex" />}
     <title>{pageTitle}</title>
     <Favicon favicon={favicon} appleIcon={appleIcon} />
     <Fonts cssVars={fontCssVars ?? []} />

package/src/components/layout/RootLayout.astro

@@ -25,7 +25,11 @@ import Breadcrumbs from "./Breadcrumbs.astro";
 import Empty from "./Empty.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
-import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
+import {
+  BANNER_INIT_SCRIPT,
+  SIDEBAR_SCROLL_INIT_SCRIPT,
+  THEME_INIT_SCRIPT,
+} from "./head-scripts.ts";
 import Header from "./Header.astro";
 import Icon from "../Icon.astro";
 import {
@@ -355,7 +359,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
 <!doctype html>
-<html dir={dir} lang={locale}>
+<html data-pagefind-ignore={indexable ? undefined : "all"} dir={dir} lang={locale}>
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
@@ -558,7 +562,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
             </nav>
           )
         }
-        <nav>
+        <nav data-blume-nav-tree>
           {
             MobileNavSlot ? (
               <>
@@ -587,6 +591,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
           }
         </nav>
       </aside>
+      <script is:inline set:html={SIDEBAR_SCROLL_INIT_SCRIPT} />
       <main class="px-6 pt-6 pb-10 lg:px-8 xl:px-10" id="blume-content">
         <BreadcrumbsSlot
           crumbs={crumbs}
@@ -896,6 +901,12 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         };
 
         for (const image of zoomTargets) {
+          // An image that is itself a link navigates on click — binding zoom
+          // to it would flash a zoom overlay in the instant before navigation
+          // and advertise (via the cursor) a zoom that never happens.
+          if (image.closest("a")) {
+            continue;
+          }
           image.classList.add("cursor-zoom-in");
           image.addEventListener("click", () => openZoom(image));
         }

package/src/components/layout/Search.astro

@@ -325,7 +325,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         document.addEventListener("keydown", (event) => {
           if (
             (event.key === "k" || event.key === "K") &&
-            (event.metaKey || event.ctrlKey)
+            (event.metaKey || event.ctrlKey) &&
+            // Ctrl+Shift+K is Firefox's web console; a shifted or alted chord
+            // belongs to the browser, not the search dialog.
+            !event.shiftKey &&
+            !event.altKey
           ) {
             // ⌘K toggles, mirroring the Ask AI panel's ⌘I: pressing it with
             // the dialog open must close it, not re-showModal an open dialog

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

@@ -1,11 +1,12 @@
 /**
  * Pre-paint inline scripts shared by the document layouts (`RootLayout`,
- * `PageLayout`, `ReferenceLayout`). They run synchronously in `<head>`, before
- * first paint, so the page never flashes the wrong theme or a since-dismissed
- * banner. Kept in one place so the layouts can't drift on this timing-critical
- * logic.
+ * `PageLayout`, `ReferenceLayout`). They run synchronously — in `<head>`, or
+ * immediately after the markup they act on — before that content paints, so the
+ * page never flashes the wrong theme, a since-dismissed banner, or a sidebar
+ * scrolled away from the current page. Kept in one place so the layouts can't
+ * drift on this timing-critical logic.
  *
- * Both are constants, never built by interpolating config into source text: the
+ * All are constants, never built by interpolating config into source text: any
  * values they need ride in as `data-*` attributes on the script tag and are read
  * back through `document.currentScript`. Baking a config string into JS — even
  * via `JSON.stringify` — is code construction, and JSON escaping does not cover
@@ -27,3 +28,19 @@ export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.
  * Reads `data-key` — the banner's dismissal key.
  */
 export const BANNER_INIT_SCRIPT = `(()=>{const k=document.currentScript?.dataset.key;if(k&&localStorage.getItem("blume-banner:"+k))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`;
+
+/**
+ * Center the current page's sidebar link before the sidebar paints. Every
+ * navigation is a full page load, and the sidebar is its own scroll container,
+ * so without this it is reborn scrolled to the top on every click — on a long
+ * sidebar the viewport visibly jumps away from the link you just clicked.
+ *
+ * Runs inline immediately after the sidebar `<aside>` (not in `<head>`: it
+ * needs that markup parsed). The lookup is scoped to the page tree
+ * (`data-blume-nav-tree`) because the drawer also holds the mobile tabs list,
+ * whose active tab is `aria-current` too. `getClientRects()` skips links that
+ * aren't rendered — `hidden` drill-in panels and breakpoint-hidden duplicates —
+ * and the script no-ops when the active link is already inside the visible
+ * scroll area, so a short sidebar never moves.
+ */
+export const SIDEBAR_SCROLL_INIT_SCRIPT = `(()=>{const n=document.querySelector("[data-blume-nav-drawer]");const s=n&&(n.querySelector("[data-blume-nav-tree]")||n);if(!s)return;let l=null;for(const a of s.querySelectorAll('a[aria-current="page"]')){if(a.getClientRects().length){l=a;break;}}if(!l)return;const r=n.getBoundingClientRect();const t=l.getBoundingClientRect();if(t.top>=r.top&&t.bottom<=r.bottom)return;n.scrollTop+=t.top-r.top-(n.clientHeight-t.height)/2;})();`;

package/src/components/openapi/SchemaProperty.astro

@@ -99,10 +99,10 @@ const expandable =
   }
   {
     expandable && (
-      <details class="group mt-2" open={expandAll}>
+      <details class="mt-2" open={expandAll}>
         <summary class="cursor-pointer select-none text-accent text-xs hover:underline">
-          <span class="group-open:hidden">Show properties</span>
-          <span class="hidden group-open:inline">Hide properties</span>
+          <span class="[details[open]>summary_&]:hidden">Show properties</span>
+          <span class="hidden [details[open]>summary_&]:inline">Hide properties</span>
         </summary>
         <div class="mt-2 border-border border-l pl-4">
           <SchemaTable

package/src/core/config-input.ts

@@ -1,3 +1,4 @@
+import type { AstroIntegration } from "astro";
 import type { z } from "zod";
 
 import type { ComponentMarkdown } from "../ai/component-markdown.ts";
@@ -290,6 +291,15 @@ export interface NavTabItem {
 
 /** A top-level tab in the header, optionally opening a dropdown of items. */
 export interface NavTab {
+  /**
+   * Where the tab links to, when that differs from `path`. `path` scopes the
+   * sidebar section and matches the active tab; without `href`, a section whose
+   * `path` isn't itself a page falls back to the section's first page, or keeps
+   * `path` when the section has no linkable page at all. Set this to send
+   * readers somewhere else — e.g. a generated `/changelog` index, or a custom
+   * `.astro` landing page, neither of which is part of the content tree.
+   */
+  href?: string;
   /** Lucide icon name shown beside the label. */
   icon?: string;
   /** Dropdown items; omit for a plain link tab. */
@@ -522,6 +532,12 @@ export interface AskConfig {
   baseUrl?: string;
   /** Turn Ask AI on. Defaults to `false`. */
   enabled?: boolean;
+  /**
+   * Existing Ask AI endpoint to call instead of generating one. This keeps a
+   * Blume site static while an API backend owns retrieval, model access, rate
+   * limiting, and streaming. Accepts an absolute URL or root-relative path.
+   */
+  endpoint?: string;
   /** Model id to use. Defaults to `openai/gpt-5.5`. */
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */
@@ -1115,6 +1131,8 @@ export interface BlumeConfig {
   github?: GithubConfig;
   /** Internationalization (opt-in multi-locale). */
   i18n?: I18nConfig;
+  /** Astro integrations appended after Blume's built-ins, in declaration order. */
+  integrations?: AstroIntegration[];
   /** "Last updated" timestamps from git history or frontmatter. Defaults to `false`. */
   lastModified?: LastModifiedConfig;
   /** Site logo / brand mark. */

package/src/core/config.ts

@@ -84,6 +84,10 @@ import type { Diagnostic } from "./types.ts";
  * - `analytics` — PostHog, Vercel, or arbitrary `scripts` (Plausible, Fathom,
  *   GA, …).
  *
+ * **Astro**
+ * - `integrations` — Astro integrations appended after Blume's built-ins, in
+ *   declaration order. Install and maintain each integration in the site.
+ *
  * **Deployment & i18n**
  * - `deployment` — `site` URL (needed for absolute links, sitemaps, and OG),
  *   `adapter` (`vercel`/`node`/`netlify`/`cloudflare`), `output`

package/src/core/data.ts

@@ -95,6 +95,7 @@ export interface BlumeDataConfig {
   appleIcon: BlumeFavicon | null;
   /** Ask AI empty-state suggestions, or `null` when Ask AI is off. */
   ask: {
+    endpoint: string | null;
     suggestions: NonNullable<ResolvedConfig["ai"]["ask"]>["suggestions"];
   } | null;
   banner: BlumeBanner | null;
@@ -104,6 +105,8 @@ export interface BlumeDataConfig {
   codeThemes: ResolvedConfig["markdown"]["codeBlocks"]["theme"];
   /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
   codeWrap: boolean;
+  /** `dateFormat`: `Intl.DateTimeFormat` options for the date stamps. */
+  dateFormat: ResolvedConfig["dateFormat"];
   description: string | undefined;
   favicon: BlumeFavicon;
   feedback: boolean;

package/src/core/deployment-env.ts

@@ -30,12 +30,17 @@ const PLATFORMS: Platform[] = [
   {
     adapter: "vercel",
     detect: (env) => Boolean(env.VERCEL),
-    site: (env) => toUrl(env.VERCEL_PROJECT_PRODUCTION_URL ?? env.VERCEL_URL),
+    // Fall through per *resolved* value, not per variable — a platform can set
+    // a var to the empty string, which `??` on the raw values treats as
+    // present, dead-ending the chain and silently losing the site URL.
+    site: (env) =>
+      toUrl(env.VERCEL_PROJECT_PRODUCTION_URL) ?? toUrl(env.VERCEL_URL),
   },
   {
     adapter: "netlify",
     detect: (env) => Boolean(env.NETLIFY),
-    site: (env) => toUrl(env.URL ?? env.DEPLOY_PRIME_URL ?? env.DEPLOY_URL),
+    site: (env) =>
+      toUrl(env.URL) ?? toUrl(env.DEPLOY_PRIME_URL) ?? toUrl(env.DEPLOY_URL),
   },
   {
     adapter: "cloudflare",

package/src/core/graph.ts

@@ -97,6 +97,7 @@ const buildLocaleNavigation = (
     path.startsWith("/") ? localizeRoute(path, code, i18n) : path;
   const tabs = options.navigation.tabs?.map((tab) => ({
     ...tab,
+    ...(tab.href ? { href: localizePath(tab.href) } : {}),
     items: tab.items?.map((item) => ({
       ...item,
       path: localizePath(item.path),
@@ -116,7 +117,13 @@ const buildLocaleNavigation = (
     basePath: options.basePath ?? "",
     diagnostics,
     display: options.navigation.sidebar.display,
-    featured: options.navigation.featured,
+    // Internal featured hrefs are localized like tab paths — a pinned
+    // `/changelog` link rendered on `/fr/…` pages must stay inside the
+    // reader's locale, not kick them back to the default one.
+    featured: options.navigation.featured?.map((link) => ({
+      ...link,
+      href: localizePath(link.href),
+    })),
     folderMeta: options.folderMeta,
     // The localized tree root ("/" for the hidden default, "/fr" otherwise):
     // the tab pointing here spans the whole tree and must not be treated as a

package/src/core/i18n.ts

@@ -105,11 +105,19 @@ export const localePlacement = (
 ): { navPath: string; locales: string[] } => {
   const base = rel.slice(0, rel.length - ext.length);
 
-  // Shared `$` file: the same content in every locale.
+  // Shared `$` file: the same content in every locale. A shared file placed
+  // inside a locale directory (`fr/changelog.$.mdx`) still sheds that
+  // directory from its nav path — otherwise every locale's record would route
+  // under `/fr/…`, nesting the default locale inside the French namespace and
+  // the French copy at `/fr/fr/…`.
   if (base.endsWith(".$")) {
+    const shared = `${base.slice(0, -2)}${ext}`;
     return {
       locales: i18n.locales.map((locale) => locale.code),
-      navPath: `${base.slice(0, -2)}${ext}`,
+      navPath:
+        i18n.parser === "dir"
+          ? detectLocale(shared.split("/"), i18n).rest.join("/")
+          : shared,
     };
   }
 

package/src/core/navigation.ts

@@ -473,9 +473,13 @@ const normalizeRef = (ref: string): string => {
     return "/";
   }
   const withSlash = ref.startsWith("/") ? ref : `/${ref}`;
-  const trimmed = withSlash.endsWith("/index")
-    ? withSlash.slice(0, -"/index".length)
-    : withSlash;
+  // Routes are stored slashless (`/guides`, not `/guides/`); a hand-written
+  // `"guides/"` ref must still find its page instead of being silently
+  // dropped from the sidebar.
+  const noTrailing = withSlash.replace(/\/+$/u, "");
+  const trimmed = noTrailing.endsWith("/index")
+    ? noTrailing.slice(0, -"/index".length)
+    : noTrailing;
   // "/index" trims to "" — that's the root, not an empty route.
   return trimmed === "" ? "/" : trimmed;
 };
@@ -609,10 +613,16 @@ const resolveTabHref = (sidebar: NavNode[], path: string): string => {
   return walk(sidebar) ? path : (first ?? path);
 };
 
-/** Attach a resolved `href` to each tab whose section has no index page. */
+/**
+ * Attach a resolved `href` to each tab whose section has no index page. An
+ * author-declared `href` is the tab's stated target, so it's kept as-is —
+ * resolution only fills in the tabs that didn't declare one. That's what lets a
+ * tab point at a route outside the content tree (a generated `/changelog`
+ * index, a custom `.astro` page), which resolution can't see.
+ */
 const withTabHrefs = (tabs: NavTab[], sidebar: NavNode[]): NavTab[] =>
   tabs.map((tab) => {
-    const href = resolveTabHref(sidebar, tab.path);
+    const href = tab.href ?? resolveTabHref(sidebar, tab.path);
     return href === tab.path ? tab : { ...tab, href };
   });
 
@@ -684,6 +694,7 @@ export const buildNavigation = (
   const tabs = basePath
     ? (options.tabs ?? []).map((tab) => ({
         ...tab,
+        ...(tab.href ? { href: withBasePath(basePath, tab.href) } : {}),
         items: tab.items?.map(rebasePath),
         path: withBasePath(basePath, tab.path),
       }))