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

blume 1.5.1 → 1.5.2

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 +17 -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 +7 -2
package/src/components/layout/ReferenceLayout.astro +10 -8
package/src/components/layout/RootLayout.astro +151 -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 +34 -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/content/Update.astro CHANGED Viewed

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

package/src/components/islands/AskAI.astro CHANGED Viewed

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

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

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

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

@@ -33,8 +33,16 @@ const vercelEnabled = enabled && analytics?.vercel === true;
 const POSTHOG_LOADER =
   '!function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="init capture register register_once register_for_session unregister unregister_for_session getFeatureFlag getFeatureFlagPayload isFeatureEnabled reloadFeatureFlags updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures on onFeatureFlags onSessionId getSurveys getActiveMatchingSurveys renderSurvey canRenderSurvey getNextSurveyStep identify setPersonProperties group resetGroups setPersonPropertiesForFlags resetPersonPropertiesForFlags setGroupPropertiesForFlags resetGroupPropertiesForFlags reset get_distinct_id getGroups get_session_id get_session_replay_url alias set_config startSessionRecording stopSessionRecording sessionRecordingStarted captureException loadToolbar get_property getSessionProperty createPersonProfile opt_in_capturing opt_out_capturing has_opted_in_capturing has_opted_out_capturing clear_opt_in_out_capturing debug getPageViewId captureTraceFeedback captureTraceMetric".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);';
 const posthog = enabled ? analytics?.posthog : undefined;
+// PostHog's loader only captures a pageview per real page load, but the client
+// router turns link clicks into in-place swaps — capture those too, keyed off
+// `astro:page-load` with a pathname guard so the initial load (which the
+// loader already counted) and same-page hash moves aren't double-counted.
+// Vercel Web Analytics and GA4's enhanced measurement track history changes
+// on their own.
+const POSTHOG_SPA_PAGEVIEWS =
+  'document.addEventListener("astro:page-load",function(){var p=window.__blumePhPath;window.__blumePhPath=location.pathname;if(p!==undefined&&p!==location.pathname){posthog.capture("$pageview");}});';
 const posthogSnippet = posthog
-  ? `${POSTHOG_LOADER}posthog.init(${JSON.stringify(posthog.key)},{api_host:${JSON.stringify(posthog.host ?? "https://us.i.posthog.com")}});`
+  ? `${POSTHOG_LOADER}posthog.init(${JSON.stringify(posthog.key)},{api_host:${JSON.stringify(posthog.host ?? "https://us.i.posthog.com")}});${POSTHOG_SPA_PAGEVIEWS}`
   : null;
 // Custom scripts: any other provider. Each is either external (`src`) or inline

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

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

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

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

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

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

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

@@ -1,6 +1,8 @@
 ---
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import { openInChatProviders } from "../../core/open-in-chat.ts";
+import type { OpenInChatProvider } from "../../core/open-in-chat.ts";
 import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
@@ -15,12 +17,25 @@ interface Props {
   mcpUrl?: string | null;
   /** Display name of the MCP server (defaults to the site title). */
   mcpName?: string | null;
+  /**
+   * "Open in chat" providers to list, in order; an empty list hides the
+   * action, and omitting the prop shows every provider.
+   */
+  openInChat?: readonly OpenInChatProvider[];
   /** Localized action labels. */
   strings?: UIStrings["actions"];
 }
-const { route, editUrl, exportPdf, exportEpub, mcpUrl, mcpName, strings } =
-  Astro.props;
+const {
+  route,
+  editUrl,
+  exportPdf,
+  exportEpub,
+  mcpUrl,
+  mcpName,
+  openInChat,
+  strings,
+} = Astro.props;
 // 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 blank.
 const a = { ...EN_UI.actions, ...strings };
@@ -44,20 +59,28 @@ const LOGOS: Record<string, string> = {
   v0: '<svg class="size-4 shrink-0" fill="currentColor" viewBox="0 0 147 70" xmlns="http://www.w3.org/2000/svg"><path d="M56 50.2031V14H70V60.1562C70 65.5928 65.5928 70 60.1562 70C57.5605 70 54.9982 68.9992 53.1562 67.1573L0 14H19.7969L56 50.2031Z"/><path d="M147 56H133V23.9531L100.953 56H133V70H96.6875C85.8144 70 77 61.1856 77 50.3125V14H91V46.1562L123.156 14H91V0H127.312C138.186 0 147 8.81439 147 19.6875V56Z"/></svg>',
 };
+/** Display names for the "Open in chat" providers. */
+const PROVIDER_NAMES: Record<OpenInChatProvider, string> = {
+  chatgpt: "ChatGPT",
+  claude: "Claude",
+  cursor: "Cursor",
+  scira: "Scira",
+  t3: "T3 Chat",
+  v0: "v0",
+};
 // Brand names stay verbatim; the surrounding "Open in" phrase localizes via
-// the `actions.openIn` template.
-const PROVIDERS = [
-  { key: "v0", name: "v0" },
-  { key: "chatgpt", name: "ChatGPT" },
-  { key: "claude", name: "Claude" },
-  { key: "t3", name: "T3 Chat" },
-  { key: "scira", name: "Scira" },
-  { key: "cursor", name: "Cursor" },
-].map((provider) => ({
-  ...provider,
-  label: a.openIn.replace("{name}", provider.name),
+// the `actions.openIn` template. `ai.openInChat` picks and orders the list;
+// an empty list hides the action entirely.
+const providers = (openInChat ?? openInChatProviders).map((key) => ({
+  key,
+  label: a.openIn.replace("{name}", PROVIDER_NAMES[key]),
 }));
+// The default list opens with v0 and separates it from the chat assistants;
+// keep that separator only while a configured list preserves v0 first.
+const chatSeparator = providers.length > 1 && providers[0]?.key === "v0";
 // Top-level actions match the ToC links: flat, no background/padding, color
 // shift on hover only.
 const rowClass =
@@ -134,41 +157,45 @@ const menuRowClass =
     )
   }
-  <details class="group relative">
-    <summary
-      class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
-    >
-      <Icon name="external-link" size={16} />
-      {a.openInChat}
-      <Icon
-        class="ms-auto transition-transform group-open:rotate-180"
-        name="chevron-down"
-        size={14}
-      />
-    </summary>
-    <div
-      class="absolute top-full right-2 z-50 mt-1 w-max min-w-[14rem] max-w-[22rem] rounded-blume border border-border bg-background p-1 shadow-xl"
-      data-blume-menu
-    >
-      {
-        PROVIDERS.map((provider, index) => (
-          <>
-            {index === 1 && <hr class="my-1 border-border border-t" />}
-            <a
-              class={menuRowClass}
-              data-open-in={provider.key}
-              rel="noreferrer"
-              target="_blank"
-            >
-              <span set:html={LOGOS[provider.key]} />
-              <span class="flex-1">{provider.label}</span>
-              <Icon name="external-link" size={13} />
-            </a>
-          </>
-        ))
-      }
-    </div>
-  </details>
+  {
+    providers.length > 0 && (
+      <details class="group relative">
+        <summary
+          class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
+        >
+          <Icon name="external-link" size={16} />
+          {a.openInChat}
+          <Icon
+            class="ms-auto transition-transform group-open:rotate-180"
+            name="chevron-down"
+            size={14}
+          />
+        </summary>
+        <div
+          class="absolute top-full right-2 z-50 mt-1 w-max min-w-[14rem] max-w-[22rem] rounded-blume border border-border bg-background p-1 shadow-xl"
+          data-blume-menu
+        >
+          {providers.map((provider, index) => (
+            <>
+              {index === 1 && chatSeparator && (
+                <hr class="my-1 border-border border-t" />
+              )}
+              <a
+                class={menuRowClass}
+                data-open-in={provider.key}
+                rel="noreferrer"
+                target="_blank"
+              >
+                <span set:html={LOGOS[provider.key]} />
+                <span class="flex-1">{provider.label}</span>
+                <Icon name="external-link" size={13} />
+              </a>
+            </>
+          ))}
+        </div>
+      </details>
+    )
+  }
   {
     mcpUrl && (
@@ -285,28 +312,51 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
     return clone.innerHTML;
   };
-  const root = document.querySelector("[data-blume-page-actions]");
-  if (root) {
+  const placeMenu = (details: HTMLDetailsElement) => {
+    const menu = details.querySelector<HTMLElement>("[data-blume-menu]");
+    const summary = details.querySelector("summary");
+    if (!(menu && summary)) {
+      return;
+    }
+    const rect = summary.getBoundingClientRect();
+    const margin = 8;
+    const flipUp =
+      rect.bottom + menu.offsetHeight + margin > window.innerHeight &&
+      rect.top - menu.offsetHeight - margin > 0;
+    menu.classList.toggle("top-full", !flipUp);
+    menu.classList.toggle("mt-1", !flipUp);
+    menu.classList.toggle("bottom-full", flipUp);
+    menu.classList.toggle("mb-1", flipUp);
+  };
+  // rAF-coalesced so a live resize drag re-reads layout once per frame, not
+  // once per event, while the open menu still tracks the viewport. Registered
+  // once at module scope (this bundle runs once per real page load) and
+  // querying live, because client-router swaps replace the menu elements.
+  window.addEventListener(
+    "resize",
+    rafThrottle(() => {
+      const open = document.querySelector<HTMLDetailsElement>(
+        "[data-blume-page-actions] details[open]"
+      );
+      if (open) {
+        placeMenu(open);
+      }
+    })
+  );
+  // Per-page setup, run on the initial load and again after every
+  // client-router swap: the swap rebuilds the actions menu from
+  // server-rendered markup, so every handler below binds to fresh elements.
+  const initPageActions = () => {
+    const root = document.querySelector("[data-blume-page-actions]");
+    if (!root) {
+      return;
+    }
     // The action dropdowns are native <details>. Make them behave like a proper
     // menu: only one open at a time, and flip above the trigger when opening
     // downward would run past the viewport bottom.
     const dropdowns = [...root.querySelectorAll<HTMLDetailsElement>("details")];
-    const placeMenu = (details: HTMLDetailsElement) => {
-      const menu = details.querySelector<HTMLElement>("[data-blume-menu]");
-      const summary = details.querySelector("summary");
-      if (!(menu && summary)) {
-        return;
-      }
-      const rect = summary.getBoundingClientRect();
-      const margin = 8;
-      const flipUp =
-        rect.bottom + menu.offsetHeight + margin > window.innerHeight &&
-        rect.top - menu.offsetHeight - margin > 0;
-      menu.classList.toggle("top-full", !flipUp);
-      menu.classList.toggle("mt-1", !flipUp);
-      menu.classList.toggle("bottom-full", flipUp);
-      menu.classList.toggle("mb-1", flipUp);
-    };
     for (const details of dropdowns) {
       details.addEventListener("toggle", () => {
         if (!details.open) {
@@ -320,17 +370,6 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
         placeMenu(details);
       });
     }
-    // rAF-coalesced so a live resize drag re-reads layout once per frame,
-    // not once per event, while the open menu still tracks the viewport.
-    window.addEventListener(
-      "resize",
-      rafThrottle(() => {
-        const open = dropdowns.find((details) => details.open);
-        if (open) {
-          placeMenu(open);
-        }
-      })
-    );
     // `data-md` is the base-less logical route; the raw-markdown endpoint is a
     // generated page route, so it's served under the deployment base like any
@@ -491,5 +530,8 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
         }
       }
     });
-  }
+  };
+  initPageActions();
+  document.addEventListener("astro:after-swap", initPageActions);
 </script>

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

@@ -42,8 +42,14 @@ const buttonClass =
 <script>
   import { track } from "./analytics-client.ts";
-  const root = document.querySelector("[data-blume-page-feedback]");
-  if (root) {
+  // Run on the initial load and again after every client-router swap, which
+  // rebuilds the rating widget from server-rendered markup — the handlers
+  // below always bind to the freshly swapped-in elements.
+  const initFeedback = () => {
+    const root = document.querySelector("[data-blume-page-feedback]");
+    if (!root) {
+      return;
+    }
     const actions = root.querySelector("[data-feedback-actions]");
     const thanks = root.querySelector("[data-feedback-thanks]");
     for (const button of root.querySelectorAll("[data-feedback-value]")) {
@@ -57,5 +63,8 @@ const buttonClass =
         thanks?.classList.remove("hidden");
       });
     }
-  }
+  };
+  initFeedback();
+  document.addEventListener("astro:after-swap", initFeedback);
 </script>

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

@@ -35,13 +35,14 @@ import { buildStructuredData } from "../../seo/jsonld.ts";
 import { normalizeXHandle } from "../../seo/x-handle.ts";
 import { withBase } from "../islands/base-path.ts";
 import "blume:theme";
+import { ClientRouter } from "astro:transitions";
 import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
 import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
-import { activeTabForRoute } from "./nav-utils.ts";
+import { currentTabForRoute } from "./nav-utils.ts";
 import WebMcp from "./WebMcp.astro";
 interface Props {
@@ -160,7 +161,7 @@ const searchLocale =
 const pageTitle = page?.title ?? site.title;
 const description = page?.description ?? site.description;
 const route = page?.route ?? "/";
-const activeTab = activeTabForRoute(navigation.tabs, route);
+const activeTab = currentTabForRoute(navigation.tabs, route, navigation.root);
 // Derive canonical + og:image from the site URL the same way the catch-all does
 // for content pages, so a custom page gets both for free. The matching OG card
@@ -230,6 +231,10 @@ 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, matching RootLayout: same-origin link clicks
+        swap the DOM in place instead of tearing the document down, so no
+        browser paints a blank frame between pages. */}
+    <ClientRouter />
     <title>{pageTitle}</title>
     <Favicon appleIcon={appleIcon} favicon={favicon} />
     <Fonts cssVars={fontCssVars ?? []} />

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

@@ -1,5 +1,6 @@
 ---
 import "blume:theme";
+import type { BlumeFavicon } from "../../core/data.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { FontHead } from "../../theme/fonts.ts";
@@ -15,6 +16,13 @@ import Header from "./Header.astro";
 // A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
 // on top, then a full-height region the reference mounts into. Unlike RootLayout
 // it has no docs sidebar/TOC/prose column, so the reference renders edge to edge.
+//
+// Deliberately NOT wired into the client router (`<ClientRouter />`): Scalar is
+// a SPA whose mount script runs once per real page load, so a client-side swap
+// back onto this page would leave the mount region empty (Astro never re-runs a
+// script it has already executed). Without the router's marker meta, the docs
+// pages' router falls back to a normal full load when navigating here — exactly
+// what a fresh Scalar mount needs.
 interface Props {
   site: { title: string; description?: string };
   logo?: {
@@ -25,14 +33,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 };