blume 2.0.2 → 2.1.0

package/src/astro/variables.ts

@@ -0,0 +1,31 @@
+import { substituteVariables } from "../core/variables.ts";
+import type { ContentVariables } from "../core/variables.ts";
+
+/**
+ * The MDX half of content variables (see `core/variables.ts`): a Vite plugin
+ * that replaces `{{name}}` in an `.mdx` module's source before the MDX
+ * compiler reads it. It has to run first: the compiler parses `{{version}}`
+ * as a JavaScript expression (a `ReferenceError` at render) and rejects
+ * `{{api-url}}` outright, so no plugin after parsing could see either.
+ */
+/** The Vite plugin slice this needs (structurally typed, like Blume's other plugins). */
+export interface VariablesVitePlugin {
+  enforce: "pre";
+  name: string;
+  transform: (code: string, id: string) => { code: string; map: null } | null;
+}
+
+export const variablesVitePlugin = (
+  variables: ContentVariables
+): VariablesVitePlugin => ({
+  enforce: "pre",
+  name: "blume:variables",
+  transform(code, id) {
+    const [path = ""] = id.split("?");
+    if (!path.endsWith(".mdx")) {
+      return null;
+    }
+    const next = substituteVariables(code, variables);
+    return next === code ? null : { code: next, map: null };
+  },
+});

package/src/audit/catalog.ts

@@ -498,6 +498,25 @@ export const CHECKS = [
     title: "Hreflang group has a language conflict",
   },
 
+  // Accessibility. Theme colors are one per site, not per page: these run
+  // on the config, the way the build resolves it.
+  {
+    category: "accessibility",
+    fix: "Pick a darker shade for light mode or a lighter one for dark mode, per mode with `theme.accent: { light, dark }`.",
+    id: "BLUME_AUDIT_THEME_CONTRAST_LOW",
+    severity: "warning",
+    tier: "static",
+    title: "Theme colors miss WCAG AA contrast",
+  },
+  {
+    category: "accessibility",
+    fix: "Write the color as hex, `rgb()`, `hsl()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`, or a named color so its contrast can be checked.",
+    id: "BLUME_AUDIT_THEME_COLOR_UNCHECKED",
+    severity: "info",
+    tier: "static",
+    title: "Theme color can't be checked for contrast",
+  },
+
   // Assets
   {
     category: "assets",

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,17 +3,16 @@ 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"]);
 
+/** Where a fragment's directives (text fragments) start. */
+const FRAGMENT_DIRECTIVE = ":~:";
+
 /** Whether a fragment lands on an id of the target page. */
 const anchorResolves = (target: PageSnapshot, fragment: string): boolean => {
   if (MAGIC_FRAGMENTS.has(fragment)) {
@@ -30,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.
  *
@@ -65,8 +61,12 @@ export const linkChecks: CheckModule = {
       page: PageSnapshot,
       link: SnapshotLink,
       target: PageSnapshot,
-      fragment: string
+      hash: string
     ): void => {
+      // A text fragment (`#:~:text=…`) is a directive the browser strips
+      // before it looks for an id; only the part in front of `:~:` names an
+      // element, and an empty one scrolls to the text instead.
+      const [fragment = ""] = hash.split(FRAGMENT_DIRECTIVE);
       if (anchorResolves(target, fragment)) {
         return;
       }
@@ -143,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(
@@ -193,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/graph.ts

@@ -58,7 +58,8 @@ export const buildGraph = (
  * Non-indexable pages are excluded — a `noindex` page is *meant* to be
  * unreachable — as is the home page, which is nobody's job to link to. Under a
  * `basePath` the home page's built URL is the base itself, so the caller names
- * it via `homeUrl`.
+ * it via `homeUrl`. An i18n fallback copy is excluded too: it stands in for a
+ * translation nobody has written yet, so the page to link to is the original.
  */
 export const orphanPages = (
   pages: PageSnapshot[],
@@ -68,6 +69,7 @@ export const orphanPages = (
   pages.filter(
     (page) =>
       page.indexable &&
+      page.route?.fallback !== true &&
       page.url !== "/" &&
       page.url !== homeUrl &&
       (graph.contentIn.get(page.url)?.size ?? 0) === 0

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

@@ -2,14 +2,17 @@ import { readFile } from "node:fs/promises";
 
 import pMap from "p-map";
 
-import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
+import { normalizeBasePath } from "../core/base-path.ts";
+import { routeSetFor } from "../core/locale-links.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { deployStaticDir } from "../deploy/adapter-output.ts";
+import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
 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";
@@ -49,6 +52,7 @@ const MODULES: CheckModule[] = [
   ogImageChecks,
   i18nChecks,
   assetChecks,
+  contrastChecks,
   sitemapChecks,
   robotsChecks,
   llmsChecks,
@@ -162,14 +166,15 @@ export const runAudit = async (options: AuditOptions): Promise<AuditResult> => {
     redirects: resolveRedirects(
       // Redirects are authored as if mounted at root; the built page URLs they
       // are checked against carry `basePath` (it's a real directory in the
-      // build), so both sides gain it here — mirroring what
-      // `applyBaseToAstroRedirects` does at build time. `withBasePath` is
-      // idempotent and leaves external `to` URLs untouched.
-      project.config.redirects.map((redirect) => ({
-        ...redirect,
-        from: withBasePath(basePath, redirect.from),
-        to: withBasePath(basePath, redirect.to),
-      })),
+      // build), so both sides gain it here, based exactly as the build bases
+      // them — a `to` naming a public file stays at the root, and external
+      // `to` URLs pass through.
+      applyBaseToAstroRedirects(
+        project.config.redirects,
+        basePath,
+        "",
+        routeSetFor(project.manifest.routes)
+      ),
       // Pages, static files, and server routes alike: a redirect may
       // legitimately land on a served asset (`/old-whitepaper` ->
       // `/files/whitepaper.pdf`), and the same predicate the link and llms.txt

package/src/audit/snapshot.ts

@@ -196,8 +196,13 @@ export const buildSnapshot = (options: {
     scripts: collectAssets(document, "script[src]", "src"),
     source: route?.sourcePath,
     styles: collectAssets(document, 'link[rel="stylesheet"][href]', "href"),
+    // Only the document's own titles: an accessible inline SVG carries a
+    // `<title>` of its own (an SVG-namespace element, not the page title), and
+    // counting it would flag BLUME_AUDIT_TITLE_MULTIPLE — or stand in for a
+    // head `<title>` that is genuinely missing.
     titles: document
       .querySelectorAll("title")
+      .filter((title) => !title.closest("svg"))
       .map((title) => title.text.trim())
       .filter((text) => text.length > 0),
     twitter: prefixedMeta(document, "name", "twitter:"),

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