create-website-build-kit 0.1.0

package/template/scripts/lib/inventory.mjs

@@ -0,0 +1,104 @@
+/**
+ * The old site's URL inventory — one reader, one format.
+ *
+ * `recon` writes `recon/urls.txt` and SKILL.md calls it "the inventory every
+ * later step reads". Three things read it — `redirects`, `shots` and the
+ * coverage check in `verify` — and until this module they each parsed it
+ * themselves, differently:
+ *
+ *   redirects  kept every line that was not blank or a `#` comment
+ *   shots      kept every line starting with `/`
+ *
+ * Which is fine until a real inventory turns up that does not match. One did:
+ * a file of ABSOLUTE URLs (`https://site.com/about/`) rather than paths,
+ * hand-made rather than written by `recon`. `redirects` then compared
+ * `https://site.com/about/` against `/about/` and matched nothing, proposing an
+ * empty map; `shots` found zero paths and silently reported the migration as
+ * greenfield with no before side. Neither said anything was wrong.
+ *
+ * So: both forms are accepted here, once, and every consumer gets the same
+ * answer. Same reason `lib/routes.mjs` and `lib/preserved.mjs` exist.
+ *
+ * ── ALREADY-DEAD URLS ARE MARKED, NOT DROPPED ─────────────────────────────
+ * `recon` pulls URLs from the Wayback Machine, and some of them were ALREADY
+ * 404 on the old site. They belong in the inventory — they still hold
+ * backlinks, so they are redirect targets — but they are not pages the
+ * migration lost. A coverage check that failed on them would go red on every
+ * healthy migration, and a check that goes red for a non-reason gets switched
+ * off. recon tags them; this reports them separately.
+ */
+
+/** Lines tagged with this were 404 on the OLD site before the migration began. */
+export const GONE_TAG = '# gone-on-old-site';
+
+/**
+ * Parse an inventory file's contents.
+ *
+ * Returns `{ live, gone, origin }` — `live` and `gone` are arrays of paths.
+ * Accepts paths and absolute URLs interchangeably.
+ */
+export function parseInventory(text) {
+  const live = [];
+  const gone = [];
+  let origin = '';
+
+  for (const raw of text.split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+
+    if (line.startsWith('#')) {
+      /* `# Inventory of https://old-site.com` — the only header worth keeping. */
+      const found = /Inventory of\s+(https?:\/\/\S+)/i.exec(line);
+      if (found) origin = found[1].replace(/\/$/, '');
+      continue;
+    }
+
+    const isGone = line.includes(GONE_TAG);
+    const value = line.split('#')[0].trim();
+    if (!value) continue;
+
+    /*
+     * Absolute or relative, the answer is the path. A hand-made inventory of
+     * absolute URLs is the case that broke two scripts silently.
+     */
+    let path;
+    if (/^https?:\/\//i.test(value)) {
+      try {
+        const u = new URL(value);
+        path = u.pathname + u.search;
+        if (!origin) origin = u.origin;
+      } catch {
+        continue;
+      }
+    } else if (value.startsWith('/')) {
+      path = value;
+    } else {
+      continue; // not a path or a URL — prose, or a stray line
+    }
+
+    (isGone ? gone : live).push(path);
+  }
+
+  return {
+    live: [...new Set(live)].sort(),
+    gone: [...new Set(gone)].sort(),
+    origin,
+  };
+}
+
+/**
+ * Read the inventory from disk, or null when there is none.
+ *
+ * Null is the normal greenfield answer, not an error: there is no old site, so
+ * there is nothing to have lost. Callers report it rather than failing.
+ */
+export function readInventory(readFileSync, file = 'recon/urls.txt') {
+  let text;
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  const parsed = parseInventory(text);
+  return parsed.live.length || parsed.gone.length ? parsed : null;
+}

package/template/scripts/lib/preserved.mjs

@@ -0,0 +1,42 @@
+/**
+ * Paths other systems point at, which must keep resolving after a migration.
+ *
+ * Shared by `recon` (which finds them on the OLD site) and `verify` (which
+ * confirms they still resolve on the NEW one). Those were two separate lists
+ * until they were not: recon reported that `/feed/` had to survive and nothing
+ * ever checked whether it had. A list in one file cannot drift from itself.
+ *
+ * `build.md` §7 names this as a definition-of-done row. See `stacks.md` §1d for
+ * why each one is silent when it breaks.
+ */
+
+export const PRESERVED = [
+  ['/robots.txt', 'The Sitemap: line is the discovery route for every crawler'],
+  ['/ads.txt', 'Programmatic revenue stops without it, with no error anywhere'],
+  ['/app-ads.txt', 'Same, for apps'],
+  ['/BingSiteAuth.xml', 'Bing ownership verification'],
+  ['/feed/', 'Subscribers and syndication partners — 301, never drop'],
+  ['/comments/feed/', 'Same'],
+  ['/rss.xml', 'Same'],
+  ['/.well-known/security.txt', 'Copy the .well-known directory wholesale'],
+  ['/.well-known/apple-app-site-association', 'App deep links break silently'],
+  ['/favicon.ico', 'Referenced by things that never re-read your HTML'],
+];
+
+/**
+ * Read back what `recon` actually found on the old site, so `verify` checks
+ * the paths that MATTERED for this migration rather than the generic list.
+ *
+ * Returns null when there is no recon output — a greenfield build has no old
+ * site, and inventing an expectation there would be noise.
+ */
+export function preservedFromRecon(readFileSync) {
+  try {
+    const md = readFileSync('recon/preserved.md', 'utf8');
+    const section = md.split('## Present on the old site')[1]?.split('##')[0] ?? '';
+    const paths = [...section.matchAll(/^\|\s*`([^`]+)`/gm)].map((m) => m[1]);
+    return paths.length ? paths : null;
+  } catch {
+    return null;
+  }
+}

package/template/scripts/lib/routes.mjs

@@ -0,0 +1,92 @@
+/**
+ * Discover the site's routes, without a list anyone has to maintain.
+ *
+ * A hardcoded route array in a script is a second source of truth for what the
+ * site contains. It goes stale silently — the script keeps passing while
+ * testing pages that no longer exist and skipping the ones that do — and it is
+ * how one project's routes ended up shipped inside this template.
+ *
+ * Production: the deployed sitemap, which is what a crawler sees.
+ * Staging or local: dist/, because staging emits no sitemap by design.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/** Routes this build emitted, as absolute paths. 404 is excluded — it is not a route. */
+export function routesFromDist() {
+  const root = ['dist/client', 'dist'].find((d) => existsSync(d));
+  if (!root) return [];
+
+  const walk = (dir) =>
+    readdirSync(dir).flatMap((entry) => {
+      const full = join(dir, entry);
+      return statSync(full).isDirectory() ? walk(full) : [full];
+    });
+
+  return walk(root)
+    .filter((f) => f.endsWith('.html') && !f.endsWith('404.html'))
+    .map((f) => '/' + relative(root, f).replace(/index\.html$/, '').replace(/\.html$/, '/'))
+    .map((p) => (p.endsWith('/') ? p : `${p}/`))
+    .sort();
+}
+
+/**
+ * Every `<loc>` in the deployed sitemap, following the index to its children.
+ * Returns [] when there is no sitemap, which is the normal staging case.
+ */
+export async function routesFromSitemap(origin, fetcher = fetch) {
+  const get = async (url) => {
+    try {
+      const res = await fetcher(url);
+      return res.status === 200 ? await res.text() : '';
+    } catch {
+      return '';
+    }
+  };
+
+  const locs = (xml) => [...xml.matchAll(/<loc>([^<]+)<\/loc>/g)].map((m) => m[1]);
+
+  /*
+   * A sitemap index lists its children as ABSOLUTE URLs at the host the build
+   * was made for. Following them literally means a local preview of a
+   * production build fetches example.com's sitemap, gets nothing, and silently
+   * falls back to dist/ — reporting fewer routes than the site has, with no
+   * error. Re-root onto the origin being asked about; a no-op when they match.
+   */
+  const reroot = (url) => {
+    try {
+      const u = new URL(url);
+      return u.origin === new URL(origin).origin ? url : new URL(u.pathname + u.search, origin).href;
+    } catch {
+      return url;
+    }
+  };
+
+  const index = await get(`${origin}/sitemap-index.xml`);
+  const maps = index ? locs(index).map(reroot) : [`${origin}/sitemap-0.xml`];
+
+  const out = [];
+  for (const map of maps) out.push(...locs(await get(map)));
+  return [...new Set(out.map(reroot))].sort();
+}
+
+/**
+ * Sitemap first, dist/ as the fallback. Returns absolute URLs plus a `source`
+ * string, so a caller can say where its list came from — a route list of
+ * unclear origin is the thing this module exists to prevent.
+ */
+export async function discoverRoutes(origin, fetcher = fetch) {
+  const fromSitemap = await routesFromSitemap(origin, fetcher);
+  if (fromSitemap.length) return { routes: fromSitemap, source: 'the deployed sitemap' };
+
+  const fromDist = routesFromDist();
+  if (fromDist.length) {
+    return {
+      routes: fromDist.map((p) => origin + p),
+      source: 'dist/ (no sitemap — expected on staging)',
+    };
+  }
+
+  return { routes: [], source: 'nothing — no sitemap and no dist/' };
+}

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

@@ -0,0 +1,335 @@
+/**
+ * Render a markdown document to a PDF in the project's own type and palette.
+ *
+ *   node scripts/md-to-pdf.mjs docs/client-note.md
+ *   node scripts/md-to-pdf.mjs docs/client-note.md out/note.pdf
+ *
+ * For client-facing documents — proposals, estimates, handover notes. Point it
+ * at the site's own typefaces (see PROJECT CONFIG below) and a PDF you send
+ * looks like the site you built, rather than a text file someone printed. It
+ * runs on a fresh template too, in the system stack.
+ *
+ * ── WHY A HAND-ROLLED CONVERTER ────────────────────────────────────────────
+ * There is no pandoc, python-markdown or weasyprint on this machine, and
+ * adding a markdown library to a static marketing site's dependencies to
+ * format the occasional proposal is a poor trade. This handles the subset our
+ * docs actually use: headings, tables, lists, bold, italic, links, code, rules
+ * and paragraphs. It is not a spec-compliant parser and does not pretend to be
+ * — if a document stops rendering correctly, the document is using something
+ * this does not support, and the fix is either to add it here or to simplify
+ * the document.
+ *
+ * Chrome comes from puppeteer, which arrives as part of pa11y-ci — already a
+ * devDependency for the accessibility suite, so this adds nothing. The Chrome
+ * binary itself lives in a shared ~/.cache/puppeteer, not in node_modules.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, basename, resolve } from 'node:path';
+
+import puppeteer from 'puppeteer';
+
+const [, , input, outputArg] = process.argv;
+if (!input) {
+  console.error('usage: node scripts/md-to-pdf.mjs <file.md> [out.pdf]');
+  process.exit(1);
+}
+const output = outputArg ?? input.replace(/\.md$/, '.pdf');
+
+/* ── Markdown → HTML ───────────────────────────────────────────────────── */
+
+const esc = (s) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+/** Inline formatting. Order matters: code first, so its contents are literal. */
+function inline(text) {
+  const codes = [];
+  let s = text.replace(/`([^`]+)`/g, (_, c) => {
+    codes.push(c);
+    return `\u0000${codes.length - 1}\u0000`;
+  });
+  s = esc(s);
+  s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+  s = s.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  s = s.replace(/(^|[^*])\*([^*]+)\*/g, '$1<em>$2</em>');
+  s = s.replace(/\u0000(\d+)\u0000/g, (_, i) => `<code>${esc(codes[Number(i)])}</code>`);
+  return s;
+}
+
+const splitRow = (line) =>
+  line
+    .trim()
+    .replace(/^\||\|$/g, '')
+    .split('|')
+    .map((c) => c.trim());
+
+function toHtml(md) {
+  const lines = md.split('\n');
+  const out = [];
+  let i = 0;
+  let list = null;
+
+  const closeList = () => {
+    if (list) {
+      out.push(`</${list}>`);
+      list = null;
+    }
+  };
+
+  while (i < lines.length) {
+    const line = lines[i];
+
+    if (/^\s*$/.test(line)) {
+      closeList();
+      i++;
+      continue;
+    }
+
+    if (/^---+\s*$/.test(line)) {
+      closeList();
+      out.push('<hr>');
+      i++;
+      continue;
+    }
+
+    const h = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (h) {
+      closeList();
+      out.push(`<h${h[1].length}>${inline(h[2])}</h${h[1].length}>`);
+      i++;
+      continue;
+    }
+
+    // Table: a header row followed by a |---|---| separator.
+    if (line.includes('|') && /^\s*\|?[\s:-]*-[\s:|-]*\|/.test(lines[i + 1] ?? '')) {
+      closeList();
+      const head = splitRow(line);
+      i += 2;
+      const rows = [];
+      while (i < lines.length && lines[i].includes('|') && lines[i].trim()) {
+        rows.push(splitRow(lines[i]));
+        i++;
+      }
+      out.push('<table><thead><tr>');
+      head.forEach((c) => out.push(`<th>${inline(c)}</th>`));
+      out.push('</tr></thead><tbody>');
+      rows.forEach((r) => {
+        out.push('<tr>');
+        r.forEach((c) => out.push(`<td>${inline(c)}</td>`));
+        out.push('</tr>');
+      });
+      out.push('</tbody></table>');
+      continue;
+    }
+
+    const li = /^\s*([-*]|\d+\.)\s+(.*)$/.exec(line);
+    if (li) {
+      const want = /^\d/.test(li[1]) ? 'ol' : 'ul';
+      if (list !== want) {
+        closeList();
+        out.push(`<${want}>`);
+        list = want;
+      }
+      // Continuation lines are indented under the marker.
+      let body = li[2];
+      while (/^\s{2,}\S/.test(lines[i + 1] ?? '') && !/^\s*([-*]|\d+\.)\s/.test(lines[i + 1])) {
+        body += ' ' + lines[++i].trim();
+      }
+      out.push(`<li>${inline(body)}</li>`);
+      i++;
+      continue;
+    }
+
+    /* Consecutive `>` lines are ONE blockquote. Emitting one per line gives
+       each its own border and margin, so a five-line note renders as five
+       stacked quotes with gaps through it — which is what a long callout in a
+       handover document looks like if you do not do this. A blank `>` line
+       starts a new paragraph inside the same quote. */
+    if (/^>\s?/.test(line)) {
+      closeList();
+      const quoted = [];
+      while (i < lines.length && /^>/.test(lines[i])) {
+        quoted.push(lines[i].replace(/^>\s?/, ''));
+        i++;
+      }
+      const paras = quoted
+        .join('\n')
+        .split(/\n\s*\n/)
+        .map((p) => p.trim().replace(/\n/g, ' '))
+        .filter(Boolean);
+      out.push(`<blockquote>${paras.map((p) => `<p>${inline(p)}</p>`).join('')}</blockquote>`);
+      continue;
+    }
+
+    // Paragraph: gather until a blank line or a block-level marker.
+    closeList();
+    let para = line;
+    while (
+      i + 1 < lines.length &&
+      lines[i + 1].trim() &&
+      !/^(#{1,6}\s|---+\s*$|>\s?|\s*([-*]|\d+\.)\s)/.test(lines[i + 1]) &&
+      !lines[i + 1].includes('|')
+    ) {
+      para += ' ' + lines[++i].trim();
+    }
+    out.push(`<p>${inline(para)}</p>`);
+    i++;
+  }
+  closeList();
+  return out.join('\n');
+}
+
+/* ── Page ──────────────────────────────────────────────────────────────── */
+
+const md = readFileSync(input, 'utf8');
+const title = (/^#\s+(.*)$/m.exec(md)?.[1] ?? basename(input, '.md')).trim();
+
+/*
+ * ⚠ PROJECT CONFIG — the type and the palette.
+ *
+ * Defaults are the system stack and a neutral ink ramp, so this runs on a fresh
+ * template and produces a plain, readable document. Point BODY_FONT and
+ * DISPLAY_FONT at the project's own woff2 in public/fonts/ and the PDF starts
+ * looking like the site — which is the whole reason to send one.
+ *
+ * Mirror the colours from src/styles/tokens.css. Do not invent values here.
+ *
+ * A missing font file is not an error: the document falls back to the system
+ * stack and says so, rather than refusing to render a proposal because a
+ * typeface moved.
+ */
+const BODY_FONT = null; // e.g. 'display.woff2'
+const DISPLAY_FONT = null; // e.g. 'script.woff2', for the H1 only
+const PALETTE = { ink: '#14171a', muted: '#5b656e', accent: '#454e56', line: '#c7ced4' };
+
+const fontDir = resolve('public/fonts');
+const face = (family, file, weight) => {
+  if (!file) return '';
+  try {
+    const b64 = readFileSync(resolve(fontDir, file)).toString('base64');
+    return `@font-face{font-family:'${family}';src:url(data:font/woff2;base64,${b64}) format('woff2');${weight}}`;
+  } catch {
+    console.warn(`md-to-pdf: ${file} not found in public/fonts — falling back to the system stack.`);
+    return '';
+  }
+};
+
+const bodyStack = `${BODY_FONT ? "'DocBody', " : ''}system-ui, sans-serif`;
+const displayStack = `${DISPLAY_FONT ? "'DocDisplay', " : ''}${bodyStack}`;
+
+const html = `<!doctype html><html><head><meta charset="utf-8"><title>${esc(title)}</title>
+<style>
+  ${face('DocBody', BODY_FONT, 'font-weight:100 900;')}
+  ${face('DocDisplay', DISPLAY_FONT, '')}
+  @page { size: A4; margin: 18mm 16mm 20mm; }
+
+  :root {
+    --ink: ${PALETTE.ink};
+    --muted: ${PALETTE.muted};
+    --accent: ${PALETTE.accent};
+    --line: ${PALETTE.line};
+  }
+
+  body {
+    font-family: ${bodyStack};
+    color: var(--ink);
+    font-size: 10.5pt;
+    line-height: 1.55;
+    margin: 0;
+  }
+
+  h1 {
+    font-family: ${displayStack};
+    font-size: 30pt;
+    font-weight: 400;
+    line-height: 1.1;
+    margin: 0 0 4mm;
+  }
+  h2 {
+    font-size: 15pt;
+    font-weight: 600;
+    margin: 9mm 0 3mm;
+    /* A heading stranded at the foot of a page is the classic PDF tell. */
+    break-after: avoid;
+  }
+  h3 { font-size: 12pt; font-weight: 600; margin: 6mm 0 2mm; break-after: avoid; }
+
+  p { margin: 0 0 3.5mm; }
+  strong { font-weight: 600; }
+  em { font-style: italic; color: var(--muted); }
+  a { color: var(--accent); text-decoration: underline; text-underline-offset: 2px; }
+  code {
+    font-family: ui-monospace, monospace;
+    font-size: 9.5pt;
+    background: color-mix(in srgb, var(--line) 35%, white);
+    padding: 0 2px;
+    border-radius: 2px;
+  }
+
+  hr { border: 0; border-block-start: 1px solid var(--line); margin: 7mm 0; }
+
+  ul, ol { margin: 0 0 4mm; padding-inline-start: 6mm; }
+  li { margin-block-end: 1.5mm; }
+
+  table {
+    inline-size: 100%;
+    border-collapse: collapse;
+    margin: 0 0 5mm;
+    font-size: 10pt;
+    /* Keep a table whole where it fits — a two-row orphan reads as an error. */
+    break-inside: avoid;
+  }
+  th, td {
+    text-align: start;
+    padding: 2mm 3mm 2mm 0;
+    border-block-end: 1px solid var(--line);
+    vertical-align: top;
+  }
+  th { font-weight: 600; border-block-end-color: var(--ink); }
+
+  blockquote p:last-child { margin-bottom: 0; }
+  blockquote {
+    margin: 0 0 4mm;
+    padding-inline-start: 4mm;
+    border-inline-start: 2px solid var(--accent);
+    color: var(--muted);
+  }
+
+  /* The closing note, set quieter than the body. */
+  body > p:last-of-type em { font-size: 9pt; }
+</style></head><body>
+${toHtml(md)}
+</body></html>`;
+
+/*
+ * Both temp files carry the PID. Two concurrent runs otherwise write and then
+ * delete each other's files, and the failure reads as a corrupt document rather
+ * than a collision.
+ */
+const tmp = `.md-pdf.${process.pid}.html`;
+writeFileSync(tmp, html);
+
+/*
+ * puppeteer is a devDependency (it arrives with pa11y-ci), so a bare import
+ * resolves normally.
+ *
+ * This used to locate Chrome by searching $HOME/.npm/_npx for whatever
+ * puppeteer an `npx --yes pa11y-ci` had left behind, then write a runner script
+ * INSIDE that directory so a bare import would resolve — because NODE_PATH is a
+ * CommonJS mechanism that ESM ignores. It worked, took the first of however
+ * many cached copies existed, and broke whenever the cache was cleared.
+ * Declaring the dependency deleted all of it.
+ */
+mkdirSync(dirname(resolve(output)), { recursive: true });
+
+const browser = await puppeteer.launch({ args: ['--no-sandbox'] });
+try {
+  const page = await browser.newPage();
+  await page.goto(`file://${resolve(tmp)}`, { waitUntil: 'networkidle0' });
+  await page.pdf({ path: resolve(output), format: 'A4', printBackground: true });
+} finally {
+  await browser.close();
+  rmSync(tmp, { force: true });
+}
+
+console.log(`${output}`);

package/template/scripts/og-cards.config.mjs

@@ -0,0 +1,114 @@
+/**
+ * ⚠ PROJECT CONFIG for `npm run cards`. The template ships this as a STUB.
+ *
+ * Everything a designer chooses lives here. scripts/og-cards.mjs holds only the
+ * machinery — the crop-safe box, the contrast measurement, the composite order —
+ * and none of it renders until this file is filled in.
+ *
+ * That split is deliberate. A social card is the one image the whole internet
+ * sees before it sees the site, so it has to carry the project's identity and
+ * not the kit's. A generator that shipped with a palette and a type scale would
+ * give every site built from this kit the same card.
+ *
+ * Fill this in AFTER the design exists — you need the real ramp, the two faces
+ * in public/fonts/, and a wordmark. `npm run cards` refuses until then, with a
+ * message saying which of them is missing.
+ *
+ * Prerequisites for the generator itself: ImageMagick, rsvg-convert, and
+ * python3 with fontTools. See docs/runbook.md §1.
+ */
+
+/**
+ * Colours, as hex. MIRROR src/styles/tokens.css — do not invent values here.
+ * ImageMagick cannot read CSS custom properties, which is the only reason these
+ * are duplicated at all. Two copies drift; check them when the ramp changes.
+ *
+ *   ink     the plain card's ground, for legal and utility pages
+ *   veil    the wash laid over a photograph so type has something to sit on.
+ *           Usually the darkest ink in the ramp
+ *   fg      title and footer over a photograph. Usually the lightest
+ *   accent  eyebrow and footer on the PLAIN card only. A mid tone has nothing
+ *           left to give once a photograph is underneath — see og-cards.mjs
+ */
+export const PALETTE = null;
+// export const PALETTE = { ink: '#…', veil: '#…', fg: '#…', accent: '#…' };
+
+/**
+ * The project's own two faces, as paths to the woff2 the SITE serves.
+ *
+ * Converted to TTF at run time rather than committed as a second copy: one
+ * source of truth, and a card that cannot drift from what the page renders.
+ * Keep in step with the @font-face block in src/styles/global.css.
+ */
+export const FONTS = null;
+// export const FONTS = {
+//   title:   'public/fonts/display.woff2',
+//   eyebrow: 'public/fonts/display.woff2',   // a second face here if there is one
+// };
+
+/**
+ * The logo, read from the component that already draws it — never committed as
+ * a second copy of the artwork. A shared link that unfurls with different
+ * branding reads as a different business, and two copies drift.
+ *
+ *   source  a file containing one <svg> with a viewBox and <path d="…">
+ *   width   drawn width in px. Roughly a quarter of the 1200px card reads at
+ *           the size a timeline actually renders it
+ *
+ * Set to null for cards with no logo. If the project has no wordmark component,
+ * point `source` at a static SVG — but keep it generated from ONE source.
+ */
+export const WORDMARK = null;
+// export const WORDMARK = { source: 'src/components/Wordmark.astro', width: 300 };
+
+/**
+ * Type scale, in px. The title size is picked by line count, so a long headline
+ * shrinks rather than overflowing.
+ */
+export const TYPE = {
+  title: { 1: 94, 2: 82, 3: 72 },
+  eyebrow: 54,
+  footer: 23,
+};
+
+/**
+ * The footer line, on every card. Keep it short — it is set small, and it is
+ * the first thing a hard crop takes.
+ *
+ * Read it from src/data/business.ts rather than typing it twice, if you prefer;
+ * this file is plain JavaScript and can import.
+ */
+export const FOOTER = '';
+// export const FOOTER = 'Town, State   ·   example.com';
+
+/**
+ * One row per page. Adding a page means adding a row and re-running — Seo.astro
+ * resolves the card from the canonical path, so there is nothing to wire.
+ *
+ *   route    the URL this card belongs to. '/' becomes og-home.jpg
+ *   slug     optional name override. Only the fallback needs one
+ *   title    the headline. NOT the <title> tag — that carries "| Business Name"
+ *            for search, which is wasted space on a card that already shows the
+ *            name. `\n` is a deliberate line break
+ *   eyebrow  small line in the second face above the title, or null
+ *   photo    manifest key for the background, or null for the plain card
+ *
+ * Legal and utility pages take the plain card: a photograph on a privacy policy
+ * is decoration pretending to be information.
+ *
+ * ── THE FALLBACK ROW IS NOT OPTIONAL ──────────────────────────────────────
+ * The last row, with `slug: 'default'` and no route, is the card every page
+ * without one of its own gets. Generate it; never hand-make it.
+ *
+ * A hand-made og-default.jpg goes stale silently. On one site the artwork
+ * predated a rebrand by two days and went on serving the old wordmark from a
+ * live site — the file existed, the manifest entry was valid, the build was
+ * green, and the only page using it was one nobody opens. Generating it means
+ * changing the type or the ink changes the fallback too.
+ */
+export const CARDS = [];
+// export const CARDS = [
+//   { route: '/',         title: 'A headline for\nthe home page.', eyebrow: 'Welcome',   photo: 'photos/hero' },
+//   { route: '/contact/', title: 'Contact us',                     eyebrow: 'Say hello', photo: null },
+//   { slug: 'default', route: null, title: 'A one-line\ndescription.', eyebrow: null, photo: 'photos/hero' },
+// ];