# Strudel Music Coding Page - Architecture Plan

## Project Overview

Create a live music coding interface in [`strudel.html`](../www/strudel.html) that allows users to write and execute Strudel code patterns in real-time. The page will use the `@strudel/web` package for audio generation and CodeMirror 6 for code editing with syntax highlighting.

## Goals

1. **Immediate Goal**: Create a functional music coding interface with Play, Stop, and Reload controls
2. **Future Goal**: Add AI-powered code generation and editing capabilities via API calls

## Architecture Overview

```mermaid
graph TD
    A[User Interface] --> B[Control Panel]
    A --> C[CodeMirror Editor]
    A --> D[Visualization Area]
    B --> E[Play Button]
    B --> F[Stop Button]
    B --> G[Reload Button]
    C --> H[Strudel Code]
    H --> I[@strudel/web Engine]
    I --> J[Audio Output]
    I --> D
    E --> I
    F --> I
    G --> C
```

## Technology Stack

### Core Libraries

1. **@strudel/web** (v1.0.3+)
   - Purpose: Strudel audio engine and pattern evaluation
   - CDN: `https://unpkg.com/@strudel/web@1.0.3`
   - Key Functions:
     - `initStrudel()` - Initialize the audio engine
     - `note().play()` - Play patterns
     - `hush()` - Stop all audio

2. **CodeMirror 6**
   - Purpose: Code editor with syntax highlighting
   - Packages needed:
     - `@codemirror/state`
     - `@codemirror/view`
     - `@codemirror/lang-javascript`
     - `@codemirror/theme-one-dark` (for dark mode)
   - CDN: Use ES modules from unpkg or skypack

3. **Existing Template Infrastructure**
   - NDK integration (already in template)
   - Theme system (dark/light mode)
   - Hamburger menu navigation
   - Footer relay status

## UI Layout Design

### Layout Structure

```
┌─────────────────────────────────────────────────────────┐
│                    HEADER (existing)                     │
├──────────────────────────┬──────────────────────────────┤
│                          │                              │
│   CODE EDITOR            │    VISUALIZATION AREA        │
│   (CodeMirror)           │    (Canvas/WebGL)            │
│                          │                              │
│   - Line numbers         │    - Waveform display        │
│   - Syntax highlight     │    - Pattern visualization   │
│   - Auto-complete        │    - Audio meters            │
│                          │                              │
├──────────────────────────┴──────────────────────────────┤
│              CONTROL PANEL (centered)                    │
│         [▶ Play]  [⏹ Stop]  [↻ Reload]                 │
├─────────────────────────────────────────────────────────┤
│                    FOOTER (existing)                     │
└─────────────────────────────────────────────────────────┘
```

### Responsive Breakpoints

- **Desktop (>1024px)**: Side-by-side editor and visualization
- **Tablet (768-1024px)**: Stacked layout with editor on top
- **Mobile (<768px)**: Full-width stacked, smaller controls

## Component Specifications

### 1. Control Panel

**Location**: Below the main content area, above footer

**Buttons**:
- **Play Button** (▶)
  - Action: Evaluate code and start playback
  - State: Disabled during playback, enabled when stopped
  - Keyboard shortcut: Ctrl+Enter (Cmd+Enter on Mac)
  
- **Stop Button** (⏹)
  - Action: Call `hush()` to stop all audio
  - State: Enabled during playback, disabled when stopped
  - Keyboard shortcut: Ctrl+.
  
- **Reload Button** (↻)
  - Action: Reset editor to default example code
  - State: Always enabled
  - Confirmation: Ask before discarding unsaved changes

**Styling**:
- Use existing CSS variables for colors
- Match hamburger button style
- Add hover effects and transitions
- Show loading state during initialization

### 2. CodeMirror Editor

**Configuration**:
```javascript
{
  language: javascript,
  theme: oneDark (or match template theme),
  lineNumbers: true,
  highlightActiveLine: true,
  bracketMatching: true,
  autocompletion: true,
  indentUnit: 2,
  tabSize: 2
}
```

**Features**:
- JavaScript syntax highlighting
- Line numbers
- Active line highlighting
- Bracket matching
- Auto-indentation
- Keyboard shortcuts (Ctrl+Enter to play)

**Default Code**:
```javascript
// Welcome to Strudel!
// Press Play or Ctrl+Enter to start

note("<c a f e>(3,8)")
  .s("piano")
  .room(0.5)
```

**Integration Points for AI** (future):
- Selection API for targeted edits
- Cursor position tracking
- Code insertion at cursor
- Undo/redo integration

### 3. Visualization Area

**Purpose**: Provide visual feedback during playback

**Options** (choose one or combine):

1. **Simple Waveform Display**
   - Canvas-based oscilloscope
   - Shows audio waveform in real-time
   - Minimal CPU usage

2. **Pattern Visualization**
   - Visual representation of the pattern structure
   - Shows active notes/events
   - Timeline view

3. **Audio Meters**
   - VU meters for volume levels
   - Peak indicators
   - Frequency spectrum analyzer

**Recommendation**: Start with simple waveform, add more later

### 4. Error Display

**Location**: Overlay or bottom panel

**Features**:
- Show JavaScript errors from code evaluation
- Show Strudel-specific errors
- Syntax error highlighting in editor
- Clear error messages with line numbers
- Dismissible error panel

**Styling**:
- Red/orange color scheme for errors
- Semi-transparent overlay
- Close button
- Auto-dismiss after successful play

## Implementation Steps

### Phase 1: Basic Setup

1. **Add Dependencies**
   - Add `@strudel/web` script tag
   - Add CodeMirror 6 ES modules
   - Verify loading order

2. **Create HTML Structure**
   - Add editor container div
   - Add visualization container div
   - Add control panel with buttons
   - Add error display container

3. **Initialize Strudel**
   - Call `initStrudel()` on page load
   - Wait for audio context initialization
   - Handle initialization errors

### Phase 2: Editor Integration

1. **Setup CodeMirror**
   - Create editor instance
   - Configure extensions
   - Apply theme matching template
   - Add default code

2. **Add Keyboard Shortcuts**
   - Ctrl+Enter: Play
   - Ctrl+.: Stop
   - Ctrl+R: Reload (with confirmation)

### Phase 3: Playback Controls

1. **Play Button**
   ```javascript
   async function handlePlay() {
     try {
       const code = editor.state.doc.toString();
       // Evaluate code in Strudel context
       const pattern = eval(code);
       await pattern.play();
       updateButtonStates('playing');
     } catch (error) {
       showError(error);
     }
   }
   ```

2. **Stop Button**
   ```javascript
   function handleStop() {
     hush();
     updateButtonStates('stopped');
   }
   ```

3. **Reload Button**
   ```javascript
   function handleReload() {
     if (hasUnsavedChanges()) {
       if (!confirm('Discard changes?')) return;
     }
     editor.dispatch({
       changes: {
         from: 0,
         to: editor.state.doc.length,
         insert: DEFAULT_CODE
       }
     });
   }
   ```

### Phase 4: Visualization

1. **Setup Canvas**
   - Create canvas element
   - Get 2D or WebGL context
   - Setup animation loop

2. **Connect Audio**
   - Get audio context from Strudel
   - Create analyzer node
   - Connect to visualization

3. **Render Loop**
   - Request animation frame
   - Update visualization
   - Handle resize events

### Phase 5: Error Handling

1. **Code Evaluation Errors**
   - Wrap eval in try-catch
   - Parse error messages
   - Highlight error lines in editor

2. **Audio Errors**
   - Handle audio context issues
   - Show user-friendly messages
   - Provide recovery options

3. **Network Errors**
   - Handle CDN loading failures
   - Show offline message
   - Provide retry mechanism

## Code Structure

### File Organization

```
www/
├── strudel.html (main file)
├── css/
│   ├── client.css (existing)
│   └── strudel.css (new - Strudel-specific styles)
├── js/
│   ├── init-ndk.mjs (existing)
│   ├── strudel-editor.mjs (new - CodeMirror setup)
│   ├── strudel-controls.mjs (new - Play/Stop/Reload)
│   └── strudel-viz.mjs (new - Visualization)
```

### Module Structure

**strudel-editor.mjs**:
```javascript
export function createEditor(container, defaultCode);
export function getEditorContent();
export function setEditorContent(code);
export function addKeyboardShortcuts(handlers);
```

**strudel-controls.mjs**:
```javascript
export function initControls(editor);
export async function play(code);
export function stop();
export function reload();
export function updateButtonStates(state);
```

**strudel-viz.mjs**:
```javascript
export function initVisualization(container);
export function connectAudio(audioContext);
export function startAnimation();
export function stopAnimation();
```

## Styling Guidelines

### CSS Variables to Use

```css
/* From existing template */
--primary-color
--secondary-color
--accent-color
--background-color
--text-color
--border-color
```

### New CSS Classes

```css
.strudel-container {
  /* Main container for editor and viz */
}

.strudel-editor {
  /* CodeMirror container */
}

.strudel-visualization {
  /* Visualization area */
}

.strudel-controls {
  /* Control panel */
}

.strudel-button {
  /* Button styling */
}

.strudel-error {
  /* Error display */
}
```

### Dark/Light Mode Support

- Use CSS variables for colors
- Sync with template theme toggle
- Apply appropriate CodeMirror theme
- Update visualization colors

## API Integration Points (Future)

### AI Code Generation

**Endpoint**: `/api/strudel/generate`

**Request**:
```json
{
  "prompt": "create a drum pattern with kick and snare",
  "context": "current code in editor",
  "style": "techno|ambient|jazz|etc"
}
```

**Response**:
```json
{
  "code": "generated Strudel code",
  "explanation": "what the code does"
}
```

### AI Code Editing

**Endpoint**: `/api/strudel/edit`

**Request**:
```json
{
  "code": "current code",
  "instruction": "add reverb to the melody",
  "selection": { "from": 10, "to": 50 }
}
```

**Response**:
```json
{
  "code": "modified code",
  "changes": [{ "from": 10, "to": 50, "insert": "new code" }]
}
```

### Integration in UI

1. **AI Button** in control panel
2. **Prompt Input** modal or sidebar
3. **Diff View** to show changes
4. **Accept/Reject** buttons for AI suggestions

## Testing Strategy

### Manual Testing

1. **Basic Functionality**
   - Load page successfully
   - Editor displays and is editable
   - Play button starts audio
   - Stop button stops audio
   - Reload resets to default

2. **Code Patterns**
   - Simple note patterns
   - Complex patterns with effects
   - Syntax errors
   - Runtime errors
   - Empty code

3. **UI Interactions**
   - Keyboard shortcuts work
   - Buttons enable/disable correctly
   - Theme toggle affects editor
   - Responsive layout works

4. **Error Handling**
   - Invalid code shows error
   - Audio context errors handled
   - Network failures handled
   - Recovery from errors works

### Browser Testing

- Chrome/Edge (Chromium)
- Firefox
- Safari (macOS/iOS)
- Mobile browsers

## Performance Considerations

1. **Audio Engine**
   - Strudel handles audio efficiently
   - Monitor CPU usage during playback
   - Limit concurrent patterns if needed

2. **Editor**
   - CodeMirror 6 is performant
   - Avoid unnecessary re-renders
   - Debounce auto-save if added

3. **Visualization**
   - Use requestAnimationFrame
   - Throttle updates if needed
   - Pause when not visible

## Security Considerations

1. **Code Evaluation**
   - Strudel uses safe evaluation context
   - No access to sensitive APIs
   - Sandboxed audio context

2. **Future AI Integration**
   - Validate API responses
   - Sanitize generated code
   - Rate limit API calls
   - Handle API errors gracefully

## Accessibility

1. **Keyboard Navigation**
   - All controls accessible via keyboard
   - Tab order is logical
   - Shortcuts documented

2. **Screen Readers**
   - ARIA labels on buttons
   - Status announcements
   - Error messages readable

3. **Visual**
   - Sufficient color contrast
   - Focus indicators visible
   - Text scalable

## Documentation

### User Documentation

1. **Getting Started Guide**
   - How to write first pattern
   - Explanation of controls
   - Keyboard shortcuts
   - Example patterns

2. **Strudel Syntax Reference**
   - Link to official docs
   - Common patterns
   - Effect reference
   - Troubleshooting

### Developer Documentation

1. **Code Comments**
   - Explain complex logic
   - Document API usage
   - Note future enhancement points

2. **README Section**
   - Architecture overview
   - Setup instructions
   - Contributing guidelines

## Future Enhancements

### Phase 2 Features

1. **Code Persistence**
   - Save patterns to localStorage
   - Load saved patterns
   - Pattern library

2. **Sharing**
   - Generate shareable URLs
   - Export as audio file
   - Share to Nostr (using existing NDK)

3. **Advanced Editor**
   - Auto-completion for Strudel functions
   - Inline documentation
   - Code snippets

4. **Enhanced Visualization**
   - Multiple visualization modes
   - Customizable colors
   - Full-screen mode

### Phase 3 Features (AI Integration)

1. **AI Code Generation**
   - Natural language to Strudel code
   - Style-based generation
   - Pattern variations

2. **AI Code Editing**
   - Targeted modifications
   - Effect suggestions
   - Pattern optimization

3. **AI Assistant**
   - Chat interface
   - Code explanations
   - Learning suggestions

## Success Criteria

### Minimum Viable Product (MVP)

- ✅ Page loads without errors
- ✅ Editor displays with syntax highlighting
- ✅ Play button executes code and produces audio
- ✅ Stop button stops audio
- ✅ Reload button resets editor
- ✅ Basic error handling works
- ✅ Responsive layout functions

### Enhanced Version

- ✅ Visualization displays during playback
- ✅ Keyboard shortcuts work
- ✅ Theme matches template
- ✅ Error messages are clear
- ✅ Performance is smooth

### Future Complete Version

- ✅ AI code generation works
- ✅ AI code editing works
- ✅ Pattern persistence works
- ✅ Sharing functionality works
- ✅ Advanced visualizations available

## Timeline Estimate

**Note**: Time estimates are not provided per project guidelines. Tasks are ordered by priority and dependency.

### Priority 1 (Core Functionality)
1. Add dependencies and HTML structure
2. Initialize Strudel engine
3. Setup CodeMirror editor
4. Implement Play/Stop/Reload buttons
5. Basic error handling

### Priority 2 (Enhanced UX)
6. Add visualization
7. Implement keyboard shortcuts
8. Style to match template
9. Add responsive design
10. Comprehensive error handling

### Priority 3 (Future Features)
11. Code persistence
12. AI integration preparation
13. Advanced visualizations
14. Sharing functionality

## References

- [Strudel Documentation](https://strudel.cc/)
- [@strudel/web README](https://github.com/tidalcycles/strudel/tree/main/packages/web)
- [CodeMirror 6 Documentation](https://codemirror.net/docs/)
- [Web Audio API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API)
- [TidalCycles](https://tidalcycles.org/)

## Notes

- Keep the implementation simple and focused initially
- Ensure compatibility with existing template infrastructure
- Design with AI integration in mind but don't implement yet
- Prioritize user experience and error handling
- Test thoroughly across browsers and devices
