blume 1.5.2 → 1.5.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # blume
 
+## 1.5.3
+
+### Patch Changes
+
+- b6770b3: Fix fully unstyled frames during client-router navigations. Astro hoists the CSS of components rendered after the head has streamed (a page's MDX content, for one) into the body as stylesheet links, and the client router neither preloads nor persists body stylesheets — so swapping in a page painted a frame or two with no CSS applied before its sheet loaded. The layouts now load an incoming page's body stylesheets into the head and wait for them before the swap, and keep the loaded copy across it.
+
 ## 1.5.2
 
 ### Patch Changes

package/package.json

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

package/src/components/layout/PageLayout.astro

@@ -40,7 +40,11 @@ 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 {
+  BANNER_INIT_SCRIPT,
+  SWAP_STYLESHEET_INIT_SCRIPT,
+  THEME_INIT_SCRIPT,
+} from "./head-scripts.ts";
 import Header from "./Header.astro";
 import { currentTabForRoute } from "./nav-utils.ts";
 import WebMcp from "./WebMcp.astro";
@@ -235,6 +239,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         swap the DOM in place instead of tearing the document down, so no
         browser paints a blank frame between pages. */}
     <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 appleIcon={appleIcon} favicon={favicon} />
     <Fonts cssVars={fontCssVars ?? []} />

package/src/components/layout/RootLayout.astro

@@ -33,6 +33,7 @@ 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";
@@ -414,6 +415,9 @@ const bannerKey = banner?.dismissible ? banner.key : null;
         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 ?? []} />

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

@@ -41,6 +41,29 @@ export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.
  */
 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);}});})();`;
+
 /**
  * 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 —