blume 2.1.0 → 2.1.2

package/src/components/layout/PageActions.astro

@@ -89,6 +89,10 @@ const providers = (openInChat ?? openInChatProviders).map((key) => ({
 // keep that separator only while a configured list preserves v0 first.
 const chatSeparator = providers.length > 1 && providers[0]?.key === "v0";
 
+// The block renders once, for the right rail. Below `xl` the script moves it
+// into the mobile "On this page" dropdown, and the global styles below the
+// markup restyle it there from that container.
+
 // Top-level actions match the ToC links: flat, no background/padding, color
 // shift on hover only.
 const rowClass =
@@ -98,6 +102,8 @@ const rowClass =
 // background).
 const menuRowClass =
   "flex w-full items-center gap-2.5 rounded-md px-2 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground";
+const panelClass =
+  "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";
 ---
 
 <div
@@ -130,24 +136,24 @@ const menuRowClass =
     <span data-blume-copy-label>{a.copyMarkdown}</span>
   </button>
 
+  {/* Each chevron turns with its own <details> only: in the mobile dropdown
+      these nest inside the outline's <details>, and a `group-open` variant
+      would match that open ancestor too. */}
   {
     (exportPdf || exportEpub) && (
-      <details class="group relative" data-blume-dropdown>
+      <details class="relative" data-blume-dropdown>
         <summary
           class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
         >
           <Icon name="download" size={16} />
           {a.export}
           <Icon
-            class="ms-auto transition-transform group-open:rotate-180"
+            class="ms-auto transition-transform [details[open]>summary_&]: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
-        >
+        <div class={panelClass} data-blume-menu>
           {exportPdf && (
             <button class={menuRowClass} data-blume-export-pdf type="button">
               <Icon name="file" size={16} />
@@ -169,22 +175,19 @@ const menuRowClass =
 
   {
     providers.length > 0 && (
-      <details class="group relative" data-blume-dropdown>
+      <details class="relative" data-blume-dropdown>
         <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"
+            class="ms-auto transition-transform [details[open]>summary_&]: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
-        >
+        <div class={panelClass} data-blume-menu>
           {providers.map((provider, index) => (
             <>
               {index === 1 && chatSeparator && (
@@ -208,22 +211,19 @@ const menuRowClass =
 
   {
     mcpUrl && (
-      <details class="group relative" data-blume-dropdown>
+      <details class="relative" data-blume-dropdown>
         <summary
           class={`${rowClass} cursor-pointer list-none [&::-webkit-details-marker]:hidden`}
         >
           <Icon name="plug" size={16} />
           {a.connectMcp}
           <Icon
-            class="ms-auto transition-transform group-open:rotate-180"
+            class="ms-auto transition-transform [details[open]>summary_&]: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
-        >
+        <div class={panelClass} data-blume-menu>
           <button class={menuRowClass} data-mcp-copy-url type="button">
             <Icon name="link" size={16} />
             <span class="flex-1" data-mcp-url-label>
@@ -259,6 +259,45 @@ const menuRowClass =
   }
 </div>
 
+<style is:global>
+  /* Below `xl` the script moves the block into the mobile "On this page"
+     dropdown (see `placeActions`), where it reads like the outline above it:
+     under a rule, its rows padded like the outline's links, its groups
+     expanding in place under their row instead of floating, and without
+     Scroll to top, since that dropdown already sits at the top of the page. */
+  [data-blume-page-actions-mount] > [data-blume-page-actions] {
+    margin-top: 0;
+    border-top: 1px solid var(--blume-border);
+    padding: 0.5rem;
+  }
+  [data-blume-page-actions-mount] [data-blume-scroll-top] {
+    display: none;
+  }
+  [data-blume-page-actions-mount]
+    :is([data-blume-page-actions] > :is(a, button), summary) {
+    border-radius: 0.375rem;
+    padding-inline: 0.5rem;
+  }
+  [data-blume-page-actions-mount] [data-blume-menu] {
+    position: static;
+    width: auto;
+    min-width: 0;
+    max-width: none;
+    margin: 0;
+    margin-inline-start: 0.5rem;
+    border-width: 0;
+    border-inline-start-width: 1px;
+    border-radius: 0;
+    background-color: transparent;
+    padding: 0;
+    padding-inline-start: 0.5rem;
+    box-shadow: none;
+  }
+  [data-blume-page-actions-mount] [data-blume-menu] > :hover {
+    background-color: transparent;
+  }
+</style>
+
 <script>
   import { copyDeferredText, copyText, flashLabel } from "../copy-feedback.ts";
   import { installDropdownDismiss } from "../dropdown-dismiss.ts";
@@ -301,13 +340,42 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
   // for the EPUB: drop decorative SVGs and interactive controls (which render as
   // broken boxes in a reader), flatten Shiki's variable-colored code to plain
   // monospace text, and reveal panels the tab scripts would otherwise hide.
-  const buildEpubChapterHtml = (article: Element): string => {
+  // Links point at the site: a site-relative `/docs/page` means nothing inside
+  // the book, so every link but an in-page `#fragment` is made absolute.
+  const buildEpubChapterHtml = async (article: Element): Promise<string> => {
     const clone = article.cloneNode(true) as Element;
     for (const el of clone.querySelectorAll(
       "svg, button, select, script, style, link, noscript, template"
     )) {
       el.remove();
     }
+    for (const link of clone.querySelectorAll<HTMLAnchorElement>("a[href]")) {
+      if (!link.getAttribute("href")?.startsWith("#")) {
+        link.setAttribute("href", link.href);
+      }
+    }
+    // The generator fetches every image into the book, and one it can't fetch
+    // (a cross-origin image served without CORS headers, a 404) fails the
+    // whole export. Try each first, and leave out the ones that fail.
+    await Promise.all(
+      [...clone.querySelectorAll("img")].map(async (img) => {
+        if (!img.getAttribute("src")) {
+          return;
+        }
+        try {
+          const response = await fetch(img.src);
+          if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+          }
+        } catch (error) {
+          console.warn(
+            `[blume] EPUB export left out an image it couldn't fetch: ${img.src}`,
+            error
+          );
+          img.remove();
+        }
+      })
+    );
     for (const pre of clone.querySelectorAll("pre")) {
       const code = document.createElement("code");
       code.textContent = pre.textContent ?? "";
@@ -339,9 +407,11 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
     menu.classList.toggle("mb-1", flipUp);
   };
 
+  // Only the rail's floating dropdowns need placing; a group open in place in
+  // the mobile dropdown is not one (see `placeActions`).
   const openDropdown = () =>
     document.querySelector<HTMLDetailsElement>(
-      "[data-blume-page-actions] details[open]"
+      "[data-blume-page-actions] details[data-blume-dropdown][open]"
     );
 
   // rAF-coalesced so a live resize drag re-reads layout once per frame, not
@@ -362,6 +432,32 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
   // dropdown behavior (also the header language switcher and nav selectors).
   installDropdownDismiss();
 
+  // The page renders its one actions block in the right rail, which only
+  // shows at `xl`. Below that the block moves into the mobile "On this page"
+  // dropdown, into the empty mount the layout passes it as children, and
+  // back at `xl`; a moved node keeps its listeners, so nothing rebinds. In
+  // the dropdown its groups expand in place, so they drop out of the shared
+  // light-dismiss and the placement here (both keyed on
+  // `data-blume-dropdown`) until the block is back in the rail, and the
+  // styles above restyle it from the mount.
+  const railQuery = window.matchMedia("(min-width: 80rem)");
+  const placeActions = () => {
+    const root = document.querySelector("[data-blume-page-actions]");
+    const rail = railQuery.matches;
+    const home = document.querySelector(
+      rail ? "[data-blume-toc]" : "[data-blume-page-actions-mount]"
+    );
+    if (!(root && home) || root.parentElement === home) {
+      return;
+    }
+    // A group left open would reopen as the other kind of menu.
+    for (const details of root.querySelectorAll("details")) {
+      details.open = false;
+      details.toggleAttribute("data-blume-dropdown", rail);
+    }
+    home.append(root);
+  };
+
   // 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.
@@ -384,7 +480,9 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
             other.open = false;
           }
         }
-        placeMenu(details);
+        if (details.hasAttribute("data-blume-dropdown")) {
+          placeMenu(details);
+        }
       });
     }
 
@@ -537,10 +635,24 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
         const epubModule = await loadEpub();
         const epub = epubModule.default?.default ?? epubModule.default;
         // The article HTML already opens with the page's <h1>, so don't let the
-        // generator prepend a second chapter-title heading.
+        // generator prepend a second chapter-title heading. The book's
+        // language is the article's (a fallback page's content locale, else
+        // the page's), and the site is its author and publisher; left out,
+        // the generator says English and "anonymous". Its defaults are spread
+        // under these options, so an unknown value is omitted, not undefined.
+        const site = document
+          .querySelector('meta[property="og:site_name"]')
+          ?.getAttribute("content");
+        const lang = article.closest("[lang]")?.getAttribute("lang");
         const result = await epub(
-          { css: EPUB_STYLES, prependChapterTitles: false, title },
-          [{ content: buildEpubChapterHtml(article), title }]
+          {
+            css: EPUB_STYLES,
+            prependChapterTitles: false,
+            title,
+            ...(site && { author: site, publisher: site }),
+            ...(lang && { lang }),
+          },
+          [{ content: await buildEpubChapterHtml(article), title }]
         );
         const blob =
           result instanceof Blob
@@ -572,5 +684,8 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
   };
 
   initPageActions();
+  placeActions();
   document.addEventListener("astro:after-swap", initPageActions);
+  document.addEventListener("astro:after-swap", placeActions);
+  railQuery.addEventListener("change", placeActions);
 </script>

package/src/components/layout/PageLayout.astro

@@ -126,10 +126,17 @@ interface Props {
   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.
+   * WebSite node, plus a WebPage node on the homepage and an article node on
+   * other routes. Defaults to on, matching RootLayout.
    */
   structuredDataEnabled?: boolean;
+  /**
+   * When the page last changed, emitted as the JSON-LD `dateModified`. A
+   * custom page has no content file to date, so pass it by hand; without a
+   * machine-readable date, search engines take whatever other date the page
+   * shows.
+   */
+  lastModified?: string | Date | null;
   /**
    * Which agent-discovery resources exist, advertised as `describedby` head
    * links plus the AI Catalog/ARD pair — the same `DiscoveryLinks` partial
@@ -184,6 +191,7 @@ const {
   ogImageSize,
   canonical,
   structuredDataEnabled,
+  lastModified,
   discovery = data.config.discovery,
   x,
   noindex,
@@ -279,7 +287,8 @@ 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.
+// page has no breadcrumb trail; the home route is a WebPage, dated by
+// `lastModified` when the page passes one.
 const structuredData =
   structuredDataEnabled === false || noindex
     ? null
@@ -289,6 +298,7 @@ const structuredData =
       description,
       identity: data.config.identity,
       locale,
+      modified: lastModified,
       route,
       siteName: site.title,
       siteUrl: siteUrl ?? null,

package/src/components/layout/RootLayout.astro

@@ -432,10 +432,13 @@ const description = page.description ?? site.description;
 // pages (and the changelog index, which has no `type`) stay `website`.
 const ogType =
   pageType === "blog" || pageType === "changelog" ? "article" : "website";
+// The last-modified date as ISO 8601, parsed once for every surface that
+// carries it; undefined when absent or unparseable.
+const lastModifiedIso = toIso(lastModified);
 // `article:*` timestamps only belong on an article; a docs page carrying them
 // would be declaring properties its `og:type` doesn't define.
 const articlePublished = ogType === "article" ? toIso(published) : undefined;
-const articleModified = ogType === "article" ? toIso(lastModified) : undefined;
+const articleModified = ogType === "article" ? lastModifiedIso : undefined;
 // X sizes the card from `twitter:card`: a large image needs the wide variant,
 // and a page with no image still gets a card (the compact `summary`) rather
 // than rendering as a bare link.
@@ -448,14 +451,12 @@ const xCreator = normalizeXHandle(x?.creator);
 
 // "Last updated on <date>" — the configured `dateFormat`, in UTC (unless the
 // config names a zone) so it matches the changelog timeline.
-const lastModifiedDate = lastModified ? new Date(lastModified) : null;
-const formattedLastModified =
-  lastModifiedDate && !Number.isNaN(lastModifiedDate.getTime())
-    ? new Intl.DateTimeFormat(
-        locale || "en",
-        resolveDateFormatOptions(dateFormat)
-      ).format(lastModifiedDate)
-    : null;
+const formattedLastModified = lastModifiedIso
+  ? new Intl.DateTimeFormat(
+      locale || "en",
+      resolveDateFormatOptions(dateFormat)
+    ).format(new Date(lastModifiedIso))
+  : null;
 
 // This page's raw-Markdown mirror, advertised as a `text/markdown` alternate
 // in the head. Content routes always have one (see `markdownRoutePaths`, which
@@ -521,6 +522,7 @@ const structuredData =
       base: import.meta.env.BASE_URL,
       breadcrumbs: crumbs,
       description,
+      homeRoute: navigation.root,
       identity: data.config.identity,
       locale,
       modified: lastModified,
@@ -868,13 +870,20 @@ const localeRedirect = localeTargets
             />
           )
         }
+        {/* Below `xl`, where the rail is hidden, the page actions ride in
+            the "On this page" dropdown, so it renders wherever the rail
+            would, with or without headings. They render once, in the rail:
+            the dropdown gets an empty mount the actions script moves them
+            into (see PageActions.astro). */}
         {
-          hasToc && (
+          showToc && (
             <TableOfContentsSlot
               headings={tocHeadings}
               title={strings.toc.title}
               variant="mobile"
-            />
+            >
+              <div data-blume-page-actions-mount />
+            </TableOfContentsSlot>
           )
         }
         <PageHeaderSlot headings={tocHeadings} page={page} route={page.route} />
@@ -911,6 +920,7 @@ const localeRedirect = localeTargets
                 (apiRail || modeLayout.width === "full") && "[&>*]:max-w-none",
                 modeLayout.width === "center" && "[&>*]:max-w-[54rem]",
               ]}
+              data-blume-page-end
             >
               {directoryGroup && <Directory group={directoryGroup} />}
               <RelatedPages links={relatedItems} title={strings.page.related} />
@@ -921,7 +931,7 @@ const localeRedirect = localeTargets
               />
               {formattedLastModified && (
                 <p class="mx-auto mt-10 max-w-content text-muted-foreground text-sm">
-                  {strings.page.lastUpdated} {formattedLastModified}
+                  {strings.page.lastUpdated} <time datetime={lastModifiedIso}>{formattedLastModified}</time>
                 </p>
               )}
               {feedback && (
@@ -1370,10 +1380,13 @@ const localeRedirect = localeTargets
       }
       @media (prefers-reduced-motion: reduce) {
         /* html prefix outranks the library's rules regardless of sheet
-           order; its transition declarations carry !important. */
+           order; its transition declarations carry !important. Near-instant,
+           never `none`: medium-zoom only finishes opening and closing on the
+           image's `transitionend`, so with no transition a zoomed image
+           ignores Escape, clicks, and scrolls forever. */
         html .medium-zoom-image,
         html .medium-zoom-overlay {
-          transition: none !important;
+          transition-duration: 1ms !important;
         }
       }
     </style>

package/src/components/layout/Search.astro

@@ -4,6 +4,7 @@ import data from "blume:data";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import type { Navigation } from "../../core/types.ts";
+import { scopesLocales } from "../../search/adapters/locale-scope.ts";
 import { scopesVersions } from "../../search/adapters/version-scope.ts";
 import { resolvePopularIconMarkup } from "../../search/popular-icon.ts";
 import Icon from "../Icon.astro";
@@ -36,9 +37,15 @@ const {
   navigation,
   popularPages,
   strings,
-  locale,
+  locale: viewedLocale,
   version: viewedVersion = null,
 } = Astro.props;
+// Mixedbread searches every language whatever the dialog asks, so on it an
+// "All languages" toggle would change nothing: treat the site as
+// single-language for search instead.
+const locale = scopesLocales(data.config.search.provider)
+  ? viewedLocale
+  : undefined;
 // Pagefind, Orama Cloud, and Mixedbread search every version whatever the
 // dialog asks, so on those an "All versions" toggle would change nothing:
 // treat the site as unversioned for search instead.
@@ -90,6 +97,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
   data-i18n-popular={s.popular}
   data-i18n-results={s.results}
   data-locale={locale || undefined}
+  data-redact-queries={data.config.search.analytics.queries ? undefined : ""}
   data-version={version ?? undefined}
   data-versioned={version === null ? undefined : ""}
 >
@@ -240,6 +248,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
     import { track } from "./analytics-client.ts";
     import { createSearchTracker } from "./search/analytics.ts";
+    import type { SearchTracker } from "./search/analytics.ts";
     import { highlight, matchSnippet } from "./search/types.ts";
     import type { SearchFn, SearchHit } from "./search/types.ts";
 
@@ -306,7 +315,8 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       searchClient ??= (async () => {
         try {
           const { createSearch } = await import("blume:search-client");
-          return await createSearch();
+          // The reader types each query, so each supersedes the last.
+          return await createSearch({ typing: true });
         } catch (error) {
           searchClient = undefined;
           throw error;
@@ -325,7 +335,7 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       preview!: HTMLElement;
       searchFn: SearchFn | null = null;
       /** Records settled queries and picked results (search/analytics.ts). */
-      tracker = createSearchTracker(track);
+      tracker!: SearchTracker;
       loaded = false;
       loadFailed = false;
       /** First-open client/index load still in flight. */
@@ -419,6 +429,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.message = this.querySelector("[data-blume-search-message]")!;
         this.preview = this.querySelector("[data-blume-search-preview]")!;
         this.assistantEnabled = this.hasAttribute("data-ask");
+        // `search.analytics.queries: false` keeps query text off providers.
+        this.tracker = createSearchTracker(track, {
+          queries: !this.hasAttribute("data-redact-queries"),
+        });
 
         const popularScript = this.querySelector(
           "[data-blume-search-popular]"

package/src/components/layout/TableOfContents.astro

@@ -15,10 +15,14 @@ interface Props {
 }
 
 const { headings, title, variant } = Astro.props;
+// The mobile dropdown also holds what the layout passes as children (the
+// mount the page actions move into below `xl`, where the rail that renders
+// them is hidden), so a page with actions but no headings still gets it.
+const hasChildren = Astro.slots.has("default");
 ---
 
 {
-  headings.length > 0 && variant === "mobile" && (
+  (headings.length > 0 || hasChildren) && variant === "mobile" && (
     <details class="group mx-auto mb-6 max-w-content rounded-blume border border-border xl:hidden">
       <summary class="flex cursor-pointer list-none items-center justify-between gap-2 px-4 py-3 font-medium text-foreground text-sm [&::-webkit-details-marker]:hidden">
         <span>{title}</span>
@@ -28,23 +32,26 @@ const { headings, title, variant } = Astro.props;
           size={16}
         />
       </summary>
-      <blume-toc class="block">
-        <ul class="m-0 list-none border-border border-t p-2">
-          {headings.map((heading) => (
-            <li
-              data-depth={heading.depth}
-              style={`padding-inline-start:${(heading.depth - 2) * 0.75}rem`}
-            >
-              <a
-                class="block rounded-md px-2 py-1.5 text-muted-foreground text-sm transition-colors hover:text-foreground aria-[current=location]:font-medium aria-[current=location]:text-foreground"
-                href={`#${heading.slug}`}
+      {headings.length > 0 && (
+        <blume-toc class="block">
+          <ul class="m-0 list-none border-border border-t p-2">
+            {headings.map((heading) => (
+              <li
+                data-depth={heading.depth}
+                style={`padding-inline-start:${(heading.depth - 2) * 0.75}rem`}
               >
-                {heading.text}
-              </a>
-            </li>
-          ))}
-        </ul>
-      </blume-toc>
+                <a
+                  class="block rounded-md px-2 py-1.5 text-muted-foreground text-sm transition-colors hover:text-foreground aria-[current=location]:font-medium aria-[current=location]:text-foreground"
+                  href={`#${heading.slug}`}
+                >
+                  {heading.text}
+                </a>
+              </li>
+            ))}
+          </ul>
+        </blume-toc>
+      )}
+      <slot />
     </details>
   )
 }

package/src/components/layout/analytics-client.ts

@@ -2,14 +2,14 @@
  * Send a custom analytics event to every analytics platform configured in
  * `blume.config.ts`. Mirrors the adapters `Analytics.astro` wires
  * (`src/analytics/*`): each one with a custom-event API is called through the
- * global its snippet defines (Cloudflare and Clearbit have none to forward
- * to), and the `blume:track` CustomEvent fires unconditionally so a project
- * can bridge the event to anything else — a `script()` adapter, say. Every
- * call no-ops cleanly when a provider isn't present — for example during
- * `blume dev`, where `Analytics.astro` injects nothing — and a provider that
- * throws (a consent shim that stubs `gtag` with a raise, a broken snippet) is
- * isolated so it neither starves the providers after it nor surfaces in the
- * feature that reported the event.
+ * global its snippet defines (Cloudflare, Clearbit, and Clics have none to
+ * forward to), and the `blume:track` CustomEvent fires unconditionally so a
+ * project can bridge the event to anything else — a `script()` adapter, say.
+ * Every call no-ops cleanly when a provider isn't present — for example
+ * during `blume dev`, where `Analytics.astro` injects nothing — and a provider
+ * that throws (a consent shim that stubs `gtag` with a raise, a broken
+ * snippet) is isolated so it neither starves the providers after it nor
+ * surfaces in the feature that reported the event.
  */
 import { track as vercelTrack } from "@vercel/analytics";
 

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

@@ -44,8 +44,13 @@
  * stored preference instead of aborting before the swap listeners exist, and
  * after a swap the theme the `before-swap` stamp carried over stands, so a
  * toggle the reader made still holds for the rest of their visit.
+ *
+ * Paper is white, so a dark page prints light: `beforeprint` switches the root
+ * to the light theme (every token, Shiki color, and `dark:` utility follows
+ * it) and `afterprint` puts the dark theme back. The listeners sit on
+ * `window`, so the one registration outlives client-router swaps.
  */
-export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const apply=()=>{const r=document.documentElement;let s=null;let blocked=false;try{s=localStorage.getItem("blume-theme");}catch{blocked=true;}const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";r.dataset.theme=s??(blocked&&r.dataset.theme?r.dataset.theme:m==="system"?sys:m);};apply();document.addEventListener("astro:before-swap",(e)=>{const t=document.documentElement.dataset.theme;if(t){e.newDocument.documentElement.dataset.theme=t;}});document.addEventListener("astro:after-swap",apply);})();`;
+export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const apply=()=>{const r=document.documentElement;let s=null;let blocked=false;try{s=localStorage.getItem("blume-theme");}catch{blocked=true;}const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";r.dataset.theme=s??(blocked&&r.dataset.theme?r.dataset.theme:m==="system"?sys:m);};apply();document.addEventListener("astro:before-swap",(e)=>{const t=document.documentElement.dataset.theme;if(t){e.newDocument.documentElement.dataset.theme=t;}});document.addEventListener("astro:after-swap",apply);let printed=null;addEventListener("beforeprint",()=>{const r=document.documentElement;if(r.dataset.theme==="dark"){printed="dark";r.dataset.theme="light";}});addEventListener("afterprint",()=>{if(printed){document.documentElement.dataset.theme=printed;printed=null;}});})();`;
 
 /**
  * Keep an embedded Scalar reference on Blume's theme. Scalar picks its own

package/src/components/layout/search/algolia.ts

@@ -48,7 +48,16 @@ export const createSearch = (opts: AlgoliaOptions): SearchFn => {
     // shape, so hits returned by that index carry those fields.
     const records =
       first && "hits" in first ? (first.hits as AlgoliaRecord[]) : [];
-    const hits = records.map((record) => ({
+    // The sync splits a long page across records that share its `url`. The
+    // index's `distinct` returns one of them, unless the site set its own
+    // `attributeForDistinct`; either way a page is listed once.
+    const pages = new Set<string>();
+    const unique = records.filter((record) => {
+      const seen = pages.has(record.url);
+      pages.add(record.url);
+      return !seen;
+    });
+    const hits = unique.map((record) => ({
       content: record.content ?? "",
       excerpt: highlight(
         excerptFor(record.description ?? "", record.content ?? "", query),