first commit

docs/media/fonts/font-subset/src/utils/format-detect.md

@@ -0,0 +1,56 @@
+# Utils: format-detect
+
+## Purpose
+
+Provides magic-byte font format detection from raw binary data. Before compressing or probing a font file, `FontCompressor` needs to know the input format to validate adapter support. This utility performs a fast 4-byte prefix check covering the four formats that matter for web font workflows: TTF, OTF, WOFF, and WOFF2.
+
+## Features
+
+- Detects TTF via `00 01 00 00` (TrueType scalar type)
+- Detects OTF via `4F 54 54 4F` ("OTTO" — OpenType CFF)
+- Detects WOFF via `77 4F 46 46` ("wOFF")
+- Detects WOFF2 via `77 4F 46 32` ("wOF2")
+- Returns `"unknown"` for unrecognised or too-short buffers (< 4 bytes)
+- Zero external dependencies — direct byte comparison without any registry
+
+## Usage: Basic Example
+
+```typescript
+import { detectFontFormat } from "@suaveplan/font-compress/utils/format-detect";
+
+const bytes = new Uint8Array([0x77, 0x4f, 0x46, 0x32, /* ... */]);
+console.log(detectFontFormat(bytes)); // "woff2"
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { detectFontFormat } from "@suaveplan/font-compress/utils/format-detect";
+import { FONT_COMPRESS_CODES, FontCompressError } from "@suaveplan/font-compress";
+
+function requireKnownFormat(data: Uint8Array): void {
+    const fmt = detectFontFormat(data);
+    if (fmt === "unknown") {
+        throw new FontCompressError(
+            FONT_COMPRESS_CODES.UNSUPPORTED_FORMAT,
+            "Unrecognised font format — expected TTF, OTF, WOFF, or WOFF2"
+        );
+    }
+}
+```
+
+## API Reference
+
+### `detectFontFormat(data: Uint8Array): FontFormat`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `data` | `Uint8Array` | Raw font bytes to inspect |
+
+**Returns** one of `"ttf"`, `"otf"`, `"woff"`, `"woff2"`, or `"unknown"`.
+
+Never throws — always returns a `FontFormat` value.
+
+## Implementation Notes
+
+The implementation avoids the `@suaveplan/mime` signature registry for font detection because the published mime package uses `"sideEffects": false`, which causes Vite to tree-shake the side-effect import (`import "./signatures/index.js"`) that registers magic-byte patterns at load time. The result is that `detectFromMagicBytes` returns `undefined` for all inputs in the built package. Inlining the four font signatures here is simpler, zero-dependency, and correct. Should `@suaveplan/mime` be rebuilt with explicit signatures exports, this module can be updated to delegate to it.

docs/media/fonts/font-subset/src/utils/unicode-ranges.md

@@ -0,0 +1,65 @@
+# Utils: unicode-ranges
+
+## Purpose
+
+Parses CSS/OpenType-style Unicode range notation into a `Set<number>` of integer codepoints. Font subsetting workflows need to know which codepoints to retain; this utility bridges the human-readable range format (e.g. `U+0020-007F`) and the numeric representation that font adapters operate on.
+
+## Features
+
+- Parses single codepoints: `U+XXXX`
+- Parses inclusive ranges: `U+XXXX-XXXX`
+- Case-insensitive for both the `U+` prefix and hex digits
+- Merges multiple ranges into a single `Set<number>` with no duplicates
+- Throws `FontCompressError(INVALID_OPTIONS)` for malformed syntax or reversed ranges
+- Zero external dependencies
+
+## Usage: Basic Example
+
+```typescript
+import { parseUnicodeRanges } from "@suaveplan/font-compress/utils/unicode-ranges";
+
+// ASCII printable range
+const ascii = parseUnicodeRanges(["U+0020-007F"]);
+console.log(ascii.has(0x41)); // true  ("A")
+console.log(ascii.size);      // 96
+```
+
+## Usage: Advanced Example
+
+```typescript
+import { parseUnicodeRanges } from "@suaveplan/font-compress/utils/unicode-ranges";
+import { FontCompressError } from "@suaveplan/font-compress";
+
+// Multi-range merge — Latin + Latin Extended
+const ranges = parseUnicodeRanges(["U+0020-007F", "U+00A0-00FF"]);
+console.log(ranges.size); // 192
+
+// Catching parse errors
+try {
+    parseUnicodeRanges(["0020-007F"]); // missing U+ prefix
+} catch (e) {
+    if (e instanceof FontCompressError) {
+        console.error(e.code);    // "FONT_COMPRESS.INVALID_OPTIONS"
+        console.error(e.message); // describes the bad input
+    }
+}
+```
+
+## API Reference
+
+### `parseUnicodeRanges(ranges: string[]): Set<number>`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `ranges` | `string[]` | Array of range strings in `U+XXXX` or `U+XXXX-XXXX` format |
+
+**Returns** a `Set<number>` containing every integer codepoint covered by the union of all input ranges.
+
+**Throws** `FontCompressError` with code `FONT_COMPRESS.INVALID_OPTIONS` when:
+
+- A string does not match the `U+XXXX` or `U+XXXX-XXXX` pattern
+- The start codepoint of a range exceeds the end codepoint
+
+## Implementation Notes
+
+The regex `^[Uu]\+([0-9A-Fa-f]{1,6})(?:-([0-9A-Fa-f]{1,6}))?$` validates the entire string in a single pass, avoiding character-by-character parsing. Codepoints up to 6 hex digits are supported (`U+10FFFF` = 1114111), covering the full Unicode range. For very large ranges (e.g. `U+0000-FFFF` = 65536 entries), callers should be aware that `Set` construction is O(n) in the number of codepoints.