# 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.