npm - blume - Versions diffs - 1.5.1 → 1.5.3 - Mend

blume 1.5.1 → 1.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/CHANGELOG.md +23 -0
package/dist/cli/index.js +340 -132
package/dist/cli/index.js.map +21 -20
package/dist/types/ai/ask-context.d.ts +78 -0
package/dist/types/core/config-input.d.ts +53 -1
package/dist/types/core/data.d.ts +16 -0
package/dist/types/core/open-in-chat.d.ts +9 -0
package/dist/types/core/schema.d.ts +48 -1
package/dist/types/core/types.d.ts +10 -3
package/dist/types/openapi/references.d.ts +9 -0
package/dist/types/search/orama-index.d.ts +70 -0
package/docs/advanced/api-reference.mdx +67 -5
package/docs/configuration/ai.mdx +35 -0
package/docs/configuration/index.mdx +13 -1
package/docs/configuration/search.mdx +4 -4
package/docs/reference/cli.mdx +1 -1
package/package.json +1 -1
package/skills/blume-migrate/SKILL.md +1 -1
package/skills/blume-migrate/references/mintlify.md +1 -1
package/src/ai/ask-context.ts +51 -11
package/src/ai/mcp/data.ts +3 -2
package/src/ai/mcp/server.ts +3 -2
package/src/assets/icon-dark.png +0 -0
package/src/astro/generate.ts +162 -13
package/src/astro/templates.ts +63 -11
package/src/components/content/AccordionItem.astro +4 -0
package/src/components/content/Update.astro +3 -0
package/src/components/islands/AskAI.astro +6 -0
package/src/components/islands/ask-ai.tsx +39 -9
package/src/components/layout/Analytics.astro +9 -1
package/src/components/layout/Favicon.astro +29 -8
package/src/components/layout/Header.astro +2 -2
package/src/components/layout/NavSelector.astro +1 -1
package/src/components/layout/PageActions.astro +120 -78
package/src/components/layout/PageFeedback.astro +12 -3
package/src/components/layout/PageLayout.astro +15 -3
package/src/components/layout/ReferenceLayout.astro +10 -8
package/src/components/layout/RootLayout.astro +155 -120
package/src/components/layout/Search.astro +41 -26
package/src/components/layout/drawer-inert.ts +10 -5
package/src/components/layout/head-scripts.ts +57 -16
package/src/components/layout/nav-utils.ts +34 -15
package/src/components/layout/search/orama.ts +3 -2
package/src/components/openapi/AsyncApiOperation.astro +22 -7
package/src/components/openapi/MessageComposer.astro +238 -0
package/src/components/openapi/Operation.astro +26 -12
package/src/components/openapi/PanelTabs.astro +7 -0
package/src/components/openapi/Playground.astro +320 -0
package/src/components/openapi/RequestPanel.astro +1 -0
package/src/components/openapi/async-snippets.ts +20 -7
package/src/components/openapi/async.ts +13 -2
package/src/components/openapi/message-composer.ts +242 -0
package/src/components/openapi/message-model.ts +108 -0
package/src/components/openapi/message.ts +153 -0
package/src/components/openapi/operation-model.ts +260 -0
package/src/components/openapi/playground-client.ts +486 -0
package/src/components/openapi/playground-schema.ts +109 -0
package/src/components/openapi/request.ts +287 -0
package/src/components/openapi/security.ts +0 -56
package/src/components/openapi/snippets.ts +23 -136
package/src/components/openapi/validate-json.ts +144 -0
package/src/components/openapi/ws-client.ts +194 -0
package/src/core/config-input.ts +66 -0
package/src/core/content-assets.ts +66 -15
package/src/core/data.ts +13 -0
package/src/core/last-modified.ts +28 -3
package/src/core/links.ts +30 -4
package/src/core/navigation.ts +26 -1
package/src/core/open-in-chat.ts +17 -0
package/src/core/schema.ts +59 -0
package/src/core/server-features.ts +11 -0
package/src/core/sources/normalize.ts +10 -2
package/src/core/types.ts +10 -3
package/src/openapi/model.ts +7 -0
package/src/openapi/proxy.ts +217 -0
package/src/openapi/references.ts +8 -0
package/src/openapi/source.ts +13 -0
package/src/registry/eject.ts +4 -5
package/src/search/orama-index.ts +109 -36
package/src/theme/entry.ts +6 -15

package/src/components/layout/RootLayout.astro CHANGED Viewed

@@ -3,7 +3,8 @@ import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import { resolveDateFormatOptions } from "../../core/date-format.ts";
 import type { ResolvedDateFormat } from "../../core/schema.ts";
-import type { BlumeClientData } from "../../core/data.ts";
+import type { OpenInChatProvider } from "../../core/open-in-chat.ts";
+import type { BlumeClientData, BlumeFavicon } from "../../core/data.ts";
 import type {
   Heading,
   LocaleSwitchOption,
@@ -11,6 +12,7 @@ import type {
   NavSelector as NavSelectorType,
 } from "../../core/types.ts";
 import "blume:theme";
+import { ClientRouter } from "astro:transitions";
 import type { FontHead } from "../../theme/fonts.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import {
@@ -31,12 +33,13 @@ import Fonts from "./Fonts.astro";
 import {
   BANNER_INIT_SCRIPT,
   SIDEBAR_SCROLL_INIT_SCRIPT,
+  SWAP_STYLESHEET_INIT_SCRIPT,
   THEME_INIT_SCRIPT,
 } from "./head-scripts.ts";
 import Header from "./Header.astro";
 import Icon from "../Icon.astro";
 import {
-  activeTabForRoute,
+  currentTabForRoute,
   findBreadcrumbs,
   flattenPages,
   getPagination,
@@ -60,14 +63,8 @@ interface Props {
     href: string;
     text?: string;
   } | null;
-  favicon?: {
-    href: string;
-    type?: string;
-  } | null;
-  appleIcon?: {
-    href: string;
-    type?: string;
-  } | null;
+  favicon?: BlumeFavicon | null;
+  appleIcon?: BlumeFavicon | null;
   banner?: {
     content: string;
     link?: { text: string; href: string };
@@ -119,6 +116,11 @@ interface Props {
   feedback?: boolean;
   exportPdf?: boolean;
   exportEpub?: boolean;
+  /**
+   * "Open in chat" providers to list, in order; an empty list hides the
+   * action, and omitting the prop shows every provider.
+   */
+  openInChat?: readonly OpenInChatProvider[];
   feeds?: { title: string; href: string }[];
   /**
    * Which agent-discovery resources exist, advertised as `describedby` head
@@ -218,6 +220,7 @@ const {
   feedback = false,
   exportPdf,
   exportEpub,
+  openInChat,
   feeds,
   discovery,
   siteUrl,
@@ -356,14 +359,21 @@ const mcpUrl =
 // pages. Without tabs — or on a route under none — this is the full sidebar.
 // `navigation.root` keeps the root-tab check in the tabs' localized/based
 // path space (`/en`, `/docs`), so a locale or base prefix doesn't misread the
-// root tab as a section tab.
+// root tab as a section tab; in an archived version tree the root is
+// versionized (`/v1.0`) while tabs stay in current-docs space, so the root
+// tab is matched by containment and the snapshot renders unscoped — the same
+// reason no tab is marked current there (tabs link back to current docs).
 const sidebar = sidebarForRoute(
   navigation.sidebar,
   navigation.tabs,
   page.route,
   navigation.root
 );
-const activeTab = activeTabForRoute(navigation.tabs, page.route);
+const activeTab = currentTabForRoute(
+  navigation.tabs,
+  page.route,
+  navigation.root
+);
 const crumbs = findBreadcrumbs(sidebar, page.route);
 const { prev, next } = getPagination(flattenPages(sidebar), page.route);
@@ -398,6 +408,16 @@ const bannerKey = banner?.dismissible ? banner.key : null;
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
+    {/* Client-side navigation: same-origin link clicks swap the DOM in place
+        instead of tearing the document down, so no browser ever paints a blank
+        frame between pages (Firefox has no cross-document paint holding and
+        flickered on every full load). Uses native view transitions where
+        supported, with Astro's simulated fade elsewhere; pairs with the
+        prefetch option in the generated Astro config. */}
+    <ClientRouter />
+    {/* Loads a next page's body-hoisted CSS before the router swaps it in —
+        see SWAP_STYLESHEET_INIT_SCRIPT for the unstyled-frame failure mode. */}
+    <script is:inline set:html={SWAP_STYLESHEET_INIT_SCRIPT} />
     <title>{pageTitle}</title>
     <Favicon favicon={favicon} appleIcon={appleIcon} />
     <Fonts cssVars={fontCssVars ?? []} />
@@ -706,6 +726,7 @@ const bannerKey = banner?.dismissible ? banner.key : null;
               exportPdf={exportPdf}
               mcpName={mcp?.name}
               mcpUrl={mcpUrl}
+              openInChat={openInChat}
               route={page.route}
               strings={strings.actions}
             />
@@ -744,6 +765,8 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       // Tree-shaken out of production builds.
       import "./hydration-hint.ts";
+      // Runs once per real page load; re-syncs itself after client-router
+      // swaps (see drawer-inert.ts).
       syncDrawerInert();
       const svg = (name: string, cls = "") =>
@@ -755,14 +778,6 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         "absolute right-3 z-[2] inline-flex size-[1.875rem] select-none items-center justify-center rounded-md text-muted-foreground bg-background transition-colors [&_svg]:pointer-events-none [&_svg]:shrink-0";
       const idleClasses = ["hover:bg-muted", "hover:text-foreground"];
-      // Localized copy-button labels, stamped on <body> by the layout markup
-      // (the Search.astro data-attribute channel) since this bundled script
-      // can't interpolate server values directly.
-      const copyCodeLabel =
-        document.body.getAttribute("data-i18n-copy-code") || "Copy code";
-      const copiedLabel =
-        document.body.getAttribute("data-i18n-copied") || "Copied!";
       const languageLabels: Record<string, string> = {
         astro: "Astro",
         bash: "Bash",
@@ -784,111 +799,131 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         zsh: "Zsh",
       };
-      for (const pre of document.querySelectorAll(".prose pre")) {
-        if (pre.querySelector("[data-blume-copy]")) {
-          continue;
-        }
-        // Skip nested <pre>: Twoslash renders each hover popup's type signature
-        // as a <pre> inside the code block, which shouldn't get its own button.
-        if (pre.parentElement?.closest("pre")) {
-          continue;
-        }
-        const language = pre.getAttribute("data-language");
-        if (language) {
-          pre.setAttribute(
-            "data-language",
-            languageLabels[language.toLowerCase()] ?? language
-          );
-        }
-        pre.classList.add("group", "relative");
-        // The code element is the scroll container (see the theme entry), but
-        // Shiki's tab stop lands on the pre, which no longer scrolls. Move the
-        // stop to the code so keyboard users can actually scroll the block
-        // (WCAG 2.1.1 — the same rule the table wrapper handles). Twoslash and
-        // API-panel blocks keep the pre as their scroller, so theirs stays.
-        const scroller = pre.querySelector("code");
-        if (scroller && !pre.matches(".twoslash, blume-panel-tabs *")) {
-          scroller.setAttribute("tabindex", "0");
-          pre.removeAttribute("tabindex");
-        }
-        const button = document.createElement("button");
-        button.type = "button";
-        // The language-label bar (prose) vs flush code (tabs) need a different
-        // offset; pick the Tailwind class by context instead of a CSS override.
-        const topClass = pre.closest("blume-tabs, .not-prose")
-          ? "top-2.5"
-          : "top-2";
-        button.className = `${buttonClass} ${idleClasses.join(" ")} ${topClass}`;
-        button.setAttribute("data-blume-copy", "");
-        button.setAttribute("aria-label", copyCodeLabel);
-        button.innerHTML =
-          svg(
-            "check",
-            "scale-0 text-green-600 transition-transform dark:text-green-500"
-          ) + svg("copy", "absolute transition-transform");
-        const [checkIcon, copyIcon] = button.querySelectorAll("svg");
-        // While checked the button drops its idle hover tint so the green
-        // check reads as a steady confirmation, mirroring Lina's copied state.
-        // The accessible name tracks the visual state for anyone probing the
-        // button mid-confirmation.
-        const setChecked = (checked: boolean) => {
-          checkIcon?.classList.toggle("scale-0", !checked);
-          copyIcon?.classList.toggle("scale-0", checked);
-          button.setAttribute(
-            "aria-label",
-            checked ? copiedLabel : copyCodeLabel
-          );
-          for (const cls of idleClasses) {
-            button.classList.toggle(cls, !checked);
+      // Per-page setup, run on the initial load and again after every
+      // client-router swap (which replaces the body with server-rendered
+      // markup that has none of this applied). Everything in here binds to
+      // elements the swap just created, so nothing double-attaches.
+      const initPage = async () => {
+        // Localized copy-button labels, stamped on <body> by the layout markup
+        // (the Search.astro data-attribute channel) since this bundled script
+        // can't interpolate server values directly. Read per page so a
+        // cross-locale navigation picks up the new language's labels.
+        const copyCodeLabel =
+          document.body.getAttribute("data-i18n-copy-code") || "Copy code";
+        const copiedLabel =
+          document.body.getAttribute("data-i18n-copied") || "Copied!";
+        for (const pre of document.querySelectorAll(".prose pre")) {
+          if (pre.querySelector("[data-blume-copy]")) {
+            continue;
           }
-        };
-        const flash = createCopyFlash(setChecked, copiedLabel);
-        button.addEventListener("click", async () => {
-          const code = pre.querySelector("code");
-          let text = code?.textContent ?? "";
-          // Twoslash nests each hover popup's type signature and docs inside
-          // the <code>; copying textContent verbatim would interleave them
-          // with the source. Strip the popups from a clone first.
-          if (code?.querySelector(".twoslash-popup-container")) {
-            const clone = code.cloneNode(true) as HTMLElement;
-            for (const popup of clone.querySelectorAll(
-              ".twoslash-popup-container"
-            )) {
-              popup.remove();
-            }
-            text = clone.textContent ?? "";
+          // Skip nested <pre>: Twoslash renders each hover popup's type signature
+          // as a <pre> inside the code block, which shouldn't get its own button.
+          if (pre.parentElement?.closest("pre")) {
+            continue;
           }
-          if (await copyText(text)) {
-            flash();
+          const language = pre.getAttribute("data-language");
+          if (language) {
+            pre.setAttribute(
+              "data-language",
+              languageLabels[language.toLowerCase()] ?? language
+            );
           }
-        });
-        pre.appendChild(button);
-      }
-      // Click-to-zoom for content images (gated by `markdown.imageZoom`),
-      // via medium-zoom: ESC/scroll/click dismissal, natural-size capping,
-      // and the open/close transition races are its problem, not ours.
-      // Opt out per-image with `data-no-zoom`.
-      if (document.body.hasAttribute("data-blume-image-zoom")) {
-        const zoomTargets = Array.from(
-          document.querySelectorAll<HTMLImageElement>(
-            ".prose img:not([data-no-zoom])"
-          )
-          // An image that is itself a link navigates on click — binding zoom
-          // to it would flash a zoom overlay in the instant before navigation
-          // and advertise (via the cursor) a zoom that never happens.
-        ).filter((image) => !image.closest("a"));
-        if (zoomTargets.length > 0) {
-          // Lazy: pages without a zoomable image never load the library,
-          // matching how mermaid is only fetched on pages with a diagram.
-          const { default: mediumZoom } = await import("medium-zoom");
-          mediumZoom(zoomTargets, {
-            background:
-              "color-mix(in oklab, var(--color-background) 80%, transparent)",
-            margin: 24,
+          pre.classList.add("group", "relative");
+          // The code element is the scroll container (see the theme entry), but
+          // Shiki's tab stop lands on the pre, which no longer scrolls. Move the
+          // stop to the code so keyboard users can actually scroll the block
+          // (WCAG 2.1.1 — the same rule the table wrapper handles). Twoslash and
+          // API-panel blocks keep the pre as their scroller, so theirs stays.
+          const scroller = pre.querySelector("code");
+          if (scroller && !pre.matches(".twoslash, blume-panel-tabs *")) {
+            scroller.setAttribute("tabindex", "0");
+            pre.removeAttribute("tabindex");
+          }
+          const button = document.createElement("button");
+          button.type = "button";
+          // The language-label bar (prose) vs flush code (tabs) need a different
+          // offset; pick the Tailwind class by context instead of a CSS override.
+          const topClass = pre.closest("blume-tabs, .not-prose")
+            ? "top-2.5"
+            : "top-2";
+          button.className = `${buttonClass} ${idleClasses.join(" ")} ${topClass}`;
+          button.setAttribute("data-blume-copy", "");
+          button.setAttribute("aria-label", copyCodeLabel);
+          button.innerHTML =
+            svg(
+              "check",
+              "scale-0 text-green-600 transition-transform dark:text-green-500"
+            ) + svg("copy", "absolute transition-transform");
+          const [checkIcon, copyIcon] = button.querySelectorAll("svg");
+          // While checked the button drops its idle hover tint so the green
+          // check reads as a steady confirmation, mirroring Lina's copied state.
+          // The accessible name tracks the visual state for anyone probing the
+          // button mid-confirmation.
+          const setChecked = (checked: boolean) => {
+            checkIcon?.classList.toggle("scale-0", !checked);
+            copyIcon?.classList.toggle("scale-0", checked);
+            button.setAttribute(
+              "aria-label",
+              checked ? copiedLabel : copyCodeLabel
+            );
+            for (const cls of idleClasses) {
+              button.classList.toggle(cls, !checked);
+            }
+          };
+          const flash = createCopyFlash(setChecked, copiedLabel);
+          button.addEventListener("click", async () => {
+            const code = pre.querySelector("code");
+            let text = code?.textContent ?? "";
+            // Twoslash nests each hover popup's type signature and docs inside
+            // the <code>; copying textContent verbatim would interleave them
+            // with the source. Strip the popups from a clone first.
+            if (code?.querySelector(".twoslash-popup-container")) {
+              const clone = code.cloneNode(true) as HTMLElement;
+              for (const popup of clone.querySelectorAll(
+                ".twoslash-popup-container"
+              )) {
+                popup.remove();
+              }
+              text = clone.textContent ?? "";
+            }
+            if (await copyText(text)) {
+              flash();
+            }
           });
+          pre.appendChild(button);
         }
-      }
+        // Click-to-zoom for content images (gated by `markdown.imageZoom`),
+        // via medium-zoom: ESC/scroll/click dismissal, natural-size capping,
+        // and the open/close transition races are its problem, not ours.
+        // Opt out per-image with `data-no-zoom`.
+        if (document.body.hasAttribute("data-blume-image-zoom")) {
+          const zoomTargets = Array.from(
+            document.querySelectorAll<HTMLImageElement>(
+              ".prose img:not([data-no-zoom])"
+            )
+            // An image that is itself a link navigates on click — binding zoom
+            // to it would flash a zoom overlay in the instant before navigation
+            // and advertise (via the cursor) a zoom that never happens.
+          ).filter((image) => !image.closest("a"));
+          if (zoomTargets.length > 0) {
+            // Lazy: pages without a zoomable image never load the library,
+            // matching how mermaid is only fetched on pages with a diagram.
+            const { default: mediumZoom } = await import("medium-zoom");
+            mediumZoom(zoomTargets, {
+              background:
+                "color-mix(in oklab, var(--color-background) 80%, transparent)",
+              margin: 24,
+            });
+          }
+        }
+      };
+      void initPage();
+      document.addEventListener("astro:after-swap", () => {
+        void initPage();
+      });
     </script>
     <style is:global>
       /* medium-zoom ships no z-index; lift the lightbox above the chrome

package/src/components/layout/Search.astro CHANGED Viewed

@@ -203,6 +203,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   />
   <script>
+    import { navigate } from "astro:transitions/client";
     import { chromeIcons as icons } from "../../theme/chrome-icons.ts";
     import { prefixBase } from "../islands/base-path.ts";
     import { escape as escapeHtml } from "html-escaper";
@@ -301,6 +302,36 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       version = "";
       allVersions = false;
+      // Document-level, so it outlives this element unless removed: each
+      // client-router swap rebuilds the header (and this element with it), and
+      // an orphaned copy would keep toggling a dialog that is no longer in the
+      // document. Held as a field so disconnectedCallback can detach it.
+      #onDocumentKeydown = (event: KeyboardEvent) => {
+        if (
+          (event.key === "k" || event.key === "K") &&
+          (event.metaKey || event.ctrlKey) &&
+          // Ctrl+Shift+K is Firefox's web console; a shifted or alted chord
+          // belongs to the browser, not the search dialog.
+          !event.shiftKey &&
+          !event.altKey
+        ) {
+          // ⌘K toggles, mirroring the Ask AI panel's ⌘I: pressing it with
+          // the dialog open must close it, not re-showModal an open dialog
+          // (an InvalidStateError on older engines).
+          event.preventDefault();
+          if (this.dialog.open) {
+            this.dialog.close();
+          } else {
+            this.open();
+          }
+        } else if (event.key === "/" && !this.isField(event.target)) {
+          // "/" stays open-only; the field guard keeps it inert while
+          // typing (including in the search input itself).
+          event.preventDefault();
+          this.open();
+        }
+      };
       connectedCallback() {
         this.devOnlyMsg =
           this.getAttribute("data-i18n-dev") || this.devOnlyMsg;
@@ -397,31 +428,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           () => this.open()
         );
-        document.addEventListener("keydown", (event) => {
-          if (
-            (event.key === "k" || event.key === "K") &&
-            (event.metaKey || event.ctrlKey) &&
-            // Ctrl+Shift+K is Firefox's web console; a shifted or alted chord
-            // belongs to the browser, not the search dialog.
-            !event.shiftKey &&
-            !event.altKey
-          ) {
-            // ⌘K toggles, mirroring the Ask AI panel's ⌘I: pressing it with
-            // the dialog open must close it, not re-showModal an open dialog
-            // (an InvalidStateError on older engines).
-            event.preventDefault();
-            if (this.dialog.open) {
-              this.dialog.close();
-            } else {
-              this.open();
-            }
-          } else if (event.key === "/" && !this.isField(event.target)) {
-            // "/" stays open-only; the field guard keeps it inert while
-            // typing (including in the search input itself).
-            event.preventDefault();
-            this.open();
-          }
-        });
+        document.addEventListener("keydown", this.#onDocumentKeydown);
         this.input.addEventListener("input", () => this.render());
         this.dialog.addEventListener("keydown", (event) =>
@@ -434,6 +441,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         });
       }
+      disconnectedCallback() {
+        document.removeEventListener("keydown", this.#onDocumentKeydown);
+      }
       isField(target: EventTarget | null): boolean {
         const el = target as HTMLElement | null;
         return Boolean(
@@ -799,7 +810,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
             new CustomEvent("blume:open-ask-ai", { detail: { query } })
           );
         } else if (item.url) {
-          window.location.href = item.url;
+          // Close first so the dialog isn't left open over the transition;
+          // navigate() rides the client router (and falls back to a normal
+          // full load on pages without it).
+          this.dialog.close();
+          navigate(item.url);
         }
       }

package/src/components/layout/drawer-inert.ts CHANGED Viewed

@@ -4,15 +4,19 @@
  * stay focusable on every page. Mirrors the header's `data-blume-nav-open`
  * toggle into `inert`/`aria-hidden` — but only below `lg` (64rem), where the
  * same element isn't the static sidebar (RootLayout) or is display-hidden
- * anyway (PageLayout). Shared by both layouts' inline scripts.
+ * anyway (PageLayout). Shared by both layouts' bundled scripts, which run once
+ * per real page load; the drawer element is rebuilt by every client-router
+ * swap, so `sync` re-queries it each time and re-runs on `astro:after-swap`.
  */
 export const syncDrawerInert = (): void => {
-  const drawer = document.querySelector<HTMLElement>("[data-blume-nav-drawer]");
-  if (!drawer) {
-    return;
-  }
   const desktop = window.matchMedia("(min-width: 64rem)");
   const sync = () => {
+    const drawer = document.querySelector<HTMLElement>(
+      "[data-blume-nav-drawer]"
+    );
+    if (!drawer) {
+      return;
+    }
     const hidden =
       !desktop.matches &&
       !Object.hasOwn(document.documentElement.dataset, "blumeNavOpen");
@@ -28,4 +32,5 @@ export const syncDrawerInert = (): void => {
   new MutationObserver(sync).observe(document.documentElement, {
     attributeFilter: ["data-blume-nav-open"],
   });
+  document.addEventListener("astro:after-swap", sync);
 };

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

@@ -6,6 +6,15 @@
  * scrolled away from the current page. Kept in one place so the layouts can't
  * drift on this timing-critical logic.
  *
+ * Under the client router (`<ClientRouter />`), each script's element reappears
+ * on every navigated-to page but is executed only once per real page load —
+ * Astro skips scripts whose content it has already run. Anything that must hold
+ * per navigation therefore also registers an `astro:after-swap` listener on the
+ * first (and only) execution: the swap replaces the `<html>` attributes and the
+ * body wholesale, wiping `data-theme`/`data-blume-banner-hidden` and rebuilding
+ * the sidebar, and `after-swap` fires before the new page paints — the same
+ * no-flash timing the initial inline run has.
+ *
  * All are constants, never built by interpolating config into source text: any
  * values they need ride in as `data-*` attributes on the script tag and are read
  * back through `document.currentScript`. Baking a config string into JS — even
@@ -16,31 +25,63 @@
 /**
  * Set `data-theme` from the stored preference (or the configured default, or the
- * OS setting for `"system"`) before the body paints, avoiding a theme flash.
+ * OS setting for `"system"`) before the body paints, avoiding a theme flash —
+ * and again after every client-router swap, which resets `<html>` attributes to
+ * the incoming page's server-rendered (theme-less) set.
  *
  * Reads `data-mode` — `"system" | "light" | "dark"`.
  */
-export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);})();`;
+export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const apply=()=>{const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);};apply();document.addEventListener("astro:after-swap",apply);})();`;
 /**
- * Hide a previously-dismissed banner before it can flash in.
+ * Hide a previously-dismissed banner before it can flash in — and again after
+ * every client-router swap, which wipes the `<html>` marker attribute.
  *
  * Reads `data-key` — the banner's dismissal key.
  */
-export const BANNER_INIT_SCRIPT = `(()=>{const k=document.currentScript?.dataset.key;if(k&&localStorage.getItem("blume-banner:"+k))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`;
+export const BANNER_INIT_SCRIPT = `(()=>{const k=document.currentScript?.dataset.key;if(!k){return;}const apply=()=>{if(localStorage.getItem("blume-banner:"+k)){document.documentElement.setAttribute("data-blume-banner-hidden","");}};apply();document.addEventListener("astro:after-swap",apply);})();`;
+/**
+ * Keep the page styled across client-router swaps. Astro hoists the CSS of a
+ * component rendered after the head has streamed (the page's MDX content, the
+ * WebMcp island) into the **body** as `<link rel="stylesheet">` tags — and the
+ * client router only preloads and persists stylesheets it finds in the head.
+ * A swapped-in body `<link>` applies asynchronously, so every navigation to a
+ * page with body CSS painted one or two completely unstyled frames (giant raw
+ * SVG logo, default link colors) before the sheet kicked in — even when the
+ * same sheet was already loaded on the outgoing page, because the swap throws
+ * the old body (and its link element) away.
+ *
+ * Two listeners close the gap. `astro:before-preparation` wraps the router's
+ * loader: after the next document is fetched, any of its body stylesheets not
+ * already in the live head are appended there and awaited, so their rules
+ * apply before the swap. `astro:before-swap` then moves the incoming
+ * document's body stylesheets into its head, where the router's head diff
+ * keeps the already-loaded copy (matched by `href`) instead of re-inserting a
+ * fresh, not-yet-applied link — and drops it again on a later navigation to a
+ * page that doesn't use it. A sheet that fails to load resolves rather than
+ * wedging the navigation; the page renders as it would have without this.
+ */
+export const SWAP_STYLESHEET_INIT_SCRIPT = `(()=>{const sel='body link[rel="stylesheet"]';document.addEventListener("astro:before-preparation",(e)=>{const load=e.loader;e.loader=async()=>{await load();const links=[...e.newDocument.querySelectorAll(sel)].filter((l)=>!document.head.querySelector('link[rel="stylesheet"][href="'+l.getAttribute("href")+'"]'));await Promise.all(links.map((l)=>new Promise((done)=>{const c=document.createElement("link");for(const a of l.attributes){c.setAttribute(a.name,a.value);}c.onload=done;c.onerror=done;document.head.append(c);})));};});document.addEventListener("astro:before-swap",(e)=>{for(const l of e.newDocument.querySelectorAll(sel)){e.newDocument.head.append(l);}});})();`;
 /**
- * Center the current page's sidebar link before the sidebar paints. Every
- * navigation is a full page load, and the sidebar is its own scroll container,
- * so without this it is reborn scrolled to the top on every click — on a long
- * sidebar the viewport visibly jumps away from the link you just clicked.
+ * Keep the sidebar's scroll useful across page changes. The sidebar is its own
+ * scroll container, reborn scrolled to the top whenever its markup is rebuilt —
+ * on a long sidebar the viewport would visibly jump away from the link you just
+ * clicked.
+ *
+ * On the initial load it centers the current page's link before the sidebar
+ * paints (it runs inline immediately after the sidebar `<aside>`, not in
+ * `<head>`: it needs that markup parsed). On client-router navigations it first
+ * restores the exact scroll position saved at `astro:before-swap` — so clicking
+ * through nearby links doesn't move the sidebar at all — and only re-centers
+ * when the new page's link sits outside the visible scroll area.
  *
- * Runs inline immediately after the sidebar `<aside>` (not in `<head>`: it
- * needs that markup parsed). The lookup is scoped to the page tree
- * (`data-blume-nav-tree`) because the drawer also holds the mobile tabs list,
- * whose active tab is `aria-current` too. `getClientRects()` skips links that
- * aren't rendered — `hidden` drill-in panels and breakpoint-hidden duplicates —
- * and the script no-ops when the active link is already inside the visible
- * scroll area, so a short sidebar never moves.
+ * The lookup is scoped to the page tree (`data-blume-nav-tree`) because the
+ * drawer also holds the mobile tabs list, whose active tab is `aria-current`
+ * too. `getClientRects()` skips links that aren't rendered — `hidden` drill-in
+ * panels and breakpoint-hidden duplicates — and centering no-ops when the
+ * active link is already inside the visible scroll area, so a short sidebar
+ * never moves.
  */
-export const SIDEBAR_SCROLL_INIT_SCRIPT = `(()=>{const n=document.querySelector("[data-blume-nav-drawer]");const s=n&&(n.querySelector("[data-blume-nav-tree]")||n);if(!s)return;let l=null;for(const a of s.querySelectorAll('a[aria-current="page"]')){if(a.getClientRects().length){l=a;break;}}if(!l)return;const r=n.getBoundingClientRect();const t=l.getBoundingClientRect();if(t.top>=r.top&&t.bottom<=r.bottom)return;n.scrollTop+=t.top-r.top-(n.clientHeight-t.height)/2;})();`;
+export const SIDEBAR_SCROLL_INIT_SCRIPT = `(()=>{const drawer=()=>document.querySelector("[data-blume-nav-drawer]");const center=()=>{const n=drawer();const s=n&&(n.querySelector("[data-blume-nav-tree]")||n);if(!s)return;let l=null;for(const a of s.querySelectorAll('a[aria-current="page"]')){if(a.getClientRects().length){l=a;break;}}if(!l)return;const r=n.getBoundingClientRect();const t=l.getBoundingClientRect();if(t.top>=r.top&&t.bottom<=r.bottom)return;n.scrollTop+=t.top-r.top-(n.clientHeight-t.height)/2;};let saved=-1;document.addEventListener("astro:before-swap",()=>{const n=drawer();saved=n?n.scrollTop:-1;});document.addEventListener("astro:after-swap",()=>{const n=drawer();if(n&&saved>=0){n.scrollTop=saved;}center();});center();})();`;