blume 1.5.0 → 1.5.2

package/src/components/layout/PageActions.astro

@@ -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

@@ -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

@@ -24,22 +24,25 @@ import type {
 } 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";
 import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
 import {
   OG_IMAGE_HEIGHT,
   OG_IMAGE_TYPE,
   OG_IMAGE_WIDTH,
 } from "../../og/dimensions.ts";
+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 {
@@ -57,7 +60,7 @@ interface Props {
    */
   page?: { title?: string; description?: string; route?: string };
   themeMode: "system" | "light" | "dark";
-  fontCssVars?: string[];
+  fontCssVars?: (string | FontHead)[];
   searchEnabled: boolean;
   /**
    * Opt this page out of the header's Ask AI trigger. Defaults to whether Ask
@@ -75,7 +78,24 @@ interface Props {
   ogEnabled?: boolean;
   /** SEO overrides; a marketing page often sets its own canonical/og image. */
   ogImage?: string | null;
+  /**
+   * Alt text for a user-supplied `ogImage`, emitted as `og:image:alt` /
+   * `twitter:image:alt`. The generated card derives its own from the title.
+   */
+  ogImageAlt?: string;
+  /**
+   * Pixel size of a user-supplied `ogImage`, emitted as `og:image:width` /
+   * `og:image:height` so crawlers can lay the card out before fetching it.
+   * The generated card declares its known size automatically.
+   */
+  ogImageSize?: { height: number; width: number };
   canonical?: string | null;
+  /**
+   * Emit schema.org JSON-LD for this page (`data.config.structuredData`) — a
+   * WebSite node, plus an article node on non-root routes. Defaults to on,
+   * matching RootLayout.
+   */
+  structuredDataEnabled?: boolean;
   /**
    * X (Twitter) attribution (`data.config.x`): the site's account and an author
    * handle, emitted as `twitter:site`/`twitter:creator`.
@@ -113,7 +133,10 @@ const {
   siteUrl,
   ogEnabled,
   ogImage,
+  ogImageAlt,
+  ogImageSize,
   canonical,
+  structuredDataEnabled,
   x,
   noindex,
   locale = "en",
@@ -138,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
@@ -153,11 +176,12 @@ const basedRoute = withBase(route);
 // don't come out double-slashed — the catch-all strips it the same way.
 const siteBase = siteUrl ? siteUrl.replace(/\/$/u, "") : null;
 // The route-derived part is percent-encoded (the sitemap convention) so a
-// Unicode route slug yields a legal URI that byte-matches the sitemap <loc>.
+// Unicode route slug yields a legal URI that byte-matches the sitemap <loc> —
+// including the root, whose <loc> is `https://site/` with the slash.
 const resolvedCanonical =
   canonical ??
   (siteBase
-    ? `${siteBase}${basedRoute === "/" ? "" : encodeURI(basedRoute)}`
+    ? `${siteBase}${basedRoute === "/" ? "/" : encodeURI(basedRoute)}`
     : null);
 // An explicit `ogImage` wins. A root-relative path (e.g. an image dropped in
 // `public/`) is resolved against the site URL so crawlers get an absolute
@@ -180,6 +204,25 @@ const twitterCard = resolvedOgImage ? "summary_large_image" : "summary";
 const xSite = normalizeXHandle(x?.handle);
 const xCreator = normalizeXHandle(x?.creator);
 
+// JSON-LD, mirroring RootLayout: skipped when disabled or noindexed. A custom
+// page has no breadcrumb trail; the home route yields the WebSite node alone.
+const structuredData =
+  structuredDataEnabled === false || noindex
+    ? null
+    : buildStructuredData({
+      base: import.meta.env.BASE_URL,
+      breadcrumbs: [],
+      description,
+      locale,
+      route,
+      siteName: site.title,
+      siteUrl: siteUrl ?? null,
+      title: pageTitle,
+    });
+const structuredDataJson = structuredData
+  ? JSON.stringify(structuredData).replaceAll("<", "\\u003c")
+  : null;
+
 const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
@@ -188,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 ?? []} />
@@ -218,8 +265,26 @@ const bannerKey = banner?.dismissible ? banner.key : null;
               <meta content={pageTitle} property="og:image:alt" />
             </>
           )}
+          {!ogGenerated && ogImageSize && (
+            <>
+              <meta
+                content={String(ogImageSize.width)}
+                property="og:image:width"
+              />
+              <meta
+                content={String(ogImageSize.height)}
+                property="og:image:height"
+              />
+            </>
+          )}
+          {!ogGenerated && ogImageAlt && (
+            <meta content={ogImageAlt} property="og:image:alt" />
+          )}
           <meta content={resolvedOgImage} name="twitter:image" />
           {ogGenerated && <meta content={pageTitle} name="twitter:image:alt" />}
+          {!ogGenerated && ogImageAlt && (
+            <meta content={ogImageAlt} name="twitter:image:alt" />
+          )}
         </>
       )
     }
@@ -228,6 +293,15 @@ const bannerKey = banner?.dismissible ? banner.key : null;
     {description && <meta content={description} name="twitter:description" />}
     {xSite && <meta content={xSite} name="twitter:site" />}
     {xCreator && <meta content={xCreator} name="twitter:creator" />}
+    {
+      structuredDataJson && (
+        <script
+          is:inline
+          set:html={structuredDataJson}
+          type="application/ld+json"
+        />
+      )
+    }
     {
       bannerKey && (
         <script data-key={bannerKey} is:inline set:html={BANNER_INIT_SCRIPT} />

package/src/components/layout/ReferenceLayout.astro

@@ -1,7 +1,9 @@
 ---
 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";
 import type { Navigation } from "../../core/types.ts";
 import Analytics from "./Analytics.astro";
 import WebMcp from "./WebMcp.astro";
@@ -14,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?: {
@@ -24,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 };
@@ -51,7 +54,7 @@ interface Props {
   navigation: Navigation;
   route: string;
   themeMode: "system" | "light" | "dark";
-  fontCssVars?: string[];
+  fontCssVars?: (string | FontHead)[];
   searchEnabled: boolean;
   pageTitle: string;
   /** Keep the reference route out of crawler indexes. */