spore-ledlab/MULTI_NODE_UPDATE.md

# Multi-Node Canvas Grid Update

## Overview

The SPORE LEDLab interface has been redesigned to display all SPORE nodes simultaneously with individual canvases in a responsive grid layout. Each node can be controlled independently with its own preset and parameters.

## Key Changes

### 1. UI Layout Redesign

**Before:**
- Single canvas display in center
- Node list in right sidebar
- Controls always visible in right sidebar

**After:**
- Full-width grid layout displaying all nodes
- Each node has its own canvas card
- Floating control panel appears when a node is selected
- Maximizes screen space for displaying multiple nodes

### 2. New Components

#### `NodeCanvasGrid` Component
- **Location:** `/public/scripts/node-canvas-grid.js`
- **Purpose:** Manages the grid of node canvases
- **Features:**
  - Displays all discovered SPORE nodes in a responsive grid
  - Each node card shows:
    - Node IP address
    - Connection status (connected/streaming)
    - Live canvas with streaming visualization
  - Click on any node to select it and show controls
  - Supports both individual node selection and broadcast mode
  - Real-time frame rendering for each node

#### Updated `PresetControls` Component
- **Location:** `/public/scripts/preset-controls.js`
- **Changes:**
  - Now works with floating control panel
  - Tracks parameters per node (using Map)
  - Restores node-specific settings when switching between nodes
  - Sends node-specific commands to server

### 3. CSS Styling

#### New Classes
- `.matrix-grid-section` - Full-width container for node grid
- `.node-canvas-grid` - CSS grid layout for node cards
- `.node-canvas-item` - Individual node card styling
  - Hover effects
  - Selected state (green border glow)
  - Streaming animation
- `.floating-controls` - Floating control panel
  - Appears when node is selected
  - Slides in from right (desktop) or bottom (mobile)
  - Closes when clicking X or deselecting node

#### Responsive Design
- Desktop: 3-4 columns based on screen width
- Tablet: 2-3 columns
- Mobile: 1-2 columns with controls sliding from bottom

### 4. Server-Side Multi-Node Streaming

#### Updated `LEDLabServer` Class
- **Location:** `/server/index.js`
- **New Features:**
  - `nodeStreams` Map: Tracks active streams per node
  - `nodeConfigurations` Map: Stores per-node settings
  - Simultaneous streaming to multiple nodes
  - Per-node preset instances and parameters

#### Key Methods Updated
- `startPreset(presetName, width, height, nodeIp, parameters)`
  - Now accepts nodeIp to target specific node
  - Supports initial parameter values
  
- `stopStreaming(nodeIp)`
  - Stops streaming for specific node or all nodes
  
- `updatePresetParameter(parameter, value, nodeIp)`
  - Updates parameters for specific node or broadcast to all
  
- `streamFrameForNode(nodeIp)`
  - Generates and sends frames for specific node
  - Multiple intervals running simultaneously

### 5. HTML Structure

#### Stream View (Main View)
```html
<section class="matrix-grid-section">
  <div class="node-canvas-grid">
    <!-- Node cards dynamically created here -->
  </div>
</section>

<aside class="floating-controls">
  <!-- Control panel content -->
</aside>
```

### 6. User Workflow

1. **Node Discovery**
   - Nodes automatically discovered via UDP
   - Each node appears as a card in the grid

2. **Node Selection**
   - Click any node card to select it
   - Floating control panel appears
   - Node card highlights with green border

3. **Configure Node**
   - Select preset from dropdown
   - Adjust parameters with sliders
   - Changes apply only to selected node

4. **Start Streaming**
   - Click "Start Streaming" button
   - Node card shows "streaming" status
   - Canvas displays live animation

5. **Multi-Node Operation**
   - Select different node
   - Configure with different preset/parameters
   - Start streaming independently
   - Multiple nodes can stream simultaneously

6. **Broadcast Mode**
   - Click "Broadcast to All" button
   - Control panel shows "Broadcast to All"
   - Preset and parameters apply to all nodes

## Technical Details

### Per-Node State Management

#### Client-Side (PresetControls)
```javascript
this.nodeParameters = new Map(); // nodeIp -> {presetName, parameters}
```
- Stores preset selection and parameters for each node
- Restores settings when switching between nodes
- Maintains independent state per node

#### Server-Side (LEDLabServer)
```javascript
this.nodeStreams = new Map(); // nodeIp -> {preset, presetName, interval, matrixSize}
this.nodeConfigurations = new Map(); // nodeIp -> {presetName, parameters, matrixSize}
```
- Active streams run independently with separate intervals
- Configurations saved per node
- Multiple presets can run simultaneously

### WebSocket Messages

#### Enhanced Messages
All streaming-related messages now include optional `nodeIp` field:
```javascript
{
  type: 'startPreset',
  presetName: 'lava-lamp',
  width: 16,
  height: 16,
  nodeIp: '192.168.1.100', // or null for broadcast
  parameters: {speed: 1.5, scale: 2.0}
}
```

### Frame Rendering

Each node has its own canvas with:
- Independent rendering context
- Automatic sizing based on container
- Serpentine pixel order support
- Glow effects for bright pixels
- Smooth animations

## Benefits

1. **Visual Overview** - See all nodes at once
2. **Independent Control** - Each node can run different animations
3. **Space Efficient** - Responsive grid maximizes screen usage
4. **Scalable** - Works with 1-20+ nodes
5. **Intuitive** - Click to select, visual feedback
6. **Flexible** - Individual or broadcast mode

## Backwards Compatibility

- Old single-stream API still supported
- Settings view unchanged
- Existing presets work without modification
- UDP discovery unchanged

## File Changes Summary

### New Files
- `/public/scripts/node-canvas-grid.js` - New component

### Modified Files
- `/public/index.html` - Updated layout
- `/public/styles/main.css` - New grid and floating control styles
- `/public/scripts/preset-controls.js` - Per-node parameter tracking
- `/public/scripts/ledlab-app.js` - Initialize new component
- `/server/index.js` - Multi-node streaming support

### Unchanged Files
- All preset files (`/presets/*.js`)
- `/server/udp-discovery.js`
- `/public/scripts/framework.js`
- `/public/scripts/theme-manager.js`
- `/public/scripts/navigation.js`

## Testing Recommendations

1. Test with single node
2. Test with multiple nodes (2-4)
3. Test node selection and switching
4. Test broadcast mode
5. Test parameter independence
6. Test starting/stopping individual streams
7. Test responsive layout on different screen sizes
8. Test node disconnection/reconnection

## Future Enhancements

- Drag to reorder nodes
- Group nodes for collective control
- Save/load multi-node scenes
- Node status graphs
- Performance metrics per node