client/plans/strudel-page-architecture.md

Strudel Music Coding Page - Architecture Plan

Project Overview

Create a live music coding interface in 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

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:

{
  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:

// 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

   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

   function handleStop() {
     hush();
     updateButtonStates('stopped');
   }
   

3. Reload Button

   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:

export function createEditor(container, defaultCode);
export function getEditorContent();
export function setEditorContent(code);
export function addKeyboardShortcuts(handlers);

strudel-controls.mjs:

export function initControls(editor);
export async function play(code);
export function stop();
export function reload();
export function updateButtonStates(state);

strudel-viz.mjs:

export function initVisualization(container);
export function connectAudio(audioContext);
export function startAnimation();
export function stopAnimation();

Styling Guidelines

CSS Variables to Use

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

New CSS Classes

.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:

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

Response:

{
  "code": "generated Strudel code",
  "explanation": "what the code does"
}

AI Code Editing

Endpoint: /api/strudel/edit

Request:

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

Response:

{
  "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
• @strudel/web README
• CodeMirror 6 Documentation
• Web Audio API
• TidalCycles

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