blume 2.0.3 → 2.1.0

package/src/audit/checks/contrast.ts

@@ -0,0 +1,183 @@
+import type { ResolvedConfig } from "../../core/schema.ts";
+import type { Diagnostic } from "../../core/types.ts";
+import { composite, contrastRatio, parseColor } from "../../theme/color.ts";
+import type { Rgba } from "../../theme/color.ts";
+import {
+  MIN_TEXT_CONTRAST,
+  labelOn,
+  resolveAccent,
+  resolveAction,
+  themeInk,
+} from "../../theme/palette.ts";
+import type { ColorMode } from "../../theme/palette.ts";
+import { finding } from "../catalog.ts";
+import type { CheckModule } from "../types.ts";
+
+const MODES = ["light", "dark"] as const satisfies readonly ColorMode[];
+
+/** The theme config key a color comes from. */
+type ThemeKey = "theme.accent" | "theme.action" | "theme.background";
+
+/** A color the theme draws text in, over the surface it sits on. */
+interface TextPair {
+  fix: string;
+  key: ThemeKey;
+  /** What the pair is, for the message: "Accent text on the page". */
+  label: string;
+  surface: Rgba;
+  text: Rgba;
+}
+
+/** A theme color, resolved for one mode, and the config key it came from. */
+interface ThemeColor {
+  key: ThemeKey;
+  value: string;
+}
+
+/** What one mode's check found: pairs to measure, colors it couldn't read. */
+interface ModeColors {
+  pairs: TextPair[];
+  unread: ThemeColor[];
+}
+
+/** A fill and the label the build puts on it (`labelOn`, as `readableOn`). */
+const fillPair = (
+  key: "theme.accent" | "theme.action",
+  fill: Rgba,
+  page: Rgba,
+  mode: ColorMode
+): TextPair => ({
+  fix: `Neither white nor dark text reaches ${MIN_TEXT_CONTRAST}:1 on this shade. Move \`${key}\`'s ${mode} shade lighter or darker.`,
+  key,
+  label:
+    key === "theme.action"
+      ? "The call-to-action label"
+      : "Button labels on the accent",
+  surface: composite(fill, page),
+  text: parseColor(labelOn(fill, mode)) ?? fill,
+});
+
+/** The accent's pairs: accent text on the page, and labels on accent fills. */
+const accentPairs = (fill: Rgba, page: Rgba, mode: ColorMode): TextPair[] => [
+  {
+    fix: `${mode === "light" ? "Darken" : "Lighten"} \`theme.accent\`'s ${mode} shade (\`theme.accent: { light, dark }\`).`,
+    key: "theme.accent",
+    label: "Accent text on the page",
+    surface: page,
+    text: fill,
+  },
+  fillPair("theme.accent", fill, page, mode),
+];
+
+/** The pairs a custom page background sets: body and secondary text on it. */
+const backgroundPairs = (page: Rgba, mode: ColorMode): TextPair[] => {
+  const fix = `Pick a \`theme.background\` ${mode} color further from the text color.`;
+  return [
+    {
+      fix,
+      key: "theme.background",
+      label: "Body text on the page",
+      surface: page,
+      text: themeInk(mode, "foreground"),
+    },
+    {
+      fix,
+      key: "theme.background",
+      label: "Secondary text on the page",
+      surface: page,
+      text: themeInk(mode, "mutedForeground"),
+    },
+  ];
+};
+
+/** Everything one mode draws text in, from the theme config. */
+const modeColors = (
+  theme: ResolvedConfig["theme"],
+  mode: ColorMode
+): ModeColors => {
+  const unread: ThemeColor[] = [];
+  const read = (color: ThemeColor): Rgba | null => {
+    const parsed = parseColor(color.value);
+    if (!parsed) {
+      unread.push(color);
+    }
+    return parsed;
+  };
+  const custom = theme.background?.[mode];
+  const customPage =
+    custom === undefined
+      ? null
+      : read({ key: "theme.background", value: custom });
+  // Text on a page color the audit can't read can't be measured.
+  if (custom !== undefined && !customPage) {
+    return { pairs: [], unread };
+  }
+  const page = customPage ?? themeInk(mode, "background");
+  const pairs = customPage ? backgroundPairs(customPage, mode) : [];
+  const accent = read({
+    key: "theme.accent",
+    value: resolveAccent(theme)[mode],
+  });
+  if (accent) {
+    pairs.push(...accentPairs(accent, page, mode));
+  }
+  const action = resolveAction(theme);
+  const actionFill =
+    action && read({ key: "theme.action", value: action[mode] });
+  if (actionFill) {
+    pairs.push(fillPair("theme.action", actionFill, page, mode));
+  }
+  return { pairs, unread };
+};
+
+/**
+ * Theme contrast: the text colors a configured theme draws — accent text,
+ * labels on accent and call-to-action fills, and body text on a custom
+ * background — measured against WCAG AA's 4.5:1 in both color modes, resolved
+ * the way the build resolves them (presets per mode, labels by `labelOn`).
+ * One finding per failing pair, pointed at blume.config.ts, since a theme
+ * color is a site-wide choice, not a page's.
+ */
+export const contrastChecks: CheckModule = {
+  category: "accessibility",
+  run(context) {
+    const { theme } = context.project.config;
+    const site = {
+      file: context.project.context.configFile ?? undefined,
+      url: "/",
+    };
+    const found: Diagnostic[] = [];
+    const reported = new Set<string>();
+    for (const mode of MODES) {
+      const { pairs, unread } = modeColors(theme, mode);
+      for (const color of unread) {
+        const id = `${color.key}:${color.value}`;
+        if (!reported.has(id)) {
+          reported.add(id);
+          found.push(
+            finding(
+              "BLUME_AUDIT_THEME_COLOR_UNCHECKED",
+              site,
+              `\`${color.key}\` is "${color.value}", which the audit can't read as a color, so its contrast went unchecked.`
+            )
+          );
+        }
+      }
+      for (const pair of pairs) {
+        const ratio = contrastRatio(pair.text, pair.surface);
+        if (ratio < MIN_TEXT_CONTRAST) {
+          found.push(
+            finding(
+              "BLUME_AUDIT_THEME_CONTRAST_LOW",
+              site,
+              `${pair.label} in ${mode} mode is ${ratio.toFixed(2)}:1, under the ${MIN_TEXT_CONTRAST}:1 WCAG AA asks of body text (\`${pair.key}\`).`,
+              pair.fix
+            )
+          );
+        }
+      }
+    }
+    return found;
+  },
+  tier: "static",
+};

package/src/audit/checks/i18n.ts

@@ -2,6 +2,7 @@ import { normalizeBasePath, stripBasePath } from "../../core/base-path.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
+import { redirectAt } from "../redirects.ts";
 import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
 import { decodePath, normalizePath } from "../url.ts";
 import { isArchivedLatestCanonical } from "./indexability.ts";
@@ -134,9 +135,7 @@ const hreflangChecks = (
     }
 
     const target = context.byUrl.get(path);
-    const redirect = context.redirects.find(
-      (entry) => normalizePath(entry.from) === path
-    );
+    const redirect = redirectAt(context.redirects, path);
     if (redirect) {
       found.push(
         finding(

package/src/audit/checks/indexability.ts

@@ -3,6 +3,7 @@ import type { Diagnostic } from "../../core/types.ts";
 import { deployPlatform } from "../../deploy/platforms/index.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
+import { redirectAt } from "../redirects.ts";
 import { ERROR_ROUTES } from "../types.ts";
 import type { AuditContext, CheckModule, PageSnapshot } from "../types.ts";
 import { decodePath, normalizePath, siteOrigin } from "../url.ts";
@@ -118,9 +119,7 @@ const canonicalChecks = (
 
   // The canonical points at another page on this site. It must exist, and it
   // must not itself redirect — a canonical to a redirect is a dead end.
-  const redirect = context.redirects.find(
-    (entry) => normalizePath(entry.from) === target
-  );
+  const redirect = redirectAt(context.redirects, target);
   if (redirect) {
     found.push(
       finding(

package/src/audit/checks/links.ts

@@ -3,13 +3,9 @@ import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import { orphanPages } from "../graph.ts";
 import { pageSite } from "../locate.ts";
-import type {
-  AuditContext,
-  CheckModule,
-  PageSnapshot,
-  SnapshotLink,
-} from "../types.ts";
-import { isServed, normalizePath, resolveHref, siteOrigin } from "../url.ts";
+import { redirectAt } from "../redirects.ts";
+import type { CheckModule, PageSnapshot, SnapshotLink } from "../types.ts";
+import { isServed, resolveHref, siteOrigin } from "../url.ts";
 
 /** Browser-magic fragments that scroll without needing a matching id. */
 const MAGIC_FRAGMENTS = new Set(["", "top"]);
@@ -33,9 +29,6 @@ const anchorResolves = (target: PageSnapshot, fragment: string): boolean => {
   }
 };
 
-const redirectFrom = (context: AuditContext, path: string) =>
-  context.redirects.find((entry) => normalizePath(entry.from) === path);
-
 /**
  * Internal links, and what they land on.
  *
@@ -150,7 +143,7 @@ export const linkChecks: CheckModule = {
       }
 
       const { path } = resolved;
-      const redirect = redirectFrom(context, path);
+      const redirect = redirectAt(context.redirects, path);
       if (redirect) {
         if (link.content) {
           found.push(
@@ -200,7 +193,7 @@ export const linkChecks: CheckModule = {
       );
     }
     for (const [path, page] of redirectedChrome) {
-      const redirect = redirectFrom(context, path);
+      const redirect = redirectAt(context.redirects, path);
       found.push(
         finding(
           "BLUME_AUDIT_LINK_TO_REDIRECT",

package/src/audit/checks/sitemap.ts

@@ -2,6 +2,7 @@ import { normalizeBasePath, stripBasePath } from "../../core/base-path.ts";
 import type { Diagnostic } from "../../core/types.ts";
 import { finding } from "../catalog.ts";
 import { pageSite } from "../locate.ts";
+import { redirectAt } from "../redirects.ts";
 import type { AuditContext, CheckModule } from "../types.ts";
 import { decodePath, normalizePath, siteOrigin } from "../url.ts";
 
@@ -100,9 +101,7 @@ const checkListedUrl = (
   );
   const page = context.byUrl.get(path);
   if (!page) {
-    const redirect = context.redirects.find(
-      (entry) => normalizePath(entry.from) === path
-    );
+    const redirect = redirectAt(context.redirects, path);
     return [
       finding(
         "BLUME_AUDIT_SITEMAP_BAD_URL",

package/src/audit/redirects.ts

@@ -1,3 +1,7 @@
+import {
+  isPatternPath,
+  patternDestination,
+} from "../core/redirect-patterns.ts";
 import type { RedirectResolution } from "./types.ts";
 import { normalizePath } from "./url.ts";
 
@@ -7,18 +11,6 @@ interface ConfiguredRedirect {
   status: number;
 }
 
-/**
- * Follow every configured redirect through to its destination, classifying what
- * it lands on.
- *
- * - `loop`   — the chain revisits a hop it has already been to. Never resolves.
- * - `broken` — the chain ends somewhere the build does not serve.
- * - `chain`  — it resolves, but through at least one intermediate redirect.
- * - `ok`     — one hop, straight to a real page.
- *
- * An external destination (`https://…`) is always `ok`: it's outside the site,
- * so there's no local page to check it against.
- */
 /**
  * A destination's page path: the part before any query string or fragment. A
  * redirect to `/guide#setup` or `/search?q=x` lands on the `/guide` / `/search`
@@ -30,6 +22,22 @@ const pathOnly = (value: string): string => {
   return cut === -1 ? value : value.slice(0, cut);
 };
 
+/**
+ * Follow every configured redirect through to its destination, classifying what
+ * it lands on.
+ *
+ * - `loop`    — the chain revisits a hop it has already been to. Never resolves.
+ * - `broken`  — the chain ends somewhere the build does not serve.
+ * - `chain`   — it resolves, but through at least one intermediate redirect.
+ * - `ok`      — one hop, straight to a real page.
+ * - `pattern` — a pattern (`/beta/:slug*`), which covers paths rather than
+ *   naming one, so there is no single chain to walk; {@link redirectAt}
+ *   resolves a path it covers.
+ *
+ * An external destination (`https://…`) is always `ok`: it's outside the site,
+ * so there's no local page to check it against. A hop onto a path a pattern
+ * covers continues through that pattern.
+ */
 export const resolveRedirects = (
   redirects: readonly ConfiguredRedirect[],
   /** Whether the build serves a normalized path — see `isServed`. */
@@ -39,9 +47,14 @@ export const resolveRedirects = (
   for (const redirect of redirects) {
     byFrom.set(normalizePath(redirect.from), redirect);
   }
+  const hopFrom = (path: string): string | undefined =>
+    byFrom.get(path)?.to ?? patternDestination(redirects, path);
 
   return redirects.map((redirect) => {
     const from = normalizePath(redirect.from);
+    if (isPatternPath(redirect.from)) {
+      return { ...redirect, chain: [from], outcome: "pattern" as const };
+    }
     const chain: string[] = [from];
     const seen = new Set<string>([from]);
     let current = redirect.to;
@@ -63,11 +76,11 @@ export const resolveRedirects = (
       }
       chain.push(next);
       seen.add(next);
-      const hop = byFrom.get(next);
-      if (!hop) {
+      const hop = hopFrom(next);
+      if (hop === undefined) {
         break;
       }
-      current = hop.to;
+      current = hop;
     }
 
     const destination = chain.at(-1) ?? from;
@@ -84,3 +97,21 @@ export const resolveRedirects = (
     };
   });
 };
+
+/**
+ * The configured redirect a path takes, for the checks that report a link,
+ * canonical, sitemap entry, or `hreflang` pointing through one: the exact
+ * redirect from that path, else the pattern covering it, its `to` filled in
+ * for this path.
+ */
+export const redirectAt = (
+  redirects: readonly RedirectResolution[],
+  path: string
+): { to: string } | undefined => {
+  const exact = redirects.find((entry) => normalizePath(entry.from) === path);
+  if (exact) {
+    return exact;
+  }
+  const to = patternDestination(redirects, path);
+  return to === undefined ? undefined : { to };
+};

package/src/audit/run.ts

@@ -12,6 +12,7 @@ import { CHECKS } from "./catalog.ts";
 import type { CheckId } from "./catalog.ts";
 import { assetChecks } from "./checks/assets.ts";
 import { contentChecks } from "./checks/content.ts";
+import { contrastChecks } from "./checks/contrast.ts";
 import { dnsAidChecks } from "./checks/dns-aid.ts";
 import { duplicateChecks } from "./checks/duplicates.ts";
 import { i18nChecks } from "./checks/i18n.ts";
@@ -51,6 +52,7 @@ const MODULES: CheckModule[] = [
   ogImageChecks,
   i18nChecks,
   assetChecks,
+  contrastChecks,
   sitemapChecks,
   robotsChecks,
   llmsChecks,

package/src/audit/types.ts

@@ -13,6 +13,7 @@ import type {
 export type AuditTier = "static" | "network" | "external";
 
 export type AuditCategory =
+  | "accessibility"
   | "content"
   | "duplicates"
   | "indexability"
@@ -110,7 +111,7 @@ export interface RedirectResolution {
   status: number;
   /** Every hop from `from` to the final target, inclusive. */
   chain: string[];
-  outcome: "ok" | "loop" | "broken" | "chain";
+  outcome: "ok" | "loop" | "broken" | "chain" | "pattern";
 }
 
 /** One urlset file behind a sitemap, for the per-file size limits. */

package/src/blume-modules.d.ts

@@ -15,6 +15,13 @@ declare module "blume:search-client" {
   export const createSearch: () => Fn | Promise<Fn>;
 }
 
+declare module "blume:consent-client" {
+  /** Start the configured consent adapter's browser module (see `consentClientTemplate`); a no-op for one without. */
+  // oxlint-disable-next-line typescript/consistent-type-imports
+  type Consent = import("./components/layout/consent/types.ts").BlumeConsent;
+  export const startConsentClient: (consent: Consent) => void;
+}
+
 declare module "blume:ask" {
   /** The generated Ask trigger (see `askComponentTemplate`); empty when Ask is off. */
   // Mirrors the generated `.blume/src/env.d.ts` declaration: the trigger's type

package/src/captcha/client.ts

@@ -0,0 +1,152 @@
+/**
+ * The browser half of the bot check: a fresh token for each question the
+ * assistant sends (both providers' tokens are single-use). The provider's
+ * script loads with the first question rather than with the page, and one
+ * widget serves every question after it: an invisible hCaptcha, or a
+ * Turnstile that only shows itself when it needs the reader to interact,
+ * in a small container at the foot of the viewport.
+ *
+ * The client router swaps `<body>` on every navigation, taking the container
+ * and its widget with it, so a question after a swap mounts a new one.
+ */
+import type { CaptchaSettings } from "./schema.ts";
+
+/** Each provider's script, rendering only when asked to. */
+export const CAPTCHA_SCRIPTS = {
+  hcaptcha: "https://js.hcaptcha.com/1/api.js?render=explicit",
+  turnstile:
+    "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit",
+} as const;
+
+/** What Blume asks a Turnstile widget for. */
+interface TurnstileRenderOptions {
+  appearance: "interaction-only";
+  callback: (token: string) => void;
+  "error-callback": () => void;
+  execution: "execute";
+  sitekey: string;
+}
+
+/** The slice of `window.turnstile` the check uses. */
+export interface TurnstileApi {
+  execute: (widget: string) => void;
+  render: (container: HTMLElement, options: TurnstileRenderOptions) => string;
+  reset: (widget: string) => void;
+}
+
+/** What Blume asks an hCaptcha widget for. */
+interface HcaptchaRenderOptions {
+  sitekey: string;
+  size: "invisible";
+}
+
+/** The slice of `window.hcaptcha` the check uses. */
+export interface HcaptchaApi {
+  execute: (
+    widget: string,
+    options: { async: true }
+  ) => Promise<{ response: string }>;
+  render: (container: HTMLElement, options: HcaptchaRenderOptions) => string;
+  reset: (widget: string) => void;
+}
+
+/** The window, with the providers' globals once their scripts ran. */
+type CaptchaWindow = Window & {
+  hcaptcha?: HcaptchaApi;
+  turnstile?: TurnstileApi;
+};
+
+/** A Turnstile token on its way. */
+interface PendingToken {
+  reject: (error: Error) => void;
+  resolve: (token: string) => void;
+}
+
+/** Get a token for the next question. */
+export type CaptchaTokenGetter = (settings: CaptchaSettings) => Promise<string>;
+
+/** A token getter with its own script, container, and widget. */
+export const createCaptchaClient = (): CaptchaTokenGetter => {
+  let loaded: Promise<void> | undefined;
+  let host: HTMLElement | undefined;
+  let widget: string | undefined;
+  let pending: PendingToken | undefined;
+
+  const load = (kind: CaptchaSettings["kind"]): Promise<void> => {
+    // oxlint-disable-next-line promise/avoid-new -- adapt the script tag's load events
+    loaded ??= new Promise<void>((resolve, reject) => {
+      const tag = document.createElement("script");
+      tag.async = true;
+      tag.src = CAPTCHA_SCRIPTS[kind];
+      tag.addEventListener("load", () => resolve());
+      tag.addEventListener("error", () => {
+        // Let the next question try again.
+        loaded = undefined;
+        reject(new Error(`The ${kind} script didn't load.`));
+      });
+      document.head.append(tag);
+    });
+    return loaded;
+  };
+
+  // The widget's container, mounted again when a swap took the last one.
+  const mount = (): HTMLElement => {
+    if (host?.isConnected) {
+      return host;
+    }
+    host = document.createElement("div");
+    host.className = "fixed bottom-4 left-1/2 z-[60] -translate-x-1/2";
+    host.dataset.blumeCaptcha = "";
+    document.body.append(host);
+    widget = undefined;
+    return host;
+  };
+
+  const turnstileToken = (api: TurnstileApi, siteKey: string) =>
+    // oxlint-disable-next-line promise/avoid-new -- adapt Turnstile's token callbacks
+    new Promise<string>((resolve, reject) => {
+      pending = { reject, resolve };
+      const target = mount();
+      if (widget === undefined) {
+        widget = api.render(target, {
+          appearance: "interaction-only",
+          callback: (token) => pending?.resolve(token),
+          "error-callback": () =>
+            pending?.reject(new Error("The Turnstile check failed.")),
+          execution: "execute",
+          sitekey: siteKey,
+        });
+      } else {
+        api.reset(widget);
+      }
+      api.execute(widget);
+    });
+
+  const hcaptchaToken = async (api: HcaptchaApi, siteKey: string) => {
+    const target = mount();
+    if (widget === undefined) {
+      widget = api.render(target, { sitekey: siteKey, size: "invisible" });
+    } else {
+      api.reset(widget);
+    }
+    const { response } = await api.execute(widget, { async: true });
+    return response;
+  };
+
+  return async (settings) => {
+    await load(settings.kind);
+    // SAFETY: CaptchaWindow only adds the providers' optional globals, each
+    // checked before use.
+    const { hcaptcha, turnstile } = window as CaptchaWindow;
+    if (settings.kind === "hcaptcha" && hcaptcha) {
+      return hcaptchaToken(hcaptcha, settings.siteKey);
+    }
+    if (settings.kind === "turnstile" && turnstile) {
+      return turnstileToken(turnstile, settings.siteKey);
+    }
+    throw new Error(`The ${settings.kind} script loaded without its API.`);
+  };
+};
+
+/** The page's token getter: one script and one widget per page load. */
+export const captchaToken = createCaptchaClient();

package/src/captcha/hcaptcha.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+import type { AdapterDescriptor } from "../core/adapter.ts";
+import { adapterDescriptorSchema } from "../core/adapter.ts";
+
+/** Options for {@link hcaptcha}. */
+export interface HcaptchaOptions {
+  /** The site key, from the hCaptcha dashboard. */
+  siteKey: string;
+}
+
+export const hcaptchaOptionsSchema = z.strictObject({
+  siteKey: z.string().min(1),
+});
+
+export type HcaptchaAdapter = AdapterDescriptor<"hcaptcha", HcaptchaOptions>;
+
+export const hcaptchaAdapterSchema = adapterDescriptorSchema(
+  "hcaptcha",
+  hcaptchaOptionsSchema
+);
+
+/** Where the assistant's route checks an hCaptcha token. */
+export const HCAPTCHA_VERIFY_URL = "https://api.hcaptcha.com/siteverify";
+
+/**
+ * hCaptcha, as an invisible check: most readers never see a challenge. The
+ * site key is public and goes to the browser; the secret the route checks
+ * tokens with comes from `HCAPTCHA_SECRET_KEY`.
+ */
+export const hcaptcha = (options: HcaptchaOptions): HcaptchaAdapter => ({
+  kind: "hcaptcha",
+  options,
+  requiredSecrets: ["HCAPTCHA_SECRET_KEY"],
+  runtimeDeps: [],
+});

package/src/captcha/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Bot checks for the assistant (`ai.assistant.captcha` in `blume.config.ts`).
+ * The assistant gets a token from the check before each question and the
+ * generated route verifies it before calling the model:
+ *
+ * ```ts
+ * import { defineConfig } from "blume";
+ * import { turnstile } from "blume/captcha";
+ *
+ * export default defineConfig({
+ *   ai: {
+ *     assistant: {
+ *       enabled: true,
+ *       captcha: turnstile({ siteKey: "0x4AAAAAAA…" }),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * Each factory returns a plain descriptor (see `core/adapter.ts`); the browser
+ * half is `client.ts`, the server half `verify.ts`.
+ */
+export type { AdapterDescriptor, JsonValue } from "../core/adapter.ts";
+export { hcaptcha } from "./hcaptcha.ts";
+export type { HcaptchaAdapter, HcaptchaOptions } from "./hcaptcha.ts";
+export type { CaptchaAdapter, CaptchaSettings } from "./schema.ts";
+export { turnstile } from "./turnstile.ts";
+export type { TurnstileAdapter, TurnstileOptions } from "./turnstile.ts";

package/src/captcha/schema.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+
+import { hcaptchaAdapterSchema } from "./hcaptcha.ts";
+import { turnstileAdapterSchema } from "./turnstile.ts";
+
+/**
+ * The configured bot check, as its factory returned it. Anything that isn't
+ * one fails with the adapter hint; an adapter's own option errors keep their
+ * messages.
+ */
+export const captchaAdapterSchema = z.discriminatedUnion(
+  "kind",
+  [hcaptchaAdapterSchema, turnstileAdapterSchema],
+  {
+    error:
+      'captcha takes one adapter — e.g. `captcha: turnstile({ siteKey })` or `captcha: hcaptcha({ siteKey })`, imported from "blume/captcha".',
+  }
+);
+
+export type CaptchaAdapter = z.output<typeof captchaAdapterSchema>;
+
+/** What the browser needs to run the check: never the secret. */
+export interface CaptchaSettings {
+  kind: CaptchaAdapter["kind"];
+  siteKey: string;
+}
+
+/** The public half of an adapter, for the data snapshot. */
+export const captchaSettings = (adapter: CaptchaAdapter): CaptchaSettings => ({
+  kind: adapter.kind,
+  siteKey: adapter.options.siteKey,
+});