suaveplan/openspec/archive/2026-05-23-enterprise-react-audio-fingerprint/tasks.md

Tasks: enterprise-react-audio-fingerprint

Change ID: enterprise-react-audio-fingerprint Package: @suaveplan/react-audio-fingerprint Target path: packages/ui/react/react-audio-fingerprint Prerequisite packages on Verdaccio: @suaveplan/react-audio, @suaveplan/audio-analysis-spectrum, @suaveplan/audio-engine-browser, @suaveplan/error, @suaveplan/types, @suaveplan/opentelemetry, @suaveplan/events

---

1. Scaffold

• 1.1 Directory tree per proposal.
• 1.2 package.json at 0.1.0, "sideEffects": false, full subpath exports. React 19 peer; python-audio-fingerprint optional peer gated to ./backends/python-backend.
• 1.3 tsconfig.json, vitest.config.ts (happy-dom).

2. Error codes

• 2.1 src/error-codes.ts — defineCodes("REACT_AUDIO_FINGERPRINT", [...]), ReactAudioFingerprintError extends AudioError.
• 2.2 error-codes.test.ts — every code reachable.

3. Fingerprint algorithm

• 3.1 src/fingerprint/peak-detector.ts — 2D local-peak detection above noise floor with cap.
• 3.2 src/fingerprint/constellation.ts — pair hashing within target-zone window; 32-bit quantisation.
• 3.3 src/fingerprint/audio-fingerprinter.ts — composes peak-detector + constellation against audio-analysis-spectrum FFT/spectrogram.
• 3.4 audio-fingerprinter.test.ts — determinism, peak count cap, noise-floor behaviour.

4. Matcher

• 4.1 src/fingerprint/fingerprint-matcher.ts — time-offset histogramming.
• 4.2 fingerprint-matcher.test.ts — sort order, partial match resilience.

5. Corpus

• 5.1 src/corpus/memory-corpus/ — Map-backed, 'changed' event.
• 5.2 src/corpus/indexeddb-corpus/ — IDB-backed, persistence-across-instances test.
• 5.3 OTel corpus_size gauge wiring.

6. Backends

• 6.1 src/backends/local-backend/ — default; runs the local algorithm.
• 6.2 src/backends/python-backend/ — optional subpath delegating to python-audio-fingerprint over HTTP.

7. Hooks

• 7.1 use-audio-fingerprint — useSyncExternalStore-backed; AbortSignal cancellation; SSR-safe initial state.
• 7.2 use-fingerprint-matcher — subscribes to corpus 'changed'; clears lastResults on corpus identity change.
• 7.3 use-fingerprint-progress — convenience progress accessor.

8. Components (each: .tsx, .md, .types.ts, .test.tsx, .stories.tsx)

• 8.1 audio-fingerprint-uploader/ — DnD + file picker + URL paste; progress bar; accessible.
• 8.2 fingerprint-match-display/ — ranked list with confidence bars.
• 8.3 fingerprint-visualizer/ — constellation overlay on spectrogram; tooltip on peak focus.

9. Benchmarks

• 9.1 src/__benchmarks__/fingerprint.bench.ts — fingerprint a 60 s reference; report MB/s.
• 9.2 src/__benchmarks__/match.bench.ts — match a 10 s query against a 10 k-entry corpus.

10. Tests

• 10.1 tests/integration.test.tsx — uploader → fingerprint → match against memory corpus → display.
• 10.2 tests/purity.test.ts — no FFT in src/; dependency-set allowlist.
• 10.3 tests/property.test.ts (fast-check) — noisy clip matches its source; distinct sources distinct fingerprints.
• 10.4 tests/exports.test.ts — every surface subpath; python gated.
• 10.5 tests/bundle-size/{root-only,matcher-only}.size.test.ts.

11. Docs + verify + archive

• 11.1 All co-located .md (≥200 words).
• 11.2 README.md at package root with quick-start, corpus example, backend swap example.
• 11.3 bunx turbo lint typecheck test --filter=@suaveplan/react-audio-fingerprint green; coverage 100/100/100/100.
• 11.4 Walk every ### Requirement and **Verified by:**.
• 11.5 Fold spec delta; move change folder to archive.