blume 1.4.3 → 1.5.0

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/RootLayout.astro

@@ -8,6 +8,7 @@ import type {
   Heading,
   LocaleSwitchOption,
   Navigation,
+  NavSelector as NavSelectorType,
 } from "../../core/types.ts";
 import "blume:theme";
 import type { ComponentOverride } from "../../core/define-components.ts";
@@ -46,6 +47,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 };
@@ -149,6 +151,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 +232,9 @@ const {
   localeAlternates,
   xDefault,
   localeSwitch,
+  versionSelector,
+  versionNotice,
+  searchVersion = null,
   layout = {},
   clientData,
   toc = { enabled: true, maxLevel: 3, minLevel: 2 },
@@ -499,16 +514,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;
 };

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

@@ -8,6 +8,7 @@ interface AlgoliaRecord {
   title: string;
   description?: string;
   content?: string;
+  version?: string;
 }
 
 /**
@@ -27,15 +28,24 @@ export const createSearch = (opts: {
           hitsPerPage: SEARCH_LIMIT,
           indexName: opts.indexName,
           query,
-          // The sync uploads `locale` on every record so an i18n site can
-          // scope hosted results to the active language.
-          ...(options?.locale && {
-            facetFilters: [`locale:${options.locale}`],
-          }),
+          // The sync uploads `locale` and `version` on every record so a
+          // site can scope hosted results to the active language and the
+          // viewed docs version (the current docs upload as "current").
+          ...(() => {
+            const facetFilters = [
+              ...(options?.locale ? [`locale:${options.locale}`] : []),
+              ...(options?.version === undefined
+                ? []
+                : [`version:${options.version || "current"}`]),
+            ];
+            return facetFilters.length > 0 ? { facetFilters } : {};
+          })(),
         },
       ],
     });
     const [first] = results;
+    // SAFETY: the build-time sync uploads every record in the AlgoliaRecord
+    // 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) => ({
@@ -46,6 +56,9 @@ export const createSearch = (opts: {
       ),
       title: highlight(record.title, query),
       url: record.url,
+      // Records store the current docs' version as "current" (hosted backends
+      // treat empty facet values unreliably); the hit contract uses "".
+      version: record.version === "current" ? "" : record.version,
     }));
     return { hits, sections: [] };
   };

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

@@ -18,6 +18,9 @@ export const createSearch =
     if (!response.ok) {
       return { hits: [], sections: [] };
     }
+    // SAFETY: the endpoint is Blume-generated (`search-endpoint` template) and
+    // responds with the SearchHit list it built; title/excerpt are still
+    // escaped below before the dialog injects them as HTML.
     const records = (await response.json()) as SearchHit[];
     const hits = records.slice(0, SEARCH_LIMIT).map((hit) => ({
       ...hit,

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

@@ -3,6 +3,16 @@ import { Document } from "flexsearch";
 import { buildResult, RESULT_POOL } from "./types.ts";
 import type { IndexedDocument, SearchFn } from "./types.ts";
 
+/**
+ * The fields FlexSearch indexes. An anonymous alias of the indexed fields:
+ * unlike the `IndexedDocument` interface it satisfies FlexSearch's
+ * index-signature `DocumentData` constraint structurally.
+ */
+type SearchDocument = Pick<
+  IndexedDocument,
+  "content" | "description" | "route" | "title"
+>;
+
 /**
  * FlexSearch: reuse the same static `blume-search.json` Orama ships, but build
  * a FlexSearch document index in the browser. Keyless; works in dev and build.
@@ -13,17 +23,17 @@ export const createSearch = async (opts: {
   indexUrl: string;
 }): Promise<SearchFn> => {
   const response = await fetch(opts.indexUrl);
+  // SAFETY: `blume-search.json` is generated by our own search indexer, which
+  // writes exactly this document shape.
   const documents = (await response.json()) as IndexedDocument[];
   const byRoute = new Map(documents.map((doc) => [doc.route, doc]));
 
-  const index = new Document({
+  const index = new Document<SearchDocument>({
     document: { id: "route", index: ["title", "description", "content"] },
     tokenize: "forward",
   });
   for (const doc of documents) {
-    // FlexSearch's `DocumentData` is an index-signature type; our concrete
-    // record satisfies it structurally but TS needs the cast.
-    index.add(doc as unknown as Record<string, string>);
+    index.add(doc);
   }
 
   // FlexSearch's in-memory search is synchronous, so the SearchFn resolves
@@ -40,9 +50,15 @@ export const createSearch = async (opts: {
         }
         seen.add(route);
         const doc = byRoute.get(route);
-        // Filter to the active locale (when one is requested) before shaping,
-        // so section counts and results stay within the language.
-        if (doc && (!options?.locale || doc.locale === options.locale)) {
+        // Filter to the active locale and version (when requested) before
+        // shaping, so section counts and results stay within scope. `""` is
+        // the current version, so version presence is tested explicitly.
+        if (
+          doc &&
+          (!options?.locale || doc.locale === options.locale) &&
+          (options?.version === undefined ||
+            (doc.version ?? "") === options.version)
+        ) {
           matched.push(doc);
         }
       }

package/src/components/layout/search/orama-cloud.ts

@@ -31,7 +31,7 @@ export const createSearch = (opts: {
       ...(options?.locale && { where: { locale: options.locale } }),
     });
     const hits = (results?.hits ?? []).map((hit) => {
-      const doc = hit.document as unknown as OramaCloudRecord;
+      const doc: OramaCloudRecord = hit.document;
       return {
         content: doc.content ?? "",
         excerpt: highlight(

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

@@ -19,13 +19,16 @@ export const createSearch = async (opts: {
   locale?: string;
 }): Promise<SearchFn> => {
   const response = await fetch(opts.indexUrl);
+  // SAFETY: `blume-search.json` is generated by our own indexer
+  // (`buildSearchDocuments`), which writes exactly this document shape.
   const documents = (await response.json()) as IndexedDocument[];
   const db = await buildOramaIndex(documents, opts.locale);
 
   return async (query, options) => {
     const docs = await queryOramaIndex(db, query, RESULT_POOL, {
       locale: options?.locale,
+      version: options?.version,
     });
-    return buildResult(docs as IndexedDocument[], query, options?.section);
+    return buildResult(docs, query, options?.section);
   };
 };

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

@@ -23,6 +23,8 @@ export const createSearch = async (opts: {
 }): Promise<SearchFn> => {
   // The pagefind bundle lives in the built site (not node_modules) and is
   // resolved at runtime by URL — it can't be a static, code-splittable path.
+  // SAFETY: the URL points at the `pagefind.js` module our own build emitted,
+  // whose export contract (`search()`) is fixed by pagefind.
   // oxlint-disable-next-line react-doctor/no-dynamic-import-path
   const pagefind = (await import(
     /* @vite-ignore */

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

@@ -13,6 +13,11 @@ export interface SearchHit {
   section?: string;
   /** Plain-text page content, used to render the preview pane. */
   content?: string;
+  /**
+   * Docs version the hit belongs to (`""` = current). Local indexes and the
+   * hosted Algolia/Typesense adapters set it; other providers leave it unset.
+   */
+  version?: string;
 }
 
 /** A category pill with its result count. */
@@ -30,7 +35,12 @@ export interface SearchResult {
 /** A configured query function — the common contract every provider returns. */
 export type SearchFn = (
   query: string,
-  options?: { section?: string; locale?: string }
+  options?: {
+    section?: string;
+    locale?: string;
+    /** Docs version to scope to (`""` = current); omitted disables it. */
+    version?: string;
+  }
 ) => Promise<SearchResult>;
 
 /** A document in the client-loaded `blume-search.json` index. */
@@ -42,6 +52,7 @@ export interface IndexedDocument {
   breadcrumb?: string[];
   section?: string;
   locale?: string;
+  version?: string;
 }
 
 /** Max results surfaced in the dialog. */
@@ -193,6 +204,7 @@ export const buildResult = (
     section: doc.section ?? "",
     title: highlight(doc.title, query),
     url: doc.route,
+    version: doc.version,
   }));
   return { hits, sections };
 };

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

@@ -8,6 +8,7 @@ interface TypesenseRecord extends Record<string, unknown> {
   title: string;
   description?: string;
   content?: string;
+  version?: string;
 }
 
 /**
@@ -40,9 +41,20 @@ export const createSearch = (opts: {
           per_page: SEARCH_LIMIT,
           q: query,
           query_by: "title,description,content",
-          // The sync marks `locale` as a facet so an i18n site can scope
-          // hosted results to the active language.
-          ...(options?.locale && { filter_by: `locale:=${options.locale}` }),
+          // The sync marks `locale` and `version` as facets so hosted results
+          // scope to the active language and the viewed docs version (the
+          // current docs upload as "current").
+          ...(() => {
+            const clauses = [
+              ...(options?.locale ? [`locale:=${options.locale}`] : []),
+              ...(options?.version === undefined
+                ? []
+                : [`version:=${options.version || "current"}`]),
+            ];
+            return clauses.length > 0
+              ? { filter_by: clauses.join(" && ") }
+              : {};
+          })(),
         },
         {}
       );
@@ -56,6 +68,10 @@ export const createSearch = (opts: {
         ),
         title: highlight(doc.title, query),
         url: doc.url,
+        // Records store the current docs' version as "current" (hosted
+        // backends treat empty facet values unreliably); the hit contract
+        // uses "".
+        version: doc.version === "current" ? "" : doc.version,
       };
     });
     return { hits, sections: [] };