Automate Whitelist Subsetting for Marketing Hero Fonts

Scan the rendered output for the hero node and collect its unique codepoints — the same decoding the browser tool uses.

// extract-hero.mjs
import fs from "node:fs";

const html = fs.readFileSync("./dist/index.html", "utf8");
const m = html.match(/data-hero[^>]*>([^<]*)</);
const heroText = m ? m[1] : "JAD APPS — Build Faster";

const chars = new Set();
for (const ch of Array.from(heroText)) {
  const cp = ch.codePointAt(0);
  if (cp != null) chars.add(String.fromCodePoint(cp));
}
fs.writeFileSync("./hero-chars.txt", [...chars].join(""));
console.log(`hero glyphs: ${chars.size}`);

This reproduces the in-browser Character Whitelist Builder exactly: .notdef kept, glyphs matched by unicode/unicodes, rebuilt with new Font(). Output is uncompressed TTF — convert to WOFF2 next.

// subset-hero.mjs  —  node subset-hero.mjs Brand.ttf hero-chars.txt
import fs from "node:fs";
import opentype from "opentype.js";

const [, , fontPath, charsFile] = process.argv;
const keep = new Set(
  Array.from(fs.readFileSync(charsFile, "utf8").trim())
    .map(c => c.codePointAt(0))
);

const font = opentype.loadSync(fontPath);
const glyphs = [font.glyphs.get(0)];            // .notdef, always
for (let i = 1; i < font.glyphs.length; i++) {
  const g = font.glyphs.get(i);
  const us = g.unicodes?.length ? g.unicodes : [g.unicode];
  if (us.some(u => u != null && keep.has(u))) glyphs.push(g);
}
if (glyphs.length === 1) throw new Error("Subset would be empty.");

const out = new opentype.Font({
  familyName: font.getEnglishName("fontFamily") || "Brand",
  styleName:  font.getEnglishName("fontSubfamily") || "Regular",
  unitsPerEm: font.unitsPerEm,
  ascender:   font.ascender,
  descender:  font.descender,
  glyphs,
});
fs.writeFileSync("Brand.hero.ttf", Buffer.from(out.toArrayBuffer()));
console.log(`kept ${glyphs.length} glyphs (incl .notdef)`);
// NOTE: kern/GPOS/GSUB dropped — same as the browser tool.

If the hero needs kern pairs or ligatures, the opentype.js path won't do — pyftsubset keeps layout tables and can emit WOFF2 directly. pip install fonttools brotli first.

pyftsubset Brand.ttf \
  --text-file=hero-chars.txt \
  --layout-features='*' \
  --flavor=woff2 \
  --output-file=Brand.hero.woff2
# Layout preserved; web-ready WOFF2 in one command.

Regenerate the hero font in CI and fail the build if it regresses past a budget, catching the case where a copy edit widens the glyph set.

- name: Build hero font
  run: |
    node extract-hero.mjs
    node subset-hero.mjs src/fonts/Brand.ttf hero-chars.txt
    npx ttf2woff2 < Brand.hero.ttf > dist/fonts/Brand.hero.woff2
- name: Enforce hero font budget
  run: |
    SIZE=$(stat -c%s dist/fonts/Brand.hero.woff2)
    echo "Brand.hero.woff2 = $SIZE bytes"
    test "$SIZE" -le 4096   # fail if over 4 KB

Run the actual JAD Character Whitelist Builder locally via the runner when you don't want Python or native deps. The schema is option-only (whitelistChars); the runner executes on your machine so the font stays local.

# 1. Inspect the schema (one required option: whitelistChars)
curl -H "Authorization: Bearer $JAD_API_KEY" \
  https://jadapps.example/api/v1/tools/character-whitelist-builder

# 2. Dispatch to your paired local runner (font stays local):
#    POST file + inputs to the runner endpoint per the API docs:
#    127.0.0.1:9789/v1/tools/character-whitelist-builder/run
#    inputs={"whitelistChars":"JAD APPS — Build Faster"}
# Output is TTF; convert to WOFF2 as a follow-up step.

The browser-parity opentype.js script drops kern/GPOS/GSUB, exactly like the in-browser tool. If a designer hand-kerned the hero in mockups, the deployed micro-font will show default spacing. For caps geometric heroes this is usually fine; for refined editorial headlines, switch to pyftsubset --layout-features='*' or hb-subset in the pipeline — those preserve the tables.

The whole point of automation: if marketing changes 'Build Faster' to 'Build Faster™', the ™ (U+2122) won't be in the old subset and renders .notdef. Because the pipeline re-derives the whitelist from the built HTML on every deploy, the regeneration picks it up automatically — provided your extraction step reads the final rendered text, not a stale source string.

Glyph extraction only sees text present in the built output. If the hero string is injected client-side (e.g. from an API after hydration), the build-time scan won't see it and the subset will tofu. For any runtime-variable hero, fall back to a charset subset (Latin range) instead of a whitelist so unexpected characters still render.

If your extraction strips whitespace, the space glyph (U+0020) won't be in the set and 'JAD APPS' will render with a .notdef box between words. The browser tool keeps inner spaces; your script must too. Don't .replace(/\s/g,'') the hero text before building the codepoint set — keep the space.

Just like the browser tool, the opentype.js script's toArrayBuffer() can fail on CFF (PostScript-outline) OTF fonts. In a pipeline this surfaces as a thrown error mid-build. Either convert the source to a TrueType-outline TTF first, or use pyftsubset/hb-subset which handle CFF and CFF2 properly.

The opentype.js step emits an uncompressed TTF; shipping it directly is 2–3× larger than necessary. Always add a WOFF2 conversion (ttf2woff2, or use pyftsubset --flavor=woff2 to skip the two-step). Gate on the WOFF2 size, not the TTF size, so the budget reflects the real wire cost.

Subsetting on every build, including local dev, is wasteful. Cache by a hash of (source font bytes + hero string); skip when unchanged. Or restrict the subset step to production builds so local iteration stays fast. The output is deterministic for a given (font, string), so caching is safe.

The Whitelist Builder (and the script) processes one font file at a time. A hero in Bold plus a sub-headline in Regular means two subset runs producing two micro-fonts. Loop your weights in the build script; give each output a distinct filename and @font-face font-weight so the browser picks the right one.