OpenSpec Change: enterprise-react-font-decompress

Change ID: enterprise-react-font-decompress
Package: @suaveplan/react-font-decompress
Category: react
Target path: react/media/react-font-decompress
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/react-font-decompress.md

Summary

Deliver @suaveplan/react-font-decompress on genesis from scratch at enterprise quality. Thin React adapter around @suaveplan/font-decompress for loading binary-packed BTF fonts in the browser (Three.js/R3F). Ships useFont(url), useFonts(urls), BinaryFontLoader, and createBrowserLoader(). Genesis lifts coverage from effectively 0% on hook files to 100% by writing real tests.

Current-state audit (genesis)

Package does not exist on genesis — fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	`FontError`
`zod` (`catalog:forms`)	Config schemas

External: tslib catalog:build. React 18 peer.

Preserved public API surface

useFont(url: string): { font: TypefaceFont | null; loading: boolean; error: Error | null }
useFonts(urls: string[]): { fonts: TypefaceFont[]; loading: boolean; error: Error | null }
BinaryFontLoader
createBrowserLoader(): string   // inline script string
// Re-exports from @suaveplan/font-decompress
PathCommand, TypefaceFont

New additions for genesis

FontError — codes: FONT_LOAD_FAILED, FONT_DECODE_FAILED.
Real hook tests — no "is a function" stubs; tests use @suaveplan/testing-dom and real DI.
Module-level cache — BinaryFontLoader uses a Map<url, Promise<TypefaceFont>> to deduplicate concurrent loads.
Stories — useFont playground, useFonts multi-URL playground.

File layout

react/media/react-font-decompress/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    hooks/
      use-font/ (ts + md + test + stories + index)
      use-fonts/ (ts + md + test + stories + index)
    loader/
      binary-font-loader/ (ts + md + test + index)
      browser-loader/ (ts + md + test + index)
    types/

2.2 KiB Raw Blame History