Compare commits

..

3 Commits

Author SHA1 Message Date
7c9f4310d0 Merge branch 'main' into fix/1536-hot-reload
Some checks failed
Review Approval Gate / verify-review (pull_request) Failing after 8s
CI / test (pull_request) Failing after 1m8s
CI / validate (pull_request) Failing after 1m7s
2026-04-22 01:12:04 +00:00
15b9a4398c Merge branch 'main' into fix/1536-hot-reload
Some checks failed
Review Approval Gate / verify-review (pull_request) Failing after 8s
CI / test (pull_request) Failing after 1m7s
CI / validate (pull_request) Failing after 1m11s
2026-04-22 01:05:01 +00:00
Alexander Whitestone
11175e72c0 feat: portal hot-reload from portals.json without server restart (closes #1536)
Some checks failed
CI / test (pull_request) Failing after 1m20s
CI / validate (pull_request) Failing after 1m24s
Review Approval Gate / verify-review (pull_request) Failing after 9s
2026-04-21 08:01:56 -04:00
5 changed files with 109 additions and 725 deletions

3
app.js
View File

@@ -734,6 +734,9 @@ async function init() {
const response = await fetch('./portals.json');
const portalData = await response.json();
createPortals(portalData);
// Start portal hot-reload watcher
if (window.PortalHotReload) PortalHotReload.start(5000);
} catch (e) {
console.error('Failed to load portals.json:', e);
addChatMessage('error', 'Portal registry offline. Check logs.');

View File

@@ -1,268 +0,0 @@
# 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:**
```javascript
// 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:**
```javascript
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
```javascript
// 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
```javascript
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
```javascript
const status = visualizer.getStatus();
console.log('Connected:', status.connected);
console.log('Events:', status.eventCount);
console.log('Particles:', status.activeParticles);
```
## Integration with Nexus
### Auto-Initialize
```javascript
// 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
```javascript
// 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
```javascript
// 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
```bash
node --test tests/test_nostr_visualizer.js
```
### Integration Tests
```javascript
// 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.**

View File

@@ -395,9 +395,9 @@
<div id="memory-connections-panel" class="memory-connections-panel" style="display:none;" aria-label="Memory Connections Panel"></div>
<script src="./boot.js"></script>
<script src="./js/nostr-event-visualizer.js"></script>
<script src="./avatar-customization.js"></script>
<script src="./lod-system.js"></script>
<script src="./portal-hot-reload.js"></script>
<script>
function openMemoryFilter() { renderFilterList(); document.getElementById('memory-filter').style.display = 'flex'; }
function closeMemoryFilter() { document.getElementById('memory-filter').style.display = 'none'; }

View File

@@ -1,456 +0,0 @@
/**
* Nostr Event Stream Visualization
* Issue #874: [NEXUS] Implement Nostr Event Stream Visualization
*
* Visualize incoming Nostr events as data streams or particles flowing through
* the Nexus, representing the agent's connection to the wider mesh.
*/
class NostrEventVisualizer {
constructor(options = {}) {
this.relayUrl = options.relayUrl || 'wss://relay.nostr.info';
this.maxEvents = options.maxEvents || 100;
this.particleCount = options.particleCount || 50;
this.streamSpeed = options.streamSpeed || 1.0;
this.particleSize = options.particleSize || 0.5;
this.ws = null;
this.events = [];
this.particles = [];
this.scene = null;
this.camera = null;
this.renderer = null;
this.isConnected = false;
this.reconnectAttempts = 0;
this.maxReconnectAttempts = 5;
// Callbacks
this.onEvent = options.onEvent || (() => {});
this.onConnect = options.onConnect || (() => {});
this.onDisconnect = options.onDisconnect || (() => {});
this.onError = options.onError || console.error;
// Event types to visualize
this.eventTypes = options.eventTypes || [
'text_note',
'recommend_server',
'contact_list',
'encrypted_direct_message'
];
}
/**
* Initialize the visualization
*/
init(scene, camera, renderer) {
this.scene = scene;
this.camera = camera;
this.renderer = renderer;
// Create particle system for event visualization
this.createParticleSystem();
console.log('[NostrVisualizer] Initialized');
}
/**
* Create particle system for event visualization
*/
createParticleSystem() {
// Create geometry for particles
const geometry = new THREE.BufferGeometry();
const positions = new Float32Array(this.particleCount * 3);
const colors = new Float32Array(this.particleCount * 3);
const sizes = new Float32Array(this.particleCount);
// Initialize particles
for (let i = 0; i < this.particleCount; i++) {
// Random position in a sphere
const theta = Math.random() * Math.PI * 2;
const phi = Math.acos(2 * Math.random() - 1);
const r = 50 + Math.random() * 50;
positions[i * 3] = r * Math.sin(phi) * Math.cos(theta);
positions[i * 3 + 1] = r * Math.sin(phi) * Math.sin(theta);
positions[i * 3 + 2] = r * Math.cos(phi);
// Color based on event type
colors[i * 3] = 0.3; // R
colors[i * 3 + 1] = 0.8; // G
colors[i * 3 + 2] = 1.0; // B
sizes[i] = this.particleSize;
// Store particle data
this.particles.push({
index: i,
x: positions[i * 3],
y: positions[i * 3 + 1],
z: positions[i * 3 + 2],
vx: (Math.random() - 0.5) * 0.1,
vy: (Math.random() - 0.5) * 0.1,
vz: (Math.random() - 0.5) * 0.1,
color: { r: 0.3, g: 0.8, b: 1.0 },
size: this.particleSize,
event: null
});
}
geometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
geometry.setAttribute('size', new THREE.BufferAttribute(sizes, 1));
// Create material
const material = new THREE.PointsMaterial({
size: this.particleSize,
vertexColors: true,
transparent: true,
opacity: 0.8,
blending: THREE.AdditiveBlending
});
// Create points
this.particleSystem = new THREE.Points(geometry, material);
this.scene.add(this.particleSystem);
console.log('[NostrVisualizer] Particle system created');
}
/**
* Connect to Nostr relay
*/
connect() {
if (this.isConnected) {
console.warn('[NostrVisualizer] Already connected');
return;
}
console.log(`[NostrVisualizer] Connecting to ${this.relayUrl}...`);
try {
this.ws = new WebSocket(this.relayUrl);
this.ws.onopen = () => {
console.log('[NostrVisualizer] Connected to Nostr relay');
this.isConnected = true;
this.reconnectAttempts = 0;
// Subscribe to events
this.subscribe();
// Call connect callback
this.onConnect();
};
this.ws.onmessage = (event) => {
try {
const data = JSON.parse(event.data);
this.handleEvent(data);
} catch (error) {
console.error('[NostrVisualizer] Failed to parse event:', error);
}
};
this.ws.onclose = () => {
console.log('[NostrVisualizer] Disconnected from Nostr relay');
this.isConnected = false;
// Call disconnect callback
this.onDisconnect();
// Attempt reconnect
this.scheduleReconnect();
};
this.ws.onerror = (error) => {
console.error('[NostrVisualizer] WebSocket error:', error);
this.onError(error);
};
} catch (error) {
console.error('[NostrVisualizer] Failed to connect:', error);
this.onError(error);
}
}
/**
* Subscribe to Nostr events
*/
subscribe() {
if (!this.isConnected || !this.ws) {
console.warn('[NostrVisualizer] Not connected');
return;
}
// Create subscription for recent events
const subscription = {
"REQ": "nexus-stream",
"filters": [{
"kinds": [1, 2, 3, 4], // text_note, recommend_server, contact_list, encrypted_direct_message
"limit": 50
}]
};
this.ws.send(JSON.stringify(subscription));
console.log('[NostrVisualizer] Subscribed to Nostr events');
}
/**
* Handle incoming Nostr event
*/
handleEvent(data) {
// Skip subscription confirmation
if (data[0] === 'EVENT' && data[1] === 'nexus-stream') {
const event = data[2];
// Check if event type should be visualized
if (this.eventTypes.includes(this.getEventType(event.kind))) {
this.visualizeEvent(event);
this.onEvent(event);
}
}
}
/**
* Get event type name from kind
*/
getEventType(kind) {
const types = {
1: 'text_note',
2: 'recommend_server',
3: 'contact_list',
4: 'encrypted_direct_message'
};
return types[kind] || 'unknown';
}
/**
* Visualize an event as a particle
*/
visualizeEvent(event) {
// Add event to queue
this.events.push({
event: event,
timestamp: Date.now(),
visualized: false
});
// Limit queue size
if (this.events.length > this.maxEvents) {
this.events.shift();
}
// Update particle for this event
this.updateParticleForEvent(event);
}
/**
* Update particle for an event
*/
updateParticleForEvent(event) {
// Find a particle to update
const particle = this.particles.find(p => !p.event);
if (!particle) {
// All particles are in use, recycle oldest
const oldest = this.particles.reduce((a, b) =>
(a.event && a.event.timestamp < b.event.timestamp) ? a : b
);
this.resetParticle(oldest);
this.updateParticleWithEvent(oldest, event);
} else {
this.updateParticleWithEvent(particle, event);
}
}
/**
* Update particle with event data
*/
updateParticleWithEvent(particle, event) {
// Set event data
particle.event = event;
// Set color based on event type
const colors = {
'text_note': { r: 0.3, g: 0.8, b: 1.0 }, // Blue
'recommend_server': { r: 1.0, g: 0.8, b: 0.3 }, // Gold
'contact_list': { r: 0.3, g: 1.0, b: 0.8 }, // Cyan
'encrypted_direct_message': { r: 1.0, g: 0.3, b: 0.8 } // Pink
};
const eventType = this.getEventType(event.kind);
particle.color = colors[eventType] || { r: 0.5, g: 0.5, b: 0.5 };
// Update geometry
this.updateParticleGeometry(particle);
console.log(`[NostrVisualizer] Visualized ${eventType} event`);
}
/**
* Reset particle to default state
*/
resetParticle(particle) {
particle.event = null;
particle.color = { r: 0.3, g: 0.8, b: 1.0 };
particle.size = this.particleSize;
// Random position
const theta = Math.random() * Math.PI * 2;
const phi = Math.acos(2 * Math.random() - 1);
const r = 50 + Math.random() * 50;
particle.x = r * Math.sin(phi) * Math.cos(theta);
particle.y = r * Math.sin(phi) * Math.sin(theta);
particle.z = r * Math.cos(phi);
this.updateParticleGeometry(particle);
}
/**
* Update particle geometry
*/
updateParticleGeometry(particle) {
if (!this.particleSystem) return;
const geometry = this.particleSystem.geometry;
const positions = geometry.attributes.position.array;
const colors = geometry.attributes.color.array;
const sizes = geometry.attributes.size.array;
// Update position
positions[particle.index * 3] = particle.x;
positions[particle.index * 3 + 1] = particle.y;
positions[particle.index * 3 + 2] = particle.z;
// Update color
colors[particle.index * 3] = particle.color.r;
colors[particle.index * 3 + 1] = particle.color.g;
colors[particle.index * 3 + 2] = particle.color.b;
// Update size
sizes[particle.index] = particle.size;
// Mark attributes as needing update
geometry.attributes.position.needsUpdate = true;
geometry.attributes.color.needsUpdate = true;
geometry.attributes.size.needsUpdate = true;
}
/**
* Update visualization
*/
update(deltaTime) {
if (!this.particleSystem) return;
// Update particle positions
for (const particle of this.particles) {
// Move particle
particle.x += particle.vx * this.streamSpeed * deltaTime;
particle.y += particle.vy * this.streamSpeed * deltaTime;
particle.z += particle.vz * this.streamSpeed * deltaTime;
// Add some turbulence
particle.vx += (Math.random() - 0.5) * 0.01;
particle.vy += (Math.random() - 0.5) * 0.01;
particle.vz += (Math.random() - 0.5) * 0.01;
// Limit velocity
const maxVel = 0.5;
particle.vx = Math.max(-maxVel, Math.min(maxVel, particle.vx));
particle.vy = Math.max(-maxVel, Math.min(maxVel, particle.vy));
particle.vz = Math.max(-maxVel, Math.min(maxVel, particle.vz));
// Keep particles in bounds
const maxDist = 100;
if (Math.abs(particle.x) > maxDist) particle.vx *= -0.5;
if (Math.abs(particle.y) > maxDist) particle.vy *= -0.5;
if (Math.abs(particle.z) > maxDist) particle.vz *= -0.5;
// Update geometry
this.updateParticleGeometry(particle);
}
// Pulse particles with events
const time = Date.now() * 0.001;
for (const particle of this.particles) {
if (particle.event) {
// Pulse size for particles with events
particle.size = this.particleSize * (1 + 0.2 * Math.sin(time * 3 + particle.index));
this.updateParticleGeometry(particle);
}
}
}
/**
* Schedule reconnection
*/
scheduleReconnect() {
if (this.reconnectAttempts >= this.maxReconnectAttempts) {
console.error('[NostrVisualizer] Max reconnect attempts reached');
return;
}
const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);
console.log(`[NostrVisualizer] Reconnecting in ${delay / 1000}s...`);
setTimeout(() => {
this.reconnectAttempts++;
this.connect();
}, delay);
}
/**
* Disconnect from Nostr relay
*/
disconnect() {
console.log('[NostrVisualizer] Disconnecting...');
if (this.ws) {
this.ws.close();
this.ws = null;
}
this.isConnected = false;
// Clear particles
for (const particle of this.particles) {
this.resetParticle(particle);
}
console.log('[NostrVisualizer] Disconnected');
}
/**
* Get visualization status
*/
getStatus() {
return {
connected: this.isConnected,
relayUrl: this.relayUrl,
eventCount: this.events.length,
particleCount: this.particles.length,
activeParticles: this.particles.filter(p => p.event).length,
reconnectAttempts: this.reconnectAttempts
};
}
}
// Export for use in other modules
if (typeof module !== 'undefined' && module.exports) {
module.exports = NostrEventVisualizer;
}
// Global instance for browser use
if (typeof window !== 'undefined') {
window.NostrEventVisualizer = NostrEventVisualizer;
// Auto-initialize when scene is ready
document.addEventListener('DOMContentLoaded', () => {
// This would be called when Three.js scene is initialized
// window.nostrVisualizer = new NostrEventVisualizer();
// window.nostrVisualizer.init(scene, camera, renderer);
});
}

105
portal-hot-reload.js Normal file
View File

@@ -0,0 +1,105 @@
/**
* Portal Hot-Reload for The Nexus
*
* Watches portals.json for changes and hot-reloads portal list
* without server restart. Existing connections unaffected.
*
* Usage:
* PortalHotReload.start(intervalMs);
* PortalHotReload.stop();
* PortalHotReload.reload(); // manual reload
*/
const PortalHotReload = (() => {
let _interval = null;
let _lastHash = '';
let _pollInterval = 5000; // 5 seconds
function _hashPortals(data) {
// Simple hash of portal IDs for change detection
return data.map(p => p.id || p.name).sort().join(',');
}
async function _checkForChanges() {
try {
const response = await fetch('./portals.json?t=' + Date.now());
if (!response.ok) return;
const data = await response.json();
const hash = _hashPortals(data);
if (hash !== _lastHash) {
console.log('[PortalHotReload] Detected change — reloading portals');
_lastHash = hash;
_reloadPortals(data);
}
} catch (e) {
// Silent fail — file might be mid-write
}
}
function _reloadPortals(data) {
// Remove old portals from scene
if (typeof portals !== 'undefined' && Array.isArray(portals)) {
portals.forEach(p => {
if (p.group && typeof scene !== 'undefined' && scene) {
scene.remove(p.group);
}
});
portals.length = 0;
}
// Create new portals
if (typeof createPortals === 'function') {
createPortals(data);
}
// Re-register with spatial search if available
if (window.SpatialSearch && typeof portals !== 'undefined') {
portals.forEach(p => {
if (p.config && p.config.name && p.group) {
SpatialSearch.register('portal', p, p.config.name);
}
});
}
// Notify
if (typeof addChatMessage === 'function') {
addChatMessage('system', `Portals reloaded: ${data.length} portals active`);
}
console.log(`[PortalHotReload] Reloaded ${data.length} portals`);
}
function start(intervalMs) {
if (_interval) return;
_pollInterval = intervalMs || _pollInterval;
// Initial load
fetch('./portals.json').then(r => r.json()).then(data => {
_lastHash = _hashPortals(data);
}).catch(() => {});
_interval = setInterval(_checkForChanges, _pollInterval);
console.log(`[PortalHotReload] Watching portals.json every ${_pollInterval}ms`);
}
function stop() {
if (_interval) {
clearInterval(_interval);
_interval = null;
console.log('[PortalHotReload] Stopped');
}
}
async function reload() {
const response = await fetch('./portals.json?t=' + Date.now());
const data = await response.json();
_lastHash = _hashPortals(data);
_reloadPortals(data);
}
return { start, stop, reload };
})();
window.PortalHotReload = PortalHotReload;