ferst-core 0.9.2 → 0.9.4

package/components/recipes/LatestPosts.astro

@@ -242,7 +242,7 @@ const isNew = (date: Date | string) => isRecent(date, newWithinDays, nowMs);
     padding: 0.12rem 0.45rem;
     border-radius: var(--radius-pill);
     background: var(--gold);
-    color: var(--text-light);
+    color: var(--on-brand);
     font-family: var(--font-heading);
     font-size: 0.62rem;
     font-weight: 700;

package/components/recipes/LinkRow.astro

@@ -20,7 +20,7 @@ const external = (href: string) => /^https?:\/\//i.test(href);
 ---
 
 <section class="b-linkrow">
-  {title && <Heading text={title} level={3} />}
+  {title && <Heading text={title} level={2} />}
   {intro && <p class="b-linkrow__intro" set:html={inlineMarkdown(intro)} />}
   <ul class="b-linkrow__links">
     {links.map((l) => (
@@ -36,6 +36,8 @@ const external = (href: string) => /^https?:\/\//i.test(href);
 </section>
 
 <style>
+  /* Its title is the block's heading (h2, so headings stay in order) at the h3 size it always had. */
+  .b-linkrow > :global(h2) { font-size: clamp(1.375rem, 1.2rem + 0.55vw, 1.625rem); }
   .b-linkrow {
     display: flex;
     flex-direction: column;

package/components/recipes/Locations.astro

@@ -126,7 +126,7 @@ const cols = Math.min(columns, Math.max(items.length, 1)) as 1 | 2;
   .b-loc-map__load {
     font: inherit; font-family: var(--font-heading); font-weight: 600; font-size: 0.9rem;
     padding: 0.5rem 1.1rem; border: none; border-radius: var(--radius-sm);
-    background: var(--gold); color: var(--text-light); cursor: pointer;
+    background: var(--gold); color: var(--on-brand); cursor: pointer;
     transition: filter 0.15s ease;
   }
   .b-loc-map__load:hover { filter: brightness(0.94); }

package/components/recipes/MapEmbed.astro

@@ -150,7 +150,7 @@ const safe = isSafeEmbedUrl(embedUrl);
     border: none;
     border-radius: var(--radius-sm);
     background: var(--gold);
-    color: var(--text-light);
+    color: var(--on-brand);
     cursor: pointer;
     transition: filter 0.15s ease;
   }

package/components/recipes/Pricing.astro

@@ -111,7 +111,7 @@ const headAlign = headingAlign ?? blockAlign ?? 'center';
     font-weight: 700;
     letter-spacing: 0.08em;
     text-transform: uppercase;
-    color: var(--text-light);
+    color: var(--on-brand);
     background: var(--gold);
     padding: 0.2rem 0.6rem;
     border-radius: var(--radius-pill);

package/components/recipes/Steps.astro

@@ -81,7 +81,7 @@ const headAlign = headingAlign ?? blockAlign ?? 'center';
     justify-content: center;
     border-radius: var(--radius-pill);
     background: var(--gold);
-    color: var(--text-light);
+    color: var(--on-brand);
     font-family: var(--font-heading);
     font-weight: 700;
     font-size: 1.05rem;

package/components/recipes/Tiles.astro

@@ -36,6 +36,8 @@ interface Props {
   tiles?: Tile[];
 }
 const { title, intro, columns = 3, variant = 'elevated', spotlight = false, tiles = [] } = Astro.props;
+// Headings stay in order: items sit one level under the block's title, or take its place.
+const ItemHeading = title ? 'h3' : 'h2';
 // Alignment overrides (BlockLayout): the title + intro default to centred; the block's
 // own `align`, or `headingAlign` for the title alone, overrides it from the page data.
 const { align: blockAlign, headingAlign } = Astro.props as { align?: 'start' | 'center' | 'end'; headingAlign?: 'start' | 'center' | 'end' };
@@ -73,7 +75,7 @@ const cols = Math.min(columns, Math.max(tiles.length, 1)) as 1 | 2 | 3 | 4;
             <span class="b-tile__icon"><Icon name={tile.icon} size={26} /></span>
           )}
           {tile.eyebrow && <span class="b-tile__eyebrow">{tile.eyebrow}</span>}
-          {tile.title && <h3 class="b-tile__title">{tile.title}</h3>}
+          {tile.title && <ItemHeading class="b-tile__title">{tile.title}</ItemHeading>}
           {/* A linked tile is one big link: its text keeps breaks and emphasis, no inner links. */}
           {tile.text && <p class="b-tile__text" set:html={tile.href ? inlineMarkdownNoLinks(tile.text) : inlineMarkdown(tile.text)} />}
           {tile.href && !plain && <span class="b-tile__more" aria-hidden="true">{tile.linkLabel ?? 'Learn more'} &rarr;</span>}
@@ -151,7 +153,7 @@ const cols = Math.min(columns, Math.max(tiles.length, 1)) as 1 | 2 | 3 | 4;
   }
   .b-tiles__grid[data-variant='gradient'] .b-tile {
     background: linear-gradient(135deg, var(--gold), var(--accent-2, var(--gold)));
-    color: var(--text-light);
+    color: var(--on-brand);
   }
   .b-tiles__grid[data-variant='image'] .b-tile {
     color: #fff;

package/components/recipes/Video.astro

@@ -141,7 +141,7 @@ const safeLink = /^https:\/\//i.test(url) ? url : undefined;
     border: none;
     border-radius: var(--radius-sm);
     background: var(--gold);
-    color: var(--text-light);
+    color: var(--on-brand);
     cursor: pointer;
   }
   .b-video__load:hover {

package/content/accessibility.ts

@@ -0,0 +1,62 @@
+/**
+ * The accessibility statement (`/accessibility`), generated for every site like the cookie
+ * policy: what the site does for people using keyboards, screen readers or magnification,
+ * where it falls short, and how to report a problem. Pure, so it's unit-testable; the route
+ * (routes/accessibility.astro) renders it with the site's name and contact details.
+ */
+export interface StatementSection {
+  heading: string;
+  paragraphs: string[];
+  items?: string[];
+  /** On the "reporting a problem" section, when the site has contact details. */
+  contact?: { email?: string; phone?: string };
+}
+
+export interface AccessibilityStatement {
+  title: string;
+  intro: string;
+  sections: StatementSection[];
+}
+
+export function accessibilityStatement({ siteName, email, phone }: { siteName: string; email?: string; phone?: string }): AccessibilityStatement {
+  const contact = email || phone ? { ...(email ? { email } : {}), ...(phone ? { phone } : {}) } : undefined;
+  return {
+    title: 'Accessibility',
+    intro: `${siteName} wants everyone to be able to use this website, including people who use a keyboard instead of a mouse, a screen reader, or magnification.`,
+    sections: [
+      {
+        heading: 'What you can do on this site',
+        paragraphs: ['The site is built so that you can:'],
+        items: [
+          'move around it using only a keyboard, starting with a "Skip to content" link',
+          'use it with a screen reader: pages have headings in order, landmarks and descriptions for meaningful pictures',
+          'zoom in up to 400% without text spilling off the screen, and read it on a phone',
+          'read text that stands out clearly from its background, in light and dark mode',
+          'stop moving backgrounds; they stay still if your device asks for reduced motion',
+        ],
+      },
+      {
+        heading: 'The standard we aim for',
+        paragraphs: [
+          'The site aims to meet the Web Content Accessibility Guidelines version 2.2 (WCAG 2.2) at level AA. Its layout, navigation and controls are tested for accessibility before every release of the software it runs on.',
+        ],
+      },
+      {
+        heading: 'What may not be fully accessible',
+        paragraphs: ['We know of some things that may be harder to use:'],
+        items: [
+          'some documents, such as PDF newsletters and older uploads, were not written with accessibility in mind',
+          'videos shown from other sites, such as YouTube, rely on that site for their captions',
+          'some older pictures may not have a description yet',
+        ],
+      },
+      {
+        heading: 'Reporting a problem',
+        paragraphs: contact
+          ? ['If something on this site is hard to use, or you need information in another format, please tell us. We will do our best to help.']
+          : ['If something on this site is hard to use, or you need information in another format, please get in touch through the contact page. We will do our best to help.'],
+        ...(contact ? { contact } : {}),
+      },
+    ],
+  };
+}

package/content/schemas.ts

@@ -36,7 +36,8 @@ const siteIdentitySchema = z
     /** Town / city — appended to the brand in alt text. */
     location: z.string().default(''),
     /** What the site is for, which types its structured data for search engines
-     *  (lib/structured-data.mjs): Church, School, NGO, LocalBusiness or Organization. */
+     *  (lib/structured-data.mjs): School, NGO, LocalBusiness or Organization. A church is an
+     *  Organization (the parish), its churches its places. */
     kind: z.enum(['church', 'school', 'charity', 'business', 'organisation']).default('organisation'),
   })
   .default({});

package/integration.mjs

@@ -22,6 +22,9 @@
  * @param {boolean} [options.calendar=true] Inject the `/calendar` route.
  * @param {boolean} [options.blog=true] Inject the blog routes (`/posts`,
  *   `/posts/[...slug]`, `/posts/tag/[...tag]`).
+ * @param {boolean} [options.accessibility=true] Inject `/accessibility`, the accessibility statement
+ *   every footer links to (content/accessibility.ts). Skipped when the site has its own
+ *   `src/pages/accessibility.astro`.
  * @param {boolean} [options.cookiePolicy=true] Inject `/cookie-policy` (the page the cookie
  *   banner links to), generated from the blocks the site uses. Skipped automatically when
  *   the site has its own `src/pages/cookie-policy.astro`.
@@ -35,16 +38,28 @@
  *   `public/` win.
  * @param {boolean} [options.seo=true] Search signals (lib/seo.mjs): `/robots.txt`, and once
  *   `ferst-site.json` has a `siteUrl`, `/sitemap.xml`, a canonical address on every page,
- *   structured data and link previews, and (with the blog) `/posts/rss.xml`.
+ *   structured data and link previews, and (with the blog) `/posts/rss.xml`. Every build's
+ *   internal links to a page point at its own address (`/about-us/`), not at a redirect.
  *   A test copy (any branch but the production one) is marked noindex on every file. A
  *   site's own `public/robots.txt` or `public/sitemap.xml` wins.
  * @returns {import('astro').AstroIntegration}
  */
 import { copyFileSync, createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { deploymentBranch } from './bin/cms-config.mjs';
-import { seoContext, withNoindexHeader } from './lib/seo.mjs';
+import { linksToPageAddresses, seoContext, withNoindexHeader } from './lib/seo.mjs';
 import { writeSiteIcons } from './lib/site-icon.mjs';
 
+/** Every page of a build (its .html files, at any depth), as file URLs. */
+function htmlFiles(dir) {
+  return readdirSync(dir, { withFileTypes: true }).flatMap((entry) =>
+    entry.isDirectory()
+      ? htmlFiles(new URL(`${encodeURIComponent(entry.name)}/`, dir))
+      : entry.name.endsWith('.html')
+        ? [new URL(encodeURIComponent(entry.name), dir)]
+        : [],
+  );
+}
+
 /** The self-hosted fonts the engine's CSS requests (/fonts/*.woff2), shipped in the package. */
 const FONTS_DIR = new URL('./fonts/', import.meta.url);
 const FONT_URL = /^\/fonts\/([a-z0-9-]+\.woff2)(?:\?.*)?$/;
@@ -97,7 +112,7 @@ function readSiteMeta(root) {
 const hasPublicFile = (root, name) => Boolean(root) && existsSync(new URL(`public/${name}`, root));
 
 export default function ferst(options = {}) {
-  const { calendar = true, blog = true, cookiePolicy = true, notFound = true, icons = true, seo = true } = options;
+  const { calendar = true, blog = true, cookiePolicy = true, accessibility = true, notFound = true, icons = true, seo = true } = options;
   const fonts = ferstFonts().hooks;
   /** This build's search context, decided at setup and used again when the build is done. */
   let search = null;
@@ -150,6 +165,11 @@ export default function ferst(options = {}) {
             entrypoint: 'ferst-core/routes/cookie-policy.astro',
           });
         }
+        // Every footer links to the accessibility statement. The site's own page wins.
+        const ownStatement = config?.root && existsSync(new URL('src/pages/accessibility.astro', config.root));
+        if (accessibility && !ownStatement) {
+          injectRoute({ pattern: '/accessibility', entrypoint: 'ferst-core/routes/accessibility.astro' });
+        }
         // A missing address must answer 404, not the home page (Cloudflare Pages serves the
         // home page with a 200 when a build has no 404.html). The site's own page wins.
         const ownNotFound = config?.root && existsSync(new URL('src/pages/404.astro', config.root));
@@ -163,6 +183,7 @@ export default function ferst(options = {}) {
             define: {
               'import.meta.env.FERST_ROUTES_BLOG': JSON.stringify(blog),
               'import.meta.env.FERST_ROUTES_CALENDAR': JSON.stringify(calendar),
+              'import.meta.env.FERST_ROUTES_ACCESSIBILITY': JSON.stringify(accessibility),
             },
           },
         });
@@ -197,6 +218,21 @@ export default function ferst(options = {}) {
       'astro:server:setup': fonts['astro:server:setup'],
       'astro:build:done': async (ctx) => {
         await fonts['astro:build:done'](ctx);
+        // Internal links point at each page's one address, never at a redirect (lib/seo.mjs).
+        if (seo) {
+          const isPage = (path) => {
+            try {
+              return existsSync(new URL(`.${path}index.html`, ctx.dir));
+            } catch {
+              return false;
+            }
+          };
+          for (const file of htmlFiles(ctx.dir)) {
+            const html = readFileSync(file, 'utf8');
+            const linked = linksToPageAddresses(html, isPage);
+            if (linked !== html) writeFileSync(file, linked);
+          }
+        }
         // A test copy is noindex on every file: pages, and the PDFs and images beside them.
         if (search && !search.production) {
           const file = new URL('_headers', ctx.dir);

package/layouts/Base.astro

@@ -32,6 +32,7 @@ import { getCalloutSettings } from '../lib/callout';
 import { buildThemeStyle } from '../lib/themeTokens';
 import { canonicalUrl, previewTags } from '../lib/seo.mjs';
 import { structuredData } from '../lib/structured-data.mjs';
+import { titlesAbove } from '../lib/pages';
 
 interface Props {
   title: string;
@@ -101,9 +102,13 @@ const canonical = siteUrl && indexable ? canonicalUrl(siteUrl, path) : null;
 const noindex = !indexable || import.meta.env.FERST_SEO_PRODUCTION === false;
 
 // What the page tells search engines and link previews about the site (lib/structured-data,
-// lib/seo): from the site's own details, the same facts it shows visitors.
+// lib/seo): from the site's own details, the same facts it shows visitors. A nested page also
+// carries its breadcrumb trail, from the titles of the pages above it.
+const nested = path.split('/').filter(Boolean).length >= 2;
+const breadcrumbs = indexable && siteUrl && nested ? await titlesAbove(path) : {};
 const ld = indexable
   ? structuredData({
+      breadcrumbs,
       siteUrl: siteUrl || null,
       path,
       identity,
@@ -251,6 +256,8 @@ const hasFeed = Boolean(siteUrl) && import.meta.env.FERST_ROUTES_BLOG !== false;
     </script>
   </head>
   <body>
+    <!-- The first thing a keyboard reaches: straight past the header to the page. -->
+    <a class="skip-link" href="#main">Skip to content</a>
     <SiteHeader
       path={path}
       headerClass={headerClass}
@@ -262,7 +269,7 @@ const hasFeed = Boolean(siteUrl) && import.meta.env.FERST_ROUTES_BLOG !== false;
       cta={navigation.cta}
     />
 
-    <main class:list={['site-main', mainClass]} data-content-align={align}>
+    <main id="main" tabindex="-1" class:list={['site-main', mainClass]} data-content-align={align}>
       <slot name="hero" />
       <slot />
       {showSecondaryLogo && (secondaryLogoLight || secondaryLogoDark) && (
@@ -296,6 +303,14 @@ const hasFeed = Boolean(siteUrl) && import.meta.env.FERST_ROUTES_BLOG !== false;
          all flow from the same variables — no per-mode hex overrides here.
       */
       * { box-sizing: border-box; }
+      /* Skip link: hidden until a keyboard reaches it, then shown at the top left. */
+      .skip-link {
+        position: absolute; left: 0.75rem; top: -100%; z-index: 1000;
+        padding: 0.6rem 1rem; border-radius: 0.375rem;
+        background: var(--fg); color: var(--bg); font-weight: 600; text-decoration: none;
+      }
+      .skip-link:focus { top: 0.75rem; outline: 2px solid var(--bg); outline-offset: 2px; }
+      #main:focus { outline: none; }
       html, body { margin: 0; padding: 0; }
       html {
         height: 100%;

package/lib/contrast.ts

@@ -0,0 +1,146 @@
+/**
+ * Colour contrast for a theme (WCAG 2.2 AA): every text and brand colour the token builder
+ * (lib/themeTokens.ts) derives, measured against the ground it sits on, in light and dark
+ * mode. Theme Studio warns before saving a theme that fails; the tests hold the neutral
+ * defaults to it. Pure, so it's unit-testable.
+ *
+ * The derivations mirror themeTokens.ts: light mode mixes in sRGB (CSS `color-mix(in srgb)`),
+ * dark mode moves the same three colours in OKLCH. A colour that isn't hex (a CSS variable or
+ * function in an override) is skipped, never guessed.
+ */
+import type { ThemeSettings } from '../content/schemas';
+import { DARK_DEFAULTS, NEUTRAL_SOURCE } from './themeDefaults';
+
+type RGB = [number, number, number]; // 0..1, gamma-encoded sRGB
+
+function parseHex(hex: string): RGB | null {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(hex ?? '').trim());
+  if (!m) return null;
+  const h = m[1].length === 3 ? m[1].split('').map((c) => c + c).join('') : m[1];
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16) / 255) as RGB;
+}
+
+const toLinear = (c: number) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const toGamma = (c: number) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+const clamp01 = (n: number) => Math.min(1, Math.max(0, n));
+
+function luminance([r, g, b]: RGB): number {
+  return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+
+function ratio(a: RGB, b: RGB): number {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** WCAG contrast ratio between two hex colours (1 to 21). */
+export function contrastRatio(a: string, b: string): number {
+  const ra = parseHex(a);
+  const rb = parseHex(b);
+  if (!ra || !rb) throw new Error(`not a hex colour: ${!ra ? a : b}`);
+  return ratio(ra, rb);
+}
+
+const rgbHex = (c: RGB) => '#' + c.map((v) => Math.round(v * 255).toString(16).padStart(2, '0')).join('');
+
+/** CSS `color-mix(in srgb, a p, b)`. */
+const mix = (a: RGB, b: RGB, p: number): RGB => a.map((v, i) => v * p + b[i] * (1 - p)) as RGB;
+
+// OKLCH ⇄ sRGB (Björn Ottosson's OKLab).
+function toOklch([r, g, b]: RGB): [number, number, number] {
+  const [lr, lg, lb] = [r, g, b].map(toLinear);
+  const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+  const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+  const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  return [L, Math.hypot(A, B), Math.atan2(B, A)];
+}
+
+function fromOklch(L: number, C: number, h: number): RGB {
+  const A = C * Math.cos(h);
+  const B = C * Math.sin(h);
+  const l = (L + 0.3963377774 * A + 0.2158037573 * B) ** 3;
+  const m = (L - 0.1055613458 * A - 0.0638541728 * B) ** 3;
+  const s = (L - 0.0894841775 * A - 1.291485548 * B) ** 3;
+  const lin = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+  ];
+  return lin.map((c) => clamp01(toGamma(clamp01(c)))) as RGB;
+}
+
+export type ContrastPair = 'text' | 'secondary-text' | 'links' | 'button-text';
+
+export interface ContrastIssue {
+  mode: 'light' | 'dark';
+  pair: ContrastPair;
+  /** What a person sees fail, in plain words. */
+  label: string;
+  ratio: number;
+  needs: number;
+}
+
+const LABELS: Record<ContrastPair, string> = {
+  text: 'Text on the page background',
+  'secondary-text': 'Secondary text (dates, captions) on the page background',
+  links: 'Links and brand-coloured text on the page background',
+  'button-text': 'Text on brand-coloured buttons',
+};
+
+/**
+ * Text on brand fills in light mode (`--on-brand`): white, or the theme's ink when that reads
+ * better on the brand (a pale brand such as a gold). In dark mode it's the dark ground. Null
+ * when either colour isn't hex.
+ */
+export function onBrandColour(brand: string, ink: string): string | null {
+  const b = parseHex(brand);
+  const i = parseHex(ink);
+  if (!b || !i) return null;
+  return ratio(i, b) > ratio([1, 1, 1], b) ? ink.trim() : '#FFFFFF';
+}
+const AA = 4.5;
+
+/**
+ * Every pair in `theme` that falls below WCAG AA (4.5:1), light mode then dark. Empty when the
+ * theme passes.
+ */
+export function contrastIssues(theme: ThemeSettings): ContrastIssue[] {
+  const brand = parseHex(theme.brand || NEUTRAL_SOURCE.brand) ?? parseHex(NEUTRAL_SOURCE.brand)!;
+  const ink = parseHex(theme.ink || NEUTRAL_SOURCE.ink) ?? parseHex(NEUTRAL_SOURCE.ink)!;
+  const surface = parseHex(theme.surface || NEUTRAL_SOURCE.surface) ?? parseHex(NEUTRAL_SOURCE.surface)!;
+
+  // Dark mode: the same three colours moved in OKLCH (themeTokens.ts DARK_DERIVATION), or the
+  // site's own overrides when they're hex.
+  const depth = typeof theme.darkDepth === 'number' ? theme.darkDepth : DARK_DEFAULTS.depth;
+  const cap = typeof theme.darkChroma === 'number' ? theme.darkChroma : DARK_DEFAULTS.chroma;
+  const [, sc, sh] = toOklch(surface);
+  const [, ic, ih] = toOklch(ink);
+  const [, bc, bh] = toOklch(brand);
+  const ov = theme.darkOverrides ?? { ground: '', text: '', accent: '' };
+  const override = (v: string | undefined) => (v ? parseHex(v) : undefined);
+  const ground = override(ov.ground) ?? (ov.ground ? null : fromOklch(depth, Math.min(Math.max(sc * 3.5, 0), cap), sh));
+  const text = override(ov.text) ?? (ov.text ? null : fromOklch(0.94, ic * 0.3, ih));
+  const accent = override(ov.accent) ?? (ov.accent ? null : fromOklch(0.78, bc * 0.9, bh));
+  const muted = text ? (() => { const [l, c, h] = toOklch(text); return fromOklch(l - 0.2, c, h); })() : null;
+
+  const checks: Array<[ContrastIssue['mode'], ContrastPair, RGB | null, RGB | null]> = [
+    ['light', 'text', ink, surface],
+    ['light', 'secondary-text', mix(ink, surface, 0.72), surface],
+    ['light', 'links', brand, surface],
+    ['light', 'button-text', parseHex(onBrandColour(rgbHex(brand), rgbHex(ink)) ?? '#FFFFFF'), brand],
+    ['dark', 'text', text, ground],
+    ['dark', 'secondary-text', muted, ground],
+    ['dark', 'links', accent, ground],
+    ['dark', 'button-text', ground, accent],
+  ];
+  const issues: ContrastIssue[] = [];
+  for (const [mode, pair, fg, bg] of checks) {
+    if (!fg || !bg) continue; // a colour we can't read: skipped, never guessed
+    const r = ratio(fg, bg);
+    if (r < AA) issues.push({ mode, pair, label: LABELS[pair], ratio: Math.round(r * 100) / 100, needs: AA });
+  }
+  return issues;
+}

package/lib/pages.ts

@@ -22,6 +22,24 @@
  * can still hand-build a one-off page beside the JSON-driven ones.
  */
 import { getCollection } from 'astro:content';
+import { getPostsSettings } from './posts';
+
+/**
+ * The titles of the pages above a nested address, for its breadcrumb trail
+ * (lib/structured-data): each address above it that is a page of its own, and the news page
+ * above a post. Keyed by address (`/about-us/`).
+ */
+export async function titlesAbove(path: string): Promise<Record<string, string>> {
+  const segments = path.split('/').filter(Boolean);
+  const above = new Set(segments.slice(0, -1).map((_, i) => segments.slice(0, i + 1).join('/')));
+  const titles: Record<string, string> = {};
+  if (!above.size) return titles;
+  for (const entry of await getPageEntries()) {
+    if (above.has(entry.id) && entry.data.title) titles[`/${entry.id}/`] = entry.data.title;
+  }
+  if (above.has('posts') && !titles['/posts/']) titles['/posts/'] = (await getPostsSettings()).title;
+  return titles;
+}
 
 /** All non-draft `pages` entries. */
 export async function getPageEntries() {

package/lib/seo.mjs

@@ -129,6 +129,22 @@ export function withNoindexHeader(existing) {
   return `${current.replace(/\s*$/, '')}\n\n${NOINDEX_RULE}`;
 }
 
+/**
+ * Internal links pointed at each page's one address. A page's address is its trailing-slash
+ * form (`/about-us/`), and Cloudflare Pages answers the slash-less form with a redirect: a link
+ * to `/about-us` costs every visit and crawl a hop, and search engines list the slash-less form
+ * as a page with a redirect. So `href="/about-us"` gains its slash, keeping any `?query` or
+ * `#section`, when `isPage('/about-us/')` says that page exists. Files, other sites and
+ * addresses that are already right are left alone.
+ * @param {string} html
+ * @param {(path: string) => boolean} isPage  whether `/x/` is a page of the site
+ */
+export function linksToPageAddresses(html, isPage) {
+  return String(html).replace(/(\shref=")(\/(?!\/)[^"?#]*[^"/?#])([?#][^"]*)?"/g, (match, attr, path, rest = '') =>
+    isPage(`${path}/`) ? `${attr}${path}/${rest}"` : match,
+  );
+}
+
 /**
  * Link-preview tags (Open Graph and Twitter card) for one page: what a link shared on
  * Facebook, WhatsApp or LinkedIn shows. The picture is the page's own (its hero), else the

package/lib/structured-data.mjs

@@ -4,17 +4,18 @@
  * same facts the site shows visitors. Base renders it in each page's head once the site has
  * an address (its links must be absolute). Pure, so it's unit-testable.
  *
- * - The site is one entity (`#organization`), typed by its kind: a church with one place is
- *   a `Church` at that address; with several places (a parish of several churches) it's an
- *   `Organization` with each church as a `location`.
+ * - The site is one entity (`#organization`), typed by its kind. A church site is the parish,
+ *   an `Organization` with each of its churches as a `location` (schema.org's `Church` is a
+ *   building, and a building can't publish the website or write its posts); with one church,
+ *   the parish is at that church's address. Other kinds list several places as `location`s.
  * - The website names that entity as its publisher.
  * - A post is an `Article`, dated, published by the site.
  */
 import { canonicalUrl } from './seo.mjs';
 
-/** The schema.org type for each kind of site (`identity.kind`). */
-const TYPE = { church: 'Church', school: 'School', charity: 'NGO', business: 'LocalBusiness', organisation: 'Organization' };
-/** The type of each of a site's places, when it has several. */
+/** The schema.org type for each kind of site (`identity.kind`). A church site is an `Organization`. */
+const TYPE = { school: 'School', charity: 'NGO', business: 'LocalBusiness', organisation: 'Organization' };
+/** The type of each of a site's places, when it lists them. */
 const PLACE_TYPE = { church: 'Church', school: 'School', business: 'LocalBusiness' };
 
 /** Drop empty values (undefined, '', empty arrays and objects) so the data says only what's known. */
@@ -36,22 +37,45 @@ const isoDate = (d) => {
   return Number.isNaN(date.getTime()) ? undefined : date.toISOString().slice(0, 10);
 };
 
+/**
+ * The trail to a nested page (the site › each page above it › the page), or undefined for a
+ * top-level page. `titles` maps each address above the page to its page title; an address
+ * that isn't a page of its own is left out, and a trail with nothing between the site and
+ * the page isn't worth showing.
+ */
+function breadcrumbList(site, path, title, siteName, titles) {
+  const segments = String(path).split('/').filter(Boolean);
+  if (segments.length < 2 || !title) return undefined;
+  const items = [{ name: siteName, item: `${site}/` }];
+  for (let i = 1; i < segments.length; i++) {
+    const above = `/${segments.slice(0, i).join('/')}/`;
+    if (titles[above]) items.push({ name: titles[above], item: canonicalUrl(site, above) });
+  }
+  if (items.length < 2) return undefined;
+  items.push({ name: title, item: canonicalUrl(site, path) });
+  return {
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((it, i) => ({ '@type': 'ListItem', position: i + 1, name: it.name, item: it.item })),
+  };
+}
+
 /**
  * The JSON-LD for one page, or null when the site has no address.
  * @param {{ siteUrl: string | null, path: string, identity: any, contact: any, places?: any[], logo?: string,
- *   title?: string, description?: string, article?: { date: Date | string, image?: string } }} p
+ *   title?: string, description?: string, article?: { date: Date | string, image?: string },
+ *   breadcrumbs?: Record<string, string> }} p  `breadcrumbs`: the titles of the pages above this one.
  */
-export function structuredData({ siteUrl, path, identity, contact = {}, places = [], logo, title, description, article }) {
+export function structuredData({ siteUrl, path, identity, contact = {}, places = [], logo, title, description, article, breadcrumbs = {} }) {
   if (!siteUrl) return null;
   const site = siteUrl.replace(/\/+$/, '');
   const abs = (u) => (!u ? undefined : /^https?:\/\//i.test(u) ? u : `${site}${u.startsWith('/') ? '' : '/'}${u}`);
   const orgId = `${site}/#organization`;
   const kind = identity?.kind || 'organisation';
   const filled = places.filter((p) => p && (p.name || p.streetAddress || p.postalCode));
-  const several = filled.length > 1;
+  const listPlaces = filled.length > 1 || kind === 'church';
 
   const organisation = clean({
-    '@type': several && kind === 'church' ? 'Organization' : TYPE[kind] || 'Organization',
+    '@type': TYPE[kind] || 'Organization',
     '@id': orgId,
     name: identity?.siteTitle,
     alternateName: identity?.shortName && identity.shortName !== identity.siteTitle ? identity.shortName : undefined,
@@ -62,7 +86,7 @@ export function structuredData({ siteUrl, path, identity, contact = {}, places =
     email: contact.email,
     sameAs: [contact.facebookUrl],
     address: filled.length === 1 ? postal(filled[0]) : undefined,
-    location: several
+    location: listPlaces
       ? filled.map((p) => ({ '@type': PLACE_TYPE[kind] || 'Place', name: p.name, address: postal(p), hasMap: p.mapUrl }))
       : undefined,
   });
@@ -70,6 +94,8 @@ export function structuredData({ siteUrl, path, identity, contact = {}, places =
     organisation,
     { '@type': 'WebSite', '@id': `${site}/#website`, url: `${site}/`, name: identity?.siteTitle, inLanguage: 'en-GB', publisher: { '@id': orgId } },
   ];
+  const trail = breadcrumbList(site, path, title, identity?.siteTitle, breadcrumbs);
+  if (trail) graph.push(trail);
   if (article) {
     graph.push(
       clean({

package/lib/themeDefaults.ts

@@ -0,0 +1,15 @@
+/**
+ * The theme's fallbacks, shared by the token builder (themeTokens.ts) and the contrast check
+ * (contrast.ts) so both derive the same palette.
+ */
+
+/** The neutral source triple — used to fill any colour a client leaves blank so
+ *  the derivation is always self-contained (mirrors `styles/theme.css`). */
+export const NEUTRAL_SOURCE = {
+  brand: '#4F46E5',
+  ink: '#1F2937',
+  surface: '#F1F5F9',
+} as const;
+
+/** Defaults for the dark-formula knobs (also the CMS/schema defaults). */
+export const DARK_DEFAULTS = { depth: 0.21, chroma: 0.05 } as const;