chore(ai): doc js/nostr/client.js (agent)

docs/nostr-client-overview.md

@@ -63,3 +63,66 @@ The client tracks `tombstones` (map of ID -> deletedAt timestamp). Any incoming
 *   `subscribeVideos(callback)`: Main feed subscription.
 *   `publishVideo(payload)`: Complex flow to upload -> sign -> publish -> mirror.
 *   `connectRemoteSigner(uri)`: Handshake protocol for NIP-46.
+
+## Why it works this way
+
+### 1. Immutability & "Active Map"
+Nostr events are immutable signed messages. To support "edits", we must allow multiple events to represent the same "entity" (Video).
+- **The Trade-off**: We accept higher memory usage (storing multiple versions in `allEvents`) to gain strict cryptographic verifiability.
+- **The Solution**: `activeMap` acts as a "Latest-State Projection" (Materialized View) that the UI consumes. This decouples the network reality (append-only log) from the user expectation (mutable state).
+
+### 2. Buffering vs. Streaming
+Directly piping relay events to React State (`setState`) triggers a Re-Render Cycle for every message.
+- **The Bottleneck**: Initial loads often fetch 500-2000 events in <2 seconds.
+- **The Solution**: A 75ms debounce buffer collects bursts and processes them in one microtask. This turns 1000 re-renders into ~10-15, keeping the UI thread responsive (60fps).
+
+### 3. Dual-Layer Caching (IDB + Memory)
+Relays are slow and sometimes fail.
+- **Offline-First**: We restore from IndexedDB immediately on boot (`init`).
+- **Fingerprinting**: We hash events before writing to IDB. If `JSON.stringify(video)` hasn't changed, we skip the write syscall. This reduces I/O freezing on mobile devices.
+
+## When to change
+
+- **Update `EVENTS_CACHE_VERSION`**: If you change the internal `Video` object structure (e.g., rename fields in `convertEventToVideo`), bump the DB version in `EventsCacheStore` to force a wipe/rebuild on client devices.
+- **Modify `subscribeVideos`**: If adding new filters (e.g., "Kids Only Mode"), update the subscription filter here. Ensure the buffer logic remains to protect performance.
+- **Refactor Signers**: If NIP-46 changes or a new signer standard (NIP-XX) emerges, modify `signerHelpers.js` and `client.js` methods (`signAndPublishEvent`).
+
+## Sequence Example: Publish Video
+
+Publishing is not atomic; it's a multi-step orchestration to ensure compatibility across different Nostr clients (WebSeed vs. File Metadata vs. Categorization).
+
+```mermaid
+sequenceDiagram
+    participant UI as VideoUploadModal
+    participant Client as NostrClient
+    participant Signer as NIP-07/46
+    participant Relay
+
+    UI->>Client: publishVideo(payload)
+    activate Client
+
+    Note right of Client: 1. Construct Main Video Note
+    Client->>Client: buildVideoPostEvent (Kind 30078)
+    Client->>Signer: signEvent(Kind 30078)
+    Signer-->>Client: signedEvent
+    Client->>Relay: Publish Kind 30078
+
+    Note right of Client: 2. NIP-94 Mirror (Optional)
+    opt has hosted URL
+        Client->>Client: buildMirrorEvent (Kind 1063)
+        Client->>Signer: signEvent(Kind 1063)
+        Signer-->>Client: signedMirror
+        Client->>Relay: Publish Kind 1063
+    end
+
+    Note right of Client: 3. NIP-71 Metadata (Optional)
+    opt has tags/categories
+        Client->>Client: buildNip71Event (Kind 22)
+        Client->>Signer: signEvent(Kind 22)
+        Signer-->>Client: signedWrapper
+        Client->>Relay: Publish Kind 22
+    end
+
+    Client-->>UI: Success (returns Main Event)
+    deactivate Client
+```