create-website-build-kit 0.1.0

package/template/src/components/Img.astro

@@ -0,0 +1,129 @@
+---
+/**
+ * Responsive WebP <img> driven by the build-time manifest.
+ *
+ * Takes a *portable reference* — `photos/hero-home`, not a URL — and resolves
+ * it to a src/srcset plus intrinsic width and height. Every image therefore
+ * carries dimensions, so nothing shifts while it loads, and moving where the
+ * images are served from is one change in the manifest generator rather than a
+ * content migration.
+ */
+import manifest from '../data/image-manifest.json';
+
+interface Props {
+  /** Manifest key, e.g. "photos/hero-home". */
+  name: string;
+  alt: string;
+  /** `sizes` attribute — how wide the image renders at each breakpoint. */
+  sizes?: string;
+  /** Above-the-fold images should be eager + high priority. */
+  priority?: boolean;
+  class?: string;
+  /** Crop to a ratio via CSS, e.g. "16/9". Keeps the intrinsic box honest. */
+  ratio?: string;
+  loading?: 'lazy' | 'eager';
+  style?: string;
+}
+
+const {
+  name,
+  alt,
+  sizes = '100vw',
+  priority = false,
+  class: className,
+  ratio,
+  loading,
+  style,
+} = Astro.props;
+
+const entry = (manifest as Record<string, { src: string; srcset: string; width: number; height: number; widths?: number[]; avifSrcset?: string | null }>)[name];
+
+if (!entry) {
+  // Fail the build, not the page. A missing image is a content bug and should
+  // never reach a deploy as a silently broken <img>.
+  throw new Error(
+    `Img: no manifest entry for "${name}". Run \`npm run media\` after adding it to media/source/.`,
+  );
+}
+
+const eager = priority || loading === 'eager';
+const objectStyle = ratio ? `aspect-ratio:${ratio};object-fit:cover;` : '';
+
+/*
+ * ── THE `src` FALLBACK IS NOT THE LARGEST VARIANT ──────────────────────────
+ * The manifest's `src` points at the widest file generated. Real browsers never
+ * fetch it — `srcset` and `sizes` govern, so a phone takes the smallest that
+ * fits.
+ *
+ * But anything ignoring `srcset` takes `src` literally: crawlers, SEO auditors,
+ * feed readers and parts of Google's image pipeline. On one site that meant an
+ * audit tool correctly reporting a 380 KB homepage image that no visitor ever
+ * downloaded.
+ *
+ * So `src` is the widest variant at or under FALLBACK_WIDTH, and `srcset` stays
+ * complete. Costs real users nothing — they never use it.
+ *
+ * ⚠ Do NOT "fix" this by trimming the manifest's larger widths. Those are what
+ * a 2x or 3x display actually selects through `srcset`.
+ */
+const FALLBACK_WIDTH = 1024;
+const candidates = (entry.widths ?? []).filter((w) => w <= FALLBACK_WIDTH);
+const fallbackWidth = candidates.length ? Math.max(...candidates) : null;
+const fallbackSrc =
+  fallbackWidth && entry.srcset
+    ? (entry.srcset
+        .split(',')
+        .map((part) => part.trim())
+        .find((part) => part.endsWith(` ${fallbackWidth}w`))
+        ?.split(' ')[0] ?? entry.src)
+    : entry.src;
+
+/*
+ * <picture> only wraps; the <img> is still the element that lays out, carries
+ * the class, and holds width/height. Order matters — the browser takes the
+ * FIRST <source> it can decode, so AVIF comes before the WebP fallback, and
+ * the <img> is what anything without AVIF support gets.
+ *
+ * The `src` on the <img> stays WebP deliberately: it is the fallback, and the
+ * FALLBACK_WIDTH rule above still governs which width it points at.
+ *
+ * Written here and not as an HTML comment — `<!-- -->` in an Astro template
+ * body is emitted into every rendered page.
+ */
+---
+
+<picture>
+  {entry.avifSrcset && <source type="image/avif" srcset={entry.avifSrcset} sizes={sizes} />}
+  <img
+    src={fallbackSrc}
+    srcset={entry.srcset}
+    sizes={sizes}
+    width={entry.width}
+    height={entry.height}
+    alt={alt}
+    class={className}
+    loading={eager ? 'eager' : 'lazy'}
+    decoding={eager ? 'sync' : 'async'}
+    fetchpriority={priority ? 'high' : undefined}
+    style={[objectStyle, style].filter(Boolean).join('')}
+  />
+</picture>
+
+<style>
+  /*
+   * `display: contents` so <picture> adds no box.
+   *
+   * Without it the wrapper becomes an inline box between the layout parent and
+   * the image, and a grid or flex parent starts laying out the PICTURE instead
+   * of the img — `aspect-ratio`, `object-fit` and any `height: 100%` on the
+   * image quietly stop doing what they did. Nothing errors; the page just
+   * shifts, which is the worst way to find out.
+   *
+   * It does not rescue a direct-child selector: `.grid > img` no longer matches
+   * once there is a <picture> in between. Search for `> img` after turning AVIF
+   * on — see docs/traps.md.
+   */
+  picture {
+    display: contents;
+  }
+</style>

package/template/src/components/PageHero.astro

@@ -0,0 +1,88 @@
+---
+/**
+ * The opening block of an interior page: breadcrumbs, h1, optional lede.
+ *
+ * Structure only. There is no treatment here on purpose — no background, no
+ * image overlay, no gradient. What the opening of a page looks like is the
+ * single most identifying decision on the site; if it ships in the template,
+ * every site built from it opens the same way.
+ *
+ * Style it per project, or replace this component entirely. What is worth
+ * keeping is the breadcrumb markup: an ordered list inside a labelled <nav>
+ * with aria-current on the last item, which is what assistive tech and
+ * BreadcrumbList structured data both expect.
+ */
+
+interface Props {
+  title: string;
+  lede?: string;
+  breadcrumbs?: { name: string; href: string }[];
+  /** Extra classes for the section — the project's own treatment. */
+  class?: string;
+}
+
+const { title, lede, breadcrumbs, class: className = '' } = Astro.props;
+
+/* Narrowed once here rather than inside the template: a `&&` guard in an Astro
+   expression does not carry the narrowing into the callback, so `.map((crumb, i)`
+   picks up implicit `any` and stops being checked at all. */
+const crumbs = breadcrumbs ?? [];
+---
+
+<section class:list={['hero', 'under-header', 'section--tight', className]}>
+  <div class="container">
+    {
+      crumbs.length > 0 && (
+        <nav class="hero__crumbs" aria-label="Breadcrumb">
+          <ol role="list">
+            {crumbs.map((crumb, i) => (
+              <li>
+                {i < crumbs.length - 1 ? (
+                  <>
+                    <a href={crumb.href}>{crumb.name}</a>
+                    <span aria-hidden="true">/</span>
+                  </>
+                ) : (
+                  <span aria-current="page">{crumb.name}</span>
+                )}
+              </li>
+            ))}
+          </ol>
+        </nav>
+      )
+    }
+
+    <h1>{title}</h1>
+    {lede && <p class="hero__lede">{lede}</p>}
+    <slot />
+  </div>
+</section>
+
+<style>
+  .hero__crumbs ol {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--space-3xs);
+    margin-block-end: var(--space-m);
+    padding: 0;
+    list-style: none;
+    font-size: var(--step--1);
+    color: var(--text-muted);
+  }
+
+  .hero__crumbs li {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--space-3xs);
+  }
+
+  .hero__lede {
+    margin-block-start: var(--space-m);
+    font-size: var(--step-1);
+    color: var(--text-muted);
+    /* Long-form text at full container width is the most common reason a page
+       reads as a document rather than a designed thing. */
+    max-inline-size: var(--measure);
+  }
+</style>

package/template/src/components/Seo.astro

@@ -0,0 +1,119 @@
+---
+/**
+ * Every <head> tag that search engines and social scrapers read.
+ *
+ * Titles and descriptions were diffed against the Rank Math export; see
+ * docs/seo-parity.md for the table and the reason behind each difference.
+ */
+import { site, isProduction } from '../data/site';
+import { business } from '../data/business';
+import manifest from '../data/image-manifest.json';
+
+type ManifestEntry = { src: string; width: number; height: number };
+const images = manifest as Record<string, ManifestEntry>;
+
+/**
+ * Resolve a page image to the JPEG twin the media pipeline emits for social.
+ *
+ * The site serves WebP everywhere, but Facebook and LinkedIn still fail to
+ * render a WebP og:image, so a shared post would unfurl with no picture at all.
+ * Anything without a twin falls back to the branded default card.
+ */
+/*
+ * Returns null when the project has no card yet, and the tags are then OMITTED.
+ *
+ * This used to emit `/img/social/og-default.jpg` regardless, reasoning that a
+ * well-formed tag was better than a missing one. It is not: the file does not
+ * exist until `npm run media` or `npm run cards` has run, so every page
+ * advertised a card that 404s. Scrapers cache that failure, the markup looks
+ * correct, and `npm run verify` was the first thing ever to notice.
+ *
+ * A missing og:image degrades to a title-and-description unfurl. A broken one
+ * is a blank rectangle plus a cached negative. Same reasoning as
+ * `business.logoPath` in the structured data.
+ */
+function socialCard(src: string | undefined): ManifestEntry | null {
+  const fallback = images['social/og-default'] ?? null;
+  if (!src) return fallback;
+  if (src.endsWith('.jpg') || src.endsWith('.jpeg')) {
+    const direct = Object.values(images).find((entry) => entry.src === src);
+    return direct ?? fallback;
+  }
+  const name = /\/img\/[^/]+\/(.+?)(?:-\d+)?\.webp$/.exec(src)?.[1];
+  return (name && images[`social/${name}`]) || fallback;
+}
+
+interface Props {
+  title: string;
+  description: string;
+  /** Path-only canonical, e.g. "/services/". Resolved against the build host. */
+  canonical?: string;
+  image?: string;
+  imageAlt?: string;
+  type?: 'website' | 'article';
+  publishedAt?: Date;
+  updatedAt?: Date;
+  noindex?: boolean;
+}
+
+const {
+  title,
+  description,
+  canonical,
+  image,
+  imageAlt = business.name,
+  type = 'website',
+  publishedAt,
+  updatedAt,
+  noindex = false,
+} = Astro.props;
+
+const canonicalUrl = new URL(canonical ?? Astro.url.pathname, Astro.site).href;
+const card = socialCard(image);
+const imageUrl = card ? new URL(card.src, Astro.site).href : null;
+
+// Staging is never indexable, whatever the page asks for. This is derived from
+// the build variable, so there is no switch anyone can forget at go-live.
+const blockIndexing = noindex || !site.indexable;
+const robots = blockIndexing
+  ? 'noindex, nofollow'
+  : 'index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1';
+---
+
+<title>{title}</title>
+<meta name="description" content={description} />
+<meta name="robots" content={robots} />
+<link rel="canonical" href={canonicalUrl} />
+
+<meta property="og:type" content={type} />
+<meta property="og:locale" content="en_US" />
+<meta property="og:site_name" content={business.name} />
+<meta property="og:title" content={title} />
+<meta property="og:description" content={description} />
+<meta property="og:url" content={canonicalUrl} />
+{
+  card && imageUrl && (
+    <>
+      <meta property="og:image" content={imageUrl} />
+      <meta property="og:image:width" content={String(card.width)} />
+      <meta property="og:image:height" content={String(card.height)} />
+      <meta property="og:image:alt" content={imageAlt} />
+    </>
+  )
+}
+
+{publishedAt && <meta property="article:published_time" content={publishedAt.toISOString()} />}
+{updatedAt && <meta property="article:modified_time" content={updatedAt.toISOString()} />}
+
+<meta name="twitter:card" content={imageUrl ? 'summary_large_image' : 'summary'} />
+<meta name="twitter:title" content={title} />
+<meta name="twitter:description" content={description} />
+{imageUrl && <meta name="twitter:image" content={imageUrl} />}
+
+{
+  isProduction && (
+    <>
+      <link rel="alternate" type="application/rss+xml" title={`${business.name} — Insights`} href="/rss.xml" />
+    </>
+  )
+}

package/template/src/components/StructuredData.astro

@@ -0,0 +1,173 @@
+---
+/**
+ * JSON-LD, built from src/data/business.ts — the same file the visible header,
+ * footer and contact page read from. The schema physically cannot claim a
+ * phone number or an address the page does not show.
+ */
+import { business, addressOneLine } from '../data/business';
+import { services } from '../data/services';
+
+interface Props {
+  type?: 'home' | 'page' | 'article' | 'blog';
+  breadcrumbs?: { name: string; href: string }[];
+  article?: {
+    headline: string;
+    description: string;
+    image?: string;
+    publishedAt: Date;
+    updatedAt?: Date;
+    url: string;
+  };
+  faq?: { question: string; answer: string }[];
+}
+
+const { type = 'page', breadcrumbs, article, faq } = Astro.props;
+
+const siteUrl = Astro.site!.origin;
+const abs = (p: string) => new URL(p, Astro.site).href;
+
+const organizationId = `${siteUrl}/#organization`;
+const websiteId = `${siteUrl}/#website`;
+
+const organization = {
+  /* From business.ts — never hardcoded here. A subtype left in the shared
+     layer becomes every future site's industry. See the note on schemaTypes. */
+  '@type': business.schemaTypes,
+  '@id': organizationId,
+  name: business.name,
+  legalName: business.legalName,
+  url: siteUrl,
+  description: business.description,
+  foundingDate: String(business.foundedYear),
+  telephone: business.phone.e164,
+  email: business.email.display,
+  priceRange: business.priceRange,
+  /* Omitted rather than pointed at a file that may not exist — a schema logo
+     returning 404 is a Search Console warning nothing in a build would show. */
+  ...(business.logoPath ? { logo: { '@type': 'ImageObject', url: abs(business.logoPath) } } : {}),
+  image: abs('/img/social/og-default.jpg'),
+  address: {
+    '@type': 'PostalAddress',
+    streetAddress: business.address.street,
+    addressLocality: business.address.locality,
+    addressRegion: business.address.region,
+    postalCode: business.address.postalCode,
+    addressCountry: business.address.country,
+  },
+  geo: {
+    '@type': 'GeoCoordinates',
+    latitude: business.geo.latitude,
+    longitude: business.geo.longitude,
+  },
+  hasMap: business.address.mapUrl,
+  openingHoursSpecification: [
+    {
+      '@type': 'OpeningHoursSpecification',
+      dayOfWeek: business.hours.days.map((d) => `https://schema.org/${d}`),
+      opens: business.hours.opens,
+      closes: business.hours.closes,
+    },
+  ],
+  areaServed: business.serviceAreas.map((area) => ({
+    '@type': 'City',
+    name: area,
+    containedInPlace: { '@type': 'State', name: business.address.regionName },
+  })),
+  hasOfferCatalog: {
+    '@type': 'OfferCatalog',
+    name: `${business.name} services`,
+    itemListElement: services.map((s) => ({
+      '@type': 'Offer',
+      itemOffered: { '@type': 'Service', name: s.title, description: s.short },
+    })),
+  },
+  ...(business.socials.length ? { sameAs: business.socials.map((s) => s.url) } : {}),
+};
+
+const website = {
+  '@type': 'WebSite',
+  '@id': websiteId,
+  url: siteUrl,
+  name: business.name,
+  description: business.description,
+  publisher: { '@id': organizationId },
+  inLanguage: business.locale,
+};
+
+/*
+ * The page node. `type` used to be destructured and never read — Base.astro
+ * passed `schemaType` on every page and it did nothing at all, which is the
+ * quietest kind of dead prop: the call site looks correct and the output has
+ * simply never contained it.
+ */
+const PAGE_TYPE = {
+  home: 'WebPage',
+  page: 'WebPage',
+  article: 'WebPage',
+  blog: 'CollectionPage',
+} as const;
+
+const page = {
+  '@type': PAGE_TYPE[type],
+  '@id': `${abs(Astro.url.pathname)}#webpage`,
+  url: abs(Astro.url.pathname),
+  isPartOf: { '@id': websiteId },
+  about: { '@id': organizationId },
+  inLanguage: business.locale,
+};
+
+const graph: Record<string, unknown>[] = [organization, website, page];
+
+const crumbs = breadcrumbs ?? [];
+const questions = faq ?? [];
+
+if (crumbs.length) {
+  graph.push({
+    '@type': 'BreadcrumbList',
+    itemListElement: crumbs.map((crumb, i) => ({
+      '@type': 'ListItem',
+      position: i + 1,
+      name: crumb.name,
+      item: abs(crumb.href),
+    })),
+  });
+}
+
+if (article) {
+  graph.push({
+    '@type': 'BlogPosting',
+    headline: article.headline,
+    description: article.description,
+    ...(article.image ? { image: abs(article.image) } : {}),
+    datePublished: article.publishedAt.toISOString(),
+    dateModified: (article.updatedAt ?? article.publishedAt).toISOString(),
+    author: { '@id': organizationId },
+    publisher: { '@id': organizationId },
+    mainEntityOfPage: { '@type': 'WebPage', '@id': abs(article.url) },
+    isPartOf: { '@id': websiteId },
+  });
+}
+
+if (questions.length) {
+  graph.push({
+    '@type': 'FAQPage',
+    mainEntity: questions.map((item) => ({
+      '@type': 'Question',
+      name: item.question,
+      acceptedAnswer: { '@type': 'Answer', text: item.answer },
+    })),
+  });
+}
+
+const jsonLd = { '@context': 'https://schema.org', '@graph': graph };
+---
+
+<script
+  type="application/ld+json"
+  is:inline
+  set:html={JSON.stringify(jsonLd)}
+/>
+<meta name="geo.placename" content={`${business.address.locality}, ${business.address.regionName}`} />
+<meta name="geo.position" content={`${business.geo.latitude};${business.geo.longitude}`} />
+<meta name="geo.region" content={`${business.address.country}-${business.address.region}`} />
+<meta name="business:contact_data:street_address" content={addressOneLine} />

package/template/src/content/blog/.gitkeep

@@ -0,0 +1,5 @@
+Posts go here as markdown. `docs/content.md` has the frontmatter and the rules.
+
+This file exists so the directory ships. Without it Astro's glob loader warns
+"The base directory src/content/blog/ does not exist" on every single build,
+and `npm run media` threw ENOENT looking for posts to twin social cards for.

package/template/src/content.config.ts

@@ -0,0 +1,81 @@
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+/**
+ * Blog posts. The schema is strict on purpose: a bad edit fails the build
+ * rather than shipping a page with a missing title or a broken date.
+ */
+const blog = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './src/content/blog' }),
+  schema: z.object({
+    title: z.string().min(1).max(120),
+    /** Overrides <title>; falls back to `title` when absent. */
+    seoTitle: z.string().max(120).optional(),
+    description: z.string().min(50).max(200),
+    publishedAt: z.coerce.date(),
+    updatedAt: z.coerce.date().optional(),
+    /** Portable reference into public/img — never an absolute CDN URL. */
+    image: z.string().optional(),
+    imageAlt: z.string().optional(),
+    categories: z.array(z.string()).min(1),
+    focusKeyword: z.string().optional(),
+    draft: z.boolean().default(false),
+  }),
+});
+
+/**
+ * Legal and policy pages — privacy, terms, house rules, cookie notice.
+ *
+ * One markdown file each, rendered through one route, so three near-identical
+ * page files never get written and an editor can change an effective date
+ * without a developer. Empty in a fresh template: it emits no routes until
+ * somebody adds a file, which is why shipping it costs the template no pages.
+ *
+ * ── DATES ARE STRINGS HERE, DELIBERATELY ───────────────────────────────────
+ * `z.coerce.date()` turns `2026-08-21` into 2026-08-21T00:00:00**Z**, and
+ * formatting that instant anywhere west of Greenwich renders **20 August** —
+ * measured: US Pacific and US Eastern both shift it, London and Tokyo do not.
+ * So a legal page's effective date is correct on a European laptop and a day
+ * early off a US CI runner, with nothing anywhere to report it.
+ *
+ * An effective date is a CALENDAR DATE, not an instant. Keeping it a string
+ * removes the class of bug rather than handling it. `formatLegalDate` in
+ * lib/legal.ts renders it, pinned to UTC.
+ */
+const isoDate = z
+  .preprocess(
+    /*
+     * ⚠ ASTRO'S FRONTMATTER PARSER RETURNS A **Date** FOR AN UNQUOTED
+     * `2026-08-21`, not a string — which is where this whole class of bug
+     * starts, and it is invisible until something formats it. Editors write
+     * dates unquoted because that is the natural thing to write, so accept
+     * both and normalise to the UTC calendar date immediately. After this
+     * point the value is a plain string and cannot drift again.
+     */
+    (value) => (value instanceof Date ? value.toISOString().slice(0, 10) : value),
+    z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/, 'use YYYY-MM-DD')
+      /* The regex accepts 2026-13-45. Confirm it is a date that exists. */
+      .refine((v) => new Date(`${v}T00:00:00Z`).toISOString().startsWith(v), 'not a real date'),
+  );
+
+const legal = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './src/content/legal' }),
+  schema: z.object({
+    title: z.string().min(1).max(120),
+    description: z.string().min(50).max(200),
+    /** The date the terms took effect. Shown on the page. */
+    effective: isoDate,
+    /** Only when it has genuinely changed since. Omit otherwise. */
+    updated: isoDate.optional(),
+    /** Footer link text, when the title is too long for it. */
+    navLabel: z.string().max(40).optional(),
+    /** Footer ordering, low first. Ties fall back to the title. */
+    order: z.number().default(50),
+    /** A page that must exist and must not be indexed — rare, but real. */
+    noindex: z.boolean().default(false),
+  }),
+});
+
+export const collections = { blog, legal };

package/template/src/data/areas.ts

@@ -0,0 +1,31 @@
+/**
+ * Service-area landing pages: one template, one entry each.
+ *
+ * ── ONLY add a place you can describe distinctly. ──────────────────────────
+ * Pages that differ by nothing but the town name are doorway pages and can be
+ * penalised. Each needs something genuinely local: which authority issues the
+ * permit, what the housing stock is, what actually drives demand there.
+ *
+ * A place you cannot write about distinctly still belongs in
+ * business.serviceAreas — it just does not get a page.
+ *
+ * Leave this array empty if the business is not service-area based.
+ */
+
+export type Area = {
+  slug: string;
+  city: string;
+  category?: string; // matches a blog category, so the page can pull its own articles
+  county: string;
+  permitAuthority: string; // or whatever the local gatekeeper is in your field
+  title: string;
+  description: string;
+  intro: string;
+  localFactors: { heading: string; body: string }[]; // three, no filler
+  commonWork: string[];
+  image: string; // manifest key
+};
+
+export const areas: Area[] = [];
+
+export const areaBySlug = (slug: string) => areas.find((area) => area.slug === slug);