Merge pull request #820 from PR0M3TH3AN/codex/update-documentation-for-new-import-paths

Document nostr facade migration

README.md

@@ -192,6 +192,19 @@ fresh output so third-party dependencies cannot sneak inline style mutations
 into production. Use `npm run build:beacon:bundle` only if you need the raw
 esbuild output for debugging.
 
+### Nostr facade migration
+
+Nostr helpers now ship behind dedicated facades so downstream plugins can pick
+the entry point that matches their feature set:
+
+1. **Default client ([NIP-07](https://github.com/nostr-protocol/nips/blob/master/07.md)):** `import { nostrClient, requestDefaultExtensionPermissions } from './nostrClientFacade.js';`
+2. **View counters ([NIP-71](https://github.com/nostr-protocol/nips/blob/master/71.md)):** `import { recordVideoView, subscribeVideoViewEvents } from './nostrViewEventsFacade.js';`
+3. **Watch-history lists ([NIP-51](https://github.com/nostr-protocol/nips/blob/master/51.md) + [NIP-04](https://github.com/nostr-protocol/nips/blob/master/04.md) encryption):** `import { updateWatchHistoryListWithDefaultClient } from './nostrWatchHistoryFacade.js';`
+
+`js/nostr.js` remains as a compatibility shim while existing plugins migrate, but
+it will be removed in a future release. Move any legacy `import { ... } from './nostr.js';`
+calls over to the facades above so upgrades stay painless.
+
 The build command compiles Tailwind with `tailwind.config.cjs`, runs it through
 the PostCSS pipeline defined in `postcss.config.cjs` (for autoprefixing), and
 emits the purged, minified stylesheet at `css/tailwind.generated.css`. Commit the

docs/nostr-analytics.md

@@ -26,7 +26,13 @@ Every view event includes a unique `#d` tag derived from the pointer scope, the
 
 ### Client bindings & feature toggles
 
-When wiring moderation or playback toggles into view analytics, call through [`js/nostr/viewEventBindings.js`](../js/nostr/viewEventBindings.js). The binding wraps the singleton client so feature flags, relay discovery, and COUNT/LIST fallbacks all run through the same guard clauses that enforce the NIP-71/NIP-78 schemas. Modules that need to no-op when relays disable optional methods can rely on the binding’s "unavailable" errors to short-circuit cleanly.
+When wiring moderation or playback toggles into view analytics, import helpers from the [NIP-71](https://github.com/nostr-protocol/nips/blob/master/71.md) facade and let it reach into the binding layer for you:
+
+```js
+import { recordVideoView, subscribeVideoViewEvents } from "../nostrViewEventsFacade.js";
+```
+
+The facade wraps [`js/nostr/viewEventBindings.js`](../js/nostr/viewEventBindings.js) so feature flags, relay discovery, and COUNT/LIST fallbacks all run through the same guard clauses that enforce the NIP-71/NIP-78 schemas. `js/nostr.js` still exports shimmed versions for legacy bundles, but new code should migrate to the facades to keep the eventual removal painless. Modules that need to no-op when relays disable optional methods can rely on the binding’s "unavailable" errors to short-circuit cleanly.
 
 ### Hydration, COUNT, and UI sync
 

docs/nostr-event-schemas.md

@@ -48,7 +48,8 @@ Authentication providers should register their capabilities with the
 `nostrClient` after login so every publish helper can reuse them:
 
 ```js
-import { setActiveSigner } from "./nostr/index.js";
+import { nostrClient } from "./nostrClientFacade.js";
+import { setActiveSigner } from "./nostr/client.js";
 
 setActiveSigner({
   type: "extension", // optional label, used to request NIP-07 permissions
@@ -59,10 +60,14 @@ setActiveSigner({
   nip44Encrypt: (targetHex, plaintext) => extension.nip44.encrypt(targetHex, plaintext),
   nip44Decrypt: (actorHex, ciphertext) => extension.nip44.decrypt(actorHex, ciphertext),
 });
+
+await nostrClient.ensureExtensionPermissions();
 ```
 
 `setActiveSigner` accepts any object that implements the subset of capabilities
-you support. `nostrClient` will prefer the registered signer for signing and
+you support. `nostrClient` (imported from the
+[NIP-07](https://github.com/nostr-protocol/nips/blob/master/07.md)-aligned
+`nostrClientFacade.js`) will prefer the registered signer for signing and
 encryption before falling back to session actors. Call `clearActiveSigner()` on
 logout if your integration manages session state manually; the built-in logout
 handler already does this for the default extension flow.
@@ -99,13 +104,32 @@ timestamps.
 `nostrClient` instance, registers it with the runtime via
 `registerNostrClient`, and exposes helpers like
 `requestDefaultExtensionPermissions`. Import the singleton or permission helper
-from this module or from the canonical export barrel at
-[`js/nostr/index.js`](../js/nostr/index.js) whenever you need to run a NIP-07
-handshake. `js/nostr.js` re-exports the default client alongside the
-singleton-aware bindings for view counters and watch history so legacy imports
-continue to resolve. New NIP features should reuse this bootstrapper instead of
-creating bespoke clients so permission caching and relay wiring stay
-consistent.【F:js/nostr/defaultClient.js†L1-L25】
+through the dedicated facade when you need to run a NIP-07 handshake:
+
+```js
+import { nostrClient, requestDefaultExtensionPermissions } from "./nostrClientFacade.js";
+```
+
+`js/nostr.js` remains as a compatibility shim while downstream packages migrate;
+it forwards to the new facades but is slated for removal once legacy imports
+are retired.【F:js/nostr/defaultClient.js†L1-L25】【F:js/nostr.js†L1-L92】
+
+For analytics, route through the
+[NIP-71](https://github.com/nostr-protocol/nips/blob/master/71.md) helpers in
+`nostrViewEventsFacade.js`:
+
+```js
+import { recordVideoView } from "./nostrViewEventsFacade.js";
+```
+
+Watch-history list management layers
+[NIP-51](https://github.com/nostr-protocol/nips/blob/master/51.md) semantics on
+encrypted snapshots—import from `nostrWatchHistoryFacade.js` to stay aligned
+with the chunk/index lifecycle:
+
+```js
+import { updateWatchHistoryListWithDefaultClient } from "./nostrWatchHistoryFacade.js";
+```
 
 ## Event catalogue