Merge pull request #1315 from PR0M3TH3AN/ai/doc-client-20231026-15350337132812859795

chore(ai): document js/nostr/client.js

docs/nostr-client-overview.md

@@ -0,0 +1,91 @@
+# NostrClient Overview
+
+`js/nostr/client.js` exports the `NostrClient` class, which serves as the central controller for all Nostr network interactions and state management within the application. It acts as a facade over `nostr-tools`, managing connections, subscriptions, caching, and signing.
+
+## Key Responsibilities
+
+1.  **Connection Management**: Maintains a pool of connections to multiple relays (`SimplePool`).
+2.  **State Management**: Tracks video events, deduplicates them, and manages deletions via tombstones.
+3.  **Caching**: Implements a "stale-while-revalidate" strategy using IndexedDB (with localStorage fallback) to restore UI state immediately upon load.
+4.  **Event Publishing**: Orchestrates the signing and broadcasting of complex event chains (Video Note -> NIP-94 Mirror -> NIP-71 Metadata).
+5.  **Signer Abstraction**: Unifies NIP-07 (Extension), NIP-46 (Remote/Bunker), and Local (nsec) signing under a single interface.
+6.  **Video History**: Reconstructs the edit history of videos using `videoRootId` and `d` tags.
+
+## Architecture & State
+
+The client maintains several internal maps to manage state:
+
+*   `allEvents`: A raw map of all fetched video events (key: event ID).
+*   `activeMap`: A derived map containing only the *latest* version of each video, keyed by a stable identifier (`videoRootId` or addressable pointer).
+*   `rawEvents`: A cache of the exact raw JSON events from relays, used for signature verification and re-publishing.
+*   `tombstones`: Tracks timestamps of deletion events to prevent "zombie" events (deleted events reappearing from slow relays) from resurfacing.
+
+### Caching Strategy (`EventsCacheStore`)
+
+To ensure instant load times, the client persists its state to IndexedDB (`bitvid-events-cache`).
+*   **Snapshot**: On a debounced timer (or idle callback), the current state (`allEvents`, `tombstones`) is serialized.
+*   **Fingerprinting**: Events are fingerprinted to avoid writing unchanged data to the DB.
+*   **Restore**: On `init()`, the client loads the latest snapshot into memory, allowing the UI to render before any network requests complete.
+
+## Key Flows
+
+### 1. Initialization (`init`)
+
+```mermaid
+graph TD
+    A[init()] --> B[restoreLocalData]
+    B --> C{IndexedDB Available?}
+    C -- Yes --> D[Load Snapshot]
+    C -- No --> E[Load localStorage]
+    D & E --> F[Render UI with Cached Data]
+    F --> G[ensurePool]
+    G --> H[connectToRelays]
+    H --> I[Ready for Subscriptions]
+```
+
+### 2. Video Subscription (`subscribeVideos`)
+
+To prevent UI thrashing during high-volume event ingress (e.g., initial flood from relays), the client uses a **buffering and debouncing** strategy.
+
+1.  **Buffer**: Incoming events are pushed to `eventBuffer` instead of being processed immediately.
+2.  **Debounce**: A flush timer is scheduled (75ms).
+3.  **Flush**: When the timer fires, the entire buffer is processed:
+    *   Events are validated and converted.
+    *   `activeMap` is updated (latest-wins logic).
+    *   `onVideo` callback is fired once with the batch updates.
+    *   Cache persistence is scheduled.
+
+### 3. Publishing a Video (`publishVideo`)
+
+Publishing is a multi-step process ensuring compatibility and discoverability.
+
+1.  **Video Note (Kind 30078)**: The core content (magnet, infohash, metadata) is signed and published. A unique `videoRootId` is generated for new videos.
+2.  **NIP-94 Mirror (Kind 1063)**: If a direct HTTP URL is provided, a file header event is published to point to the hosted file.
+3.  **NIP-71 Metadata (Kind 22/21)**: Addressable metadata tags are published to support categorization/grouping without modifying the immutable video note.
+
+### 4. Remote Signer Handshake (`connectRemoteSigner`)
+
+For NIP-46 (Nostr Connect), the client implements a full handshake flow:
+
+1.  **Ephemeral Key**: Generates a local key pair for the session.
+2.  **Handshake**: Publishes a Kind 24133 (`NIP46_RPC_KIND`) event to the relay.
+3.  **Wait**: Listens for an acknowledgment or `auth_url` challenge from the signer.
+4.  **Session**: Once connected, stores the session metadata to allow auto-reconnection.
+
+## Why it works this way
+
+*   **Buffering**: essential for performance. React rendering cycles are expensive; updating state for every single event in a 5000-event relay dump would freeze the browser.
+*   **Tombstones**: essential for eventual consistency. Relays are distributed and can be out of sync. If a user deletes a video, we must remember that deletion timestamp so a slow relay doesn't "undelete" it by serving the old event later.
+*   **Dual-Layer Cache**: IndexedDB is asynchronous and large-capacity; localStorage is synchronous but small. We use IndexedDB for the bulk data but keep a fallback for environments where IDB might be flaky or slow to initialize.
+
+## When to change
+
+*   **Refactor `EventsCacheStore`**: If moving to a more robust state management library (like RxDB or dedicated worker), this logic should be extracted.
+*   **New Event Kinds**: If the video data model changes (e.g., V4 schema), `convertEventToVideo` and `publishVideo` will need updates.
+*   **Signer upgrades**: As NIP-46 evolves (e.g., Bunker standards), the handshake and connection logic in `nip46Client.js` (and its orchestration here) will need adjustment.
+
+## Related Files
+
+*   `js/nostrEventSchemas.js`: Defines the structure of the events being built/parsed.
+*   `js/nostr/nip46Client.js`: Handles the low-level RPC for remote signers.
+*   `js/state/profileCache.js`: Handles user profile metadata (Kind 0), which is separate from video data.