blume 2.0.3 → 2.1.1

package/src/ratelimit/wrangler.ts

@@ -0,0 +1,70 @@
+import { createHash } from "node:crypto";
+
+import type { JsonValue } from "../core/adapter.ts";
+import { isJsonObject } from "../core/sources/json.ts";
+import { RATE_LIMIT_BINDING } from "./cloudflare.ts";
+import type { CloudflareRateLimitAdapter } from "./cloudflare.ts";
+
+/** The Workers rate limiting binding, as the Worker's config declares it. */
+export interface RateLimitBindingConfig {
+  name: string;
+  namespace_id: string;
+  simple: { limit: number; period: 10 | 60 };
+}
+
+/**
+ * A namespace id for a Worker that sets none: a positive integer derived from
+ * its name, so two Blume sites on one account don't share one.
+ */
+export const rateLimitNamespace = (workerName: string): string => {
+  const digest = createHash("sha256").update(workerName).digest("hex");
+  return String((Number.parseInt(digest.slice(0, 8), 16) % 2_000_000_000) + 1);
+};
+
+const isText = <Value>(value: Value): value is Value & string =>
+  typeof value === "string";
+
+/** The binding `cloudflare()` asks for, on the Worker named `workerName`. */
+export const rateLimitBinding = (
+  adapter: CloudflareRateLimitAdapter,
+  workerName: string
+): RateLimitBindingConfig => ({
+  name: RATE_LIMIT_BINDING,
+  namespace_id: adapter.options.namespaceId ?? rateLimitNamespace(workerName),
+  simple: {
+    limit: adapter.options.requests ?? 10,
+    period: adapter.options.window ?? 60,
+  },
+});
+
+/**
+ * The built Worker's config (`dist/server/wrangler.json`) with Blume's rate
+ * limiting binding in `ratelimits`, replacing an earlier one of the same name
+ * and keeping any others. `null` when the config isn't a JSON object.
+ */
+export const withRateLimitBinding = (
+  wranglerText: string,
+  adapter: CloudflareRateLimitAdapter
+): string | null => {
+  let config: JsonValue;
+  try {
+    config = JSON.parse(wranglerText);
+  } catch {
+    return null;
+  }
+  if (!isJsonObject(config) || Array.isArray(config)) {
+    return null;
+  }
+  const { name, ratelimits } = config;
+  const others = Array.isArray(ratelimits)
+    ? ratelimits.filter(
+        (entry) => !(isJsonObject(entry) && entry.name === RATE_LIMIT_BINDING)
+      )
+    : [];
+  const binding = rateLimitBinding(adapter, isText(name) ? name : "");
+  config.ratelimits = [
+    ...others,
+    { ...binding, simple: { ...binding.simple } },
+  ];
+  return JSON.stringify(config);
+};

package/src/reference/asyncapi.ts

@@ -16,9 +16,9 @@ import type { PlaygroundOptions, ReferenceSourceOptions } from "./options.ts";
 export interface AsyncApiOptions {
   /**
    * Code-sample tools shown per operation (Blume renderer). Defaults to every
-   * tool appropriate to the operation's protocol binding.
+   * tool appropriate to the operation's protocol binding; `false` shows none.
    */
-  codeSamples?: string[];
+  codeSamples?: string[] | false;
   /** Start nested schema rows expanded rather than collapsed (Blume renderer). Defaults to `false`. */
   expandSchemas?: boolean;
   /**

package/src/reference/graphql.ts

@@ -3,18 +3,33 @@ import { z } from "zod";
 import type { AdapterDescriptor } from "../core/adapter.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
 import {
+  graphqlAuthSchema,
   graphqlSourceSchema,
   liftSpec,
   hasSources,
   missingSourcesIssue,
   sharedOptions,
 } from "./options.ts";
-import type { GraphqlSourceOptions, PlaygroundOptions } from "./options.ts";
+import type {
+  GraphqlAuthOptions,
+  GraphqlSourceOptions,
+  PlaygroundOptions,
+} from "./options.ts";
 
 /** Options for {@link graphql}. */
 export interface GraphqlOptions {
-  /** Code-sample languages shown per operation. Defaults to `["curl", "js", "python"]`. */
-  codeSamples?: string[];
+  /**
+   * How the endpoint authenticates, like the site's `api.auth`: `bearer`,
+   * `basic`, or `key` (sent in the `name` header, `x-api-key` by default).
+   * The Try it panel gets a field for the credential and the code samples
+   * send a placeholder. Applies to every source; a per-source `auth` wins.
+   */
+  auth?: GraphqlAuthOptions;
+  /**
+   * Code-sample languages shown per operation, in order. Defaults to
+   * `["curl", "js", "python"]`; `false` shows none.
+   */
+  codeSamples?: string[] | false;
   /**
    * URL of the live GraphQL endpoint the playground and code samples target —
    * a schema, unlike an OpenAPI document, names no server. Applies to every
@@ -49,6 +64,8 @@ export const graphqlOptionsSchema = z
       codeSamples: ["curl", "js", "python"],
       route: "/graphql",
     }),
+    /** Default endpoint auth for every source (per-source `auth` wins). */
+    auth: graphqlAuthSchema.optional(),
     /** Default live endpoint URL for every source (per-source `endpoint` wins). */
     endpoint: z.string().optional(),
     /** One or more schemas; each renders on its own route by default. */

package/src/reference/index.ts

@@ -27,6 +27,7 @@ export type { GraphqlAdapter, GraphqlOptions } from "./graphql.ts";
 export { openapi } from "./openapi.ts";
 export type { OpenApiAdapter, OpenApiOptions } from "./openapi.ts";
 export type {
+  GraphqlAuthOptions,
   GraphqlSourceOptions,
   PlaygroundOptions,
   ReferenceSourceOptions,

package/src/reference/openapi.ts

@@ -4,18 +4,24 @@ import type { AdapterDescriptor } from "../core/adapter.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
 import {
   liftSpec,
-  referenceSourceSchema,
+  openapiSourceSchema,
+  overlaysHaveSpec,
+  overlaysNeedSpecIssue,
   hasSources,
   missingSourcesIssue,
   rendererRemovedHint,
   sharedOptions,
 } from "./options.ts";
-import type { PlaygroundOptions, ReferenceSourceOptions } from "./options.ts";
+import type { OpenApiSourceOptions, PlaygroundOptions } from "./options.ts";
 
 /** Options for {@link openapi}. */
 export interface OpenApiOptions {
-  /** Code-sample languages shown per operation (Blume renderer). Defaults to `["curl", "js", "python"]`. */
-  codeSamples?: string[];
+  /**
+   * Code-sample languages generated per operation (Blume renderer), in
+   * order. Defaults to `["curl", "js", "python"]`; `false` (or an empty list)
+   * generates none, so only the spec's own `x-codeSamples` show.
+   */
+  codeSamples?: string[] | false;
   /** Start nested schema rows expanded rather than collapsed (Blume renderer). Defaults to `false`. */
   expandSchemas?: boolean;
   /**
@@ -26,10 +32,15 @@ export interface OpenApiOptions {
    * `vercel()` in `deployment`).
    */
   playground?: PlaygroundOptions;
+  /**
+   * OpenAPI Overlay documents for `spec`, applied in order before it renders.
+   * With `sources`, each source takes its own `overlays`.
+   */
+  overlays?: string[];
   /** Where the reference mounts. Defaults to `/reference`. */
   route?: string;
   /** One or more specs; each renders on its own route by default. */
-  sources?: ReferenceSourceOptions[];
+  sources?: OpenApiSourceOptions[];
   /** Shorthand for a single source: `sources: [{ spec }]`. */
   spec?: string;
 }
@@ -43,12 +54,15 @@ export const openapiOptionsSchema = z
       }),
       /** Start nested schema rows expanded rather than collapsed (Blume renderer). */
       expandSchemas: z.boolean().default(false),
+      /** Overlays for the `spec` shorthand. */
+      overlays: z.array(z.string()).optional(),
       /** One or more specs; each renders on its own route by default. */
-      sources: z.array(referenceSourceSchema).default([]),
+      sources: z.array(openapiSourceSchema).default([]),
     },
     rendererRemovedHint
   )
-  .transform(liftSpec(referenceSourceSchema))
+  .refine(overlaysHaveSpec, overlaysNeedSpecIssue)
+  .transform(liftSpec(openapiSourceSchema))
   .refine(hasSources, missingSourcesIssue("openapi"));
 
 /** `openapi()` options with every default applied and `spec` folded into `sources`. */

package/src/reference/options.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { AUTH_METHODS } from "../components/content/api-page.ts";
+import type { AuthMethod } from "../components/content/api-page.ts";
 import { unrecognizedKeysMessage } from "../core/unrecognized-keys.ts";
 
 /**
@@ -65,18 +67,78 @@ export interface ReferenceSourceOptions {
 /** A spec source with every default applied. */
 export type ResolvedReferenceSource = z.output<typeof referenceSourceSchema>;
 
+/**
+ * [OpenAPI Overlay](https://spec.openapis.org/overlay/latest.html) documents
+ * (local paths or `http(s)` URLs) applied in order to an OpenAPI spec before
+ * it renders: changes to a spec you don't edit by hand.
+ */
+export const overlaysSchema = z.array(z.string()).default([]);
+
+/** Whether adapter-level `overlays` has the `spec` it belongs to. */
+export const overlaysHaveSpec = (options: {
+  overlays?: string[];
+  spec?: string;
+}): boolean => !options.overlays || options.spec !== undefined;
+
+/** The refinement issue for `overlays` set beside `sources` instead of `spec`. */
+export const overlaysNeedSpecIssue = {
+  message:
+    "`overlays` belongs to the `spec` shorthand; with `sources`, give each source its own `overlays`.",
+  path: ["overlays"],
+};
+
+/** An OpenAPI spec source: the shared shape plus its `overlays`. */
+export const openapiSourceSchema = referenceSourceSchema.extend({
+  overlays: overlaysSchema,
+});
+
+/** One OpenAPI spec source, as `openapi()` accepts it. */
+export interface OpenApiSourceOptions extends ReferenceSourceOptions {
+  /**
+   * OpenAPI Overlay documents (local paths or `http(s)` URLs) applied in
+   * order to the spec before it renders.
+   */
+  overlays?: string[];
+}
+
+/**
+ * How a GraphQL endpoint authenticates, in the shape the site's `api.auth`
+ * takes for hand-written endpoints: `bearer`, `basic`, or `key` (sent in the
+ * `name` header, `x-api-key` by default). A schema, unlike an OpenAPI
+ * document, declares no security schemes, so this is what gives the Try it
+ * panel its credential field.
+ */
+export const graphqlAuthSchema = z.strictObject({
+  method: z.enum(AUTH_METHODS),
+  /** The header an API key goes in. Defaults to `x-api-key`. */
+  name: z.string().optional(),
+});
+
+/** The `auth` option of `graphql()` and its sources. */
+export interface GraphqlAuthOptions {
+  /** `bearer`, `basic`, `key`, or `none`. */
+  method: AuthMethod;
+  /** The header an API key goes in. Defaults to `x-api-key`. */
+  name?: string;
+}
+
 /**
  * A single GraphQL schema: the shared source shape plus `endpoint`, the live
  * GraphQL API URL the playground and code samples target (a schema, unlike an
- * OpenAPI document, names no server).
+ * OpenAPI document, names no server), and `auth`, how that endpoint
+ * authenticates.
  */
 export const graphqlSourceSchema = referenceSourceSchema.extend({
+  /** How the endpoint authenticates (playground + code samples). */
+  auth: graphqlAuthSchema.optional(),
   /** URL of the live GraphQL endpoint (playground + code samples). */
   endpoint: z.string().optional(),
 });
 
 /** One schema source, as `graphql()` accepts it. */
 export interface GraphqlSourceOptions extends ReferenceSourceOptions {
+  /** How the endpoint authenticates; wins over the adapter's `auth`. */
+  auth?: GraphqlAuthOptions;
   /** URL of the live GraphQL endpoint (playground + code samples); wins over the adapter's `endpoint`. */
   endpoint?: string;
 }
@@ -157,8 +219,13 @@ export const sharedOptions = (defaults: {
   codeSamples: string[];
   route: string;
 }) => ({
-  /** Code-sample languages/tools shown per operation (Blume renderer). */
-  codeSamples: z.array(z.string()).default(defaults.codeSamples),
+  /**
+   * Code-sample languages/tools shown per operation (Blume renderer), or
+   * `false` for none: only the spec's own `x-codeSamples` then.
+   */
+  codeSamples: z
+    .union([z.literal(false), z.array(z.string())])
+    .default(defaults.codeSamples),
   /** The "Try it" panel; see {@link playgroundSchema}. */
   playground: playgroundSchema,
   /** Where the reference mounts. */
@@ -168,8 +235,9 @@ export const sharedOptions = (defaults: {
 });
 
 /**
- * Resolve the `spec` shorthand into `sources` so downstream code reads one
- * field: the shorthand becomes the first source (with the source defaults
+ * Resolve the `spec` shorthand (and, on OpenAPI kinds, the `overlays` beside
+ * it) into `sources` so downstream code reads one field: the shorthand becomes
+ * the first source (with the source defaults
  * applied through the source schema itself, so the two can never drift) and
  * the `spec` key is dropped. An adapter with neither renders nothing, which
  * is a config mistake rather than a choice — `refine` it away with
@@ -179,15 +247,19 @@ export const liftSpec =
   <Source extends { spec: string }>(
     sourceSchema: z.ZodType<Source, { spec: string }>
   ) =>
-  <Options extends { sources: Source[]; spec?: string }>({
+  <Options extends { sources: Source[]; spec?: string; overlays?: string[] }>({
+    overlays,
     spec,
     ...options
-  }: Options): Omit<Options, "spec"> => ({
+  }: Options): Omit<Options, "spec" | "overlays"> => ({
     ...options,
     sources:
       spec === undefined
         ? options.sources
-        : [sourceSchema.parse({ spec }), ...options.sources],
+        : [
+            sourceSchema.parse(overlays ? { overlays, spec } : { spec }),
+            ...options.sources,
+          ],
   });
 
 /** Whether an adapter has anything to render; pairs with {@link missingSourcesIssue}. */

package/src/reference/scalar.ts

@@ -2,7 +2,13 @@ import { z } from "zod";
 
 import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
 import { adapterDescriptorSchema } from "../core/adapter.ts";
-import { hasSources, missingSourcesIssue } from "./options.ts";
+import {
+  hasSources,
+  missingSourcesIssue,
+  overlaysHaveSpec,
+  overlaysNeedSpecIssue,
+  overlaysSchema,
+} from "./options.ts";
 
 /**
  * What the generated Scalar page imports. Declared on every `scalar()`
@@ -22,6 +28,11 @@ export const scalarSourceSchema = z.strictObject({
   label: z.string().optional(),
   /** Emit noindex metadata and omit the page from the sitemap. */
   noindex: z.boolean().default(false),
+  /**
+   * OpenAPI Overlay documents applied in order to the document before it's
+   * embedded (inlined, so a remote spec with overlays is fetched at build).
+   */
+  overlays: overlaysSchema,
   /** Per-source route; defaults to the adapter's `route` (or a derived path). */
   route: z.string().optional(),
   /** Local path or `http(s)` URL to the OpenAPI or AsyncAPI document. */
@@ -34,6 +45,8 @@ export interface ScalarSourceOptions {
   label?: string;
   /** Emit noindex metadata and omit the page from the sitemap. Defaults to `false`. */
   noindex?: boolean;
+  /** OpenAPI Overlay documents applied in order to the document before it's embedded. */
+  overlays?: string[];
   /** Per-source route; defaults to the adapter's `route` (or a derived path). */
   route?: string;
   /** Local path or `http(s)` URL to the OpenAPI or AsyncAPI document. */
@@ -55,6 +68,8 @@ export type ResolvedScalarOptions = {
 
 /** The options {@link scalar} maps itself. */
 export interface ScalarNamedOptions {
+  /** OpenAPI Overlay documents for `spec`; with `sources`, each takes its own. */
+  overlays?: string[];
   /** Where the reference mounts. Defaults to `/reference`. */
   route?: string;
   /** One or more documents; each renders on its own route by default. */
@@ -87,6 +102,8 @@ export type ScalarOptions = ScalarNamedOptions & {
  */
 export const scalarOptionsSchema = z
   .object({
+    /** Overlays for the `spec` shorthand. */
+    overlays: z.array(z.string()).optional(),
     /** Where the reference mounts. */
     route: z.string().default("/reference"),
     /** One or more documents; each renders on its own route by default. */
@@ -97,13 +114,21 @@ export const scalarOptionsSchema = z
     theme: z.string().optional(),
   })
   .catchall(z.json())
-  .transform(({ spec, sources, ...options }): ResolvedScalarOptions => ({
-    ...options,
-    sources:
-      spec === undefined
-        ? sources
-        : [scalarSourceSchema.parse({ spec }), ...sources],
-  }))
+  .refine(overlaysHaveSpec, overlaysNeedSpecIssue)
+  .transform(
+    ({ overlays, spec, sources, ...options }): ResolvedScalarOptions => ({
+      ...options,
+      sources:
+        spec === undefined
+          ? sources
+          : [
+              scalarSourceSchema.parse(
+                overlays ? { overlays, spec } : { spec }
+              ),
+              ...sources,
+            ],
+    })
+  )
   .refine(hasSources, missingSourcesIssue("scalar"));
 
 export type ScalarAdapter = AdapterDescriptor<"scalar", ScalarOptions>;

package/src/registry/eject.ts

@@ -63,6 +63,7 @@ import {
   rssEndpointTemplate,
   runtimeDependencies,
   runtimeTsconfigTemplate,
+  consentClientTemplate,
   searchClientTemplate,
   searchEndpointTemplate,
   staticJsonEndpointTemplate,
@@ -87,6 +88,7 @@ import {
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
+import { sourcePages } from "../search/source-pages.ts";
 import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
@@ -162,9 +164,12 @@ const askFiles = async (
   const files = [
     {
       content: askEndpointTemplate(backend, {
+        captcha: assistant.captcha,
         cors: assistant.cors,
         instructions: assistant.instructions,
+        rateLimit: project.config.rateLimit,
         retrieval: assistant.retrieval,
+        tools: assistant.tools ?? backend.toolsByDefault,
       }),
       path: join(srcDir, "pages", "api", "ask.ts"),
     },
@@ -243,7 +248,10 @@ const playgroundProxyFiles = (
   needsPlaygroundProxy(config)
     ? [
         {
-          content: playgroundProxyTemplate(specOrigins(openApiData)),
+          content: playgroundProxyTemplate(
+            specOrigins(openApiData),
+            config.rateLimit
+          ),
           path: join(srcDir, PLAYGROUND_PROXY_ENTRY),
         },
       ]
@@ -667,6 +675,7 @@ export const eject = async (
       content: astroConfigTemplate({
         askPath: "./src/generated/Ask.astro",
         config,
+        consentClientPath: "./src/generated/consent-client.ts",
         contentRoot: relContext.contentRoot,
         contentRoutes: project.manifest.routes.map((route) => route.path),
         context: relContext,
@@ -747,7 +756,7 @@ export const eject = async (
         // the package is hoisted out of the project's own node_modules.
         sources: [
           blumeSourceGlob(root, genDir),
-          "../../**/*.{astro,mdx,ts,tsx}",
+          "../../**/*.{astro,jsx,mdx,ts,tsx}",
         ],
         twoslashCss: twoslashCss(),
         userTheme,
@@ -869,8 +878,9 @@ export const eject = async (
     );
   }
 
-  // The client-feature loaders behind the `blume:features` alias, and the
-  // provider-specific client loader behind `blume:search-client`.
+  // The client-feature loaders behind the `blume:features` alias, the
+  // provider-specific client loader behind `blume:search-client`, and the
+  // consent adapter's browser module behind `blume:consent-client`.
   files.push(
     {
       content: featuresTemplate(features),
@@ -879,6 +889,10 @@ export const eject = async (
     {
       content: searchClientTemplate(config),
       path: join(genDir, "search-client.ts"),
+    },
+    {
+      content: consentClientTemplate(config.consent),
+      path: join(genDir, "consent-client.ts"),
     }
   );
 
@@ -899,7 +913,11 @@ export const eject = async (
 
   if (searchAdapter.kind === "mixedbread") {
     files.push({
-      content: mixedbreadSearchEndpointTemplate(searchAdapter.options),
+      content: mixedbreadSearchEndpointTemplate(
+        searchAdapter.options,
+        sourcePages(project),
+        config.rateLimit
+      ),
       path: join(srcDir, "pages", "api", "search.ts"),
     });
   }

package/src/registry/registry.ts

@@ -262,6 +262,13 @@ export const registry: RegistryItem[] = [
     name: "feedback",
     slot: "Feedback",
   }),
+  layoutComponent({
+    description:
+      "The site footer: a row of links, social icons, the theme toggle, and the Cookie settings link.",
+    file: "SiteFooter.astro",
+    name: "footer",
+    slot: "Footer",
+  }),
   ...CONTENT_COMPONENTS.map(contentComponent),
 ];
 

package/src/search/adapters/locale-scope.ts

@@ -0,0 +1,30 @@
+import type { SearchAdapterKind } from "./registry.ts";
+
+/**
+ * Whether each adapter's client can limit results to one language. The
+ * source-built indexes (Orama, FlexSearch) store every document's `locale`,
+ * the Algolia, Orama Cloud, and Typesense syncs upload it for their clients
+ * to filter on, and Pagefind keeps an index per language, merging the others
+ * in to search them all. The Mixedbread endpoint takes no filter, so it
+ * always searches every language. Keyed by every kind so a new adapter has
+ * to decide.
+ */
+const SCOPES_LOCALES = {
+  algolia: true,
+  flexsearch: true,
+  mixedbread: false,
+  none: false,
+  orama: true,
+  "orama-cloud": true,
+  pagefind: true,
+  typesense: true,
+} satisfies Record<SearchAdapterKind, boolean>;
+
+/**
+ * Whether the configured search adapter scopes results to the page's
+ * language. The search dialog offers its "All languages" toggle only when it
+ * does: on the others the toggle would change nothing, and every query
+ * already spans all languages.
+ */
+export const scopesLocales = (kind: SearchAdapterKind): boolean =>
+  SCOPES_LOCALES[kind];

package/src/search/adapters/typesense.ts

@@ -6,14 +6,22 @@ import type { SearchAdapter } from "./types.ts";
 /**
  * Connection details for a self-hosted or cloud Typesense node. The browser
  * queries the collection with the search-only `apiKey`; the build-time sync
- * recreates the collection with `TYPESENSE_ADMIN_API_KEY`, which never enters
- * the config.
+ * rebuilds it with `TYPESENSE_ADMIN_API_KEY`, which never enters the config.
  */
 export interface TypesenseNamedOptions {
   /** The search-only API key (public — it ships to the browser). */
   apiKey: string;
+  /** The alias the sync points at each new collection, and searches read. */
   collection: string;
   host: string;
+  /**
+   * The language Typesense tokenizes the text fields for, as a two-letter
+   * code (`ja`, `zh`, `ko`, `th`, …). Typesense's default tokenizer splits on
+   * spaces, so text in a script written without them — Chinese, Japanese,
+   * Thai — only matches from the start of a run. Omitted, the fields keep
+   * that default.
+   */
+  locale?: string;
   /** Defaults to 443. */
   port?: number;
   /** Defaults to `https`. */
@@ -39,14 +47,16 @@ export const typesenseOptionsSchema = z
     apiKey: z.string(),
     collection: z.string(),
     host: z.string(),
+    locale: z.string().optional(),
     port: z.number().int().positive().optional(),
     protocol: z.enum(["http", "https"]).optional(),
   })
   .catchall(z.json());
 
 /**
- * Hosted search on Typesense. Each `blume build` drops and recreates the
- * collection so deleted or renamed pages don't linger as stale hits.
+ * Hosted search on Typesense. Each `blume build` imports into a new
+ * collection and swaps the `collection` alias onto it, so deleted or renamed
+ * pages don't linger as stale hits and searches never read a partial index.
  */
 export const typesense = (options: TypesenseOptions): TypesenseAdapter => ({
   kind: "typesense",

package/src/search/build.ts

@@ -3,6 +3,11 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { close, createIndex } from "pagefind";
 import { dirname, join } from "pathe";
 
+/** The part of `pagefind-entry.json` that counts the index's pages. */
+interface PagefindEntry {
+  languages: Record<string, { page_count: number }>;
+}
+
 /**
  * Build a local Pagefind search index over the built site. Pagefind indexes
  * every rendered page except those whose `<html>` carries
@@ -23,7 +28,9 @@ import { dirname, join } from "pathe";
  * Pagefind/pagefind#1272; switch back to `writeFiles()` once a release ships
  * that fix.
  *
- * Returns the number of pages indexed.
+ * Returns the number of pages indexed: the index's own count, summed over its
+ * languages from `pagefind-entry.json`. `addDirectory`'s `page_count` counts
+ * every HTML file it read, including the ones kept out of the index.
  */
 export const buildSearchIndex = async (outDir: string): Promise<number> => {
   const { index } = await createIndex({});
@@ -34,7 +41,7 @@ export const buildSearchIndex = async (outDir: string): Promise<number> => {
   // These awaits are strictly ordered, not independent: the directory must be
   // indexed before its files are read, and the index closed only after.
   // oxlint-disable-next-line react-doctor/async-parallel
-  const result = await index.addDirectory({ path: outDir });
+  await index.addDirectory({ path: outDir });
   const { files } = await index.getFiles();
   await close();
 
@@ -49,5 +56,16 @@ export const buildSearchIndex = async (outDir: string): Promise<number> => {
     files.map((file) => writeFile(join(searchDir, file.path), file.content))
   );
 
-  return result.page_count;
+  // Pagefind always writes the entry file, listing no languages when nothing
+  // was indexed.
+  const entry = files.find((file) => file.path === "pagefind-entry.json");
+  // SAFETY: the entry file is Pagefind's JSON, which counts each language's
+  // pages in `page_count`.
+  const { languages } = JSON.parse(
+    new TextDecoder().decode(entry?.content)
+  ) as PagefindEntry;
+  return Object.values(languages).reduce(
+    (sum, language) => sum + language.page_count,
+    0
+  );
 };