123 lines
3.4 KiB
Markdown
123 lines
3.4 KiB
Markdown
# OpenSpec Change: enterprise-font-compress-btf
|
||
|
||
- **Change ID**: enterprise-font-compress-btf
|
||
- **Package**: `@suaveplan/font-compress`
|
||
- **Category**: universal
|
||
- **Target path**: `universal/compression/font-compress`
|
||
- **Status**: PROPOSED
|
||
- **Date**: 2026-04-25
|
||
- **Reference source**: `/mnt/s/web/suaveplan/packages/universal/font-compress/src/packer/`
|
||
|
||
---
|
||
|
||
## Summary
|
||
|
||
Deliver `@suaveplan/font-compress` on the genesis branch from scratch at enterprise quality. The package implements BTF (Binary TypeFace) binary packing: takes a `TypefaceFont` JSON (from `@suaveplan/font-convert`) and produces a compact `Uint8Array` using dictionary-based compression with `@suaveplan/bitpacker`. Also provides `BinaryFontUnpacker` which reverses the process (BTF binary → `TypefaceFont` JSON).
|
||
|
||
---
|
||
|
||
## Current-state audit (genesis)
|
||
|
||
The package does not exist on genesis. The original logic was split across `@suaveplan/font-compress` (packing) and `@suaveplan/font-decompress` (unpacking) on main. In genesis we co-locate packer and unpacker here since they share the binary format and dictionary logic.
|
||
|
||
---
|
||
|
||
## BTF binary format
|
||
|
||
```
|
||
[metadata: familyName string][cssFontWeight string][cssFontStyle string]
|
||
[reversed: 1 byte]
|
||
[dictLen: uint32][dictionary: Int16Array × dictLen]
|
||
[metrics: 9 × uint16 (indexes into dictionary)]
|
||
[glyphCount: uint32]
|
||
[per glyph: char codepoint uint32][ha/x_min/x_max: 3 × uint16][cmdCount: uint16]
|
||
[per cmd: type byte + coord indexes uint16 × 2|4|0]
|
||
```
|
||
|
||
String encoding: `[length: uint16][utf8 bytes]`
|
||
|
||
---
|
||
|
||
## Available workspace deps on genesis
|
||
|
||
| Package | Role |
|
||
|---|---|
|
||
| `@suaveplan/error` (`workspace:^`) | Base class for `FontCompressError`; `FONT_COMPRESS.*` codes |
|
||
| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
|
||
| `@suaveplan/font-convert` (`workspace:^`) | `TypefaceFont`, `TypefaceGlyph`, `PathCommand` types |
|
||
| `@suaveplan/bitpacker` (`workspace:^`) | `BitWriter`/`BitReader` for bit-packed command encoding |
|
||
| `zod` (`catalog:forms`) | Option schemas |
|
||
| `@opentelemetry/api` (`catalog:observability`) | Spans + metrics |
|
||
|
||
---
|
||
|
||
## Public API
|
||
|
||
```ts
|
||
class FontCompressError extends SuaveplanError<FontCompressErrorCode>
|
||
|
||
type FontCompressErrorCode =
|
||
| 'FONT_COMPRESS_PACK_FAILED'
|
||
| 'FONT_COMPRESS_UNPACK_FAILED'
|
||
| 'FONT_COMPRESS_INVALID_DATA'
|
||
|
||
class BinaryFontPacker {
|
||
pack(font: TypefaceFont): Uint8Array
|
||
}
|
||
|
||
class BinaryFontUnpacker {
|
||
unpack(data: Uint8Array): TypefaceFont
|
||
}
|
||
|
||
function createBinaryFontPacker(): BinaryFontPacker
|
||
function createBinaryFontUnpacker(): BinaryFontUnpacker
|
||
```
|
||
|
||
---
|
||
|
||
## File layout
|
||
|
||
```text
|
||
universal/compression/font-compress/
|
||
package.json
|
||
tsconfig.lib.json
|
||
vitest.config.ts
|
||
vite.config.ts
|
||
src/
|
||
index.ts
|
||
error-codes.ts
|
||
constants/
|
||
index.ts
|
||
packer/
|
||
binary-font-packer/
|
||
binary-font-packer.ts
|
||
binary-font-packer.md
|
||
binary-font-packer.test.ts
|
||
index.ts
|
||
unpacker/
|
||
binary-font-unpacker/
|
||
binary-font-unpacker.ts
|
||
binary-font-unpacker.md
|
||
binary-font-unpacker.test.ts
|
||
index.ts
|
||
utils/
|
||
encode-string.ts
|
||
encode-string.md
|
||
encode-string.test.ts
|
||
parse-path.ts
|
||
parse-path.md
|
||
parse-path.test.ts
|
||
__benchmarks__/
|
||
font-compress.bench.ts
|
||
tests/
|
||
roundtrip.test.ts
|
||
property.test.ts
|
||
```
|
||
|
||
---
|
||
|
||
## Impact
|
||
|
||
**Downstream**: Three.js font loading pipelines.
|
||
**Prerequisites**: `@suaveplan/font-convert`, `@suaveplan/bitpacker`.
|