craft-fonts/docs/integration.md

Using craft-fonts in a Crafting App

craft-fonts is a fully optional source of fonts. An app must build, test and run without it; with it, the app embeds the fonts listed in fonts/manifest.txt and uses them (today: Japanese, Korean, Hebrew and UI-symbol fallback). A native consumer may additionally opt in to fonts/simplified-chinese-manifest.txt for the LXGW WenKai Lite Simplified Chinese fallback; that manifest is never part of the default set or a wasm build.

Why not a Cargo dependency

Cargo resolves every dependency in Cargo.toml, optional ones included, even when the feature that enables them is off. A git dependency on craft-fonts would make every build (offline, in a fork, on a mirror) need this repository. So apps never list craft-fonts in Cargo.toml. The build option is an environment variable instead.

The build option: CRAFT_FONTS_DIR

git clone https://github.com/storytold/craft-fonts ../craft-fonts
CRAFT_FONTS_DIR=$PWD/../craft-fonts cargo build --release

• Unset (the default): nothing changes. The app uses its own bundled fonts and system fonts.
• Set to a craft-fonts checkout: the app's build.rs reads fonts/manifest.txt and embeds every font it lists.
• Set but not a checkout (no manifest, missing file): the build prints a cargo::warning and carries on without craft-fonts, unless CRAFT_FONTS_REQUIRED=1 is also set, which turns it into a build error. Release workflows set both, so a release can't silently ship without them.

Use an absolute path (e.g. CRAFT_FONTS_DIR=$PWD/../craft-fonts): Cargo runs build scripts in the crate's own directory, so a relative path would resolve from there. CRAFT_FONTS_DIR is read by build.rs, so changing it rebuilds only the crate that embeds the fonts.

The build.rs recipe

Put this in the build script of the one crate that installs fonts (usually the UI or text crate). It has no dependencies; the manifest format is defined in crates/craft-fonts/src/parse.rs.

use std::fmt::Write as _;
use std::path::PathBuf;

fn main() {
    println!("cargo::rerun-if-env-changed=CRAFT_FONTS_DIR");
    println!("cargo::rerun-if-env-changed=CRAFT_FONTS_REQUIRED");
    let mut src = String::from("pub static CRAFT_FONTS: &[CraftFont] = &[\n");
    let required = std::env::var_os("CRAFT_FONTS_REQUIRED").is_some();
    if let Some(dir) = std::env::var_os("CRAFT_FONTS_DIR").map(PathBuf::from) {
        match craft_fonts(&dir) {
            Ok(entries) => src.push_str(&entries),
            Err(e) if required => {
                println!("cargo::error=CRAFT_FONTS_DIR={}: {e}", dir.display());
            }
            Err(e) => println!("cargo::warning=building without craft-fonts: CRAFT_FONTS_DIR={}: {e}", dir.display()),
        }
    } else if required {
        println!("cargo::error=CRAFT_FONTS_REQUIRED is set but CRAFT_FONTS_DIR is missing");
    }
    src.push_str("];\n");
    let out = PathBuf::from(std::env::var_os("OUT_DIR").unwrap_or_default()).join("craft_fonts.rs");
    if let Err(e) = std::fs::write(&out, src) {
        println!("cargo::error=writing {}: {e}", out.display());
    }
}

/// One `CraftFont { .. }` initialiser per manifest line.
fn craft_fonts(dir: &std::path::Path) -> Result<String, String> {
    let manifest = dir.join("fonts/manifest.txt");
    println!("cargo::rerun-if-changed={}", manifest.display());
    let text = std::fs::read_to_string(&manifest).map_err(|e| format!("{}: {e}", manifest.display()))?;
    // Web builds use an explicit allowlist. Never embed the whole manifest or Noto CJK.
    // GridCraft's selected faces are BIZ UDPGothic Regular/Bold, NanumGothic Regular,
    // Noto Sans Symbols Regular and Noto Sans Symbols 2 Regular (verified cmap coverage requires
    // both symbol faces). Measure raw font bytes, raw wasm and compressed wasm before/after.
    const WEB_FONTS: &[(&str, &str)] = &[
        ("BIZ UDPGothic", "Regular"),
        ("BIZ UDPGothic", "Bold"),
        ("NanumGothic", "Regular"),
        ("Noto Sans Symbols", "Regular"),
        ("Noto Sans Symbols 2", "Regular"),
    ];
    let wasm = std::env::var("CARGO_CFG_TARGET_ARCH").is_ok_and(|a| a == "wasm32");
    let mut out = String::new();
    let mut included = Vec::new();
    for line in text.lines().map(str::trim).filter(|l| !l.is_empty() && !l.starts_with('#')) {
        let f: Vec<&str> = line.split(" | ").map(str::trim).collect();
        let [family, style, file, scripts, ..] = f.as_slice() else {
            return Err(format!("malformed manifest line: {line}"));
        };
        if wasm && !WEB_FONTS.contains(&(*family, *style)) {
            continue;
        }
        let path = dir.join(file).canonicalize().map_err(|e| format!("{file}: {e}"))?;
        included.push((*family, *style));
        println!("cargo::rerun-if-changed={}", path.display());
        let scripts: Vec<String> = scripts.split(',').map(|s| format!("{:?}", s.trim())).collect();
        let _ = writeln!(
            out,
            "    CraftFont {{ family: {family:?}, style: {style:?}, scripts: &[{}], bytes: include_bytes!({:?}) }},",
            scripts.join(", "),
            path.display().to_string(),
        );
    }
    if std::env::var_os("CRAFT_FONTS_REQUIRED").is_some() {
        for &(family, style) in WEB_FONTS {
            if !included.contains(&(family, style)) {
                return Err(format!("required fallback face is missing: {family} {style}"));
            }
        }
    }
    Ok(out)
}

And in the crate:

/// A font from the optional craft-fonts build input (empty unless built with `CRAFT_FONTS_DIR`).
pub struct CraftFont {
    pub family: &'static str,
    pub style: &'static str,
    /// ISO 15924 scripts the font is for, e.g. `"Jpan"`.
    pub scripts: &'static [&'static str],
    pub bytes: &'static [u8],
}

include!(concat!(env!("OUT_DIR"), "/craft_fonts.rs"));

CRAFT_FONTS is always defined, so there is no cfg to thread through: an empty slice means the app was built without craft-fonts. Code that uses it must work when it is empty.

Optional: the Latin presentation fonts (fonts/latin-manifest.txt)

fonts/latin-manifest.txt is a second, opt-in manifest in exactly the same format as fonts/manifest.txt (same 8 fields, same parser in crates/craft-fonts/src/parse.rs). It lists the Latin presentation catalog: Inter, the metric-compatible Office substitutes (Carlito for Calibri, Caladea for Cambria, Liberation Sans / Serif / Mono for Arial / Times New Roman / Courier New), Source Sans 3, Source Serif 4, Montserrat, Lato, Open Sans, Roboto, Merriweather, Playfair Display, Poppins and Nunito Sans. The central catalog is 16 families, 51 faces, about 19.5 MiB (20,417,364 bytes of font files). The fonts are listed in README.md and ATTRIBUTION.md.

The recipe above reads only fonts/manifest.txt, so apps that don't opt in are unchanged. An app that wants these fonts reads the second manifest too, in addition to the first. Generalise craft_fonts to take the manifest path and its web allowlist, and call it once per manifest:

/// Manifests this app embeds, each with the (family, style) pairs its wasm32 build keeps.
const MANIFESTS: &[(&str, &[(&str, &str)])] = &[
    ("fonts/manifest.txt", &[("BIZ UDPGothic", "Regular")]),
    // Opt in to the Latin catalog; on the web keep only Inter Regular + Bold.
    ("fonts/latin-manifest.txt", &[("Inter", "Regular"), ("Inter", "Bold")]),
];

// In main(), match on this instead of on craft_fonts(&dir) (same Ok/Err handling):
//     MANIFESTS.iter().map(|(rel, web)| craft_fonts(&dir, rel, web)).collect::<Result<String, String>>()
// and in craft_fonts(dir, rel, web): read dir.join(rel) instead of "fonts/manifest.txt",
// and use `web` instead of WEB_FONTS.

• Consumer filter (required for some apps). Eight faces are Adobe-authored: Source Sans 3 (4) and Source Serif 4 (4), 2,594,420 bytes. They remain in the central catalog and are valid OFL-1.1 assets, but a consumer that must not embed Adobe-authored faces skips those two families, leaving 43 permitted Latin faces. DeckCraft already excludes them; FigCraft adds the same family filter in its own build.rs. The main manifest is unaffected.
• Styles. Most families are static files (Regular, Bold, Italic, Bold Italic, SemiBold / Semibold as each family names it). Montserrat, Open Sans, Roboto, Playfair Display and Nunito Sans are variable fonts, one file per upright/italic, listed with style Variable or Italic Variable: register them once and select weights through the wght axis (set it explicitly, e.g. 400 / 700: a variable font's default instance isn't always Regular). The tests check that exactly these styles have a wght axis with a real range containing 400.
• Scripts. Every line is tagged Latn (many also cover Greek and Cyrillic, but nothing asserts that, so don't rely on it).
• Office documents. When a document asks for Calibri, Cambria, Arial, Times New Roman or Courier New and the system doesn't have it, substitute Carlito, Caladea, Liberation Sans, Liberation Serif or Liberation Mono: same advance widths, so line breaks and text boxes match.
• Web (wasm32). Embed only Inter Regular and Inter Bold (~0.8 MB) from this manifest, as in the allowlist above; the full catalog would push a web build past typical per-file hosting limits together with the main manifest's fonts.
• Licences. All are OFL-1.1 and each family directory has its OFL.txt, so the packaging rule below (copy fonts/*/OFL.txt for each embedded font) covers them unchanged.
• From Rust tools that can depend on this repo, the same table is craft_fonts::LATIN_FONTS (load_latin, feature embed-latin). The default FONTS table and embed feature remain exactly fonts/manifest.txt.

Optional native-only manifest

fonts/simplified-chinese-manifest.txt uses the same eight-field format and parser, but it is a separate opt-in input. Read it only for non-wasm builds, after the main manifest has been parsed:

• Native builds only. Never read it from a wasm branch and never add its row to WEB_FONTS. Native builds that do not opt in embed no added bytes.
• Missing file is compatible. An older craft-fonts checkout without the optional manifest is not an error; continue with the main manifest's fonts.
• Malformed or unreadable when present. Under CRAFT_FONTS_REQUIRED=1, fail the build. In optional mode, emit a cargo::warning and keep every successfully parsed font from the main manifest. An optional-manifest error must never discard the main fonts.
• Required mode still needs a directory. CRAFT_FONTS_REQUIRED=1 with no CRAFT_FONTS_DIR is a build error, as in the recipe above.
• Not in FONTS/embed. craft-fonts' default FONTS table and embed feature cover only fonts/manifest.txt; the optional row appears in neither that table nor LATIN_FONTS/embed-latin. Apps supply their own static initializer from the parsed optional file.
• Native fallback order. Append LXGW WenKai Lite / Regular after the existing native families, so it fills characters they lack without taking precedence over BIZ for characters BIZ already covers. It is a per-character fallback, not a promise of uniform Chinese typography or of system-font-first precedence. It does not make static localized UI labels render in Chinese unless the consumer installs the face for those labels too.

The central tests in crates/craft-fonts-tests/tests/fonts.rs parse the optional file with craft_fonts::parse_manifest and verify the exact row, SHA-256, adjacent licence and RFN text, one static weight-400 face without fvar/avar/STAT, outlines for 简体中文演示文稿 and 简, the 24 MiB ceiling, and that the face is absent from FONTS/fonts/manifest.txt.

Using the fonts

• UI (egui): append permitted craft faces at the end of each interface font family, after bundled fonts, system fonts and existing script fallbacks. Register Japanese (Jpan) faces, NanumGothic / Regular for Hang,Kore, Noto Sans Hebrew / Regular for Hebr, Noto Sans Devanagari / Regular for Deva, and both Noto Sans Symbols / Regular and Noto Sans Symbols 2 / Regular for Zsym. The Hebrew file is one static face: add it once per family set that includes it (for example the proportional family and, where the consumer has one, the CELL/monospace family). Do not expand it into the nine named instances of the old variable fixture. A native consumer that opts in to the Simplified Chinese manifest adds LXGW WenKai Lite / Regular for Hani,Hans after those existing families. Match the exact family/style spelling; in particular, NanumGothic has no space. Verify the installed production set with CRAFT_FONTS_REQUIRED=1 and strict glyph assertions for each advertised script and symbol. Hebrew coverage here means each codepoint has a drawn outline. The storytold egui fork uses HarfRust shaping and bidi layout, but font-only tests do not qualify correctly positioned vocalized (pointed) Hebrew in an app. The initial glyph acceptance text is unpointed, e.g. שלום deck 42; shaping needs separate app-level checks. Devanagari coverage likewise means each codepoint has a drawn outline: the font-only tests do not qualify conjunct formation or mark positioning, which need app-level shaping checks such as PhotoCraft's Camera Raw language-switch test with फ़ा (U+092B U+093C U+093E).
• Document text engines: register the same permitted script and symbol faces after the document's requested font and the app's existing fallback faces. Preserve the app's asset exclusions, and do not treat a script tag as proof that every character in that script exists.
• Web (wasm32): the recipe uses a fixed allowlist. Never embed the whole manifest: the current faces together are roughly 43.8 MiB (45.9 MB), over typical per-file hosting limits. Measure the raw bytes of each allowlisted font, plus raw and compressed wasm before and after, against the consumer's actual web gate. Do not call the result "within budget" without a named number and a real check. GridCraft's decision is documented in egui-037-font-coverage-plan.md: BIZ UDPGothic Regular/Bold, NanumGothic Regular, Noto Sans Symbols Regular and Noto Sans Symbols 2 Regular (the verified cmap shows Symbols 1 lacks ✕/◀ and Symbols 2 supplies them), and no Noto CJK. Hebrew is deliberately not in that web allowlist: Noto Sans Hebrew is a native-only addition in this round, and web Hebrew remains an unqualified gap. LXGW WenKai Lite is likewise native-only and must stay out of every wasm allowlist. No existing web allowlist adds Noto Sans Devanagari; keep every wasm allowlist explicit.
• Prefer BIZ UDPGothic for UI text and Shippori Mincho / BIZ UDMincho for serif document text.
• Optional-input diagnostics may skip when CRAFT_FONTS is empty. Acceptance tests that validate advertised scripts must run with CRAFT_FONTS_DIR set and CRAFT_FONTS_REQUIRED=1, and must fail (not skip) when a required face or codepoint is missing. Never weaken strict glyph checks, substitute tofu comparisons, or use allow_missing_glyphs() to make acceptance pass.

Releases and licences

The fonts are OFL-1.1: they can be embedded and redistributed, but the licence text must go with them. In release.yml, check out craft-fonts at a pinned commit and build with it:

- uses: actions/checkout@v4
  with:
    repository: storytold/craft-fonts
    ref: <full commit SHA>        # bump deliberately
    path: craft-fonts
# then, on the build steps:
env:
  CRAFT_FONTS_DIR: ${{ github.workspace }}/craft-fonts
  CRAFT_FONTS_REQUIRED: "1"

Packages built with craft-fonts must include each embedded font's licence file (copy $CRAFT_FONTS_DIR/fonts/*/OFL.txt into the package's licences, named after the family) and the app's NOTICE must say that builds made with CRAFT_FONTS_DIR embed the fonts listed in craft-fonts' ATTRIBUTION.md.

Adding a font

1. Put the file and its licence under fonts/<family>/, from a pinned upstream commit.
2. Add a manifest line (with its SHA-256) and an ATTRIBUTION.md row. A Latin presentation face belongs in fonts/latin-manifest.txt; a face that only some native consumers should embed belongs in fonts/simplified-chinese-manifest.txt; neither belongs in the default fonts/manifest.txt.
3. cargo test --workspace: craft-fonts-tests checks the checksum, licence, family and style names, and, for Japanese fonts, coverage and vertical-text support. Add exact ISO 15924 script assertions for any new face. Coverage tests may claim only glyphs the face really contains: check outlines as well as cmap entries, do not claim a codepoint supplied by another face (egui's emoji faces supply 📋), and do not claim full-script coverage from a sample string. Static faces also get metadata assertions (no fvar/STAT, weight 400), so a variable font with a Thin default cannot pass as a one-face Regular.