# CERT self-host fonts (printit.verae.ai)

[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)

Drop-in woff2 directory for the CERT-01 web viewer (`../certificate.html`).

`certificate.html` probes this folder at load time. If any planned `.woff2`
validates (woff2 magic `wOF2`), it injects local `@font-face` and **skips**
the Google Fonts CDN. If none are present, it loads CDN Fraunces + JetBrains
Mono. Binaries are **not** committed — only `.gitkeep` keeps the path in git.
Do **not** download or commit proprietary fonts.
Operators place OFL Fraunces themselves — see [`LICENSE-FONTS.md`](./LICENSE-FONTS.md).

## Table of Contents

- [Install](#install)
- [Usage](#usage)
- [Background](#background)
- [Planned filenames](#planned-filenames)
- [Fetch scaffold](#fetch-scaffold)
- [Out of scope](#out-of-scope)
- [Status](#status)
- [Contributing](#contributing)
- [License](#license)

## Install

Place OFL-licensed files next to this README (no proprietary fonts):

```sh
# From this directory (site/printit.verae.ai/fonts/)
cp /path/to/fraunces-opsz-wght-700.woff2 .
cp /path/to/fraunces-opsz-wght-600.woff2 .   # optional weight 600
cp /path/to/jetbrains-mono-500.woff2 .      # optional mono
cp /path/to/OFL.txt .                        # required beside binaries

./fetch-fonts.example.sh --check             # exit 0 when required set present
```

Deploy with the static site (`rsync` to `/var/www/printit.verae.ai/` — see
parent `README.md`). No HTML edit is required: the viewer auto-selects local
vs CDN.

## Usage

```sh
# No woff2 yet → certificate.html uses Google Fonts CDN Fraunces
open ../certificate.html

# After drop-in → local @font-face only (CDN not requested)
./fetch-fonts.example.sh --check && open ../certificate.html
# Smoke offline: block fonts.googleapis.com / fonts.gstatic.com;
# title must still render Fraunces from local woff2 (or Georgia if missing).
```

How drop-in works:

1. Obtain **OFL-licensed** Fraunces (and optional JetBrains Mono) as woff2
   from upstream or a subsetted build (title glyphs only is enough for CERT).
2. Name files exactly as in [Planned filenames](#planned-filenames).
3. Commit `OFL.txt` / `LICENSE` next to the binaries (keep copyright notices).
4. Open `certificate.html` — head script HEADs each candidate, checks woff2
   magic (avoids Caddy `try_files` HTML false-positives), injects
   `@font-face` for hits, otherwise appends the CDN `<link>`.
5. Keep the Georgia / Times New Roman / serif stack as final fallback in CSS.

Do **not** uncomment network fetches in `fetch-fonts.example.sh` until license
review. This tree must not ship proprietary font files.

## Background

| Surface | Fonts today | Offline fallback |
|---------|-------------|------------------|
| `certificate.html` title | Local `fonts/*.woff2` if present, else **Fraunces** CDN | Georgia / Times New Roman / serif |
| Mono digests | Local mono woff2 if present, else **JetBrains Mono** CDN | ui-monospace / SF Mono / Menlo |
| UI kit (`verae-ui-kit.css`) | Inter + Material Symbols Rounded CDN | system stacks in `brand/tokens.css` |
| Issued PDF (`internal/pdfcert`) | Core Times/Helvetica; **`EmbedBrandFonts` default false** (env `VERAE_EMBED_BRAND_FONTS`) | N/A until opt-in + licensed face |

Design source of truth: `verae-2026-design/ui-designs/src/html/CERT-01.html`
(tokens `--font-serif: 'Fraunces'`; design-kit `src/fonts/` ships Cantarell +
Material Symbols TTF only — **no Fraunces binary in-repo yet**).

**Not claimed:** full CERT-01.html pixel match, PDF Fraunces embed, or
production binaries in git.

## Planned filenames

```
fonts/
  README.md                 (this file)
  .gitkeep
  fetch-fonts.example.sh    # curl placeholders; no download until uncommented
  fraunces-opsz-wght-600.woff2   # variable or static; opsz + weight 600
  fraunces-opsz-wght-700.woff2   # weight 700 (title)
  jetbrains-mono-500.woff2      # optional; digests already have mono stack
  OFL.txt / LICENSE             # required license text beside binaries
```

Exact names must stay stable once wired so deploys and the head probe match.

## Fetch scaffold

[`fetch-fonts.example.sh`](./fetch-fonts.example.sh) — **example only**.
Comment-only upstream URLs (google/fonts OFL trees). Does not curl until an
operator uncomments a pinned-commit block after license review.

```sh
./fetch-fonts.example.sh          # prints instructions; no network
./fetch-fonts.example.sh --check  # exit 1 until woff2 + OFL.txt present
```

## Out of scope

| Item | Owner / later |
|------|----------------|
| PDF CERT Fraunces embed | **EmbedBrandFonts default false** (option + `VERAE_EMBED_BRAND_FONTS`); Times/Helvetica until enabled + licensed face |
| Inter / Material Symbols self-host for whole site | optional; CERT title is OPEN-ISSUES #7 residual |
| Cantarell from design-kit TTFs | GNOME mock only; not required for CERT-01 web title |
| Pixel-perfect CERT-01.html match | Still later (OPEN-ISSUES Advanced) |

## Status

| Step | State |
|------|-------|
| Placeholder dir + this plan | **Done** (L7) |
| `fetch-fonts.example.sh` placeholders | **Done** (TODO-7 A7) — no binaries fetched |
| Web cert spacing toward CERT-01 | **Closer** — not full pixel |
| Local-first `@font-face` else CDN | **Done** — `certificate.html` probes `fonts/*.woff2` |
| Drop-in docs (this README) | **Done** |
| woff2 binaries + OFL in git | **Not started** — operator drop-in only ([LICENSE-FONTS.md](./LICENSE-FONTS.md)) |
| `EmbedBrandFonts` default false | **Done** — opt-in env/option; no embed path yet |
| Pixel match / PDF embed claim | **Not started** — do not claim |

## Contributing

Questions: Verae eng / printit site owners. PRs that add **OFL** woff2 +
`OFL.txt` with stable planned names are welcome. PRs that vendor proprietary
fonts or strip copyright notices will be rejected. Do not enable the example
fetch script in CI.

## License

Documentation in this directory: UNLICENSED © Verae LLC.

Font binaries are **not** shipped. Operators place OFL Fraunces themselves —
see [`LICENSE-FONTS.md`](./LICENSE-FONTS.md). When added, binaries remain under
upstream licenses (typically SIL OFL 1.1). Ship upstream `OFL.txt` beside any
binary. This directory does not re-license font files.