blume 2.0.3 → 2.1.0

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,
@@ -162,9 +163,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 +247,10 @@ const playgroundProxyFiles = (
   needsPlaygroundProxy(config)
     ? [
         {
-          content: playgroundProxyTemplate(specOrigins(openApiData)),
+          content: playgroundProxyTemplate(
+            specOrigins(openApiData),
+            config.rateLimit
+          ),
           path: join(srcDir, PLAYGROUND_PROXY_ENTRY),
         },
       ]
@@ -667,6 +674,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,
@@ -869,8 +877,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 +888,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 +912,10 @@ export const eject = async (
 
   if (searchAdapter.kind === "mixedbread") {
     files.push({
-      content: mixedbreadSearchEndpointTemplate(searchAdapter.options),
+      content: mixedbreadSearchEndpointTemplate(
+        searchAdapter.options,
+        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/documents.ts

@@ -54,6 +54,10 @@ export interface SearchDocument {
    * Filterable through the MCP tools' `filters` input.
    */
   facets?: Record<string, string>;
+  /** Frontmatter `search.boost`: the page's relevance multiplier, when set. */
+  boost?: number;
+  /** Frontmatter `search.keywords`: extra terms the page is found by. */
+  keywords?: string[];
 }
 
 /**
@@ -77,6 +81,13 @@ export interface SearchRecord {
   version: string;
   /** Single faceting tag (the first frontmatter tag, when present). */
   tag?: string;
+  /**
+   * The page's relevance multiplier, 1 unless `search.boost` sets it: a
+   * ranking attribute every record carries, so the backend can sort by it.
+   */
+  boost: number;
+  /** Extra terms the page is found by (`search.keywords`). */
+  keywords?: string[];
 }
 
 // Tag-shaped only: a name (or closing slash/fragment) right after `<`, and no
@@ -414,6 +425,17 @@ const pageBody = async (
   });
 };
 
+/** The ranking a page asks for: its `search.boost` and `search.keywords`. */
+const rankingFields = (
+  search: PageRecord["meta"]["search"] | undefined
+): Pick<SearchDocument, "boost" | "keywords"> => {
+  const { boost, keywords } = search ?? {};
+  return {
+    ...(boost !== undefined && boost !== 1 && { boost }),
+    ...(keywords && keywords.length > 0 && { keywords }),
+  };
+};
+
 /**
  * Build search documents from the content graph. Only indexable pages are
  * included (per the route manifest), and content comes from the source files,
@@ -531,7 +553,7 @@ export const buildSearchDocuments = async (
       if (facets) {
         document.facets = facets;
       }
-      return document;
+      return { ...document, ...rankingFields(page?.meta?.search) };
     })
   );
 };
@@ -539,13 +561,15 @@ export const buildSearchDocuments = async (
 /**
  * Map per-page search documents to the flat record shape hosted backends
  * ingest. One record per page, keyed by route; the first tag becomes the
- * faceting `tag`.
+ * faceting `tag`, and every record carries a `boost` (1 by default).
  */
 export const toSearchRecords = (documents: SearchDocument[]): SearchRecord[] =>
   documents.map((doc) => ({
     _id: doc.route,
+    boost: doc.boost ?? 1,
     content: doc.content,
     description: doc.description,
+    ...(doc.keywords && { keywords: doc.keywords }),
     locale: doc.locale,
     tag: doc.tags?.[0],
     title: doc.title,

package/src/search/orama-index.ts

@@ -31,6 +31,10 @@ export interface OramaDoc {
    * but not indexed, so they ride along on the returned document untouched. */
   breadcrumb?: string[];
   section?: string;
+  /** The page's relevance multiplier (`search.boost`); stored, not indexed. */
+  boost?: number;
+  /** Extra terms the page is found by (`search.keywords`). */
+  keywords?: string[];
 }
 
 const SCHEMA = {
@@ -42,6 +46,7 @@ const SCHEMA = {
   // serves every project's facet keys, with `containsAll` matching a filter
   // set. Derived from `facets` at insert time.
   facetTerms: "enum[]",
+  keywords: "string[]",
   locale: "enum",
   route: "string",
   title: "string",
@@ -52,8 +57,21 @@ const SCHEMA = {
 const toFacetTerms = (facets: Record<string, string>): string[] =>
   Object.entries(facets).map(([key, value]) => `${key}:${value}`);
 
-/** Title and description outrank body text, matching the search dialog. */
-const BOOST = { description: 2, title: 3 };
+/**
+ * Title and description outrank body text, matching the search dialog; a
+ * page's keywords count as much as its title, since its author chose them.
+ */
+const BOOST = { description: 2, keywords: 3, title: 3 };
+
+/** Databases holding a boosted page, which rank by boosted score. */
+const boostedDatabases = new WeakSet<AnyOrama>();
+
+/** A search match as Orama's sort function sees it: id, score, document. */
+type RankedMatch = [unknown, number, OramaDoc];
+
+/** Rank matches by relevance times the page's `search.boost`. */
+const byBoostedScore = (a: RankedMatch, b: RankedMatch): number =>
+  b[1] * (b[2].boost ?? 1) - a[1] * (a[2].boost ?? 1);
 
 /**
  * The script whose text Orama's default tokenizer keeps mostly intact. Its
@@ -322,6 +340,9 @@ export const buildOramaIndex = async (
       doc.facets ? { ...doc, facetTerms: toFacetTerms(doc.facets) } : doc
     )
   );
+  if (documents.some((doc) => (doc.boost ?? 1) !== 1)) {
+    boostedDatabases.add(db);
+  }
   return db;
 };
 
@@ -391,10 +412,14 @@ export const queryOramaIndex = async (
   if (facetTerms.length > 0) {
     where.facetTerms = { containsAll: facetTerms };
   }
+  // Boosts multiply every match's score before the limit applies (Orama
+  // sorts the whole match set with a sort function), so a boosted page can
+  // rise past matches outside the first page.
   const unfiltered = {
     boost: BOOST,
     limit,
-    properties: ["title", "description", "content"],
+    properties: ["title", "keywords", "description", "content"],
+    ...(boostedDatabases.has(db) && { sortBy: byBoostedScore }),
     term,
   };
   const params =

package/src/search/pagefind-ranking.ts

@@ -0,0 +1,39 @@
+/**
+ * A page's `search.boost` and `search.keywords`, as Pagefind reads them from
+ * the built page. Pagefind has no page-level boost, only element weights, so
+ * the page's body carries its boost as its weight: a boosted page's matches
+ * count for more and it ranks higher. Pagefind damps repeated matches, so the
+ * lift is smaller than the full multiplier: a boost of 5 scored its page about
+ * 1.5 to 2 times higher in testing. A boost past Pagefind's largest weight,
+ * 10, counts as 10.
+ * Keywords go on an empty element as an indexed attribute, found like text
+ * and never shown.
+ */
+
+/** The largest weight Pagefind takes. */
+const MAX_WEIGHT = 10;
+
+/** The attribute a page's keywords ride on. */
+export const KEYWORDS_ATTRIBUTE = "data-blume-keywords";
+
+/** What the page body carries for Pagefind. */
+export interface PagefindRanking {
+  /** `data-pagefind-weight` for the body, when the page is boosted. */
+  weight?: string;
+  /** The keywords, space-separated, when the page sets any. */
+  keywords?: string;
+}
+
+export const pagefindRanking = (search: {
+  boost?: number;
+  keywords?: string[];
+}): PagefindRanking => {
+  const { boost, keywords } = search;
+  return {
+    ...(boost !== undefined &&
+      boost !== 1 && {
+        weight: String(Math.min(boost, MAX_WEIGHT)),
+      }),
+    ...(keywords && keywords.length > 0 && { keywords: keywords.join(" ") }),
+  };
+};

package/src/search/sync/algolia.ts

@@ -16,6 +16,9 @@ export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
  */
 const FILTER_ATTRIBUTES = ["locale", "version"] as const;
 
+/** The custom ranking rule that orders close matches by `search.boost`. */
+const BOOST_RANKING = "desc(boost)";
+
 /** A faceting declaration's attribute: `filterOnly(locale)` → `locale`. */
 const facetAttribute = (declaration: string): string =>
   declaration.replace(/^\w+\((?<name>.*)\)$/u, "$<name>");
@@ -48,12 +51,17 @@ export const syncAlgolia = async (
     indexName,
     objects: records.map((record) => ({ ...record, objectID: record._id })),
   });
-  const { attributesForFaceting = [] } = await client.getSettings({
-    indexName,
-  });
+  const { attributesForFaceting = [], customRanking = [] } =
+    await client.getSettings({ indexName });
   const declared = new Set(attributesForFaceting.map(facetAttribute));
   const missing = FILTER_ATTRIBUTES.filter((name) => !declared.has(name));
-  if (missing.length === 0) {
+  // Every record carries `boost` (search.boost, 1 by default): ranking by it
+  // after textual relevance puts boosted pages first among close matches.
+  // A ranking the site set in the dashboard keeps its place ahead of it.
+  const ranksByBoost = customRanking.some((rule) =>
+    /^(?:asc|desc)\(boost\)$/u.test(rule)
+  );
+  if (missing.length === 0 && ranksByBoost) {
     return;
   }
   const { taskID } = await client.setSettings({
@@ -63,6 +71,9 @@ export const syncAlgolia = async (
         ...attributesForFaceting,
         ...missing.map((name) => `filterOnly(${name})`),
       ],
+      customRanking: ranksByBoost
+        ? customRanking
+        : [...customRanking, BOOST_RANKING],
     },
   });
   await client.waitForTask({ indexName, taskID });

package/src/search/sync/orama-cloud.ts

@@ -31,9 +31,12 @@ export const syncOramaCloud = async (
   const index = manager.index(config.indexId);
   await index.snapshot(
     records.map((record) => ({
+      // The dialog multiplies each hit's score by it (search.boost).
+      boost: record.boost,
       content: record.content,
       description: record.description,
       id: record._id,
+      keywords: record.keywords ?? [],
       // Carried so an i18n site can filter hosted results per language.
       locale: record.locale,
       tag: record.tag,

package/src/search/sync/typesense.ts

@@ -57,6 +57,9 @@ export const syncTypesense = async (
       { name: "description", optional: true, type: "string" },
       { name: "content", type: "string" },
       { name: "url", type: "string" },
+      { name: "keywords", optional: true, type: "string[]" },
+      // The dialog sorts close matches by it (search.boost, 1 by default).
+      { name: "boost", type: "float" },
       { facet: true, name: "tag", optional: true, type: "string" },
       // Carried as facets so hosted results can filter per language and per
       // docs version (the SearchRecord contract; current docs = "current").
@@ -67,9 +70,11 @@ export const syncTypesense = async (
   });
 
   const documents = records.map((record) => ({
+    boost: record.boost,
     content: record.content,
     description: record.description,
     id: record._id,
+    keywords: record.keywords ?? [],
     locale: record.locale,
     tag: record.tag,
     title: record.title,

package/src/seo/metatags.ts

@@ -0,0 +1,67 @@
+/**
+ * Site-wide meta tags (`seo.metatags`): tags written into every page's head,
+ * for what Blume has no setting of its own for, such as site-verification
+ * tokens, `theme-color`, or an app banner. The tags Blume writes itself are
+ * refused, each pointing at the setting that controls it, so a page never
+ * carries two values for one tag.
+ */
+
+const IMAGE =
+  "`seo.og` for the generated cards, or `seo.image` in a page's frontmatter";
+const TITLE = "`title`, or `seo.title` in a page's frontmatter";
+const DESCRIPTION =
+  "`description` in a page's frontmatter or the config, or a page's `seo.description`";
+const FROM_PAGE = "Blume sets it from each page's type and dates";
+
+/** The tags Blume writes itself, by lowercase name, and what sets each. */
+const OWNED = new Map([
+  ["article:modified_time", FROM_PAGE],
+  ["article:published_time", FROM_PAGE],
+  ["description", DESCRIPTION],
+  ["og:description", DESCRIPTION],
+  ["og:site_name", "the config's `title`"],
+  ["og:title", TITLE],
+  ["og:type", FROM_PAGE],
+  ["og:url", "`deployment.site`, which sets each page's canonical URL"],
+  ["robots", "`seo.noindex` in a page's frontmatter"],
+  ["twitter:card", "Blume sets it from each page's image"],
+  ["twitter:creator", "`seo.x.creator` in the config or a page's frontmatter"],
+  ["twitter:description", DESCRIPTION],
+  ["twitter:site", "`seo.x.handle`"],
+  ["twitter:title", TITLE],
+  ["viewport", "Blume sets it for every page"],
+]);
+
+/** `og:image` and `twitter:image`, and their sub-properties. */
+const IMAGE_TAG = /^(?:og|twitter):image(?::|$)/u;
+
+/**
+ * What sets a tag Blume writes itself, or `undefined` for a tag the site can
+ * add.
+ */
+export const ownedMetatag = (name: string): string | undefined => {
+  const key = name.trim().toLowerCase();
+  return IMAGE_TAG.test(key) ? IMAGE : OWNED.get(key);
+};
+
+/**
+ * The Open Graph families, which the protocol names with `property`; every
+ * other tag takes `name`.
+ */
+const PROPERTY_TAG =
+  /^(?:og|fb|article|book|profile|music|video|al|product):/iu;
+
+/** One site-wide tag, as its `<meta>` element's attributes. */
+export interface MetatagAttributes {
+  content: string;
+  name?: string;
+  property?: string;
+}
+
+/** The site's `seo.metatags` as `<meta>` attributes, in the order written. */
+export const metatagAttributes = (
+  tags?: Readonly<Record<string, string>> | null
+): MetatagAttributes[] =>
+  Object.entries(tags ?? {}).map(([name, content]) =>
+    PROPERTY_TAG.test(name) ? { content, property: name } : { content, name }
+  );

package/src/theme/chrome-icons.ts

@@ -19,6 +19,7 @@ interface ChromeIconSet {
 
 export const chromeIcons: ChromeIconSet = {
   check: '<path d="M20 6 9 17l-5-5"/>',
+  "chevron-down": '<path d="m6 9 6 6 6-6"/>',
   copy: '<rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/>',
   file: '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/>',
   search: '<circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/>',