blume 2.2.2 → 2.2.3

package/src/core/schema.ts

@@ -207,10 +207,9 @@ const changelogMetaSchema = z.strictObject({
 
 /**
  * A post author: a bare name/handle, or an object with a name plus optional
- * avatar/URL. The object is passthrough so richer author metadata (social
- * handles, roles) survives untouched — Blume doesn't render authors yet, so
- * this exists to preserve the field (common on blog/changelog pages) rather
- * than have a strict scan reject it.
+ * avatar/URL. Blume credits the name and URL in the page's JSON-LD; the object
+ * is passthrough so richer author metadata (social handles, roles) survives
+ * untouched rather than have a strict scan reject it.
  */
 const authorSchema = z.union([
   z.string(),
@@ -254,7 +253,7 @@ const pageMetaBaseSchema = z.strictObject({
     .optional(),
   /** How this page's endpoint authenticates, over the site's `api.auth`. */
   authMethod: z.enum(AUTH_METHODS).optional(),
-  /** Post author(s) for blog/changelog content; preserved, not yet rendered. */
+  /** Post author(s) for blog/changelog content, credited in JSON-LD. */
   authors: z.union([authorSchema, z.array(authorSchema)]).optional(),
   changelog: changelogMetaSchema.optional(),
   /** Publish date for feed-backed content like blog/changelog. */
@@ -1609,8 +1608,9 @@ const ogConfigSchema = z.strictObject({
   /**
    * Generate a per-page Open Graph image. Defaults to on once a deployment
    * site URL is known (set or auto-detected) and off otherwise, since
-   * `og:image` must be absolute to be useful to crawlers — resolved in
-   * `loadConfig`. An explicit value here always wins.
+   * `og:image` must be absolute to be useful to crawlers, and off when `image`
+   * sets a default every page would show instead — resolved in `loadConfig`.
+   * An explicit value here always wins.
    */
   enabled: z.boolean().optional(),
   /**
@@ -1619,6 +1619,13 @@ const ogConfigSchema = z.strictObject({
    * families are fetched from Google Fonts at build.
    */
   fonts: z.array(ogFontSchema).optional(),
+  /**
+   * Default social image for pages without their own `seo.image`, in place of
+   * the generated card: one path or URL, or one per locale (resolved like any
+   * localizable label). A root-relative path is served under the deployment
+   * base.
+   */
+  image: localizableLabelSchema.optional(),
   /**
    * Local SVG used in the generated card instead of the site logo; `false`
    * renders the card without any brand mark.
@@ -1728,6 +1735,29 @@ type SoftwareResolved = z.output<typeof softwareConfigSchema>;
 
 /** Discoverability features: OG images, feeds, sitemap, structured data. */
 const seoConfigFields = {
+  /**
+   * Date pages without a front matter `date` by the git commit that added
+   * their source file, following exact renames. Off by default.
+   */
+  datePublished: z.union([z.literal(false), z.literal("git")]).default(false),
+  /**
+   * Structured-data entities shared with a parent site (`example.com/docs`),
+   * referenced by absolute `@id` instead of defined again (see `seo/jsonld.ts`).
+   */
+  jsonLd: z
+    .strictObject({
+      /** Credited on pages without their own `authors`. */
+      author: z.strictObject({ "@id": z.url() }).optional(),
+      /** The Organization's `@id`; `seo.organization` still adds its details. */
+      organizationId: z.url().optional(),
+      /** Every page's publisher, over the Organization. */
+      publisher: z.strictObject({ "@id": z.url() }).optional(),
+      /** Emit the WebSite node. Defaults to true unless `websiteId` is set. */
+      website: z.boolean().optional(),
+      /** The WebSite's `@id`, which every page names as `isPartOf`. */
+      websiteId: z.url().optional(),
+    })
+    .prefault({}),
   /**
    * Meta tags written into every page's head, name to content: site
    * verification, `theme-color`, and anything else Blume has no setting for.
@@ -1754,8 +1784,16 @@ const seoConfigFields = {
   /** Generate robots.txt (with a Sitemap reference when available). */
   robots: z.boolean().default(true),
   rss: rssConfigSchema.prefault({}),
-  /** Generate sitemap.xml (requires deployment.site). */
-  sitemap: z.boolean().default(true),
+  /**
+   * Generate sitemap.xml (requires deployment.site). `{ alternates: true }`
+   * also lists each page's translations as hreflang links.
+   */
+  sitemap: z
+    .union([
+      z.boolean(),
+      z.strictObject({ alternates: z.boolean().default(false) }),
+    ])
+    .default(true),
   /** The documented product, as a homepage `SoftwareApplication` node. */
   software: z
     .union([z.boolean(), softwareConfigSchema])

package/src/core/types.ts

@@ -256,6 +256,11 @@ export interface PageRecord {
   unknownProps?: ElementUse[];
   /** Resolved "last updated" ISO date, when the feature is enabled. */
   lastModified?: string;
+  /**
+   * The git commit that added the source file, as an ISO date, when
+   * `seo.datePublished` is `"git"` and front matter carries no `date`.
+   */
+  published?: string;
   /** Absolute paths of files this page `<include>`s, transitively. Drives the
    * dev-server invalidation edge from a partial to the pages that splice it. */
   includes?: string[];
@@ -484,6 +489,11 @@ export interface RouteManifestEntry {
   aiExclude?: boolean;
   /** Resolved "last updated" ISO date, when the feature is enabled. */
   lastModified?: string;
+  /**
+   * The git commit that added the source file, as an ISO date, when
+   * `seo.datePublished` is `"git"` and front matter carries no `date`.
+   */
+  published?: string;
 }
 
 /** The generated runtime contract between core and the Astro project. */

package/src/deploy/sitemap.ts

@@ -14,6 +14,7 @@ import {
 import { isHiddenPage } from "../core/hidden-pages.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import { siteRoot } from "../core/site-url.ts";
+import type { RouteAlternate } from "../core/types.ts";
 
 /**
  * Astro's reserved error routes. A user-authored override (`pages/404.astro`,
@@ -79,13 +80,95 @@ export const describeSitemapFiles = (files: readonly SitemapFile[]): string =>
 const URLS_PER_FILE = 50_000;
 
 const renderUrlset = (
-  urls: string[]
+  urls: string[],
+  alternatesEnabled: boolean
 ): string => `<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${alternatesEnabled ? ' xmlns:xhtml="http://www.w3.org/1999/xhtml"' : ""}>
 ${urls.join("\n")}
 </urlset>
 `;
 
+/**
+ * The content pages crawlers may index under their own URL: drafts, hidden,
+ * `noindex` (the page's or its archived version's), and error pages can't, nor
+ * can a page whose own `seo.canonical` names another URL.
+ */
+const indexablePages = (
+  project: BlumeProject
+): BlumeProject["graph"]["pages"] => {
+  const deployBase = normalizeBasePath(project.config.deployment.options.base);
+  // A non-empty version always names a configured archived entry — that is
+  // the only way detection assigns one.
+  const noindexVersions = new Set(
+    (project.config.versions?.archived ?? []).flatMap((version) =>
+      version.noindex ? [version.id] : []
+    )
+  );
+  return project.graph.pages.filter(
+    (page) =>
+      !page.meta.draft &&
+      !isHiddenPage(page, project.graph) &&
+      !page.meta.seo.noindex &&
+      !noindexVersions.has(page.version) &&
+      !ERROR_ROUTES.has(page.route) &&
+      !canonicalElsewhere(
+        page.meta.seo.canonical,
+        mountBasePath(deployBase, page.route)
+      )
+  );
+};
+
+/**
+ * The content pages the sitemap lists: the indexable ones, less archived-version
+ * pages whose canonical points at a still-existing latest equivalent —
+ * listing a URL whose canonical says "index the other page" invites the
+ * noindexed-page-in-sitemap incoherence Docusaurus is known for. A page that
+ * exists only in an archived version stays listed (self-canonical), and a
+ * page's own `seo.canonical` wins over the version's default, as it does in
+ * the page head (see `canonicalElsewhere`).
+ */
+const listedPages = (project: BlumeProject): BlumeProject["graph"]["pages"] => {
+  const latestVersions = new Set(
+    (project.config.versions?.archived ?? []).flatMap((version) =>
+      version.canonical === "latest" ? [version.id] : []
+    )
+  );
+  const currentKeys = new Set(
+    project.graph.pages.flatMap((page) =>
+      page.version === "" ? [`${page.versionKey}\u0000${page.locale}`] : []
+    )
+  );
+  return indexablePages(project).filter(
+    (page) =>
+      !(
+        latestVersions.has(page.version) &&
+        !page.meta.seo.canonical &&
+        currentKeys.has(`${page.versionKey}\u0000${page.locale}`)
+      )
+  );
+};
+
+/**
+ * Each route's hreflang set, keyed by route: its indexable translations. The
+ * page head links it, and so does the sitemap under `seo.sitemap.alternates`,
+ * so the two never disagree, and neither points crawlers at a page they're
+ * told not to index. A page that can't be indexed joins no set — except an
+ * i18n fallback copy, which links the translations it stands in for.
+ */
+export const hreflangAlternates = (
+  project: BlumeProject
+): Map<string, RouteAlternate[]> => {
+  const indexable = new Set(indexablePages(project).map((page) => page.route));
+  return new Map(
+    project.manifest.routes.map((route) => [
+      route.path,
+      route.fallback || indexable.has(route.path)
+        ? route.alternates.filter((alternate) => indexable.has(alternate.path))
+        : [],
+    ])
+  );
+};
+
 /**
  * Build the sitemap files from the route manifest plus the routes the manifest
  * can't see: custom `.astro` pages (most importantly a custom landing `/`) and
@@ -112,43 +195,38 @@ export const buildSitemapFiles = (
   // top of every one, even a route whose first segment matches it: under base
   // `/guides`, `guides/setup.md` is served at `/guides/guides/setup`.
   const deployBase = normalizeBasePath(project.config.deployment.options.base);
-
-  // Archived-version pages leave the sitemap when the version is noindexed,
-  // or when their canonical points at a still-existing latest equivalent —
-  // listing a URL whose canonical says "index the other page" invites the
-  // noindexed-page-in-sitemap incoherence Docusaurus is known for. A page
-  // that exists only in an archived version stays listed (self-canonical),
-  // and a page's own `seo.canonical` wins over the version's default, as it
-  // does in the page head (see `canonicalElsewhere`).
-  const { versions } = project.config;
-  const archivedById = new Map(
-    (versions?.archived ?? []).map((version) => [version.id, version])
-  );
-  const currentKeys = versions
-    ? new Set(
-        project.graph.pages.flatMap((page) =>
-          page.version === "" ? [`${page.versionKey}\u0000${page.locale}`] : []
-        )
-      )
-    : null;
-  const archivedExcluded = (page: (typeof project.graph.pages)[number]) => {
-    if (!page.version) {
-      return false;
+  const alternatesEnabled =
+    project.config.seo.sitemap !== true &&
+    project.config.seo.sitemap.alternates;
+  const hreflang = alternatesEnabled ? hreflangAlternates(project) : null;
+  // A page's translations as `xhtml:link`s, plus `x-default` at the default
+  // locale's — the same set the page head links, for pages in 2+ locales.
+  const alternateTags = (route: string): string => {
+    const alternates = hreflang?.get(route) ?? [];
+    if (alternates.length < 2) {
+      return "";
     }
-    // A non-empty version always names a configured archived entry — that is
-    // the only way detection assigns one.
-    const archived = archivedById.get(page.version);
-    return Boolean(
-      archived?.noindex ||
-      (archived?.canonical === "latest" &&
-        !page.meta.seo.canonical &&
-        currentKeys?.has(`${page.versionKey}\u0000${page.locale}`))
+    const defaultPage = alternates.find(
+      (entry) => entry.locale === project.config.i18n?.defaultLocale
     );
+    const links = defaultPage
+      ? [...alternates, { ...defaultPage, locale: "x-default" }]
+      : alternates;
+    return links
+      .map(
+        (entry) =>
+          `<xhtml:link rel="alternate" hreflang="${escapeXml(entry.locale)}" href="${escapeXml(encodeURI(`${base}${mountBasePath(deployBase, entry.path)}`))}"/>`
+      )
+      .join("");
   };
 
   const seen = new Set<string>();
   const urls: string[] = [];
-  const pushUrl = (route: string, lastModified?: string): void => {
+  const pushUrl = (
+    route: string,
+    lastModified?: string,
+    alternates = ""
+  ): void => {
     // `<loc>` must be a well-formed, XML-escaped URL: percent-encode the path,
     // then escape XML metacharacters (notably `&`) so a route like
     // `/Tips & Tricks` doesn't produce invalid XML that gets the whole sitemap
@@ -158,21 +236,16 @@ export const buildSitemapFiles = (
       return;
     }
     seen.add(loc);
-    urls.push(`  <url><loc>${loc}</loc>${lastmodTag(lastModified)}</url>`);
+    urls.push(
+      `  <url><loc>${loc}</loc>${lastmodTag(lastModified)}${alternates}</url>`
+    );
   };
-  for (const page of project.graph.pages) {
-    const served = mountBasePath(deployBase, page.route);
-    if (
-      page.meta.draft ||
-      isHiddenPage(page, project.graph) ||
-      page.meta.seo.noindex ||
-      ERROR_ROUTES.has(page.route) ||
-      archivedExcluded(page) ||
-      canonicalElsewhere(page.meta.seo.canonical, served)
-    ) {
-      continue;
-    }
-    pushUrl(served, page.lastModified);
+  for (const page of listedPages(project)) {
+    pushUrl(
+      mountBasePath(deployBase, page.route),
+      page.lastModified,
+      alternateTags(page.route)
+    );
   }
   // Custom `.astro` pages and the generated changelog index mount outside
   // `basePath` (they're injected at their pattern — see `blumeIntegration`), so
@@ -192,7 +265,9 @@ export const buildSitemapFiles = (
   urls.sort();
 
   if (urls.length <= URLS_PER_FILE) {
-    return [{ name: "sitemap.xml", xml: renderUrlset(urls) }];
+    return [
+      { name: "sitemap.xml", xml: renderUrlset(urls, alternatesEnabled) },
+    ];
   }
 
   const chunks: SitemapFile[] = [];
@@ -201,7 +276,10 @@ export const buildSitemapFiles = (
     const name = `sitemap-${chunks.length + 1}.xml`;
     chunks.push({
       name,
-      xml: renderUrlset(urls.slice(start, start + URLS_PER_FILE)),
+      xml: renderUrlset(
+        urls.slice(start, start + URLS_PER_FILE),
+        alternatesEnabled
+      ),
     });
     // Chunks sit next to sitemap.xml, so their URLs layer the same deployment
     // base robots.txt uses for the index.

package/src/search/documents.ts

@@ -11,6 +11,8 @@ import type {
   DownlevelWalk,
   MdastNode as DownlevelNode,
 } from "../ai/component-markdown.ts";
+import { relativeLinkRewriter } from "../ai/relative-links.ts";
+import type { RelativeLinkRewriter } from "../ai/relative-links.ts";
 import { projectComponentSerializers } from "../ai/serializers.ts";
 import { applyAudienceVisibility } from "../ai/visibility.ts";
 import type { VisibilityAudience } from "../ai/visibility.ts";
@@ -399,17 +401,20 @@ interface BuildOptions {
 
 /**
  * Read a page's body and reduce it per the extraction options. The
- * `"markdown"` body is agent-facing, so its components are downleveled in the
- * source with the serializers every agent surface uses (front matter in scope
- * for prop expressions). The plain body is parsed as written and walked, with
- * the same serializers applied per component on the way, so the index reads a
- * `<Card>` or `<TypeTable>` as the text it shows.
+ * `"markdown"` body, the one `rewriteLinks` comes with, is agent-facing: its
+ * page links are rewritten, then its components downleveled in the source
+ * with the serializers every agent surface uses (front matter in scope for
+ * prop expressions), in the order llms-full.txt takes. The plain body is
+ * parsed as written and walked, with the same serializers applied per
+ * component on the way, so the index reads a `<Card>` or `<TypeTable>` as
+ * the text it shows.
  */
 const pageBody = async (
   project: BlumeProject,
   page: PageRecord | undefined,
-  options: Pick<BuildOptions, "audience" | "content"> | undefined,
-  components: Record<string, ComponentMarkdown>
+  options: Pick<BuildOptions, "audience"> | undefined,
+  components: Record<string, ComponentMarkdown>,
+  rewriteLinks: RelativeLinkRewriter | undefined
 ): Promise<string> => {
   if (!page) {
     return "";
@@ -419,8 +424,12 @@ const pageBody = async (
     parsed.content,
     options?.audience ?? "web"
   );
-  if (options?.content === "markdown") {
-    return downlevelComponents(visible.trim(), components, parsed.data);
+  if (rewriteLinks) {
+    return downlevelComponents(
+      rewriteLinks(visible, page).trim(),
+      components,
+      parsed.data
+    );
   }
   return toPlainText(visible, page.format, {
     downlevel: {
@@ -460,7 +469,9 @@ const rankingFields = (
  * same serializers the `.md` mirror, llms-full.txt and MCP `get_page` use: a
  * page whose body is a `<CardGroup>` of `<Card>`s is prose to a reader and bare
  * JSX to anything reading the source, and section landing pages are exactly
- * that shape.
+ * that shape. Its page links point at the pages they mean, as they do there
+ * too, as the routes the assistant's snapshot keys those pages by (see
+ * `relativeLinkRewriter`'s `assistant`): the model cites the links it reads.
  *
  * `audience` resolves `<Visibility>` blocks before extraction: `"web"`
  * (default) keeps web-only content and drops agents-only blocks — the site
@@ -518,6 +529,12 @@ export const buildSearchDocuments = async (
   // Built once — `downlevelComponents` rebuilds its registry per call
   // otherwise.
   const components = projectComponentSerializers(project);
+  // The `"markdown"` body is the assistant's: the model cites the links it
+  // reads, so a page link points at the page the snapshot holds.
+  const rewriteLinks =
+    options?.content === "markdown"
+      ? relativeLinkRewriter(project, { assistant: true })
+      : undefined;
 
   // A page in no sidebar group falls under the "Docs" section, in its own
   // language: the label is a UI string, resolved once per locale.
@@ -542,7 +559,13 @@ export const buildSearchDocuments = async (
   return await Promise.all(
     indexable.map(async (route) => {
       const page = pageById.get(route.id);
-      const body = await pageBody(project, page, options, components);
+      const body = await pageBody(
+        project,
+        page,
+        options,
+        components,
+        rewriteLinks
+      );
       const tags = page?.meta?.search?.tags;
       const crumb = crumbs.get(route.path);
       const facets = page ? pageFacets(page, project.config) : undefined;

package/src/search/fold.ts

@@ -0,0 +1,175 @@
+/**
+ * Latin folding, shared by the search index and everything that finds a query
+ * in a page's text afterwards: the search dialog's highlights and excerpts,
+ * and the assistant's excerpts. The index matches Prüfung for `prufung`, so
+ * the rest must too, or a page found by folding shows its opening with
+ * nothing marked.
+ */
+
+/** A Latin letter and the combining marks on it, which NFD splits off. */
+const LATIN_ACCENTS = /(?<letter>\p{Script=Latin})\p{M}+/gu;
+
+/** A Latin character outside ASCII, once NFD has split off its accents. */
+const NON_ASCII_LATIN = /(?=\P{ASCII})\p{Script=Latin}/gu;
+
+/**
+ * Latin letters NFD leaves whole, spelled the way an unaccented query types
+ * them. Orama's own diacritics table folds the same letters, though its
+ * English splitter cuts words at them first.
+ */
+const LATIN_FOLDS = new Map([
+  ["ß", "ss"],
+  ["æ", "ae"],
+  ["œ", "oe"],
+  ["ø", "o"],
+  ["ł", "l"],
+  ["đ", "d"],
+  ["ð", "d"],
+  ["ħ", "h"],
+  ["ı", "i"],
+  ["þ", "th"],
+]);
+
+/**
+ * U+00AD, the invisible break hint `&shy;` writes inside a long word. It
+ * belongs to no word: split there, Prüfungs&shy;ordnung would index as two.
+ */
+const SOFT_HYPHEN = /\u00AD/gu;
+
+/** `text` without its soft hyphens. */
+export const stripSoftHyphens = (text: string): string =>
+  text.replace(SOFT_HYPHEN, "");
+
+/**
+ * Fold lowercased text's Latin letters to the plain letters an unaccented
+ * query types: accents drop (café → cafe), letters NFD leaves whole are
+ * spelled out (Łódź → lodz, ışık and IŞIK → isik, Straße → strasse), and
+ * compatibility forms unpack (the fi ligature → fi, fullwidth ＡＰＩ → api).
+ * Soft hyphens go too. Marks on any other script, and marks on no letter
+ * (the keycap in 1️⃣), stay.
+ */
+export const foldLatin = (lowered: string): string =>
+  stripSoftHyphens(lowered)
+    .normalize("NFD")
+    .replace(
+      NON_ASCII_LATIN,
+      (letter) =>
+        LATIN_FOLDS.get(letter) ?? letter.normalize("NFKD").toLowerCase()
+    )
+    .replace(LATIN_ACCENTS, "$<letter>");
+
+/**
+ * A run of Latin letters and the marks on them (lowercase İ is i plus a
+ * combining dot), inside a term of any script.
+ */
+const LATIN_RUN = /\p{Script=Latin}[\p{Script=Latin}\p{M}]*/gu;
+
+/**
+ * {@link foldLatin} for the Latin letters of a lowercased term, whatever
+ * script the rest of it is in: a segmenter keeps caféनमस्ते together as one
+ * term. Only the Latin runs fold. Marks are spelling elsewhere (Thai vowels
+ * and tones; the breve that separates Cyrillic й from и), and NFD would split
+ * a Hangul syllable into its jamo.
+ */
+export const foldLatinTerm = (term: string): string =>
+  term.replace(LATIN_RUN, (run) => foldLatin(run));
+
+/**
+ * The Unicode blocks holding Latin letters outside ASCII: Latin-1 through
+ * Latin Extended-B, the phonetic extensions and Latin Extended Additional,
+ * superscripts through number forms, Latin Extended-C, -D and -E, the
+ * ligatures, and the fullwidth forms.
+ */
+const LATIN_BLOCKS = [
+  [0x00_80, 0x02_4f],
+  [0x1d_00, 0x1e_ff],
+  [0x20_70, 0x21_8f],
+  [0x2c_60, 0x2c_7f],
+  [0xa7_20, 0xa7_ff],
+  [0xab_30, 0xab_6f],
+  [0xfb_00, 0xfb_06],
+  [0xff_21, 0xff_5a],
+] as const;
+
+const LATIN = /^\p{Script=Latin}$/u;
+const PLAIN = /^[a-z]+$/u;
+
+let spellings: Map<string, string> | undefined;
+
+/**
+ * Every Latin character outside ASCII that folds to plain letters, keyed by
+ * those letters: `a` → àáâ…, `ss` → ßẞ. Built on first use, not at import.
+ */
+const latinSpellings = (): Map<string, string> => {
+  if (spellings) {
+    return spellings;
+  }
+  spellings = new Map();
+  for (const [first, last] of LATIN_BLOCKS) {
+    for (let code = first; code <= last; code += 1) {
+      const char = String.fromCodePoint(code);
+      const plain = foldLatin(char.toLowerCase());
+      if (LATIN.test(char) && PLAIN.test(plain)) {
+        spellings.set(plain, `${spellings.get(plain) ?? ""}${char}`);
+      }
+    }
+  }
+  return spellings;
+};
+
+/** A Latin letter in a query, with the marks a decomposed query puts on it. */
+const QUERY_LETTER = /\p{Script=Latin}\p{M}*/gu;
+
+const REGEXP_SPECIAL = /[$()*+.?[\\\]^{|}]/gu;
+
+/** What may follow a letter inside a word: its accents, or a soft hyphen. */
+const LETTER_TAIL = String.raw`[\p{M}\u00AD]*`;
+
+/**
+ * The longest plain spelling a single character folds to (ⅷ → viii), so the
+ * pattern builder knows how far ahead to look.
+ */
+const longestSpelling = (folds: Map<string, string>): number =>
+  Math.max(...[...folds.keys()].map((plain) => plain.length));
+
+/**
+ * A regex source that finds `term` in unfolded text whatever accents, soft
+ * hyphens or spelled-out letters its Latin words carry there: `prufung`
+ * matches Prüfung, `strasse` matches Straße. Compile it with the `iu` flags.
+ * Characters outside Latin match as themselves.
+ */
+export const accentInsensitive = (term: string): string => {
+  const folds = latinSpellings();
+  const longest = longestSpelling(folds);
+  const letter = (plain: string): string =>
+    `[${plain}${folds.get(plain) ?? ""}]${LETTER_TAIL}`;
+  const chars = [
+    ...stripSoftHyphens(term.toLowerCase()).replace(QUERY_LETTER, (latin) =>
+      foldLatin(latin)
+    ),
+  ];
+  let source = "";
+  let index = 0;
+  while (index < chars.length) {
+    let length = Math.min(longest, chars.length - index);
+    // The longest run here that a single character spells out — `ss` for ß.
+    while (
+      length > 1 &&
+      !folds.has(chars.slice(index, index + length).join(""))
+    ) {
+      length -= 1;
+    }
+    const run = chars.slice(index, index + length);
+    const plain = run.join("");
+    if (length > 1) {
+      const letters = run.map((char) => letter(char)).join("");
+      source += `(?:${letters}|[${folds.get(plain) ?? ""}]${LETTER_TAIL})`;
+    } else if (PLAIN.test(plain)) {
+      source += letter(plain);
+    } else {
+      source += plain.replaceAll(REGEXP_SPECIAL, String.raw`\$&`);
+    }
+    index += length;
+  }
+  return source;
+};