blume 1.7.0 → 1.7.2

package/src/astro/templates.ts

@@ -9,7 +9,7 @@ import type { AskBackend } from "../ai/ask.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import { TOC_HIDDEN_KEY } from "../core/heading-markers.ts";
-import type { ResolvedConfig } from "../core/schema.ts";
+import type { AskReasoning, ResolvedConfig } from "../core/schema.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.ts";
@@ -1040,12 +1040,58 @@ const ASK_FALLBACK_PROMPT =
 
 /** The `ai.ask` values the generated endpoint has to carry with it. */
 export interface AskEndpointOptions {
+  /** `ai.ask.cors` — origins allowed to call the route from another site. */
+  cors?: string[];
   /** `ai.ask.instructions` — extra system-prompt text. */
   instructions?: string;
+  /**
+   * `ai.ask.reasoning` — how much the model reasons before answering, sent
+   * as the backend's own reasoning-effort control.
+   */
+  reasoning?: AskReasoning;
   /** `ai.ask.retrieval` — how much documentation each question carries. */
   retrieval?: AskRetrievalOptions;
 }
 
+/** The pieces `askEndpointTemplate` splices in for `ai.ask.cors`. */
+interface AskCorsTemplate {
+  /** The route's closing token: `});` when the POST is wrapped, `};` otherwise. */
+  close: string;
+  /** The runtime import, when anything is listed. */
+  imports: string[];
+  /** The opening of `export const POST: APIRoute = `. */
+  open: string;
+  /** The allow list and the `OPTIONS` handler, spliced after the provider setup. */
+  setup: string;
+}
+
+/**
+ * `ai.ask.cors`: a browser only lets another origin read the stream when the
+ * response names that origin, and a JSON POST preflights first, so the route
+ * answers `OPTIONS` and wraps the `POST` in `withCors`, which stamps a listed
+ * origin on every response — errors included, so a cross-origin caller can
+ * tell a 400 from a 500 — without each `return` having to remember to.
+ * Unlisted origins get no allow header and stay subject to the same-origin
+ * rule. Left out entirely when nothing is listed, so the default route is
+ * unchanged.
+ */
+const askCorsTemplate = (cors: readonly string[] = []): AskCorsTemplate =>
+  cors.length > 0
+    ? {
+        close: "});",
+        imports: [
+          'import { preflightResponse, withCors } from "blume/ai/cors.ts";',
+        ],
+        open: "withCors(ALLOWED_ORIGINS, async ({ request }) => {",
+        setup: `
+const ALLOWED_ORIGINS = ${JSON.stringify(cors)};
+
+export const OPTIONS: APIRoute = ({ request }) =>
+  preflightResponse(request, ALLOWED_ORIGINS);
+`,
+      }
+    : { close: "};", imports: [], open: "async ({ request }) => {", setup: "" };
+
 /**
  * Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`).
  *
@@ -1053,15 +1099,24 @@ export interface AskEndpointOptions {
  * built-in prompt on every path: the grounded prompt via `createAskContext`,
  * 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.
+ * sizes retrieval. `options.reasoning` (the `ai.ask.reasoning` config)
+ * reaches the model call on both paths. `options.cors` (the `ai.ask.cors`
+ * config) adds a preflight handler and wraps the `POST` so every response
+ * names a listed origin. All four travel in one options object so a new call
+ * site can't silently drop one of them.
  */
 export const askEndpointTemplate = (
   backend: AskBackend,
   grounded: boolean,
   options?: AskEndpointOptions
 ): string => {
-  const instructions = options?.instructions;
+  const { instructions, reasoning, retrieval } = options ?? {};
+  // `ai.ask.reasoning`. The gateway and OpenAI-compatible providers take it
+  // from `streamText`'s top-level `reasoning` (the gateway maps it to the
+  // model's own control, the OpenAI-compatible provider sends it as
+  // `reasoning_effort`). OpenRouter's provider ignores that call option and
+  // only reads its own model setting, so there the level rides on the model
+  // as `reasoning.effort`. Omitted keeps the provider default on every path.
   const fallbackPrompt = instructions
     ? `${ASK_FALLBACK_PROMPT}\n\n${instructions}`
     : ASK_FALLBACK_PROMPT;
@@ -1080,24 +1135,34 @@ export const askEndpointTemplate = (
   ];
   let setup = "";
   let modelExpr = JSON.stringify(backend.model);
+  // `ai.ask.headers`, inlined as literals: every provider factory below takes
+  // the same `headers` option, so one line serves all three.
+  const headersField = backend.headers
+    ? `\n  headers: ${JSON.stringify(backend.headers)},`
+    : "";
   if (backend.kind === "gateway") {
-    setup = `\nconst gateway = createGateway({ apiKey: getSecret("AI_GATEWAY_API_KEY") });\n`;
+    setup = `\nconst gateway = createGateway({
+  apiKey: getSecret("AI_GATEWAY_API_KEY"),${headersField}
+});\n`;
     modelExpr = `gateway(${JSON.stringify(backend.model)})`;
   } else if (backend.kind === "openrouter") {
     imports.push(
       'import { createOpenRouter } from "@openrouter/ai-sdk-provider";'
     );
-    setup = `\nconst openrouter = createOpenRouter({ apiKey: getSecret(${JSON.stringify(
-      backend.apiKeyEnv
-    )}) });\n`;
-    modelExpr = `openrouter(${JSON.stringify(backend.model)})`;
+    setup = `\nconst openrouter = createOpenRouter({
+  apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),${headersField}
+});\n`;
+    const settings = reasoning
+      ? `, { reasoning: { effort: ${JSON.stringify(reasoning)} } }`
+      : "";
+    modelExpr = `openrouter(${JSON.stringify(backend.model)}${settings})`;
   } else if (backend.kind === "openai-compatible") {
     imports.push(
       'import { createOpenAICompatible } from "@ai-sdk/openai-compatible";'
     );
     setup = `\nconst provider = createOpenAICompatible({
   apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),
-  baseURL: ${JSON.stringify(backend.baseUrl)},
+  baseURL: ${JSON.stringify(backend.baseUrl)},${headersField}
   name: ${JSON.stringify(backend.name)},
 });\n`;
     modelExpr = `provider(${JSON.stringify(backend.model)})`;
@@ -1113,13 +1178,15 @@ export const askEndpointTemplate = (
     if (instructions) {
       groundFields.push(`instructions: ${JSON.stringify(instructions)}`);
     }
-    if (options?.retrieval) {
-      groundFields.push(`retrieval: ${JSON.stringify(options.retrieval)}`);
+    if (retrieval) {
+      groundFields.push(`retrieval: ${JSON.stringify(retrieval)}`);
     }
     const groundOptions =
       groundFields.length > 0 ? `, { ${groundFields.join(", ")} }` : "";
     setup += `\nconst ground = createAskContext(askData${groundOptions});\n`;
   }
+  const cors = askCorsTemplate(options?.cors);
+  imports.push(...cors.imports);
   // Validate the client-supplied body and cap its size. The endpoint is
   // unauthenticated, so bounding message count/length limits how much a caller
   // can spend against the model per request, and restricting roles to
@@ -1176,24 +1243,29 @@ export const askEndpointTemplate = (
   const onError = `      onError({ error }) {
         console.error("Ask AI provider error:", error);
       },`;
+  // The `streamText` argument list, built once so the grounded and plain
+  // paths can't drift: they differ only in where the instructions come from.
+  const streamFields = [
+    `model: ${modelExpr}`,
+    grounded
+      ? "instructions"
+      : `instructions:\n        ${JSON.stringify(fallbackPrompt)}`,
+    "messages",
+  ];
+  if (reasoning && backend.kind !== "openrouter") {
+    streamFields.push(`reasoning: ${JSON.stringify(reasoning)}`);
+  }
+  const call = `    const result = streamText({
+      ${streamFields.join(",\n      ")},
+${onError}
+    });`;
   const stream = grounded
     ? `    const instructions =
       (await ground(messages, body.page)) ??
       ${JSON.stringify(fallbackPrompt)};
-    const result = streamText({
-      model: ${modelExpr},
-      instructions,
-      messages,
-${onError}
-    });`
-    : `    const result = streamText({
-      model: ${modelExpr},
-      instructions:
-        ${JSON.stringify(fallbackPrompt)},
-      messages,
-${onError}
-    });`;
-  const handler = `export const POST: APIRoute = async ({ request }) => {
+${call}`
+    : call;
+  const handler = `export const POST: APIRoute = ${cors.open}
 ${validate}
 ${keyCheck}
   try {
@@ -1202,12 +1274,12 @@ ${stream}
   } catch {
     return new Response("Failed to generate a response.", { status: 500 });
   }
-};`;
+${cors.close}`;
   return `// Generated by Blume. Do not edit.
 ${imports.join("\n")}
 
 export const prerender = false;
-${setup}
+${setup}${cors.setup}
 ${handler}
 `;
 };
@@ -1692,15 +1764,22 @@ export function GET({ props }: { props: { section: string } }) {
  * every collapsed section on every page. Ids are `navGroupIds` over the full
  * tree, the same ids the pages' sidebars use; the `version`/`locale`
  * segments pick the navigation variant (`current`/`default` for the
- * unversioned, unlocalized tree). Rendered with no current route — a
- * section that isn't on the active path has no active row by definition.
+ * unversioned, unlocalized tree, and `default` again for the default locale
+ * while its URL prefix is hidden: Astro's i18n routing 404s a page URL that
+ * carries the default locale's code as a segment). Rendered with no current
+ * route — a section that isn't on the active path has no active row by
+ * definition.
  */
 export const navFragmentTemplate = (): string =>
   `---
 // Generated by Blume. Do not edit.
 import NavTree from "blume/components/layout/NavTree.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
-import { navGroupIds, navVariants } from "blume/components/layout/nav-utils.ts";
+import {
+  hiddenDefaultLocale,
+  navGroupIds,
+  navVariants,
+} from "blume/components/layout/nav-utils.ts";
 import type { NavNode } from "blume/core/types.ts";
 import data from "blume:data";
 
@@ -1711,15 +1790,16 @@ export const partial = true;
 // Only imports are in scope here (Astro hoists getStaticPaths), which is why
 // the variant walk lives in nav-utils.
 export function getStaticPaths() {
-  return navVariants(data).flatMap(({ locale, navigation, version }) =>
-    [...navGroupIds(navigation.sidebar)]
-      .filter(([node]) => (node.display ?? "flat") !== "flat")
-      .map(([, id]) => ({ params: { id, locale, version } }))
+  return navVariants(data, hiddenDefaultLocale(data.config.i18n)).flatMap(
+    ({ locale, navigation, version }) =>
+      [...navGroupIds(navigation.sidebar)]
+        .filter(([node]) => (node.display ?? "flat") !== "flat")
+        .map(([, id]) => ({ params: { id, locale, version } }))
   );
 }
 
 const { id, locale, version } = Astro.params;
-const variant = navVariants(data).find(
+const variant = navVariants(data, hiddenDefaultLocale(data.config.i18n)).find(
   (entry) => entry.version === version && entry.locale === locale
 );
 const ids = variant
@@ -1933,37 +2013,22 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
 </ReferenceLayout>
 `;
 
-export const catchAllPageTemplate = (options: {
-  exportEpub: boolean;
-  exportPdf: boolean;
-  mathEnabled: boolean;
-  /**
-   * Whether the sidebar defers collapsed sections to prerendered fragments
-   * (see `navFragmentTemplate`); true when some group renders as a
-   * disclosure or a drill-in panel.
-   */
-  navFragments?: boolean;
-  /** Serialize the island-hooks snapshot; only needed when React is enabled. */
-  needsReact: boolean;
-}): string => {
-  const mathImport = options.mathEnabled
+/**
+ * The component map every rendered entry body receives via
+ * `<Content components={...} />`: Blume's content components, `<Math>` when
+ * math is enabled, the island wrappers, and the user's `mdxComponents`
+ * overrides. Shared by the catch-all page and the changelog index so a
+ * `:::` directive (compiled to `<Callout>`) or an explicit `<Steps>` renders
+ * wherever an entry is rendered — an MDX body throws "Expected component
+ * `X` to be defined" the moment a page renders it without this map.
+ */
+const contentComponentsSource = (mathEnabled: boolean) => {
+  const mathImport = mathEnabled
     ? 'import Math from "blume/components/content/Math.astro";\n'
     : "";
-  const mathEntry = options.mathEnabled ? "Math,\n  " : "";
-  // The island-hooks snapshot (config + navigation + page) for `blume/hooks`.
-  const clientData = options.needsReact
-    ? "\n  clientData={{ config: data.config, navigation, page: { route, title: seo.title ?? title } }}"
-    : "";
-
-  return `---
-// Generated by Blume. Do not edit.
-import { getEntry, render } from "astro:content";
-import type { CollectionKey } from "astro:content";
-import RootLayout from "blume/components/layout/RootLayout.astro";
-import { withBase } from "blume/components/islands/base-path.ts";
-import { stripBasePath, withBasePath } from "blume/core/base-path.ts";
-import { resolveSlot } from "blume/components/layout/overrides.ts";
-import Accordion from "blume/components/content/Accordion.astro";
+  const mathEntry = mathEnabled ? "Math,\n  " : "";
+  return {
+    imports: `import Accordion from "blume/components/content/Accordion.astro";
 import AccordionItem from "blume/components/content/AccordionItem.astro";
 import AutoTypeTable from "blume/components/content/AutoTypeTable.astro";
 import Badge from "blume/components/content/Badge.astro";
@@ -2003,19 +2068,8 @@ import ApiOverview from "blume/components/openapi/ApiOverview.astro";
 import ApiTagOperations from "blume/components/openapi/ApiTagOperations.astro";
 import Operation from "blume/components/openapi/Operation.astro";
 ${mathImport}import { mdxComponents as userMdx, layoutOverrides } from "../generated/components.ts";
-import { islandComponents } from "../generated/islands.ts";
-import data from "blume:data";
-
-const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
-const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
-
-// Docs content is file-based and always prerendered, even in server output
-// (where only endpoints like /api/ask render on demand). Without this, server
-// builds would render this route on demand and ignore getStaticPaths, leaving
-// the entry id undefined.
-export const prerender = true;
-
-const components = {
+import { islandComponents } from "../generated/islands.ts";`,
+    map: `{
   Accordion,
   AccordionItem,
   ApiOverview,
@@ -2052,8 +2106,52 @@ const components = {
   YouTube,
   ${mathEntry}...islandComponents,
   ...userMdx,
+}`,
+  };
 };
 
+export const catchAllPageTemplate = (options: {
+  exportEpub: boolean;
+  exportPdf: boolean;
+  mathEnabled: boolean;
+  /**
+   * Whether the sidebar defers collapsed sections to prerendered fragments
+   * (see `navFragmentTemplate`); true when some group renders as a
+   * disclosure or a drill-in panel.
+   */
+  navFragments?: boolean;
+  /** Serialize the island-hooks snapshot; only needed when React is enabled. */
+  needsReact: boolean;
+}): string => {
+  const { imports: componentImports, map: componentMap } =
+    contentComponentsSource(options.mathEnabled);
+  // The island-hooks snapshot (config + navigation + page) for `blume/hooks`.
+  const clientData = options.needsReact
+    ? "\n  clientData={{ config: data.config, navigation, page: { route, title: seo.title ?? title } }}"
+    : "";
+
+  return `---
+// Generated by Blume. Do not edit.
+import { getEntry, render } from "astro:content";
+import type { CollectionKey } from "astro:content";
+import RootLayout from "blume/components/layout/RootLayout.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
+import { stripBasePath, withBasePath } from "blume/core/base-path.ts";
+import { resolveSlot } from "blume/components/layout/overrides.ts";
+${componentImports}
+import data from "blume:data";
+
+const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
+const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
+
+// Docs content is file-based and always prerendered, even in server output
+// (where only endpoints like /api/ask render on demand). Without this, server
+// builds would render this route on demand and ignore getStaticPaths, leaving
+// the entry id undefined.
+export const prerender = true;
+
+const components = ${componentMap};
+
 export function getStaticPaths() {
   return data.routes.map((route) => ({
     params: { slug: route.path === "/" ? undefined : route.path.slice(1) },
@@ -2324,7 +2422,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   exportEpub={${options.exportEpub}}${
     options.navFragments
       ? `
-  navFragmentBase={withBase(\`/blume-nav/\${version || "current"}/\${i18n ? locale : "default"}\`)}`
+  navFragmentBase={withBase(\`/blume-nav/\${version || "current"}/\${i18n && localePrefix(locale) ? locale : "default"}\`)}`
       : ""
   }
   openInChat={data.config.openInChat}
@@ -2355,6 +2453,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 export const changelogIndexTemplate = (options: {
   exportEpub: boolean;
   exportPdf: boolean;
+  mathEnabled: boolean;
   /** Serialize the island-hooks snapshot; only needed when React is enabled. */
   needsReact: boolean;
   /** Whether a `staged` collection exists (non-filesystem changelog sources). */
@@ -2368,6 +2467,8 @@ export const changelogIndexTemplate = (options: {
   const stagedSpread = options.staged
     ? '\n  ...(await getCollection("staged")),'
     : "";
+  const { imports: componentImports, map: componentMap } =
+    contentComponentsSource(options.mathEnabled);
 
   return `---
 // Generated by Blume. Do not edit.
@@ -2377,11 +2478,19 @@ import Update from "blume/components/content/Update.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { resolveDateFormatOptions } from "blume/core/date-format.ts";
-import { layoutOverrides } from "../generated/components.ts";
+${componentImports}
 import data from "blume:data";
 
+const Color = Object.assign(ColorRoot, { Item: ColorItem, Row: ColorRow });
+const Tree = Object.assign(TreeRoot, { File: TreeFile, Folder: TreeFolder });
+
 export const prerender = true;
 
+// Entry bodies are MDX rendered outside the catch-all, so they need the same
+// component map: a \`:::\` callout or \`<Steps>\` in a release note otherwise
+// throws "Expected component ... to be defined" at build time.
+const components = ${componentMap};
+
 const entryDate = (entry: {
   data: { date?: string | null; changelog?: { date?: string | null } | null };
 }) => entry.data.date ?? entry.data.changelog?.date ?? null;
@@ -2580,7 +2689,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
       >
         {majorGroups[0].items.map(({ Content, href, id, label, date, tags }) => (
           <Update description={date} href={href} id={id} label={label} tags={tags}>
-            <Content />
+            <Content components={components} />
           </Update>
         ))}
         {majorGroups.slice(1).map((group) => (
@@ -2591,7 +2700,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
           >
             {group.items.map(({ Content, href, id, label, date, tags }) => (
               <Update description={date} href={href} id={id} label={label} tags={tags}>
-                <Content />
+                <Content components={components} />
               </Update>
             ))}
           </section>
@@ -2611,7 +2720,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
       <div class="not-prose mt-8">
         {items.map(({ Content, href, id, label, date, tags }) => (
           <Update description={date} href={href} id={id} label={label} tags={tags}>
-            <Content />
+            <Content components={components} />
           </Update>
         ))}
       </div>

package/src/components/content/YouTube.astro

@@ -20,7 +20,7 @@ const src = videoId ? youtubeEmbedUrl(videoId, { start }) : null;
 
 {
   src && (
-    <div class="not-prose my-6 aspect-video overflow-hidden rounded-blume border border-border bg-muted/30">
+    <div class="not-prose my-6 aspect-video w-full overflow-hidden rounded-blume border border-border bg-muted/30">
       <iframe
         allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
         allowfullscreen

package/src/components/layout/Header.astro

@@ -150,7 +150,7 @@ const ctaClass = [
 // so the offset can't drift while open, and re-measure when a banner dismiss or
 // a resize/rotation moves the header. Crossing into the desktop breakpoint
 // (64rem, Tailwind `lg`) closes the drawer so the scroll lock can't outlive it.
-const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-blume-header]");if(h){document.documentElement.style.setProperty("--blume-drawer-top",h.getBoundingClientRect().bottom+"px");}};document.addEventListener("click",(e)=>{const t=e.target.closest("[data-blume-theme-toggle]");if(t){const d=document.documentElement;const next=d.dataset.theme==="dark"?"light":"dark";const s=document.createElement("style");s.appendChild(document.createTextNode("*,*::before,*::after{transition:none!important}"));document.head.appendChild(s);d.dataset.theme=next;localStorage.setItem("blume-theme",next);window.getComputedStyle(d).opacity;setTimeout(()=>document.head.removeChild(s),1);}const n=e.target.closest("[data-blume-nav-toggle]");if(n){const d=document.documentElement;const open=d.toggleAttribute("data-blume-nav-open");if(open){dr();}d.style.overflow=open?"hidden":"";}const b=e.target.closest("[data-blume-banner-dismiss]");if(b){const bar=b.closest("[data-blume-banner]");const k=bar&&bar.getAttribute("data-banner-key");if(k){localStorage.setItem("blume-banner:"+k,"1");}document.documentElement.setAttribute("data-blume-banner-hidden","");requestAnimationFrame(dr);}});addEventListener("resize",()=>{const d=document.documentElement;if(!d.hasAttribute("data-blume-nav-open")){return;}if(matchMedia("(min-width:64rem)").matches){d.removeAttribute("data-blume-nav-open");d.style.overflow="";}else{dr();}});})();`;
+const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-blume-header]");if(h){document.documentElement.style.setProperty("--blume-drawer-top",h.getBoundingClientRect().bottom+"px");}};document.addEventListener("click",(e)=>{const t=e.target.closest("[data-blume-theme-toggle]");if(t){const d=document.documentElement;const next=d.dataset.theme==="dark"?"light":"dark";const s=document.createElement("style");s.appendChild(document.createTextNode("*,*::before,*::after{transition:none!important}"));document.head.appendChild(s);d.dataset.theme=next;localStorage.setItem("blume-theme",next);window.getComputedStyle(d).opacity;setTimeout(()=>document.head.removeChild(s),1);}const n=e.target.closest("[data-blume-nav-toggle]");if(n){const d=document.documentElement;const open=d.toggleAttribute("data-blume-nav-open");if(open){dr();}}const b=e.target.closest("[data-blume-banner-dismiss]");if(b){const bar=b.closest("[data-blume-banner]");const k=bar&&bar.getAttribute("data-banner-key");if(k){localStorage.setItem("blume-banner:"+k,"1");}document.documentElement.setAttribute("data-blume-banner-hidden","");requestAnimationFrame(dr);}});addEventListener("resize",()=>{const d=document.documentElement;if(!d.hasAttribute("data-blume-nav-open")){return;}if(matchMedia("(min-width:64rem)").matches){d.removeAttribute("data-blume-nav-open");}else{dr();}});})();`;
 ---
 
 <header