branding-engine 0.1.0

package/src/lib/render.mjs

@@ -0,0 +1,56 @@
+// Shared headless-Chromium plumbing for the renderers that need live text (the
+// social cards and the brand sheet; the mark and wordmark are pure SVG and need
+// none of this). Centralizes the @font-face embed and the launch / fonts-ready /
+// close dance, and lets a whole build reuse one browser instead of launching one
+// per kit.
+import { readFileSync } from 'node:fs';
+import { fontPath } from './font.mjs';
+
+// The bundled font embedded as a data URI, as an @font-face for `family`.
+export function fontFaceCss(family) {
+  const b64 = readFileSync(fontPath()).toString('base64');
+  return `@font-face{font-family:${family};font-weight:200 900;font-display:block;` +
+    `src:url(data:font/woff2;base64,${b64}) format('woff2')}`;
+}
+
+// Playwright is an optional dependency: only the sheet and social-card renderers
+// need a browser, so it's imported lazily. The mark/wordmark/icons path never
+// touches this and installs lean.
+export async function launchBrowser() {
+  let chromium;
+  try {
+    ({ chromium } = await import('@playwright/test'));
+  } catch {
+    throw new Error(
+      'Brand sheets and social cards need Playwright. Install it with:\n' +
+        '  npm i -D @playwright/test && npx playwright install chromium\n' +
+        'The mark, wordmark, and icons need none of this.',
+    );
+  }
+  return chromium.launch();
+}
+
+// Open a page on `browser`, load `html`, wait for webfonts, hand the page to
+// `fn` (which takes the screenshots), and always close the page. The browser is
+// the caller's to own and reuse.
+export async function withPage(browser, { html, viewport, deviceScaleFactor = 2 }, fn) {
+  const page = await browser.newPage({ viewport, deviceScaleFactor });
+  try {
+    await page.setContent(html, { waitUntil: 'load' });
+    await page.evaluate(async () => { await document.fonts.ready; });
+    return await fn(page);
+  } finally {
+    await page.close();
+  }
+}
+
+// For one-off CLIs: launch a browser just for `fn`, then close it. The build
+// passes its own shared browser to withPage directly instead.
+export async function withBrowser(fn) {
+  const browser = await launchBrowser();
+  try {
+    return await fn(browser);
+  } finally {
+    await browser.close();
+  }
+}

package/src/lib/wordmark.mjs

@@ -0,0 +1,100 @@
+// Build a horizontal lockup as a single self-contained SVG: the mark tile, then
+// the name set in real Inter outlines, on one baseline. No raster, no headless
+// browser. The tile keeps its surface accent (white glyph); the text ink is
+// `currentColor` by default, so one SVG serves both light and dark backgrounds.
+//
+// Outlines come from the wordmark glyph cache (extracted at the wordmark weight,
+// which is lighter than the mark's), so this stays pure node like mark.mjs.
+import { markSvg } from './mark.mjs';
+import { normalizeHex } from './color.mjs';
+import { loadGlyphs, wordmarkGlyphFile } from './glyphs.mjs';
+
+// Proportions are expressed against the tile so the lockup scales as one unit.
+// The 128/36/96 ratios match the original lockup; letter-spacing matches the
+// site's .brand (caps) and the title-case lockup respectively.
+const TILE = 256;
+const PAD = (TILE * 24) / 128; // breathing room around the lockup
+const GAP = (TILE * 36) / 128; // tile-to-text gap
+const FONT_PX = (TILE * 96) / 128; // text size relative to the tile
+const LETTER_SPACING = { title: -0.03125, caps: -0.02 }; // em
+
+// Read glyphs lazily so a cache (re)written earlier in the same process, or a
+// BRAND_WORDMARK_GLYPHS set by build.mjs, is honored on first render.
+let _glyphData;
+function glyphData() {
+  if (!_glyphData) _glyphData = loadGlyphs(wordmarkGlyphFile());
+  return _glyphData;
+}
+
+// Lay the text out in font units and measure its ink box. Blank glyphs (space)
+// carry advance but no path, so they push the pen without affecting the bounds.
+function layoutText(text, letterSpacingEm) {
+  const { unitsPerEm, glyphs } = glyphData();
+  const ls = letterSpacingEm * unitsPerEm;
+  const chars = [...text];
+  let penX = 0;
+  const placed = [];
+  chars.forEach((ch, i) => {
+    const g = glyphs[ch];
+    if (!g) {
+      throw new Error(
+        `No wordmark outline for "${ch}". Available: ${Object.keys(glyphs).join('')}. ` +
+          `Re-run with this text so build extracts it, or extend ${wordmarkGlyphFile()}.`,
+      );
+    }
+    placed.push({ x: penX, g });
+    penX += g.advance + (i < chars.length - 1 ? ls : 0);
+  });
+  let xMin = Infinity, xMax = -Infinity, yMin = Infinity, yMax = -Infinity;
+  for (const { x, g } of placed) {
+    if (!g.path) continue;
+    xMin = Math.min(xMin, x + g.bounds.xMin);
+    xMax = Math.max(xMax, x + g.bounds.xMax);
+    yMin = Math.min(yMin, g.bounds.yMin);
+    yMax = Math.max(yMax, g.bounds.yMax);
+  }
+  return { placed, xMin, xMax, cy: (yMin + yMax) / 2 };
+}
+
+/**
+ * Build the wordmark lockup as a self-contained SVG string.
+ * @param {object} opts
+ * @param {string}  opts.tileHex            tile accent fill
+ * @param {string}  opts.text               the name (case as stored)
+ * @param {string}  [opts.glyph='JS']       tile monogram
+ * @param {string}  [opts.ink='currentColor'] text fill (explicit color for PNGs)
+ * @param {boolean} [opts.caps=false]       uppercase the text (matches the site)
+ */
+export function wordmarkSvg({ tileHex, text, glyph = 'JS', ink = 'currentColor', caps = false }) {
+  const fill = normalizeHex(tileHex);
+  const rendered = caps ? text.toUpperCase() : text;
+  const { unitsPerEm } = glyphData();
+  const s = FONT_PX / unitsPerEm;
+  const { placed, xMin, xMax, cy } = layoutText(rendered, caps ? LETTER_SPACING.caps : LETTER_SPACING.title);
+
+  const H = TILE + 2 * PAD;
+  const x0 = PAD + TILE + GAP; // text left edge
+  const W = +(x0 + s * (xMax - xMin) + PAD).toFixed(2);
+
+  // The tile reuses markSvg; strip its outer <svg> and place it as a group so we
+  // avoid nesting a full svg inside another.
+  const tileInner = markSvg({ size: TILE, rounded: true, bg: fill, glyph })
+    .replace(/^<svg[^>]*>/, '')
+    .replace(/<\/svg>$/, '');
+  const tile = `<g transform="translate(${PAD} ${PAD})">${tileInner}</g>`;
+
+  // Glyph outlines are y-up (font space); flip them, left-align at x0, centre the
+  // ink box on the tile's vertical centre.
+  const paths = placed
+    .filter((p) => p.g.path)
+    .map(({ x, g }) => `<path transform="translate(${x.toFixed(2)} 0)" d="${g.path}"/>`)
+    .join('');
+  const textTransform =
+    `translate(${x0} ${H / 2}) scale(${s.toFixed(5)} ${(-s).toFixed(5)}) ` +
+    `translate(${(-xMin).toFixed(2)} ${(-cy).toFixed(2)})`;
+
+  return `<svg width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" xmlns="http://www.w3.org/2000/svg">`
+    + tile
+    + `<g fill="${ink}" transform="${textTransform}">${paths}</g>`
+    + `</svg>`;
+}

package/src/make-cards.mjs

@@ -0,0 +1,28 @@
+// Render a set of social cards into <outDir>/cards/. The card copy, palette, and
+// photo are passed in by the caller (the build reads them from a brand config),
+// so nothing brand-specific is hardcoded here.
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { renderCard } from './lib/card.mjs';
+import { withBrowser } from './lib/render.mjs';
+
+export async function makeCards({ cards, colors, photoPath, outDir, browser }) {
+  if (!cards || !cards.length) return;
+  const dir = path.join(outDir, 'cards');
+  mkdirSync(dir, { recursive: true });
+
+  const render = async (b) => {
+    for (const c of cards) {
+      await renderCard(b, {
+        width: c.width, height: c.height, photoWidth: c.photoWidth,
+        eyebrow: c.eyebrow, name: c.name, tagline: c.tagline, meta: c.meta, url: c.url,
+        colors, photoPath,
+        outPath: path.join(dir, c.file),
+      });
+    }
+  };
+  // Reuse the build's browser when given one; otherwise launch our own.
+  if (browser) await render(browser);
+  else await withBrowser(render);
+  console.log(`  cards     ${cards.map((c) => c.file).join(', ')}`);
+}

package/src/make-mark.mjs

@@ -0,0 +1,45 @@
+// Generate a full icon set for one surface: the shared monogram in a given accent
+// color, into <outDir>/<slug>/icons/ (favicon svg/ico, favicon-32/192,
+// apple-touch-icon at 180 full-bleed) and <outDir>/<slug>/mark/ (mark svg +
+// 512/1024 + transparent light/dark).
+import { Buffer } from 'node:buffer';
+import fs from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { markSvg } from './lib/mark.mjs';
+import { normalizeHex } from './lib/color.mjs';
+import { pngsToIco } from './lib/ico.mjs';
+
+export async function makeMark({ slug, hex, glyph = 'JS', outDir }) {
+  const fill = normalizeHex(hex);
+  const iconsDir = path.join(outDir, slug, 'icons');
+  const markDir = path.join(outDir, slug, 'mark');
+  fs.mkdirSync(iconsDir, { recursive: true });
+  fs.mkdirSync(markDir, { recursive: true });
+
+  const rounded = markSvg({ size: 512, rounded: true, bg: fill, glyph });
+  const square = markSvg({ size: 512, rounded: false, bg: fill, glyph });
+  const transLight = markSvg({ size: 1024, rounded: true, bg: null, fg: fill, glyph });
+  const transDark = markSvg({ size: 1024, rounded: true, bg: null, fg: '#ffffff', glyph });
+
+  const png = (svg, size) => sharp(Buffer.from(svg)).resize(size, size).png().toBuffer();
+  const icon = (name, buf) => fs.writeFileSync(path.join(iconsDir, name), buf);
+  const mk = (name, buf) => fs.writeFileSync(path.join(markDir, name), buf);
+
+  icon('favicon.svg', markSvg({ size: 64, rounded: true, bg: fill, glyph }));
+  icon('favicon-32.png', await png(rounded, 32));
+  icon('favicon-192.png', await png(rounded, 192));
+  icon('apple-touch-icon.png', await png(square, 180));
+  icon('favicon.ico', pngsToIco([
+    { size: 16, buffer: await png(rounded, 16) },
+    { size: 32, buffer: await png(rounded, 32) },
+  ]));
+
+  mk('mark.svg', rounded);
+  mk('mark-512.png', await png(rounded, 512));
+  mk('mark-1024.png', await png(rounded, 1024));
+  mk('mark-transparent-light.png', await png(transLight, 1024));
+  mk('mark-transparent-dark.png', await png(transDark, 1024));
+
+  console.log(`  mark      ${slug.padEnd(12)} ${glyph} on ${fill}`);
+}

package/src/make-sheet.mjs

@@ -0,0 +1,170 @@
+// Generate a brand sheet for one kit into <outDir>/<slug>/: a rendered one-pager
+// (overview.png, in the kit's own font) plus a README.md that inlines the poster
+// and the kit's assets from the same folder. Reads BRAND_FONT (live text) and
+// BRAND_GLYPHS (mark outlines) like the others.
+import { Buffer } from 'node:buffer';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { markSvg } from './lib/mark.mjs';
+import { fontPath } from './lib/font.mjs';
+import { darken, normalizeHex } from './lib/color.mjs';
+import { esc } from './lib/html.mjs';
+import { fontFaceCss, withBrowser, withPage } from './lib/render.mjs';
+
+const b64 = (s) => Buffer.from(s).toString('base64');
+
+// "inter-variable-latin.woff2" -> "Inter"; "Arial Unicode.ttf" -> "Arial".
+function prettyFont(file) {
+  const stem = file.replace(/\.[^.]+$/, '').split(/[-_ ]/)[0];
+  return stem.charAt(0).toUpperCase() + stem.slice(1);
+}
+
+export async function makeSheet({ slug, hex, glyph = 'JS', wordmark, deep, browser, outDir }) {
+  const fill = normalizeHex(hex);
+  const deepShade = deep ? normalizeHex(deep) : darken(fill);
+  const title = wordmark || glyph;
+
+  const font = fontPath();
+  const fontFile = path.basename(font);
+  const fontLabel = prettyFont(fontFile);
+
+  const rounded = b64(markSvg({ size: 512, rounded: true, bg: fill, glyph }));
+  const tLight = b64(markSvg({ size: 512, rounded: true, bg: null, fg: fill, glyph }));
+  const tDark = b64(markSvg({ size: 512, rounded: true, bg: null, fg: '#ffffff', glyph }));
+
+  const kitDir = path.join(outDir, slug);
+  const sheetDir = path.join(kitDir, 'sheet');
+  mkdirSync(sheetDir, { recursive: true });
+
+  const wordmarkBlock = wordmark
+    ? '\n## Wordmark\n\n![wordmark](wordmark/wordmark-light.png)\n\n' +
+      '![wordmark caps](wordmark/wordmark-caps-light.png)\n\n' +
+      'Vector-first: `wordmark.svg` (text in `currentColor`) is the source; the ' +
+      '`-light/-dark` PNGs rasterize from it. Title case and all-caps both ship.\n'
+    : '';
+
+  const html = `<!doctype html><html><head><meta charset="utf-8"><style>
+${fontFaceCss('Brand')}
+*{margin:0;padding:0;box-sizing:border-box}
+:root{--accent:${fill};--deep:${deepShade};--ink:#0b0620;--muted:#6b6b73;--line:#ececf0}
+html,body{width:1200px}
+body{font-family:Brand,system-ui,sans-serif;background:#fff;color:var(--ink);-webkit-font-smoothing:antialiased;padding:84px 88px}
+.eyebrow{font-size:18px;font-weight:700;letter-spacing:4px;text-transform:uppercase;color:var(--accent)}
+header{display:flex;align-items:center;gap:34px;padding-bottom:40px;border-bottom:3px solid var(--accent)}
+header>img{width:120px;height:120px}
+.name{font-size:84px;font-weight:800;letter-spacing:-3px;line-height:1}
+.sub{font-size:21px;font-weight:500;color:var(--muted);margin-top:8px}
+section{padding:46px 0;border-bottom:1px solid var(--line)}
+h2{font-size:15px;font-weight:700;letter-spacing:3px;text-transform:uppercase;color:var(--muted);margin-bottom:28px}
+.marks{display:flex;align-items:center;gap:28px}
+.marks>img,.chip{width:132px;height:132px;border-radius:26px}
+.chip{display:flex;align-items:center;justify-content:center}
+.chip img{width:100%;height:100%;display:block}
+.chip.paper{border:1px solid var(--line)}
+.chip.dark{background:#0b1220}
+.swatches{display:flex;gap:22px}
+.sw{flex:1}
+.box{height:118px;border-radius:16px;border:1px solid var(--line)}
+.lab{margin-top:12px;font-size:18px;font-weight:700}
+.hex{font-size:15px;color:var(--muted);font-variant-numeric:tabular-nums}
+.big{font-size:128px;font-weight:800;letter-spacing:-5px;line-height:1}
+.alpha{font-size:33px;font-weight:600;letter-spacing:1px;margin-top:22px;line-height:1.5}
+.row{font-size:28px;margin-top:14px}
+.w4{font-weight:400}.w6{font-weight:600}.w8{font-weight:800}
+footer{padding-top:38px;font-size:16px;color:var(--muted);display:flex;justify-content:space-between}
+</style></head><body>
+<header>
+  <img src="data:image/svg+xml;base64,${rounded}">
+  <div><div class="eyebrow">Brand Kit</div><div class="name">${esc(title)}</div><div class="sub">${esc(slug)} &middot; ${esc(fill)} &middot; ${esc(fontLabel)}</div></div>
+</header>
+<section class="sec-mark">
+  <h2>Mark</h2>
+  <div class="marks">
+    <img src="data:image/svg+xml;base64,${rounded}">
+    <div class="chip paper"><img src="data:image/svg+xml;base64,${tLight}"></div>
+    <div class="chip dark"><img src="data:image/svg+xml;base64,${tDark}"></div>
+  </div>
+</section>
+<section class="sec-color">
+  <h2>Color</h2>
+  <div class="swatches">
+    <div class="sw"><div class="box" style="background:${fill}"></div><div class="lab">Accent</div><div class="hex">${fill}</div></div>
+    <div class="sw"><div class="box" style="background:${deepShade}"></div><div class="lab">Deep</div><div class="hex">${deepShade}</div></div>
+    <div class="sw"><div class="box" style="background:#0b0620"></div><div class="lab">Ink</div><div class="hex">#0b0620</div></div>
+    <div class="sw"><div class="box" style="background:#fff"></div><div class="lab">Paper</div><div class="hex">#ffffff</div></div>
+  </div>
+</section>
+<section class="sec-type">
+  <h2>Type &middot; ${esc(fontLabel)}</h2>
+  <div class="big">Aa</div>
+  <div class="alpha">ABCDEFGHIJKLMNOPQRSTUVWXYZ<br>abcdefghijklmnopqrstuvwxyz 0123456789</div>
+  <div class="row w4">Regular: hands-on security and infrastructure.</div>
+  <div class="row w6">Semibold: hands-on security and infrastructure.</div>
+  <div class="row w8">Black: hands-on security and infrastructure.</div>
+</section>
+<footer><span>${esc(title)} &middot; Brand Kit</span><span>${esc(fontLabel)}</span></footer>
+</body></html>`;
+
+  // The poster, plus each section as its own library image the README inlines.
+  const shoot = (b) =>
+    withPage(b, { html, viewport: { width: 1200, height: 800 } }, async (page) => ({
+      overview: await page.screenshot({ type: 'png', fullPage: true }),
+      mark: await page.locator('.sec-mark').screenshot(),
+      palette: await page.locator('.sec-color').screenshot(),
+      type: await page.locator('.sec-type').screenshot(),
+    }));
+  // Reuse the build's browser when given one; otherwise launch our own.
+  const shots = browser ? await shoot(browser) : await withBrowser(shoot);
+
+  const save = (buf, name, w) => sharp(buf).resize({ width: w }).png().toFile(path.join(sheetDir, name));
+  await save(shots.overview, 'overview.png', 1200);
+  await save(shots.mark, 'sheet-mark.png', 1024);
+  await save(shots.palette, 'palette.png', 1024);
+  await save(shots.type, 'type-specimen.png', 1024);
+
+  const md = `# ${title} Brand Kit
+
+The full kit: the poster up top, each section's own image below, then the files,
+all generated from the brand's mark, color, and font.
+
+![${title} brand overview](sheet/overview.png)
+
+## Mark
+
+![mark](sheet/sheet-mark.png)
+
+Rounded accent tile with a white glyph (default); accent glyph and white glyph on
+transparent for light and dark surfaces. In \`mark/\`: \`mark.svg\`,
+\`mark-512/1024.png\`, \`mark-transparent-light/dark.png\`.
+
+## Color
+
+![palette](sheet/palette.png)
+
+| Role | Hex |
+|---|---|
+| Accent | \`${fill}\` |
+| Deep | \`${deepShade}\` |
+| Ink | \`#0b0620\` |
+| Paper | \`#ffffff\` |
+
+CSS custom properties in \`web/tokens.css\`.
+
+## Type
+
+![type specimen](sheet/type-specimen.png)
+
+${fontLabel} (\`${fontFile}\`).
+${wordmarkBlock}
+## Folders
+
+- \`icons/\` favicons + apple-touch
+- \`mark/\` the mark: vector, raster, transparent light/dark
+- \`wordmark/\` horizontal lockups: \`wordmark.svg\` + light/dark PNGs, title + caps
+- \`sheet/\` this overview and its section images
+- \`web/\` \`tokens.css\`, \`site.webmanifest\`, \`head.html\` (drop-in wiring)
+`;
+  writeFileSync(path.join(kitDir, 'README.md'), md);
+  console.log(`  sheet     ${slug.padEnd(12)} sheet/ + README.md`);
+}

package/src/make-web.mjs

@@ -0,0 +1,52 @@
+// Generate the drop-in web wiring for a kit into <outDir>/<slug>/web/:
+//   tokens.css        the palette as CSS custom properties
+//   site.webmanifest  PWA/icon manifest
+//   head.html         the favicon + theme-color <link> block, copy-paste ready
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { darken, normalizeHex } from './lib/color.mjs';
+
+export function makeWeb({ slug, hex, glyph = 'JS', name, deep, onColor, outDir }) {
+  const accent = normalizeHex(hex);
+  const deepShade = deep ? normalizeHex(deep) : darken(accent);
+  const onAccent = onColor ? normalizeHex(onColor) : '#ffffff';
+  const label = name || slug;
+  const webDir = path.join(outDir, slug, 'web');
+  mkdirSync(webDir, { recursive: true });
+
+  writeFileSync(
+    path.join(webDir, 'tokens.css'),
+    `:root {\n` +
+      `  --brand-accent: ${accent};\n` +
+      `  --brand-deep: ${deepShade};\n` +
+      `  --brand-on-accent: ${onAccent};\n` +
+      `  --brand-ink: #0b0620;\n` +
+      `  --brand-paper: #ffffff;\n` +
+      `}\n`,
+  );
+
+  const manifest = {
+    name: label,
+    short_name: glyph,
+    icons: [
+      { src: '/icons/favicon-192.png', sizes: '192x192', type: 'image/png' },
+      { src: '/icons/apple-touch-icon.png', sizes: '180x180', type: 'image/png' },
+    ],
+    theme_color: accent,
+    background_color: '#ffffff',
+    display: 'standalone',
+  };
+  writeFileSync(path.join(webDir, 'site.webmanifest'), JSON.stringify(manifest, null, 2) + '\n');
+
+  writeFileSync(
+    path.join(webDir, 'head.html'),
+    `<!-- Adjust the paths to wherever you deploy the icons. -->\n` +
+      `<link rel="icon" href="/favicon.ico" sizes="any">\n` +
+      `<link rel="icon" type="image/svg+xml" href="/icons/favicon.svg">\n` +
+      `<link rel="apple-touch-icon" href="/icons/apple-touch-icon.png">\n` +
+      `<link rel="manifest" href="/site.webmanifest">\n` +
+      `<meta name="theme-color" content="${accent}">\n`,
+  );
+
+  console.log(`  web       ${slug.padEnd(12)} tokens.css, site.webmanifest, head.html`);
+}

package/src/make-wordmark.mjs

@@ -0,0 +1,42 @@
+// Render the horizontal lockup (mark tile + name) for one surface into
+// <outDir>/<slug>/wordmark/, SVG-first: a vector wordmark.svg is the source, and
+// the light/dark PNGs are rasterized from it. Two cases ship: title ("Joe
+// Severino") and all-caps ("JOE SEVERINO").
+import { Buffer } from 'node:buffer';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { wordmarkSvg } from './lib/wordmark.mjs';
+import { WORDMARK_CHARS, ensureGlyphs, wordmarkGlyphFile } from './lib/glyphs.mjs';
+
+const INK = { light: '#0b0620', dark: '#ffffff' }; // ink for light / dark backgrounds
+const PNG_HEIGHT = 512; // raster export height; SVG stays the source of truth
+const VARIANTS = [
+  { caps: false, base: 'wordmark' },
+  { caps: true, base: 'wordmark-caps' },
+];
+
+export async function makeWordmark({ slug, hex, text, glyph = 'JS', weight = 700, outDir }) {
+  const dir = path.join(outDir, slug, 'wordmark');
+  mkdirSync(dir, { recursive: true });
+
+  // The build pre-extracts, but a one-off kit lands straight here, so make sure
+  // the cache exists. It bundles the whole alphabet (WORDMARK_CHARS) so a one-off
+  // never overwrites the shared set with just its own name's letters.
+  ensureGlyphs({ file: wordmarkGlyphFile(), weight, chars: WORDMARK_CHARS, label: 'wordmark glyphs' });
+
+  const toPng = (svg) => sharp(Buffer.from(svg)).resize({ height: PNG_HEIGHT }).png().toBuffer();
+  for (const { caps, base } of VARIANTS) {
+    writeFileSync(
+      path.join(dir, `${base}.svg`),
+      wordmarkSvg({ tileHex: hex, text, glyph, caps, ink: 'currentColor' }),
+    );
+    for (const [name, ink] of Object.entries(INK)) {
+      writeFileSync(
+        path.join(dir, `${base}-${name}.png`),
+        await toPng(wordmarkSvg({ tileHex: hex, text, glyph, caps, ink })),
+      );
+    }
+  }
+  console.log(`  wordmark  ${slug.padEnd(12)} "${text}" + caps`);
+}

package/src/site.mjs

@@ -0,0 +1,116 @@
+// Site plug-and-play. `initSite` scaffolds a flat brand config (and an npm
+// script) into a project; `generateSite` reads it and writes a favicon set,
+// web manifest, and CSS tokens into the project's public/ directory, at the
+// root paths a static site (Astro, Eleventy, plain HTML) expects.
+//
+// This path is pure vector + sharp, so it needs no headless browser. The richer
+// kit (wordmark lockups, social cards, brand sheet) comes from `build` / `kit`.
+import { Buffer } from 'node:buffer';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import sharp from 'sharp';
+import { markSvg } from './lib/mark.mjs';
+import { darken, normalizeHex } from './lib/color.mjs';
+import { pngsToIco } from './lib/ico.mjs';
+
+const DEFAULT_CONFIG = {
+  name: 'My Site',
+  accent: '#2563EB',
+  glyph: 'MS',
+  wordmark: 'My Site',
+};
+
+// The <head> block that wires the generated files. theme-color reflects accent.
+function headSnippet(accent) {
+  return [
+    '<link rel="icon" href="/favicon.ico" sizes="any" />',
+    '<link rel="icon" type="image/svg+xml" href="/favicon.svg" />',
+    '<link rel="apple-touch-icon" href="/apple-touch-icon.png" />',
+    '<link rel="manifest" href="/site.webmanifest" />',
+    `<meta name="theme-color" content="${accent}" />`,
+  ].join('\n');
+}
+
+function loadConfig(configPath, cwd) {
+  const file = configPath ? path.resolve(cwd, configPath) : path.join(cwd, 'brand.config.json');
+  if (!existsSync(file)) {
+    throw new Error(`No brand config at ${file}. Run \`branding-engine init\` first.`);
+  }
+  return JSON.parse(readFileSync(file, 'utf8'));
+}
+
+/** Scaffold brand.config.json (and a `brand` npm script) into a project. */
+export function initSite({ cwd = process.cwd() } = {}) {
+  const created = [];
+  const cfgPath = path.join(cwd, 'brand.config.json');
+  if (existsSync(cfgPath)) {
+    console.log('brand.config.json already exists, leaving it untouched.');
+  } else {
+    writeFileSync(cfgPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + '\n');
+    created.push('brand.config.json');
+  }
+
+  const pkgPath = path.join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    pkg.scripts = pkg.scripts || {};
+    if (!pkg.scripts.brand) {
+      pkg.scripts.brand = 'branding-engine generate';
+      writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+      created.push('package.json ("brand" script)');
+    }
+  }
+  return { created, headSnippet: headSnippet(DEFAULT_CONFIG.accent) };
+}
+
+/** Generate the favicon set, manifest, and CSS tokens into <publicDir>/. */
+export async function generateSite({ config, publicDir = 'public', cwd = process.cwd() } = {}) {
+  const cfg = loadConfig(config, cwd);
+  const accent = normalizeHex(cfg.accent);
+  const onAccent = cfg.onColor ? normalizeHex(cfg.onColor) : '#ffffff';
+  const deep = cfg.deep ? normalizeHex(cfg.deep) : darken(accent);
+  const glyph = cfg.glyph || 'JS';
+  const name = cfg.name || 'Site';
+
+  const pub = path.resolve(cwd, publicDir);
+  mkdirSync(pub, { recursive: true });
+
+  const rounded = markSvg({ size: 512, rounded: true, bg: accent, fg: onAccent, glyph });
+  const square = markSvg({ size: 512, rounded: false, bg: accent, fg: onAccent, glyph });
+  const png = (svg, size) => sharp(Buffer.from(svg)).resize(size, size).png().toBuffer();
+  const write = (name_, buf) => writeFileSync(path.join(pub, name_), buf);
+
+  write('favicon.svg', markSvg({ size: 64, rounded: true, bg: accent, fg: onAccent, glyph }));
+  write('favicon-32.png', await png(rounded, 32));
+  write('favicon-192.png', await png(rounded, 192));
+  write('apple-touch-icon.png', await png(square, 180));
+  write('favicon.ico', pngsToIco([
+    { size: 16, buffer: await png(rounded, 16) },
+    { size: 32, buffer: await png(rounded, 32) },
+  ]));
+  write('site.webmanifest', JSON.stringify({
+    name,
+    short_name: glyph,
+    icons: [
+      { src: '/favicon-192.png', sizes: '192x192', type: 'image/png' },
+      { src: '/apple-touch-icon.png', sizes: '180x180', type: 'image/png' },
+    ],
+    theme_color: accent,
+    background_color: '#ffffff',
+    display: 'standalone',
+  }, null, 2) + '\n');
+  write('brand-tokens.css',
+    `:root {\n` +
+    `  --brand-accent: ${accent};\n` +
+    `  --brand-deep: ${deep};\n` +
+    `  --brand-on-accent: ${onAccent};\n` +
+    `  --brand-ink: #0b0620;\n` +
+    `  --brand-paper: #ffffff;\n` +
+    `}\n`);
+
+  const written = [
+    'favicon.svg', 'favicon-32.png', 'favicon-192.png', 'apple-touch-icon.png',
+    'favicon.ico', 'site.webmanifest', 'brand-tokens.css',
+  ];
+  return { publicDir: pub, written, headSnippet: headSnippet(accent) };
+}