Initial Commit

packages/ui/react/react-audio-fingerprint/src/backends/local-backend/local-backend.md

@@ -0,0 +1,66 @@
+# `local-backend` — Default in-process `FingerprintBackend`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`LocalBackend` is the default implementation of the `FingerprintBackend`
+contract that hooks and components depend on. It composes `AudioFingerprinter`
+and `FingerprintMatcher` so callers get a single facade with the same shape
+the optional `PythonBackend` exposes from its gated subpath. The class owns
+no state apart from its two collaborator instances.
+
+## Features
+
+- Single facade for `fingerprint(doc, opts?)` and `match(query, corpus)`.
+- `AbortSignal` and progress passthrough to the underlying fingerprinter.
+- Pure in-process: no I/O, no fetch, no server dependency.
+- Matches the `FingerprintBackend` interface byte-for-byte so it can be
+  swapped at runtime via a hook prop.
+- Constructor takes no arguments — defaults rule.
+
+## Usage: Basic Example
+
+```ts
+import { LocalBackend } from "@suaveplan/react-audio-fingerprint/backends/local-backend";
+
+const backend = new LocalBackend();
+const fp = await backend.fingerprint(doc);
+```
+
+## Usage: Advanced Example
+
+Inject the backend into the hook explicitly to keep the default exporting tree
+shaken when a custom backend is in use:
+
+```ts
+import { LocalBackend } from "@suaveplan/react-audio-fingerprint/backends/local-backend";
+
+const backend = new LocalBackend();
+const controller = new AbortController();
+const fp = await backend.fingerprint(doc, {
+    signal: controller.signal,
+    onProgress: ({ fraction }) => console.log(fraction),
+});
+const results = await backend.match(fp, corpus);
+```
+
+## API Reference
+
+- `class LocalBackend implements FingerprintBackend`.
+- `fingerprint(doc, opts?): Promise<Fingerprint>`.
+- `match(query, corpus): Promise<MatchResult[]>`.
+
+## Implementation Notes
+
+The class deliberately avoids exposing the underlying `AudioFingerprinter` and
+`FingerprintMatcher` instances so consumers cannot mutate them after
+construction — this preserves determinism and keeps the public surface stable
+across versions. There is no caching layer here; consumers wishing to cache
+fingerprint results between renders should do so at the hook layer, where the
+relationship to the React commit phase is explicit. Errors from the
+underlying components propagate unchanged; the backend deliberately does NOT
+re-wrap them so the original `ReactAudioFingerprintError` code surfaces to the
+caller.