# @suaveplan/font-compress - BTF (Binary TypeFace) binary packing — packer-only since the 2026-05-17 split. Converts typeface.js JSON to compact Uint8Array using dictionary-based compression. Pairs with @suaveplan/font-decompress for the runtime unpack side. ## Summary BTF (Binary TypeFace) binary packing and unpacking. Converts `TypefaceFont` (typeface.js JSON format) to a compact `Uint8Array` using dictionary-based integer compression, and reverses it. Designed for Three.js / game-engine font pipelines where fonts must be shipped as efficient binary assets. ## Documentation tree - [auto-boot](./src/bin/auto-boot.md) — Pure side-effect entry imported by `suaveplan-font-compress.ts` for the shebang-launch case. The only behaviour is: if… - [dispatch](./src/bin/dispatch.md) — Per-file orchestration extracted from the bin entry. Reads a single input file from disk, routes binary inputs (TTF/OTF… - [format-utils](./src/bin/format-utils.md) — Pure formatting helpers backing the operator-facing output of the `suaveplan-font-compress` bin. The helpers exist so t… - [parser](./src/bin/parser.md) — Bin-specific wrapper around `@suaveplan/cli`'s generic `parseArgs` that enforces the `suaveplan-font-compress` flag set… - [printer](./src/bin/printer.md) — Stdout / stderr renderers used by the `suaveplan-font-compress` bin. Owns the help screen, banner, per-file progress li… - [suaveplan-font-compress](./src/bin/suaveplan-font-compress.md) — Operator-facing CLI that wires `@suaveplan/font-convert` (`FontConverter` / `BatchConverter`) into this package's `Bina… - [error-codes](./src/error-codes/error-codes.md) — `FontCompressError` is the structured error type for the `@suaveplan/font-compress` package, extending `SuaveplanError`… - [error-codes](./src/error-codes/error-codes.md) — `FontCompressError` is the structured error type for the `@suaveplan/font-compress` package, extending `SuaveplanError`… - [binary-font-packer](./src/packer/binary-font-packer/binary-font-packer.md) — _(no submodules)_ - [binary-font-packer](./src/packer/binary-font-packer/binary-font-packer.md) — _(no submodules)_ - [encode-string](./src/utils/encode-string.md) — Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encod… - [parse-path](./src/utils/parse-path.md) — Parses a typeface.js outline string into an array of structured command objects. The typeface.js format encodes glyph o… - [binary-font-packer](./src/packer/binary-font-packer/binary-font-packer.md) — _(no submodules)_- [binary-font-unpacker](./src/unpacker/binary-font-unpacker/binary-font-unpacker.md) — _(no submodules)_- [binary-font-unpacker](./src/unpacker/binary-font-unpacker/binary-font-unpacker.md) — _(no submodules)_- [encode-string](./src/utils/encode-string.md) — Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encod… - [parse-path](./src/utils/parse-path.md) — Parses a typeface.js outline string into an array of structured command objects. The typeface.js format encodes glyph o… - [error-codes](./src/error-codes.md) — `FontCompressError` is the structured error type for the `@suaveplan/font-compress` package, extending `SuaveplanError`… - [binary-font-packer](./src/packer/binary-font-packer/binary-font-packer.md) — _(no submodules)_- [binary-font-unpacker](./src/unpacker/binary-font-unpacker/binary-font-unpacker.md) — _(no submodules)_- [binary-font-unpacker](./src/unpacker/binary-font-unpacker/binary-font-unpacker.md) — _(no submodules)_- [encode-string](./src/utils/encode-string.md) — Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encod… - [parse-path](./src/utils/parse-path.md) — Parses a typeface.js outline string into an array of structured command objects. The typeface.js format encodes glyph o… - [error-codes](./src/error-codes.md) — `FontCompressError` is the structured error type for the `@suaveplan/font-compress` package, extending `SuaveplanError`… - [binary-font-packer](./src/packer/binary-font-packer/binary-font-packer.md) — _(no submodules)_- [binary-font-unpacker](./src/unpacker/binary-font-unpacker/binary-font-unpacker.md) — _(no submodules)_- [binary-font-unpacker](./src/unpacker/binary-font-unpacker/binary-font-unpacker.md) — _(no submodules)_- [encode-string](./src/utils/encode-string.md) — Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encod… - [parse-path](./src/utils/parse-path.md) — Parses a typeface.js outline string into an array of structured command objects. The typeface.js format encodes glyph o… - [error-codes](./src/error-codes.md) — `FontCompressError` is the structured error type for the `@suaveplan/font-compress` package, extending `SuaveplanError`… - [binary-font-packer](./src/packer/binary-font-packer/binary-font-packer.md) — _(no submodules)_- [binary-font-unpacker](./src/unpacker/binary-font-unpacker/binary-font-unpacker.md) — _(no submodules)_ - [binary-font-unpacker](./src/unpacker/binary-font-unpacker/binary-font-unpacker.md) — _(no submodules)_- [encode-string](./src/utils/encode-string.md) — Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encod… - [parse-path](./src/utils/parse-path.md) — Parses a typeface.js outline string into an array of structured command objects. The typeface.js format encodes glyph o… - [error-codes](./src/error-codes.md) — `FontCompressError` is the structured error type for the `@suaveplan/font-compress` package, extending `SuaveplanError`… ## Packages | Module | Description | |--------|-------------| | [`BinaryFontPacker`](src/packer/binary-font-packer/binary-font-packer.md) | Packs `TypefaceFont` → BTF `Uint8Array` | | [`BinaryFontUnpacker`](src/unpacker/binary-font-unpacker/binary-font-unpacker.md) | Unpacks BTF `Uint8Array` → `TypefaceFont` | | [`FontCompressError`](src/error-codes.md) | Structured error with stable codes | | [`parsePath`](src/utils/parse-path.md) | Tokenises typeface.js outline strings | | [`encodeString`/`decodeString`](src/utils/encode-string.md) | Length-prefixed UTF-8 string encoding | ## Install ```bash bun add @suaveplan/font-compress @suaveplan/font-convert ``` ## Quick Start ```typescript import { BinaryFontPacker, BinaryFontUnpacker } from "@suaveplan/font-compress"; import type { TypefaceFont } from "@suaveplan/font-convert"; const font: TypefaceFont = /* from @suaveplan/font-convert */; // Pack to binary const packed = new BinaryFontPacker().pack(font); // Unpack back to TypefaceFont const restored = new BinaryFontUnpacker().unpack(packed); ``` ## BTF Binary Format ```text [familyName: uint32-len + UTF-8] [cssFontWeight: uint32-len + UTF-8] [cssFontStyle: uint32-len + UTF-8] [reversed: uint8] [dictLen: uint32 LE] [dict: Int16Array × dictLen] ← all unique integer values [metricsIdxs: Uint16Array × 9] ← ascender,descender,ulPos,ulThk,res,yMin,xMin,yMax,xMax [glyphCount: uint32 LE] per-glyph: [charCode: uint32 LE] [indexCount: uint32 LE] [indexes: Uint16Array × indexCount] ← ha,x_min,x_max, then cmd_byte+coord_indexes ``` Command bytes: `0=m`, `1=l`, `2=b(cubic)`, `3=q(quadratic)`, `4=z`. ## CLI The package ships a `suaveplan-font-compress` bin that composes [`@suaveplan/font-convert`](../font-convert/README.md) (`FontConverter` / `BatchConverter`) with `BinaryFontPacker` to turn TTF/OTF/WOFF/WOFF2 (or already-converted typeface JSON) into compact `.btf` artefacts. See [`src/bin/suaveplan-font-compress.md`](./src/bin/suaveplan-font-compress.md) for the full flag reference, exit-code table, and in-process API. End-to-end example: ```sh # Bake every font under ./fonts into ./out (mirrored layout, BTF default). bunx suaveplan-font-compress ./fonts -o ./out # Inspect the typeface intermediate (skips the BTF pack step). bunx suaveplan-font-compress ./fonts/Inter.ttf -o ./debug --format=json # Overwrite existing outputs. bunx suaveplan-font-compress ./fonts -o ./out --force ``` Exit codes: `0` success, `1` per-file failure(s), `2` invalid CLI args, `3` missing input path.