blume 1.5.0 → 1.5.2

package/src/astro/templates.ts

@@ -3,6 +3,7 @@ import { pathToFileURL } from "node:url";
 
 import { dirname, isAbsolute, join, relative } from "pathe";
 
+import type { AskRetrievalOptions } from "../ai/ask-context.ts";
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
@@ -406,6 +407,11 @@ const resolveOptimizeDeps = (options: {
   const optimizeDepsInclude = [
     "blume > mermaid",
     "blume > epub-gen-memory/bundle",
+    // Astro's own client-router/prefetch virtual modules are deliberately NOT
+    // forced in here: they read Vite `define`-injected constants
+    // (__PREFETCH_PREFETCH_ALL__ and friends) that a pre-bundled copy loses,
+    // throwing ReferenceError on every page. Astro manages their optimization
+    // itself, without a mid-session reload.
     ...(options.needsReact && options.reactCompilerPath
       ? ["react/compiler-runtime"]
       : []),
@@ -694,6 +700,11 @@ ${userConfigSetup}export default defineConfig({
     },
   },
   devToolbar: { enabled: false },
+  // The layouts render Astro's <ClientRouter />, and its in-place swaps read
+  // from the prefetch cache — fetching every link on hover/viewport hides the
+  // request latency behind the user's intent, so most navigations swap
+  // instantly.
+  prefetch: { prefetchAll: true },
   vite: {
     plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
     // Everything hydration can reach must be part of the dev dep optimizer's
@@ -887,17 +898,30 @@ export const collections = { docs${options.staged ? ", staged" : ""} };
 const ASK_FALLBACK_PROMPT =
   "You are a helpful documentation assistant. Answer using the project's documentation.";
 
+/** The `ai.ask` values the generated endpoint has to carry with it. */
+export interface AskEndpointOptions {
+  /** `ai.ask.instructions` — extra system-prompt text. */
+  instructions?: string;
+  /** `ai.ask.retrieval` — how much documentation each question carries. */
+  retrieval?: AskRetrievalOptions;
+}
+
 /**
  * Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`).
- * `instructions` (the `ai.ask.instructions` config) is appended to the
+ *
+ * `options.instructions` (the `ai.ask.instructions` config) is appended to the
  * built-in prompt on every path: the grounded prompt via `createAskContext`,
- * and the plain fallback here.
+ * and the plain fallback here. `options.retrieval` (the `ai.ask.retrieval`
+ * config) is forwarded to `createAskContext` on the grounded path, where it
+ * sizes retrieval. Both travel in one options object so a new call site can't
+ * silently drop one of them.
  */
 export const askEndpointTemplate = (
   backend: AskBackend,
   grounded: boolean,
-  instructions?: string
+  options?: AskEndpointOptions
 ): string => {
+  const instructions = options?.instructions;
   const fallbackPrompt = instructions
     ? `${ASK_FALLBACK_PROMPT}\n\n${instructions}`
     : ASK_FALLBACK_PROMPT;
@@ -933,9 +957,15 @@ export const askEndpointTemplate = (
       'import { createAskContext } from "blume/ai/ask-context.ts";',
       'import askData from "../../generated/ask-data.json";'
     );
-    const groundOptions = instructions
-      ? `, { instructions: ${JSON.stringify(instructions)} }`
-      : "";
+    const groundFields: string[] = [];
+    if (instructions) {
+      groundFields.push(`instructions: ${JSON.stringify(instructions)}`);
+    }
+    if (options?.retrieval) {
+      groundFields.push(`retrieval: ${JSON.stringify(options.retrieval)}`);
+    }
+    const groundOptions =
+      groundFields.length > 0 ? `, { ${groundFields.join(", ")} }` : "";
     setup += `\nconst ground = createAskContext(askData${groundOptions});\n`;
   }
   // Validate the client-supplied body and cap its size. The endpoint is
@@ -1099,7 +1129,7 @@ const SEARCH_BASE_IMPORT =
 /**
  * A client that loads a static `blume-search.json` index (Orama, FlexSearch).
  * `locale` (Orama only) is the site's `i18n.defaultLocale`, which selects a
- * word-segmenting tokenizer for languages written without spaces.
+ * word-segmenting tokenizer for every non-Latin script.
  */
 const staticSearchClient = (module: string, locale?: string): string =>
   `${SEARCH_CLIENT_HEADER}${searchClientImport(module)}${SEARCH_BASE_IMPORT}
@@ -1410,6 +1440,31 @@ export const ALL: APIRoute = ({ request }) => handler(request);
 `;
 };
 
+/**
+ * Generate the playground's CORS proxy endpoint
+ * (`.blume/src/blume-openapi/api-proxy.ts`), behind
+ * `openapi.playground.proxy: true`. A thin server-rendered wrapper around the
+ * shipped `createPlaygroundProxyHandler`; injected at `/_api-proxy` rather
+ * than written under `pages/` because Astro treats `_`-prefixed page files as
+ * private.
+ *
+ * `origins` — the origins of the servers the documented specs declare — is
+ * baked in as the handler's allowlist. It cannot come from the request or from
+ * client-side data: that is the whole trust boundary keeping the endpoint from
+ * being an open proxy onto the deployment's own network.
+ */
+export const playgroundProxyTemplate = (origins: string[]): string =>
+  `// Generated by Blume. Do not edit.
+import type { APIRoute } from "astro";
+import { createPlaygroundProxyHandler } from "blume/openapi/proxy.ts";
+
+export const prerender = false;
+
+const handler = createPlaygroundProxyHandler(${JSON.stringify(origins)});
+
+export const ALL: APIRoute = ({ request }) => handler(request);
+`;
+
 /** Generate a prerendered endpoint that serves a fixed JSON payload. */
 export const staticJsonEndpointTemplate = <Payload extends object>(
   payload: Payload
@@ -1454,7 +1509,8 @@ export function GET({ props }: { props: { section: string } }) {
 /** Generate the OG image endpoint (`.blume/src/pages/og/[...slug].png.ts`). */
 export const ogEndpointTemplate = (
   customRoutes: OgCustomRoute[] = [],
-  og: { families?: OgFontFamilies; fonts?: OgFont[] } = {}
+  og: { families?: OgFontFamilies; fonts?: OgFont[] } = {},
+  includeChangelog = false
 ): string =>
   `// Generated by Blume. Do not edit.
 import { renderOgImage } from "blume/og";
@@ -1493,6 +1549,13 @@ export function getStaticPaths() {
   }
   for (const route of data.routes) {
     add(route.path === "/" ? "index" : route.path.slice(1), route.title);
+  }${
+    includeChangelog
+      ? `
+  // The generated changelog index is not a content route, so it needs its own
+  // card. Added last: a custom page or content route owning /changelog wins.
+  add("changelog", data.ui.changelog?.title ?? "Changelog");`
+      : ""
   }
   return paths;
 }
@@ -1795,10 +1858,9 @@ const contentLocale =
 const contentDir = i18n
   ? (i18n.locales.find((l) => l.code === contentLocale)?.dir ?? "ltr")
   : "ltr";
-const absolute = (path: string) => {
-  const p = withBase(path);
-  return base + (p === "/" ? "" : p);
-};
+// The root route keeps its trailing slash (\`https://site/\`) so canonical and
+// hreflang URLs byte-match the sitemap's <loc> for the home page.
+const absolute = (path: string) => base + withBase(path);
 
 // An archived page defaults its canonical to the same page in the latest docs
 // when that page still exists — search engines treat the live page as
@@ -1809,7 +1871,7 @@ const canonical =
   (archived && archived.canonical === "latest" && latestVersionAlt && base
     ? absolute(latestVersionAlt.path)
     : base
-      ? \`\${base}\${basedRoute === "/" ? "" : encodeURI(basedRoute)}\`
+      ? \`\${base}\${basedRoute === "/" ? "/" : encodeURI(basedRoute)}\`
       : null);
 const effectiveNoindex = Boolean(seo.noindex) || (archived?.noindex ?? false);
 
@@ -1944,6 +2006,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   feedback={data.config.feedback}
   exportPdf={${options.exportPdf}}
   exportEpub={${options.exportEpub}}
+  openInChat={data.config.openInChat}
   feeds={data.feeds}
   discovery={data.config.discovery}
   siteUrl={data.config.site}
@@ -2122,6 +2185,12 @@ const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 const basedRoute = withBase("/changelog");
 const canonical = base ? base + basedRoute : null;
 
+// The generated OG card for this route (the /og endpoint emits it alongside
+// the content-route cards), absolutized like the catch-all's so crawlers get
+// a full URL when the site is known.
+const ogPath = data.config.og.enabled ? withBase("/og/changelog.png") : null;
+const ogImage = ogPath && base ? base + ogPath : ogPath;
+
 // The page chrome (h1, title, description) comes from the same translatable
 // \`changelog\` group as the reveal button; optional chaining tolerates a
 // not-yet-regenerated data snapshot from before these keys existed.
@@ -2129,7 +2198,10 @@ const changelogTitle = data.ui.changelog?.title ?? "Changelog";
 const changelogDescription =
   data.ui.changelog?.description ??
   "Product updates, new features, and fixes from every release.";
-const pageTitle = data.config.title + " " + changelogTitle;
+// The layout suffixes "- {site title}" itself, so the page title is just the
+// changelog's own name — prefixing the site title too would double it
+// ("Acme Changelog - Acme").
+const pageTitle = changelogTitle;
 
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
@@ -2161,11 +2233,13 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
   indexable={true}
-  ogImage={null}
+  ogImage={ogImage}
+  ogGenerated={Boolean(ogImage)}
   x={data.config.x}
   canonical={canonical}
   exportPdf={${options.exportPdf}}
   exportEpub={${options.exportEpub}}
+  openInChat={data.config.openInChat}
   feeds={data.feeds}
   discovery={data.config.discovery}
   siteUrl={data.config.site}

package/src/components/content/AccordionItem.astro

@@ -121,6 +121,10 @@ const accordionId = id ?? componentSlug(title);
     };
 
     window.addEventListener("hashchange", openHashAccordion);
+    // Client-router swaps replace the body with fresh server-rendered
+    // accordions (duplicate ids and all), so the dedupe + hash-open pass has
+    // to run again for each new page.
+    document.addEventListener("astro:after-swap", init);
     if (document.readyState === "loading") {
       document.addEventListener("DOMContentLoaded", init, { once: true });
     } else {

package/src/components/content/Update.astro

@@ -110,6 +110,9 @@ const tagList = Array.isArray(tags) ? tags : tags ? [tags] : [];
       }
     };
 
+    // Client-router swaps replace the body with fresh server-rendered entries
+    // (duplicate ids and all), so the dedupe has to run again for each page.
+    document.addEventListener("astro:after-swap", dedupeUpdateIds);
     if (document.readyState === "loading") {
       document.addEventListener("DOMContentLoaded", dedupeUpdateIds, {
         once: true,

package/src/components/islands/AskAI.astro

@@ -44,12 +44,18 @@ const icons = {
 };
 ---
 
+{/* transition:persist carries the island — and with it the conversation,
+    the draft input, and the open panel — across client-router navigations
+    instead of remounting it empty on every page. The island re-portals its
+    panel and re-stamps the body push attribute itself on astro:after-swap
+    (see ask-ai.tsx), since the swap replaces <body> wholesale. */}
 <AskAI
   client:load
   endpoint={endpoint}
   icons={icons}
   strings={strings}
   suggestions={items}
+  transition:persist="blume-ask"
 />
 
 <style is:global>

package/src/components/islands/ask-ai.tsx

@@ -144,7 +144,6 @@ const AskAI = ({
   // Merge per key (not `strings ?? …`) so a dictionary from a stale snapshot
   // that predates newer keys still resolves every label to its English default.
   const t = { ...DEFAULT_ASK, ...strings };
-  const [mounted, setMounted] = useState(false);
   const [open, setOpen] = useState(false);
   const [input, setInput] = useState("");
   // The streaming client — request shaping, optimistic assistant bubble,
@@ -164,10 +163,25 @@ const AskAI = ({
   // Where focus came from when the panel opened, restored on close.
   const returnFocusRef = useRef<HTMLElement | null>(null);
 
-  // Portal target (document.body) only exists after mount; guards SSR. The
-  // one-time false→true flip is deliberate, so the initial `false` is required.
-  // oxlint-disable-next-line react/react-compiler, react-doctor/no-initialize-state -- deliberate post-mount portal guard
-  useEffect(() => setMounted(true), []);
+  // Where the panel portals to — the CURRENT document.body, held as state.
+  // Null until mount (guards SSR), then refreshed on every client-router swap:
+  // the island rides across navigations via transition:persist, but each swap
+  // installs a NEW <body>, discarding the portaled panel with the old one and
+  // resetting the `data-blume-ask` push attribute to the incoming page's
+  // server-rendered set. Reading document.body inline in render would NOT
+  // recover from that — it isn't a reactive value, so the memoized portal
+  // keeps its stale (detached) container. State identity is what re-anchors
+  // the portal and re-runs the body-scoped effects below.
+  const [portalTarget, setPortalTarget] = useState<HTMLElement | null>(null);
+  useEffect(() => {
+    // The initial null→body flip is deliberate (there is no body during SSR);
+    // it is the same one-time post-mount cascade the old `mounted` flag had.
+    // oxlint-disable-next-line react/react-compiler -- deliberate post-mount portal-target initialization
+    setPortalTarget(document.body);
+    const onSwap = () => setPortalTarget(document.body);
+    document.addEventListener("astro:after-swap", onSwap);
+    return () => document.removeEventListener("astro:after-swap", onSwap);
+  }, []);
 
   // The search modal forwards its query so "Ask AI: <query>" carries straight in.
   useEffect(() => {
@@ -239,6 +253,18 @@ const AskAI = ({
     };
   }, [open]);
 
+  // Re-stamp the push attribute after a swap while the panel is open — the new
+  // body arrives without it. Deliberately separate from the effect above: a
+  // navigation must not re-run the focus handling and yank focus out of the
+  // page the reader just moved to.
+  useEffect(() => {
+    // document.body (not portalTarget) so the compiler doesn't flag a state
+    // mutation; by the time this runs for a swap, they are the same element.
+    if (open && portalTarget) {
+      document.body.dataset.blumeAsk = "open";
+    }
+  }, [open, portalTarget]);
+
   // Below the desktop dock breakpoint the open panel is a full-width overlay,
   // so Tab must not escape into the page it covers: every other child of
   // <body> (the panel portals to body) turns inert until close. The desktop
@@ -299,12 +325,16 @@ const AskAI = ({
       media.removeEventListener("change", apply);
       release();
     };
-  }, [open]);
+    // portalTarget: each swap installs a new <body>, so the sweep and its
+    // observer must re-run against the new children (the old ones are
+    // detached).
+  }, [open, portalTarget]);
 
-  // Keep the newest message in view as it streams in.
+  // Keep the newest message in view as it streams in — and after a swap, when
+  // the re-portaled panel's scroll container is reborn at the top.
   useEffect(() => {
     scrollRef.current?.scrollTo({ top: scrollRef.current.scrollHeight });
-  }, [messages]);
+  }, [messages, portalTarget]);
 
   const runQuestion = (raw: string) => {
     const question = raw.trim();
@@ -501,7 +531,7 @@ const AskAI = ({
       >
         <Glyph path={icons.chat} size={18} />
       </button>
-      {mounted && createPortal(panel, document.body)}
+      {portalTarget && createPortal(panel, portalTarget)}
     </>
   );
 };

package/src/components/layout/Analytics.astro

@@ -33,8 +33,16 @@ const vercelEnabled = enabled && analytics?.vercel === true;
 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_LOADER}posthog.init(${JSON.stringify(posthog.key)},{api_host:${JSON.stringify(posthog.host ?? "https://us.i.posthog.com")}});${POSTHOG_SPA_PAGEVIEWS}`
   : null;
 
 // Custom scripts: any other provider. Each is either external (`src`) or inline

package/src/components/layout/Favicon.astro

@@ -1,23 +1,44 @@
 ---
+import type { BlumeFavicon } from "../../core/data.ts";
 import { withBase } from "../islands/base-path.ts";
 // Emits the icon <link>s for the document <head>: the favicon (rel="icon") and,
 // when the project ships one, the Apple touch icon (rel="apple-touch-icon").
 // Each href is either a URL to a file the project ships in public/, or a data
 // URI (a root-level icon, or the bundled Blume favicon default) — both resolved
 // by the generator's resolveFavicon / resolveAppleIcon.
+//
+// When the favicon has a dark variant, three links cover every consumer class:
+// an unconditional light link first (bots and services that take the first
+// rel="icon" and ignore `media`, and UAs that honor `media` but match neither
+// color-scheme query), then the media-gated pair. Browsers that honor `media`
+// take the last matching link — the dark link in dark mode, the trailing light
+// link in light mode — and browsers that ignore `media` but take the last link
+// also land on light, the safe default against light browser chrome.
 interface Props {
-  favicon?: {
-    href: string;
-    type?: string;
-  } | null;
-  appleIcon?: {
-    href: string;
-    type?: string;
-  } | null;
+  favicon?: BlumeFavicon | null;
+  appleIcon?: BlumeFavicon | null;
 }
 
 const { appleIcon, favicon } = Astro.props;
 ---
 
 {favicon && <link href={withBase(favicon.href)} rel="icon" type={favicon.type} />}
+{
+  favicon?.dark && (
+    <>
+      <link
+        href={withBase(favicon.dark.href)}
+        media="(prefers-color-scheme: dark)"
+        rel="icon"
+        type={favicon.dark.type}
+      />
+      <link
+        href={withBase(favicon.href)}
+        media="(prefers-color-scheme: light)"
+        rel="icon"
+        type={favicon.type}
+      />
+    </>
+  )
+}
 {appleIcon && <link href={withBase(appleIcon.href)} rel="apple-touch-icon" />}

package/src/components/layout/Fonts.astro

@@ -1,14 +1,34 @@
 ---
 // Emits the optimized @font-face declarations + preload links for each
 // configured font (Astro's Fonts API). Renders nothing when no fonts are set;
-// the CSS variables match the astro.config `fonts:` entries.
+// the CSS variables match the astro.config `fonts:` entries. Preloads are
+// narrowed to the weights above-the-fold text renders in (see
+// `theme/fonts.ts`); a bare string entry — an older generated template — keeps
+// the previous preload-everything behavior.
 import { Font } from "astro:assets";
+import type { FontHead } from "../../theme/fonts.ts";
 
 interface Props {
-  cssVars: string[];
+  cssVars: (string | FontHead)[];
 }
 
 const { cssVars } = Astro.props;
+
+const entries = cssVars.map((value) =>
+  typeof value === "string"
+    ? { cssVariable: value, preload: true as const }
+    : {
+        cssVariable: value.cssVariable,
+        preload: value.preloadWeights.map((weight) => ({
+          style: "normal" as const,
+          weight,
+        })),
+      }
+);
 ---
 
-{cssVars.map((cssVar) => <Font cssVariable={cssVar} preload />)}
+{
+  entries.map((entry) => (
+    <Font cssVariable={entry.cssVariable} preload={entry.preload} />
+  ))
+}

package/src/components/layout/Header.astro

@@ -14,7 +14,7 @@ import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
 import LanguageSwitcher from "./LanguageSwitcher.astro";
 import Logo from "./Logo.astro";
-import { activeTabForRoute } from "./nav-utils.ts";
+import { currentTabForRoute } from "./nav-utils.ts";
 import NavSelector from "./NavSelector.astro";
 import { resolveSlot } from "./overrides.ts";
 import Search from "./Search.astro";
@@ -108,7 +108,7 @@ const SearchSlot = resolveSlot(layout.Search, Search);
 // PageLayout) it's a tabs-only drawer the layout renders — so the button is also
 // needed whenever there are tabs to reveal.
 const showNavToggle = hasDrawer && (hasSidebar || navigation.tabs.length > 0);
-const activeTab = activeTabForRoute(navigation.tabs, route);
+const activeTab = currentTabForRoute(navigation.tabs, route, navigation.root);
 // Where the header's inline tab bar appears. With a sidebar it shares the `md`
 // breakpoint with the docs drawer; without one, the tabs-only drawer is the sole
 // mobile nav below `lg`, so the inline tabs wait until `lg` to avoid duplicating

package/src/components/layout/NavSelector.astro

@@ -6,7 +6,7 @@ import { withBase } from "../islands/base-path.ts";
 // <details>/<summary> like the language switcher.
 import type { NavSelector } from "../../core/types.ts";
 import Icon from "../Icon.astro";
-import { isUnderPath } from "./nav-utils.ts";
+import { isUnderPath } from "../../core/navigation.ts";
 
 interface Props {
   selector: NavSelector;