blume 1.4.3 → 1.5.1

package/src/components/layout/Header.astro

@@ -5,7 +5,11 @@ import { withBase } from "../islands/base-path.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
-import type { LocaleSwitchOption, Navigation } from "../../core/types.ts";
+import type {
+  LocaleSwitchOption,
+  Navigation,
+  NavSelector as NavSelectorConfig,
+} from "../../core/types.ts";
 import { GITHUB_MARK } from "../github-mark.ts";
 import Icon from "../Icon.astro";
 import LanguageSwitcher from "./LanguageSwitcher.astro";
@@ -50,8 +54,16 @@ interface Props {
   /** Localized chrome labels (nav toggle, sections, GitHub, theme toggle). */
   navStrings?: UIStrings["nav"];
   localeSwitch?: LocaleSwitchOption[];
+  /**
+   * Auto-populated version switcher, rendered ahead of the configured
+   * selectors. `null`/absent when versioning is off — or when the user
+   * declares their own `kind: "version"` selector, which then owns the UI.
+   */
+  versionSelector?: NavSelectorConfig | null;
   /** Active locale for per-language search filtering. */
   searchLocale?: string;
+  /** Viewed docs version for search filtering (`""` = current; `null`/absent = off). */
+  searchVersion?: string | null;
   /**
    * Layout-slot overrides forwarded from the root layout. The header honors
    * `Logo` and `Search` here so those pieces can be replaced without swapping
@@ -77,7 +89,9 @@ const {
   switcherStrings,
   navStrings,
   localeSwitch,
+  versionSelector,
   searchLocale,
+  searchVersion = null,
   layout = {},
 } = Astro.props;
 
@@ -167,6 +181,15 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
     )
   }
   <div class="flex-1"></div>
+  {
+    /* Right-aligned next to the language switcher: the spacer absorbs its
+       width, so pages without a version selector (blog, generated references)
+       keep the logo, tabs, and the rest of this cluster in place — no layout
+       shift when crossing into the docs. */
+    versionSelector && (
+      <NavSelector align="end" route={route} selector={versionSelector} />
+    )
+  }
   {
     localeSwitch && localeSwitch.length > 1 && (
       <LanguageSwitcher
@@ -184,6 +207,7 @@ const clickScript = `(()=>{const dr=()=>{const h=document.querySelector("[data-b
         navigation={navigation}
         popularPages={data.config.search.popular}
         strings={searchStrings}
+        version={searchVersion}
       />
     )
   }

package/src/components/layout/NavSelector.astro

@@ -11,9 +11,16 @@ import { isUnderPath } from "./nav-utils.ts";
 interface Props {
   selector: NavSelector;
   route: string;
+  /**
+   * Which edge the dropdown panel anchors to. `start` (the default) suits the
+   * header's leading selector group; the version selector sits at the trailing
+   * edge next to the language switcher, where a start-anchored panel would
+   * overflow the viewport — pass `end` there.
+   */
+  align?: "start" | "end";
 }
 
-const { selector, route } = Astro.props;
+const { selector, route, align = "start" } = Astro.props;
 
 // The active item is the deepest path the current route sits under (on a path
 // boundary, so `/api` never claims `/api-reference` routes), falling back to
@@ -46,7 +53,9 @@ const menuRowClass =
           size={14}
         />
       </summary>
-      <div class="absolute start-0 z-50 mt-2 min-w-56 rounded-blume border border-border bg-background p-1 shadow-xl">
+      <div
+        class={`absolute z-50 mt-2 min-w-56 rounded-blume border border-border bg-background p-1 shadow-xl ${align === "end" ? "end-0" : "start-0"}`}
+      >
         {selector.items.map((item) => (
           <a
             aria-current={item.path === active?.path ? "true" : undefined}

package/src/components/layout/NavTree.astro

@@ -45,8 +45,8 @@ const n = { ...EN_UI.nav, ...strings };
 const badgeBase =
   "shrink-0 rounded-full px-1.5 py-0.5 font-medium text-[0.65rem] leading-none";
 const badgeClass = `${badgeBase} bg-muted text-muted-foreground`;
-// HTTP-method badges (from an OpenAPI reference's sidebar) are color-coded;
-// every other badge keeps the neutral style.
+// HTTP-method and AsyncAPI-action badges (from a reference's sidebar) are
+// color-coded to match MethodBadge; every other badge keeps the neutral style.
 const METHOD_BADGE: Record<string, string> = {
   DELETE: "bg-red-500/15 text-red-700 dark:text-red-300",
   GET: "bg-green-500/15 text-green-700 dark:text-green-300",
@@ -55,6 +55,8 @@ const METHOD_BADGE: Record<string, string> = {
   PATCH: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
   POST: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
   PUT: "bg-orange-500/15 text-orange-700 dark:text-orange-300",
+  RECEIVE: "bg-teal-500/15 text-teal-700 dark:text-teal-300",
+  SEND: "bg-violet-500/15 text-violet-700 dark:text-violet-300",
 };
 const badgeClassFor = (badge: string): string => {
   const method = METHOD_BADGE[badge.toUpperCase()];

package/src/components/layout/PageLayout.astro

@@ -24,12 +24,14 @@ 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";
@@ -57,7 +59,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 +77,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 +132,10 @@ const {
   siteUrl,
   ogEnabled,
   ogImage,
+  ogImageAlt,
+  ogImageSize,
   canonical,
+  structuredDataEnabled,
   x,
   noindex,
   locale = "en",
@@ -153,11 +175,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 +203,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;
 ---
 
@@ -218,8 +260,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 +288,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

@@ -2,6 +2,7 @@
 import "blume:theme";
 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";
@@ -51,7 +52,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. */

package/src/components/layout/RootLayout.astro

@@ -8,8 +8,10 @@ import type {
   Heading,
   LocaleSwitchOption,
   Navigation,
+  NavSelector as NavSelectorType,
 } from "../../core/types.ts";
 import "blume:theme";
+import type { FontHead } from "../../theme/fonts.ts";
 import type { ComponentOverride } from "../../core/define-components.ts";
 import {
   OG_IMAGE_HEIGHT,
@@ -46,6 +48,7 @@ import PageActions from "./PageActions.astro";
 import PageFeedback from "./PageFeedback.astro";
 import Pagination from "./Pagination.astro";
 import TableOfContents from "./TableOfContents.astro";
+import VersionBanner from "./VersionBanner.astro";
 
 interface Props {
   site: { title: string; description?: string };
@@ -88,7 +91,7 @@ interface Props {
   imageZoom?: boolean;
   codeWrap?: boolean;
   themeMode: "system" | "light" | "dark";
-  fontCssVars?: string[];
+  fontCssVars?: (string | FontHead)[];
   searchEnabled: boolean;
   indexable: boolean;
   ogImage?: string | null;
@@ -149,6 +152,16 @@ interface Props {
   xDefault?: string | null;
   /** Language-switcher entries for the current page. */
   localeSwitch?: LocaleSwitchOption[];
+  /** Auto-populated version switcher (`null` when versioning is off or a user selector owns it). */
+  versionSelector?: NavSelectorType | null;
+  /** Old-version notice for archived pages (`null` on current-docs pages). */
+  versionNotice?: {
+    message: string;
+    latestHref: string;
+    latestLabel: string;
+  } | null;
+  /** Viewed docs version for search filtering (`""` = current; `null`/absent = off). */
+  searchVersion?: string | null;
   /**
    * User layout-slot overrides from `components.ts` (`defineComponents`). Each
    * key replaces the matching built-in; unknown keys are ignored. Wired slots:
@@ -220,6 +233,9 @@ const {
   localeAlternates,
   xDefault,
   localeSwitch,
+  versionSelector,
+  versionNotice,
+  searchVersion = null,
   layout = {},
   clientData,
   toc = { enabled: true, maxLevel: 3, minLevel: 2 },
@@ -499,16 +515,19 @@ const bannerKey = banner?.dismissible ? banner.key : null;
       href="#blume-content">{strings.page.skipToContent}</a
     >
     <Banner banner={banner} strings={strings.banner} />
+    <VersionBanner notice={versionNotice ?? null} />
     <HeaderSlot
       askEnabled={askEnabled}
       askStrings={strings.ask}
       layout={layout}
       localeSwitch={localeSwitch}
+      versionSelector={versionSelector}
       logo={logo}
       navigation={navigation}
       route={page.route}
       searchEnabled={searchEnabled}
       searchLocale={searchLocale}
+      searchVersion={searchVersion}
       navStrings={navStrings}
       searchStrings={strings.search}
       site={site}

package/src/components/layout/Search.astro

@@ -19,10 +19,21 @@ interface Props {
   strings?: UIStrings["search"];
   /** Active locale to filter results to; omitted disables locale filtering. */
   locale?: string;
+  /**
+   * Docs version to filter results to (`""` = the current docs — a meaningful
+   * value, so `null`/omitted is what disables version filtering).
+   */
+  version?: string | null;
 }
 
-const { askEnabled = false, navigation, popularPages, strings, locale } =
-  Astro.props;
+const {
+  askEnabled = false,
+  navigation,
+  popularPages,
+  strings,
+  locale,
+  version = null,
+} = Astro.props;
 // Merge over the English baseline per key (rather than `strings ?? …`) so a
 // partial — or empty `{}` — strings object still resolves every label to a
 // default, matching the pattern PageActions uses for its own dictionary.
@@ -59,13 +70,15 @@ 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-version={version ?? undefined}
+  data-versioned={version === null ? undefined : ""}
 >
   {/* The label and shortcut hint wait until `lg`: below it the hamburger and
       inline tab bar share the header row, and a full-width search field would
       press into the language switcher. */}
   <button
     aria-label={s.button}
-    class="inline-flex h-9 cursor-pointer items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground lg:min-w-48"
+    class="inline-flex h-9 cursor-pointer items-center gap-2 rounded-full border border-border bg-background px-3 text-muted-foreground text-sm transition-colors hover:border-foreground hover:text-foreground lg:min-w-40"
     data-blume-search-open
     type="button"
   >
@@ -135,15 +148,29 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       class="flex items-center justify-between gap-3 border-border border-t px-3 py-2 text-muted-foreground text-xs"
     >
       {
-        locale ? (
-          <label class="flex cursor-pointer select-none items-center gap-1.5">
-            <input
-              class="size-3.5 accent-accent"
-              data-blume-search-all-locales
-              type="checkbox"
-            />
-            {s.allLanguages}
-          </label>
+        locale || version !== null ? (
+          <span class="flex items-center gap-3">
+            {locale && (
+              <label class="flex cursor-pointer select-none items-center gap-1.5">
+                <input
+                  class="size-3.5 accent-accent"
+                  data-blume-search-all-locales
+                  type="checkbox"
+                />
+                {s.allLanguages}
+              </label>
+            )}
+            {version !== null && (
+              <label class="flex cursor-pointer select-none items-center gap-1.5">
+                <input
+                  class="size-3.5 accent-accent"
+                  data-blume-search-all-versions
+                  type="checkbox"
+                />
+                {s.allVersions}
+              </label>
+            )}
+          </span>
         ) : (
           <span />
         )
@@ -268,6 +295,11 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
       // reader has opted to search across every language instead.
       locale: string | null = null;
       allLocales = false;
+      // The viewed docs version ("" = current; null when versioning is off),
+      // and the opt-in to search across every version.
+      versioned = false;
+      version = "";
+      allVersions = false;
 
       connectedCallback() {
         this.devOnlyMsg =
@@ -284,6 +316,10 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         this.resultsMsg =
           this.getAttribute("data-i18n-results") || this.resultsMsg;
         this.locale = this.getAttribute("data-locale");
+        // "" (the current docs) is a real version value, so a presence flag —
+        // not the attribute's truthiness — decides whether filtering is on.
+        this.versioned = this.hasAttribute("data-versioned");
+        this.version = this.getAttribute("data-version") ?? "";
         this.dialog = this.querySelector("[data-blume-search-dialog]")!;
         this.input = this.querySelector("[data-blume-search-input]")!;
         this.grid = this.querySelector("[data-blume-search-grid]")!;
@@ -323,6 +359,25 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
           });
         }
 
+        // Per-version filtering mirrors the locale toggle: default to the
+        // viewed version, with a remembered opt-in to search every version.
+        const allVersionsToggle = this.querySelector<HTMLInputElement>(
+          "[data-blume-search-all-versions]"
+        );
+        if (allVersionsToggle) {
+          this.allVersions =
+            readStorage("blume-search-all-versions") === "1";
+          allVersionsToggle.checked = this.allVersions;
+          allVersionsToggle.addEventListener("change", () => {
+            this.allVersions = allVersionsToggle.checked;
+            writeStorage(
+              "blume-search-all-versions",
+              this.allVersions ? "1" : "0"
+            );
+            this.render();
+          });
+        }
+
         // The handlers accept both ⌘ and Ctrl chords; show the right modifier
         // per platform on the button hint and the footer's preview hint.
         const isApple = /mac|iphone|ipad|ipod/iu.test(navigator.platform);
@@ -483,11 +538,14 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
 
         const localeFilter =
           this.locale && !this.allLocales ? this.locale : undefined;
+        const versionFilter =
+          this.versioned && !this.allVersions ? this.version : undefined;
         let result: Awaited<ReturnType<SearchFn>>;
         try {
           result = await this.searchFn(query, {
             locale: localeFilter,
             section: this.activeSection ?? undefined,
+            version: versionFilter,
           });
         } catch {
           // A hosted provider can reject (network error, outage); the results
@@ -636,10 +694,16 @@ const kbd = "rounded border border-border bg-muted px-1 py-0.5 font-mono";
         const excerpt = hit.excerpt
           ? `<span class="mt-0.5 line-clamp-2 text-muted-foreground text-xs">${hit.excerpt}</span>`
           : "";
+        // A cross-version hit (all-versions search) names its version so the
+        // reader knows they're about to leave the docs they're viewing.
+        const versionTag =
+          this.versioned && hit.version !== undefined && hit.version !== this.version
+            ? `<span class="ms-2 inline-block rounded-full bg-muted px-1.5 py-0.5 align-middle text-[0.65rem] text-muted-foreground">${escapeHtml(hit.version || "latest")}</span>`
+            : "";
         el.innerHTML = `
           <span class="mt-0.5 shrink-0 text-muted-foreground">${svg("file")}</span>
           <span class="flex-1">
-            <span class="block truncate font-normal text-foreground text-sm">${hit.title}</span>
+            <span class="block truncate font-normal text-foreground text-sm">${hit.title}${versionTag}</span>
             ${excerpt}
           </span>`;
         const item: Selectable = { el, hit, kind: "link", url: href };

package/src/components/layout/VersionBanner.astro

@@ -0,0 +1,39 @@
+---
+import { withBase } from "../islands/base-path.ts";
+import Icon from "../Icon.astro";
+
+// The "you're viewing an old version" notice, shared by RootLayout and
+// ReferenceLayout so every shell shows the same bar on archived pages. Unlike
+// the announcement Banner it is never dismissible — the reader should know
+// they're on frozen docs for as long as they are. The message and link label
+// arrive fully resolved (localized, `{version}` substituted) from the
+// catch-all, so this component carries no string fallbacks of its own.
+interface Props {
+  notice: {
+    message: string;
+    /** The same page in the latest docs when it exists, else the docs root. */
+    latestHref: string;
+    latestLabel: string;
+  } | null;
+}
+
+const { notice } = Astro.props;
+---
+
+{
+  notice && (
+    <div
+      class="flex items-center justify-center gap-x-2 gap-y-0.5 border-amber-300 border-b bg-amber-100 px-10 py-2.5 text-center text-amber-900 text-sm max-sm:flex-wrap dark:border-amber-900 dark:bg-amber-950 dark:text-amber-200"
+      data-blume-version-banner
+    >
+      <span>{notice.message}</span>
+      <a
+        class="inline-flex items-center gap-1 font-medium underline underline-offset-2"
+        href={withBase(notice.latestHref)}
+      >
+        {notice.latestLabel}
+        <Icon name="arrow-right" size={14} />
+      </a>
+    </div>
+  )
+}

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

@@ -19,10 +19,15 @@ interface AnalyticsWindow {
 }
 
 export const track = (event: string, props: TrackProps): void => {
-  if (typeof window === "undefined") {
+  // Read through `globalThis` so an SSR/import-time call sees `undefined`
+  // instead of a bare-identifier ReferenceError.
+  const browserWindow = globalThis.window;
+  if (browserWindow === undefined) {
     return;
   }
-  const w = window as typeof window & AnalyticsWindow;
+  // SAFETY: AnalyticsWindow only adds optional provider globals, so any window
+  // satisfies the intersection; each provider is feature-checked before use.
+  const w = browserWindow as typeof browserWindow & AnalyticsWindow;
 
   // Vercel Web Analytics — self-gates to a no-op until `window.va` is set up.
   vercelTrack(event, props);
@@ -32,7 +37,5 @@ export const track = (event: string, props: TrackProps): void => {
   w.gtag?.("event", event, props);
   w.plausible?.(event, { props });
   // Universal hook for any other integration.
-  window.dispatchEvent(
-    new CustomEvent("blume:track", { detail: { event, props } })
-  );
+  w.dispatchEvent(new CustomEvent("blume:track", { detail: { event, props } }));
 };

package/src/components/layout/hydration-hint.ts

@@ -13,7 +13,7 @@ const PATTERNS = [
   /server rendered html/iu,
 ];
 
-if (import.meta.env.DEV && typeof window !== "undefined") {
+if (import.meta.env.DEV && "window" in globalThis) {
   const original = console.error.bind(console);
   let shown = false;
   console.error = (...args: unknown[]) => {

package/src/components/layout/nav-utils.ts

@@ -209,10 +209,7 @@ export const sidebarForRoute = (
 };
 
 /** Resolve previous/next pages around the current route. */
-export const getPagination = (
-  flat: FlatPage[],
-  route: string
-): { prev: FlatPage | null; next: FlatPage | null } => {
+export const getPagination = (flat: FlatPage[], route: string) => {
   const index = flat.findIndex((page) => page.route === route);
   if (index === -1) {
     return { next: null, prev: null };

package/src/components/layout/overrides.ts

@@ -1,4 +1,21 @@
-import type { ComponentOverride } from "../../core/define-components.ts";
+import type {
+  ComponentOverride,
+  IslandDescriptor,
+} from "../../core/define-components.ts";
+
+/** A leftover path string an override resolved to (see `resolveSlot`). */
+const isPathString = (override: ComponentOverride): override is string =>
+  typeof override === "string";
+
+/** An `IslandDescriptor` whose `component` is actually present. */
+const isResolvedIsland = (
+  override: ComponentOverride
+): override is IslandDescriptor =>
+  typeof override === "object" &&
+  override !== null &&
+  "component" in override &&
+  override.component !== undefined &&
+  override.component !== null;
 
 /**
  * Resolve a layout-slot override to the component Astro should render, falling
@@ -15,20 +32,16 @@ export const resolveSlot = <T>(
   override: ComponentOverride | undefined,
   fallback: T
 ): T => {
-  if (
-    override === undefined ||
-    override === null ||
-    typeof override === "string"
-  ) {
+  if (override === undefined || override === null || isPathString(override)) {
     return fallback;
   }
-  if (
-    typeof override === "object" &&
-    "component" in override &&
-    override.component !== undefined &&
-    override.component !== null
-  ) {
+  if (isResolvedIsland(override)) {
+    // SAFETY: `ComponentReference` is untyped (`unknown`); the generated
+    // components map stores real components for this slot, so the descriptor's
+    // component is renderable as the slot's component type.
     return override.component as T;
   }
+  // SAFETY: same untyped `ComponentReference` — a bare value here is the
+  // imported component the config referenced for this slot.
   return override as T;
 };