npm - branding-engine - Versions diffs - 0.1.0 - Mend

branding-engine 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 (27) hide show

package/LICENSE +21 -0
package/README.md +129 -0
package/assets/fonts/inter/NOTICE.md +11 -0
package/assets/fonts/inter/inter-variable-latin.woff2 +0 -0
package/assets/glyphs/brand-glyphs.json +367 -0
package/assets/glyphs/wordmark-glyphs.json +637 -0
package/bin/cli.mjs +66 -0
package/index.mjs +15 -0
package/package.json +50 -0
package/requirements.txt +3 -0
package/src/build.mjs +146 -0
package/src/lib/card.mjs +54 -0
package/src/lib/color.mjs +21 -0
package/src/lib/extract-glyphs.py +75 -0
package/src/lib/font.mjs +17 -0
package/src/lib/glyphs.mjs +93 -0
package/src/lib/html.mjs +3 -0
package/src/lib/ico.mjs +23 -0
package/src/lib/mark.mjs +73 -0
package/src/lib/render.mjs +56 -0
package/src/lib/wordmark.mjs +100 -0
package/src/make-cards.mjs +28 -0
package/src/make-mark.mjs +45 -0
package/src/make-sheet.mjs +170 -0
package/src/make-web.mjs +52 -0
package/src/make-wordmark.mjs +42 -0
package/src/site.mjs +116 -0

package/bin/cli.mjs ADDED Viewed

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+// branding-engine CLI.
+//   branding-engine init                              scaffold a site brand.config + npm script
+//   branding-engine generate [--public <dir>] [--config <file>]   favicons + manifest + tokens -> public/
+//   branding-engine build [--config <dir|brand.json>] [--out <dir>] [--only a,b]
+//   branding-engine kit <slug> <hex> <initials> ["Wordmark"] [--font f] [--out d] [--only a,b]
+// Stages for --only: mark, wordmark, sheet, web, cards (mark includes favicons).
+import { buildBrand, buildKit } from '../src/build.mjs';
+import { generateSite, initSite } from '../src/site.mjs';
+function parse(argv) {
+  const pos = [];
+  const opt = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      opt[key] = next && !next.startsWith('--') ? argv[++i] : true;
+    } else {
+      pos.push(a);
+    }
+  }
+  return { pos, opt };
+}
+const USAGE =
+  'Usage:\n' +
+  '  branding-engine init                          scaffold brand.config.json + a `brand` npm script\n' +
+  '  branding-engine generate [--public <dir>] [--config <file>]   favicons + manifest + tokens -> public/\n' +
+  '  branding-engine build [--config <dir|brand.json>] [--out <dir>] [--only mark,wordmark,sheet,web,cards]\n' +
+  '  branding-engine kit <slug> <hex> <initials> ["Wordmark"] [--font <file>] [--out <dir>] [--only ...]';
+const [cmd, ...rest] = process.argv.slice(2);
+const { pos, opt } = parse(rest);
+try {
+  if (cmd === 'init') {
+    const { created, headSnippet } = initSite({});
+    if (created.length) console.log('Created:\n' + created.map((c) => '  ' + c).join('\n'));
+    console.log('\nNext: edit brand.config.json (accent, glyph, name), then run `npm run brand`.');
+    console.log('\nAdd this to your site <head> (or import public/brand-tokens.css for the CSS vars):\n');
+    console.log(headSnippet + '\n');
+  } else if (cmd === 'generate') {
+    const { written, publicDir, headSnippet } = await generateSite({ config: opt.config, publicDir: opt.public });
+    console.log(`Wrote ${written.length} files to ${publicDir}:`);
+    console.log(written.map((w) => '  ' + w).join('\n'));
+    console.log('\n<head> snippet (theme-color reflects your accent):\n');
+    console.log(headSnippet);
+  } else if (cmd === 'build') {
+    await buildBrand({ config: opt.config, outDir: opt.out, only: opt.only });
+  } else if (cmd === 'kit') {
+    const [slug, hex, glyph, wordmark] = pos;
+    if (!slug || !hex || !glyph) {
+      console.error(USAGE);
+      process.exit(1);
+    }
+    await buildKit({ slug, hex, glyph, wordmark, font: opt.font, outDir: opt.out, only: opt.only });
+  } else {
+    console.error(USAGE);
+    process.exit(cmd ? 1 : 0);
+  }
+} catch (err) {
+  console.error(`\n${err.message}`);
+  process.exit(1);
+}

package/index.mjs ADDED Viewed

@@ -0,0 +1,15 @@
+// Programmatic API. The CLI (bin/cli.mjs) is a thin wrapper over buildBrand /
+// buildKit; import these directly to embed the engine in a build pipeline.
+export { buildBrand, buildKit } from './src/build.mjs';
+export { initSite, generateSite } from './src/site.mjs';
+export { makeMark } from './src/make-mark.mjs';
+export { makeWordmark } from './src/make-wordmark.mjs';
+export { makeSheet } from './src/make-sheet.mjs';
+export { makeWeb } from './src/make-web.mjs';
+export { makeCards } from './src/make-cards.mjs';
+export { markSvg } from './src/lib/mark.mjs';
+export { wordmarkSvg } from './src/lib/wordmark.mjs';
+// Lower-level primitives for embedding the renderers in a custom pipeline (e.g.
+// a site that writes brand assets to its own paths).
+export { renderCard } from './src/lib/card.mjs';
+export { launchBrowser } from './src/lib/render.mjs';

package/package.json ADDED Viewed

@@ -0,0 +1,50 @@
+{
+  "name": "branding-engine",
+  "version": "0.1.0",
+  "description": "Generate a complete brand kit — favicon set, vector mark, wordmark lockups, social cards, brand sheet, and web tokens — from one accent color and a monogram.",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "bin": {
+    "branding-engine": "bin/cli.mjs"
+  },
+  "exports": {
+    ".": "./index.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "index.mjs",
+    "requirements.txt"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joeseverino/branding-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/joeseverino/branding-engine/issues"
+  },
+  "homepage": "https://github.com/joeseverino/branding-engine#readme",
+  "keywords": [
+    "branding",
+    "favicon",
+    "logo",
+    "svg",
+    "social-cards"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "sharp": "0.34.5"
+  },
+  "optionalDependencies": {
+    "@playwright/test": "^1.60.0"
+  },
+  "license": "MIT"
+}

package/requirements.txt ADDED Viewed

@@ -0,0 +1,3 @@
+# For ./glyphs.sh (glyph extraction). Install with: pip install -r requirements.txt
+fonttools>=4.60
+brotli>=1.1

package/src/build.mjs ADDED Viewed

@@ -0,0 +1,146 @@
+// Orchestrates the engine. buildBrand() renders every kit defined by a brand
+// config; buildKit() renders a single one-off. Neither hardcodes anything
+// brand-specific: the config (and the output directory) are the inputs.
+//
+// A brand config is a brand.json (or a directory holding one) describing the
+// primary identity, optional surfaces, and optional social cards. Paths inside it
+// (`font`, `portrait`) are resolved relative to the config's own directory.
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_FONT } from './lib/font.mjs';
+import { WORDMARK_CHARS, ensureGlyphs } from './lib/glyphs.mjs';
+import { darken } from './lib/color.mjs';
+import { launchBrowser } from './lib/render.mjs';
+import { makeMark } from './make-mark.mjs';
+import { makeWordmark } from './make-wordmark.mjs';
+import { makeSheet } from './make-sheet.mjs';
+import { makeWeb } from './make-web.mjs';
+import { makeCards } from './make-cards.mjs';
+const ALL_STAGES = ['mark', 'wordmark', 'sheet', 'web', 'cards'];
+const BASE_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+// Normalize an `only` selector (array, comma string, or null=all) to a Set.
+function stageSet(only) {
+  if (!only) return new Set(ALL_STAGES);
+  const list = Array.isArray(only) ? only : String(only).split(',');
+  return new Set(list.map((s) => s.trim()).filter(Boolean));
+}
+// Resolve a config: an object, a brand.json path, or a directory holding one.
+function loadConfig(config) {
+  if (config && typeof config === 'object') {
+    return { brand: config, surfaces: config.surfaces || {}, brandDir: process.cwd() };
+  }
+  let file = config || process.cwd();
+  let dir;
+  if (existsSync(file) && !file.endsWith('.json')) {
+    dir = path.resolve(file);
+    file = path.join(dir, 'brand.json');
+  } else {
+    file = path.resolve(file);
+    dir = path.dirname(file);
+  }
+  const brand = JSON.parse(readFileSync(file, 'utf8'));
+  const sFile = path.join(dir, 'surfaces.json');
+  const surfaces = existsSync(sFile)
+    ? JSON.parse(readFileSync(sFile, 'utf8'))
+    : brand.surfaces || {};
+  return { brand, surfaces, brandDir: dir };
+}
+/** Build every kit defined by a brand config into outDir. */
+export async function buildBrand({ config, outDir, only } = {}) {
+  const { brand, surfaces, brandDir } = loadConfig(config);
+  outDir = outDir ? path.resolve(outDir) : path.join(process.cwd(), 'kits');
+  const stages = stageSet(only);
+  const font = brand.font ? path.resolve(brandDir, brand.font) : DEFAULT_FONT;
+  const weight = brand.weight || 800;
+  const wordmarkWeight = brand.wordmarkWeight || 700;
+  const id = brand.identity;
+  const kits = [
+    { slug: id.slug, color: id.color, glyph: id.glyph, wordmark: id.wordmark, deep: id.deep, onColor: id.onColor },
+    ...Object.entries(surfaces).map(([slug, s]) => ({
+      slug, color: s.color, glyph: s.glyph || id.glyph, wordmark: s.wordmark, deep: s.deep, onColor: s.onColor,
+    })),
+  ];
+  const markChars = [...new Set([...BASE_CHARS, ...kits.flatMap((k) => [...k.glyph])])].join('');
+  process.env.BRAND_FONT = font;
+  process.env.BRAND_GLYPHS = 'brand-glyphs.json';
+  process.env.BRAND_WORDMARK_GLYPHS = 'wordmark-glyphs.json';
+  if (stages.has('mark') || stages.has('sheet')) {
+    ensureGlyphs({ file: 'brand-glyphs.json', font, weight, chars: markChars, label: 'mark glyphs' });
+  }
+  if (stages.has('wordmark')) {
+    ensureGlyphs({ file: 'wordmark-glyphs.json', font, weight: wordmarkWeight, chars: WORDMARK_CHARS, label: 'wordmark glyphs' });
+  }
+  const browser = stages.has('sheet') || (stages.has('cards') && brand.cards) ? await launchBrowser() : null;
+  try {
+    console.log(`Building ${brand.name || 'brand'} -> ${outDir}`);
+    for (const k of kits) {
+      if (stages.has('mark')) await makeMark({ slug: k.slug, hex: k.color, glyph: k.glyph, outDir });
+      if (stages.has('wordmark') && k.wordmark) await makeWordmark({ slug: k.slug, hex: k.color, text: k.wordmark, glyph: k.glyph, weight: wordmarkWeight, outDir });
+      if (stages.has('sheet')) await makeSheet({ slug: k.slug, hex: k.color, glyph: k.glyph, wordmark: k.wordmark, deep: k.deep, browser, outDir });
+      if (stages.has('web')) makeWeb({ slug: k.slug, hex: k.color, glyph: k.glyph, name: k.wordmark || brand.name, deep: k.deep, onColor: k.onColor, outDir });
+    }
+    if (stages.has('cards') && brand.cards) {
+      const photoPath = brand.portrait ? path.resolve(brandDir, brand.portrait) : path.join(brandDir, 'portrait.jpg');
+      const colors = {
+        panel: id.color,
+        panelDeep: id.deep || darken(id.color),
+        onPanel: id.onColor || '#ffffff',
+        accent: brand.cardPalette.accent,
+        textSoft: brand.cardPalette.textSoft,
+        textMuted: brand.cardPalette.textMuted,
+      };
+      await makeCards({ cards: brand.cards, colors, photoPath, outDir, browser });
+    }
+  } finally {
+    if (browser) await browser.close();
+  }
+  console.log('Done.');
+}
+/** Build a single one-off kit (no config file needed). */
+export async function buildKit({
+  slug, hex, glyph = 'JS', wordmark, font, outDir, only,
+  weight = 800, wordmarkWeight = 700, browser,
+} = {}) {
+  outDir = outDir ? path.resolve(outDir) : path.join(process.cwd(), 'kits');
+  const stages = stageSet(only);
+  // A custom font points the caches at font-specific files and pre-extracts the
+  // mark glyphs for these initials; the default font uses the bundled caches and
+  // needs no python. (makeWordmark extracts its own wordmark cache.)
+  if (font) {
+    const abs = path.isAbsolute(font) ? font : path.resolve(process.cwd(), font);
+    const stem = path.basename(abs).replace(/\.[^.]+$/, '');
+    process.env.BRAND_FONT = abs;
+    process.env.BRAND_GLYPHS = `${stem}-glyphs.json`;
+    process.env.BRAND_WORDMARK_GLYPHS = `${stem}-wordmark-glyphs.json`;
+    if (stages.has('mark') || stages.has('sheet')) {
+      ensureGlyphs({ file: process.env.BRAND_GLYPHS, font: abs, weight, chars: glyph, label: 'mark glyphs' });
+    }
+  } else {
+    delete process.env.BRAND_FONT;
+    process.env.BRAND_GLYPHS = 'brand-glyphs.json';
+    process.env.BRAND_WORDMARK_GLYPHS = 'wordmark-glyphs.json';
+  }
+  const ownsBrowser = !browser && stages.has('sheet');
+  const b = browser || (ownsBrowser ? await launchBrowser() : null);
+  try {
+    if (stages.has('mark')) await makeMark({ slug, hex, glyph, outDir });
+    if (stages.has('wordmark') && wordmark) await makeWordmark({ slug, hex, text: wordmark, glyph, weight: wordmarkWeight, outDir });
+    if (stages.has('sheet')) await makeSheet({ slug, hex, glyph, wordmark, browser: b, outDir });
+    if (stages.has('web')) makeWeb({ slug, hex, glyph, name: wordmark, outDir });
+  } finally {
+    if (ownsBrowser && b) await b.close();
+  }
+  console.log(`Kit ${slug} -> ${outDir}/${slug}`);
+}

package/src/lib/card.mjs ADDED Viewed

@@ -0,0 +1,54 @@
+// Shared social-card renderer: a "text panel + photo" card rendered in real Inter
+// via headless Chromium (full-text Inter is beyond the glyph-outline mark pipeline).
+// Self-contained: the Inter woff2 is bundled in the kit and embedded as a data URI,
+// and the palette is passed in, so no dependency on any other repo.
+import { readFileSync } from 'node:fs';
+import sharp from 'sharp';
+import { esc } from './html.mjs';
+import { fontFaceCss, withPage } from './render.mjs';
+/**
+ * Render a card to a PNG on the given (caller-owned) browser.
+ * @param {import('@playwright/test').Browser} browser
+ * @param {object} o  width, height, photoWidth, eyebrow, name, tagline, meta, url,
+ *                    photoPath, outPath, and colors { panel, panelDeep, onPanel,
+ *                    accent, textSoft, textMuted }.
+ */
+export async function renderCard(browser, o) {
+  const c = o.colors;
+  const photoB64 = readFileSync(o.photoPath).toString('base64');
+  const html = `<!doctype html><html><head><meta charset="utf-8"><style>
+${fontFaceCss('Inter')}
+*{margin:0;padding:0;box-sizing:border-box}
+html,body{width:${o.width}px;height:${o.height}px}
+body{display:flex;font-family:Inter,sans-serif;overflow:hidden;-webkit-font-smoothing:antialiased}
+.panel{width:${o.width - o.photoWidth}px;height:${o.height}px;
+  background:linear-gradient(135deg,${c.panel},${c.panelDeep});
+  padding:72px;display:flex;flex-direction:column;justify-content:center;color:${c.onPanel}}
+.eyebrow{font-size:24px;font-weight:600;letter-spacing:3.5px;color:${c.textMuted};text-transform:uppercase}
+.name{font-size:78px;font-weight:800;letter-spacing:-2px;line-height:1.05;margin-top:18px}
+.rule{width:64px;height:5px;border-radius:2.5px;background:${c.accent};margin-top:26px}
+.tagline{font-size:30px;font-weight:400;color:${c.textSoft};margin-top:30px}
+.meta{font-size:24px;font-weight:600;letter-spacing:.5px;color:${c.textMuted};margin-top:14px}
+.url{font-size:25px;font-weight:600;letter-spacing:.5px;color:${c.textMuted};margin-top:34px}
+.photo{width:${o.photoWidth}px;height:${o.height}px;object-fit:cover;object-position:top}
+</style></head><body>
+<div class="panel">
+  <div class="eyebrow">${esc(o.eyebrow)}</div>
+  <div class="name">${esc(o.name)}</div>
+  <div class="rule"></div>
+  <div class="tagline">${esc(o.tagline)}</div>
+  <div class="meta">${esc(o.meta)}</div>
+  <div class="url">${esc(o.url)}</div>
+</div>
+<img class="photo" src="data:image/jpeg;base64,${photoB64}">
+</body></html>`;
+  const shot = await withPage(
+    browser,
+    { html, viewport: { width: o.width, height: o.height } },
+    (page) => page.screenshot({ type: 'png' }),
+  );
+  // Rendered at 2x for crisp text; downscale to the exact card size.
+  await sharp(shot).resize(o.width, o.height).png().toFile(o.outPath);
+}

package/src/lib/color.mjs ADDED Viewed

@@ -0,0 +1,21 @@
+// Color helpers shared across the generators, so every kit normalizes and
+// validates color the same way, and derives the same "deep" shade.
+// Return a validated "#rrggbb" from "rrggbb" or "#rrggbb"; throw otherwise.
+export function normalizeHex(hex) {
+  const v = '#' + String(hex).replace(/^#/, '');
+  if (!/^#[0-9a-fA-F]{6}$/.test(v)) {
+    throw new Error(`Invalid hex color: "${hex}". Expected 6 hex digits, e.g. 1f4d57.`);
+  }
+  return v;
+}
+// Multiply each channel toward black. The default 0.62 is the kits' fallback
+// "deep" shade when brand.json doesn't supply a curated one.
+export function darken(hex, f = 0.62) {
+  const n = parseInt(normalizeHex(hex).slice(1), 16);
+  const r = Math.round(((n >> 16) & 255) * f);
+  const g = Math.round(((n >> 8) & 255) * f);
+  const b = Math.round((n & 255) * f);
+  return '#' + [r, g, b].map((x) => x.toString(16).padStart(2, '0')).join('');
+}

package/src/lib/extract-glyphs.py ADDED Viewed

@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""Extract glyph outlines as SVG path data for the brand mark.
+Defaults to the bundled Inter variable woff2, but any font works: pass a path to
+a .ttf/.otf/.woff2. Variable fonts are instantiated at the given weight; static
+fonts use their single master. Output is JSON the node generators consume, so
+they stay pure-node.
+Usage:
+  python3 bin/lib/extract-glyphs.py "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789" 800
+  python3 bin/lib/extract-glyphs.py "AB" 700 ~/fonts/SomeFont.ttf
+  python3 bin/lib/extract-glyphs.py "AB" 700 ~/fonts/SomeFont.ttf myfont-glyphs.json
+The default run writes brand-glyphs.json (the kit's glyph cache). A custom font
+writes <font-stem>-glyphs.json unless you name the output, so the brand cache is
+never clobbered by accident. Point a generator at a non-default file with
+BRAND_GLYPHS=<file> (e.g. BRAND_GLYPHS=somefont-glyphs.json ./kit.sh ...).
+"""
+import json
+import sys
+from pathlib import Path
+from fontTools.ttLib import TTFont
+from fontTools.varLib.instancer import instantiateVariableFont
+from fontTools.pens.svgPathPen import SVGPathPen
+from fontTools.pens.boundsPen import BoundsPen
+here = Path(__file__).resolve().parent
+root = here.parents[1]
+default_font = root / "assets/fonts/inter/inter-variable-latin.woff2"
+chars = sys.argv[1] if len(sys.argv) > 1 else "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
+weight = float(sys.argv[2]) if len(sys.argv) > 2 else 800.0
+font_path = Path(sys.argv[3]).expanduser() if len(sys.argv) > 3 else default_font
+if len(sys.argv) > 4:
+    out_path = Path(sys.argv[4])
+    if not out_path.is_absolute():
+        out_path = here / out_path
+elif len(sys.argv) > 3:
+    # Custom font, no explicit output: derive a name so Inter is never clobbered.
+    out_path = here / f"{font_path.stem}-glyphs.json"
+else:
+    out_path = here / "brand-glyphs.json"
+font = TTFont(str(font_path))
+if "fvar" in font:
+    instantiateVariableFont(font, {"wght": weight}, inplace=True)
+glyph_set = font.getGlyphSet()
+cmap = font.getBestCmap()
+upem = font["head"].unitsPerEm
+glyphs = {}
+for ch in dict.fromkeys(chars):
+    name = cmap[ord(ch)]
+    g = glyph_set[name]
+    pen = SVGPathPen(glyph_set)
+    g.draw(pen)
+    bp = BoundsPen(glyph_set)
+    g.draw(bp)
+    # Blank glyphs (e.g. the space) have no contours, so BoundsPen leaves
+    # bounds None; they still carry an advance width the layout needs.
+    xmin, ymin, xmax, ymax = bp.bounds or (0, 0, 0, 0)
+    glyphs[ch] = {
+        "path": pen.getCommands(),
+        "advance": g.width,
+        "bounds": {"xMin": xmin, "yMin": ymin, "xMax": xmax, "yMax": ymax},
+    }
+out_path.write_text(json.dumps(
+    {"font": font_path.name, "unitsPerEm": upem, "weight": weight, "glyphs": glyphs},
+    indent=2,
+))
+print(f"wrote {out_path.name} from {font_path.name} — upem={upem} weight={int(weight)} chars={''.join(glyphs)}")

package/src/lib/font.mjs ADDED Viewed

@@ -0,0 +1,17 @@
+// Resolves the live-text font used by the wordmark/card renderers and the glyph
+// extractor. The default is the Inter bundled with this package; BRAND_FONT (or a
+// brand config's `font`) overrides it. A relative override is resolved from the
+// caller's working directory, since the consumer: not this package: owns it.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+// Absolute path to the bundled default font.
+export const DEFAULT_FONT = path.join(pkgRoot, 'assets/fonts/inter/inter-variable-latin.woff2');
+export function fontPath() {
+  const f = process.env.BRAND_FONT;
+  if (!f) return DEFAULT_FONT;
+  return path.isAbsolute(f) ? f : path.resolve(process.cwd(), f);
+}

package/src/lib/glyphs.mjs ADDED Viewed

@@ -0,0 +1,93 @@
+// Shared glyph-outline cache management. A cache is the JSON that
+// extract-glyphs.py writes: { font, unitsPerEm, weight, glyphs }. Both the mark
+// (uppercase monogram at the brand weight) and the wordmark (mixed case at the
+// lighter wordmark weight) sit on this, so extraction logic lives in one place.
+//
+// Two cache locations: the read-only set BUNDLED with this package (the default
+// Inter, full alphabet: so the common case needs no python and never writes),
+// and a writable directory (BRAND_CACHE_DIR, else <cwd>/.brand-cache) used when a
+// custom font or a missing glyph forces a fresh extraction. The package install
+// itself is never written to.
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DEFAULT_FONT, fontPath } from './font.mjs';
+const here = path.dirname(fileURLToPath(import.meta.url));
+const BUNDLED_DIR = path.resolve(here, '..', '..', 'assets', 'glyphs');
+function cacheDir() {
+  return process.env.BRAND_CACHE_DIR || path.join(process.cwd(), '.brand-cache');
+}
+// Where loadGlyphs would read `file` from: the writable cache if present, else the
+// bundled set. Custom fonts only ever land in the writable cache.
+function resolveRead(file) {
+  const writable = path.join(cacheDir(), file);
+  return existsSync(writable) ? writable : path.join(BUNDLED_DIR, file);
+}
+// The wordmark cache bundles the whole alphabet (both cases), digits, and space,
+// so any name renders from the default-font cache without re-extracting: the
+// same reason the mark cache bundles A-Z/0-9. Text-driven extraction would let a
+// one-off ("kit chris-blake …") overwrite the shared set with just its own chars.
+export const WORDMARK_CHARS =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 ';
+// True when a readable cache covers this font, weight, and every character (a
+// missing glyph or a font/weight change forces a re-extract).
+export function cacheCovers({ file, font, weight, chars }) {
+  const p = resolveRead(file);
+  if (!existsSync(p)) return false;
+  try {
+    const g = JSON.parse(readFileSync(p, 'utf8'));
+    if (font && g.font !== path.basename(font)) return false;
+    if (weight != null && Number(g.weight) !== Number(weight)) return false;
+    return [...chars].every((ch) => g.glyphs && g.glyphs[ch]);
+  } catch {
+    return false;
+  }
+}
+// Extract `chars` from `font` at `weight` into the writable cache unless a
+// readable cache already covers them. Throws (with an actionable message) only if
+// extraction is actually needed and python3/fonttools is missing.
+export function ensureGlyphs({ file, font = fontPath(), weight, chars, label = file }) {
+  if (cacheCovers({ file, font, weight, chars })) return;
+  const dir = cacheDir();
+  const out = path.join(dir, file);
+  const charset = [...new Set([...chars])].join('');
+  mkdirSync(dir, { recursive: true });
+  console.log(`Extracting ${label} "${charset}" @ ${weight} from ${path.basename(font)}`);
+  try {
+    execFileSync(
+      'python3',
+      [path.resolve(here, 'extract-glyphs.py'), charset, String(weight), font, out],
+      { stdio: 'inherit' },
+    );
+  } catch {
+    throw new Error(
+      `Could not extract glyphs into ${out}. A custom font or new glyph needs ` +
+        `python3 + fonttools (pip install -r requirements.txt). The bundled Inter ` +
+        `needs none of this.`,
+    );
+  }
+}
+export function loadGlyphs(file) {
+  return JSON.parse(readFileSync(resolveRead(file), 'utf8'));
+}
+// The wordmark's outline cache filename. Defaults to wordmark-glyphs.json (the
+// bundled Inter set); a one-off in a custom font gets its own file so Inter's
+// cache is never clobbered. Both the extractor and the renderer call this so they
+// always agree on the filename.
+export function wordmarkGlyphFile() {
+  if (process.env.BRAND_WORDMARK_GLYPHS) return process.env.BRAND_WORDMARK_GLYPHS;
+  const f = process.env.BRAND_FONT;
+  if (f && path.basename(f) !== path.basename(DEFAULT_FONT)) {
+    return `${path.basename(f).replace(/\.[^.]+$/, '')}-wordmark-glyphs.json`;
+  }
+  return 'wordmark-glyphs.json';
+}

package/src/lib/html.mjs ADDED Viewed

@@ -0,0 +1,3 @@
+// Escape text for safe interpolation into the HTML the Chromium renderers build.
+export const esc = (s) =>
+  String(s).replace(/[<>&]/g, (c) => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;' }[c]));

package/src/lib/ico.mjs ADDED Viewed

@@ -0,0 +1,23 @@
+// Minimal, dependency-free PNG-based .ico encoder. Takes [{ size, buffer }] of
+// PNG buffers and packs them into a single .ico (used for favicon.ico).
+import { Buffer } from 'node:buffer';
+export function pngsToIco(images) {
+  const header = Buffer.alloc(6);
+  header.writeUInt16LE(1, 2);
+  header.writeUInt16LE(images.length, 4);
+  const entries = [];
+  let offset = 6 + images.length * 16;
+  for (const { size, buffer } of images) {
+    const e = Buffer.alloc(16);
+    e.writeUInt8(size >= 256 ? 0 : size, 0);
+    e.writeUInt8(size >= 256 ? 0 : size, 1);
+    e.writeUInt16LE(1, 4);
+    e.writeUInt16LE(32, 6);
+    e.writeUInt32LE(buffer.length, 8);
+    e.writeUInt32LE(offset, 12);
+    offset += buffer.length;
+    entries.push(e);
+  }
+  return Buffer.concat([header, ...entries, ...images.map((i) => i.buffer)]);
+}

package/src/lib/mark.mjs ADDED Viewed

@@ -0,0 +1,73 @@
+// Builds a brand mark SVG from real Inter (weight 800) glyph outlines.
+// Parameterized: the color and glyph are arguments, so one monogram renders in
+// any surface's accent. Self-contained, with no dependency on any other repo.
+//
+// Outlines come from brand-glyphs.json (A-Z and 0-9 are bundled by default).
+import { loadGlyphs } from './glyphs.mjs';
+// Read glyphs lazily so a BRAND_GLYPHS set in-process (by the build) is honored.
+// Defaults to brand-glyphs.json; point at another extracted set with BRAND_GLYPHS.
+let _glyphData;
+function glyphData() {
+  if (!_glyphData) _glyphData = loadGlyphs(process.env.BRAND_GLYPHS || 'brand-glyphs.json');
+  return _glyphData;
+}
+const RENDER = {
+  letterSpacing: -0.045, // em
+  widthRatio: 0.63,      // glyph ink width relative to the box
+  radiusRatio: 0.22,     // rounded-square corner radius (0 = square)
+};
+// Lay the glyph string out in font units and measure the combined ink box.
+function layout(glyph) {
+  const { unitsPerEm, glyphs } = glyphData();
+  const ls = RENDER.letterSpacing * unitsPerEm;
+  const chars = [...glyph];
+  let penX = 0;
+  const placed = [];
+  chars.forEach((ch, i) => {
+    const g = glyphs[ch];
+    if (!g) {
+      throw new Error(
+        `No outline for glyph "${ch}". Available: ${Object.keys(glyphs).join(', ')}. ` +
+          `It will be extracted automatically for the bundled font; for a custom ` +
+          `font, ensure python3 + fonttools are installed.`,
+      );
+    }
+    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) {
+    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, cx: (xMin + xMax) / 2, cy: (yMin + yMax) / 2, gw: xMax - xMin };
+}
+/**
+ * Build the mark as a self-contained SVG string.
+ * @param {object} opts
+ * @param {number}  [opts.size=512]      square canvas size
+ * @param {boolean} [opts.rounded=true]  rounded-square (false = full square)
+ * @param {string|null} [opts.bg]        tile fill, or null for transparent
+ * @param {string}  [opts.fg='#ffffff']  glyph fill
+ * @param {string}  [opts.glyph='JS']    monogram (J and S are the extracted outlines)
+ */
+export function markSvg({ size = 512, rounded = true, bg, fg = '#ffffff', glyph = 'JS' } = {}) {
+  const { placed, cx, cy, gw } = layout(glyph);
+  const s = (RENDER.widthRatio * size) / gw;
+  const rx = rounded ? +(size * RENDER.radiusRatio).toFixed(2) : 0;
+  const bgRect = bg ? `<rect width="${size}" height="${size}" rx="${rx}" fill="${bg}"/>` : '';
+  const paths = placed
+    .map(({ x, g }) => `<path transform="translate(${x.toFixed(2)} 0)" d="${g.path}"/>`)
+    .join('');
+  // Glyph outlines are y-up (font space); flip and centre them in the canvas.
+  return `<svg width="${size}" height="${size}" viewBox="0 0 ${size} ${size}" xmlns="http://www.w3.org/2000/svg">`
+    + bgRect
+    + `<g fill="${fg}" transform="translate(${size / 2} ${size / 2}) scale(${s.toFixed(5)} ${(-s).toFixed(5)}) translate(${(-cx).toFixed(2)} ${(-cy).toFixed(2)})">${paths}</g>`
+    + `</svg>`;
+}