1 files changed, 119 insertions, 0 deletions
diff --git a/tools/timeline_editor/README.md b/tools/timeline_editor/README.md
new file mode 100644
index 0000000..aed140e
--- /dev/null
+++ b/tools/timeline_editor/README.md
@@ -0,0 +1,119 @@
+# Timeline Editor
+
+Interactive web-based editor for `demo.seq` timeline files.
+
+## Features
+
+✅ **Implemented:**
+- 📂 Load/save `demo.seq` files
+- 📊 Visual Gantt-style timeline
+- 🎯 Drag & drop sequences along timeline
+- 🎯 Drag & drop effects along timeline
+- ⏱️ Edit timing (start/end times)
+- ⚙️ Edit priorities
+- ⚙️ Edit effect class names and constructor arguments
+- 🔍 Zoom in/out (10% - 200%)
+- 📋 Real-time statistics
+- 🗑️ Delete sequences/effects
+- ➕ Add new sequences
+
+## Usage
+
+1. **Open the editor:**
+   ```bash
+   open tools/timeline_editor/index.html
+   ```
+   Or double-click `index.html` in Finder.
+
+2. **Load a timeline:**
+   - Click "📂 Load demo.seq"
+   - Select your `assets/demo.seq` file
+
+3. **Edit the timeline:**
+   - **Drag sequences/effects** to move them along the timeline
+   - **Click an item** to select it and view properties
+   - **Edit properties** in the panel below
+   - **Click "Apply"** to save property changes
+
+4. **Save your changes:**
+   - Click "💾 Save demo.seq"
+   - Choose where to save the modified file
+
+5. **Zoom controls:**
+   - Use the zoom slider to adjust timeline scale
+   - Higher zoom = more pixels per second
+
+## Keyboard Shortcuts
+
+- **Delete key**: Delete selected item (when implemented)
+- **Escape**: Deselect current item
+
+## File Format
+
+The editor parses and generates `.seq` files with this format:
+
+```
+SEQUENCE <start_time> <priority>
+  EFFECT <ClassName> <start_time> <end_time> <priority> [args...]
+  EFFECT <ClassName> <start_time> <end_time> <priority> [args...]
+```
+
+Example:
+```
+SEQUENCE 0.0 0
+  EFFECT FlashEffect 0.0 1.0 0
+  EFFECT FadeEffect 0.5 2.0 1
+
+SEQUENCE 3.0 1
+  EFFECT HeptagonEffect 0.0 0.5 0
+```
+
+## Color Coding
+
+- **Blue boxes**: Sequences (container for effects)
+- **Gray boxes**: Effects (visual elements)
+- **Green highlight**: Selected sequence
+- **Orange highlight**: Selected effect
+
+## Tips
+
+- **Sequences** have absolute start times
+- **Effects** have start/end times **relative to their sequence**
+- Priority determines rendering order (higher = rendered later = on top)
+- Effect constructor arguments are passed as-is to the C++ code
+
+## Limitations
+
+- No preview rendering (this is intentional - it's just a timeline editor)
+- No automatic overlap detection yet
+- No undo/redo (coming soon)
+- Cannot add effects to sequences (manually edit properties for now)
+
+## Future Enhancements
+
+- [ ] Undo/redo functionality
+- [ ] Add effect button
+- [ ] Overlap detection warnings
+- [ ] Snap-to-grid
+- [ ] Timeline playback indicator
+- [ ] Multiple file comparison
+- [ ] Export to different formats
+
+## Technical Details
+
+- Pure HTML/CSS/JavaScript (no dependencies)
+- No backend required
+- Works offline
+- All processing happens in the browser
+- Files are saved via browser download API
+
+## Integration
+
+After editing in the timeline editor:
+
+1. Save the modified `demo.seq`
+2. Copy it to `assets/demo.seq`
+3. Rebuild the project: `cmake --build build`
+4. The new timeline will be compiled into the demo
+
+No code changes needed - the `seq_compiler` automatically processes the updated file.