Initial Commit

openspec/changes/enterprise-font-decompress/proposal.md

@@ -0,0 +1,172 @@
+# OpenSpec Change: enterprise-font-decompress
+
+- **Change ID**: enterprise-font-decompress
+- **Package**: `@suaveplan/font-decompress`
+- **Category**: universal
+- **Target path**: `universal/compression/font-decompress`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/font-decompress.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/font-decompress` on the genesis branch from scratch at enterprise quality. The package provides font decompression and extraction: WOFF2-to-TTF expansion, WOFF-to-TTF expansion, glyph enumeration, codepoint-to-glyph mapping extraction, and font metadata reading. Counterpart to `@suaveplan/font-compress`. Pure TypeScript; binary font operations delegate to an injectable `FontDecompressAdapter`.
+
+---
+
+## Current-state audit (genesis)
+
+The package does not exist on genesis yet — this is a fresh build. No prior source, no test results, no coverage data. The main-branch package had 95%+ coverage.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | Base class for `FontDecompressError`; `FONT_DECOMPRESS.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `LoggerLike`, `Clock` |
+| `@suaveplan/mime` (`workspace:^`) | Font MIME-type detection |
+| `@suaveplan/font-compress` (`workspace:^`) | `FontFormat`, `FontMetadata` shared types |
+| `zod` (`catalog:forms`) | Zod schemas for all public option types |
+| `@opentelemetry/api` (`catalog:observability`) | Spans + counters |
+
+Dev deps: `vitest`, `@vitest/coverage-istanbul`, `fast-check`, `mitata` (all `catalog:testing`).
+
+---
+
+## Public API
+
+### Core types
+
+```ts
+class FontDecompressError extends SuaveplanError
+
+interface GlyphInfo {
+  id: number
+  unicode: number | null
+  name: string | null
+}
+
+interface CmapEntry {
+  codepoint: number
+  glyphId: number
+}
+
+interface DecompressResult {
+  data: Uint8Array
+  format: FontFormat              // re-exported from @suaveplan/font-compress
+  mimeType: string
+  originalSize: number
+  decompressedSize: number
+}
+
+interface FontDecompressAdapter {
+  readonly supportedInputFormats: readonly FontFormat[]
+  probe(data: Uint8Array): Promise<FontMetadata>
+  decompress(data: Uint8Array): Promise<DecompressResult>
+  enumerateGlyphs(data: Uint8Array): Promise<GlyphInfo[]>
+  getCmapTable(data: Uint8Array): Promise<CmapEntry[]>
+}
+
+interface FontDecompressorOptions {
+  adapter: FontDecompressAdapter
+  logger?: LoggerLike
+  clock?: Clock
+}
+
+class FontDecompressor {
+  constructor(options: FontDecompressorOptions)
+  probe(data: Uint8Array): Promise<FontMetadata>
+  decompress(data: Uint8Array, signal?: AbortSignal): Promise<DecompressResult>
+  enumerateGlyphs(data: Uint8Array, signal?: AbortSignal): Promise<GlyphInfo[]>
+  getCmapTable(data: Uint8Array, signal?: AbortSignal): Promise<CmapEntry[]>
+}
+
+function createFontDecompressor(options: FontDecompressorOptions): FontDecompressor
+```
+
+### Error codes
+
+```ts
+type FontDecompressErrorCode =
+  | 'FONT_DECOMPRESS_UNSUPPORTED_FORMAT'
+  | 'FONT_DECOMPRESS_PARSE_FAILED'
+  | 'FONT_DECOMPRESS_DECODE_FAILED'
+  | 'FONT_DECOMPRESS_INVALID_INPUT'
+
+const FONT_DECOMPRESS_ERROR_METADATA: Readonly<Record<FontDecompressErrorCode, CodeMetadata>>
+function registerFontDecompressErrorCodes(): void
+```
+
+### Zod schemas
+
+```ts
+GlyphInfoSchema
+CmapEntrySchema
+DecompressResultSchema
+FontDecompressorOptionsSchema
+```
+
+---
+
+## New additions for genesis
+
+1. **`FontDecompressAdapter` interface** — codec-agnostic; `NullFontDecompressAdapter` ships for unit tests.
+2. **`getCmapTable`** — extracts the Unicode cmap (platform 3, encoding 1) as an array of `CmapEntry` — useful for building glyph-to-character lookup tables without full font parse.
+3. **Shared types re-export** — `FontFormat`, `FontMetadata` re-used from `@suaveplan/font-compress`; no duplication.
+4. **`AbortSignal` propagation** — every async method; throws `FontDecompressError(FONT_DECOMPRESS_DECODE_FAILED)` on abort.
+5. **OTel instrumentation** — span `font.decompress`, counter `font_decompress_total`, histogram `font_decompress_duration_ms`.
+6. **Property-based tests** — decompressed size ≥ original size for WOFF/WOFF2, glyph count > 0 for non-empty font.
+7. **Benchmark suite** — decompress 50 kB WOFF2, enumerate glyphs from 200 kB TTF.
+
+---
+
+## File layout
+
+```text
+universal/compression/font-decompress/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/
+      index.ts
+    types/
+      common.ts
+      common.md
+    core/
+      font-decompressor/
+        font-decompressor.ts
+        font-decompressor.md
+        font-decompressor.types.ts
+        font-decompressor.test.ts
+        index.ts
+    adapters/
+      null-adapter/
+        null-adapter.ts
+        null-adapter.md
+        null-adapter.test.ts
+        index.ts
+    utils/
+      format-detect.ts
+      format-detect.md
+      format-detect.test.ts
+    __benchmarks__/
+      font-decompress.bench.ts
+  tests/
+    integration.test.ts
+    property.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: font inspection tools, `@suaveplan/react-font-decompress` React layer.
+**Breaking changes**: none — fresh build.
+**Prerequisites**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/font-compress` published to Verdaccio.