# Timeline Editor - Feature Roadmap

This document outlines planned enhancements for the interactive timeline editor.

---

## Phase 1: Core Editing Features (High Priority)

### 1.1 Snap-to-Beat ⭐ Priority: HIGH
**Goal:** Enable precise musical timing by snapping items to beat boundaries.

**Features:**
- Parse BPM from demo.seq file (`# BPM 120`)
- Calculate beat grid based on BPM (e.g., 120 BPM = 0.5s per beat)
- Visual beat markers on timeline (lighter gray lines between second markers)
- Toggle snap mode (keyboard shortcut: `S` key)
- When dragging, snap position to nearest beat
- Status indicator showing current snap mode and BPM

**Implementation Details:**
```javascript
// Calculate beat positions
const beatsPerSecond = bpm / 60.0;
const secondsPerBeat = 60.0 / bpm;

// Snap function
function snapToBeat(timeInSeconds) {
    if (!snapEnabled) return timeInSeconds;
    const beatIndex = Math.round(timeInSeconds * beatsPerSecond);
    return beatIndex * secondsPerBeat;
}

// Visual beat markers
for (let beat = 0; beat < maxBeats; beat++) {
    const beatTime = beat * secondsPerBeat;
    // Render subtle vertical line at beatTime
}
```

**UI Additions:**
- Checkbox: "☑️ Snap to Beat (S)" in zoom controls
- Display: "BPM: 120 | Beat: 0.5s" in status bar
- Visual: Dashed vertical lines at beat boundaries

**Effort:** 4-6 hours
**Dependencies:** None
**Impact:** Makes musical timing much easier

---

### 1.2 Create New Effects ⭐ Priority: HIGH
**Goal:** Add effects to sequences without manual property editing.

**Features:**
- "➕ Add Effect" button (enabled when sequence is selected)
- Modal dialog or inline form for effect creation:
  - Effect class name (dropdown or autocomplete)
  - Start time (relative to sequence)
  - Duration
  - Priority (default: 0)
  - Constructor arguments (optional text field)
- Double-click on sequence to add effect at that position
- Right-click context menu option

**Implementation Details:**
```javascript
function showEffectCreationDialog(sequenceIndex, timeHint = 0) {
    const dialog = document.createElement('div');
    dialog.className = 'modal-dialog';
    dialog.innerHTML = `
        <h3>New Effect</h3>
        <label>Class Name: <input id="newEffectClass" list="effectClasses"></label>
        <datalist id="effectClasses">
            <option>FlashEffect</option>
            <option>FadeEffect</option>
            <option>HeptagonEffect</option>
            <!-- Add more from known effects -->
        </datalist>
        <label>Start Time: <input type="number" id="newEffectStart" value="${timeHint}"></label>
        <label>Duration: <input type="number" id="newEffectDuration" value="1.0"></label>
        <label>Priority: <input type="number" id="newEffectPriority" value="0"></label>
        <label>Arguments: <input type="text" id="newEffectArgs"></label>
        <button onclick="createEffect()">Create</button>
        <button onclick="closeDialog()">Cancel</button>
    `;
    document.body.appendChild(dialog);
}

function createEffect() {
    const effect = {
        type: 'effect',
        className: document.getElementById('newEffectClass').value,
        startTime: parseFloat(document.getElementById('newEffectStart').value),
        endTime: parseFloat(document.getElementById('newEffectStart').value) +
                 parseFloat(document.getElementById('newEffectDuration').value),
        priority: parseInt(document.getElementById('newEffectPriority').value),
        args: document.getElementById('newEffectArgs').value
    };

    sequences[selectedSequenceIndex].effects.push(effect);
    closeDialog();
    renderTimeline();
}
```

**UI Additions:**
- Button: "➕ Add Effect to Sequence" (appears when sequence selected)
- Modal dialog with form
- Context menu on right-click
- Keyboard shortcut: `E` key when sequence selected

**Effort:** 6-8 hours
**Dependencies:** Need list of available effect classes
**Impact:** Essential for productive editing

---

### 1.3 Overlap Detection & Warnings ⭐ Priority: MEDIUM
**Goal:** Visualize and warn about timeline conflicts.

**Features:**
- Detect sequence overlaps (same priority, overlapping time ranges)
- Detect effect overlaps within same sequence
- Visual indicators:
  - Red border around overlapping items
  - Warning icon (⚠️) on overlapping items
  - Tooltip explaining conflict
- Warnings panel listing all conflicts
- Filter timeline to show only conflicts

**Detection Logic:**
```javascript
function detectOverlaps() {
    const conflicts = [];

    // Check sequence overlaps (same priority)
    for (let i = 0; i < sequences.length; i++) {
        for (let j = i + 1; j < sequences.length; j++) {
            const seq1 = sequences[i];
            const seq2 = sequences[j];

            if (seq1.priority !== seq2.priority) continue;

            const seq1End = seq1.startTime + getSequenceDuration(seq1);
            const seq2End = seq2.startTime + getSequenceDuration(seq2);

            if (seq1.startTime < seq2End && seq2.startTime < seq1End) {
                conflicts.push({
                    type: 'sequence',
                    items: [i, j],
                    severity: 'warning',
                    message: `Sequences ${i+1} and ${j+1} overlap with same priority ${seq1.priority}`
                });
            }
        }
    }

    // Check effect overlaps within sequences
    sequences.forEach((seq, seqIdx) => {
        for (let i = 0; i < seq.effects.length; i++) {
            for (let j = i + 1; j < seq.effects.length; j++) {
                const eff1 = seq.effects[i];
                const eff2 = seq.effects[j];

                if (eff1.priority !== eff2.priority) continue;

                if (eff1.startTime < eff2.endTime && eff2.startTime < eff1.endTime) {
                    conflicts.push({
                        type: 'effect',
                        sequenceIndex: seqIdx,
                        items: [i, j],
                        severity: 'info',
                        message: `Effects overlap in sequence ${seqIdx+1}`
                    });
                }
            }
        }
    });

    return conflicts;
}
```

**Visual Indicators:**
```css
.sequence.conflict {
    border-color: #f48771;
    box-shadow: 0 0 10px rgba(244, 135, 113, 0.5);
}

.effect.conflict {
    border-color: #f48771;
}

.conflict-warning {
    position: absolute;
    top: 2px;
    right: 2px;
    font-size: 14px;
}
```

**UI Additions:**
- Panel: "⚠️ Conflicts" (collapsible, shows list of warnings)
- Button: "🔍 Show Only Conflicts" (filters view)
- Visual: Red borders and warning icons on conflicting items
- Tooltip: Hover over warning icon for details

**Effort:** 8-10 hours
**Dependencies:** None
**Impact:** Prevents rendering issues and z-order bugs

---

## Phase 2: Productivity Enhancements (Medium Priority)

### 2.1 Undo/Redo System
**Goal:** Allow users to experiment without fear of breaking things.

**Implementation:**
- Command pattern for all mutations
- History stack (max 50 commands)
- Keyboard shortcuts: `Ctrl+Z` (undo), `Ctrl+Shift+Z` (redo)
- Buttons in toolbar

**Effort:** 10-12 hours
**Priority:** MEDIUM

---

### 2.2 Multi-Select & Batch Operations
**Goal:** Edit multiple items at once.

**Features:**
- Click + Ctrl/Cmd to add to selection
- Click + Shift for range selection
- Drag box to select multiple
- Batch operations:
  - Move all selected items together
  - Delete all selected
  - Adjust priority of all selected
  - Duplicate selection

**Effort:** 12-15 hours
**Priority:** MEDIUM

---

### 2.3 Copy/Paste & Duplication
**Goal:** Reuse sequences and effects quickly.

**Features:**
- `Ctrl+C` to copy selected item(s)
- `Ctrl+V` to paste at current time
- `Ctrl+D` to duplicate in place
- Paste adjusts timing to avoid overlaps (optional)

**Effort:** 6-8 hours
**Priority:** MEDIUM

---

### 2.4 Keyboard Shortcuts & Navigation
**Goal:** Power users can work without mouse.

**Shortcuts:**
- `Space`: Play/pause preview indicator (if implemented)
- `Arrow Keys`: Move selected item (fine adjustment)
- `Shift+Arrow`: Resize selected effect duration
- `Delete` / `Backspace`: Delete selected
- `S`: Toggle snap-to-beat
- `E`: Create effect in selected sequence
- `N`: New sequence
- `1-9`: Jump to sequence 1-9
- `/`: Focus search/filter box

**Effort:** 4-6 hours
**Priority:** MEDIUM

---

## Phase 3: Advanced Features (Low Priority)

### 3.1 Timeline Playback Indicator
**Goal:** Visualize current playback position.

**Features:**
- Vertical red line showing current time
- Play/pause button
- Time advances at real-time speed (or adjustable)
- Click timeline to seek
- Does NOT render effects (just shows position)

**Effort:** 4-6 hours
**Priority:** LOW
**Note:** This is ONLY a position indicator, not a preview renderer

---

### 3.2 Templates & Presets
**Goal:** Quick-start with common patterns.

**Features:**
- Template library (e.g., "Intro Sequence", "Beat Drop", "Outro")
- Save custom templates
- Drag template onto timeline to instantiate
- Templates include sequences + effects with relative timing

**Effort:** 8-10 hours
**Priority:** LOW

---

### 3.3 Search & Filter
**Goal:** Navigate large timelines quickly.

**Features:**
- Search bar: Filter by effect class name
- Filter by priority
- Filter by time range
- Highlight matching items
- "Go to" dialog (jump to specific time)

**Effort:** 6-8 hours
**Priority:** LOW

---

### 3.4 Timeline Comparison View
**Goal:** Compare two versions of the timeline.

**Features:**
- Load two .seq files side by side
- Diff view showing additions/deletions/changes
- Color-coded: green = added, red = removed, yellow = modified
- Merge changes from one timeline to another

**Effort:** 15-20 hours
**Priority:** LOW

---

### 3.5 Export Formats
**Goal:** Support alternative output formats.

**Features:**
- Export to JSON (for programmatic processing)
- Export to CSV (for spreadsheet analysis)
- Export to Markdown table (for documentation)
- Import from JSON/CSV

**Effort:** 6-8 hours
**Priority:** LOW

---

### 3.6 Auto-Save & Local Storage
**Goal:** Never lose work.

**Features:**
- Auto-save to browser localStorage every 30 seconds
- Restore last session on load
- Warning if leaving page with unsaved changes
- Session history (last 5 sessions)

**Effort:** 4-6 hours
**Priority:** LOW

---

## Implementation Priority

**Immediate (Next 1-2 weeks):**
1. ✅ Snap-to-Beat (4-6h) - Makes editing much easier
2. ✅ Create New Effects (6-8h) - Essential for productivity

**Short-term (Next 1-2 months):**
3. ✅ Overlap Detection (8-10h) - Prevents bugs
4. ✅ Undo/Redo (10-12h) - Safety net for experimentation
5. ✅ Copy/Paste (6-8h) - Common workflow

**Medium-term (Next 3-6 months):**
6. Multi-Select (12-15h)
7. Keyboard Shortcuts (4-6h)
8. Timeline Playback Indicator (4-6h)

**Long-term (Nice to have):**
9. Templates (8-10h)
10. Search/Filter (6-8h)
11. Timeline Comparison (15-20h)
12. Export Formats (6-8h)
13. Auto-Save (4-6h)

---

## Total Effort Estimates

**Phase 1 (Core):** 22-28 hours
**Phase 2 (Productivity):** 38-51 hours
**Phase 3 (Advanced):** 51-74 hours

**Total:** ~110-150 hours for full feature set

---

## Development Approach

**Incremental Rollout:**
- Each feature should be a separate commit
- Keep the single-file HTML structure for simplicity
- Add features in priority order
- Test with real demo.seq files after each feature

**Code Organization (when file gets too large):**
- Consider splitting into:
  - `index.html` (UI structure + styles)
  - `editor.js` (main logic)
  - `parser.js` (seq file parsing)
  - `timeline.js` (rendering)
  - `commands.js` (undo/redo system)

**Testing Strategy:**
- Manual testing with assets/demo.seq
- Test edge cases: empty files, single sequence, many overlaps
- Browser compatibility: Chrome, Firefox, Safari
- No automated tests (keep it simple for now)

---

## Design Principles

1. **Keep it simple:** Avoid over-engineering
2. **No dependencies:** Stay pure HTML/JS/CSS
3. **Instant feedback:** All operations should feel immediate
4. **Visual clarity:** Color-coding, icons, clear labels
5. **Forgiving UX:** Undo/redo, non-destructive operations
6. **Offline-first:** No network required

---

## Questions for Future Consideration

1. **Effect Class Validation:**
   - Should we validate effect class names against known effects?
   - Source of truth: Parse C++ code? Hardcoded list? User-maintained?

2. **Priority System:**
   - Current system uses integers (-1, 0, 1, 2...)
   - Should we add named priority levels? (Background, Normal, Foreground, Top)

3. **BPM Changes:**
   - What if BPM changes mid-timeline?
   - Support for tempo changes?

4. **Collaboration:**
   - Should multiple people be able to edit the same timeline?
   - Real-time collaboration? (probably overkill)

5. **Preview Integration:**
   - Should we ever integrate visual preview?
   - Current answer: NO (out of scope, would require WebAssembly + full engine)

---

## Success Metrics

**v1.0 (Current):** ✅ Basic editing works
**v1.1 (Phase 1):** Snap-to-beat + effect creation = productive editing
**v2.0 (Phase 2):** Undo/redo + multi-select = professional tool
**v3.0 (Phase 3):** Advanced features = power user delight

**Goal:** Make timeline editing 10x faster than manual text editing.