the-nexus/docs/nostr-event-visualizer.md

Nostr Event Stream Visualization

Issue: #874 - [NEXUS] Implement Nostr Event Stream Visualization

Overview

Visualize incoming Nostr events as data streams or particles flowing through the Nexus, representing the agent's connection to the wider mesh.

Architecture

+---------------------------------------------------+
|           Nostr Event Visualizer                  |
+---------------------------------------------------|
|  Nostr Relay Connection                           |
|  +-------------+  +-------------+  +-------------+
|  | WebSocket   |  | Event       |  | Subscription|
|  | Client      |  | Handler     |  | Manager     |
|  +-------------+  +-------------+  +-------------+
|  +-------------+  +-------------+  +-------------+
|  | Particle    |  | Color       |  | Animation   |
|  | System      |  | Manager     |  | Engine      |
|  +-------------+  +-------------+  +-------------+
+---------------------------------------------------+

Components

1. Nostr Event Visualizer (js/nostr-event-visualizer.js)

Main visualization class for Nostr events.

Features:

• Connect to Nostr relay via WebSocket
• Subscribe to event stream
• Visualize events as particles
• Color-coded by event type
• Animated particle system

Usage:

// Create visualizer
const visualizer = new NostrEventVisualizer({
    relayUrl: 'wss://relay.nostr.info',
    maxEvents: 100,
    particleCount: 50,
    streamSpeed: 1.0
});

// Initialize with Three.js scene
visualizer.init(scene, camera, renderer);

// Connect to Nostr relay
visualizer.connect();

// Update visualization
visualizer.update(deltaTime);

2. Event Types Visualized

Event Type	Color	Description
text_note	Blue	Text notes/posts
recommend_server	Gold	Server recommendations
contact_list	Cyan	Contact lists
encrypted_direct_message	Pink	Encrypted messages

3. Particle System

Features:

• Particles flow through the Nexus world
• Color-coded by event type
• Size pulses for active events
• Turbulence for natural movement
• Bounded within world space

Configuration:

const visualizer = new NostrEventVisualizer({
    particleCount: 50,        // Number of particles
    streamSpeed: 1.0,         // Flow speed
    particleSize: 0.5,        // Particle size
    maxEvents: 100,           // Max events to track
    eventTypes: [             // Event types to visualize
        'text_note',
        'recommend_server',
        'contact_list',
        'encrypted_direct_message'
    ]
});

Usage Examples

Basic Usage

// Create visualizer
const visualizer = new NostrEventVisualizer({
    relayUrl: 'wss://relay.nostr.info'
});

// Initialize with Three.js
visualizer.init(scene, camera, renderer);

// Connect to relay
visualizer.connect();

// Update in animation loop
function animate() {
    requestAnimationFrame(animate);
    visualizer.update(1/60);  // 60 FPS
    renderer.render(scene, camera);
}
animate();

With Event Callbacks

const visualizer = new NostrEventVisualizer({
    onEvent: (event) => {
        console.log('New event:', event.kind, event.content);
    },
    onConnect: () => {
        console.log('Connected to Nostr relay');
    },
    onDisconnect: () => {
        console.log('Disconnected from Nostr relay');
    }
});

Get Status

const status = visualizer.getStatus();
console.log('Connected:', status.connected);
console.log('Events:', status.eventCount);
console.log('Particles:', status.activeParticles);

Integration with Nexus

Auto-Initialize

// In app.js or initialization code
document.addEventListener('DOMContentLoaded', () => {
    // Wait for Three.js scene to be ready
    if (window.scene && window.camera && window.renderer) {
        const visualizer = new NostrEventVisualizer();
        visualizer.init(window.scene, window.camera, window.renderer);
        visualizer.connect();
        
        // Store globally
        window.nostrVisualizer = visualizer;
    }
});

With Animation Loop

// In animation loop
function animate() {
    requestAnimationFrame(animate);
    
    // Update Nostr visualizer
    if (window.nostrVisualizer) {
        window.nostrVisualizer.update(1/60);
    }
    
    // Render scene
    renderer.render(scene, camera);
}

Event Handling

Event Types

// text_note (kind 1)
{
    "id": "...",
    "pubkey": "...",
    "created_at": 1234567890,
    "kind": 1,
    "tags": [],
    "content": "Hello Nostr!",
    "sig": "..."
}

// recommend_server (kind 2)
{
    "id": "...",
    "pubkey": "...",
    "created_at": 1234567890,
    "kind": 2,
    "tags": [],
    "content": "wss://relay.example.com",
    "sig": "..."
}

// contact_list (kind 3)
{
    "id": "...",
    "pubkey": "...",
    "created_at": 1234567890,
    "kind": 3,
    "tags": [["p", "pubkey1"], ["p", "pubkey2"]],
    "content": "",
    "sig": "..."
}

// encrypted_direct_message (kind 4)
{
    "id": "...",
    "pubkey": "...",
    "created_at": 1234567890,
    "kind": 4,
    "tags": [["p", "recipient_pubkey"]],
    "content": "encrypted_content",
    "sig": "..."
}

Testing

Unit Tests

node --test tests/test_nostr_visualizer.js

Integration Tests

// Create visualizer
const visualizer = new NostrEventVisualizer();

// Connect to relay
visualizer.connect();

// Check status
const status = visualizer.getStatus();
assert(status.connected === true);

// Update visualization
visualizer.update(1/60);

// Disconnect
visualizer.disconnect();

Related Issues

• Issue #874: This implementation
• Issue #1124: MemPalace integration (related visualization)

Files

• js/nostr-event-visualizer.js - Main visualization module
• docs/nostr-event-visualizer.md - This documentation
• tests/test_nostr_visualizer.js - Test suite (to be added)

Conclusion

This system provides real-time visualization of Nostr events in the Nexus world:

1. Connection to Nostr relays via WebSocket
2. Visualization of events as colored particles
3. Animation with turbulence and pulsing
4. Integration with Three.js scene

Ready for production use.