skills/plugins/document-navigator/docs/media/fonts/font-compress

@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 — Pure side-effect entry imported by suaveplan-font-compress.ts for the shebang-launch case. The only behaviour is: if…
• dispatch — Per-file orchestration extracted from the bin entry. Reads a single input file from disk, routes binary inputs (TTF/OTF…
• format-utils — Pure formatting helpers backing the operator-facing output of the suaveplan-font-compress bin. The helpers exist so t…
• parser — Bin-specific wrapper around @suaveplan/cli's generic parseArgs that enforces the suaveplan-font-compress flag set…
• printer — Stdout / stderr renderers used by the suaveplan-font-compress bin. Owns the help screen, banner, per-file progress li…
• suaveplan-font-compress — Operator-facing CLI that wires @suaveplan/font-convert (FontConverter / BatchConverter) into this package's `Bina…
• error-codes — FontCompressError is the structured error type for the @suaveplan/font-compress package, extending SuaveplanError…
  • error-codes — FontCompressError is the structured error type for the @suaveplan/font-compress package, extending SuaveplanError…
• binary-font-packer — (no submodules)
  • binary-font-packer — (no submodules)
• encode-string — Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encod…
• parse-path — 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 — Parses a typeface.js outline string into an array of structured command objects. The typeface.js format encodes glyph o…
• error-codes — FontCompressError is the structured error type for the @suaveplan/font-compress package, extending SuaveplanError…
• binary-font-packer — (no submodules)- binary-font-unpacker — (no submodules)- binary-font-unpacker — (no submodules)- encode-string — Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encod…
• parse-path — Parses a typeface.js outline string into an array of structured command objects. The typeface.js format encodes glyph o…
• error-codes — FontCompressError is the structured error type for the @suaveplan/font-compress package, extending SuaveplanError…
• binary-font-packer — (no submodules)- binary-font-unpacker — (no submodules)- binary-font-unpacker — (no submodules)- encode-string — Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encod…
• parse-path — Parses a typeface.js outline string into an array of structured command objects. The typeface.js format encodes glyph o…
• error-codes — FontCompressError is the structured error type for the @suaveplan/font-compress package, extending SuaveplanError…
• binary-font-packer — (no submodules)- binary-font-unpacker — (no submodules) - binary-font-unpacker — (no submodules)- encode-string — Utilities for encoding and decoding length-prefixed UTF-8 strings in the BTF binary format. They provide the wire encod…
• parse-path — Parses a typeface.js outline string into an array of structured command objects. The typeface.js format encodes glyph o…
• error-codes — FontCompressError is the structured error type for the @suaveplan/font-compress package, extending SuaveplanError…

Packages

Module	Description
BinaryFontPacker	Packs TypefaceFont → BTF Uint8Array
BinaryFontUnpacker	Unpacks BTF Uint8Array → TypefaceFont
FontCompressError	Structured error with stable codes
parsePath	Tokenises typeface.js outline strings
encodeString/decodeString	Length-prefixed UTF-8 string encoding

Install

bun add @suaveplan/font-compress @suaveplan/font-convert

Quick Start

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

[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 (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 for the full flag reference, exit-code table, and in-process API.

End-to-end example:

# 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.