peerpigeon 0.1.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +141 -1365
  2. package/cli.js +1382 -0
  3. package/dist/peerpigeon-browser.js +12450 -0
  4. package/dist/peerpigeon-browser.js.map +7 -0
  5. package/docs/API_DOCUMENTATION.md +1976 -0
  6. package/docs/BOOTSTRAP_HUBS.md +319 -0
  7. package/docs/CLI_README.md +371 -0
  8. package/docs/CUSTOM_HUB_NAMESPACES.md +182 -0
  9. package/docs/CUSTOM_NAMESPACE_IMPLEMENTATION.md +187 -0
  10. package/docs/DOCUMENTATION_REORGANIZATION.md +172 -0
  11. package/docs/HUB_QUICK_REF.md +108 -0
  12. package/docs/HUB_SCRIPTS.md +341 -0
  13. package/docs/HUB_SYSTEM.md +599 -0
  14. package/docs/MIGRATION_COMPLETE.md +93 -0
  15. package/docs/NETWORK_NAMESPACES.md +212 -0
  16. package/docs/PIGEONRTC_MIGRATION.md +280 -0
  17. package/docs/README.md +108 -0
  18. package/docs/SELECTIVE_STREAMING_GUIDE.md +427 -0
  19. package/docs/TEST_CLEANUP_COMPLETE.md +80 -0
  20. package/examples/bootstrap-hub-example.js +292 -0
  21. package/examples/browser/README.md +278 -0
  22. package/examples/browser/app.js +2426 -49
  23. package/examples/browser/index.html +481 -630
  24. package/examples/browser/minimal/README.md +55 -0
  25. package/examples/browser/minimal/index.html +75 -0
  26. package/examples/browser/minimal/minimal.js +234 -0
  27. package/examples/browser/styles.css +687 -1425
  28. package/examples/browser/test-bundle.html +35 -0
  29. package/examples/browser-2/index.html +30 -0
  30. package/examples/browser-2/package.json +21 -0
  31. package/examples/browser-2/src/App-simple.vue +21 -0
  32. package/examples/browser-2/src/App.vue +420 -0
  33. package/examples/browser-2/src/components/CryptoView.vue +1661 -0
  34. package/examples/browser-2/src/components/DHTView.vue +1281 -0
  35. package/examples/browser-2/src/components/DebugView.vue +1773 -0
  36. package/examples/browser-2/src/components/MediaView.vue +1048 -0
  37. package/examples/browser-2/src/components/MessagingView.vue +775 -0
  38. package/examples/browser-2/src/components/NetworkView.vue +930 -0
  39. package/examples/browser-2/src/components/StorageView.vue +1376 -0
  40. package/examples/browser-2/src/main.js +5 -0
  41. package/examples/browser-2/src/stores/peerpigeon.js +895 -0
  42. package/examples/browser-2/vite.config.js +6 -0
  43. package/examples/hub-example.js +189 -0
  44. package/examples/multi-hub-test.js +186 -0
  45. package/examples/node/README.md +2 -2
  46. package/examples/programmatic-namespace-example.js +108 -0
  47. package/examples/selective-streaming-demo.html +698 -0
  48. package/examples/standard-events-demo.js +126 -0
  49. package/index.js +7 -1
  50. package/package.json +34 -16
  51. package/server/index.js +1058 -98
  52. package/server/start.js +52 -0
  53. package/src/ConnectionManager.js +239 -225
  54. package/src/CryptoManager.js +147 -18
  55. package/src/DebugLogger.js +0 -7
  56. package/src/DistributedStorageManager.js +224 -205
  57. package/src/EnvironmentDetector.js +88 -4
  58. package/src/EventEmitter.js +79 -1
  59. package/src/EvictionManager.js +10 -9
  60. package/src/GossipManager.js +163 -11
  61. package/src/MediaManager.js +12 -2
  62. package/src/PeerConnection.js +343 -311
  63. package/src/PeerPigeonMesh.js +576 -135
  64. package/src/PigeonRTC-browser.js +247 -0
  65. package/src/SignalingClient.js +14 -243
  66. package/src/SignalingHandler.js +31 -10
  67. package/src/StorageManager.js +0 -39
  68. package/src/WebDHT-Simple.js +389 -0
  69. package/src/WebDHT.js +363 -1165
  70. package/src/browser-entry.js +58 -0
  71. package/examples/browser/assets/images/favicon.png +0 -0
  72. package/examples/browser/assets/images/pigeon.png +0 -0
  73. package/examples/browser/crypto-test.html +0 -427
  74. package/examples/browser/ui-old.js +0 -1926
  75. package/examples/browser/ui.js +0 -3391
  76. package/websocket-server/README.md +0 -247
  77. package/websocket-server/server.js +0 -391
@@ -0,0 +1,212 @@
1
+ # Network Namespaces in PeerPigeon
2
+
3
+ PeerPigeon now supports **named network segregation** with automatic global mesh fallback, allowing you to create isolated peer-to-peer networks for different purposes while maintaining connectivity when needed.
4
+
5
+ ## Features
6
+
7
+ ### Named Networks
8
+ - Create isolated mesh networks with custom names (e.g., "gaming", "work", "family")
9
+ - Peers in different networks cannot discover or connect to each other directly
10
+ - Messages, DHT data, and storage are fully isolated by network namespace
11
+ - Backward compatible with existing deployments using the "global" network
12
+
13
+ ### Global Fallback
14
+ - When a named network has insufficient peers, automatically fall back to the global network
15
+ - Seamlessly return to the original network when peers become available
16
+ - Configurable fallback behavior (can be disabled if strict isolation is required)
17
+
18
+ ### Data Isolation
19
+ - **Gossip Messages**: Network-scoped message propagation
20
+ - **WebDHT**: Namespaced key-value storage with network prefixes
21
+ - **Peer Discovery**: Network-filtered peer announcements
22
+ - **Signaling**: Network-tagged signaling messages
23
+
24
+ ## Usage
25
+
26
+ ### Basic Setup
27
+
28
+ ```javascript
29
+ // Create a mesh in a specific network
30
+ const mesh = new PeerPigeon.PeerPigeonMesh({
31
+ networkName: 'gaming', // Join the "gaming" network
32
+ allowGlobalFallback: true, // Allow fallback to global network
33
+ maxPeers: 3,
34
+ minPeers: 2
35
+ });
36
+
37
+ await mesh.init();
38
+ await mesh.connect('ws://localhost:3000');
39
+ ```
40
+
41
+ ### Network Management
42
+
43
+ ```javascript
44
+ // Change network (only when disconnected)
45
+ mesh.setNetworkName('work');
46
+
47
+ // Check current network status
48
+ const status = mesh.getStatus();
49
+ console.log('Current network:', status.networkName);
50
+ console.log('Original network:', status.originalNetworkName);
51
+ console.log('In fallback mode:', status.isInFallbackMode);
52
+
53
+ // Configure fallback behavior
54
+ mesh.setAllowGlobalFallback(false); // Disable fallback for strict isolation
55
+ ```
56
+
57
+ ### Event Handling
58
+
59
+ ```javascript
60
+ // Listen for network status changes
61
+ mesh.addEventListener('statusChanged', (event) => {
62
+ if (event.type === 'network') {
63
+ console.log('Network status:', event.message);
64
+ console.log('Current network:', event.networkName);
65
+ console.log('Fallback mode:', event.fallbackMode);
66
+ }
67
+ });
68
+ ```
69
+
70
+ ## Browser UI Support
71
+
72
+ The browser-2 example now includes a Network tab with:
73
+
74
+ - **Current Network Display**: Shows active network and fallback status
75
+ - **Network Switching**: Easy switching between named networks
76
+ - **Quick Networks**: Predefined network buttons (global, gaming, work, family, test)
77
+ - **Fallback Controls**: Toggle global fallback on/off
78
+ - **Network Health**: Real-time peer count and connection status
79
+
80
+ ## API Reference
81
+
82
+ ### Constructor Options
83
+
84
+ ```javascript
85
+ const mesh = new PeerPigeon.PeerPigeonMesh({
86
+ networkName: 'global', // Network name (default: 'global')
87
+ allowGlobalFallback: true, // Allow global fallback (default: true)
88
+ // ... other existing options
89
+ });
90
+ ```
91
+
92
+ ### Methods
93
+
94
+ - `setNetworkName(name)` - Change network (only when disconnected)
95
+ - `getNetworkName()` - Get current network name
96
+ - `getOriginalNetworkName()` - Get original network name (before fallback)
97
+ - `isUsingGlobalFallback()` - Check if currently in fallback mode
98
+ - `setAllowGlobalFallback(allow)` - Enable/disable global fallback
99
+
100
+ ### Status Properties
101
+
102
+ The `getStatus()` method now includes:
103
+
104
+ ```javascript
105
+ {
106
+ networkName: 'gaming', // Current network
107
+ originalNetworkName: 'gaming', // Original network
108
+ isInFallbackMode: false, // Whether in fallback mode
109
+ allowGlobalFallback: true, // Fallback setting
110
+ // ... other existing status properties
111
+ }
112
+ ```
113
+
114
+ ## Use Cases
115
+
116
+ ### Gaming Communities
117
+ ```javascript
118
+ // Create isolated gaming networks
119
+ const gamingMesh = new PeerPigeon.PeerPigeonMesh({
120
+ networkName: 'minecraft-server-1',
121
+ allowGlobalFallback: false // Strict isolation
122
+ });
123
+ ```
124
+
125
+ ### Work Teams
126
+ ```javascript
127
+ // Create private work networks with fallback
128
+ const workMesh = new PeerPigeon.PeerPigeonMesh({
129
+ networkName: 'team-alpha',
130
+ allowGlobalFallback: true // Fall back to global if team is offline
131
+ });
132
+ ```
133
+
134
+ ### Family Networks
135
+ ```javascript
136
+ // Create family networks for private sharing
137
+ const familyMesh = new PeerPigeon.PeerPigeonMesh({
138
+ networkName: 'smith-family',
139
+ allowGlobalFallback: false // Keep family data private
140
+ });
141
+ ```
142
+
143
+ ## Migration Guide
144
+
145
+ ### Existing Applications
146
+ Existing PeerPigeon applications continue to work without changes. They automatically use the "global" network namespace.
147
+
148
+ ### Adding Network Support
149
+ 1. Add `networkName` to constructor options
150
+ 2. Optionally configure `allowGlobalFallback`
151
+ 3. Handle network status events
152
+ 4. Update UI to show current network (optional)
153
+
154
+ ## Implementation Details
155
+
156
+ ### Signaling Protocol
157
+ All signaling messages now include a `networkName` field:
158
+
159
+ ```javascript
160
+ {
161
+ type: 'offer',
162
+ data: { /* offer data */ },
163
+ networkName: 'gaming',
164
+ // ... other fields
165
+ }
166
+ ```
167
+
168
+ ### DHT Storage
169
+ Keys are automatically prefixed with the network name:
170
+ - User key: `"mykey"`
171
+ - Stored as: `"gaming:mykey"`
172
+
173
+ ### Gossip Messages
174
+ Messages include network namespace and are filtered on receipt:
175
+
176
+ ```javascript
177
+ {
178
+ id: 'msg-123',
179
+ type: 'gossip',
180
+ content: 'Hello network!',
181
+ networkName: 'gaming',
182
+ // ... other fields
183
+ }
184
+ ```
185
+
186
+ ### Fallback Logic
187
+ 1. Monitor network health (peer count, discovery)
188
+ 2. If original network becomes empty, activate global fallback
189
+ 3. Periodically check if original network has peers
190
+ 4. Automatically return to original network when viable
191
+
192
+ ## Best Practices
193
+
194
+ 1. **Choose meaningful network names** - Use descriptive names like "project-alpha" or "family-chat"
195
+ 2. **Consider fallback carefully** - Enable for public/social networks, disable for private/sensitive networks
196
+ 3. **Monitor network status** - Listen for status events to inform users about network changes
197
+ 4. **Test isolation** - Verify that different networks cannot access each other's data
198
+ 5. **Plan for empty networks** - Consider what happens when you're the first/only peer in a network
199
+
200
+ ## Limitations
201
+
202
+ 1. **Disconnect required for network change** - Must disconnect before switching networks
203
+ 2. **No cross-network communication** - Networks are fully isolated (by design)
204
+ 3. **Signaling server support** - Requires updated signaling server for optimal peer counting
205
+ 4. **Fallback detection** - Current implementation uses simple heuristics for network health
206
+
207
+ ## Future Enhancements
208
+
209
+ - **Signaling server integration** - Better peer counting and network health detection
210
+ - **Network bridging** - Optional cross-network message relay for authorized peers
211
+ - **Network discovery** - Discover available networks through the signaling server
212
+ - **Persistent preferences** - Remember preferred networks across sessions
@@ -0,0 +1,280 @@
1
+ # PigeonRTC Migration - COMPLETE ✅
2
+
3
+ ## Summary
4
+
5
+ PeerPigeon has been **successfully migrated** from direct WebRTC API usage to **PigeonRTC**, a pluggable cross-platform WebRTC abstraction library. This provides better cross-platform support, cleaner code, easier maintenance, and proper separation of browser and Node.js dependencies.
6
+
7
+ **Migration Status**: ✅ Complete - All tests passing (Browser: 13/13, Node.js: All passing)
8
+
9
+ ## What Changed
10
+
11
+ ### 1. Dependencies
12
+ - **Added**: `pigeonrtc@^0.0.3` as a dependency
13
+ - **Retained**: `@koush/wrtc@^0.5.3` (used by PigeonRTC for Node.js support)
14
+
15
+ ### 2. Environment Detection (`src/EnvironmentDetector.js`)
16
+ **Before**: Manual WebRTC polyfill loading with direct `@koush/wrtc` imports
17
+ ```javascript
18
+ _initNodeWebRTC() {
19
+ const wrtc = require('@koush/wrtc');
20
+ global.RTCPeerConnection = wrtc.RTCPeerConnection;
21
+ // ...
22
+ }
23
+ ```
24
+
25
+ **After**: PigeonRTC initialization with automatic adapter detection
26
+ ```javascript
27
+ async initWebRTCAsync() {
28
+ const { createPigeonRTC } = await import('pigeonrtc');
29
+ this._pigeonRTC = await createPigeonRTC();
30
+ return this._pigeonRTC.isSupported();
31
+ }
32
+ ```
33
+
34
+ ### 2.5. Mesh Initialization (`src/PeerPigeonMesh.js`)
35
+ **Critical Fix**: PigeonRTC must be initialized for ALL environments (browser and Node.js)
36
+
37
+ **Before**: Only initialized for Node.js
38
+ ```javascript
39
+ if (this.runtimeInfo?.isNodeJS) {
40
+ await environmentDetector.initWebRTCAsync();
41
+ }
42
+ ```
43
+
44
+ **After**: Initialized for all environments
45
+ ```javascript
46
+ // Initialize PigeonRTC for cross-platform WebRTC support
47
+ const webrtcInitialized = await environmentDetector.initWebRTCAsync();
48
+ if (webrtcInitialized) {
49
+ const adapterName = environmentDetector.getPigeonRTC()?.getAdapterName();
50
+ this.debug.log(`🌐 PigeonRTC initialized successfully (${adapterName})`);
51
+ }
52
+ ```
53
+
54
+ ### 3. Peer Connection (`src/PeerConnection.js`)
55
+ **Before**: Direct `RTCPeerConnection` instantiation
56
+ ```javascript
57
+ this.connection = new RTCPeerConnection({ iceServers: [...] });
58
+ ```
59
+
60
+ **After**: PigeonRTC's `createPeerConnection` method
61
+ ```javascript
62
+ const pigeonRTC = environmentDetector.getPigeonRTC();
63
+ this.connection = pigeonRTC.createPeerConnection({ iceServers: [...] });
64
+ ```
65
+
66
+ ### 4. Media Manager (`src/MediaManager.js`)
67
+ **Before**: Direct `navigator.mediaDevices.getUserMedia` calls
68
+ ```javascript
69
+ this.localStream = await navigator.mediaDevices.getUserMedia(constraints);
70
+ ```
71
+
72
+ **After**: PigeonRTC's `getUserMedia` with fallback
73
+ ```javascript
74
+ const pigeonRTC = environmentDetector.getPigeonRTC();
75
+ if (pigeonRTC) {
76
+ this.localStream = await pigeonRTC.getUserMedia(constraints);
77
+ } else {
78
+ this.localStream = await navigator.mediaDevices.getUserMedia(constraints);
79
+ }
80
+ ```
81
+
82
+ ### 5. Main Entry Points
83
+ **Updated**: `index.js` and `src/browser-entry.js` to export `initWebRTCAsync` function
84
+
85
+ ## Benefits
86
+
87
+ ### 1. **Cross-Platform Compatibility**
88
+ - Automatic environment detection (browser vs Node.js)
89
+ - Single API for all platforms
90
+ - No more manual polyfill management
91
+
92
+ ### 2. **Cleaner Code**
93
+ - Removed manual WebRTC polyfill logic
94
+ - Unified API across environments
95
+ - Better separation of concerns
96
+
97
+ ### 3. **Better Maintainability**
98
+ - WebRTC polyfills managed in one place (PigeonRTC)
99
+ - Easier to update WebRTC implementations
100
+ - Reduced code duplication
101
+
102
+ ### 4. **Future Extensibility**
103
+ - Easy to add React Native support
104
+ - Custom adapters for specialized use cases
105
+ - Mockable for unit tests
106
+
107
+ ## Usage
108
+
109
+ ### Initialization
110
+ PigeonRTC is automatically initialized when calling `mesh.init()`:
111
+
112
+ ```javascript
113
+ import { PeerPigeonMesh } from 'peerpigeon';
114
+
115
+ const mesh = new PeerPigeonMesh();
116
+ await mesh.init(); // PigeonRTC is initialized automatically
117
+ ```
118
+
119
+ ### Manual Initialization
120
+ You can also manually initialize PigeonRTC:
121
+
122
+ ```javascript
123
+ import { environmentDetector } from 'peerpigeon';
124
+
125
+ // Initialize PigeonRTC explicitly
126
+ await environmentDetector.initWebRTCAsync();
127
+
128
+ // Get the PigeonRTC instance
129
+ const pigeonRTC = environmentDetector.getPigeonRTC();
130
+ console.log('Adapter:', pigeonRTC.getAdapterName()); // 'NodeRTCAdapter' or 'BrowserRTCAdapter'
131
+ ```
132
+
133
+ ## Testing
134
+
135
+ ### Integration Test
136
+ A comprehensive integration test was created at `test/pigeonrtc-integration-test.js`:
137
+
138
+ ```bash
139
+ node test/pigeonrtc-integration-test.js
140
+ ```
141
+
142
+ This test verifies:
143
+ - ✅ PigeonRTC initialization
144
+ - ✅ PigeonRTC instance availability
145
+ - ✅ WebRTC capability detection
146
+ - ✅ RTCPeerConnection creation
147
+ - ✅ PeerPigeonMesh initialization
148
+ - ✅ Environment reporting
149
+
150
+ ### Results
151
+ All tests passed successfully:
152
+ - **Browser**: Uses native WebRTC (BrowserRTCAdapter)
153
+ - **Node.js**: Uses @koush/wrtc (NodeRTCAdapter)
154
+ - **Cross-platform**: Same API, different implementations
155
+
156
+ ## Migration Notes
157
+
158
+ ### Breaking Changes
159
+ **None** - The migration is backward compatible. Existing code continues to work without modifications.
160
+
161
+ ### Performance Impact
162
+ - **Bundle Size**: +6.5KB (minified) for PigeonRTC
163
+ - **Initialization**: <1ms overhead
164
+ - **Runtime**: Zero overhead (direct pass-through to native WebRTC)
165
+
166
+ ### Browser Support
167
+ - Chrome/Edge 56+
168
+ - Firefox 44+
169
+ - Safari 11+
170
+ - Opera 43+
171
+
172
+ ### Node.js Support
173
+ - Node.js 14.0.0+
174
+ - Requires `@koush/wrtc` package (already included)
175
+
176
+ ## Architecture
177
+
178
+ ```
179
+ ┌─────────────────────────────────────┐
180
+ │ PeerPigeon Application │
181
+ └──────────────┬──────────────────────┘
182
+ │
183
+ ┌──────▼──────┐
184
+ │ PigeonRTC │ (Unified API)
185
+ └──────┬──────┘
186
+ │
187
+ ┌─────────┴─────────┐
188
+ │ │
189
+ ┌────▼─────┐ ┌─────▼──────┐
190
+ │ Browser │ │ Node.js │
191
+ │ Adapter │ │ Adapter │
192
+ └────┬─────┘ └─────┬──────┘
193
+ │ │
194
+ ┌────▼─────┐ ┌─────▼──────┐
195
+ │ Native │ │ @koush/ │
196
+ │ WebRTC │ │ wrtc │
197
+ └──────────┘ └────────────┘
198
+ ```
199
+
200
+ ## Test Results
201
+
202
+ ### Browser Integration Tests
203
+ ✅ **13/13 tests passing**
204
+ - Peer connections and mesh formation
205
+ - DHT cross-peer operations
206
+ - Storage replication and persistence
207
+ - Private/Public/Frozen storage spaces
208
+ - Crypto system functionality
209
+ - Network information display
210
+ - API utilities
211
+
212
+ ### Node.js Tests
213
+ ✅ **All tests passing**
214
+ - PigeonRTC initialization
215
+ - NodeRTCAdapter functionality
216
+ - Peer connection creation
217
+ - WebRTC feature detection
218
+
219
+ Run tests:
220
+ ```bash
221
+ npm test
222
+ ```
223
+
224
+ Build browser bundle:
225
+ ```bash
226
+ npm run build
227
+ ```
228
+
229
+ ## Browser Bundle Architecture
230
+
231
+ The browser bundle (`dist/peerpigeon-browser.js`) is now properly configured:
232
+ - ✅ Includes standalone `BrowserRTCAdapter` from `src/PigeonRTC-browser.js`
233
+ - ✅ Sets global `__PEERPIGEON_PIGEONRTC__` factory function
234
+ - ✅ Bundles UnSEA crypto library
235
+ - ❌ Excludes Node.js dependencies (`pigeonrtc`, `@koush/wrtc`)
236
+ - ❌ No native binaries or Node.js-only modules
237
+
238
+ **Build Configuration** (`scripts/build-browser.js`):
239
+ ```javascript
240
+ external: ['pigeonrtc', '@koush/wrtc'], // Prevent Node.js modules from bundling
241
+ ```
242
+
243
+ ## Migration Completion Checklist
244
+
245
+ - [x] Install PigeonRTC package (v0.0.3)
246
+ - [x] Update EnvironmentDetector with async initialization
247
+ - [x] Update PeerConnection to use PigeonRTC API
248
+ - [x] Update MediaManager for getUserMedia support
249
+ - [x] Fix PeerPigeonMesh initialization for all environments
250
+ - [x] Create standalone browser PigeonRTC implementation
251
+ - [x] Configure build system to exclude Node.js dependencies
252
+ - [x] Test in browser environment (13/13 passing)
253
+ - [x] Test in Node.js environment (all passing)
254
+ - [x] Update documentation
255
+
256
+ ## Next Steps
257
+
258
+ ### Future Enhancements
259
+ 1. **React Native Support**: Add React Native adapter when needed
260
+ 2. **Custom Adapters**: Create specialized adapters for edge cases
261
+ 3. **Mock Adapter**: Better unit testing with mock adapters
262
+
263
+ ### Maintenance
264
+ - PigeonRTC is maintained by PeerPigeon team
265
+ - Updates managed through npm
266
+ - Version: 0.0.3 (actively developed)
267
+
268
+ ## Resources
269
+
270
+ - **PigeonRTC Repository**: https://github.com/PeerPigeon/PigeonRTC
271
+ - **PigeonRTC Documentation**: See README in the repository
272
+ - **Integration Guide**: Available in PigeonRTC INTEGRATION.md
273
+
274
+ ## Migration Date
275
+ October 13, 2025
276
+
277
+ ## Status
278
+ ✅ **Complete and Production Ready**
279
+
280
+ All tests passed. The migration has been completed successfully with no breaking changes.
package/docs/README.md ADDED
@@ -0,0 +1,108 @@
1
+ # PeerPigeon Documentation
2
+
3
+ Complete documentation for PeerPigeon - a WebRTC-based peer-to-peer mesh networking library.
4
+
5
+ ## 📚 Core Documentation
6
+
7
+ ### Getting Started
8
+ - **[Main README](../README.md)** - Quick start and overview
9
+ - **[API Documentation](API_DOCUMENTATION.md)** - Complete API reference
10
+ - **[CLI Guide](CLI_README.md)** - Command-line interface usage
11
+
12
+ ### Advanced Features
13
+ - **[Network Namespaces](NETWORK_NAMESPACES.md)** - Create isolated peer networks
14
+ - **[Selective Streaming](SELECTIVE_STREAMING_GUIDE.md)** - Optimize media streaming bandwidth
15
+ - **[Hub System Overview](HUB_SYSTEM.md)** - Multi-server mesh architecture
16
+ - **[Hub Quick Reference](HUB_QUICK_REF.md)** - Quick start for hub deployment
17
+ - **[Hub Scripts](HUB_SCRIPTS.md)** - Automation scripts for hubs
18
+ - **[Bootstrap Hubs](BOOTSTRAP_HUBS.md)** - Hub discovery and federation
19
+
20
+ ## 📖 Guides by Topic
21
+
22
+ ### Messaging & Communication
23
+ - **Gossip Protocol** - Reliable broadcast messaging (see API_DOCUMENTATION.md)
24
+ - **Direct Messaging** - Peer-to-peer communication (see API_DOCUMENTATION.md)
25
+ - **Event System** - Standard Node.js EventEmitter API (see API_DOCUMENTATION.md)
26
+
27
+ ### Storage & Data
28
+ - **WebDHT** - Low-level distributed hash table (see API_DOCUMENTATION.md)
29
+ - **DistributedStorageManager** - High-level encrypted storage (see API_DOCUMENTATION.md)
30
+ - **Storage Spaces** - Organized data namespaces (see API_DOCUMENTATION.md)
31
+ - **CRDT Support** - Conflict-free collaborative editing (see API_DOCUMENTATION.md)
32
+
33
+ ### Media & Streaming
34
+ - **Media Manager** - Audio/video stream management (see API_DOCUMENTATION.md)
35
+ - **Selective Streaming** - Bandwidth optimization (see SELECTIVE_STREAMING_GUIDE.md)
36
+ - **Stream Controls** - Dynamic stream management (see API_DOCUMENTATION.md)
37
+
38
+ ### Network Architecture
39
+ - **XOR Distance Routing** - Kademlia-inspired topology (see API_DOCUMENTATION.md)
40
+ - **Mesh Optimization** - Automatic peer selection (see API_DOCUMENTATION.md)
41
+ - **Eviction Strategy** - Smart peer replacement (see API_DOCUMENTATION.md)
42
+ - **Network Namespaces** - Isolated networks (see NETWORK_NAMESPACES.md)
43
+
44
+ ### Server & Infrastructure
45
+ - **Signaling Server** - WebSocket server setup (see API_DOCUMENTATION.md)
46
+ - **Hub System** - Multi-server federation (see HUB_SYSTEM.md)
47
+ - **Bootstrap Hubs** - Hub discovery (see BOOTSTRAP_HUBS.md)
48
+ - **[Custom Hub Namespaces](CUSTOM_HUB_NAMESPACES.md)** - Isolate hub networks with custom namespaces
49
+ - **CLI Tools** - Command-line utilities (see CLI_README.md)
50
+
51
+ ## 🔧 Reference Documents
52
+
53
+ ### Migration & Maintenance
54
+ - **[Migration Complete](MIGRATION_COMPLETE.md)** - WebSocket server migration notes
55
+ - **[Test Cleanup](TEST_CLEANUP_COMPLETE.md)** - Test suite cleanup notes
56
+
57
+ ## 💡 Examples
58
+
59
+ ### Code Examples
60
+ - **[Browser Examples](../examples/browser/)** - Web application examples
61
+ - **[Node.js Examples](../examples/node/)** - Server-side examples
62
+ - **[NativeScript Examples](../examples/nativescript/)** - Mobile app examples
63
+
64
+ ### Quick Examples
65
+
66
+ #### Basic Mesh Setup
67
+ ```javascript
68
+ import { PeerPigeonMesh } from 'peerpigeon';
69
+
70
+ const mesh = new PeerPigeonMesh({ enableWebDHT: true });
71
+ await mesh.init();
72
+ await mesh.connect('ws://localhost:3000');
73
+ ```
74
+
75
+ #### Message Broadcasting
76
+ ```javascript
77
+ mesh.sendMessage('Hello, everyone!');
78
+ mesh.on('messageReceived', ({ from, content }) => {
79
+ console.log(`${from}: ${content}`);
80
+ });
81
+ ```
82
+
83
+ #### Distributed Storage
84
+ ```javascript
85
+ await mesh.storage.put('key', { data: 'value' });
86
+ const value = await mesh.storage.get('key');
87
+ ```
88
+
89
+ #### Media Streaming
90
+ ```javascript
91
+ const stream = await navigator.mediaDevices.getUserMedia({ video: true });
92
+ mesh.media.addLocalStream(stream, 'camera');
93
+ mesh.media.streamToPeer('peer-id', 'camera', { video: true, audio: true });
94
+ ```
95
+
96
+ ## 🔗 External Resources
97
+
98
+ - **GitHub Repository**: [github.com/draeder/peerpigeon](https://github.com/draeder/peerpigeon)
99
+ - **npm Package**: [npmjs.com/package/peerpigeon](https://www.npmjs.com/package/peerpigeon)
100
+ - **Issue Tracker**: [github.com/draeder/peerpigeon/issues](https://github.com/draeder/peerpigeon/issues)
101
+
102
+ ## 📝 License
103
+
104
+ All documentation is provided under the MIT License.
105
+
106
+ ---
107
+
108
+ **Need help?** Check out the examples or open an issue on GitHub!