create-website-build-kit 0.1.15 → 0.1.17

package/index.mjs

@@ -108,9 +108,41 @@ if (!existsSync(join(dest, '.gitignore'))) {
 const pkgPath = join(dest, 'package.json');
 const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
 pkg.name = name.replace(/[^a-z0-9-]+/gi, '-').replace(/^-+|-+$/g, '').toLowerCase() || 'site';
-writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 
-console.log(`  ${GREEN}✓${RESET} template → ${dir}/`);
+/*
+ * ── WHICH KIT THIS SITE CAME FROM ──────────────────────────────────────────
+ * ⚠ THE TEMPLATE IS COPIED, NOT LINKED. Nothing the kit fixes afterwards ever
+ *   reaches a site already built — not a trap, not a gate, not a pipeline
+ *   change. A shipped site sat 19% behind on every image for weeks after AVIF
+ *   landed, and it surfaced only because somebody happened to read both trees
+ *   for an unrelated reason.
+ *
+ *   Without a stamp, "is this site current?" is archaeology: compare files by
+ *   eye against a repo whose history you have to guess at. With one it is
+ *   reading a line.
+ *
+ * The VERSION, not the commit: every release is tagged, so this resolves to a
+ * commit in one lookup, and embedding a commit would mean the packer's git
+ * state deciding what ships. It goes in package.json because that is the file
+ * a developer opens first and nobody deletes.
+ */
+const kitPkg = JSON.parse(
+  readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8'),
+);
+const stamp = { version: kitPkg.version, scaffolded: new Date().toISOString().slice(0, 10) };
+
+/* Placed straight after `version` rather than appended, so it is visible
+   without scrolling past the dependency list. */
+const ordered = {};
+for (const [key, value] of Object.entries(pkg)) {
+  ordered[key] = value;
+  if (key === 'version') ordered.websiteBuildKit = stamp;
+}
+if (!ordered.websiteBuildKit) ordered.websiteBuildKit = stamp;
+
+writeFileSync(pkgPath, `${JSON.stringify(ordered, null, 2)}\n`);
+
+console.log(`  ${GREEN}✓${RESET} template → ${dir}/${DIM}  (kit ${stamp.version})${RESET}`);
 
 const run = (cmd, args, label) => {
   const r = spawnSync(cmd, args, { cwd: dest, stdio: 'ignore', shell: process.platform === 'win32' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-website-build-kit",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Scaffold a production marketing site \u2014 Astro on Cloudflare Workers, with the gates, the migration playbook and the accessibility work already wired.",
   "keywords": [
     "astro",

package/template/CLAUDE.md

@@ -95,6 +95,27 @@ The rules whose failure looks like success — double-counted pageviews, a conve
 two pipes, a trigger on `sent=1` that catches almost nothing — are in `docs/analytics.md`.
 Read it before adding any tag.
 
+**`package.json` records which kit this site came from.** `websiteBuildKit.version` is stamped at
+scaffold time and is never updated afterwards, because ⚠ **the template is copied, not linked** —
+nothing the kit fixes later reaches this site. A trap closed upstream, a gate added, a pipeline
+improved: none of it arrives. One site sat 19% behind on every image for weeks after AVIF landed.
+Compare that version against the kit's releases when something here looks older than it should.
+
+**`npm run check:drift` says what this site is behind on.** The kit is copied, not linked, so
+nothing fixed upstream arrives here. It reports and changes nothing.
+
+**Text over a photograph is measured, not forbidden.** Declare the region in
+`src/data/contrast.json` — image, box, scrim strength, text colour — and `npm run check:contrast`
+composites it and fails production below 4.5:1. ⚠ **The danger is never the photograph, it is a
+weakened scrim.** On a real site two of three regions could not fail at any photograph; the one
+exposure was a scrim lightened from 92% to 62% so a client's photography could show its colour.
+This check is what makes weakening one safe.
+
+**Navigation may be CMS-managed; redirects may not.** `check:cms` resolves every internal path in
+CMS-managed data against `src/pages`, so a menu item pointing at a missing page fails the build
+rather than 404ing for a visitor. A redirect has no such check — a client toggling one off is
+silent traffic loss — so it stays in code.
+
 ⚠ **A CMS DELETES EVERY KEY ITS SCHEMA FORGOT.** It rewrites the whole file from the schema, so
 anything undeclared is absent from what it writes back — the client changes one field, saves, and
 the rest is gone, looking like an ordinary content commit. `npm run check:cms` refuses a

package/template/package.json

@@ -8,36 +8,38 @@
     "node": ">=22.12.0"
   },
   "scripts": {
-    "dev": "astro dev",
-    "check": "astro check",
     "a11y": "node scripts/check-a11y.mjs",
     "a11y:evidence": "node scripts/a11y-evidence.mjs",
-    "reflow": "node scripts/check-reflow.mjs",
-    "console": "node scripts/check-console.mjs",
-    "shots": "node scripts/shots.mjs",
-    "tells": "node scripts/tells.mjs",
-    "media": "node scripts/optimize-media.mjs",
+    "build": "astro build",
+    "build:production": "node scripts/build.mjs production",
+    "build:staging": "node scripts/build.mjs staging",
     "cards": "node scripts/og-cards.mjs",
-    "lastmod": "node scripts/lastmod.mjs",
-    "indexnow": "node scripts/indexnow.mjs",
-    "verify": "node scripts/verify.mjs",
+    "check": "astro check",
+    "check:cms": "node scripts/check-cms.mjs",
+    "check:contrast": "node scripts/check-contrast.mjs",
+    "check:copy": "node scripts/check-copy.mjs",
+    "check:drift": "node scripts/check-drift.mjs",
+    "check:form": "node scripts/check-form.mjs",
+    "check:secrets": "node scripts/check-secrets.mjs",
     "check:sitemap": "node scripts/check-sitemap.mjs",
-    "recon": "node scripts/recon.mjs",
-    "extract": "node scripts/extract.mjs",
+    "console": "node scripts/check-console.mjs",
+    "deploy:production": "npm run build:production && wrangler deploy && node scripts/check-secrets.mjs",
+    "deploy:staging": "npm run build:staging && wrangler deploy && node scripts/check-secrets.mjs",
+    "dev": "astro dev",
     "dns": "node scripts/dns-snapshot.mjs",
-    "seo": "npx --yes @nurkamol/seo-audit@1",
-    "redirects": "node scripts/redirects.mjs",
+    "extract": "node scripts/extract.mjs",
     "handover": "node scripts/md-to-pdf.mjs docs/handover.md docs/handover.pdf",
-    "build": "astro build",
-    "build:staging": "node scripts/build.mjs staging",
-    "build:production": "node scripts/build.mjs production",
+    "indexnow": "node scripts/indexnow.mjs",
+    "lastmod": "node scripts/lastmod.mjs",
+    "media": "node scripts/optimize-media.mjs",
     "preview": "wrangler dev",
-    "deploy:staging": "npm run build:staging && wrangler deploy && node scripts/check-secrets.mjs",
-    "deploy:production": "npm run build:production && wrangler deploy && node scripts/check-secrets.mjs",
-    "check:secrets": "node scripts/check-secrets.mjs",
-    "check:copy": "node scripts/check-copy.mjs",
-    "check:form": "node scripts/check-form.mjs",
-    "check:cms": "node scripts/check-cms.mjs"
+    "recon": "node scripts/recon.mjs",
+    "redirects": "node scripts/redirects.mjs",
+    "reflow": "node scripts/check-reflow.mjs",
+    "seo": "npx --yes @nurkamol/seo-audit@1",
+    "shots": "node scripts/shots.mjs",
+    "tells": "node scripts/tells.mjs",
+    "verify": "node scripts/verify.mjs"
   },
   "dependencies": {
     "@astrojs/cloudflare": "^14.1.7",

package/template/scripts/build.mjs

@@ -122,6 +122,10 @@ step(process.execPath, ['scripts/check-env.mjs']);
 
 if (env === 'production') {
   step(process.execPath, ['scripts/check-sitemap.mjs']);
+  /* Production only: it measures the GENERATED images, and a staging build is
+     often run before `npm run media` has caught up. A no-op until a project
+     declares regions — the template has no design and therefore none. */
+  step(process.execPath, ['scripts/check-contrast.mjs']);
 }
 
 /* A sanity line, so the log says which environment actually ran rather than

package/template/scripts/check-cms.mjs

@@ -41,6 +41,8 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { parse } from 'yaml';
+import { literalImages } from './lib/literal-images.mjs';
+import { routeExists, routesFromPages } from './lib/routes.mjs';
 
 const RESET = '\x1b[0m';
 const RED = '\x1b[31m';
@@ -321,6 +323,83 @@ for (const entry of entries) {
   }
 }
 
+/* ── internal links a client can type ────────────────────────────────────── */
+
+/*
+ * ⚠ THIS IS WHAT MAKES NAVIGATION SAFE TO PUT IN A CMS.
+ *
+ *   `stacks.md` kept nav out of the CMS for a good reason — a bad value should
+ *   fail the build, not publish. A typo'd path gives a menu item leading to a
+ *   404: the page renders, nothing errors, and only a visitor finds it.
+ *
+ *   But navigation was missing from all five audited sites, so every client had
+ *   to ask for a menu change. That is not a rule being respected, it is a gap
+ *   the rule creates. The answer is not to forbid the field, it is to verify
+ *   it — before the build, while somebody is still looking at the config.
+ *
+ * ⚠ A DYNAMIC ROUTE IS A PATTERN. `[slug].astro` serves every legal page, so
+ *   treating routes as literal strings would report most of a site as broken.
+ *   `routesFromPages` returns patterns for those and `routeExists` matches them.
+ *
+ * External links, `mailto:`, `tel:` and bare anchors are somebody else's
+ * problem — `verify` checks those against the deployed site, where they can
+ * actually be resolved.
+ */
+const LINKISH = /(^|\.)(href|url|link|to|target|destination)$/i;
+const routes = routesFromPages();
+const brokenLinks = [];
+
+if (routes.static.size || routes.dynamic.length) {
+  for (const entry of entries) {
+    const documents = [];
+    if (entry?.type === 'collection' && existsSync(entry.path ?? '')) {
+      const walk = (d) =>
+        readdirSync(d).flatMap((e) => {
+          const full = join(d, e);
+          return statSync(full).isDirectory() ? walk(full) : [full];
+        });
+      for (const file of walk(entry.path).filter((f) => /\.mdx?$/.test(f))) {
+        const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(file, 'utf8'));
+        if (!m) continue;
+        try {
+          documents.push({ where: rel(file), data: parse(m[1]) ?? {} });
+        } catch {
+          /* reported elsewhere */
+        }
+      }
+    } else if (/\.json$/.test(entry?.path ?? '') && existsSync(entry.path)) {
+      try {
+        documents.push({ where: rel(entry.path), data: JSON.parse(readFileSync(entry.path, 'utf8')) });
+      } catch {
+        /* reported above */
+      }
+    }
+
+    for (const doc of documents) {
+      const visit = (value, path) => {
+        if (Array.isArray(value)) return value.forEach((v) => visit(v, path));
+        if (value && typeof value === 'object') {
+          for (const [k, v] of Object.entries(value)) visit(v, path ? `${path}.${k}` : k);
+          return;
+        }
+        if (typeof value !== 'string' || !LINKISH.test(path)) return;
+        if (!value.startsWith('/')) return; // external, mailto:, tel:, #anchor
+        if (routeExists(value, routes)) return;
+        brokenLinks.push({ where: doc.where, path, value });
+      };
+      visit(doc.data, '');
+    }
+  }
+}
+
+if (brokenLinks.length) {
+  problems.push({
+    label: 'internal links',
+    why: `${brokenLinks.length} point at a page this site does not serve`,
+    links: brokenLinks,
+  });
+}
+
 /* ── coverage, and secrets ───────────────────────────────────────────────── */
 
 /*
@@ -375,6 +454,70 @@ if (uncovered.length) {
   );
 }
 
+/*
+ * ⚠ A CLIENT GUIDE DOES NOT GO OUT OF DATE GRACEFULLY. IT STARTS LYING.
+ *
+ *   `docs/handover.md` is the only document written for the client. One
+ *   project's was written when the CMS had six entries; it had thirteen by the
+ *   time anyone looked, and nothing noticed. That is the mild half.
+ *
+ *   The serious half is that it still said the address and phone number "are
+ *   not editable" — which stopped being true the day those moved into the CMS.
+ *   A client reading that either asks you to do something she can do herself,
+ *   or assumes her address updates everywhere on its own because the document
+ *   told her the site owned it.
+ *
+ *   Only the client ever finds out. So: every entry the CMS shows should be
+ *   named in the guide. A warning, not a failure — what the guide says is a
+ *   judgement, and a section deliberately left out is a decision.
+ */
+const GUIDE = join('docs', 'handover.md');
+
+if (existsSync(GUIDE) && entries.length) {
+  const guide = readFileSync(GUIDE, 'utf8').toLowerCase();
+  const unmentioned = entries
+    .map((e) => e?.label ?? e?.name)
+    .filter(Boolean)
+    .filter((label) => !guide.includes(String(label).toLowerCase()));
+  if (unmentioned.length) {
+    warnings.push(
+      `${unmentioned.length} CMS section(s) the client guide never mentions: ` +
+        `${unmentioned.join(', ')}.\n` +
+        `      ${GUIDE} is the only document written for the client. A section it omits is one ` +
+        `they will not know they can edit — and a claim it makes that the CMS has since ` +
+        `contradicted is worse, because they will believe it.`,
+    );
+  }
+}
+
+/*
+ * ⚠ A SENTENCE SAYING "PHOTOGRAPHS ARE CHOSEN IN CODE" COVERS THE FIELDS THAT
+ *   EXIST AND EXCUSES THE ONES THAT DO NOT.
+ *
+ *   On a real build that left a header band, four class tiles and a gift-card
+ *   picture as string literals in `.astro`, while the config claimed images
+ *   were deliberately developer-controlled. The client opened the page, saw a
+ *   photograph, and had no way to change it. Nothing was broken; the only
+ *   symptom was someone looking for a field that was never there.
+ *
+ *   A warning, because a fixed image IS sometimes right — a logo, an
+ *   illustration that belongs to the layout. The rule is that it must be a
+ *   decision, not an oversight.
+ */
+const literals = literalImages();
+if (literals.length) {
+  warnings.push(
+    `${literals.length} image(s) hardcoded in pages, which the CMS cannot change:\n` +
+      literals
+        .slice(0, 10)
+        .map((l) => `      ${l.file}  ${l.value}`)
+        .join('\n') +
+      (literals.length > 10 ? `\n      …and ${literals.length - 10} more` : '') +
+      `\n      Each is a field the client does not have. Either give it one, or write down ` +
+      `why it is fixed — "chosen in code" stops being true the moment the next one is added.`,
+  );
+}
+
 /*
  * ⚠ A SECRET IN A CMS IS A SECRET THE CLIENT CAN READ AND CHANGE. Analytics
  *   IDs, tokens and keys are technical configuration: their failure mode is
@@ -418,6 +561,16 @@ for (const p of problems) {
         `      the client will never touch — or move them out of a CMS-managed file.${RESET}`,
     );
   }
+  if (p.links) {
+    for (const l of p.links.slice(0, 8)) {
+      console.error(`      ${DIM}${l.where}  ${l.path} = ${JSON.stringify(l.value)}${RESET}`);
+    }
+    console.error(
+      `      ${DIM}A menu item pointing at a missing page renders perfectly and 404s only\n` +
+        `      for a visitor. This is what lets navigation be a CMS field at all: the\n` +
+        `      value is checked before the build rather than trusted.${RESET}`,
+    );
+  }
   if (p.picker) {
     console.error(
       `      ${DIM}The site still renders this: <Img> accepts a manifest key as well as a\n` +

package/template/scripts/check-contrast.mjs

@@ -0,0 +1,218 @@
+/**
+ * Contrast of text sitting on a photograph, measured off the real pixels.
+ *
+ *   npm run check:contrast
+ *
+ * Runs in `build:production`. A failure is a red build, so the last good deploy
+ * stays live — which is the correct outcome for a photograph that has made the
+ * navigation unreadable.
+ *
+ * ── THE GAP THIS FILLS ─────────────────────────────────────────────────────
+ * ⚠ NO ACCESSIBILITY RUNNER CAN SEE THIS. axe and pa11y report a flat ~1.01:1
+ *   for every text-over-image case, because neither composites a transparent
+ *   element over the pixels behind it. So the failure is invisible to `a11y`,
+ *   invisible to the build, and invisible to the client who swapped the photo.
+ *
+ * That gap is what forces a bad choice: either let a client change a header
+ * photograph and risk breaking the nav, or refuse to let them choose at all.
+ * It is a false choice. Let them choose, and measure what they chose.
+ *
+ * ── WHAT MEASURING IT ACTUALLY TAUGHT ──────────────────────────────────────
+ * Fed a deliberately hostile frame, on a real site with three such regions:
+ *
+ *   band header, 82% ink scrim    near-white photo →  9.66:1   cannot fail
+ *   tile label,  72% ink scrim    near-white photo →  6.76:1   cannot fail
+ *   script text, 62% cream scrim  near-black photo →  2.86:1   ✗ rejected
+ *
+ * ⚠ TWO OF THE THREE COULD NOT FAIL. Those scrims were strong enough that no
+ *   photograph gets through them — which is what "guarantee the ground instead
+ *   of hoping for it" is for. The pattern had already solved the problem and
+ *   everyone was still behaving as though it had not.
+ *
+ *   The one real exposure was a scrim that had been LIGHTENED, from 92% to 62%,
+ *   so a client's new photography could show its colour. **The danger is never
+ *   the photograph. It is a weakened scrim** — and this check is what makes
+ *   weakening one safe to do.
+ *
+ * ── WHY THE REGIONS ARE DECLARED AND NOT DETECTED ──────────────────────────
+ * A region is a box, a scrim strength and a text colour. All three belong to a
+ * project's design, and ⚠ **this template has no design** — so the kit ships
+ * the measurement and the declaration format, never the regions. With none
+ * declared this exits 0 and says so, rather than printing a tick it has not
+ * earned.
+ *
+ * Declare them in `src/data/contrast.json`:
+ *
+ *   {
+ *     "regions": [
+ *       {
+ *         "label": "header band",
+ *         "image": "photos/hero-band",
+ *         "box":   { "x": 0, "y": 0, "w": 1, "h": 0.4 },
+ *         "scrim": { "colour": "#1a0d05", "from": 0.82, "to": 0.82 },
+ *         "text":  "#ffffff"
+ *       }
+ *     ]
+ *   }
+ *
+ * `box` is fractions of the image. `scrim.from`/`to` are alpha at the top and
+ * bottom of the box, so a gradient is expressible. `image` is a manifest key.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import sharp from 'sharp';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const DIM = '\x1b[2m';
+
+const DECL = 'src/data/contrast.json';
+const MANIFEST = 'src/data/image-manifest.json';
+const AA = 4.5;
+
+if (!existsSync(DECL)) {
+  console.log(`${DIM}·${RESET} no ${DECL} — no text-over-photograph regions declared`);
+  process.exit(0);
+}
+
+const fail = (msg) => {
+  console.error(`\n${RED}✗ ${msg}${RESET}\n`);
+  process.exit(1);
+};
+
+let regions;
+try {
+  regions = JSON.parse(readFileSync(DECL, 'utf8')).regions;
+} catch (err) {
+  fail(`${DECL} is not valid JSON — ${err.message}`);
+}
+if (!Array.isArray(regions) || !regions.length) {
+  fail(`${DECL} declares no regions. Delete the file, or describe what to measure.`);
+}
+
+const manifest = existsSync(MANIFEST) ? JSON.parse(readFileSync(MANIFEST, 'utf8')) : {};
+
+const hex = (value) => {
+  const m = /^#?([0-9a-f]{6})$/i.exec(String(value ?? ''));
+  if (!m) return null;
+  const n = parseInt(m[1], 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+};
+
+/* sRGB relative luminance, per WCAG. */
+const lum = ([r, g, b]) => {
+  const c = [r, g, b].map((v) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+};
+
+const ratio = (a, b) => {
+  const [x, y] = [lum(a), lum(b)].sort((p, q) => q - p);
+  return (x + 0.05) / (y + 0.05);
+};
+
+/** Source-over: the scrim colour at `alpha` laid on the pixel beneath. */
+const over = (pixel, scrim, alpha) => pixel.map((p, i) => scrim[i] * alpha + p * (1 - alpha));
+
+const problems = [];
+const measured = [];
+
+for (const region of regions) {
+  const label = region?.label ?? '(unlabelled)';
+  const text = hex(region?.text);
+  const scrimColour = hex(region?.scrim?.colour);
+  if (!text) fail(`region "${label}": \`text\` must be a #rrggbb colour`);
+  if (!scrimColour) fail(`region "${label}": \`scrim.colour\` must be a #rrggbb colour`);
+
+  const from = Number(region?.scrim?.from ?? 0);
+  const to = Number(region?.scrim?.to ?? from);
+  const min = Number(region?.min ?? AA);
+
+  /*
+   * ⚠ A MANIFEST KEY, NOT A PICKER PATH — and deliberately not normalised here.
+   *   `toImageKey` lives in `src/lib/image-key.ts`, which a plain .mjs script
+   *   cannot import; copying it in would leave two implementations of the same
+   *   mapping free to drift, which is the failure this whole round was about.
+   *   This file is written by a developer, not by a CMS, so it can simply ask
+   *   for the key and say so when it gets a path.
+   */
+  const key = String(region?.image ?? '');
+  const entry = manifest[key];
+  if (!entry) {
+    fail(
+      key.startsWith('/img/')
+        ? `region "${label}": \`image\` is "${key}", which is a media-picker path.\n` +
+          `  Declare the manifest key instead — the part between /img/ and the -width suffix.`
+        : `region "${label}": no manifest entry for "${key}".\n` +
+          `  Run \`npm run media\` first — this measures the generated image, not the source.`,
+    );
+  }
+
+  /* The widest generated variant: the most pixels, so the least sampling luck. */
+  const widest = (entry.widths ?? []).length ? Math.max(...entry.widths) : null;
+  const file = widest ? `public/img/${key}-${widest}.webp` : null;
+  if (!file || !existsSync(file)) {
+    fail(`region "${label}": ${file ?? 'no variant'} is missing. Run \`npm run media\`.`);
+  }
+
+  const box = region?.box ?? { x: 0, y: 0, w: 1, h: 1 };
+  const image = sharp(file);
+  const meta = await image.metadata();
+  const left = Math.max(0, Math.round((box.x ?? 0) * meta.width));
+  const top = Math.max(0, Math.round((box.y ?? 0) * meta.height));
+  const width = Math.max(1, Math.min(meta.width - left, Math.round((box.w ?? 1) * meta.width)));
+  const height = Math.max(1, Math.min(meta.height - top, Math.round((box.h ?? 1) * meta.height)));
+
+  const { data } = await image
+    .extract({ left, top, width, height })
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+
+  /*
+   * ⚠ PER-CHANNEL EXTREMES, NOT THE AVERAGE. An average hides exactly the
+   *   highlight that breaks a word — the brightest pixel under the type is what
+   *   a reader's eye lands on. Both extremes are taken because light text fails
+   *   against a bright pixel and dark text fails against a dark one, and a
+   *   check that only knows one of those is half a check.
+   */
+  const brightest = [0, 0, 0];
+  const darkest = [255, 255, 255];
+  for (let i = 0; i < data.length; i += 3) {
+    const y = Math.floor(i / 3 / width);
+    const alpha = from + (to - from) * (height > 1 ? y / (height - 1) : 0);
+    const composited = over([data[i], data[i + 1], data[i + 2]], scrimColour, alpha);
+    for (let c = 0; c < 3; c++) {
+      if (composited[c] > brightest[c]) brightest[c] = composited[c];
+      if (composited[c] < darkest[c]) darkest[c] = composited[c];
+    }
+  }
+
+  const worst = Math.min(ratio(text, brightest), ratio(text, darkest));
+  measured.push({ label, worst, min });
+  if (worst < min) problems.push({ label, worst, min, image: region?.image });
+}
+
+for (const m of measured) {
+  const mark = m.worst < m.min ? `${RED}✗${RESET}` : `${GREEN}✓${RESET}`;
+  console.log(`  ${mark} ${m.label}  ${m.worst.toFixed(2)}:1  ${DIM}(needs ${m.min}:1)${RESET}`);
+}
+
+if (!problems.length) {
+  console.log(`${GREEN}✓${RESET} ${measured.length} text-over-photograph region(s) legible`);
+  process.exit(0);
+}
+
+console.error(`\n${RED}✗ ${problems.length} region(s) below the contrast floor${RESET}\n`);
+for (const p of problems) {
+  console.error(`    ${p.label}  ${p.worst.toFixed(2)}:1  needs ${p.min}:1  ${DIM}${p.image}${RESET}`);
+}
+console.error(
+  `\n  ${DIM}The photograph is rarely the problem. Check whether this region's scrim has\n` +
+    `  been lightened — that is what turns a guarantee into a hope. Strengthen the\n` +
+    `  scrim, or choose a photograph without a bright area under the type.${RESET}\n`,
+);
+process.exit(1);

package/template/scripts/check-drift.mjs

@@ -0,0 +1,291 @@
+/**
+ * What a delivered site is missing, because the kit moved on without it.
+ *
+ *   npm run check:drift
+ *   node scripts/check-drift.mjs --json     # for CI, or for many sites at once
+ *
+ * ── WHY THIS IS DIFFERENT FROM EVERY OTHER CHECK HERE ──────────────────────
+ * ⚠ THE TEMPLATE IS COPIED, NOT LINKED. Nothing the kit fixes afterwards
+ *   reaches a site already built. Every other gate in this directory protects
+ *   the next project; this one is the only thing that speaks to the ones
+ *   already shipped.
+ *
+ * The cost is not hypothetical. A delivered site served every image about 19%
+ * larger than intended for weeks after the pipeline gained AVIF, and it
+ * surfaced only because somebody happened to read two trees side by side for an
+ * unrelated reason. The same site still carried a source file with a literal
+ * NUL — invisible to `git diff`, to `grep`, and to the provenance sweep.
+ *
+ * ── IT REPORTS. IT NEVER CHANGES ANYTHING. ─────────────────────────────────
+ * Exit 0 whatever it finds, unless it cannot run at all. A remediation tool
+ * that edits before you have read its findings is not a tool, it is a surprise.
+ *
+ * ── WHY IT DOES NOT RE-IMPLEMENT THE OTHER CHECKS ──────────────────────────
+ * Where the current kit ships a check, drift means *not having that check*, so
+ * this looks for the file rather than repeating what it does. Copying the
+ * logic in would leave two implementations free to disagree — which is exactly
+ * the failure this whole round of work was about.
+ *
+ * Where no check exists, it analyses: AVIF, binary source files, hardcoded
+ * images, a pipeline that discards silently.
+ *
+ * ── RUNNING IT IN A SITE THAT PREDATES IT ──────────────────────────────────
+ * Copy `scripts/check-drift.mjs` and `scripts/lib/` in, then run it. It reads
+ * only; nothing it needs has to be installed first, except `yaml` for the two
+ * CMS rows — and it says so rather than skipping them in silence.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { binarySourceFiles } from './lib/binary-files.mjs';
+import { literalImages } from './lib/literal-images.mjs';
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+const json = process.argv.includes('--json');
+
+/* `yaml` arrives with Astro, but a site old enough to drift may not resolve it.
+   Two rows depend on it, and they say so rather than reporting a clean result
+   they never computed. */
+let parseYaml = null;
+try {
+  ({ parse: parseYaml } = await import('yaml'));
+} catch {
+  /* handled per row */
+}
+
+const read = (file) => {
+  try {
+    return readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+const findings = [];
+const add = (id, title, status, detail) => findings.push({ id, title, status, detail });
+
+/* ── which kit, if it says ────────────────────────────────────────────────── */
+
+const pkg_ = read('package.json');
+const manifest = pkg_ ? JSON.parse(pkg_) : {};
+const stamp = manifest.websiteBuildKit ?? null;
+
+/*
+ * ⚠ THE TEMPLATE ITSELF IS NOT A DRIFTED SITE. It is the source, and it never
+ *   carries a stamp — the scaffolder writes one into the COPY. Reporting the
+ *   kit's own template as behind the kit is the kind of false positive that
+ *   teaches people to ignore the whole report, and this one appeared the first
+ *   time this script was run.
+ */
+const isTemplate = manifest.name === 'site-name';
+
+add(
+  'K',
+  'Kit version recorded',
+  isTemplate ? 'n/a' : stamp ? 'ok' : 'drift',
+  isTemplate
+    ? 'this is the kit template itself, which is stamped when it is scaffolded'
+    : stamp
+      ? `${stamp.version}, scaffolded ${stamp.scaffolded ?? 'unknown'}`
+      : 'no stamp — this site predates the version stamp, so which kit it came from has to be worked out by hand',
+);
+
+/* ── D1 · a modern output format ──────────────────────────────────────────── */
+
+const media = read('scripts/optimize-media.mjs');
+if (!media) {
+  add('D1', 'Modern image format', 'n/a', 'no scripts/optimize-media.mjs — this site has no kit media pipeline');
+} else {
+  /* ⚠ THE DECLARATION, NOT ANY MENTION OF THE WORD. A pipeline with AVIF turned
+     OFF still documents how to turn it on — `Set FORMATS to ['webp'] to turn
+     AVIF off` — so a bare search for the string reports the opposite of the
+     truth on exactly the sites this exists for. */
+  const formats = /const\s+FORMATS\s*=\s*\[([^\]]*)\]/.exec(media);
+  const avif = formats ? /['"]avif['"]/.test(formats[1]) : false;
+  add(
+    'D1',
+    'Modern image format',
+    avif ? 'ok' : 'drift',
+    avif
+      ? 'the pipeline emits AVIF alongside WebP'
+      : 'WebP only. AVIF is about 26% smaller at matched quality — measured, but MEASURE IT HERE before quoting a number, because the saving depends on the photography',
+  );
+
+  /* ── D6 · a pipeline that discards files in silence ─────────────────────── */
+  const reports = /produced no image/.test(media);
+  const catches = /failed to process/.test(media);
+  add(
+    'D6',
+    'Pipeline reports what it dropped',
+    reports && catches ? 'ok' : 'drift',
+    reports && catches
+      ? 'names skipped files, and one bad file no longer aborts the run'
+      : `${!reports ? 'a non-raster file is dropped with no output and no warning' : ''}${!reports && !catches ? '; ' : ''}${!catches ? 'one corrupt file aborts the run midway, leaving the manifest describing a state that no longer exists' : ''}`,
+  );
+
+  const heic = /heic/i.test(media);
+  add(
+    'D1b',
+    'HEIC accepted',
+    heic ? 'ok' : 'drift',
+    heic
+      ? 'iPhone photographs convert'
+      : 'a .heic is discarded with no output and no manifest entry, while the installed libvips reads it fine',
+  );
+}
+
+/* ── D2 · source files that defeat review ─────────────────────────────────── */
+
+try {
+  const { tracked, binary } = binarySourceFiles();
+  add(
+    'D2',
+    'Source files readable as text',
+    binary.length ? 'drift' : 'ok',
+    binary.length
+      ? `${binary.length} tracked file(s) git calls BINARY — invisible to git diff, to grep, and to the provenance sweep: ${binary.join(', ')}`
+      : `${tracked.length} tracked source file(s), all readable`,
+  );
+} catch (err) {
+  add('D2', 'Source files readable as text', 'n/a', `git unavailable — ${err.message}`);
+}
+
+/* ── D5 · images the client cannot change ─────────────────────────────────── */
+
+const literals = literalImages();
+add(
+  'D5',
+  'Images are fields, not literals',
+  literals.length ? 'drift' : 'ok',
+  literals.length
+    ? `${literals.length} hardcoded in pages, e.g. ${literals
+        .slice(0, 3)
+        .map((l) => `${l.value} (${l.file})`)
+        .join(', ')} — each is an image the client can see and cannot change`
+    : 'no hardcoded image references in pages',
+);
+
+/* ── the CMS rows ─────────────────────────────────────────────────────────── */
+
+const CONFIG = '.pages.yml';
+if (!existsSync(CONFIG)) {
+  for (const [id, title] of [
+    ['D3', 'CMS image fields are pickers'],
+    ['D4', 'CMS cannot delete undeclared keys'],
+    ['D8', 'Client guide matches the CMS'],
+  ]) {
+    add(id, title, 'n/a', 'no .pages.yml — this site has no CMS');
+  }
+} else if (!parseYaml) {
+  for (const [id, title] of [
+    ['D3', 'CMS image fields are pickers'],
+    ['D4', 'CMS cannot delete undeclared keys'],
+    ['D8', 'Client guide matches the CMS'],
+  ]) {
+    add(id, title, 'n/a', 'yaml is not installed here, so the CMS config could not be read — `npm i -D yaml`');
+  }
+} else {
+  /* D3 is analysed because no shipped check covers it. */
+  let config = null;
+  try {
+    config = parseYaml(readFileSync(CONFIG, 'utf8')) ?? {};
+  } catch (err) {
+    config = null;
+    add('D3', 'CMS image fields are pickers', 'n/a', `${CONFIG} does not parse — ${err.message}`);
+  }
+
+  if (config) {
+    const flatten = (list) =>
+      (list ?? []).flatMap((e) => (e?.type === 'group' ? flatten(e.items ?? e.content ?? []) : [e]));
+    const textBoxes = [];
+    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'})`);
+        }
+        if (Array.isArray(f.fields)) walkFields(f.fields, entry, path);
+      }
+    };
+    for (const entry of flatten(config.content)) walkFields(entry?.fields, entry?.name ?? '?');
+    add(
+      'D3',
+      'CMS image fields are pickers',
+      textBoxes.length ? 'drift' : 'ok',
+      textBoxes.length
+        ? `${textBoxes.length} image field(s) are text boxes, so the editor must type a key from memory: ${textBoxes.slice(0, 4).join(', ')}`
+        : 'image fields use the picker',
+    );
+  }
+
+  /* D4 and D8 have a shipped check. Drift means not having it. */
+  const hasCms = existsSync(join('scripts', 'check-cms.mjs'));
+  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',
+  );
+  add(
+    'D8',
+    'Client guide matches the CMS',
+    hasCms && existsSync(join('docs', 'handover.md')) ? 'ok' : 'drift',
+    !existsSync(join('docs', 'handover.md'))
+      ? 'no docs/handover.md — the client has a CMS and no instructions for it'
+      : hasCms
+        ? 'check-cms.mjs cross-references the guide against the config'
+        : 'nothing checks the guide against the config; a guide that has gone stale does not read as stale, it reads as true',
+  );
+}
+
+/* ── D7 · text over photographs ───────────────────────────────────────────── */
+
+const hasContrast = existsSync(join('scripts', 'check-contrast.mjs'));
+const declares = existsSync(join('src', 'data', 'contrast.json'));
+add(
+  'D7',
+  'Text over photographs is measured',
+  hasContrast ? (declares ? 'ok' : 'n/a') : 'drift',
+  hasContrast
+    ? 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',
+);
+
+/* ── report ───────────────────────────────────────────────────────────────── */
+
+if (json) {
+  console.log(JSON.stringify({ findings }, null, 2));
+  process.exit(0);
+}
+
+const mark = { ok: `${GREEN}✓${RESET}`, drift: `${YELLOW}!${RESET}`, 'n/a': `${DIM}·${RESET}` };
+const drifted = findings.filter((f) => f.status === 'drift');
+
+console.log(`\n${BOLD}── Drift from the current kit ${'─'.repeat(28)}${RESET}\n`);
+for (const f of findings) {
+  console.log(`  ${mark[f.status]} ${f.title}`);
+  console.log(`      ${DIM}${f.detail}${RESET}`);
+}
+
+console.log('');
+if (!drifted.length) {
+  console.log(`${GREEN}✓${RESET} nothing behind that this can see\n`);
+} else {
+  console.log(
+    `${YELLOW}!${RESET} ${drifted.length} of ${findings.length} behind the current kit\n\n` +
+      `  ${DIM}Nothing has been changed. Decide what is worth doing before doing any of it —\n` +
+      `  some of these are invisible to visitors and some are a client unable to edit\n` +
+      `  their own photographs, and they are not the same job.${RESET}\n`,
+  );
+}

package/template/scripts/lib/binary-files.mjs

@@ -0,0 +1,79 @@
+/**
+ * Tracked source files that git and grep treat as BINARY.
+ *
+ * ⚠ THE PROVENANCE SWEEP IS WRITTEN WITH `grep -I`, WHICH SKIPS THEM. One
+ *   script used a literal NUL as a string sentinel, which made it binary, which
+ *   made it invisible to the sweep — while carrying a client's entire brand,
+ *   both typefaces and a base64 palette. Two commits.
+ *
+ * The tools fail quietly rather than loudly: `grep` returns nothing and exits 1
+ * exactly as it does for no-match, and `git diff` says only
+ * `Binary files differ`, so changes never appear in review.
+ *
+ * ⚠ THE OBVIOUS IMPLEMENTATION IS A FUNCTION THAT ALWAYS RETURNS NOTHING.
+ *   `git grep -I --files-without-match ''` reads like the answer and prints
+ *   nothing either way. Ask git which files it tracks, ask again which it can
+ *   read as text, and take the difference.
+ *
+ * ⚠ AN EMPTY FILE IS NOT A BINARY ONE. `git grep ''` matches LINES, and a
+ *   zero-byte file has none, so the naive difference reports every empty file.
+ *   Excluded by size rather than by guessing.
+ *
+ * Shared by the kit's own `check:binary` and by `check-drift.mjs`, which runs
+ * in a delivered project. One implementation, because two would be free to
+ * disagree about which files count.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { statSync } from 'node:fs';
+
+/** The extensions a human reviews. A .png is legitimately binary; a .mjs is not. */
+export const SOURCE_GLOBS = [
+  '*.mjs',
+  '*.js',
+  '*.cjs',
+  '*.ts',
+  '*.tsx',
+  '*.astro',
+  '*.css',
+  '*.md',
+  '*.json',
+  '*.jsonc',
+  '*.yml',
+  '*.yaml',
+  '*.html',
+  '*.txt',
+  '*.sh',
+];
+
+const git = (...args) => {
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+      .split('\n')
+      .filter(Boolean);
+  } catch (err) {
+    /* `git grep` exits 1 when nothing matches, which is not an error here. */
+    if (err.status === 1 && typeof err.stdout === 'string') {
+      return err.stdout.split('\n').filter(Boolean);
+    }
+    throw err;
+  }
+};
+
+/**
+ * `{ tracked, binary }` for the current working directory.
+ * Throws if git is unavailable — a silent empty result would be a lie.
+ */
+export function binarySourceFiles() {
+  const tracked = git('ls-files', '--', ...SOURCE_GLOBS);
+  const textual = new Set(git('grep', '-I', '-l', '', '--', ...SOURCE_GLOBS));
+  const binary = tracked.filter((file) => {
+    if (textual.has(file)) return false;
+    try {
+      return statSync(file).size > 0;
+    } catch {
+      return false; // deleted but still indexed
+    }
+  });
+  return { tracked, binary };
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Images a page renders from a hardcoded string, which no editor can change.
+ *
+ * ── THE FAILURE THIS FINDS ─────────────────────────────────────────────────
+ * After wiring five image fields into a CMS, someone wrote in the config that
+ * "photographs are chosen in code, not here". That sentence was true of the
+ * five fields that existed and quietly excused the eight that did not — a
+ * header band, four class tiles, a gift-card picture and three more, all
+ * `name="photos/x"` literals sitting in `.astro` files.
+ *
+ * ⚠ THE CLIENT OPENED THE PAGE, SAW A PHOTOGRAPH, AND HAD NO WAY TO CHANGE IT.
+ *   Nothing was broken. The build was green, the page was correct, and the
+ *   only symptom was a person looking for a field that was never there.
+ *
+ * The rule it enforces: an image a page renders is **a field, or a deliberate
+ * exception somebody wrote down** — never an oversight dressed as a principle.
+ *
+ * ── WHY A LIB AND NOT A SCRIPT ─────────────────────────────────────────────
+ * Two callers need it and they run in different worlds: `check-cms.mjs` in a
+ * project that has a CMS, and `check-drift.mjs` in a delivered site that may
+ * have neither. A second copy is two implementations free to disagree, which
+ * is the failure the whole media round was about.
+ */
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+/*
+ * ⚠ ONLY THE ATTRIBUTES THAT NAME AN IMAGE, AND ONLY QUOTED VALUES.
+ *
+ *   An earlier attempt in the source project matched every `name="…"` and
+ *   returned form fields, icon names and `<meta name="viewport">` — fifteen
+ *   hits where the truth was zero. A check that cries wolf on a form field
+ *   gets switched off before it ever finds a photograph.
+ *
+ *   `name=` is therefore accepted only on an element whose tag looks like an
+ *   image component, while `image=` and `poster=` are unambiguous anywhere.
+ *   An expression — name={photo} — has no quotes and never matches, which is
+ *   exactly right: that value came from somewhere else, which is the point.
+ */
+const IMAGE_COMPONENT = /<(Img|Image|Picture|BandHeader|Hero)\b[^>]*?\bname=["']([^"']+)["']/gis;
+const IMAGE_ATTR = /\b(?:image|poster|photo|bgImage|backgroundImage)=["']([^"']+)["']/gis;
+
+/** Values that are never a photograph a client would want to change. */
+const NOT_A_PHOTO = /^(#|https?:|data:|\/|\.\.?\/)|\.(svg|ico)$/i;
+
+const walk = (dir) =>
+  readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry);
+    return statSync(full).isDirectory() ? walk(full) : [full];
+  });
+
+/**
+ * Every hardcoded image reference under `root`.
+ *
+ * Returns `[{ file, value }]`, deduplicated per file+value, with paths in
+ * forward slashes so a Windows run reports what a Linux one does.
+ */
+export function literalImages(root = 'src/pages') {
+  const out = [];
+  const seen = new Set();
+
+  let files;
+  try {
+    files = walk(root).filter((f) => /\.(astro|mdx)$/.test(f));
+  } catch {
+    return out; // no pages directory is not this check's problem
+  }
+
+  for (const file of files) {
+    const source = readFileSync(file, 'utf8');
+    const rel = relative(process.cwd(), file).split(sep).join('/');
+
+    /* Astro comments are `{/* … *\/}` and HTML comments render; neither should
+       contribute a finding, so strip both before matching. */
+    const body = source.replace(/<!--[\s\S]*?-->/g, ' ');
+
+    for (const [regex, group] of [
+      [IMAGE_COMPONENT, 2],
+      [IMAGE_ATTR, 1],
+    ]) {
+      regex.lastIndex = 0;
+      for (const match of body.matchAll(regex)) {
+        const value = match[group];
+        if (!value || NOT_A_PHOTO.test(value)) continue;
+        const key = `${rel}::${value}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        out.push({ file: rel, value });
+      }
+    }
+  }
+
+  return out.sort((a, b) => a.file.localeCompare(b.file) || a.value.localeCompare(b.value));
+}

package/template/scripts/lib/routes.mjs

@@ -96,3 +96,70 @@ export async function discoverRoutes(origin, fetcher = fetch) {
 
   return { routes: [], source: 'nothing — no sitemap and no dist/' };
 }
+
+/**
+ * Routes derived from `src/pages`, without building anything.
+ *
+ * ── WHY NOT routesFromDist ─────────────────────────────────────────────────
+ * `check-cms.mjs` runs BEFORE the build, so `dist/` does not exist yet. The
+ * point of checking a navigation target early is to fail while somebody is
+ * still looking at the config, not after a deploy.
+ *
+ * Returns `{ static: Set<string>, dynamic: RegExp[] }`.
+ *
+ * ⚠ A DYNAMIC ROUTE IS A PATTERN, NOT A ROUTE. `[slug].astro` serves every
+ *   legal page and `[...path].astro` serves any depth. Treating those as
+ *   literal strings would report every real link through them as broken, which
+ *   on a site with a `[slug]` catch-all is *most of the site* — a check that
+ *   confident and that wrong gets switched off within a day.
+ *
+ * ⚠ ENDPOINTS ARE NOT PAGES. `robots.txt.ts` and `api/contact.ts` produce
+ *   responses, never navigable pages, so they are excluded — nobody puts them
+ *   in a menu and reporting them as available would be noise.
+ */
+export function routesFromPages(dir = 'src/pages') {
+  const out = { static: new Set(), dynamic: [] };
+  if (!existsSync(dir)) return out;
+
+  const walk = (d) =>
+    readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+      const full = join(d, e.name);
+      return e.isDirectory() ? walk(full) : [full];
+    });
+
+  for (const file of walk(dir)) {
+    const rel = relative(dir, file).split(sep).join('/');
+    /* `_` prefixed files and directories are not routed by Astro. */
+    if (rel.split('/').some((part) => part.startsWith('_'))) continue;
+    if (!/\.(astro|md|mdx)$/.test(rel)) continue; // .ts endpoints are not pages
+
+    const path =
+      '/' +
+      rel
+        .replace(/\.(astro|md|mdx)$/, '')
+        .replace(/(^|\/)index$/, '$1')
+        .replace(/\/$/, '');
+    const route = path === '/' ? '/' : `${path}/`.replace(/\/+/g, '/');
+
+    if (route.includes('[')) {
+      /* [...rest] matches any depth; [slug] matches one segment. */
+      const pattern = route
+        .replace(/[.*+?^${}()|\\]/g, '\\$&')
+        .replace(/\[\.\.\.[^\]]+\]/g, '.+')
+        .replace(/\[[^\]]+\]/g, '[^/]+');
+      out.dynamic.push(new RegExp(`^${pattern}$`));
+    } else {
+      out.static.add(route);
+    }
+  }
+
+  return out;
+}
+
+/** Does `href` correspond to a page this site serves? */
+export function routeExists(href, routes) {
+  const path = href.split('#')[0].split('?')[0];
+  const normalised = path.endsWith('/') || path === '' ? path || '/' : `${path}/`;
+  if (routes.static.has(normalised)) return true;
+  return routes.dynamic.some((re) => re.test(normalised));
+}

package/template/scripts/md-to-pdf.mjs

@@ -27,7 +27,34 @@
 import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
 import { dirname, basename, resolve } from 'node:path';
 
-import puppeteer from 'puppeteer';
+/*
+ * ⚠ puppeteer IS A TRANSITIVE DEPENDENCY, NOT A DECLARED ONE. The comment above
+ *   is true only while `pa11y-ci` is a devDependency of this project. Run pa11y
+ *   as `npx --yes pa11y-ci` instead — which a project reasonably might — and
+ *   puppeteer is never installed here at all.
+ *
+ *   A fork that did exactly that compensated by hunting for a puppeteer inside
+ *   `~/.npm/_npx`, found a stale one whose bundled Chrome would not launch, and
+ *   timed out after thirty seconds with nothing pointing at the cause.
+ *
+ *   So say it plainly rather than let a bare import throw ERR_MODULE_NOT_FOUND:
+ *   a script whose dependency is a side effect of how you happened to run a
+ *   different script is a script that breaks later, on someone else's machine,
+ *   for reasons that look unrelated.
+ */
+let puppeteer;
+try {
+  puppeteer = (await import('puppeteer')).default;
+} catch {
+  console.error(
+    `\nmd-to-pdf needs puppeteer, which is not installed.\n\n` +
+      `  It normally arrives with pa11y-ci, so this usually means pa11y-ci was\n` +
+      `  removed from devDependencies, or is being run as \`npx --yes pa11y-ci\`\n` +
+      `  rather than installed.\n\n` +
+      `  Fix: npm install --save-dev puppeteer\n`,
+  );
+  process.exit(1);
+}
 
 const [, , input, outputArg] = process.argv;
 if (!input) {