From 6bd01cd5d4c731871b433dc209147817f7e71be6 Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Thu, 5 Feb 2026 21:15:51 +0100
Subject: docs(timeline-editor): Reference SEQUENCE.md and add priority editing
 task

Documentation improvements:
1. Added reference to doc/SEQUENCE.md in README
2. Added comment in parser pointing to format spec
3. Updated README with complete format examples including:
   - Priority modifiers (+, =, -)
   - Time notation (beats vs seconds)
   - Optional sequence names
   - BPM declaration

New feature task (Phase 1):
Task 1.2b: Priority Editing UI (HIGH PRIORITY, 6-8h)
- Edit sequence priority (0-9 for scene, 10+ for post-processing)
- Toggle effect priority modifiers (+/=/-)
- Visual priority indicators and z-order visualization
- Computed priority display
- Priority conflict warnings

Implementation details:
- Radio buttons for priority modifiers
- Up/down buttons for sequence priority
- Color-coded priority levels
- Priority badges on timeline items
- Automatic priority recalculation

Rationale:
Priority control is essential for proper render order and z-stacking.
Currently, priorities are shown but not easily editable. This task
makes priority a first-class editable property.

Updated effort estimates:
- Phase 1: 28-36 hours (was 22-28)
- Total: ~117-161 hours for full feature set
---
 tools/timeline_editor/README.md | 35 ++++++++++++++++++++++++++---------
 1 file changed, 26 insertions(+), 9 deletions(-)

(limited to 'tools/timeline_editor/README.md')

diff --git a/tools/timeline_editor/README.md b/tools/timeline_editor/README.md
index aed140e..1c73c53 100644
--- a/tools/timeline_editor/README.md
+++ b/tools/timeline_editor/README.md
@@ -50,22 +50,39 @@ Interactive web-based editor for `demo.seq` timeline files.
 
 ## File Format
 
+⚠️ **For complete format specification, see:** `doc/SEQUENCE.md`
+
 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...]
+# BPM 120
+SEQUENCE <start_time> <priority> ["optional_name"] [optional_end]
+  EFFECT <+|=|-> <ClassName> <start_time> <end_time> [args...]
+  EFFECT <+|=|-> <ClassName> <start_time> <end_time> [args...]
 ```
 
+**Priority Modifiers:**
+- `+` = Increment priority (normal effects)
+- `=` = Keep same priority as previous
+- `-` = Decrement priority (background layers)
+
+**Time Notation:**
+- `0b`, `4b`, `64b` = Beats (converted using BPM)
+- `0.0`, `2.0`, `32.0` = Seconds
+- Integer without 'b': treated as beats
+- Decimal point: treated as seconds
+
 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
+# BPM 120
+SEQUENCE 0b 0 "Opening Scene"
+  EFFECT - FlashCubeEffect .2 3      # Background (priority -1)
+  EFFECT + FlashEffect 0.0 1.0       # Foreground (priority 0)
+  EFFECT + FadeEffect 0.5 2.0        # Overlay (priority 1)
+
+SEQUENCE 4b 1 "Beat Drop"
+  EFFECT + HeptagonEffect 0.0 0.5    # Priority 0
+  EFFECT = ParticlesEffect 0.0 2.0   # Priority 0 (same layer)
 ```
 
 ## Color Coding
-- 
cgit v1.2.3