blume 1.7.2 → 2.0.0

package/src/reference/scalar.ts

@@ -0,0 +1,136 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+import { hasSources, missingSourcesIssue } from "./options.ts";
+
+/**
+ * What the generated Scalar page imports. Declared on every `scalar()`
+ * descriptor so the generated project lists it, which is what lets Astro's
+ * framework-package crawl bundle the embed.
+ */
+export const SCALAR_RUNTIME_DEPS: readonly string[] = ["@scalar/astro"];
+
+/**
+ * A single document rendered by a `scalar()` reference. Scalar reads OpenAPI
+ * and AsyncAPI documents and detects which it was given, so there is one
+ * source shape for both. The embed sits outside Blume's search and llms.txt,
+ * so of the native per-source controls only `noindex` applies here.
+ */
+export const scalarSourceSchema = z.strictObject({
+  /** Nav/section label for this source. */
+  label: z.string().optional(),
+  /** Emit noindex metadata and omit the page from the sitemap. */
+  noindex: z.boolean().default(false),
+  /** 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. */
+  spec: z.string(),
+});
+
+/** One document source, as `scalar()` accepts it. */
+export interface ScalarSourceOptions {
+  /** Nav/section label for this source. */
+  label?: string;
+  /** Emit noindex metadata and omit the page from the sitemap. Defaults to `false`. */
+  noindex?: boolean;
+  /** 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. */
+  spec: string;
+}
+
+/** A source with every default applied. */
+export type ResolvedScalarSource = z.output<typeof scalarSourceSchema>;
+
+/**
+ * `scalar()` options with every default applied and `spec` folded into
+ * `sources`; every key beyond the named ones is forwarded Scalar config.
+ */
+export type ResolvedScalarOptions = {
+  route: string;
+  sources: ResolvedScalarSource[];
+  theme?: string;
+} & { [option: string]: JsonValue };
+
+/** The options {@link scalar} maps itself. */
+export interface ScalarNamedOptions {
+  /** Where the reference mounts. Defaults to `/reference`. */
+  route?: string;
+  /** One or more documents; each renders on its own route by default. */
+  sources?: ScalarSourceOptions[];
+  /** Shorthand for a single source: `sources: [{ spec }]`. */
+  spec?: string;
+  /** A Scalar theme name (`purple`, `moon`, …). Unset keeps Scalar's default theme with Blume's accent and radius layered on top. */
+  theme?: string;
+}
+
+/**
+ * Options for {@link scalar}: the source, route, and `theme` Blume maps, plus
+ * any other [Scalar configuration](https://github.com/scalar/scalar/blob/main/documentation/configuration.md)
+ * key, forwarded verbatim to the embedded `<ScalarComponent>` (`localization`,
+ * `agent`, `hideTestRequestButton`, `orderSchemaPropertiesBy`, …). Blume
+ * doesn't mirror Scalar's config surface, so this is a full escape hatch: a
+ * forwarded key wins over Blume's own derived spec/theme config. JSON values
+ * only — the configuration is inlined into the generated page. `sources` is
+ * Blume's (one page per document); Scalar's own multi-document `sources`
+ * can't be forwarded.
+ */
+export type ScalarOptions = ScalarNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+/**
+ * `spec` is the single-source shorthand and folds into `sources` at parse
+ * (through the source schema, so the two can never drift); every key beyond
+ * the named ones is Scalar configuration and passes through untouched.
+ */
+export const scalarOptionsSchema = z
+  .object({
+    /** Where the reference mounts. */
+    route: z.string().default("/reference"),
+    /** One or more documents; each renders on its own route by default. */
+    sources: z.array(scalarSourceSchema).default([]),
+    /** Shorthand for a single source: `sources: [{ spec }]`. */
+    spec: z.string().optional(),
+    /** A Scalar theme name; unset layers Blume's accent and radius on Scalar's default theme. */
+    theme: z.string().optional(),
+  })
+  .catchall(z.json())
+  .transform(({ spec, sources, ...options }): ResolvedScalarOptions => ({
+    ...options,
+    sources:
+      spec === undefined
+        ? sources
+        : [scalarSourceSchema.parse({ spec }), ...sources],
+  }))
+  .refine(hasSources, missingSourcesIssue("scalar"));
+
+export type ScalarAdapter = AdapterDescriptor<"scalar", ScalarOptions>;
+
+/** A `scalar()` descriptor as the config schema resolves it. */
+export type ResolvedScalarAdapter = AdapterDescriptor<
+  "scalar",
+  ResolvedScalarOptions
+>;
+
+export const scalarAdapterSchema = adapterDescriptorSchema(
+  "scalar",
+  scalarOptionsSchema
+);
+
+/**
+ * An API reference rendered by [Scalar](https://scalar.com)'s self-contained
+ * UI — its own sidebar, search, theme, and request client on a single route —
+ * instead of Blume's native operation pages. Takes an OpenAPI or AsyncAPI
+ * document (Scalar detects which); a GraphQL schema has no Scalar embed.
+ * Blume's per-page controls don't apply: the embed doesn't weave into the
+ * sidebar, search, or llms.txt, and it brings its own request client in place
+ * of the Try it playground.
+ */
+export const scalar = (options: ScalarOptions): ScalarAdapter => ({
+  kind: "scalar",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: [...SCALAR_RUNTIME_DEPS],
+});

package/src/reference/schema.ts

@@ -0,0 +1,88 @@
+import { z } from "zod";
+
+import { unrecognizedKeysMessage } from "../core/unrecognized-keys.ts";
+import { asyncapiAdapterSchema } from "./asyncapi.ts";
+import type { AsyncApiAdapter, ResolvedAsyncApiAdapter } from "./asyncapi.ts";
+import { graphqlAdapterSchema } from "./graphql.ts";
+import type { GraphqlAdapter, ResolvedGraphqlAdapter } from "./graphql.ts";
+import { openapiAdapterSchema } from "./openapi.ts";
+import type { OpenApiAdapter, ResolvedOpenApiAdapter } from "./openapi.ts";
+import { SCALAR_RUNTIME_DEPS, scalarAdapterSchema } from "./scalar.ts";
+import type { ResolvedScalarAdapter, ScalarAdapter } from "./scalar.ts";
+
+/** Every descriptor a `blume/reference` factory can return. */
+export type ReferenceAdapter =
+  | AsyncApiAdapter
+  | GraphqlAdapter
+  | OpenApiAdapter
+  | ScalarAdapter;
+
+/** What `config.reference` holds: each descriptor with its options resolved. */
+export type ResolvedReferenceAdapter =
+  | ResolvedAsyncApiAdapter
+  | ResolvedGraphqlAdapter
+  | ResolvedOpenApiAdapter
+  | ResolvedScalarAdapter;
+
+/**
+ * One configured reference adapter, as its factory returned it. Only `kind`
+ * and `options` carry information — the metadata lists are validated for
+ * shape, then re-derived from the resolved options so a descriptor that went
+ * through JSON resolves to the same canonical metadata the factory ships.
+ */
+export const referenceAdapterSchema = z
+  .discriminatedUnion("kind", [
+    asyncapiAdapterSchema,
+    graphqlAdapterSchema,
+    openapiAdapterSchema,
+    scalarAdapterSchema,
+  ])
+  .transform((value): ResolvedReferenceAdapter => ({
+    ...value,
+    requiredSecrets: [],
+    // Blume's own renderer parses at generate time and needs nothing; the
+    // Scalar embed is imported by its generated page.
+    runtimeDeps: value.kind === "scalar" ? [...SCALAR_RUNTIME_DEPS] : [],
+  }));
+
+const LIST_HINT =
+  'reference is a list of adapters — e.g. `reference: [openapi({ spec }), asyncapi({ spec }), graphql({ spec, endpoint }), scalar({ spec })]`, imported from "blume/reference".';
+
+/**
+ * `blume.config.reference`: the API references to render, in order. Unset
+ * means none. A non-array fails with the list hint; element errors keep their
+ * own messages.
+ */
+export const referenceConfigSchema = z
+  .array(referenceAdapterSchema, {
+    error: (issue) => (issue.code === "invalid_type" ? LIST_HINT : undefined),
+  })
+  .default([]);
+
+/** The top-level keys the `reference` list replaced. */
+const REMOVED_KEYS: readonly string[] = ["asyncapi", "graphql", "openapi"];
+
+/**
+ * The hint for a config still carrying the 1.x `openapi`/`asyncapi`/`graphql`
+ * blocks, or `undefined` when none of the unrecognized keys is one of them
+ * (so the default "unrecognized key" message applies). Wired into the root
+ * config object's error hook: the keys are gone from the schema, so without
+ * this a migrating site would see only "Unrecognized key". Any other unknown
+ * key keeps Zod's wording beside the hint, and the rest of the config is
+ * still validated in the same run.
+ */
+export const removedReferenceKeysHint = (
+  keys: string[]
+): string | undefined => {
+  const removed = REMOVED_KEYS.filter((key) => keys.includes(key));
+  if (removed.length === 0) {
+    return undefined;
+  }
+  const list = removed.map((key) => `\`${key}\``).join(", ");
+  const factories = removed.map((key) => `${key}({ … })`).join(", ");
+  const hint = `The top-level ${list} config was replaced by \`reference\`, a list of adapters imported from "blume/reference": \`reference: [${factories}]\`. Each block's options move onto its factory unchanged (\`enabled\` is gone — an adapter in the list is enabled), and a block with \`renderer: "scalar"\` becomes its own \`scalar({ spec, theme, …scalar })\` adapter in the list.`;
+  const others = keys.filter((key) => !REMOVED_KEYS.includes(key));
+  return others.length > 0
+    ? `${hint} ${unrecognizedKeysMessage(others)}`
+    : hint;
+};

package/src/registry/eject.ts

@@ -16,6 +16,7 @@ import {
   exampleScanRoots,
 } from "../astro/examples.ts";
 import {
+  analyzeComponentsFile,
   buildRuntimeData,
   clientFeaturesFor,
   collectStaged,
@@ -37,8 +38,6 @@ import {
   examplesPageTemplate,
   exampleWrapperTemplate,
   featuresTemplate,
-  islandMapTemplate,
-  islandWrapperTemplate,
   mcpEndpointTemplate,
   mcpPageFile,
   mixedbreadSearchEndpointTemplate,
@@ -46,6 +45,7 @@ import {
   ogEndpointTemplate,
   rawMarkdownEndpointTemplate,
   rssEndpointTemplate,
+  runtimeDependencies,
   runtimeTsconfigTemplate,
   searchClientTemplate,
   searchEndpointTemplate,
@@ -55,6 +55,10 @@ import { buildIncludeGraph } from "../core/includes.ts";
 import { packageRoot } from "../core/package-root.ts";
 import { scanProject } from "../core/project-graph.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
+import {
+  resolveDocsCollection,
+  sourcesOfKind,
+} from "../core/sources/collection.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { buildRssFeeds, renderRssFeed } from "../deploy/rss.ts";
 import type { OpenApiData } from "../openapi/model.ts";
@@ -62,7 +66,6 @@ import { hasScalarReferences } from "../openapi/references.ts";
 import { buildReferenceFiles } from "../openapi/scalar.ts";
 import { isOpenApiSource } from "../openapi/source.ts";
 import { buildSearchDocuments } from "../search/documents.ts";
-import { servesStaticIndex } from "../search/providers.ts";
 import {
   examplesEntryTemplate,
   tailwindEntryTemplate,
@@ -133,19 +136,18 @@ const askFiles = async (
     await rm(join(genDir, "ask-data.json"), { force: true });
     return [];
   }
-  const grounded = ask.provider !== "inkeep";
+  const backend = resolveAskBackend(ask.provider);
   const files = [
     {
-      content: askEndpointTemplate(resolveAskBackend(ask), grounded, {
+      content: askEndpointTemplate(backend, {
         cors: ask.cors,
         instructions: ask.instructions,
-        reasoning: ask.reasoning,
         retrieval: ask.retrieval,
       }),
       path: join(srcDir, "pages", "api", "ask.ts"),
     },
   ];
-  if (grounded) {
+  if (backend.grounded) {
     files.push({
       content: `${JSON.stringify(await buildAskData(project))}\n`,
       path: join(genDir, "ask-data.json"),
@@ -159,8 +161,12 @@ const hostsMcp = (
   project: BlumeProject,
   userPages: { pattern: string }[]
 ): boolean =>
-  project.config.ai.mcp.enabled &&
-  !routeIsTaken(userPages, project.graph.pages, project.config.ai.mcp.route);
+  project.config.agents.mcp.enabled &&
+  !routeIsTaken(
+    userPages,
+    project.graph.pages,
+    project.config.agents.mcp.route
+  );
 
 /**
  * The `.well-known` MCP discovery routes, injected as prerendered pages
@@ -198,7 +204,7 @@ const mcpFiles = async (
   if (!hostsMcp(project, userPages)) {
     return [];
   }
-  const { route } = project.config.ai.mcp;
+  const { route } = project.config.agents.mcp;
   const data = await buildMcpData(project);
   const discoveryInput = {
     base: data.base,
@@ -243,9 +249,8 @@ const changelogFiles = (
       page.contentType === "changelog" &&
       !(page.meta.draft || page.meta.sidebar.hidden)
   );
-  const hasChangelogSource = (project.config.content.sources ?? []).some(
-    (source) => source.type === "github-releases"
-  );
+  const hasChangelogSource =
+    sourcesOfKind(project.config, "github-releases").length > 0;
   if (
     !(hasChangelog || hasChangelogSource) ||
     routeIsTaken(userPages, project.graph.pages, "/changelog")
@@ -302,6 +307,36 @@ const examplesPreviewFiles = (
       ]
     : [];
 
+/**
+ * The packages the ejected app imports by bare name: Astro, Tailwind's Vite
+ * plugin, `blume` itself, the integrations the config wires in, whatever the
+ * configured adapters declare, and React when islands, examples, or Ask AI
+ * render with it (Blume ships React, so projects rarely list it). They have
+ * to be the project's own dependencies after eject — under a strict linker
+ * such as pnpm nothing else makes them resolvable, and `astro build` fails.
+ * The hidden runtime reaches the same packages through its `node_modules`
+ * junction into Blume's own, so only eject declares the ones its generated
+ * files import directly: the AI SDK the Ask AI route streams through (unless
+ * `ai.ask.endpoint` points elsewhere, when no route is written) and the EPUB
+ * generator's browser bundle `features.ts` loads.
+ */
+const ejectDependencies = (
+  options: Parameters<typeof runtimeDependencies>[0]
+): string[] => {
+  const { ask } = options.config.ai;
+  return [
+    ...new Set([
+      "astro",
+      "@tailwindcss/vite",
+      "blume",
+      ...runtimeDependencies(options),
+      ...(options.needsReact ? ["react", "react-dom"] : []),
+      ...(ask?.enabled && !ask.endpoint ? ["ai"] : []),
+      ...(options.config.export.epub ? ["epub-gen-memory"] : []),
+    ]),
+  ];
+};
+
 const ejectIntegrationBridge = (
   config: BlumeProject["config"],
   root: string,
@@ -318,11 +353,12 @@ const ejectIntegrationBridge = (
  *
  * Returns the written files plus non-fatal warnings, mirroring the generated
  * runtime (e.g. a Scalar reference spec that wasn't found, or a reference
- * route colliding with a content page).
+ * route colliding with a content page), and the packages the ejected app
+ * imports by bare name, for the caller to add to package.json.
  */
 export const eject = async (
   root: string
-): Promise<{ files: string[]; warnings: string[] }> => {
+): Promise<{ dependencies: string[]; files: string[]; warnings: string[] }> => {
   const project = await scanProject(root, { mode: "build" });
   const { context, config } = project;
 
@@ -345,6 +381,7 @@ export const eject = async (
     userExamplesCss,
     rawMarkdown,
     islands,
+    overrideAnalysis,
   ] = await Promise.all([
     context.pagesRoot ? discoverPages(context.pagesRoot) : Promise.resolve([]),
     detectNeedsReact(root),
@@ -356,12 +393,20 @@ export const eject = async (
     ),
     buildRawMarkdown(project),
     discoverIslands(root),
+    analyzeComponentsFile(context.componentsFile),
   ]);
-  // Island/example frameworks drive which Astro renderers the ejected config
-  // wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.
+  // The `islands/` convention and `components.ts` share the same static plan
+  // the CLI uses, with every import written relative to its generated file so
+  // the ejected app builds from any checkout (like the example wrappers below).
+  const slotPlan = planComponentSlots(islands.islands, overrideAnalysis, {
+    relativeTo: genDir,
+  });
+  // Island/example/override frameworks drive which Astro renderers the ejected
+  // config wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.
   const frameworks = new Set<string>([
     ...islands.islands.map((island) => island.framework),
     ...examples.examples.map((example) => example.framework),
+    ...slotPlan.frameworks,
   ]);
   const needsReact = needsReactRaw || askEnabled || frameworks.has("react");
   const needsVue = frameworks.has("vue");
@@ -371,13 +416,22 @@ export const eject = async (
   const relContext: ProjectContext = {
     ...context,
     contentRoot: toPosix(relative(root, context.contentRoot)),
+    distDir: "./dist",
     outDir: ".",
+    pagesRoot: context.pagesRoot
+      ? `./${toPosix(relative(root, context.pagesRoot))}`
+      : null,
     root: ".",
   };
+  // The `docs` collection resolves its base against the real project root and
+  // is then relativized like everything else, so the ejected content config
+  // never bakes in the absolute path `eject` happened to run from.
+  const docsCollection = resolveDocsCollection(config, root);
+  const relCollection = {
+    ...docsCollection,
+    base: toPosix(relative(root, docsCollection.base)),
+  };
 
-  const componentsImport = context.componentsFile
-    ? `../../${toPosix(relative(root, context.componentsFile))}`
-    : null;
   const relPages = [
     ...pages.map((page) => ({
       entrypoint: toPosix(relative(root, page.entrypoint)),
@@ -437,6 +491,7 @@ export const eject = async (
     },
     {
       content: contentConfigTemplate({
+        collection: relCollection,
         config,
         context: relContext,
         staged: hasStaged,
@@ -454,18 +509,11 @@ export const eject = async (
       path: join(srcDir, "pages", "[...slug].astro"),
     },
     {
-      // Eject keeps the portable re-export form (relative import to the user's
-      // components file); hydration/island wrappers would need machine-specific
-      // absolute paths, so the ejected app owns and wires those itself.
-      content: planComponentSlots(componentsImport, null).module,
+      content: slotPlan.module,
       path: join(genDir, "components.ts"),
     },
-    // Island/example maps the catch-all imports; written even when empty so the
-    // relative import and the `blume:examples` alias always resolve.
-    {
-      content: islandMapTemplate(islands.islands),
-      path: join(genDir, "islands.ts"),
-    },
+    // The example map the catch-all imports; written even when empty so the
+    // `blume:examples` alias always resolves.
     {
       content: exampleMapTemplate(examples.examples, config.basePath),
       path: join(genDir, "examples.ts"),
@@ -553,7 +601,6 @@ export const eject = async (
     ...changelogFiles(project, pages, srcDir, {
       exportEpub,
       exportPdf,
-      mathEnabled: usesMath,
       needsReact,
       staged: hasStaged,
     })
@@ -582,7 +629,8 @@ export const eject = async (
     }
   );
 
-  if (servesStaticIndex(config.search.provider)) {
+  const searchAdapter = config.search.provider;
+  if (searchAdapter.mode === "static") {
     const documents = await buildSearchDocuments(project);
     files.push(
       {
@@ -596,11 +644,9 @@ export const eject = async (
     );
   }
 
-  if (config.search.provider === "mixedbread") {
+  if (searchAdapter.kind === "mixedbread") {
     files.push({
-      content: mixedbreadSearchEndpointTemplate(
-        config.search.mixedbread?.storeId ?? ""
-      ),
+      content: mixedbreadSearchEndpointTemplate(searchAdapter.options),
       path: join(srcDir, "pages", "api", "search.ts"),
     });
   }
@@ -642,14 +688,14 @@ export const eject = async (
     }
   }
 
-  // Per-island and per-example live wrappers referenced by the maps above.
+  // Per-override and per-example live wrappers referenced by the maps above.
   files.push(
-    ...islands.islands.map((island) => ({
-      content: islandWrapperTemplate(island),
-      path: join(genDir, "islands", `${island.name}.astro`),
+    ...slotPlan.wrappers.map((wrapper) => ({
+      content: wrapper.content,
+      path: join(genDir, "component-slots", `${wrapper.name}.astro`),
     })),
     ...examples.examples.map((example) => ({
-      content: exampleWrapperTemplate(example),
+      content: exampleWrapperTemplate(example, join(genDir, "examples")),
       path: join(genDir, "examples", `${exampleSlug(example.path)}.astro`),
     })),
     ...examplesPreviewFiles(
@@ -688,5 +734,14 @@ export const eject = async (
   // The hidden runtime is no longer the source of truth.
   await rm(context.outDir, { force: true, recursive: true });
 
-  return { files: written.map((file) => file.path), warnings };
+  return {
+    dependencies: ejectDependencies({
+      config,
+      needsReact,
+      needsSvelte,
+      needsVue,
+    }),
+    files: written.map((file) => file.path),
+    warnings,
+  };
 };

package/src/search/adapters/algolia.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+
+import type { JsonValue } from "../../core/adapter.ts";
+import type { SearchAdapter } from "./types.ts";
+
+/**
+ * Public Algolia credentials. The browser queries the index with the
+ * search-only `apiKey`; the build-time sync replaces the index with the admin
+ * key from `ALGOLIA_ADMIN_API_KEY`, which never enters the config.
+ */
+export interface AlgoliaNamedOptions {
+  appId: string;
+  /** The search-only API key (public — it ships to the browser). */
+  apiKey: string;
+  indexName: string;
+}
+
+/**
+ * Options for {@link algolia}: the named options plus any other client
+ * option, forwarded to the browser verbatim. JSON values only.
+ */
+export type AlgoliaOptions = AlgoliaNamedOptions & {
+  [option: string]: JsonValue;
+};
+
+export type AlgoliaAdapter = SearchAdapter<"algolia", "hosted", AlgoliaOptions>;
+
+export const algoliaOptionsSchema = z
+  .object({
+    apiKey: z.string(),
+    appId: z.string(),
+    indexName: z.string(),
+  })
+  .catchall(z.json());
+
+/**
+ * Hosted search on Algolia. Each `blume build` replaces the whole index with
+ * the current records, so deleted or renamed pages don't linger as stale hits.
+ */
+export const algolia = (options: AlgoliaOptions): AlgoliaAdapter => ({
+  kind: "algolia",
+  mode: "hosted",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: ["algoliasearch"],
+});

package/src/search/adapters/flexsearch.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+import type { KeylessSearchOptions, SearchAdapter } from "./types.ts";
+
+/** FlexSearch takes no options; unknown keys fail config validation. */
+export type FlexsearchOptions = KeylessSearchOptions;
+
+export type FlexsearchAdapter = SearchAdapter<
+  "flexsearch",
+  "static",
+  FlexsearchOptions
+>;
+
+export const flexsearchOptionsSchema = z.strictObject({});
+
+/**
+ * A second keyless, client-side engine. It loads the same `/blume-search.json`
+ * index Orama ships and builds a FlexSearch document index in the browser.
+ * No locale-aware tokenizer, so prefer Orama for non-Latin scripts.
+ */
+export const flexsearch = (
+  options: FlexsearchOptions = {}
+): FlexsearchAdapter => ({
+  kind: "flexsearch",
+  mode: "static",
+  options,
+  requiredSecrets: [],
+  runtimeDeps: ["flexsearch"],
+});

package/src/search/adapters/index.ts

@@ -0,0 +1,39 @@
+/**
+ * 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/src/search/adapters/mixedbread.ts

@@ -0,0 +1,39 @@
+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 const mixedbreadOptionsSchema = z
+  .object({
+    storeId: z.string(),
+  })
+  .catchall(z.json());
+
+/**
+ * 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 const mixedbread = (options: MixedbreadOptions): MixedbreadAdapter => ({
+  kind: "mixedbread",
+  mode: "server",
+  options,
+  requiredSecrets: ["MIXEDBREAD_API_KEY"],
+  runtimeDeps: ["@mixedbread/sdk"],
+});