blume 2.1.0 → 2.1.2

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";
 
 /**
@@ -99,18 +101,44 @@ export interface OpenApiSourceOptions extends ReferenceSourceOptions {
   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;
 }

package/src/registry/eject.ts

@@ -88,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,
@@ -528,12 +529,15 @@ const examplesPreviewFiles = (
  * eject declares the ones its generated files import directly: the AI SDK the
  * assistant route streams through (unless `ai.assistant.endpoint` points
  * elsewhere, when no route is written) and the EPUB generator's browser bundle
- * `features.ts` loads (only named there when `export.epub` is on).
+ * `features.ts` loads (only named there when `export.epub` is on). The
+ * narration provider's SDK (`openai()`'s `@ai-sdk/openai`) is no runtime
+ * import, but the ejected app's `astro build` loads it to generate the clips.
  */
 const ejectDependencies = (
   options: Parameters<typeof runtimeDependencies>[0]
 ): string[] => {
   const { assistant } = options.config.ai;
+  const { narration } = options.config;
   return [
     ...new Set([
       "astro",
@@ -544,6 +548,7 @@ const ejectDependencies = (
       ...runtimeDependencies(options),
       ...(options.needsReact ? ["react", "react-dom"] : []),
       ...(assistant?.enabled && !assistant.endpoint ? ["ai"] : []),
+      ...(narration.enabled ? (narration.provider?.runtimeDeps ?? []) : []),
       ...(options.config.export.epub ? ["epub-gen-memory"] : []),
     ]),
   ];
@@ -755,7 +760,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,
@@ -914,6 +919,7 @@ export const eject = async (
     files.push({
       content: mixedbreadSearchEndpointTemplate(
         searchAdapter.options,
+        sourcePages(project),
         config.rateLimit
       ),
       path: join(srcDir, "pages", "api", "search.ts"),

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
+  );
 };

package/src/search/orama-index.ts

@@ -1,8 +1,16 @@
-import { create, insertMultiple, search } from "@orama/orama";
+import {
+  components,
+  create,
+  insert,
+  insertMultiple,
+  search,
+} from "@orama/orama";
 import type {
   AnyOrama,
   EnumArrComparisonOperator,
   EnumComparisonOperator,
+  Result,
+  SearchParamsFullText,
   Tokenizer,
 } from "@orama/orama";
 
@@ -314,32 +322,89 @@ const segmentingTokenizer = (locale?: string): Tokenizer | undefined => {
   };
 };
 
+/**
+ * On a Latin-default index holding pages in non-Latin locales, the tokenizer
+ * each of those locales' pages was indexed with, keyed by locale code. A query
+ * reads it to tokenize its term the way the pages it searches were.
+ */
+const translationTokenizers = new WeakMap<AnyOrama, Map<string, Tokenizer>>();
+
+/** A segmenting tokenizer for each document locale Orama's can't serve. */
+const localeTokenizers = (documents: OramaDoc[]): Map<string, Tokenizer> => {
+  const tokenizers = new Map<string, Tokenizer>();
+  for (const code of new Set(documents.map((doc) => doc.locale ?? ""))) {
+    const tokenizer = segmentingTokenizer(code);
+    if (tokenizer) {
+      tokenizers.set(code, tokenizer);
+    }
+  }
+  return tokenizers;
+};
+
+/**
+ * One tokenizer that hands each text to its locale's: Orama passes the
+ * language given to `insert` and `search` through to `tokenize`, so a page
+ * inserted under `ja` and a query searched under `ja` both reach the Japanese
+ * tokenizer, and everything else reaches Orama's own, exactly as on an index
+ * with no translations.
+ */
+const dispatchingTokenizer = (
+  tokenizers: Map<string, Tokenizer>
+): Tokenizer => {
+  const standard = components.tokenizer.createTokenizer();
+  return {
+    language: standard.language,
+    normalizationCache: standard.normalizationCache,
+    tokenize: (raw, language, prop, withCache) =>
+      // Orama's tokenizer rejects a language other than its own, so the
+      // locale that picked it is not passed on.
+      (tokenizers.get(language ?? "") ?? standard).tokenize(
+        raw,
+        undefined,
+        prop,
+        withCache
+      ),
+  };
+};
+
 /**
  * Build an in-memory Orama full-text index from search documents. Shared by the
  * Orama client loader (browser), the MCP server, and assistant grounding (Node),
  * so ranking is identical wherever docs are queried. `locale` — the site's
  * `i18n.defaultLocale` — swaps in a word-segmenting tokenizer for every
  * non-Latin script, all of which Orama's default tokenizer reduces to zero
- * tokens; the tokenizer belongs to the database, so on a mixed-locale site it
- * applies to every document. That is safe in one direction only: Latin words
+ * tokens. A non-Latin default's tokenizer serves every page: Latin words
  * survive segmentation intact, so English pages on a segmented index stay
- * searchable, but non-Latin translations on a Latin-default index still
- * collapse to zero tokens.
+ * searchable. A Latin default keeps Orama's tokenizer for its Latin-script
+ * pages, and each page in a non-Latin locale (the Japanese and Hindi
+ * translations of an English site) is indexed with its own locale's tokenizer.
  */
 export const buildOramaIndex = async (
   documents: OramaDoc[],
   locale?: string
 ): Promise<AnyOrama> => {
-  const tokenizer = segmentingTokenizer(locale);
-  const db = tokenizer
-    ? create({ components: { tokenizer }, schema: SCHEMA })
-    : create({ schema: SCHEMA });
-  await insertMultiple(
-    db,
-    documents.map((doc) =>
-      doc.facets ? { ...doc, facetTerms: toFacetTerms(doc.facets) } : doc
-    )
+  const rows = documents.map((doc) =>
+    doc.facets ? { ...doc, facetTerms: toFacetTerms(doc.facets) } : doc
   );
+  const tokenizer = segmentingTokenizer(locale);
+  const translations = tokenizer ? undefined : localeTokenizers(documents);
+  let db: AnyOrama;
+  if (translations && translations.size > 0) {
+    db = create({
+      components: { tokenizer: dispatchingTokenizer(translations) },
+      schema: SCHEMA,
+    });
+    for (const row of rows) {
+      // oxlint-disable-next-line no-await-in-loop -- one at a time, in order, so each page is tokenized under its own locale and ties still rank in document order.
+      await insert(db, row, row.locale);
+    }
+    translationTokenizers.set(db, translations);
+  } else {
+    db = tokenizer
+      ? create({ components: { tokenizer }, schema: SCHEMA })
+      : create({ schema: SCHEMA });
+    await insertMultiple(db, rows);
+  }
   if (documents.some((doc) => (doc.boost ?? 1) !== 1)) {
     boostedDatabases.add(db);
   }
@@ -379,17 +444,56 @@ interface OramaWhereClause {
     | undefined;
 }
 
+/** A ranked match, scored and carrying its document. */
+type Hit = Result<OramaDoc>;
+
+/**
+ * One search, with the term tokenized under `language`. On a bigrammed
+ * tokenizer the strict pass runs first: a term is only meant to match where
+ * its bigrams sit together, and scoring them independently lets a page
+ * sharing a couple of windows outrank the page the term is about. Terms
+ * spanning several words rarely appear in full on one page, so an empty
+ * strict result falls back to the default pass rather than reporting no
+ * matches.
+ */
+const rankedHits = async (
+  db: AnyOrama,
+  params: SearchParamsFullText<AnyOrama, OramaDoc>,
+  language: string | undefined,
+  bigrammed: boolean
+): Promise<Hit[]> => {
+  // The result-document generic is OramaDoc because `buildOramaIndex` is the
+  // only writer to this database and inserts OramaDoc records (plus the
+  // derived `facetTerms`).
+  const strict = bigrammed
+    ? await search<AnyOrama, OramaDoc>(
+        db,
+        { ...params, threshold: ALL_TOKENS },
+        language
+      )
+    : undefined;
+  const found =
+    strict && strict.hits.length > 0
+      ? strict
+      : await search<AnyOrama, OramaDoc>(db, params, language);
+  return found.hits;
+};
+
+/** A hit's rank across searches: its relevance times the page's boost. */
+const boostedScore = (hit: Hit): number =>
+  hit.score * (hit.document.boost ?? 1);
+
 /**
  * Query the index, returning the matching documents (highest-ranked first).
  * `filters` narrows results by exact `where` matches on the enum fields:
  * `locale` to one language, `contentTypes` to a set of page types, `facets`
  * to documents carrying every requested `key:value` term.
  *
- * On a bigrammed index the strict pass runs first: a term is only meant to
- * match where its bigrams sit together, and scoring them independently lets a
- * page sharing a couple of windows outrank the page the term is about. Terms
- * spanning several words rarely appear in full on one page, so an empty strict
- * result falls back to the default pass rather than reporting no matches.
+ * On an index whose translations have tokenizers of their own, a query scoped
+ * to a locale is tokenized with that locale's tokenizer. An unscoped query
+ * searches each locale's pages with its own tokenizer, and the Latin-script
+ * pages with Orama's, then merges the matches by score: every search runs over
+ * the one index, so their scores share its term statistics.
  */
 export const queryOramaIndex = async (
   db: AnyOrama,
@@ -424,16 +528,44 @@ export const queryOramaIndex = async (
   };
   const params =
     Object.keys(where).length > 0 ? { ...unfiltered, where } : unfiltered;
-  const bigrammed = isBigramLanguage(db.tokenizer?.language ?? "");
-  // The result-document generic is OramaDoc because `buildOramaIndex` is the
-  // only writer to this database and inserts OramaDoc records (plus the
-  // derived `facetTerms`).
-  const strict = bigrammed
-    ? await search<AnyOrama, OramaDoc>(db, { ...params, threshold: ALL_TOKENS })
-    : undefined;
-  const found =
-    strict && strict.hits.length > 0
-      ? strict
-      : await search<AnyOrama, OramaDoc>(db, params);
-  return found.hits.map((hit) => hit.document);
+  const translations = translationTokenizers.get(db);
+  if (!translations) {
+    const bigrammed = isBigramLanguage(db.tokenizer?.language ?? "");
+    const hits = await rankedHits(db, params, undefined, bigrammed);
+    return hits.map((hit) => hit.document);
+  }
+  if (filters?.locale) {
+    const { language = "" } = translations.get(filters.locale) ?? {};
+    const bigrammed = isBigramLanguage(language);
+    const hits = await rankedHits(db, params, filters.locale, bigrammed);
+    return hits.map((hit) => hit.document);
+  }
+  // `nin` matches only pages with a locale, which every Blume-built index
+  // gives each page. (Orama's `not` would admit locale-less pages, but it
+  // drops the sibling filters beside it.)
+  const searches = [
+    rankedHits(
+      db,
+      {
+        ...params,
+        where: { ...where, locale: { nin: [...translations.keys()] } },
+      },
+      undefined,
+      false
+    ),
+    ...[...translations].map(([code, tokenizer]) =>
+      rankedHits(
+        db,
+        { ...params, where: { ...where, locale: { eq: code } } },
+        code,
+        isBigramLanguage(tokenizer.language)
+      )
+    ),
+  ];
+  const found = await Promise.all(searches);
+  return found
+    .flat()
+    .toSorted((a, b) => boostedScore(b) - boostedScore(a))
+    .slice(0, limit)
+    .map((hit) => hit.document);
 };

package/src/search/source-pages.ts

@@ -0,0 +1,29 @@
+import { relative } from "pathe";
+
+import type { BlumeProject } from "../core/project-graph.ts";
+
+/** Where a page is served, and its title: what a search hit links to. */
+export interface SourcePage {
+  title: string;
+  url: string;
+}
+
+/**
+ * Each search-indexable page's source file, relative to the project root,
+ * paired with the page it renders. The Mixedbread endpoint links a hit to its
+ * page through the path `mxbai store sync` recorded for the chunk's file,
+ * which is relative to wherever the CLI ran: the project root, or a directory
+ * above it in a monorepo. Pages from a source without local files have no
+ * path to match and are left out.
+ */
+export const sourcePages = (project: BlumeProject): [string, SourcePage][] =>
+  project.manifest.routes.flatMap((route): [string, SourcePage][] =>
+    route.indexable && route.sourcePath
+      ? [
+          [
+            relative(project.context.root, route.sourcePath),
+            { title: route.title, url: route.path },
+          ],
+        ]
+      : []
+  );

package/src/search/sync/algolia.ts

@@ -23,6 +23,87 @@ const BOOST_RANKING = "desc(boost)";
 const facetAttribute = (declaration: string): string =>
   declaration.replace(/^\w+\((?<name>.*)\)$/u, "$<name>");
 
+/**
+ * The largest record Algolia accepts on its Build and Grow plans, in bytes of
+ * the record's JSON. One larger record fails the whole upload.
+ */
+const MAX_RECORD_BYTES = 10_000;
+
+/**
+ * A record as uploaded: the search record's fields plus Algolia's `objectID`.
+ * (Mapped rather than the interface itself, which the SDK's
+ * `Record<string, unknown>` objects don't accept.)
+ */
+type AlgoliaObject = Pick<SearchRecord, keyof SearchRecord> & {
+  objectID: string;
+};
+
+/** A string's or record's size as Algolia measures it: UTF-8 bytes of its JSON. */
+const jsonBytes = (value: string | AlgoliaObject): number =>
+  Buffer.byteLength(JSON.stringify(value), "utf-8");
+
+/** The JSON of the widest single character: a control character's `\u` escape. */
+const WIDEST_CHARACTER = jsonBytes("\u0000");
+
+/** The length of `text`'s longest prefix whose JSON string fits `budget`. */
+const fittingLength = (text: string, budget: number): number => {
+  let size = jsonBytes("");
+  let end = 0;
+  [...text].some((character) => {
+    size += jsonBytes(character) - jsonBytes("");
+    if (size > budget) {
+      return true;
+    }
+    end += character.length;
+    return false;
+  });
+  return end;
+};
+
+/**
+ * Cut `text` into pieces whose JSON strings fit `budget` bytes each, at the
+ * last space that fits so no word is split; a run with no space in reach (an
+ * unspaced script, a long URL) is cut between characters.
+ */
+const splitText = (text: string, budget: number): string[] => {
+  const pieces: string[] = [];
+  let rest = text;
+  while (jsonBytes(rest) > budget) {
+    const end = fittingLength(rest, budget);
+    const space = rest.lastIndexOf(" ", end);
+    const cut = space > 0 ? space : end;
+    pieces.push(rest.slice(0, cut));
+    rest = rest.slice(cut).trimStart();
+  }
+  pieces.push(rest);
+  return pieces;
+};
+
+/**
+ * A page's record, split to fit Algolia's cap the way Algolia recommends for
+ * long documents: every piece carries the page's title, description, URL and
+ * facets with a stretch of its body, and the index's `distinct` on `url`
+ * shows the page once, at its best-matching piece. The first piece keeps the
+ * page's own `objectID`; the rest add `#1`, `#2`… A record whose other fields
+ * leave no room for a single character of body can't be split to fit, and
+ * uploads whole for Algolia to reject by name.
+ */
+const toObjects = (record: SearchRecord): AlgoliaObject[] => {
+  const whole = { ...record, objectID: record._id };
+  const budget =
+    MAX_RECORD_BYTES -
+    jsonBytes({ ...whole, content: "", objectID: `${record._id}#000` }) +
+    jsonBytes("");
+  if (jsonBytes(whole) <= MAX_RECORD_BYTES || budget < WIDEST_CHARACTER) {
+    return [whole];
+  }
+  return splitText(record.content, budget).map((content, index) => ({
+    ...record,
+    content,
+    objectID: index === 0 ? record._id : `${record._id}#${index}`,
+  }));
+};
+
 /**
  * Upload the search records to Algolia. Uses the admin key from
  * `ALGOLIA_ADMIN_API_KEY` (never the adapter options, which hold only the
@@ -30,9 +111,12 @@ const facetAttribute = (declaration: string): string =>
  *
  * Uses `replaceAllObjects`, which atomically replaces the index contents, so
  * pages deleted or renamed since the last sync don't linger as stale search
- * hits that 404 when clicked. Then adds `filterOnly(locale)` and
+ * hits that 404 when clicked. A page too long for one record is split across
+ * several (see {@link toObjects}). Then adds `filterOnly(locale)` and
  * `filterOnly(version)` to the index's `attributesForFaceting`, keeping any
- * the site declared itself, so the dialog's locale and version filters match.
+ * the site declared itself, so the dialog's locale and version filters match,
+ * and, once a page is split, `url` as the index's `attributeForDistinct`
+ * unless the site set its own.
  */
 export const syncAlgolia = async (
   records: SearchRecord[],
@@ -47,12 +131,13 @@ export const syncAlgolia = async (
   const { algoliasearch }: typeof AlgoliaSdk = nodeRequire("algoliasearch");
   const client = algoliasearch(config.appId, adminKey);
   const { indexName } = config;
-  await client.replaceAllObjects({
-    indexName,
-    objects: records.map((record) => ({ ...record, objectID: record._id })),
-  });
-  const { attributesForFaceting = [], customRanking = [] } =
-    await client.getSettings({ indexName });
+  const objects = records.flatMap(toObjects);
+  await client.replaceAllObjects({ indexName, objects });
+  const {
+    attributeForDistinct,
+    attributesForFaceting = [],
+    customRanking = [],
+  } = await client.getSettings({ indexName });
   const declared = new Set(attributesForFaceting.map(facetAttribute));
   const missing = FILTER_ATTRIBUTES.filter((name) => !declared.has(name));
   // Every record carries `boost` (search.boost, 1 by default): ranking by it
@@ -61,7 +146,11 @@ export const syncAlgolia = async (
   const ranksByBoost = customRanking.some((rule) =>
     /^(?:asc|desc)\(boost\)$/u.test(rule)
   );
-  if (missing.length === 0 && ranksByBoost) {
+  // A split page's records share its `url`: distinct on it lists the page
+  // once, at its best-matching record.
+  const setsDistinct =
+    objects.length > records.length && attributeForDistinct === undefined;
+  if (missing.length === 0 && ranksByBoost && !setsDistinct) {
     return;
   }
   const { taskID } = await client.setSettings({
@@ -74,6 +163,7 @@ export const syncAlgolia = async (
       customRanking: ranksByBoost
         ? customRanking
         : [...customRanking, BOOST_RANKING],
+      ...(setsDistinct && { attributeForDistinct: "url", distinct: true }),
     },
   });
   await client.waitForTask({ indexName, taskID });