create-website-build-kit 0.1.19 → 0.1.20

package/template/scripts/check-drift.mjs

@@ -35,9 +35,10 @@
  * CMS rows — and it says so rather than skipping them in silence.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { binarySourceFiles } from './lib/binary-files.mjs';
+import { literalContent } from './lib/literal-content.mjs';
 import { literalImages } from './lib/literal-images.mjs';
 
 const RESET = '\x1b[0m';
@@ -67,6 +68,57 @@ const read = (file) => {
   }
 };
 
+/*
+ * ⚠ FEATURE-DETECT BY WHAT THE FILE IS, NOT BY WHAT IT IS CALLED.
+ *
+ *   A delivered site has `scripts/check-contrast.mjs` that measures CSS tokens
+ *   against each other — a completely different job from measuring text over a
+ *   photograph. This file saw the name, reported the site as covered, and the
+ *   hero headline had in fact never been measured by anything. When it finally
+ *   was, it came back at 5.76:1 with about seven points of margin.
+ *
+ *   A row that says "present" because of a filename is worse than a row that
+ *   says "missing", because nobody re-checks a tick.
+ *
+ * The marker is a phrase from the script's own OUTPUT, which is what defines
+ * what it does. A same-named file that does something else says so, and that
+ * is a more useful finding than either "present" or "missing".
+ *
+ * ⚠ A MARKER IS VERSION-SENSITIVE, AND THE ROW SAYS SO RATHER THAN PRETENDING
+ *   OTHERWISE. A second delivered site has a bespoke `check-cms.mjs` written
+ *   for the same failure in its own words. It carries no marker, so it reads
+ *   as 'other' — which is honest: it is not this check, it may cover part of
+ *   the same ground, and the only way to know is to read it. A row that
+ *   guessed either way would be worse than one that says go and look.
+ */
+const KIT_SCRIPT = {
+  'check-cms.mjs': 'keys in the file the schema does not declare',
+  'check-contrast.mjs': 'text-over-photograph',
+};
+
+/**
+ * 'ok' — the check is here under some name
+ * 'other' — the canonical NAME is taken by a script that is not this check
+ * false — absent
+ *
+ * ⚠ SEARCH THE DIRECTORY, NOT THE FILENAME. A project that already had a
+ *   `check-contrast.mjs` doing something else installed this one as
+ *   `check-photo-contrast.mjs`, which is the right call and which a
+ *   name-based lookup would then report as missing. What the row is asking is
+ *   whether the CHECK is here, and only its output can answer that.
+ */
+const kitScript = (name) => {
+  const marker = KIT_SCRIPT[name];
+  let files = [];
+  try {
+    files = readdirSync('scripts').filter((f) => f.endsWith('.mjs'));
+  } catch {
+    return false;
+  }
+  if (files.some((f) => (read(join('scripts', f)) ?? '').includes(marker))) return 'ok';
+  return existsSync(join('scripts', name)) ? 'other' : false;
+};
+
 const findings = [];
 const add = (id, title, status, detail) => findings.push({ id, title, status, detail });
 
@@ -171,6 +223,21 @@ add(
     : 'no hardcoded image references in pages',
 );
 
+/* ── D5b · copy the client cannot reach ───────────────────────────────────── */
+
+const inline = literalContent();
+add(
+  'D5b',
+  'Page copy is fields, not literals',
+  inline.length ? 'drift' : 'ok',
+  inline.length
+    ? `${inline.length} block(s) declared inline in page frontmatter, holding ${inline.reduce((n, b) => n + b.strings, 0)} sentence(s) no editor can reach, e.g. ${inline
+        .slice(0, 2)
+        .map((b) => `${b.name}[${b.items}] in ${b.file}`)
+        .join(', ')} — this is what "required sections cannot be edited" looks like in the source`
+    : 'no inline content blocks in pages',
+);
+
 /* ── the CMS rows ─────────────────────────────────────────────────────────── */
 
 const CONFIG = '.pages.yml';
@@ -204,14 +271,44 @@ if (!existsSync(CONFIG)) {
     const flatten = (list) =>
       (list ?? []).flatMap((e) => (e?.type === 'group' ? flatten(e.items ?? e.content ?? []) : [e]));
     const textBoxes = [];
+    /*
+     * ⚠ RESOLVE `component:` FIRST, AND DO NOT MISTAKE A WRAPPER FOR A TEXT
+     *   BOX. This got both halves wrong on a live trilingual site and
+     *   reported 18 pickers as text boxes.
+     *
+     *   A picture is very often an OBJECT — `{ src, alt, isRender }` — reached
+     *   through a shared `component: image_field`. Reading `f.type` on the
+     *   wrapper finds `undefined`, so a field correctly named `image` was
+     *   reported as an unset text box; and never descending into the
+     *   component meant the `type: image` picker actually inside it was never
+     *   seen at all.
+     *
+     *   So: a field is a text box only if it is neither a picker itself nor a
+     *   wrapper holding one.
+     */
+    const componentOf = (f, seen = new Set()) => {
+      if (!f) return null;
+      if (!f.component) return f;
+      if (seen.has(f.component)) return null;
+      seen.add(f.component);
+      const base = (config.components ?? {})[f.component];
+      return base ? componentOf({ ...base, ...f, component: undefined }, seen) : null;
+    };
     const walkFields = (fields, entry, prefix = '') => {
       for (const f of fields ?? []) {
         if (!f?.name) continue;
         const path = prefix ? `${prefix}.${f.name}` : f.name;
-        if (/^(image|photo|poster|picture|cover|thumbnail)$/i.test(f.name) && f.type !== 'image') {
-          textBoxes.push(`${entry}.${path} (type: ${f.type ?? 'unset'})`);
+        const resolved = componentOf(f) ?? f;
+        const sub = Array.isArray(resolved.fields) ? resolved.fields : null;
+        const wrapsAPicker = (sub ?? []).some((c) => (componentOf(c) ?? c)?.type === 'image');
+        if (
+          /^(image|photo|poster|picture|cover|thumbnail)$/i.test(f.name) &&
+          resolved.type !== 'image' &&
+          !wrapsAPicker
+        ) {
+          textBoxes.push(`${entry}.${path} (type: ${resolved.type ?? 'unset'})`);
         }
-        if (Array.isArray(f.fields)) walkFields(f.fields, entry, path);
+        if (sub) walkFields(sub, entry, path);
       }
     };
     for (const entry of flatten(config.content)) walkFields(entry?.fields, entry?.name ?? '?');
@@ -226,14 +323,17 @@ if (!existsSync(CONFIG)) {
   }
 
   /* D4 and D8 have a shipped check. Drift means not having it. */
-  const hasCms = existsSync(join('scripts', 'check-cms.mjs'));
+  const cms = kitScript('check-cms.mjs');
+  const hasCms = cms === 'ok';
   add(
     'D4',
     'CMS cannot delete undeclared keys',
     hasCms ? 'ok' : 'drift',
     hasCms
       ? 'scripts/check-cms.mjs is present — run it'
-      : '⚠ no check-cms.mjs. A CMS rewrites the whole file from its schema, so any key it does not declare is DELETED on the client\'s first save. Five audited sites, five failures, two losing data',
+      : cms === 'other'
+        ? '⚠ scripts/check-cms.mjs exists and is NOT this check — a bespoke one, or an older vintage. It may well cover part of the same ground; read it rather than trusting this row either way'
+        : '⚠ no check-cms.mjs. A CMS rewrites the whole file from its schema, so any key it does not declare is DELETED on the client\'s first save. Five audited sites, five failures, two losing data',
   );
   add(
     'D8',
@@ -249,7 +349,8 @@ if (!existsSync(CONFIG)) {
 
 /* ── D7 · text over photographs ───────────────────────────────────────────── */
 
-const hasContrast = existsSync(join('scripts', 'check-contrast.mjs'));
+const contrast = kitScript('check-contrast.mjs');
+const hasContrast = contrast === 'ok';
 const declares = existsSync(join('src', 'data', 'contrast.json'));
 add(
   'D7',
@@ -259,7 +360,52 @@ add(
     ? declares
       ? 'regions declared and measured in build:production'
       : 'the check is present and this site declares no regions — correct if no text sits on a photograph'
-    : 'no check-contrast.mjs. axe and pa11y report a flat ~1.01:1 for text on an image, so a photograph that makes the navigation unreadable passes every gate',
+    : contrast === 'other'
+      ? '⚠ scripts/check-contrast.mjs exists and is NOT this check — on the site this was found, it measures CSS tokens against each other, while the hero text over a photograph had never been measured by anything'
+      : 'no check-contrast.mjs. axe and pa11y report a flat ~1.01:1 for text on an image, so a photograph that makes the navigation unreadable passes every gate',
+);
+
+/* ── D9 · the accessibility run measures both palettes ────────────────────── */
+
+/*
+ * ⚠ THE DANGEROUS STATE HERE IS NOT "MISSING", IT IS "PRESENT AND INERT".
+ *
+ *   Every site the kit has delivered runs pa11y through a script that forces
+ *   `prefers-color-scheme` with `--force-prefers-color-scheme`. That is not a
+ *   Chrome switch. Chrome ignores flags it does not know WITHOUT A WORD, so
+ *   both passes measure whatever scheme the machine is in — light twice on a CI
+ *   runner — while printing "clean in light and dark", and `a11y:evidence`
+ *   writes that sentence into a dated compliance pack.
+ *
+ *   So a site can carry the two-scheme runner, a green gate and an evidence
+ *   pack, and have never measured its dark palette. Found in the kit's own
+ *   template on 2026-09-20, by covering the a11y gate in `test:gates`.
+ */
+const schemeSources = (() => {
+  try {
+    return readdirSync('scripts')
+      .filter((f) => f.endsWith('.mjs'))
+      .map((f) => read(join('scripts', f)) ?? '')
+      .concat(read(join('scripts', 'lib', 'schemes.mjs')) ?? '');
+  } catch {
+    return [];
+  }
+})();
+const forcesScheme = schemeSources.some((src) => src.includes('--blink-settings=preferredColorScheme'));
+const deadSchemeFlag = schemeSources.some((src) => src.includes('--force-prefers-color-scheme'));
+const runsPa11y = schemeSources.some((src) => src.includes('pa11y'));
+
+add(
+  'D9',
+  'Accessibility run measures both colour schemes',
+  forcesScheme ? 'ok' : deadSchemeFlag || runsPa11y ? 'drift' : 'n/a',
+  forcesScheme
+    ? 'the scheme is forced, and the script verifies the forcing took effect before measuring'
+    : deadSchemeFlag
+      ? '⚠ --force-prefers-color-scheme is NOT a Chrome switch and is ignored in silence — this run measures one palette twice and reports it as two, including in any evidence pack. Copy scripts/lib/schemes.mjs and scripts/check-a11y.mjs from the current kit'
+      : runsPa11y
+        ? 'pa11y runs in whichever scheme the machine happens to be in — one palette measured, the other untested, and nothing says which'
+        : 'no pa11y runner here, so there is no two-scheme claim to be wrong',
 );
 
 /* ── report ───────────────────────────────────────────────────────────────── */

package/template/scripts/lib/literal-content.mjs

@@ -0,0 +1,233 @@
+/**
+ * Page copy declared inline in a page, which no editor can reach.
+ *
+ * ── THE FAILURE THIS FINDS ─────────────────────────────────────────────────
+ * A client-facing page whose content is a `const` array in the page's own
+ * frontmatter. It renders correctly, it types correctly, and there is no field
+ * for any of it anywhere in the CMS.
+ *
+ * Measured across seven delivered sites with a CMS: one page carried seven
+ * pieces of equipment with patient-facing copy — 58 sentence-length strings —
+ * another carried two "about us" bands with their photographs, and a third
+ * carried a PRICE. Every one of those sites had a working CMS the client was
+ * already using. **The failure is not a missing CMS; it is a CMS that stops
+ * short of the page.**
+ *
+ * ⚠ THIS IS A WARNING AND MUST STAY ONE. An inline list is sometimes right — a
+ *   legal notice, layout labels, a table nobody will reword. The rule is the
+ *   same as for images: a decision somebody made, not an oversight nobody
+ *   noticed.
+ *
+ * ── EXCLUDED BY SHAPE, NEVER BY NAME ───────────────────────────────────────
+ * ⚠ STRUCTURED DATA IS THE ENTIRE FALSE-POSITIVE CLASS. On the seven sites it
+ *   was a third of every hit, and on one site it was ALL of them — three
+ *   blocks, three schemas, zero real findings. A JSON-LD graph is developer
+ *   territory and belongs nowhere near a client.
+ *
+ * Two shapes exclude it, and neither is the variable's name:
+ *
+ *   1. `@type` / `@context` in the block — what makes a literal JSON-LD
+ *   2. the array's DIRECT elements are not object literals — which is how
+ *      `[breadcrumbSchema([…])]` gets out, since a helper call is not content
+ *
+ * A denylist of names tests for the spelling somebody used last time. Both of
+ * these were written as name tests first, and both let a schema through.
+ *
+ * ── WHY A SCANNER AND NOT A REGEX ──────────────────────────────────────────
+ * ⚠ THE REGEX VERSION MERGED ADJACENT BLOCKS. `const crumbs = [{ … }];` closes
+ *   on its own line, so a pattern ending at `\n];` ran straight past it and
+ *   swallowed the next declaration — reporting one item as sixteen, under the
+ *   wrong variable name, on a real site. Bracket depth has to be counted, and
+ *   counting it means knowing when you are inside a string.
+ *
+ * ── WHY A LIB AND NOT A SCRIPT ─────────────────────────────────────────────
+ * Two callers, as with `literal-images.mjs`: `check-cms.mjs` in a project that
+ * has a CMS, and `check-drift.mjs` in a delivered site that may have neither.
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+const DECL = /(?:^|\n)[ \t]*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*(?::[^=\n]*)?=\s*\[/g;
+
+/*
+ * A string long enough to be a sentence rather than a label. 25 characters was
+ * chosen against real trees: at 15 it returned CSS class lists and ARIA labels,
+ * and at 40 it missed "Starting at $10." — a price living in a page's source,
+ * which is the most expensive thing on this list to leave unreachable.
+ */
+const MIN_PROSE = 25;
+
+/** JSON-LD, by the keys that define it rather than by what it is called. */
+const STRUCTURED_DATA = /['"]@(type|context|id|graph)['"]/;
+
+/**
+ * Read a bracketed region starting at `open`, returning its inner text and the
+ * index just past the closing bracket. Strings and comments are skipped so a
+ * `]` inside either does not close the region early.
+ *
+ * Template literals are scanned to their closing backtick without interpreting
+ * `${…}`. A backtick inside a template expression would end it early; that has
+ * not occurred in any tree this has been run against, and the cost is one
+ * missed block rather than a wrong one.
+ */
+function readBracketed(src, open) {
+  const CLOSES = { '[': ']', '{': '}', '(': ')' };
+  const stack = [CLOSES[src[open]]];
+  let i = open + 1;
+
+  while (i < src.length) {
+    const c = src[i];
+
+    if (c === '/' && src[i + 1] === '/') {
+      i = src.indexOf('\n', i);
+      if (i === -1) return null;
+      continue;
+    }
+    if (c === '/' && src[i + 1] === '*') {
+      const end = src.indexOf('*/', i + 2);
+      if (end === -1) return null;
+      i = end + 2;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      i++;
+      while (i < src.length && src[i] !== c) i += src[i] === '\\' ? 2 : 1;
+      i++;
+      continue;
+    }
+    if (c === '[' || c === '{' || c === '(') {
+      stack.push(CLOSES[c]);
+      i++;
+      continue;
+    }
+    if (c === ']' || c === '}' || c === ')') {
+      if (c !== stack.pop()) return null; // unbalanced — not something to reason about
+      if (!stack.length) return { body: src.slice(open + 1, i), end: i + 1 };
+      i++;
+      continue;
+    }
+    i++;
+  }
+  return null;
+}
+
+/** The array's direct elements, split on commas at depth zero. */
+function directElements(body) {
+  const out = [];
+  let depth = 0;
+  let start = 0;
+  let i = 0;
+
+  while (i < body.length) {
+    const c = body[i];
+    if (c === "'" || c === '"' || c === '`') {
+      i++;
+      while (i < body.length && body[i] !== c) i += body[i] === '\\' ? 2 : 1;
+      i++;
+      continue;
+    }
+    if (c === '[' || c === '{' || c === '(') depth++;
+    else if (c === ']' || c === '}' || c === ')') depth--;
+    else if (c === ',' && depth === 0) {
+      out.push(body.slice(start, i));
+      start = i + 1;
+    }
+    i++;
+  }
+  out.push(body.slice(start));
+  return out.map((s) => s.trim()).filter(Boolean);
+}
+
+/** Every string literal in `body` at least `MIN_PROSE` characters long. */
+function proseStrings(body) {
+  const out = [];
+  let i = 0;
+  while (i < body.length) {
+    const c = body[i];
+    if (c === "'" || c === '"' || c === '`') {
+      const start = ++i;
+      while (i < body.length && body[i] !== c) i += body[i] === '\\' ? 2 : 1;
+      const value = body.slice(start, i);
+      /* ⚠ AN INTERPOLATED TEMPLATE IS NOT PROSE. `/problems-we-solve/#${p.id}`
+         is 26 characters of URL, and it was two of the strings that put a
+         search page's route table into the findings on a real site. */
+      if (value.length >= MIN_PROSE && !value.includes('${')) out.push(value);
+      i++;
+      continue;
+    }
+    i++;
+  }
+  return out;
+}
+
+const walk = (dir) =>
+  readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry);
+    return statSync(full).isDirectory() ? walk(full) : [full];
+  });
+
+/**
+ * Every inline content block under `root`.
+ *
+ * Returns `[{ file, name, items, strings, sample }]`, largest first, with paths
+ * in forward slashes so a Windows run reports what a Linux one does.
+ */
+export function literalContent(root = 'src/pages') {
+  const out = [];
+
+  let files;
+  try {
+    files = walk(root).filter((f) => f.endsWith('.astro'));
+  } catch {
+    return out; // no pages directory is not this check's problem
+  }
+
+  for (const file of files) {
+    const source = readFileSync(file, 'utf8');
+    const fm = /^---\n([\s\S]*?)\n---/.exec(source);
+    if (!fm) continue;
+
+    const frontmatter = fm[1];
+    const rel = relative(process.cwd(), file).split(sep).join('/');
+
+    DECL.lastIndex = 0;
+    for (const match of frontmatter.matchAll(DECL)) {
+      const open = match.index + match[0].length - 1;
+      const region = readBracketed(frontmatter, open);
+      if (!region) continue;
+
+      const { body } = region;
+      if (STRUCTURED_DATA.test(body)) continue;
+
+      /*
+       * Every direct element must be an object literal. `[helper([…])]` is a
+       * call, and a call is not content however much prose it encloses — that
+       * is what lets a breadcrumb schema built by a helper out.
+       *
+       * ⚠ REQUIRING *EVERY* ELEMENT ALSO DROPS A LIST THAT SPREADS IN SHARED
+       *   ITEMS, and that is deliberate. On a real site `[…, ...navSections,
+       *   …]` was a sitemap page assembled from navigation data — structure,
+       *   not copy. This under-reports rather than over-reports, which is the
+       *   only safe direction for a warning: one that cries wolf gets switched
+       *   off, and then its silence means "not looked at" rather than "fine".
+       */
+      const elements = directElements(body);
+      const objects = elements.filter((e) => e.startsWith('{'));
+      if (!objects.length || objects.length < elements.length) continue;
+
+      const strings = proseStrings(body);
+      if (strings.length < 2) continue;
+
+      out.push({
+        file: rel,
+        name: match[1],
+        items: objects.length,
+        strings: strings.length,
+        sample: strings[0].slice(0, 60),
+      });
+    }
+  }
+
+  return out.sort((a, b) => b.strings - a.strings || a.file.localeCompare(b.file));
+}

package/template/scripts/lib/literal-images.mjs

@@ -41,6 +41,29 @@ import { join, relative, sep } from 'node:path';
 const IMAGE_COMPONENT = /<(Img|Image|Picture|BandHeader|Hero)\b[^>]*?\bname=["']([^"']+)["']/gis;
 const IMAGE_ATTR = /\b(?:image|poster|photo|bgImage|backgroundImage)=["']([^"']+)["']/gis;
 
+/*
+ * ⚠ AN EXPRESSION IS NOT AUTOMATICALLY SAFE, AND ASSUMING SO MISSES THE
+ *   IDIOMATIC ASTRO CASE ENTIRELY.
+ *
+ *   The rule above — that `name={photo}` has no quotes and so "came from
+ *   somewhere else" — holds when the value comes from content. It does NOT
+ *   hold when "somewhere else" is a static import at the top of the same
+ *   file:
+ *
+ *     import heroBg from '@/assets/hero/forum-hero-silk-road.jpg';
+ *     <Image src={heroBg} />
+ *
+ *   That is the standard way to use Astro's image pipeline, the build
+ *   optimises it properly, and the client still cannot change the photograph.
+ *   Measured on a delivered site: EIGHT such imports across its pages while
+ *   this check reported zero.
+ *
+ *   Only counted when the identifier is used somewhere other than its own
+ *   import line — an unused import renders nothing and is a lint's problem.
+ */
+const IMAGE_IMPORT =
+  /^[ \t]*import\s+([A-Za-z_$][\w$]*)\s+from\s+["']([^"']+\.(?:jpe?g|png|webp|avif|gif))["']/gim;
+
 /** Values that are never a photograph a client would want to change. */
 const NOT_A_PHOTO = /^(#|https?:|data:|\/|\.\.?\/)|\.(svg|ico)$/i;
 
@@ -75,6 +98,18 @@ export function literalImages(root = 'src/pages') {
        contribute a finding, so strip both before matching. */
     const body = source.replace(/<!--[\s\S]*?-->/g, ' ');
 
+    IMAGE_IMPORT.lastIndex = 0;
+    for (const match of source.matchAll(IMAGE_IMPORT)) {
+      const [line, identifier, specifier] = match;
+      /* Used anywhere but its own import statement? */
+      const elsewhere = source.replace(line, ' ');
+      if (!new RegExp(`\\b${identifier}\\b`).test(elsewhere)) continue;
+      const key = `${rel}::${specifier}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      out.push({ file: rel, value: specifier });
+    }
+
     for (const [regex, group] of [
       [IMAGE_COMPONENT, 2],
       [IMAGE_ATTR, 1],

package/template/scripts/lib/schemes.mjs

@@ -16,32 +16,120 @@
  * A real AA failure, in the half nobody happened to test. Forcing the scheme
  * removes the luck.
  *
- * ── IT RUNS BOTH EVEN WITH NO DARK MODE ────────────────────────────────────
- * Deliberately. A fresh template ships no `prefers-color-scheme` rule at all,
- * so the two runs are identical and cost a few seconds. The day somebody adds
- * a dark palette is exactly the day the blind spot would otherwise open, and
- * a check you have to remember to switch on is a check that is off.
+ * ── ⚠ THE FIRST FIX FOR THAT DID NOTHING AT ALL ────────────────────────────
+ * It passed `--force-prefers-color-scheme=<scheme>` to Chrome. There is no such
+ * switch. Chrome ignores flags it does not know WITHOUT A WORD, so both runs
+ * measured whatever scheme the machine was in — light twice on a CI runner,
+ * dark twice on this laptop — while printing "clean in light and dark".
+ *
+ * Measured on Chrome 148, reading the media query the page itself sees:
+ *
+ *     no flag                                  dark    (this machine's setting)
+ *     --force-prefers-color-scheme=light       dark    ← ignored
+ *     --force-dark-mode                        dark    ← browser UI only
+ *     --blink-settings=preferredColorScheme=0  dark
+ *     --blink-settings=preferredColorScheme=1  light
+ *
+ * So the dark palette of every site built with this kit went unmeasured by the
+ * gate that reported measuring it, and the evidence pack said so in writing.
+ * A gate that always passes is worse than no gate; one that produces a dated
+ * conformance document is worse again.
+ *
+ * ── AND WHY THE REPLACEMENT IS CHECKED AT RUN TIME ─────────────────────────
+ * `preferredColorScheme` is a Blink setting taken by its ORDINAL — the mojom
+ * enum `PreferredColorScheme { kDark, kLight }`. An ordinal is not a name: if
+ * that enum is ever reordered or the setting renamed, the flag goes quiet in
+ * exactly the same way, and out-of-range values fall back to light rather than
+ * erroring (`=2` renders light).
+ *
+ * `assertForced()` therefore never trusts the flag. It launches Chrome, reads
+ * `prefers-color-scheme` from a page, and refuses when what came back is not
+ * what was asked for. That assertion is the load-bearing part of this file —
+ * the flag is only how it is currently achieved.
  */
 
 export const SCHEMES = ['light', 'dark'];
 
+/** mojom::blink::PreferredColorScheme — kDark = 0, kLight = 1. */
+const ORDINAL = { dark: 0, light: 1 };
+
+/** The Chrome arguments that pin `prefers-color-scheme` for a whole session. */
+export function schemeArgs(scheme) {
+  return [`--blink-settings=preferredColorScheme=${ORDINAL[scheme]}`];
+}
+
+/** Arguments with any previous scheme forcing — including the dead flag — removed. */
+function withoutScheme(args) {
+  return args.filter(
+    (a) =>
+      !a.startsWith('--force-prefers-color-scheme') &&
+      !a.startsWith('--blink-settings=preferredColorScheme'),
+  );
+}
+
 /**
  * A pa11y-ci config with the colour scheme pinned.
  *
- * `--force-prefers-color-scheme` makes Chrome answer the media query the same
- * way on every machine, which is the only reason a contrast result is
- * comparable between a laptop and a runner.
+ * `.pa11yci.json` stays the only place the URL list lives; the scheme is
+ * injected into a copy at run time, because two config files is two URL lists
+ * and one of them goes stale.
  */
 export function configForScheme(base, scheme) {
   const defaults = { ...(base.defaults ?? {}) };
   const launch = { ...(defaults.chromeLaunchConfig ?? {}) };
-  const args = (launch.args ?? []).filter((a) => !a.startsWith('--force-prefers-color-scheme'));
+  const args = withoutScheme(launch.args ?? []);
 
   return {
     ...base,
     defaults: {
       ...defaults,
-      chromeLaunchConfig: { ...launch, args: [...args, `--force-prefers-color-scheme=${scheme}`] },
+      chromeLaunchConfig: { ...launch, args: [...args, ...schemeArgs(scheme)] },
     },
   };
 }
+
+/**
+ * Prove Chrome actually answers `prefers-color-scheme` the way we asked, by
+ * launching it and reading the media query from a page.
+ *
+ * Returns null when the forcing works, and the reason it cannot be trusted
+ * otherwise — a string the caller prints before refusing to run. It is a
+ * refusal rather than a warning on purpose: a scheme that did not take means
+ * the run measures one palette twice and reports two.
+ */
+export async function assertForced(scheme) {
+  let puppeteer;
+  try {
+    puppeteer = (await import('puppeteer')).default;
+  } catch {
+    return (
+      'puppeteer is not installed, so the colour scheme cannot be verified.\n' +
+      '  It normally arrives with pa11y-ci: npm install'
+    );
+  }
+
+  let browser;
+  try {
+    browser = await puppeteer.launch({ args: ['--no-sandbox', ...schemeArgs(scheme)] });
+    const page = await browser.newPage();
+    /* A data: URL — the probe must not depend on the site being up, because
+       "the server is down" and "the flag stopped working" would then look the
+       same and the second one is the dangerous one. */
+    await page.goto('data:text/html,<!doctype html><title>scheme probe</title>');
+    const got = (await page.evaluate(() => matchMedia('(prefers-color-scheme: dark)').matches))
+      ? 'dark'
+      : 'light';
+    if (got !== scheme) {
+      return (
+        `asked Chrome for ${scheme} and the page reported ${got}.\n` +
+        `  ${schemeArgs(scheme).join(' ')} no longer forces the scheme, so a run now\n` +
+        `  measures this machine's palette twice and reports it as both.`
+      );
+    }
+    return null;
+  } catch (error) {
+    return `could not launch Chrome to verify the colour scheme: ${String(error).slice(0, 200)}`;
+  } finally {
+    await browser?.close();
+  }
+}