blume 1.7.2 → 2.0.0

package/dist/types/search/adapters/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Search adapters for `blume.config.ts`:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { algolia } from "blume/search";
+ *
+ * export default defineConfig({
+ *   search: algolia({ appId: "…", apiKey: "…", indexName: "docs" }),
+ * });
+ * ```
+ *
+ * Each factory returns a plain, JSON-serializable descriptor — never a live
+ * client — that the generated runtime inlines as a literal.
+ */
+export { algolia } from "./algolia.ts";
+export type { AlgoliaAdapter, AlgoliaOptions } from "./algolia.ts";
+export { flexsearch } from "./flexsearch.ts";
+export type { FlexsearchAdapter, FlexsearchOptions } from "./flexsearch.ts";
+export { mixedbread } from "./mixedbread.ts";
+export type { MixedbreadAdapter, MixedbreadOptions } from "./mixedbread.ts";
+export { orama } from "./orama.ts";
+export type { OramaAdapter, OramaOptions } from "./orama.ts";
+export { oramaCloud } from "./orama-cloud.ts";
+export type { OramaCloudAdapter, OramaCloudOptions } from "./orama-cloud.ts";
+export { pagefind } from "./pagefind.ts";
+export type { PagefindAdapter, PagefindOptions } from "./pagefind.ts";
+export type { AnySearchAdapter, ResolvedSearchAdapter, SearchAdapterKind, } from "./registry.ts";
+export type { KeylessSearchOptions, SearchAdapter, SearchAdapterMode, } from "./types.ts";
+export { typesense } from "./typesense.ts";
+export type { TypesenseAdapter, TypesenseOptions } from "./typesense.ts";

package/dist/types/search/adapters/mixedbread.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import type { JsonValue } from "../../core/adapter.ts";
+import type { SearchAdapter } from "./types.ts";
+/**
+ * The Mixedbread store the generated `/api/search` endpoint queries, plus any
+ * other option, forwarded to the endpoint verbatim. JSON values only.
+ */
+export interface MixedbreadOptions {
+    storeId: string;
+    [option: string]: JsonValue;
+}
+export type MixedbreadAdapter = SearchAdapter<"mixedbread", "server", MixedbreadOptions>;
+export declare const mixedbreadOptionsSchema: z.ZodObject<{
+    storeId: z.ZodString;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+/**
+ * Semantic search on Mixedbread. Queries go through a generated `/api/search`
+ * endpoint that holds `MIXEDBREAD_API_KEY`, so the adapter requires server
+ * output. Content is synced to the store out-of-band with the `mxbai` CLI,
+ * not by the build.
+ */
+export declare const mixedbread: (options: MixedbreadOptions) => MixedbreadAdapter;

package/dist/types/search/adapters/orama-cloud.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { JsonValue } from "../../core/adapter.ts";
+import type { SearchAdapter } from "./types.ts";
+/**
+ * Public Orama Cloud credentials. The browser queries `endpoint` with the
+ * public `apiKey`; the build-time sync pushes records to `indexId` with
+ * `ORAMA_PRIVATE_API_KEY`, which never enters the config.
+ */
+export interface OramaCloudNamedOptions {
+    /** The public API key (it ships to the browser). */
+    apiKey: string;
+    endpoint: string;
+    /** Index id used by the build-time sync; omit to skip syncing. */
+    indexId?: string;
+}
+/**
+ * Options for {@link oramaCloud}: the named options plus any other client
+ * option, forwarded to the browser verbatim. JSON values only.
+ */
+export type OramaCloudOptions = OramaCloudNamedOptions & {
+    [option: string]: JsonValue;
+};
+export type OramaCloudAdapter = SearchAdapter<"orama-cloud", "hosted", OramaCloudOptions>;
+export declare const oramaCloudOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    endpoint: z.ZodString;
+    indexId: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+/**
+ * Hosted Orama. The browser queries your index endpoint directly; each
+ * `blume build` snapshots the records into the index and deploys it.
+ */
+export declare const oramaCloud: (options: OramaCloudOptions) => OramaCloudAdapter;

package/dist/types/search/adapters/orama.d.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import type { KeylessSearchOptions, SearchAdapter } from "./types.ts";
+/** Orama takes no options; unknown keys fail config validation. */
+export type OramaOptions = KeylessSearchOptions;
+export type OramaAdapter = SearchAdapter<"orama", "static", OramaOptions>;
+export declare const oramaOptionsSchema: z.ZodObject<{}, z.core.$strict>;
+/**
+ * Blume's default search: a JSON index built from the source files, served
+ * at `/blume-search.json` and queried in the browser. Keyless, and live in
+ * `blume dev`. The tokenizer follows `i18n.defaultLocale`, so non-Latin
+ * scripts are word-segmented.
+ */
+export declare const orama: (options?: OramaOptions) => OramaAdapter;

package/dist/types/search/adapters/pagefind.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import type { KeylessSearchOptions, SearchAdapter } from "./types.ts";
+/** Pagefind takes no options; unknown keys fail config validation. */
+export type PagefindOptions = KeylessSearchOptions;
+export type PagefindAdapter = SearchAdapter<"pagefind", "pagefind", PagefindOptions>;
+export declare const pagefindOptionsSchema: z.ZodObject<{}, z.core.$strict>;
+/**
+ * Pagefind indexes the built HTML after `blume build` and loads the index in
+ * shards on demand, so the initial payload stays small on very large sites.
+ * The index only exists in the production build, not in `blume dev`.
+ */
+export declare const pagefind: (options?: PagefindOptions) => PagefindAdapter;

package/dist/types/search/adapters/registry.d.ts

@@ -0,0 +1,228 @@
+import { z } from "zod";
+import type { AlgoliaAdapter } from "./algolia.ts";
+import type { FlexsearchAdapter } from "./flexsearch.ts";
+import type { MixedbreadAdapter } from "./mixedbread.ts";
+import type { OramaCloudAdapter } from "./orama-cloud.ts";
+import type { OramaAdapter } from "./orama.ts";
+import type { PagefindAdapter } from "./pagefind.ts";
+import type { KeylessSearchOptions, SearchAdapter } from "./types.ts";
+import type { TypesenseAdapter } from "./typesense.ts";
+/** Every descriptor a factory can return. */
+export type AnySearchAdapter = AlgoliaAdapter | FlexsearchAdapter | MixedbreadAdapter | OramaAdapter | OramaCloudAdapter | PagefindAdapter | TypesenseAdapter;
+/** The resolved form of `search: false`: search is disabled. */
+export type NoneSearchAdapter = SearchAdapter<"none", "none", KeylessSearchOptions>;
+/** What `config.search.provider` resolves to: an adapter, or `none`. */
+export type ResolvedSearchAdapter = AnySearchAdapter | NoneSearchAdapter;
+/** Every adapter identity, including the resolved `none`. */
+export type SearchAdapterKind = ResolvedSearchAdapter["kind"];
+export declare const NONE_SEARCH_ADAPTER: NoneSearchAdapter;
+/** One variant per public adapter factory. */
+declare const adapterVariants: readonly [z.ZodObject<{
+    kind: z.ZodLiteral<"algolia">;
+    options: z.ZodObject<{
+        apiKey: z.ZodString;
+        appId: z.ZodString;
+        indexName: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"hosted">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"flexsearch">;
+    options: z.ZodObject<{}, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"static">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"mixedbread">;
+    options: z.ZodObject<{
+        storeId: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"server">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"orama">;
+    options: z.ZodObject<{}, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"static">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"orama-cloud">;
+    options: z.ZodObject<{
+        apiKey: z.ZodString;
+        endpoint: z.ZodString;
+        indexId: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"hosted">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"pagefind">;
+    options: z.ZodObject<{}, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"pagefind">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"typesense">;
+    options: z.ZodObject<{
+        apiKey: z.ZodString;
+        collection: z.ZodString;
+        host: z.ZodString;
+        port: z.ZodOptional<z.ZodNumber>;
+        protocol: z.ZodOptional<z.ZodEnum<{
+            http: "http";
+            https: "https";
+        }>>;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"hosted">;
+}, z.core.$strict>];
+/** What a public factory returns, as the config schema accepts it. */
+export type SearchAdapterInput = z.input<(typeof adapterVariants)[number]>;
+/**
+ * Validates a descriptor — one a factory returned, or the `none` descriptor
+ * the config schema substitutes for `false` — and resolves it to the
+ * canonical form, so every consumer reads `mode`, `runtimeDeps`, and
+ * `requiredSecrets` straight off the descriptor. `none` is internal: it is
+ * not part of {@link SearchAdapterInput}, so `search: { kind: "none" }` is a
+ * type error even though the runtime schema admits it.
+ */
+export declare const resolvedSearchAdapterSchema: z.ZodPipe<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"algolia">;
+    options: z.ZodObject<{
+        apiKey: z.ZodString;
+        appId: z.ZodString;
+        indexName: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"hosted">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"flexsearch">;
+    options: z.ZodObject<{}, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"static">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"mixedbread">;
+    options: z.ZodObject<{
+        storeId: z.ZodString;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"server">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"orama">;
+    options: z.ZodObject<{}, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"static">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"orama-cloud">;
+    options: z.ZodObject<{
+        apiKey: z.ZodString;
+        endpoint: z.ZodString;
+        indexId: z.ZodOptional<z.ZodString>;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"hosted">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"pagefind">;
+    options: z.ZodObject<{}, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"pagefind">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"typesense">;
+    options: z.ZodObject<{
+        apiKey: z.ZodString;
+        collection: z.ZodString;
+        host: z.ZodString;
+        port: z.ZodOptional<z.ZodNumber>;
+        protocol: z.ZodOptional<z.ZodEnum<{
+            http: "http";
+            https: "https";
+        }>>;
+    }, z.core.$catchall<z.ZodJSONSchema>>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"hosted">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"none">;
+    options: z.ZodObject<{}, z.core.$strict>;
+    requiredSecrets: z.ZodArray<z.ZodString>;
+    runtimeDeps: z.ZodArray<z.ZodString>;
+    mode: z.ZodLiteral<"none">;
+}, z.core.$strict>], "kind">, z.ZodTransform<NoneSearchAdapter | AlgoliaAdapter | FlexsearchAdapter | MixedbreadAdapter | OramaAdapter | OramaCloudAdapter | PagefindAdapter | TypesenseAdapter, {
+    kind: "algolia";
+    options: {
+        [x: string]: z.core.util.JSONType;
+        apiKey: string;
+        appId: string;
+        indexName: string;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+    mode: "hosted";
+} | {
+    kind: "flexsearch";
+    options: Record<string, never>;
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+    mode: "static";
+} | {
+    kind: "mixedbread";
+    options: {
+        [x: string]: z.core.util.JSONType;
+        storeId: string;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+    mode: "server";
+} | {
+    kind: "orama";
+    options: Record<string, never>;
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+    mode: "static";
+} | {
+    kind: "orama-cloud";
+    options: {
+        [x: string]: z.core.util.JSONType;
+        apiKey: string;
+        endpoint: string;
+        indexId?: string | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+    mode: "hosted";
+} | {
+    kind: "pagefind";
+    options: Record<string, never>;
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+    mode: "pagefind";
+} | {
+    kind: "typesense";
+    options: {
+        [x: string]: z.core.util.JSONType;
+        apiKey: string;
+        collection: string;
+        host: string;
+        port?: number | undefined;
+        protocol?: "http" | "https" | undefined;
+    };
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+    mode: "hosted";
+} | {
+    kind: "none";
+    options: Record<string, never>;
+    requiredSecrets: string[];
+    runtimeDeps: string[];
+    mode: "none";
+}>>;
+export {};

package/dist/types/search/adapters/types.d.ts

@@ -0,0 +1,34 @@
+import type { AdapterDescriptor } from "../../core/adapter.ts";
+/**
+ * How a search adapter integrates with the generated runtime.
+ *
+ * - `static` adapters ship a client-side index (`blume-search.json`) that the
+ *   browser loads and queries — Orama, FlexSearch.
+ * - `pagefind` builds its own index from the rendered HTML after the build.
+ * - `hosted` adapters are queried directly from the browser against an
+ *   external service, with a build-time sync uploading the index — Algolia,
+ *   Orama Cloud, Typesense.
+ * - `server` adapters proxy queries through a generated `/api/search` endpoint
+ *   that holds a secret key, so they require server output — Mixedbread.
+ * - `none` is the resolved form of `search: false`: search is disabled.
+ */
+export type SearchAdapterMode = "static" | "pagefind" | "hosted" | "server" | "none";
+/**
+ * Options for an adapter that takes none. The generated client never reads
+ * them — the static engines are configured from `i18n`, and Pagefind indexes
+ * the built HTML — so unknown keys fail config validation instead of passing
+ * silently. Adding a real option later is then additive, never a behavior
+ * change for a key that used to be ignored.
+ */
+export type KeylessSearchOptions = Record<string, never>;
+/**
+ * The descriptor a search adapter factory returns and `blume.config.ts`
+ * carries under `search`: the shared {@link AdapterDescriptor} contract plus
+ * the adapter's integration `mode`. It is plain data, never a live client —
+ * the runtime templates inline it as a literal into `.blume/` and ejected
+ * files, so every field must survive a JSON round-trip.
+ */
+export interface SearchAdapter<Kind extends string = string, Mode extends SearchAdapterMode = SearchAdapterMode, Options = object> extends AdapterDescriptor<Kind, Options> {
+    /** How the generated runtime queries this adapter. */
+    mode: Mode;
+}

package/dist/types/search/adapters/typesense.d.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import type { JsonValue } from "../../core/adapter.ts";
+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.
+ */
+export interface TypesenseNamedOptions {
+    /** The search-only API key (public — it ships to the browser). */
+    apiKey: string;
+    collection: string;
+    host: string;
+    /** Defaults to 443. */
+    port?: number;
+    /** Defaults to `https`. */
+    protocol?: "http" | "https";
+}
+/**
+ * Options for {@link typesense}: the named options plus any other client
+ * option, forwarded to the browser verbatim. JSON values only.
+ */
+export type TypesenseOptions = TypesenseNamedOptions & {
+    [option: string]: JsonValue;
+};
+export type TypesenseAdapter = SearchAdapter<"typesense", "hosted", TypesenseOptions>;
+export declare const typesenseOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    collection: z.ZodString;
+    host: z.ZodString;
+    port: z.ZodOptional<z.ZodNumber>;
+    protocol: z.ZodOptional<z.ZodEnum<{
+        http: "http";
+        https: "https";
+    }>>;
+}, z.core.$catchall<z.ZodJSONSchema>>;
+/**
+ * Hosted search on Typesense. Each `blume build` drops and recreates the
+ * collection so deleted or renamed pages don't linger as stale hits.
+ */
+export declare const typesense: (options: TypesenseOptions) => TypesenseAdapter;

package/dist/types/search/build.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Build a local Pagefind search index over the built site. Pagefind indexes
+ * every rendered page except those whose `<html>` carries
+ * `data-pagefind-ignore`, which Blume stamps on non-indexable pages
+ * (search-excluded, or hidden without the opt-in), so those stay out.
+ *
+ * Pagefind is imported statically, not with `import()`: this runs in the
+ * `astro:build:done` hook, after Astro has closed the module runner an
+ * installed Blume's config was evaluated in (see `core/node-require.ts`), and
+ * Pagefind ships only an `import` export, so `require` can't load it either.
+ *
+ * The index files are fetched with `getFiles()` and written here rather than
+ * with Pagefind's `writeFiles()`: in service mode Pagefind acknowledges
+ * `writeFiles()` once tokio has buffered the writes, not once they are on
+ * disk, and `close()` kills the backend, so a loaded CI host can ship a
+ * truncated `pagefind-entry.json` (Pagefind/pagefind#1271). Writing the bytes
+ * ourselves puts them on disk before the backend goes away. Fixed upstream in
+ * Pagefind/pagefind#1272; switch back to `writeFiles()` once a release ships
+ * that fix.
+ *
+ * Returns the number of pages indexed.
+ */
+export declare const buildSearchIndex: (outDir: string) => Promise<number>;

package/dist/types/search/documents.d.ts

@@ -0,0 +1,90 @@
+import type { VisibilityAudience } from "../ai/visibility.ts";
+import type { BlumeProject } from "../core/project-graph.ts";
+/** A document indexed by the client-side search providers (Orama, FlexSearch). */
+export interface SearchDocument {
+    route: string;
+    title: string;
+    description: string;
+    content: string;
+    /** Ancestor section labels for the result breadcrumb, e.g. `["Guides"]`. */
+    breadcrumb: string[];
+    /** Top-level section label, used by the search filter pills. */
+    section: string;
+    /** Locale code, so the dialog can filter results to the active language. */
+    locale: string;
+    /** Resolved page `type` (`doc`, `blog`, a custom `rfc`…), for type filters. */
+    contentType: string;
+    /** Docs version (`""` for the current docs), so results scope to the viewed version. */
+    version: string;
+    /** Frontmatter `search.tags`, surfaced for hosted-provider faceting. */
+    tags?: string[];
+    /**
+     * Declared facet values (`content.types.<type>.facets`), key → value.
+     * Filterable through the MCP tools' `filters` input.
+     */
+    facets?: Record<string, string>;
+}
+/**
+ * A record uploaded to a hosted search backend (Algolia, Orama Cloud,
+ * Typesense, Mixedbread). `_id` is the stable per-page key; each sync adapts it
+ * to the backend's own id field (`objectID`, `id`, …).
+ */
+export interface SearchRecord {
+    _id: string;
+    url: string;
+    title: string;
+    description: string;
+    content: string;
+    /** Locale code, carried as a facet for per-language filtering. */
+    locale: string;
+    /**
+     * Docs version, carried as a facet for per-version filtering. The current
+     * docs upload as `"current"` — hosted backends treat an empty facet value
+     * unreliably, so the sentinel stands in for the empty version id.
+     */
+    version: string;
+    /** Single faceting tag (the first frontmatter tag, when present). */
+    tag?: string;
+}
+interface BuildOptions {
+    includeWhenDisabled?: boolean;
+    content?: "markdown" | "plain";
+    audience?: VisibilityAudience;
+}
+/**
+ * Build search documents from the content graph. Only indexable pages are
+ * included (per the route manifest), and content comes from the source files,
+ * so the index is identical in dev and build.
+ *
+ * Pass `includeWhenDisabled` to index pages on their content merits even when
+ * the search provider is `none` — used by the MCP server, which is a separate
+ * feature from on-page search.
+ *
+ * `content` selects the extraction: `"plain"` (default) strips Markdown to bare
+ * searchable text; `"markdown"` keeps the body's Markdown — code blocks, lists,
+ * headings — for Ask AI grounding, where fenced examples are often the answer
+ * and stripping them makes the model unable to cite content the docs do contain.
+ * The `"markdown"` body is agent-facing, so components are downleveled with the
+ * 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.
+ *
+ * `audience` resolves `<Visibility>` blocks before extraction: `"web"`
+ * (default) keeps web-only content and drops agents-only blocks — the site
+ * search and hosted syncs must not surface content the page hides — while
+ * `"agents"` mirrors llms-full.txt/MCP `get_page` (web removed, agents kept).
+ *
+ * Whether fenced code joins the plain extraction is site-wide policy, read
+ * from `search.indexing.includeCodeBlocks` here rather than threaded by each
+ * caller, so the client index, hosted syncs, eject, and the MCP `search_docs`
+ * index can't drift apart.
+ */
+export declare const buildSearchDocuments: (project: BlumeProject, options?: BuildOptions) => Promise<SearchDocument[]>;
+/**
+ * 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`.
+ */
+export declare const toSearchRecords: (documents: SearchDocument[]) => SearchRecord[];
+export {};

package/dist/types/search/facets.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedConfig } from "../core/schema.ts";
+import type { PageRecord } from "../core/types.ts";
+export declare const pageFacets: (page: Pick<PageRecord, "contentType" | "custom">, config: ResolvedConfig) => Record<string, string> | undefined;

package/dist/types/search/sync/algolia.d.ts

@@ -0,0 +1,14 @@
+import type { AlgoliaOptions } from "../adapters/algolia.ts";
+import type { SearchRecord } from "../documents.ts";
+/** The adapter options the sync reads (the public `apiKey` is never used). */
+export type AlgoliaSyncConfig = Pick<AlgoliaOptions, "appId" | "indexName">;
+/**
+ * Upload the search records to Algolia. Uses the admin key from
+ * `ALGOLIA_ADMIN_API_KEY` (never the adapter options, which hold only the
+ * public, search-only key). Throws on a missing key so the caller can warn.
+ *
+ * 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.
+ */
+export declare const syncAlgolia: (records: SearchRecord[], config: AlgoliaSyncConfig) => Promise<void>;

package/dist/types/search/sync/index.d.ts

@@ -0,0 +1,14 @@
+import type { BlumeProject } from "../../core/project-graph.ts";
+/** Minimal logger surface the build command provides. */
+export interface SyncReporter {
+    start: (message: string) => void;
+    success: (message: string) => void;
+    warn: (message: string) => void;
+}
+/**
+ * After a build, upload the per-page records to the configured hosted adapter.
+ * Reads secret admin keys from the environment; if a key (or option) is
+ * missing the sync is skipped with a warning rather than failing the build —
+ * CI may sync in a separate step.
+ */
+export declare const syncSearchProvider: (project: BlumeProject, reporter: SyncReporter) => Promise<void>;

package/dist/types/search/sync/orama-cloud.d.ts

@@ -0,0 +1,10 @@
+import type { OramaCloudOptions } from "../adapters/orama-cloud.ts";
+import type { SearchRecord } from "../documents.ts";
+/** The adapter options the sync reads (the public credentials are never used). */
+export type OramaCloudSyncConfig = Pick<OramaCloudOptions, "indexId">;
+/**
+ * Push the search records to an Orama Cloud index via `CloudManager`, using the
+ * private key from `ORAMA_PRIVATE_API_KEY`. Snapshots the full record set, then
+ * deploys. Throws on a missing key/index so the caller can warn.
+ */
+export declare const syncOramaCloud: (records: SearchRecord[], config: OramaCloudSyncConfig) => Promise<void>;

package/dist/types/search/sync/typesense.d.ts

@@ -0,0 +1,14 @@
+import type { TypesenseOptions } from "../adapters/typesense.ts";
+import type { SearchRecord } from "../documents.ts";
+/** The adapter options the sync reads (the public `apiKey` is never used). */
+export type TypesenseSyncConfig = Pick<TypesenseOptions, "collection" | "host" | "port" | "protocol">;
+/**
+ * Import the search records into a Typesense collection. Uses the admin key
+ * from `TYPESENSE_ADMIN_API_KEY`. Throws on a missing key so the caller can
+ * warn.
+ *
+ * The collection is dropped and recreated on each sync so that pages deleted or
+ * renamed since the last sync don't linger as stale search hits that 404 when
+ * clicked (an upsert alone never removes them).
+ */
+export declare const syncTypesense: (records: SearchRecord[], config: TypesenseSyncConfig) => Promise<void>;