npm - create-website-build-kit - Versions diffs - 0.1.0 - Mend

create-website-build-kit 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

package/README.md +54 -0
package/index.mjs +149 -0
package/package.json +42 -0
package/template/.dev.vars.example +3 -0
package/template/.github/workflows/gates.yml +58 -0
package/template/.node-version +1 -0
package/template/.pa11yci.json +24 -0
package/template/BUILD-STATE.md +47 -0
package/template/CLAUDE.md +153 -0
package/template/astro.config.mjs +150 -0
package/template/docs/analytics.md +86 -0
package/template/docs/content.md +138 -0
package/template/docs/handover.md +182 -0
package/template/docs/handover.pdf +0 -0
package/template/docs/runbook.md +661 -0
package/template/docs/traps.md +903 -0
package/template/gitignore +31 -0
package/template/package-lock.json +8159 -0
package/template/package.json +53 -0
package/template/public/_headers +61 -0
package/template/public/_redirects +39 -0
package/template/public/site.webmanifest +13 -0
package/template/scripts/a11y-evidence.mjs +258 -0
package/template/scripts/check-console.mjs +125 -0
package/template/scripts/check-env.mjs +99 -0
package/template/scripts/check-reflow.mjs +148 -0
package/template/scripts/check-sitemap.mjs +113 -0
package/template/scripts/dns-snapshot.mjs +267 -0
package/template/scripts/extract.mjs +317 -0
package/template/scripts/indexnow.mjs +154 -0
package/template/scripts/lastmod.mjs +147 -0
package/template/scripts/lib/inventory.mjs +104 -0
package/template/scripts/lib/preserved.mjs +42 -0
package/template/scripts/lib/routes.mjs +92 -0
package/template/scripts/md-to-pdf.mjs +335 -0
package/template/scripts/og-cards.config.mjs +114 -0
package/template/scripts/og-cards.mjs +487 -0
package/template/scripts/optimize-media.mjs +380 -0
package/template/scripts/recon.mjs +480 -0
package/template/scripts/redirects.mjs +298 -0
package/template/scripts/shots.mjs +447 -0
package/template/scripts/staging-headers.mjs +102 -0
package/template/scripts/tells.mjs +268 -0
package/template/scripts/verify.mjs +1069 -0
package/template/src/components/ContactForm.astro +405 -0
package/template/src/components/CtaBand.astro +82 -0
package/template/src/components/EnvBadge.astro +146 -0
package/template/src/components/Footer.astro +210 -0
package/template/src/components/Header.astro +530 -0
package/template/src/components/Icon.astro +56 -0
package/template/src/components/Img.astro +129 -0
package/template/src/components/PageHero.astro +88 -0
package/template/src/components/Seo.astro +119 -0
package/template/src/components/StructuredData.astro +173 -0
package/template/src/content/blog/.gitkeep +5 -0
package/template/src/content/legal/.gitkeep +0 -0
package/template/src/content.config.ts +81 -0
package/template/src/data/areas.ts +31 -0
package/template/src/data/business.ts +121 -0
package/template/src/data/categories.ts +37 -0
package/template/src/data/fonts.ts +25 -0
package/template/src/data/image-manifest.json +1 -0
package/template/src/data/lastmod.json +1 -0
package/template/src/data/nav.ts +49 -0
package/template/src/data/services.ts +39 -0
package/template/src/data/site.ts +136 -0
package/template/src/env.d.ts +28 -0
package/template/src/layouts/Base.astro +223 -0
package/template/src/lib/brevo.ts +96 -0
package/template/src/lib/hast-media.mjs +55 -0
package/template/src/lib/lastmod.mjs +47 -0
package/template/src/lib/lead.ts +92 -0
package/template/src/lib/legal-routes.mjs +31 -0
package/template/src/lib/legal.ts +75 -0
package/template/src/lib/posts.ts +64 -0
package/template/src/lib/runtime.ts +33 -0
package/template/src/pages/404.astro +51 -0
package/template/src/pages/[slug].astro +111 -0
package/template/src/pages/accessibility.astro +128 -0
package/template/src/pages/api/contact.ts +191 -0
package/template/src/pages/api/leads.csv.ts +82 -0
package/template/src/pages/contact.astro +112 -0
package/template/src/pages/index.astro +84 -0
package/template/src/pages/robots.txt.ts +38 -0
package/template/src/pages/rss.xml.ts +27 -0
package/template/src/styles/global.css +463 -0
package/template/src/styles/project.css +14 -0
package/template/src/styles/prose.css +182 -0
package/template/src/styles/tokens.css +218 -0
package/template/tsconfig.json +5 -0
package/template/wrangler.jsonc +63 -0

package/template/src/data/business.ts ADDED Viewed

@@ -0,0 +1,121 @@
+/**
+ * The one place business facts live.
+ *
+ * Both the visible UI and the JSON-LD structured data read from here, so the
+ * page and the schema can never drift apart. Change a phone number here and it
+ * updates the header, footer, every call-to-action, the notification emails and
+ * what Google reads.
+ *
+ * ── FILL THIS IN FIRST. Everything else depends on it. ─────────────────────
+ */
+export const business = {
+  name: 'Business Name',
+  /**
+   * BCP 47 language tag. Drives `<html lang>`, `inLanguage` in structured data,
+   * and how dates are formatted in the lead notification.
+   *
+   * ⚠ SET THIS. The template shipped `en-US` hardcoded in five files while its
+   * own compliance reference covered the EAA, UK GDPR and AODA — so a British
+   * or Canadian build announced itself as American to every screen reader and
+   * every crawler, and printed dates in the wrong order.
+   */
+  locale: 'en',
+  legalName: 'Business Name Ltd',
+  tagline: 'What you do, in six words',
+  description:
+    'One or two sentences that would make sense read aloud on the phone. This becomes the ' +
+    'default meta description and the Organization description in structured data.',
+  foundedYear: 2010,
+  phone: {
+    display: '(000) 000-0000', // what a visitor reads, in local convention
+    e164: '+00000000000', // E.164 WITH the country code — schema.org and tel: need it
+    href: 'tel:+00000000000',
+    sms: 'sms:+00000000000',
+  },
+  email: {
+    display: 'hello@example.com', // shown on the site
+    href: 'mailto:hello@example.com',
+    sender: 'hello@example.com', // must be a VERIFIED sender at your email provider
+    senderName: 'Business Name',
+    notify: 'owner@example.com', // where live enquiries land
+    notifyTest: 'dev@example.com', // where staging enquiries land — never the client
+  },
+  address: {
+    street: '1 Example Street',
+    locality: 'Town',
+    region: 'ST',
+    regionName: 'State',
+    /**
+     * IANA timezone, used to stamp lead notifications in the business's own
+     * local time. A hardcoded zone in the email template is a previous
+     * client's clock: every enquiry then carries a plausible timestamp that is
+     * silently hours out, and nobody checks a date they can read.
+     */
+    timeZone: 'UTC',
+    /** Short label printed after the time. Keep it in step with `timeZone`. */
+    timeZoneLabel: 'UTC',
+    postalCode: '00000',
+    country: 'US',
+    mapUrl: 'https://maps.google.com/?q=...',
+  },
+  /** Used by LocalBusiness JSON-LD. Get them from Google Maps. */
+  geo: { latitude: 0, longitude: 0 },
+  hours: {
+    days: ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'],
+    opens: '09:00',
+    closes: '17:00',
+    display: 'Mon – Fri · 9am – 5pm',
+  },
+  priceRange: '$$',
+  /**
+   * schema.org types for the organisation node, most general first.
+   *
+   * ⚠ SET THE SUBTYPE FOR THIS BUSINESS, or leave the two generic ones. The
+   * template shipped `HVACBusiness` hardcoded for two projects, so every site
+   * built from it silently declared itself a heating and ventilation company
+   * to Google — valid markup, clean build, wrong business.
+   *
+   * A wrong subtype is worse than no subtype: it is a specific claim, and rich
+   * results and local classification act on it. Pick from the LocalBusiness
+   * subtypes at https://schema.org/LocalBusiness — e.g. `Dentist`, `Plumber`,
+   * `HealthClub`, `LegalService`. If nothing fits exactly, leave it out.
+   */
+  schemaTypes: ['Organization', 'LocalBusiness'] as string[],
+  /**
+   * Logo path for structured data, relative to the site root, or null.
+   *
+   * Null by default because the template ships no brand assets, and a schema
+   * `logo` pointing at a 404 is a warning in Search Console that nothing in a
+   * build would surface. Set it after `npm run media` puts the real file in
+   * public/img/brand/.
+   */
+  logoPath: null as string | null,
+  /** Drives areaServed in structured data, and the footer list. */
+  serviceAreas: ['Town', 'Neighbouring Town'],
+  serviceAreaSummary: 'Serving Town and the surrounding area.',
+  /**
+   * Accreditations and credential badges. `image` is a manifest key, not a URL.
+   * Check the artwork before designing the strip around it — badges are often
+   * near-white PNGs drawn for a dark background.
+   */
+  credentials: [] as { name: string; image: string }[],
+  socials: [] as { name: string; url: string }[],
+  credit: { name: '', url: '' },
+} as const;
+export const addressOneLine = `${business.address.street}, ${business.address.locality}, ${business.address.region} ${business.address.postalCode}`;

package/template/src/data/categories.ts ADDED Viewed

@@ -0,0 +1,37 @@
+/**
+ * Blog categories.
+ *
+ * On a migration, **slugs must match the source CMS term slugs exactly** so
+ * every /category/<slug>/ URL that exists today keeps working. Take them from
+ * the export rather than re-slugging the display names \u2014 a name containing "&"
+ * or an accent does not slug identically everywhere, and a changed category URL
+ * is lost traffic with no error anywhere to tell you.
+ *
+ * Archive pages generate only where posts exist, so an unused entry costs
+ * nothing \u2014 but delete it anyway.
+ */
+export const categories = [
+  { name: 'General', slug: 'general', description: 'Everything that does not fit a narrower category.' },
+  { name: 'Tips', slug: 'tips', description: 'Practical advice, field-tested.' },
+] as const;
+export type Category = (typeof categories)[number];
+/* Keyed by `string`, not by the literal union `categories` infers from `as
+   const`. Left inferred, the Map only accepts the two slugs that exist today,
+   so `categoryBySlug(someSlugFromTheURL)` is a type error rather than the
+   lookup-that-may-miss it is meant to be. */
+const bySlug = new Map<string, Category>(categories.map((c) => [c.slug, c]));
+const byName = new Map<string, Category>(categories.map((c) => [c.name, c]));
+export const categoryBySlug = (slug: string) => bySlug.get(slug);
+export const categoryByName = (name: string) => byName.get(name);
+/** Turn a category display name into its URL. Unknown names slug themselves. */
+export function categoryHref(name: string): string {
+  const slug =
+    byName.get(name)?.slug ??
+    name.toLowerCase().replace(/&/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  return `/category/${slug}/`;
+}

package/template/src/data/fonts.ts ADDED Viewed

@@ -0,0 +1,25 @@
+/**
+ * Self-hosted fonts to preload.
+ *
+ * Empty on purpose. The template ships no typeface — the display/body pairing
+ * is the single largest premium lever there is, and a typeface that arrives
+ * with the starter is one nobody chose.
+ *
+ * To add one:
+ *   1. put the variable woff2 in `public/fonts/` (subset — see docs/design.md)
+ *   2. add the `@font-face` block to `src/styles/global.css`
+ *   3. name the family in `--font-display` / `--font-body` in `tokens.css`
+ *   4. add the file here, so Base.astro emits the preload
+ *
+ * Only preload faces used above the fold — a preload for a face first needed
+ * at the footer competes with the LCP image for bandwidth and costs more than
+ * it saves. Two entries is normally the whole list.
+ *
+ * Same-origin means the preload is the whole story: no DNS lookup, no TLS
+ * handshake, no third-party round trip on the critical path.
+ */
+export const preloadFonts: string[] = [
+  // '/fonts/display.woff2',
+  // '/fonts/body.woff2',
+];

package/template/src/data/image-manifest.json ADDED Viewed

	@@ -0,0 +1 @@
1	+ {}

package/template/src/data/lastmod.json ADDED Viewed

	@@ -0,0 +1 @@
1	+ {}

package/template/src/data/nav.ts ADDED Viewed

@@ -0,0 +1,49 @@
+/**
+ * Navigation and the primary call to action.
+ *
+ * One place, read by the header, the mobile menu, the footer columns and the
+ * 404's onward links — so a route added here appears everywhere it should and
+ * the 404 can never offer a page that no longer exists.
+ *
+ * The list below is the minimum that resolves in a fresh template. Replace it
+ * with the real information architecture; the route inventory from recon is
+ * what decides it, not this file.
+ */
+export interface NavItem {
+  label: string;
+  href: string;
+  /** Show in the footer's link column. Defaults to true. */
+  footer?: boolean;
+}
+export const nav: NavItem[] = [
+  { label: 'Home', href: '/' },
+  { label: 'Contact', href: '/contact/' },
+];
+/**
+ * The one action that counts as a win, as a link.
+ *
+ * Discovery names exactly one — call, form, booking, demo. This is it, and it
+ * is what the header CTA, the mobile menu and any conversion band point at.
+ * Two competing calls to action is the same as none.
+ */
+export const primaryAction = {
+  label: 'Get in touch',
+  href: '/contact/',
+} as const;
+/**
+ * Legal and required links, in the footer on every page.
+ *
+ * `/accessibility` is required under the EAA and the UK PSBAR — do not remove
+ * it. It is hand-written, so it lives here.
+ *
+ * Privacy, terms and the cookie notice do NOT go here. They are markdown in
+ * `src/content/legal/`, and the footer reads that collection directly — a
+ * footer link to a page that does not exist yet is a 404 on every page of the
+ * site and nothing will report it, so the link is derived from the page rather
+ * than typed alongside it. Add the file; the link appears.
+ */
+export const legalNav: NavItem[] = [{ label: 'Accessibility', href: '/accessibility/' }];

package/template/src/data/services.ts ADDED Viewed

@@ -0,0 +1,39 @@
+/**
+ * Service catalogue. One entry per service; the pages are generated from these.
+ *
+ * Content, not presentation. There is no `icon` or `number` field on purpose —
+ * a data file that carries card decoration has decided what the page looks
+ * like. Add whatever fields the chosen design genuinely needs, once it exists.
+ */
+export type Service = {
+  slug: string;
+  title: string;
+  short: string; // one sentence a customer would recognise as their problem
+  body: string; // the fuller explanation, for the service's own page
+  featured: boolean; // surfaced in the footer and any short list
+};
+export const services: Service[] = [
+  {
+    slug: 'first-service',
+    title: 'First Service',
+    short: 'One sentence a customer would recognise as their problem.',
+    body: 'The fuller explanation. Written for someone deciding whether to call, not for a search engine.',
+    featured: true,
+  },
+];
+/**
+ * Why this business rather than another. Specific, not generic —
+ * "same-day report" beats "great service".
+ *
+ * Where these appear, and whether they appear at all, is the archetype's
+ * decision: see references/archetypes.md for the proof model each one needs.
+ */
+export const differentiators: { title: string; body: string }[] = [
+  { title: 'Reason one', body: 'Specific, not generic.' },
+];
+/** Anything handled on the customer's behalf — paperwork, permits, filings. */
+export const documentationHandled: string[] = [];

package/template/src/data/site.ts ADDED Viewed

@@ -0,0 +1,136 @@
+/**
+ * Environment behaviour, derived once from the build variable.
+ *
+ * Nothing here is a hand-flipped switch. `PUBLIC_SITE_ENV` is set by the build
+ * script (`build:staging` / `build:production`); everything else follows from
+ * it, so there is nothing a human has to remember to change at go-live.
+ */
+import { business } from './business';
+export type SiteEnv = 'development' | 'staging' | 'production';
+export const SITE_ENV = (import.meta.env.PUBLIC_SITE_ENV ?? 'development') as SiteEnv;
+/**
+ * Exact hostname allowlist. A suffix match would treat
+ * `new.example.com` as production, which is precisely the bug.
+ */
+export const PRODUCTION_HOSTS = ['example.com', 'www.example.com'] as const;
+export const isProduction = SITE_ENV === 'production';
+export const isStaging = SITE_ENV === 'staging';
+/**
+ * The client's own analytics IDs. Both must be set or nothing is emitted.
+ *
+ * ── FILL IN OR LEAVE EMPTY. Never inherit an ID from another project. ───────
+ * A copied container sends a real business's traffic to someone else's
+ * property, builds green, deploys clean, and reports nothing wrong.
+ */
+const ANALYTICS = {
+  gtmId: '', // GTM-XXXXXXX
+  ga4Id: '', // G-XXXXXXXXXX
+} as const;
+/**
+ * Cloudflare Web Analytics. Independent of the Google tags above — set either,
+ * both or neither.
+ *
+ * Worth having on every site for two reasons that have nothing to do with
+ * duplicating GA4:
+ *
+ *  1. **Real-user Core Web Vitals from the first visitor.** CrUX needs months
+ *     of traffic before it reports on a new domain, so field data is otherwise
+ *     unavailable for exactly the period after launch when you need it.
+ *  2. **A control group for ad blockers.** It is cookieless and first-party, so
+ *     the gap between this and GA4 measures what the Google tags are losing
+ *     rather than leaving you to guess.
+ *
+ * Dashboard → Web Analytics → the site → the token in the beacon snippet.
+ */
+const CF_BEACON_TOKEN = ''; // 32-char hex
+/** True only on a real production host. Used by the worker as a runtime guard. */
+export function isProductionHost(hostname: string): boolean {
+  return (PRODUCTION_HOSTS as readonly string[]).includes(hostname.toLowerCase());
+}
+export const site = {
+  env: SITE_ENV,
+  url: import.meta.env.SITE ?? 'http://localhost:4321',
+  /** Search engines only ever see production. */
+  indexable: isProduction,
+  /**
+   * Analytics only ever fire on production. Staging HTML contains zero references.
+   *
+   * Leave these empty and no tag is emitted at all — an unset ID must never fall
+   * back to *someone else's* container. Fill both in from the client's own
+   * property (Admin → Data streams for GA4; the workspace header for GTM), or
+   * delete the block if they are not using Google analytics.
+   */
+  analytics: isProduction && ANALYTICS.ga4Id && ANALYTICS.gtmId ? ANALYTICS : null,
+  /** Cloudflare Web Analytics. Production only, and only if a token is set. */
+  cfBeaconToken: isProduction && CF_BEACON_TOKEN ? CF_BEACON_TOKEN : null,
+  /** Leads submitted off production are tagged and written to a separate namespace. */
+  leadsBinding: isProduction ? ('LEADS' as const) : ('LEADS_STAGING' as const),
+  leadTag: isProduction ? ('live' as const) : ('test' as const),
+  /**
+   * How long a stored lead survives, in days. Written as a KV `expirationTtl`,
+   * so expiry is enforced by the store rather than by anyone remembering.
+   *
+   * ── THIS IS A COMPLIANCE DECISION, NOT A STORAGE ONE ──────────────────────
+   * A lead is personal data. The UK GDPR and the GDPR both require a defined
+   * retention period and neither accepts "indefinitely" — and KV keeps a value
+   * forever unless it is told otherwise, so the default without this line is
+   * exactly the thing that cannot be justified.
+   *
+   * 180 days is the kit's default because this store is a SAFETY NET, not the
+   * system of record: the notification email is the delivery, and KV exists so
+   * that a provider outage costs a notification rather than the lead. Six
+   * months is long enough to recover from an outage nobody noticed and to run
+   * an export, and short enough to state plainly in a privacy notice.
+   *
+   * ⚠ Raise it only with a reason you would give a regulator, and make sure the
+   * privacy notice says the same number. Staging is deliberately shorter — test
+   * submissions are not records of anything.
+   */
+  leadRetentionDays: isProduction ? 180 : 30,
+  /**
+   * Who gets the new-lead notification. Off production it goes to the
+   * developer, not the client — a verification run should never land in the
+   * inbox someone answers real enquiries from.
+   */
+  leadNotifyTo: isProduction ? business.email.notify : business.email.notifyTest,
+} as const;
+/**
+ * Icons that actually exist in public/. Nothing is advertised until it does.
+ *
+ * ⚠ SET THESE once the brand assets land — `npm run media` puts them in
+ * public/img/brand/.
+ *
+ * The template used to declare all four unconditionally, so a fresh build made
+ * three failed requests on EVERY page: /favicon.ico, /img/brand/favicon.svg and
+ * the manifest's /icon-192.png. `npm run console` was the first thing to notice,
+ * which is the point of it.
+ *
+ * Declared rather than detected with `fs`, because Base.astro also renders
+ * server-side for the contact page and there is no filesystem in the Workers
+ * runtime. Same reason the analytics IDs and `business.logoPath` are declared.
+ */
+export const icons = {
+  ico: null as string | null, // '/favicon.ico'
+  svg: null as string | null, // '/img/brand/favicon.svg'
+  appleTouch: null as string | null, // '/apple-touch-icon.png'
+  /** The manifest lists its own icons — ship it only once those exist. */
+  manifest: false,
+};
+export const defaultSocialImage = '/img/social/og-default.jpg';

package/template/src/env.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+/// <reference types="@cloudflare/workers-types" />
+/**
+ * Cloudflare's runtime types — `KVNamespace`, `cloudflare:workers`, and the rest
+ * of what src/lib/runtime.ts touches.
+ *
+ * Without this, `astro check` cannot see the Workers globals, so the one file in
+ * the project that talks to a real binding is the one file TypeScript checks
+ * least. It reports `Cannot find name 'KVNamespace'` and then infers `any`
+ * through everything downstream, including the lead export.
+ *
+ * A triple-slash reference rather than `compilerOptions.types`, because setting
+ * that key switches OFF automatic @types inclusion for everything else.
+ *
+ * For types that know your actual binding NAMES rather than the generic shapes,
+ * run `npx wrangler types` and reference the file it generates instead. That
+ * has to be re-run whenever wrangler.jsonc changes, which is the trade.
+ */
+interface ImportMetaEnv {
+  /** Set by the build script. Never read directly — go through src/data/site.ts. */
+  readonly PUBLIC_SITE_ENV?: 'development' | 'staging' | 'production';
+  readonly PUBLIC_SITE_URL?: string;
+}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/template/src/layouts/Base.astro ADDED Viewed

@@ -0,0 +1,223 @@
+---
+import { ClientRouter } from 'astro:transitions';
+import Seo from '../components/Seo.astro';
+import StructuredData from '../components/StructuredData.astro';
+import Header from '../components/Header.astro';
+import Footer from '../components/Footer.astro';
+import EnvBadge from '../components/EnvBadge.astro';
+import { site, icons } from '../data/site';
+import { business } from '../data/business';
+import { preloadFonts } from '../data/fonts';
+import '../styles/global.css';
+/* This project's own look. See the note at the top of the file — a card or a
+   hero style belongs here, never in global.css. */
+import '../styles/project.css';
+interface Props {
+  title: string;
+  description: string;
+  canonical?: string;
+  image?: string;
+  imageAlt?: string;
+  type?: 'website' | 'article';
+  publishedAt?: Date;
+  updatedAt?: Date;
+  noindex?: boolean;
+  schemaType?: 'home' | 'page' | 'article' | 'blog';
+  breadcrumbs?: { name: string; href: string }[];
+  article?: Parameters<typeof StructuredData>[0]['article'];
+  faq?: { question: string; answer: string }[];
+  bodyClass?: string;
+}
+const {
+  title,
+  description,
+  canonical,
+  image,
+  imageAlt,
+  type,
+  publishedAt,
+  updatedAt,
+  noindex,
+  schemaType,
+  breadcrumbs,
+  article,
+  faq,
+  bodyClass,
+} = Astro.props;
+---
+<!doctype html>
+<html lang={business.locale}>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <!-- Set once the brand ramp is real, and keep it in step with
+         public/site.webmanifest — the two disagreeing is what makes an
+         installed icon's splash screen the wrong colour. -->
+    <meta name="theme-color" content="#ffffff" />
+    <meta name="format-detection" content="telephone=no" />
+    <Seo
+      title={title}
+      description={description}
+      canonical={canonical}
+      image={image}
+      imageAlt={imageAlt}
+      type={type}
+      publishedAt={publishedAt}
+      updatedAt={updatedAt}
+      noindex={noindex}
+    />
+    <StructuredData type={schemaType} breadcrumbs={breadcrumbs} article={article} faq={faq} />
+    <!--
+      Order matters, and so does the artwork. Browsers prefer an SVG icon over
+      the .ico when both are declared — the original /logo/favicon.svg was a
+      different mark entirely (a blue stopwatch), so the tab showed the wrong
+      logo while the .ico was perfectly correct. If this SVG is ever replaced,
+      render it and look at it before shipping.
+    -->
+    {icons.ico && <link rel="icon" href={icons.ico} sizes="32x32" />}
+    {icons.svg && <link rel="icon" href={icons.svg} type="image/svg+xml" />}
+    {icons.appleTouch && <link rel="apple-touch-icon" href={icons.appleTouch} />}
+    {icons.manifest && <link rel="manifest" href="/site.webmanifest" />}
+    <!-- Fonts are same-origin, so a preload here is the whole story: no DNS,
+         no TLS handshake, no third-party round trip on the critical path.
+         Empty until src/data/fonts.ts names one. -->
+    {
+      preloadFonts.map((href) => (
+        <link rel="preload" href={href} as="font" type="font/woff2" crossorigin />
+      ))
+    }
+    <ClientRouter />
+    {
+      /* Analytics is null off production, so staging HTML contains zero
+         references — not a disabled snippet, no snippet at all. */
+      site.analytics && (
+        <>
+          <script
+            is:inline
+            async
+            src={`https://www.googletagmanager.com/gtag/js?id=${site.analytics.ga4Id}`}
+          />
+          <script is:inline define:vars={{ ga4Id: site.analytics.ga4Id, gtmId: site.analytics.gtmId }}>
+            window.dataLayer = window.dataLayer || [];
+            function gtag() {
+              dataLayer.push(arguments);
+            }
+            gtag('js', new Date());
+            gtag('config', ga4Id);
+            /* `l` is declared. Google's published snippet takes it as a fourth
+               parameter; dropping the parameter without adding a `var` leaks an
+               implicit global called `l` onto every page — harmless until
+               something else wants that name, and impossible to find when it
+               is not. Inline scripts are non-strict, so nothing warns. */
+            (function (w, d, s, i) {
+              var l = 'dataLayer';
+              w[l] = w[l] || [];
+              w[l].push({ 'gtm.start': new Date().getTime(), event: 'gtm.js' });
+              var f = d.getElementsByTagName(s)[0],
+                j = d.createElement(s);
+              j.async = true;
+              j.src = 'https://www.googletagmanager.com/gtm.js?id=' + i;
+              f.parentNode.insertBefore(j, f);
+            })(window, document, 'script', gtmId);
+          </script>
+        </>
+      )
+    }
+    {
+      /* Cloudflare Web Analytics — a separate pipe from the Google tags above,
+         and deliberately not gated on them. Cookieless, so it needs no consent
+         banner, and it reports real-user Core Web Vitals from the first visitor
+         rather than waiting months for CrUX to cover a new domain. */
+      site.cfBeaconToken && (
+        <script
+          is:inline
+          defer
+          src="https://static.cloudflareinsights.com/beacon.min.js"
+          data-cf-beacon={JSON.stringify({ token: site.cfBeaconToken })}
+        />
+      )
+    }
+  </head>
+  <body class={bodyClass}>
+    {
+      site.analytics && (
+        <noscript>
+          <iframe
+            src={`https://www.googletagmanager.com/ns.html?id=${site.analytics.gtmId}`}
+            height="0"
+            width="0"
+            style="display:none;visibility:hidden"
+            title="Google Tag Manager"
+          />
+        </noscript>
+      )
+    }
+    <EnvBadge />
+    <a class="skip-link" href="#main">Skip to content</a>
+    <Header />
+    <main id="main">
+      <slot />
+    </main>
+    <Footer />
+    <script>
+      /**
+       * Scroll reveal.
+       *
+       * The library adds the hidden state itself (data-reveal-ready on <html>)
+       * and only after it has confirmed it can observe. If this script never
+       * runs, every [data-reveal] element is simply visible — the page is
+       * never blank because a bundle failed.
+       *
+       * The observer is rooted at the viewport, which works because <body>
+       * uses `overflow-x: clip` rather than `hidden`; `hidden` would make body
+       * a scroll container and this would never fire.
+       */
+      function setupReveal() {
+        const targets = document.querySelectorAll<HTMLElement>('[data-reveal]');
+        if (!targets.length) return;
+        const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        if (reduced || !('IntersectionObserver' in window)) {
+          document.documentElement.removeAttribute('data-reveal-ready');
+          return;
+        }
+        document.documentElement.setAttribute('data-reveal-ready', '');
+        const observer = new IntersectionObserver(
+          (entries) => {
+            for (const entry of entries) {
+              if (!entry.isIntersecting) continue;
+              entry.target.classList.add('is-revealed');
+              observer.unobserve(entry.target);
+            }
+          },
+          { rootMargin: '0px 0px -12% 0px', threshold: 0.05 },
+        );
+        for (const target of targets) observer.observe(target);
+      }
+      document.addEventListener('astro:page-load', setupReveal);
+      // The router leaves <html> attributes in place across navigations.
+      document.addEventListener('astro:before-swap', () =>
+        document.documentElement.removeAttribute('data-reveal-ready'),
+      );
+    </script>
+  </body>
+</html>