blume 1.7.3 → 2.0.1

package/src/core/config.ts

@@ -4,7 +4,11 @@ import { z } from "zod";
 
 import type { BlumeConfig } from "./config-input.ts";
 import { applyDeploymentEnv } from "./deployment-env.ts";
-import { BlumeError, diagnosticsFromZod } from "./diagnostics.ts";
+import {
+  BlumeError,
+  diagnosticsFromIssues,
+  diagnosticsFromZod,
+} from "./diagnostics.ts";
 import { createModuleLoader } from "./load-module.ts";
 import { findConfigFile } from "./project.ts";
 import { blumeConfigSchema } from "./schema.ts";
@@ -45,10 +49,12 @@ import type { Diagnostic } from "./types.ts";
  *   dismissible }`.
  *
  * **Content & navigation**
- * - `content` — where content lives (`root`, defaults to `docs`) and pluggable
- *   `sources` (filesystem, remote MDX, GitHub Releases, Sanity, Notion, or a
- *   custom `ContentSource`). Omit `sources` and the top-level `root` becomes one
- *   implicit filesystem source.
+ * - `content` — where content lives: adapters from `blume/sources` under
+ *   `sources` (`filesystem({ root })`, `mdxRemote({…})`, `githubReleases({…})`,
+ *   `sanity({…})`, `notion({…})`, `contentful({…})`, `payload({…})`,
+ *   `strapi({…})`, `obsidian({…})`, or `custom(source)`), or the
+ *   zero-config shorthand `root`/`include`/`exclude`, which desugars to one
+ *   `filesystem()` source and can't be combined with `sources`.
  * - `navigation` — sidebar, header `tabs`, `selectors` (version/language/product
  *   switchers), pinned `featured` links, header `actions` and the one `cta`,
  *   and the `repo` link (a toggle, or a URL). Omit `sidebar` to generate it
@@ -70,35 +76,41 @@ import type { Diagnostic } from "./types.ts";
  * - `export` — reader-facing PDF/EPUB export actions (off by default).
  *
  * **Reference docs**
- * - `openapi` — native OpenAPI reference: one real page per operation, woven
- *   into the sidebar and search. Point `sources`/`spec` at your spec.
- * - `asyncapi` — native AsyncAPI reference with the same treatment; 2.x specs
- *   are normalized to 3.x automatically.
+ * - `reference` — API references as a list of adapters from
+ *   `blume/reference`: `openapi({…})` and `asyncapi({…})` render native pages
+ *   (one real page per operation, woven into the sidebar and search; AsyncAPI
+ *   2.x specs are normalized to 3.x), `graphql({…})` renders a schema, and
+ *   `scalar({…})` embeds the Scalar reference instead.
  *
- * **Search & AI**
- * - `search` — search backend `provider` (`orama` by default; `pagefind`,
- *   `algolia`, `typesense`, `orama-cloud`, `mixedbread`, or `none`) plus its
- *   credential block.
- * - `ai` — `ask` (the Ask AI chat endpoint and its provider/model), `llmsTxt`
- *   (emit `llms.txt`), `mcp` (expose the docs as an MCP server for connecting
- *   agents), and `markdownComponents` (Markdown serializers for custom
- *   components in agent-facing output).
+ * **Search, AI & agents**
+ * - `search` — a search adapter from `blume/search` (`orama()` by default;
+ *   `flexsearch()`, `pagefind()`, `algolia({…})`, `oramaCloud({…})`,
+ *   `typesense({…})`, `mixedbread({…})`, or `false`), or `{ provider,
+ *   popular, indexing }` to add curated links and indexing settings.
+ * - `ai` — what faces a model at read time: `assistant` (the chat assistant, with
+ *   a provider adapter from `blume/ai` such as `gateway()` or `openrouter()`)
+ *   and `openInChat` (the "Open in chat" page action).
+ * - `agents` — the machine-readable surface: `llmsTxt`, the JSON `api`, the
+ *   `mcp` server, published `skills`, `markdownComponents` (Markdown
+ *   serializers for custom components), the `catalog` manifests,
+ *   `agentReadability`, robots `contentSignals`, `webmcp`, and `webBotAuth`.
  *
  * **SEO, feeds & analytics**
- * - `seo` — `og` images, `sitemap`, `robots`, `rss` feeds, `structuredData`
- *   JSON-LD, `agentReadability`, and robots `contentSignals`.
- * - `analytics` — PostHog, Vercel, or arbitrary `scripts` (Plausible, Fathom,
- *   GA, …).
+ * - `seo` — `og` images, `sitemap`, `robots`, `rss` feeds, and
+ *   `structuredData` JSON-LD.
+ * - `analytics` — a list of adapters from `blume/analytics`, one per provider
+ *   (`posthog()`, `googleAnalytics()`, `plausible()`, `fathom()`, `vercel()`,
+ *   `cloudflare()`, …), or `script()` for anything without one.
  *
  * **Astro**
  * - `integrations` — Astro integrations appended after Blume's built-ins, in
  *   declaration order. Install and maintain each integration in the site.
  *
  * **Deployment & i18n**
- * - `deployment` — `site` URL (needed for absolute links, sitemaps, and OG),
- *   `adapter` (`vercel`/`node`/`netlify`/`cloudflare`), `output`
- *   (`static`/`server`), and `base` path. Auto-detected on Vercel/Netlify/
- *   Cloudflare from the platform env.
+ * - `deployment` — a host adapter from `blume/deploy` (`vercel()`, `node()`,
+ *   `netlify()`, `cloudflare()`) for a server build, each taking `site`,
+ *   `base`, and `output`; or `{ site, base }` for a static build anywhere.
+ *   `site` is auto-detected on Vercel/Netlify/Cloudflare from the platform env.
  * - `i18n` — opt-in multi-locale: `locales`, `defaultLocale`, `parser`
  *   (`dir` vs filename `dot` suffix), and per-locale UI overrides.
  *
@@ -113,33 +125,41 @@ import type { Diagnostic } from "./types.ts";
  *
  * @example A production docs site with theming, search, and deployment.
  * ```ts
+ * import { vercel } from "blume/deploy";
+ * import { orama } from "blume/search";
+ *
  * export default defineConfig({
  *   title: "Acme Docs",
  *   description: "Build faster with Acme.",
  *   logo: { image: "/logo.svg", text: "Acme" },
  *   github: { owner: "acme", repo: "acme" },
- *   theme: { accent: "violet", fonts: { body: "inter" }, radius: "lg" },
+ *   theme: { accent: "purple", fonts: { body: "inter" }, radius: "lg" },
  *   navigation: {
  *     tabs: [
  *       { label: "Guides", path: "/guides" },
  *       { label: "API", path: "/api" },
  *     ],
  *   },
- *   search: { provider: "orama" },
- *   deployment: { site: "https://docs.acme.com", adapter: "vercel" },
+ *   search: orama(),
+ *   // A server build on Vercel.
+ *   deployment: vercel({ site: "https://docs.acme.com" }),
  * });
  * ```
  *
- * @example An OpenAPI reference with the Ask AI assistant enabled.
+ * @example An OpenAPI reference with the assistant enabled.
  * ```ts
+ * import { openapi } from "blume/reference";
+ *
  * export default defineConfig({
  *   title: "Acme API",
- *   openapi: {
- *     enabled: true,
- *     route: "/reference",
- *     sources: [{ label: "Core", spec: "./openapi.json" }],
- *   },
- *   ai: { ask: { enabled: true }, llmsTxt: true },
+ *   reference: [
+ *     openapi({
+ *       route: "/reference",
+ *       sources: [{ label: "Core", spec: "./openapi.json" }],
+ *     }),
+ *   ],
+ *   agents: { llmsTxt: true },
+ *   ai: { assistant: { enabled: true } },
  * });
  * ```
  *
@@ -149,6 +169,21 @@ import type { Diagnostic } from "./types.ts";
  */
 export const defineConfig = (config: BlumeConfig): BlumeConfig => config;
 
+/**
+ * A config that fails validation. `diagnostic` folds every issue into the one
+ * message a command prints; `issues` keeps each on its own, with its own
+ * line, for `blume upgrade`, which lists them one by one.
+ */
+export class ConfigValidationError extends BlumeError {
+  readonly issues: Diagnostic[];
+
+  constructor(diagnostic: Diagnostic, issues: Diagnostic[]) {
+    super(diagnostic);
+    this.name = "ConfigValidationError";
+    this.issues = issues;
+  }
+}
+
 /** Result of loading + validating a project config. */
 export interface ConfigLoadResult {
   config: ResolvedConfig;
@@ -169,12 +204,62 @@ const importConfigModule = createModuleLoader();
 /**
  * The slice of a user config module probed before schema defaults apply:
  * whether `theme.fonts` was actually set. `looseObject` keeps every other key
- * out of scope; a non-object at either level simply fails the probe.
+ * out of scope; a non-object at either level simply fails the probe. `fonts`
+ * is optional here — Zod 4 treats a bare `z.unknown()` key as required, which
+ * would fail the probe for every `theme` that doesn't set fonts.
  */
 const themeFontsProbeSchema = z.looseObject({
-  theme: z.looseObject({ fonts: z.unknown() }).optional(),
+  theme: z.looseObject({ fonts: z.unknown().optional() }).optional(),
 });
 
+const isPathSegment = (segment: PropertyKey): segment is string | number =>
+  typeof segment !== "symbol";
+
+/**
+ * Where an issue is located in the config source: its own path, except that
+ * an unknown key — which Zod reports on its parent's path — is located at the
+ * key itself, so a removed field points at the line that sets it.
+ */
+const locationPath = (issue: z.core.$ZodIssue): (string | number)[] => [
+  ...issue.path.filter(isPathSegment),
+  ...(issue.code === "unrecognized_keys" ? issue.keys.slice(0, 1) : []),
+];
+
+/** Sort key for a config issue: the line that set the field, else last. */
+const lineRank = (diagnostic: Diagnostic): number =>
+  diagnostic.line ?? Number.MAX_SAFE_INTEGER;
+
+/**
+ * One diagnostic per config issue, each anchored to the config file and, when
+ * the source is on disk, to the line and column that set the field. Issues on
+ * the config's own top level (a removed top-level block) lead, since they name
+ * the biggest moves; the rest read top to bottom, in source order.
+ */
+const configIssues = (
+  error: z.ZodError,
+  options: { file?: string; source?: string }
+): Diagnostic[] => {
+  const code = "BLUME_CONFIG_INVALID";
+  const located = diagnosticsFromIssues(
+    error.issues.map((issue) => ({
+      message: issue.message,
+      path: locationPath(issue),
+    })),
+    { code, source: options.source }
+  );
+  return diagnosticsFromZod(error, { code, ...options })
+    .map((diagnostic, index) => ({
+      ...diagnostic,
+      column: located[index]?.column,
+      line: located[index]?.line,
+    }))
+    .toSorted(
+      (a, b) =>
+        Number(Boolean(a.schemaPath)) - Number(Boolean(b.schemaPath)) ||
+        lineRank(a) - lineRank(b)
+    );
+};
+
 /**
  * Load and validate the project config. When no config file exists, schema
  * defaults produce a fully resolved config so the zero-boilerplate path works.
@@ -219,8 +304,7 @@ export const loadConfig = async (
       configFile && existsSync(configFile)
         ? readFileSync(configFile, "utf-8")
         : undefined;
-    const diagnostics = diagnosticsFromZod(parsed.error, {
-      code: "BLUME_CONFIG_INVALID",
+    const diagnostics = configIssues(parsed.error, {
       file: configFile ?? undefined,
       source,
     });
@@ -241,14 +325,14 @@ export const loadConfig = async (
             message: `${primary.message}\n${rest.length} more config issue(s):\n${moreIssues}`,
           }
         : primary;
-    throw new BlumeError(detail);
+    throw new ConfigValidationError(detail, diagnostics);
   }
 
   // Resolve the canonical site URL, then SEO defaults that depend on it.
   // Precedence: explicit config > platform env (Vercel/Netlify/Cloudflare, via
   // applyDeploymentEnv) > the local dev server URL (dev only).
   const config = applyDeploymentEnv(parsed.data);
-  const site = config.deployment.site ?? options.devServerUrl;
+  const site = config.deployment.options.site ?? options.devServerUrl;
 
   // OG images need an absolute `og:image`, so they default on once a site URL
   // is known and off otherwise. An explicit `seo.og.enabled` always wins.
@@ -257,7 +341,12 @@ export const loadConfig = async (
   return {
     config: {
       ...config,
-      deployment: { ...config.deployment, site },
+      deployment: site
+        ? {
+            ...config.deployment,
+            options: { ...config.deployment.options, site },
+          }
+        : config.deployment,
       seo: { ...config.seo, og: { ...config.seo.og, enabled: ogEnabled } },
     },
     configFile,

package/src/core/custom-pages.ts

@@ -0,0 +1,105 @@
+import { extname, relative } from "pathe";
+import { glob, globSync } from "tinyglobby";
+
+/**
+ * Custom `.astro` pages (the `pages/` folder): discovery and the routes they
+ * serve. Lives in core so the content graph can see them too — a header tab or
+ * brand link that points at a custom page must know the page exists only at
+ * its own path, not under every locale prefix.
+ */
+
+/** A user `.astro` page and the route pattern Blume injects it at. */
+export interface CustomPageRoute {
+  /** Route pattern, e.g. `/changelog` or `/examples/[slug]`. */
+  pattern: string;
+  /** Absolute path to the user's `.astro` page file. */
+  entrypoint: string;
+}
+
+const PAGE_GLOB = ["**/*.astro"];
+
+/**
+ * Astro's routing convention: a file or folder whose name starts with `_` is a
+ * private partial — importable (shared layouts, home-page sections), but never
+ * built into a route. Blume injects pages itself, so it must reproduce the same
+ * exclusion or every `pages/_home/Hero.astro`-style component ships as an HTML
+ * page.
+ */
+const isPrivatePage = (rel: string): boolean =>
+  rel.split("/").some((segment) => segment.startsWith("_"));
+
+/** Map discovered page files to routes; shared by the async/sync discoverers. */
+const toPageRoutes = (
+  pagesRoot: string,
+  files: string[]
+): CustomPageRoute[] => {
+  files.sort();
+  const routes: CustomPageRoute[] = [];
+  for (const file of files) {
+    const rel = relative(pagesRoot, file);
+    if (isPrivatePage(rel)) {
+      continue;
+    }
+    const withoutExt = rel.slice(0, rel.length - extname(rel).length);
+    const parts = withoutExt.split("/");
+    // Only a trailing `index` maps to its parent dir; a folder literally named
+    // `index` (e.g. `index/foo.astro`) must keep its segment.
+    if (parts.at(-1) === "index") {
+      parts.pop();
+    }
+    const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
+    routes.push({ entrypoint: file, pattern });
+  }
+  return routes;
+};
+
+/**
+ * Discover user `.astro` pages and map them to route patterns. Files keep their
+ * original location; only the route pattern is derived (index -> parent,
+ * dynamic `[param]` segments preserved).
+ */
+export const discoverPages = async (
+  pagesRoot: string
+): Promise<CustomPageRoute[]> =>
+  toPageRoutes(
+    pagesRoot,
+    await glob(PAGE_GLOB, { absolute: true, cwd: pagesRoot, onlyFiles: true })
+  );
+
+/** {@link discoverPages} for synchronous callers (e.g. the sitemap builder). */
+export const discoverPagesSync = (pagesRoot: string): CustomPageRoute[] =>
+  toPageRoutes(
+    pagesRoot,
+    globSync(PAGE_GLOB, { absolute: true, cwd: pagesRoot, onlyFiles: true })
+  );
+
+/** Skip private (`_partial`, `.well-known`) and Astro dynamic (`[param]`) parts. */
+const PRIVATE_SEGMENT = /^[._]/u;
+
+/** Segments of a static, shareable page pattern; null for dynamic/private ones. */
+export const staticSegments = (pattern: string): string[] | null => {
+  const segments = pattern.split("/").filter(Boolean);
+  return segments.some(
+    (part) => PRIVATE_SEGMENT.test(part) || part.includes("[")
+  )
+    ? null
+    : segments;
+};
+
+/**
+ * The static routes served by custom `.astro` pages — the same filtering as
+ * the generated OG cards, but yielding the routes themselves. Feeds the route
+ * sets that must know every servable page beyond the content graph (the link
+ * checker, the sitemap); dynamic (`[param]`) and private segments are skipped
+ * because their concrete URLs can't be enumerated statically.
+ */
+export const customStaticRoutes = (pages: { pattern: string }[]): string[] => {
+  const routes = new Set<string>();
+  for (const { pattern } of pages) {
+    const segments = staticSegments(pattern);
+    if (segments !== null) {
+      routes.add(segments.length === 0 ? "/" : `/${segments.join("/")}`);
+    }
+  }
+  return [...routes];
+};

package/src/core/data.ts

@@ -1,7 +1,8 @@
+import type { SearchAdapterKind } from "../search/adapters/registry.ts";
 import type { StructuredDataIdentity } from "../seo/jsonld.ts";
 import type { FontHead } from "../theme/fonts.ts";
 import type { UIStrings } from "./i18n-ui.ts";
-import type { ResolvedConfig, SearchProvider } from "./schema.ts";
+import type { ResolvedConfig } from "./schema.ts";
 import type { Navigation, RouteAlternate, VersionAlternate } from "./types.ts";
 
 /**
@@ -98,6 +99,11 @@ export interface BlumeRoute {
   lastModified: string | null;
   /** Resolved locale code (the default locale when not under i18n). */
   locale: string;
+  /**
+   * True when the page's source publishes one language only (GitHub
+   * Releases), so the page renders without a language switcher.
+   */
+  monolingual: boolean;
   path: string;
   title: string;
   /** Resolved docs version (`""` for the current docs). */
@@ -112,35 +118,37 @@ export interface BlumeRoute {
 
 /** Site-wide settings derived from `blume.config` — the `config` field of {@link BlumeData}. */
 export interface BlumeDataConfig {
-  analytics: NonNullable<ResolvedConfig["analytics"]> | null;
+  /** Analytics adapter descriptors, in configured order; empty when none. */
+  analytics: ResolvedConfig["analytics"];
   /** Apple touch icon, or `null` when none is configured/detected. */
   appleIcon: BlumeFavicon | null;
-  /** Ask AI empty-state suggestions, or `null` when Ask AI is off. */
-  ask: {
+  /** The assistant's empty-state suggestions, or `null` when the assistant is off. */
+  assistant: {
     endpoint: string | null;
-    suggestions: NonNullable<ResolvedConfig["ai"]["ask"]>["suggestions"];
+    suggestions: NonNullable<ResolvedConfig["ai"]["assistant"]>["suggestions"];
   } | null;
   banner: BlumeBanner | null;
   /** Site-wide route mount point, normalized to `""` or `/seg` (see config). */
   basePath: string;
-  /** `markdown.codeBlocks.theme`: light/dark Shiki themes for code surfaces. */
-  codeThemes: ResolvedConfig["markdown"]["codeBlocks"]["theme"];
+  /** `markdown.code.theme`: light/dark Shiki themes for code surfaces. */
+  codeThemes: ResolvedConfig["markdown"]["code"]["theme"];
   /** `markdown.code.wrap`: wrap long code lines instead of scrolling. */
   codeWrap: boolean;
   /** `dateFormat`: `Intl.DateTimeFormat` options for the date stamps. */
   dateFormat: ResolvedConfig["dateFormat"];
   description: string | undefined;
   /**
-   * Which agent-discovery resources exist for the layout to advertise in every
-   * page's `<head>` (`seo.agentReadability`, `ai.llmsTxt.enabled`) — the HTML
-   * counterpart of the homepage-only HTTP `Link` header, for agents that enter
-   * on a deep page (see `ai/link-headers.ts`). `sitemap` (`seo.sitemap` with a
+   * Which agent-discovery resources exist for every layout to advertise in its
+   * page's `<head>` (`agents.agentReadability`, `agents.llmsTxt.enabled`) via
+   * the shared `DiscoveryLinks.astro` partial — the HTML counterpart of the
+   * homepage-only HTTP `Link` header, for agents that enter on a deep page
+   * (see `ai/link-headers.ts`). `sitemap` (`seo.sitemap` with a
    * `deployment.site`, the condition under which one is emitted) feeds the
    * 404 page's recovery links rather than the head.
    */
   discovery: {
     agentReadability: boolean;
-    /** Whether the AI Catalog / ARD manifest is published (`ai.catalog`). */
+    /** Whether the AI Catalog / ARD manifest is published (`agents.catalog`). */
     aiCatalog: boolean;
     /** Whether the JSON docs API and its `/openapi.json` are published. */
     api: boolean;
@@ -203,7 +211,8 @@ export interface BlumeDataConfig {
     enabled: boolean;
     /** Resolved empty-state links; empty when unset (Search falls back to sidebar). */
     popular: { icon?: string; label: string; route: string }[];
-    provider: SearchProvider;
+    /** The configured adapter's kind (`none` when search is disabled). */
+    provider: SearchAdapterKind;
   };
   /** Deployment site URL, or `null` when none is configured/detected. */
   site: string | null;
@@ -213,8 +222,8 @@ export interface BlumeDataConfig {
   /** Table-of-contents settings: whether to show it and the heading range. */
   toc: ResolvedConfig["toc"];
   /**
-   * WebMCP in-page tools (`ai.webmcp`), plus whether llms.txt exists for the
-   * list tool to fetch (`ai.llmsTxt.enabled`).
+   * WebMCP in-page tools (`agents.webmcp`), plus whether llms.txt exists for the
+   * list tool to fetch (`agents.llmsTxt.enabled`).
    */
   /** Docs versioning config; `null` when the site is unversioned. */
   versions: NonNullable<ResolvedConfig["versions"]> | null;
@@ -223,6 +232,16 @@ export interface BlumeDataConfig {
   x: { creator?: string; handle?: string };
 }
 
+/**
+ * The `discovery` flags the head partial (`components/layout/DiscoveryLinks.astro`)
+ * advertises — every layout's `discovery` prop is typed from here so a renamed
+ * or added flag surfaces in the shells at typecheck instead of drifting.
+ */
+export type DiscoveryHeadLinks = Pick<
+  BlumeDataConfig["discovery"],
+  "agentReadability" | "aiCatalog" | "llmsTxt"
+>;
+
 /**
  * The compact snapshot the layout serializes into the page for React island
  * hooks (`blume/hooks`). Islands hydrate independently, so this is read from a

package/src/core/define-components.ts

@@ -19,22 +19,25 @@ export interface IslandDescriptor {
 // oxlint-disable-next-line anti-slop/no-unknown-type-aliases -- inherits the untyped `ComponentReference` above
 export type ComponentOverride = ComponentReference | IslandDescriptor;
 
-/** User-authored component overrides, grouped by surface. */
+/**
+ * User-authored component overrides, grouped by surface. Blume reads this file
+ * statically (never executing it), so every entry must be an imported
+ * identifier, a path string, or a `{ component, client, media }` object literal
+ * — an entry with a `client` mode is an island, hydrated through a generated
+ * wrapper.
+ */
 // oxlint-disable anti-slop/no-unsafe-dictionary-type -- `ComponentOverride` is untyped by
 // design: user configs pass imported components from any framework (React
 // functions, Svelte classes, Vue SFC objects), which share no structural type.
 // `resolveSlot` and the generated components map are the runtime boundary.
 export interface ComponentOverrides {
-  /**
-   * Interactive framework components made available in every `.mdx` page. Like
-   * `mdx`, but hydrated: entries default to `client: "visible"`. Shorthand for
-   * an `mdx` descriptor with a client mode, and the config-file equivalent of
-   * dropping a component in the `islands/` folder.
-   */
-  islands?: Record<string, ComponentOverride>;
   /** Layout slot overrides (`Header`, `Sidebar`, `Footer`, ...). */
   layout?: Record<string, ComponentOverride>;
-  /** MDX component map overrides (`Callout`, `Card`, ...). */
+  /**
+   * MDX component map overrides (`Callout`, `Card`, ...) and additions,
+   * available in every `.mdx` page. Give an entry a `client` mode to hydrate
+   * it — the config-file equivalent of dropping a component in `islands/`.
+   */
   mdx?: Record<string, ComponentOverride>;
 }
 // oxlint-enable anti-slop/no-unsafe-dictionary-type

package/src/core/deployment-env.ts

@@ -1,87 +1,31 @@
+import { inferDeploymentSite } from "../deploy/platforms/index.ts";
 import type { ResolvedConfig } from "./schema.ts";
 
-/** The deployment platforms Blume can infer from runtime/CI env vars. */
-type DeploymentAdapter = NonNullable<ResolvedConfig["deployment"]["adapter"]>;
-
-interface Platform {
-  /** Astro adapter to use when building for server output on this platform. */
-  adapter: DeploymentAdapter;
-  /** True when the env indicates the build is running on this platform. */
-  detect: (env: NodeJS.ProcessEnv) => boolean;
-  /** Resolve the canonical site URL from the platform's env vars, or null. */
-  site: (env: NodeJS.ProcessEnv) => string | null;
-}
-
-/** Prefix a bare host with `https://`; pass values that are already absolute. */
-const toUrl = (value: string | undefined): string | null => {
-  const trimmed = value?.trim();
-  if (!trimmed) {
-    return null;
-  }
-  return /^https?:\/\//u.test(trimmed) ? trimmed : `https://${trimmed}`;
-};
-
-/**
- * Platforms checked in order; the first whose `detect` matches wins. Site URLs
- * prefer the stable production domain over per-deployment preview URLs so the
- * inferred origin (sitemap, OG, RSS) stays put across deploys.
- */
-const PLATFORMS: Platform[] = [
-  {
-    adapter: "vercel",
-    detect: (env) => Boolean(env.VERCEL),
-    // Fall through per *resolved* value, not per variable — a platform can set
-    // a var to the empty string, which `??` on the raw values treats as
-    // present, dead-ending the chain and silently losing the site URL.
-    site: (env) =>
-      toUrl(env.VERCEL_PROJECT_PRODUCTION_URL) ?? toUrl(env.VERCEL_URL),
-  },
-  {
-    adapter: "netlify",
-    detect: (env) => Boolean(env.NETLIFY),
-    site: (env) =>
-      toUrl(env.URL) ?? toUrl(env.DEPLOY_PRIME_URL) ?? toUrl(env.DEPLOY_URL),
-  },
-  {
-    adapter: "cloudflare",
-    detect: (env) => Boolean(env.CF_PAGES),
-    site: (env) => toUrl(env.CF_PAGES_URL),
-  },
-];
-
 /**
- * Adapters whose `deployment.site` arrives from platform env vars at deploy
- * time. Consumers (e.g. the audit) use this to tell "site is missing" apart
- * from "site is missing *here*, but the platform will set it".
- */
-export const SITE_INFERRING_ADAPTERS: ReadonlySet<string> = new Set(
-  PLATFORMS.map((platform) => platform.adapter)
-);
-
-/**
- * Fill in `deployment.adapter` and `deployment.site` from platform env vars
- * (Vercel, Netlify, Cloudflare Pages) when the user hasn't set them. Explicit
- * config always wins, and the adapter is only inferred for server output (it
- * has no effect on static builds). Mirrors Astro's platform auto-detection so a
- * project deployed to a known host gets a working canonical origin for free.
+ * Fill in the deployment `site` from platform env vars (Vercel, Netlify,
+ * Cloudflare Pages) when the config hasn't set one. Explicit config always
+ * wins. Each adapter's platform declares its own detection and URL vars (see
+ * `deploy/platforms/*`); the configured adapter is asked first, then every
+ * other platform, so a static build deployed to a known host gets a working
+ * canonical origin for free, mirroring Astro's platform auto-detection.
  */
 export const applyDeploymentEnv = (
   config: ResolvedConfig,
   env: NodeJS.ProcessEnv = process.env
 ): ResolvedConfig => {
-  const platform = PLATFORMS.find((candidate) => candidate.detect(env));
-  if (!platform) {
+  const { deployment } = config;
+  if (deployment.options.site) {
     return config;
   }
-
-  const { deployment } = config;
-  const adapter =
-    deployment.adapter ??
-    (deployment.output === "server" ? platform.adapter : null);
-  const site = deployment.site ?? platform.site(env) ?? undefined;
-
-  if (adapter === deployment.adapter && site === deployment.site) {
+  const site = inferDeploymentSite(deployment, env);
+  if (!site) {
     return config;
   }
-  return { ...config, deployment: { ...deployment, adapter, site } };
+  return {
+    ...config,
+    deployment: {
+      ...deployment,
+      options: { ...deployment.options, site },
+    },
+  };
 };