blume 1.7.1 → 1.7.2

package/dist/types/core/schema.d.ts

@@ -327,6 +327,11 @@ export type SidebarItemConfig = string | {
     root?: string;
 };
 export declare const searchProviders: readonly ["orama", "pagefind", "flexsearch", "algolia", "orama-cloud", "typesense", "mixedbread", "none"];
+/**
+ * The `ai.ask.reasoning` levels: the AI SDK's top-level `reasoning` values
+ * minus `provider-default`, which is what omitting the field means.
+ */
+export declare const askReasoningLevels: readonly ["none", "minimal", "low", "medium", "high", "xhigh"];
 /** Ask AI backends. `gateway` (default) routes through the Vercel AI Gateway. */
 export declare const askAiProviders: readonly ["gateway", "openrouter", "llmgateway", "inkeep", "openai-compatible"];
 declare const aiConfigSchema: z.ZodObject<{
@@ -334,6 +339,7 @@ declare const aiConfigSchema: z.ZodObject<{
     ask: z.ZodOptional<z.ZodObject<{
         apiKeyEnv: z.ZodOptional<z.ZodString>;
         baseUrl: z.ZodOptional<z.ZodURL>;
+        cors: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodPipe<z.ZodURL, z.ZodTransform<string, string>>]>>>;
         enabled: z.ZodDefault<z.ZodBoolean>;
         endpoint: z.ZodOptional<z.ZodString>;
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -346,6 +352,14 @@ declare const aiConfigSchema: z.ZodObject<{
             inkeep: "inkeep";
             "openai-compatible": "openai-compatible";
         }>>;
+        reasoning: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            minimal: "minimal";
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>>;
         retrieval: z.ZodOptional<z.ZodObject<{
             contextBudget: z.ZodOptional<z.ZodNumber>;
             excerptChars: z.ZodOptional<z.ZodNumber>;
@@ -391,6 +405,7 @@ declare const aiConfigSchema: z.ZodObject<{
     webmcp: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strict>;
 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";
@@ -505,9 +520,9 @@ declare const contentSignalsSchema: z.ZodPipe<z.ZodUnion<readonly [z.ZodBoolean,
 declare const dateFormatConfigSchema: z.ZodObject<{
     calendar: z.ZodOptional<z.ZodString>;
     dateStyle: z.ZodOptional<z.ZodEnum<{
+        medium: "medium";
         full: "full";
         long: "long";
-        medium: "medium";
         short: "short";
     }>>;
     day: z.ZodOptional<z.ZodEnum<{
@@ -576,6 +591,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
         ask: z.ZodOptional<z.ZodObject<{
             apiKeyEnv: z.ZodOptional<z.ZodString>;
             baseUrl: z.ZodOptional<z.ZodURL>;
+            cors: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodPipe<z.ZodURL, z.ZodTransform<string, string>>]>>>;
             enabled: z.ZodDefault<z.ZodBoolean>;
             endpoint: z.ZodOptional<z.ZodString>;
             headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -588,6 +604,14 @@ export declare const blumeConfigSchema: z.ZodObject<{
                 inkeep: "inkeep";
                 "openai-compatible": "openai-compatible";
             }>>;
+            reasoning: z.ZodOptional<z.ZodEnum<{
+                none: "none";
+                minimal: "minimal";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+            }>>;
             retrieval: z.ZodOptional<z.ZodObject<{
                 contextBudget: z.ZodOptional<z.ZodNumber>;
                 excerptChars: z.ZodOptional<z.ZodNumber>;
@@ -773,9 +797,9 @@ export declare const blumeConfigSchema: z.ZodObject<{
     dateFormat: z.ZodDefault<z.ZodObject<{
         calendar: z.ZodOptional<z.ZodString>;
         dateStyle: z.ZodOptional<z.ZodEnum<{
+            medium: "medium";
             full: "full";
             long: "long";
-            medium: "medium";
             short: "short";
         }>>;
         day: z.ZodOptional<z.ZodEnum<{
@@ -1061,6 +1085,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
             label: z.ZodString;
         }, z.core.$strict>>>;
         provider: z.ZodDefault<z.ZodEnum<{
+            none: "none";
             algolia: "algolia";
             mixedbread: "mixedbread";
             orama: "orama";
@@ -1068,7 +1093,6 @@ export declare const blumeConfigSchema: z.ZodObject<{
             flexsearch: "flexsearch";
             "orama-cloud": "orama-cloud";
             typesense: "typesense";
-            none: "none";
         }>>;
         typesense: z.ZodOptional<z.ZodObject<{
             collection: z.ZodString;

package/docs/configuration/ask-ai.mdx

@@ -109,6 +109,37 @@ Blume sends the same `POST` body as its built-in route:
 
 Return a successful response whose body is a plain UTF-8 text stream. If the endpoint is on another origin, allow the docs origin with CORS: accept `OPTIONS` and `POST`, permit the `content-type` request header, and return the CORS headers on both the preflight and streamed response. With `endpoint` set, Blume generates the chat UI but no server route, grounding snapshot, provider dependency, or provider-secret warning; your backend owns retrieval, authentication, rate limiting, model access, and citations.
 
+## Cross-origin callers
+
+The generated endpoint answers the in-page assistant on its own origin. To call it from another site as well — a marketing page with an ask box, say — list that site's origin in `cors`:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    cors: ["https://www.example.com"],
+  },
+}
+```
+
+The route then answers the browser's `OPTIONS` preflight and names a listed origin on every response — the streamed answer and the error statuses alike, so the caller can tell a rejected body from a provider failure. Origins that aren't listed get no header and stay subject to the browser's same-origin rule. Each entry is reduced to its origin, so `https://www.example.com/docs/` and `https://www.example.com` mean the same thing. To let any page call the route, list `"*"` instead of origins.
+
+The caller sends the same `POST` body the [external endpoint](#external-endpoint) contract describes and reads back the same text stream. Send it as JSON with a `content-type: application/json` header:
+
+```ts
+const response = await fetch("https://docs.example.com/api/ask", {
+  body: JSON.stringify({
+    messages: [{ role: "user", content: "How do I deploy?" }],
+  }),
+  headers: { "content-type": "application/json" },
+  method: "POST",
+});
+```
+
+The content type matters: Astro's cross-site request check rejects a cross-origin `POST` that has no content type, or a form-like one such as `text/plain`, with a 403 before the route runs, and that response carries no CORS headers, so the browser reports it as a network error rather than a status. The preflight allows whatever request headers the caller asks for, so a fetch wrapper that adds its own headers needs no extra configuration.
+
+`cors` only affects the generated route; with an external `endpoint`, CORS is that backend's job, and setting both is a config error. The endpoint stays unauthenticated either way, so the [rate limiting](#rate-limiting) advice applies to cross-origin traffic too.
+
 ## Server output required
 
 Blume's built-in Ask AI backend is a server route (`POST /api/ask`), so it can't run on a static build. Switch to server output and pick an adapter:
@@ -188,6 +219,22 @@ The values are written into the generated route as-is, so keep secrets in `apiKe
 
 Keys are read through Astro's [`getSecret()`](https://docs.astro.build/en/guides/environment-variables/#retrieving-secrets-programmatically), so each adapter supplies them its own way: environment variables on Node, Vercel, and Netlify, and the Worker's [bindings](https://docs.astro.build/en/guides/integrations-guide/cloudflare/#environment-variables-and-secrets) on Cloudflare. Enabling Ask AI also turns on React for the in-page island — see [Customization](/docs/configuration/customization#interactive-islands).
 
+## Reasoning
+
+Reasoning models think before they answer, and how much they do so by default varies by model. For grounded docs Q&A the retrieved excerpts carry the answer, so most of that thinking is latency the reader waits through. `reasoning` sets how much the model reasons: `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, or `"xhigh"`:
+
+```ts blume.config.ts lineNumbers
+ai: {
+  ask: {
+    enabled: true,
+    model: "openai/gpt-5.5",
+    reasoning: "none",
+  },
+}
+```
+
+The value is sent as the backend's own reasoning-effort control. Through the gateway it travels as the [AI SDK's `reasoning` option](https://ai-sdk.dev/docs/ai-sdk-core/reasoning), which the gateway maps to the model's setting — OpenAI's `reasoning_effort`, for example. On OpenRouter it is sent as `reasoning.effort`, and on LLMGateway or a custom `openai-compatible` endpoint as `reasoning_effort` in the request, so the endpoint has to accept that parameter. The model has to support the level you pick: OpenAI rejects a level a model doesn't offer (`"none"` and `"xhigh"` exist only on some), so check the model's documentation before setting one. Inkeep runs its own QA pipeline and has no reasoning control, so setting `reasoning` with that backend is a config error. Leave it unset to keep the model's default. Like [retrieval size](#retrieval-size), it trades thoroughness for time-to-first-token, and answers stay grounded either way.
+
 ## Rate limiting
 
 The `POST /api/ask` endpoint is **unauthenticated** — it has to be, so the in-page assistant can call it. Blume validates each request — rejecting malformed bodies, capping it to 1–40 messages, and accepting only `user`/`assistant` roles so a caller can't inject their own system prompt and repurpose the route as a general LLM proxy — to bound how much a single call can spend against your model, but it can't stop someone from calling the endpoint repeatedly. If cost abuse is a concern, put the route behind a rate limiter — your host's (e.g. Vercel's) edge rate limiting, a middleware, or your model provider's per-key spend limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/ai/cors.ts

@@ -0,0 +1,87 @@
+/**
+ * CORS for the generated Ask AI route (`ai.ask.cors`).
+ *
+ * A browser only lets a page on another origin read a response that names
+ * that origin, and a JSON `POST` preflights first. `preflightResponse` answers
+ * the `OPTIONS`; `withCors` wraps the `POST` handler so every response it
+ * returns — the stream, a 400, a 500 — carries the headers. Wrapping once,
+ * rather than stamping each `return`, keeps the next return site added to the
+ * handler from shipping an opaque failure for that one status.
+ *
+ * `allowed` is the `ai.ask.cors` list: origins already reduced to their
+ * `scheme://host[:port]` form by the config schema, or the single entry `"*"`
+ * to admit every origin.
+ */
+
+/** The `ai.ask.cors` entry that admits every origin. */
+export const ANY_ORIGIN = "*";
+
+/** The headers a response carries for a cross-origin caller. */
+export interface CorsHeaders {
+  "access-control-allow-origin"?: string;
+  vary?: string;
+}
+
+/** The response headers that name the caller's origin when `allowed` lists it. */
+export const corsHeaders = (
+  request: Request,
+  allowed: readonly string[]
+): CorsHeaders => {
+  if (allowed.includes(ANY_ORIGIN)) {
+    // A wildcard answer is the same for every caller, so nothing to vary on.
+    return { "access-control-allow-origin": ANY_ORIGIN };
+  }
+  // `Vary` rides on both branches: the answer depends on `Origin` whether or
+  // not it was listed, so a shared cache never hands one origin's response
+  // (or the header-less one) to another.
+  const origin = request.headers.get("origin");
+  return origin && allowed.includes(origin)
+    ? { "access-control-allow-origin": origin, vary: "origin" }
+    : { vary: "origin" };
+};
+
+/** Answer the browser's `OPTIONS` preflight for the route. */
+export const preflightResponse = (
+  request: Request,
+  allowed: readonly string[]
+): Response =>
+  new Response(null, {
+    headers: {
+      ...corsHeaders(request, allowed),
+      // Reflect whatever the caller's fetch wrapper asks to send, falling back
+      // to the JSON POST's own `content-type`; a listed origin shouldn't need
+      // an eject to add a header of its own.
+      "access-control-allow-headers":
+        request.headers.get("access-control-request-headers") ?? "content-type",
+      "access-control-allow-methods": "POST",
+      "access-control-max-age": "86400",
+    },
+    status: 204,
+  });
+
+/** The slice of Astro's `APIContext` the wrapped handler reads. */
+interface RequestContext {
+  request: Request;
+}
+
+/** Stamp the CORS headers on every response `handler` returns. */
+export const withCors =
+  (
+    allowed: readonly string[],
+    handler: (context: RequestContext) => Promise<Response> | Response
+  ): ((context: RequestContext) => Promise<Response>) =>
+  async (context) => {
+    const response = await handler(context);
+    for (const [key, value] of Object.entries(
+      corsHeaders(context.request, allowed)
+    )) {
+      // `Vary` accumulates (the handler may already vary on something), the
+      // rest replace.
+      if (key === "vary") {
+        response.headers.append(key, value);
+      } else {
+        response.headers.set(key, value);
+      }
+    }
+    return response;
+  };

package/src/astro/generate.ts

@@ -1826,7 +1826,9 @@ const writeAskFiles = async (
   await write(
     join(srcDir, "pages", "api", "ask.ts"),
     askEndpointTemplate(resolveAskBackend(ask), grounded, {
+      cors: ask.cors,
       instructions: ask.instructions,
+      reasoning: ask.reasoning,
       retrieval: ask.retrieval,
     })
   );

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;
@@ -1097,7 +1152,10 @@ export const askEndpointTemplate = (
     setup = `\nconst openrouter = createOpenRouter({
   apiKey: getSecret(${JSON.stringify(backend.apiKeyEnv)}),${headersField}
 });\n`;
-    modelExpr = `openrouter(${JSON.stringify(backend.model)})`;
+    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";'
@@ -1120,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
@@ -1183,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 {
@@ -1209,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}
 `;
 };

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,