blume 1.7.0 → 1.7.2

package/src/components/layout/NavTree.astro

@@ -35,7 +35,10 @@ interface Props {
   /**
    * Stable ids for the full sidebar's groups (`navGroupIds`), so panel and
    * fragment ids match across the scoped views the layout renders. Absent,
-   * ids fall back to positions within this render.
+   * ids fall back to positions within this render. A group missing from the
+   * map exists only in this render — a container the tab scoping rebuilt
+   * without a nested tab section — so no fragment can serve it: it renders
+   * in full instead of being deferred.
    */
   ids?: Map<NavNode, string>;
   /**
@@ -63,9 +66,12 @@ const {
 const idOf = (node: NavNode, positional: string): string =>
   ids?.get(node) ?? positional;
 
-/** The fragment a deferred section loads from, when sections are deferred. */
-const fragmentFor = (id: string): string | undefined =>
-  fragmentBase ? `${fragmentBase}/${id}` : undefined;
+/**
+ * The fragment a group's section loads from, when sections are deferred and
+ * the group is one the fragments know (in `ids`, or `ids` is absent).
+ */
+const fragmentFor = (node: NavNode, id: string): string | undefined =>
+  fragmentBase && (ids?.has(node) ?? true) ? `${fragmentBase}/${id}` : undefined;
 
 // 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
@@ -150,66 +156,56 @@ const initialId =
           strings={n}
         />
       </div>
-      {panels.map((panel) => (
-        <div
-          data-nav-depth={panel.depth}
-          data-nav-panel={panel.id}
-          data-nav-src={panel.active ? undefined : fragmentFor(panel.id)}
-          hidden={panel.id !== initialId}
-        >
-          {/* 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">
+      {panels.map((panel) => {
+        const src = panel.active ? undefined : fragmentFor(panel.node, panel.id);
+        return (
+          <div
+            data-nav-depth={panel.depth}
+            data-nav-panel={panel.id}
+            data-nav-src={src}
+            hidden={panel.id !== initialId}
+          >
+            {/* 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-[0.65rem] 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 rounded-[0.65rem] px-1 py-1 font-semibold text-foreground text-sm transition-colors hover:bg-muted"
+                  href={withBase(panel.route)}
+                >
+                  {panel.label}
+                </a>
+              </div>
+            ) : (
               <button
-                aria-label={n.back}
-                class="-ml-1 flex shrink-0 items-center justify-center self-stretch rounded-[0.65rem] px-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+                aria-label={`${n.back}: ${panel.label}`}
+                class="-ml-1 mb-3 flex w-full items-center gap-1.5 rounded-[0.65rem] p-1 text-left font-semibold text-foreground text-sm transition-colors hover:bg-muted"
                 data-nav-back={panel.parentId}
                 type="button"
               >
-                <Icon class="rtl:-scale-x-100" name="arrow-left" size={16} />
+                <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>
-              <a
-                aria-current={panel.route === currentRoute ? "page" : undefined}
-                class="flex-1 truncate rounded-[0.65rem] px-1 py-1 font-semibold text-foreground text-sm transition-colors hover:bg-muted"
-                href={withBase(panel.route)}
-              >
-                {panel.label}
-              </a>
-            </div>
-          ) : (
-            <button
-              aria-label={`${n.back}: ${panel.label}`}
-              class="-ml-1 mb-3 flex w-full items-center gap-1.5 rounded-[0.65rem] 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>
-          )}
-          {/* An inactive panel's contents are deferred (fetched into this
-              element on drill-in) when fragments are on; otherwise the
-              build-time cache renders them once. */}
-          {panel.active ? (
-            <Self
-              currentRoute={currentRoute}
-              depth={1}
-              fragmentBase={fragmentBase}
-              idPrefix={panel.id}
-              ids={ids}
-              items={panel.children}
-              root={false}
-              strings={n}
-            />
-          ) : fragmentBase ? null : (
-            <NavTreeCache node={panel.node} variant={`${panel.id}|${n.back}|${n.deprecated}`}>
+            )}
+            {/* An inactive panel's contents are deferred (fetched into this
+                element on drill-in) when it has a fragment; otherwise the
+                build-time cache renders them once. */}
+            {panel.active ? (
               <Self
                 currentRoute={currentRoute}
                 depth={1}
@@ -220,10 +216,23 @@ const initialId =
                 root={false}
                 strings={n}
               />
-            </NavTreeCache>
-          )}
-        </div>
-      ))}
+            ) : src ? null : (
+              <NavTreeCache node={panel.node} variant={`${panel.id}|${n.back}|${n.deprecated}`}>
+                <Self
+                  currentRoute={currentRoute}
+                  depth={1}
+                  fragmentBase={fragmentBase}
+                  idPrefix={panel.id}
+                  ids={ids}
+                  items={panel.children}
+                  root={false}
+                  strings={n}
+                />
+              </NavTreeCache>
+            )}
+          </div>
+        );
+      })}
     </blume-nav>
   ) : (
     <ul class="m-0 list-none space-y-px p-0">
@@ -362,11 +371,11 @@ const initialId =
                 </summary>
                 <div
                   class="space-y-0.5 border-border border-l pl-3"
-                  data-nav-src={open ? undefined : fragmentFor(id)}
+                  data-nav-src={open ? undefined : fragmentFor(item, id)}
                 >
                   {/* A closed group's children are deferred (fetched into this
-                      element on first open) when fragments are on. */}
-                  {!open && fragmentBase ? null : active ? (
+                      element on first open) when it has a fragment. */}
+                  {!open && fragmentFor(item, id) ? null : active ? (
                     <Self
                       currentRoute={currentRoute}
                       depth={depth + 1}

package/src/components/layout/RootLayout.astro

@@ -407,7 +407,10 @@ const sidebar = sidebarForRoute(
   navigation.root
 );
 // Stable group ids over the full tree, so the scoped view above names its
-// panels and deferred fragments the same way every other page does.
+// panels and deferred fragments the same way every other page does. A
+// container the scoping rebuilt is not in the map, and NavTree renders it in
+// full rather than deferring it to a fragment that would render the full
+// tree's version.
 const navIds = navGroupIds(navigation.sidebar);
 const activeTab = currentTabForRoute(
   navigation.tabs,

package/src/components/layout/Search.astro

@@ -445,6 +445,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.dialog.addEventListener("keydown", (event) =>
           this.onKeydown(event)
         );
+        this.dialog.addEventListener("close", () => this.unlockPageScroll());
         this.dialog.addEventListener("click", (event) => {
           if (event.target === this.dialog) {
             this.dialog.close();
@@ -454,6 +455,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
       disconnectedCallback() {
         document.removeEventListener("keydown", this.#onDocumentKeydown);
+        this.unlockPageScroll();
       }
 
       isField(target: EventTarget | null): boolean {
@@ -473,6 +475,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           return;
         }
         this.dialog.showModal();
+        this.lockPageScroll();
         this.input.focus();
         this.input.select();
         if (!this.loaded) {
@@ -498,6 +501,14 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.render();
       }
 
+      lockPageScroll() {
+        document.documentElement.setAttribute("data-blume-search-dialog-open", "");
+      }
+
+      unlockPageScroll() {
+        document.documentElement.removeAttribute("data-blume-search-dialog-open");
+      }
+
       onKeydown(event: KeyboardEvent) {
         if (event.key === "ArrowDown") {
           event.preventDefault();

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

@@ -151,6 +151,15 @@ const isTabSection = (node: NavNode, tabPaths: Set<string>): boolean => {
  * instead of duplicating each tab as a sidebar group. A container left empty by
  * this pruning is dropped too, so no bare heading is stranded. The root tab
  * spans everything, so it never removes anything.
+ *
+ * A group with no tab section anywhere beneath it is kept as the same object:
+ * the stable group ids (`navGroupIds`) and the build-time subtree cache are
+ * both keyed by node identity, so a copy would lose its id — its collapsed
+ * fragment was then requested by a positional name no route serves — and
+ * re-render on every page. A container that did lose a section is rebuilt,
+ * so it has no id: the deferred fragments render from the full tree, which
+ * would put the section back, so `NavTree` renders such a container in full
+ * instead (its untouched children still defer by their own ids).
  */
 const withoutTabSections = (
   nodes: NavNode[],
@@ -173,10 +182,15 @@ const withoutTabSections = (
         continue;
       }
       if (item.kind === "group") {
-        // A container left empty by pruning is dropped, so no bare heading is
-        // stranded.
         const children = prune(item.children);
-        if (children.length > 0) {
+        if (
+          children.length === item.children.length &&
+          children.every((child, index) => child === item.children[index])
+        ) {
+          kept.push(item);
+        } else if (children.length > 0) {
+          // A container left empty by pruning is dropped, so no bare heading
+          // is stranded.
           kept.push({ ...item, children });
         }
       } else {
@@ -280,27 +294,45 @@ export interface NavVariant {
   navigation: Navigation;
 }
 
+/**
+ * The locale whose code must not appear as a fragment URL segment: the
+ * default locale while its URL prefix is hidden. Astro's i18n routing 404s any
+ * page URL carrying that locale's code as a segment (it expects the default
+ * locale to be unprefixed), so its trees are keyed `default` instead, the same
+ * way its page routes drop the prefix. `null` when every locale is prefixed
+ * or the site is single-locale.
+ */
+export const hiddenDefaultLocale = (
+  i18n: { defaultLocale: string; hideDefaultLocalePrefix: boolean } | null
+): string | null => (i18n?.hideDefaultLocalePrefix ? i18n.defaultLocale : null);
+
 /**
  * Every navigation tree the runtime data holds — the default, each locale's,
  * and each archived version's per locale — keyed the way the deferred
  * sidebar fragments' URLs are (`/blume-nav/<version>/<locale>/…`). An
  * unlocalized version tree is keyed by `""` in the data; it maps to
- * `default` here.
+ * `default` here, as does the hidden-prefix default locale's (see
+ * `hiddenDefaultLocale`), whose current tree is `data.navigation` already.
  */
-export const navVariants = (data: {
-  navigation: Navigation;
-  navigationByLocale: Record<string, Navigation>;
-  navigationByVersion: Record<string, Record<string, Navigation>>;
-}): NavVariant[] => [
+export const navVariants = (
+  data: {
+    navigation: Navigation;
+    navigationByLocale: Record<string, Navigation>;
+    navigationByVersion: Record<string, Record<string, Navigation>>;
+  },
+  hiddenDefault: string | null = null
+): NavVariant[] => [
   { locale: "default", navigation: data.navigation, version: "current" },
-  ...Object.entries(data.navigationByLocale).map(([locale, navigation]) => ({
-    locale,
-    navigation,
-    version: "current",
-  })),
+  ...Object.entries(data.navigationByLocale)
+    .filter(([locale]) => locale !== hiddenDefault)
+    .map(([locale, navigation]) => ({
+      locale,
+      navigation,
+      version: "current",
+    })),
   ...Object.entries(data.navigationByVersion).flatMap(([version, byLocale]) =>
     Object.entries(byLocale).map(([locale, navigation]) => ({
-      locale: locale || "default",
+      locale: locale && locale !== hiddenDefault ? locale : "default",
       navigation,
       version,
     }))

package/src/core/adapter.ts

@@ -0,0 +1,61 @@
+import { z } from "zod";
+
+/**
+ * The serializable descriptor an integration factory returns — `posthog({ key })`,
+ * `vercel()`, `script({ src })` and their siblings. A descriptor is plain data:
+ * the CLI evaluates `blume.config.ts` once, validates what came back, and
+ * writes it into the generated project's data snapshot as a JSON literal. That
+ * is where the runtime reads it — nothing generated imports the config at
+ * request time — so a descriptor can't carry functions, class instances, or
+ * anything else JSON drops.
+ *
+ * Every consumer reads the descriptor instead of switching on a provider name:
+ * the head emitter and `blume doctor` branch on `kind`, the generated
+ * `.blume/package.json` declares `runtimeDeps`, and the secrets check warns
+ * when an entry of `requiredSecrets` is unset.
+ *
+ * An adapter's verbatim option passthrough is typed as {@link JsonValue} and
+ * validated with `z.json()`, so a function, `undefined`, a bigint, or a
+ * non-finite number fails config validation with a path instead of vanishing
+ * (or throwing) when the snapshot is serialized.
+ */
+export interface AdapterDescriptor<Kind extends string, Options> {
+  /** Which integration this is. */
+  kind: Kind;
+  /** The options the factory was called with, verbatim. */
+  options: Options;
+  /** Env vars the integration reads at runtime; `blume dev`/`build` warn when one is unset. */
+  requiredSecrets: string[];
+  /** Extra packages the generated `.blume/package.json` must declare. */
+  runtimeDeps: string[];
+}
+
+/**
+ * A value JSON can carry unchanged — what an adapter's passthrough options are
+ * typed as. Structurally identical to what `z.json()` accepts.
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+/**
+ * The schema for one descriptor `kind`, validating its `options` with the
+ * adapter's own option schema. Members of a `z.discriminatedUnion("kind", …)`.
+ */
+export const adapterDescriptorSchema = <
+  Kind extends string,
+  Options extends z.ZodType,
+>(
+  kind: Kind,
+  options: Options
+) =>
+  z.strictObject({
+    kind: z.literal(kind),
+    options,
+    requiredSecrets: z.array(z.string()),
+    runtimeDeps: z.array(z.string()),
+  });

package/src/core/config-input.ts

@@ -681,6 +681,8 @@ export interface AskSuggestion {
 /** Backends that can route an Ask AI request. */
 type AskProviderGateway = "gateway" | "openrouter" | "llmgateway";
 type AskProvider = AskProviderGateway | "inkeep" | "openai-compatible";
+/** How much the model reasons before answering (`ai.ask.reasoning`). */
+type AskReasoning = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
 /** How much retrieved documentation each Ask AI question carries. */
 export interface AskRetrievalConfig {
@@ -715,6 +717,18 @@ export interface AskConfig {
    * overrides the built-in preset.
    */
   baseUrl?: string;
+  /**
+   * Origins allowed to call the generated endpoint from another site — a
+   * marketing page that embeds an ask box, for example — or `"*"` to allow
+   * every origin. The route answers preflight requests and names a listed
+   * origin on every response, errors included; every other origin stays
+   * subject to the browser's same-origin rule. Callers must send the body as
+   * JSON with a `content-type: application/json` header, or Astro's cross-site
+   * request check rejects the `POST` before the route runs. Only the generated
+   * route reads this; an external `endpoint` handles its own CORS and can't be
+   * combined with it.
+   */
+  cors?: string[];
   /** Turn Ask AI on. Defaults to `false`. */
   enabled?: boolean;
   /**
@@ -723,6 +737,13 @@ export interface AskConfig {
    * limiting, and streaming. Accepts an absolute URL or root-relative path.
    */
   endpoint?: string;
+  /**
+   * Static request headers sent to the provider on every call — a
+   * caller-identifying header for a shared backend, for example. Values are
+   * written into the generated route as literals, so keep secrets in
+   * `apiKeyEnv` rather than here.
+   */
+  headers?: Record<string, string>;
   /**
    * Extra system-prompt text appended to the built-in instructions — use it
    * for identity, language, or tone. The built-in grounding behavior (answer
@@ -733,6 +754,18 @@ export interface AskConfig {
   model?: string;
   /** Which backend routes the request. Defaults to `gateway`. */
   provider?: AskProvider;
+  /**
+   * How much the model reasons before answering, from `"none"` to `"xhigh"`.
+   * Sent as the backend's own reasoning-effort control: the AI SDK's
+   * `reasoning` option on the gateway, `reasoning.effort` on OpenRouter, and
+   * `reasoning_effort` on OpenAI-compatible endpoints. The model has to
+   * support the level — OpenAI rejects one a model doesn't offer — and the
+   * endpoint has to accept the parameter; Inkeep has no reasoning control,
+   * so the field is rejected there. Omitted keeps the model's default.
+   * `"none"` is the fastest and cheapest for grounded docs Q&A, where the
+   * retrieved excerpts carry the answer.
+   */
+  reasoning?: AskReasoning;
   /**
    * How much documentation each question carries into the model's prompt.
    * Lower values cut time-to-first-token — which dominates on a self-hosted

package/src/core/schema.ts

@@ -767,6 +767,19 @@ const searchConfigSchema = z
     }
   });
 
+/**
+ * The `ai.ask.reasoning` levels: the AI SDK's top-level `reasoning` values
+ * minus `provider-default`, which is what omitting the field means.
+ */
+export const askReasoningLevels = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+
 /** Ask AI backends. `gateway` (default) routes through the Vercel AI Gateway. */
 export const askAiProviders = [
   "gateway",
@@ -872,17 +885,43 @@ const aiConfigSchema = z.strictObject({
       // Base URL of the backend. Required for `openai-compatible` only when no
       // external endpoint is supplied; for named providers it overrides the preset.
       baseUrl: z.url().optional(),
+      // Origins allowed to call the generated `/api/ask` from another site (a
+      // marketing page that embeds an ask box, say), or `"*"` for every
+      // origin. Each URL is reduced to its origin so a trailing slash or path
+      // can't defeat the exact match the route performs. Read by the
+      // generated route only; an external `endpoint` owns its own CORS.
+      cors: z
+        .array(
+          z.union([
+            z.literal("*"),
+            z
+              .url({ protocol: /^https?$/u })
+              .transform((value) => new URL(value).origin),
+          ])
+        )
+        .optional(),
       enabled: z.boolean().default(false),
       // Optional external endpoint for projects that keep their docs static
       // and host Ask AI in an existing backend. Absolute URLs and root-relative
       // paths are both valid; the built-in request/stream contract is unchanged.
       endpoint: askEndpointSchema.optional(),
+      // Static request headers the generated endpoint sends the provider on
+      // every call (a caller-identifying header for a shared backend, say).
+      // Values are inlined into the generated route as literals, so the API
+      // key stays in `apiKeyEnv`; these are for non-secret metadata.
+      headers: z.record(z.string(), z.string()).optional(),
       // Extra system-prompt text (identity, language, tone) appended to the
       // built-in instructions, so the grounding contract — answer from the
       // retrieved excerpts, cite pages as Markdown links — stays intact.
       instructions: z.string().trim().min(1).optional(),
       model: z.string().default("openai/gpt-5.5"),
       provider: z.enum(askAiProviders).default("gateway"),
+      // How much the model reasons before answering, sent as the backend's
+      // own reasoning-effort control (see `askEndpointTemplate`). Omitted
+      // keeps the provider's default; `none` is the fastest and cheapest for
+      // grounded docs Q&A, where the excerpts carry the answer. Not for
+      // Inkeep, which has no such control (refined below).
+      reasoning: z.enum(askReasoningLevels).optional(),
       // How much documentation each question carries. Injected characters are
       // the dominant term in time-to-first-token on a self-hosted backend, so
       // these trade recall for latency. No zod defaults here: only what the
@@ -921,6 +960,27 @@ const aiConfigSchema = z.strictObject({
           path: ["baseUrl"],
         });
       }
+      // `cors` configures the generated route, which an external `endpoint`
+      // replaces; accepting both would silently do nothing.
+      if (value.cors && value.endpoint) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "ai.ask.cors only applies to the generated route; with ai.ask.endpoint, CORS is that backend's job.",
+          path: ["cors"],
+        });
+      }
+      // Inkeep runs its own QA pipeline behind an OpenAI-compatible endpoint
+      // with no reasoning control; a level would only reach it as an
+      // unsupported `reasoning_effort`, so refuse it up front.
+      if (value.provider === "inkeep" && value.reasoning) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            'ai.ask.reasoning is not supported when provider is "inkeep".',
+          path: ["reasoning"],
+        });
+      }
     })
     .optional(),
   /**
@@ -1073,6 +1133,7 @@ const navigationConfigSchema = z.strictObject({
 });
 
 export type AskAiProvider = (typeof askAiProviders)[number];
+export type AskReasoning = (typeof askReasoningLevels)[number];
 export type AskAiConfig = NonNullable<z.infer<typeof aiConfigSchema>["ask"]>;
 export { openInChatProviders } from "./open-in-chat.ts";
 export type { OpenInChatProvider } from "./open-in-chat.ts";