From 7a383635525c9f9617965f3c79a9f2d6c86550cd Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Mon, 16 Feb 2026 11:58:34 +0100
Subject: docs(sequence): update and compact v2 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Documentation Changes:
- Rewrote SEQUENCE_v2.md: practical guide focused on actual implementation
  - Removed design philosophy, added concrete examples
  - Documented all implemented features and current limitations
  - Added effect creation templates (standard post-process, 3D with depth)
  - 130 lines → 222 lines (expanded with examples)

- Updated EFFECT_WORKFLOW.md for v2
  - Changed from v1 Effect/PostProcessEffect to EffectV2
  - Updated all steps for v2 workflow (6 steps instead of 8)
  - Added complete templates with proper v2 signatures
  - Documented common issues and solutions
  - Removed v1-specific content

- Archived v1 documentation
  - Moved doc/SEQUENCE.md → doc/archive/SEQUENCE_V1.md
  - V1 system removed, documentation preserved for reference

Content Focus:
- Quick start examples (simple chain, multi-output, ping-pong)
- Timeline syntax reference with REQUIRED priority modifiers
- Architecture overview (SequenceV2, EffectV2, Node system)
- Compiler features (DAG validation, topological sort, ping-pong detection)
- Practical templates (copy-paste ready)
- Common issues section (build errors, runtime errors)

Status Documentation:
- ✅ Implemented: DAG validation, node aliasing, 7 effects ported
- ❌ Missing: Flatten mode, BPM handling, GetDemoDuration calculation
- TODO: Port remaining effects, implement flatten, update HTML editor

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 doc/EFFECT_WORKFLOW.md     | 356 +++++++++++++++++++++++----------------------
 doc/SEQUENCE.md            | 220 ----------------------------
 doc/SEQUENCE_v2.md         | 315 +++++++++++++++++++++++++--------------
 doc/archive/SEQUENCE_V1.md | 220 ++++++++++++++++++++++++++++
 4 files changed, 605 insertions(+), 506 deletions(-)
 delete mode 100644 doc/SEQUENCE.md
 create mode 100644 doc/archive/SEQUENCE_V1.md

diff --git a/doc/EFFECT_WORKFLOW.md b/doc/EFFECT_WORKFLOW.md
index 57cf904..bdec2b6 100644
--- a/doc/EFFECT_WORKFLOW.md
+++ b/doc/EFFECT_WORKFLOW.md
@@ -1,248 +1,256 @@
-# Effect Creation Workflow
+# Effect Creation Workflow (v2)
 
 **Target Audience:** AI coding agents and developers
 
-Automated checklist for adding new visual effects to the demo.
+Checklist for adding visual effects using Sequence v2 system.
 
 ---
 
 ## Quick Reference
 
-**For ShaderToy conversions:** Use `tools/shadertoy/convert_shadertoy.py` then follow steps 3-8 below.
-
-**For SDF/raymarching effects:** See `doc/SDF_EFFECT_GUIDE.md` for streamlined workflow using SDFEffect base class.
-
-**For custom effects:** Follow all steps 1-8.
+**ShaderToy:** `tools/shadertoy/convert_shadertoy.py` then follow steps below
+**SDF/Raymarching:** See `doc/SDF_EFFECT_GUIDE.md`
+**Custom v2 effects:** Follow all steps 1-6
 
 ---
 
-## Step-by-Step Workflow
+## Workflow
 
 ### 1. Create Effect Files
 
-**Description:** Each visual effect must have its own dedicated header (`.h`) and implementation (`.cc`) file pair.
+**Files** (v2 naming):
+- Header: `src/effects/<name>_effect_v2.h`
+- Implementation: `src/effects/<name>_effect_v2.cc`
+- Shader: `workspaces/main/shaders/<name>_v2.wgsl`
 
-**Location:**
-- Header: `src/effects/<effect_name>_effect.h`
-- Implementation: `src/effects/<effect_name>_effect.cc`
-- Shader: `workspaces/main/shaders/<effect_name>.wgsl`
+**Class name**: `<Name>EffectV2` (e.g., `TunnelEffectV2`)
 
-**Naming Convention:**
-- Class name: `<EffectName>Effect` (e.g., `TunnelEffect`, `PlasmaEffect`)
-- Files: `<effect_name>_effect.*` (snake_case)
+**Base class**: `EffectV2` (all effects)
 
-**Base Class:**
-- Post-process effects: inherit from `PostProcessEffect`
-- Scene effects: inherit from `Effect`
-
-**Render Signature:**
+**Constructor**:
 ```cpp
-void render(WGPURenderPassEncoder pass,
-            const CommonPostProcessUniforms& uniforms) override;
+MyEffectV2(const GpuContext& ctx,
+           const std::vector<std::string>& inputs,
+           const std::vector<std::string>& outputs);
 ```
 
-**Uniforms Available:**
+**Required methods**:
 ```cpp
-uniforms.time;             // Physical seconds (constant speed)
-uniforms.beat_time;        // Musical beats (bar synchronization)
-uniforms.beat_phase;       // Fractional beat 0.0-1.0 (smooth oscillation)
-uniforms.audio_intensity;  // Audio peak for beat sync
-uniforms.resolution;       // Screen dimensions
-uniforms.aspect_ratio;     // Width/height ratio
+void render(WGPUCommandEncoder encoder,
+            const UniformsSequenceParams& params,
+            NodeRegistry& nodes) override;
+
+// Optional: for effects needing temp nodes (depth buffers, intermediate textures)
+void declare_nodes(NodeRegistry& registry) override;
 ```
 
-**Template:** See `tools/shadertoy/template.*` or use `convert_shadertoy.py`
+**Uniforms**:
+```cpp
+params.time;            // Physical seconds
+params.beat_time;       // Musical beats
+params.beat_phase;      // Fractional beat 0.0-1.0
+params.audio_intensity; // Audio peak
+params.resolution;      // vec2(width, height)
+params.aspect_ratio;    // width/height
+```
 
 ### 2. Add Shader to Assets
 
-**File:** `workspaces/main/assets.txt`
-
-**Format:**
-```
-SHADER_<UPPER_SNAKE_NAME>, NONE, shaders/<effect_name>.wgsl, "Effect description"
-```
+**File**: `workspaces/main/assets.txt`
 
-**Example:**
 ```
-SHADER_TUNNEL, NONE, shaders/tunnel.wgsl, "Tunnel effect shader"
+SHADER_<UPPER_NAME>, NONE, shaders/<name>_v2.wgsl, "Description"
 ```
 
-**Asset ID:** Will be `AssetId::ASSET_SHADER_<UPPER_SNAKE_NAME>` in C++
+Asset ID: `AssetId::ASSET_SHADER_<UPPER_NAME>`
 
 ### 3. Add to CMakeLists.txt
 
-**File:** `CMakeLists.txt`
-
-**Action:** Add `src/effects/<effect_name>_effect.cc` to **BOTH** GPU_SOURCES sections:
-- Headless mode section (around line 141-167)
-- Normal mode section (around line 171-197)
-
-**Location:** After similar effects (post-process with post-process, scene with scene)
+**File**: `CMakeLists.txt`
 
-**Example:**
-```cmake
-# In headless section (line ~152):
-        src/effects/solarize_effect.cc
-        src/effects/tunnel_effect.cc        # <-- Add here
-        src/effects/chroma_aberration_effect.cc
-
-# In normal section (line ~183):
-        src/effects/solarize_effect.cc
-        src/effects/tunnel.cc        # <-- Add here
-        src/effects/chroma_aberration_effect.cc
-```
+Add `src/effects/<name>_effect_v2.cc` to **BOTH** GPU_SOURCES sections:
+- Headless mode (around line 141-167)
+- Normal mode (around line 171-197)
 
 ### 4. Include in demo_effects.h
 
-**File:** `src/gpu/demo_effects.h`
+**File**: `src/gpu/demo_effects.h`
 
-**Action:** `src/gpu/demo_effects.h` now acts as a central include file. Add a single include directive for your new effect's header:
 ```cpp
-#include "effects/<effect_name>_effect.h"
+#include "effects/<name>_effect_v2.h"
 ```
 
-**Location:** Alphabetically with other effect includes
-
 ### 5. Add to Timeline
 
-**File:** `workspaces/main/timeline.seq`
+**File**: `workspaces/main/timeline_v2.seq`
 
-**Format:**
 ```
-SEQUENCE <start_time> <priority>
-  EFFECT <+|=|-> <EffectName>Effect <local_start> <local_end> [params...]
+SEQUENCE <start> <priority> "name"
+  EFFECT + MyEffectV2 source -> sink 0.0 4.0
 ```
 
-**Priority Modifiers (REQUIRED):**
-- `+` : Increment priority
-- `=` : Same priority as previous effect
-- `-` : Decrement priority (for backgrounds)
+**Priority modifiers** (REQUIRED): `+` (increment), `=` (same), `-` (decrement)
 
-**Example:**
-```
-SEQUENCE 0.0 0
-  EFFECT + TunnelEffect 0.0 10.0
-```
+### 6. Regenerate and Build
 
-**Common Mistake:** Missing priority modifier (`+`, `=`, `-`) after EFFECT keyword
+```bash
+# Regenerate timeline.cc
+python3 tools/seq_compiler_v2.py workspaces/main/timeline_v2.seq \
+  --output src/generated/timeline.cc
 
-### 6. Update Tests
+# Build
+cmake --build build -j4
 
-**File:** `src/tests/gpu/test_demo_effects.cc`
+# Test
+./build/demo64k
+```
+
+---
 
-**Action:** Add effect to appropriate list:
+## Templates
+
+### Standard Post-Process Effect
 
-**Post-Process Effects (lines 80-93):**
 ```cpp
-{"TunnelEffect", std::make_shared<TunnelEffect>(fixture.ctx())},
+// my_effect_v2.h
+#pragma once
+#include "gpu/effect_v2.h"
+#include "gpu/uniform_helper.h"
+
+class MyEffectV2 : public EffectV2 {
+ public:
+  MyEffectV2(const GpuContext& ctx,
+             const std::vector<std::string>& inputs,
+             const std::vector<std::string>& outputs);
+  ~MyEffectV2() override;
+
+  void render(WGPUCommandEncoder encoder,
+              const UniformsSequenceParams& params,
+              NodeRegistry& nodes) override;
+
+ private:
+  WGPURenderPipeline pipeline_;
+  WGPUBindGroup bind_group_;
+  UniformBuffer<UniformsSequenceParams> uniforms_buffer_;
+};
 ```
 
-**Scene Effects (lines 125-137):**
 ```cpp
-{"TunnelEffect", std::make_shared<TunnelEffect>(fixture.ctx())},
+// my_effect_v2.cc
+#include "effects/my_effect_v2.h"
+#include "gpu/post_process_helper.h"
+#include "gpu/shaders.h"
+
+MyEffectV2::MyEffectV2(const GpuContext& ctx,
+                       const std::vector<std::string>& inputs,
+                       const std::vector<std::string>& outputs)
+    : EffectV2(ctx, inputs, outputs), pipeline_(nullptr), bind_group_(nullptr) {
+  uniforms_buffer_.init(ctx_.device);
+  pipeline_ = create_post_process_pipeline(ctx_.device,
+                                           WGPUTextureFormat_RGBA8Unorm,
+                                           my_shader_v2_wgsl);
+}
+
+MyEffectV2::~MyEffectV2() {
+  if (bind_group_) wgpuBindGroupRelease(bind_group_);
+  if (pipeline_) wgpuRenderPipelineRelease(pipeline_);
+}
+
+void MyEffectV2::render(WGPUCommandEncoder encoder,
+                        const UniformsSequenceParams& params,
+                        NodeRegistry& nodes) {
+  WGPUTextureView input_view = nodes.get_view(input_nodes_[0]);
+  WGPUTextureView output_view = nodes.get_view(output_nodes_[0]);
+
+  uniforms_buffer_.update(ctx_.queue, params);
+  pp_update_bind_group(ctx_.device, pipeline_, &bind_group_, input_view,
+                       uniforms_buffer_.get(), {nullptr, 0});
+
+  WGPURenderPassColorAttachment color_attachment = {
+    .view = output_view,
+#if !defined(DEMO_CROSS_COMPILE_WIN32)
+    .depthSlice = WGPU_DEPTH_SLICE_UNDEFINED,
+#endif
+    .loadOp = WGPULoadOp_Clear,
+    .storeOp = WGPUStoreOp_Store,
+    .clearValue = {0.0, 0.0, 0.0, 1.0}
+  };
+
+  WGPURenderPassDescriptor pass_desc = {
+    .colorAttachmentCount = 1,
+    .colorAttachments = &color_attachment
+  };
+
+  WGPURenderPassEncoder pass = wgpuCommandEncoderBeginRenderPass(encoder, &pass_desc);
+  wgpuRenderPassEncoderSetPipeline(pass, pipeline_);
+  wgpuRenderPassEncoderSetBindGroup(pass, 0, bind_group_, 0, nullptr);
+  wgpuRenderPassEncoderDraw(pass, 3, 1, 0, 0);  // Fullscreen triangle
+  wgpuRenderPassEncoderEnd(pass);
+  wgpuRenderPassEncoderRelease(pass);
+}
 ```
 
-**3D Effects:** If requires Renderer3D, add to `requires_3d` check (line 148-151)
-
-### 7. Build and Test
-
-```bash
-# Full build
-cmake --build build -j4
-
-# Run effect tests
-cmake -S . -B build -DDEMO_BUILD_TESTS=ON
-cmake --build build -j4 --target test_demo_effects
-cd build && ./test_demo_effects
+### 3D Effect with Depth
 
-# Run all tests
-cd build && ctest
+```cpp
+class My3DEffectV2 : public EffectV2 {
+  std::string depth_node_;
+
+  My3DEffectV2(const GpuContext& ctx, ...)
+    : EffectV2(ctx, inputs, outputs),
+      depth_node_(outputs[0] + "_depth") {}
+
+  void declare_nodes(NodeRegistry& registry) override {
+    registry.declare_node(depth_node_, NodeType::DEPTH24, -1, -1);
+  }
+
+  void render(WGPUCommandEncoder encoder,
+              const UniformsSequenceParams& params,
+              NodeRegistry& nodes) override {
+    WGPUTextureView color_view = nodes.get_view(output_nodes_[0]);
+    WGPUTextureView depth_view = nodes.get_view(depth_node_);
+
+    WGPURenderPassDepthStencilAttachment depth_attachment = {
+      .view = depth_view,
+      .depthLoadOp = WGPULoadOp_Clear,
+      .depthStoreOp = WGPUStoreOp_Discard,
+      .depthClearValue = 1.0f
+    };
+
+    WGPURenderPassDescriptor pass_desc = {
+      .colorAttachmentCount = 1,
+      .colorAttachments = &color_attachment,
+      .depthStencilAttachment = &depth_attachment
+    };
+    // ... render 3D scene
+  }
+};
 ```
 
-### 8. Verify
-
-**Checklist:**
-- [ ] Effect compiles without errors
-- [ ] Effect appears in timeline
-- [ ] test_demo_effects passes
-- [ ] Effect renders correctly: `./build/demo64k`
-- [ ] No shader compilation errors
-- [ ] Follows naming conventions
-
 ---
 
 ## Common Issues
 
-### Build Error: "no member named 'ASSET_..._SHADER'"
-
-**Cause:** Shader not in assets.txt or wrong asset ID name
-
-**Fix:**
-1. Check `workspaces/main/assets.txt` has shader entry
-2. Asset ID is `ASSET_` + uppercase entry name (e.g., `SHADER_TUNNEL` → `ASSET_SHADER_TUNNEL`)
-
-### Build Error: "undefined symbol for architecture"
-
-**Cause:** Effect not in CMakeLists.txt GPU_SOURCES
+**Build Error: "no member named 'ASSET_..._SHADER'"**
+- Shader not in `assets.txt` or wrong name
+- Asset ID is `ASSET_` + uppercase entry name
 
-**Fix:** Add `.cc` file to BOTH sections (headless and normal mode)
+**Build Error: "undefined symbol"**
+- Effect not in CMakeLists.txt GPU_SOURCES
+- Must add to BOTH sections (headless + normal)
 
-### Timeline Parse Error: "Expected '+', '=', or '-'"
-
-**Cause:** Missing priority modifier after EFFECT keyword
-
-**Fix:** Use `EFFECT +`, `EFFECT =`, or `EFFECT -` (never just `EFFECT`)
-
-### Test Failure: Effect not in test list
-
-**Cause:** Effect not added to test_demo_effects.cc
-
-**Fix:** Add to `post_process_effects` or `scene_effects` list
-
----
+**Runtime Error: "Node not found"**
+- Forgot `declare_nodes()` for temp nodes
+- `init_effect_nodes()` not called (check generated timeline.cc)
 
-## Automation Script Example
-
-```bash
-#!/bin/bash
-# Example automation for AI agents
-
-EFFECT_NAME="$1"  # CamelCase (e.g., "Tunnel")
-SNAKE_NAME=$(echo "$EFFECT_NAME" | sed 's/\([A-Z]\)/_\L\1/g' | sed 's/^_//')
-UPPER_NAME=$(echo "$SNAKE_NAME" | tr '[:lower:]' '[:upper:]')
-
-echo "Creating effect: $EFFECT_NAME"
-echo "  Snake case: $SNAKE_NAME"
-echo "  Upper case: $UPPER_NAME"
-
-# 1. Generate files (if using ShaderToy)
-# ./tools/shadertoy/convert_shadertoy.py shader.txt "$EFFECT_NAME"
-
-# 2. Add to assets.txt
-echo "SHADER_${UPPER_NAME}, NONE, shaders/${SNAKE_NAME}.wgsl, \"${EFFECT_NAME} effect\"" \
-    >> workspaces/main/assets.txt
-
-# 3. Add to CMakeLists.txt (both sections)
-# Use Edit tool to add to both GPU_SOURCES sections
-
-# 4. Add include to demo_effects.h
-# Use Edit tool to add #include line
-
-# 5. Add to timeline.seq
-# Use Edit tool to add EFFECT line with priority modifier
-
-# 6. Add to test file
-# Use Edit tool to add to appropriate test list
-
-# 7. Build
-cmake --build build -j4
-```
+**Runtime Error: "invalid bind group"**
+- Pipeline format doesn't match framebuffer (use RGBA8Unorm)
+- Missing texture view or null resource
 
 ---
 
 ## See Also
 
-- `tools/shadertoy/README.md` - ShaderToy conversion guide
-- `doc/SEQUENCE.md` - Timeline format documentation
-- `doc/CONTRIBUTING.md` - General contribution guidelines
-- `src/effects/` - Existing effect examples
+- `doc/SEQUENCE_v2.md` - Timeline syntax and architecture
+- `tools/seq_compiler_v2.py` - Compiler implementation
+- `src/effects/*_v2.{h,cc}` - Example effects
diff --git a/doc/SEQUENCE.md b/doc/SEQUENCE.md
deleted file mode 100644
index 03d0c45..0000000
--- a/doc/SEQUENCE.md
+++ /dev/null
@@ -1,220 +0,0 @@
-# Sequence System Documentation
-
-This document describes the `.seq` file format used to define demo timelines.
-
-## Overview
-
-Sequence files (`.seq`) define the timeline and layering of visual effects. They are compiled by `seq_compiler` into C++ code at build time.
-
-**Locations:**
-- Main demo: `workspaces/main/timeline.seq`
-- Test demo: `workspaces/test/timeline.seq`
-- Compiler: `tools/seq_compiler.cc`
-- Generated output: `src/generated/timeline.cc`
-
----
-
-## Syntax Reference
-
-### BPM Declaration
-```
-# BPM 120
-```
-Specifies beats per minute. Required. Used to convert beats to physical seconds at runtime.
-
-### END_DEMO Directive
-```
-END_DEMO <time>
-```
-Optional auto-exit time in beats (e.g., `64` or `64b`) or explicit seconds (`32.0s`).
-
-### SEQUENCE Declaration
-```
-SEQUENCE <global_start> <priority> ["optional_name"] [optional_end]
-  EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...]
-```
-
-**Parameters:**
-- `global_start`: Sequence start time in beats (default) or explicit seconds (`2.5s`)
-- `priority`: Render order (0-9 for scenes, 10+ for post-processing)
-- `"optional_name"`: Optional display name for Gantt charts
-- `[optional_end]`: Optional sequence end time in beats (forces effect termination)
-
-**Examples:**
-```
-SEQUENCE 0 0                        # Basic sequence
-SEQUENCE 0 0 "Intro"                # Named sequence
-SEQUENCE 0 0 [5.0]                  # Explicit end time
-SEQUENCE 0 0 "Action Scene" [10.0]  # Both name and end time
-```
-
-### EFFECT Declaration
-```
-EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...]
-```
-
-**Priority Modifiers:**
-- `+`: Increment priority (or start at 0 if first)
-- `=`: Keep same priority as previous
-- `-`: Decrement priority (or start at -1 if first, for backgrounds)
-
-**Parameters:**
-- `EffectClassName`: C++ class from `demo_effects.h`
-- `local_start`, `local_end`: Time in beats relative to sequence start
-- `constructor_args`: Optional (rarely used, most effects use standard params only)
-
----
-
-## Time Notation
-
-**Beat-based timing (default):** All times are in musical beats, ensuring alignment regardless of BPM changes.
-
-| Notation | Example | Description |
-|----------|---------|-------------|
-| **Beats (default)** | `0`, `4`, `16` | Integer or decimal, no suffix |
-| Explicit beats | `4b`, `16.5b` | Optional 'b' suffix for clarity |
-| Explicit seconds | `2.0s`, `8.25s` | Suffix 's' for physical time (rare) |
-
-**Conversion:** At 120 BPM, 1 beat = 0.5 seconds, 4 beats = 2 seconds
-
-**Why beats?**
-- Musical alignment: Sequences stay synchronized to music structure
-- BPM independence: Changing BPM preserves musical timing
-- Intuitive authoring: Timeline matches bars/beats
-
----
-
-## Runtime Parameters
-
-All effects receive these parameters every frame in `render()` via `CommonPostProcessUniforms`:
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `resolution` | vec2 | Screen dimensions in pixels |
-| `aspect_ratio` | float | Screen width/height ratio |
-| `time` | float | Physical time in seconds (unaffected by tempo) |
-| `beat_time` | float | Musical time in beats (absolute) |
-| `beat_phase` | float | Fractional beat (0.0-1.0 within current beat) |
-| `audio_intensity` | float | Audio peak (0.0-1.0, for beat sync) |
-
-**Use cases:**
-- `time`: Physics-based animation (constant speed)
-- `beat_time`: Musical animation (sync to bars/beats)
-- `beat_phase`: Smooth oscillation per beat
-
----
-
-## Priority System
-
-**Scene Effects (0-9):**
-- `-1`: Background (skybox, far objects)
-- `0-5`: Midground (main geometry)
-- `6-9`: Foreground (overlays, particles)
-
-**Post-Process (10+):**
-- Applied in order: blur → distortion → color grading
-- Higher priority = rendered later (on top)
-
----
-
-## Examples
-
-### Basic Sequence
-```
-# BPM 120
-SEQUENCE 0 0
-  EFFECT + FlashEffect 0 1         # Priority 0, beats 0-1 (0-0.5s @ 120 BPM)
-  EFFECT + HeptagonEffect 0.4 20   # Priority 1, beats 0.4-20
-```
-
-### Same Priority Layering
-```
-SEQUENCE 0 0
-  EFFECT + Flash 0 1               # Priority 0
-  EFFECT = Fade 0.2 0.6            # Priority 0 (same layer)
-  EFFECT + Other 0.4 6             # Priority 1
-```
-
-### Background Elements
-```
-SEQUENCE 0 0
-  EFFECT - FlashCube 0 20          # Priority -1 (background)
-  EFFECT = BgEffect 0 10           # Priority -1 (same layer)
-  EFFECT + MainEffect 0 20         # Priority 0 (foreground)
-```
-
-### Sequence with Explicit End
-```
-SEQUENCE 16 0 [10]
-  EFFECT + Particles 0 240         # Runs until beat 26 (sequence end at 16+10)
-```
-
-### Post-Processing Chain
-```
-SEQUENCE 0 10
-  EFFECT + GaussianBlur 0 120      # Applied first
-  EFFECT + ChromaAberration 0 120  # Applied second
-  EFFECT + Solarize 0 120          # Applied last
-```
-
-### Four-Bar Sequence (16 beats)
-```
-# BPM 120
-SEQUENCE 0 0 "Intro"
-  EFFECT + Flash 0 1               # First beat
-  EFFECT + Heptagon 4 12           # Second bar through third bar
-  EFFECT + Fade 15 16              # Final beat
-```
-
-### Explicit Physical Time (Rare)
-```
-SEQUENCE 2.5s 0 "Intro timing"     # Start at 2.5 physical seconds
-  EFFECT + Fade 0 4                # Fade from beat 0-4 (relative)
-```
-
----
-
-## Visualization
-
-### Gantt Charts
-
-**ASCII Chart (Terminal):**
-```bash
-./build/seq_compiler workspaces/main/timeline.seq --gantt=timeline.txt
-```
-
-**HTML/SVG Chart (Recommended):**
-```bash
-./build/seq_compiler workspaces/main/timeline.seq --gantt-html=timeline.html
-```
-Interactive visualization with hover tooltips, color coding, and zoom/pan.
-
-### Validation Only
-```bash
-./build/seq_compiler workspaces/main/timeline.seq
-```
-Validates syntax without generating code.
-
----
-
-## Integration
-
-CMake automatically invokes the compiler on workspace timeline changes:
-
-```cmake
-add_custom_command(
-  OUTPUT ${GENERATED_DIR}/timeline.cc
-  COMMAND seq_compiler ${WORKSPACE_TIMELINE} ${GENERATED_DIR}/timeline.cc
-  DEPENDS ${WORKSPACE_TIMELINE}
-)
-```
-
----
-
-## See Also
-
-- `workspaces/main/timeline.seq` - Main demo timeline
-- `workspaces/test/timeline.seq` - Test demo timeline
-- `doc/WORKSPACE_SYSTEM.md` - Workspace organization
-- `src/gpu/demo_effects.h` - Available effect classes
-- `doc/HOWTO.md` - Building and running
diff --git a/doc/SEQUENCE_v2.md b/doc/SEQUENCE_v2.md
index 0e9d5a9..7ce6efc 100644
--- a/doc/SEQUENCE_v2.md
+++ b/doc/SEQUENCE_v2.md
@@ -1,130 +1,221 @@
-# Sequence v2 System Documentation
+# Sequence v2: DAG-based Effect Routing
 
-**Status:** Phase 1 & 2 complete (Foundation + Compiler operational)
+**Status:** ✅ Operational (Phase 4 complete, v1 removed)
+
+Explicit node system with DAG effect routing. Replaces v1 implicit framebuffer ping-pong.
 
 ## Quick Start
 
 ```bash
-# Compile v2 timeline to C++
-python3 tools/seq_compiler_v2.py input.seq --output generated/timeline_v2.cc
+# Compile timeline
+python3 tools/seq_compiler_v2.py workspaces/main/timeline_v2.seq --output src/generated/timeline.cc
 
-# Final mode (flattened, no vtables)
-python3 tools/seq_compiler_v2.py input.seq --output timeline_v2.cc --flatten
+# Flatten mode (future: inline effects, no vtables)
+python3 tools/seq_compiler_v2.py timeline.seq --output timeline.cc --flatten
 ```
 
-## v2 Timeline Syntax
+## Timeline Syntax
 
 ```
-# BPM 120
+# BPM 120 (optional, currently ignored)
 
-SEQUENCE 0.0 0 "sequence_name"
+SEQUENCE <start_time> <priority> ["name"]
   # Node declarations (optional, auto-inferred as u8x4_norm)
-  NODE gbuf_normal f16x8
+  NODE temp1 u8x4_norm
   NODE depth depth24
+  NODE gbuf_normal f16x8
 
-  # Asset dependencies
+  # Asset dependencies (validated at compile-time)
   ASSET shader_blur
 
-  # Effect routing: inputs... -> outputs...
-  EFFECT + DeferredRender source depth -> gbuf_normal gbuf_pos 0.0 10.0
-  EFFECT + Compose gbuf_normal gbuf_pos -> composed 0.0 10.0
-  EFFECT + Blur composed -> sink 0.0 10.0
+  # Effect routing with priority modifier
+  EFFECT <+|=|-> EffectClass input1 input2 -> output1 output2 start end [params]
+```
+
+**Priority modifiers** (REQUIRED):
+- `+` : Increment priority (foreground)
+- `=` : Same priority as previous
+- `-` : Decrement priority (background)
+
+**Node types**: `u8x4_norm` (default), `f32x4`, `f16x8`, `depth24`, `compute_f32`
+
+**Reserved nodes**: `source` (input), `sink` (output)
+
+### Examples
+
+**Simple chain:**
+```
+SEQUENCE 0.0 0 "basic"
+  EFFECT + HeptagonEffect source -> temp1 0.0 10.0
+  EFFECT + GaussianBlur temp1 -> sink 0.0 10.0
+```
+
+**Multi-output (G-buffer):**
+```
+SEQUENCE 0.0 0 "deferred"
+  NODE gbuf_n f16x8
+  NODE gbuf_p f32x4
+  NODE depth depth24
+
+  EFFECT + DeferredRender source depth -> gbuf_n gbuf_p 0.0 10.0
+  EFFECT + Compose gbuf_n gbuf_p -> sink 0.0 10.0
+```
+
+**Ping-pong (auto-optimized):**
+```
+SEQUENCE 0.0 0 "blur"
+  # Compiler detects alternating pattern, aliases temp2 -> temp1
+  EFFECT + BlurH source -> temp1 0.0 10.0
+  EFFECT + BlurV temp1 -> temp2 0.0 10.0
+  EFFECT + Sharpen temp2 -> sink 0.0 10.0
+```
+
+## Architecture
+
+### SequenceV2 Class
+
+```cpp
+class SequenceV2 {
+  NodeRegistry nodes_;              // Typed texture management
+  std::vector<EffectDAGNode> effect_dag_;  // Topologically sorted
+  UniformsSequenceParams params_;   // Per-frame uniforms
+
+  virtual void preprocess(float time, float beat_time, float beat_phase, float audio_intensity);
+  virtual void render_effects(WGPUCommandEncoder encoder);
+};
+```
+
+### EffectV2 Class
+
+```cpp
+class EffectV2 {
+  std::vector<std::string> input_nodes_;
+  std::vector<std::string> output_nodes_;
+
+  virtual void declare_nodes(NodeRegistry& registry) {}  // Optional temp nodes
+  virtual void render(WGPUCommandEncoder encoder,
+                      const UniformsSequenceParams& params,
+                      NodeRegistry& nodes) = 0;
+};
+```
+
+### Node System
+
+**Types**: Match WGSL texture formats
+- `U8X4_NORM`: RGBA8Unorm (default for source/sink/intermediate)
+- `F32X4`: RGBA32Float (HDR, compute outputs)
+- `F16X8`: 8-channel float16 (G-buffer normals/vectors)
+- `DEPTH24`: Depth24Plus (3D rendering)
+- `COMPUTE_F32`: Storage buffer (non-texture compute data)
+
+**Aliasing**: Compiler detects ping-pong patterns (Effect i writes A reads B, Effect i+1 writes B reads A) and aliases nodes to same backing texture.
+
+## Compiler Features
+
+**seq_compiler_v2.py** generates optimized C++ from `.seq`:
+
+1. **DAG Validation**: Cycle detection, connectivity checks
+2. **Topological Sort**: Execution order from dependencies
+3. **Ping-pong Detection**: Automatic node aliasing
+4. **Code Generation**: SequenceV2 subclasses with node declarations and effect DAG
+
+**Output**: Single `.cc` file with:
+- Multiple `SequenceV2` subclasses (one per SEQUENCE)
+- `InitializeV2Sequences()` - Registry initialization
+- `GetActiveV2Sequence(float time)` - Active sequence lookup
+- `RenderV2Timeline()` - Encoder-based and surface-based variants
+
+## Creating Effects
+
+**For standard post-process:**
+```cpp
+class MyEffectV2 : public EffectV2 {
+  WGPURenderPipeline pipeline_;
+  UniformBuffer<UniformsSequenceParams> uniforms_;
+
+  MyEffectV2(const GpuContext& ctx, const std::vector<std::string>& inputs,
+             const std::vector<std::string>& outputs)
+    : EffectV2(ctx, inputs, outputs) {
+    uniforms_.init(ctx_.device);
+    pipeline_ = create_post_process_pipeline(ctx_.device,
+                                             WGPUTextureFormat_RGBA8Unorm,
+                                             my_shader_wgsl);
+  }
+
+  void render(WGPUCommandEncoder encoder, const UniformsSequenceParams& params,
+              NodeRegistry& nodes) override {
+    WGPUTextureView input = nodes.get_view(input_nodes_[0]);
+    WGPUTextureView output = nodes.get_view(output_nodes_[0]);
+    uniforms_.update(ctx_.queue, params);
+    // ... render pass
+  }
+};
+```
+
+**For 3D effects with depth:**
+```cpp
+class My3DEffectV2 : public EffectV2 {
+  std::string depth_node_;
+
+  My3DEffectV2(...) : EffectV2(...), depth_node_(outputs[0] + "_depth") {}
+
+  void declare_nodes(NodeRegistry& registry) override {
+    registry.declare_node(depth_node_, NodeType::DEPTH24, -1, -1);
+  }
+
+  void render(...) {
+    WGPUTextureView color = nodes.get_view(output_nodes_[0]);
+    WGPUTextureView depth = nodes.get_view(depth_node_);
+    // ... render pass with depth attachment
+  }
+};
+```
+
+## Uniform Access
+
+```cpp
+params.time;            // Physical seconds (constant speed)
+params.beat_time;       // Musical beats (tempo-scaled)
+params.beat_phase;      // Fractional beat 0.0-1.0
+params.audio_intensity; // Audio peak for beat sync
+params.resolution;      // vec2(width, height)
+params.aspect_ratio;    // width/height
 ```
 
-**Node types:** `u8x4_norm`, `f32x4`, `f16x8`, `depth24`, `compute_f32`
-
-**Priority modifiers:** `+` (increment), `=` (same), `-` (decrement)
-
----
-
-This document describes the high-level ideas for an improved Sequence + Effects system "version 2".
-
-## Goal
-
-* more flexibility and less boilerplate
-* fully configurable by text (.seq)
-* no compatibility with previous version of sequences
-* sequence can be stacked (with priority) and arranged in a timeline to create a demo
-
-## Structure
-
-### Sequence
-
-A 'Sequence' unit consist of:
-  * A predeclared set of named assets and Effects that are used during the sequence
-  * a start-time, end-time
-  * a globally-visible set of internal time-dependent params (UniformsSequenceParams) derived from GlobalParams
-  * a globally-visible set of fixed params values (UniformsSequenceStaticParams) used to configure effects
-  * an input in RGBAu8 format ("Source"). Black by default (RGB=0,0,0,255). Buffer format: u8x4_norm (see below)
-  * an output in RGBAu8 format ("Sink"). This output goes to the next sequence in stack or to physical display
-  * the sink of a Sequence is the source of the next Sequence in the stack, or goes to screen if it's the last sequence in stack
-  * three programatic sections: 'Preprocess', 'EffectFlow' (time-ordered set of effects), 'Postprocess'
-  * a set of internal buffers (Nodes = compute buffers or textures, used as input or render targets by effects stack)
-  * this Nodes are visible to the final post-process effect
-  * Node persists during the whole sequence
-  * at compile time, one can detect which Node can actually be ping-pong buffers
-  * each Sequence's preprocess and postprocess is unique and attached to the sequence
-
-### Effects
-
-The effect unit consists in:
-  * An 'Effect' within the Sequence uses the UniformsSequenceParams and GlobalParams to update its internal state
-  * Receives updated InputNode from the previous effects (InputNode = buffer, textures, g-buffer, ...)
-  * processes them with a shader or c++ code (3d engine, etc.)
-  * fills its OutputNode, passed to the next effect or the final postprocessing step
-  * uses the sequence's assets and params only
-  * if needed an effect predefines an alias of one of its internal buffer as its declared 'postprocess_output' OutputNode
-  * by default, postprocess_output = sequence RGBA Source
-  * Effect's are not attached to a particular Sequence, and can be used in any Sequence
-
-### Preprocess:
-  * the preprocessing step sets up the local UniformsSequenceParams (prepare timers, objects' transforms, camera position, fills Uniform buffers, etc.) 
-  * it's a single function attached to the Sequence unit (virtual method?)
-
-### Postprocess:
-  * the post-process unique (virtual) function is responsible for the final assembly into OuputNode
-  * it can take any internal Node as input (most likely the last effects' output) and produces its final Sink content
-
-## How it works
-
-### initialization
-
-at initialization time, the sequence knows from compile-time:
-  * the list of assets it needs to be ready at start time
-  * the list of effects needed, their input nodes, their output node
-  * the list of internal textures, buffer, render target, depth-buffer it will need for its stack effect to work
-  * which intern Node buffers can actually be ping-pong buffers, to optimize resource
-  * generally speaking, the lifetime of a buffer during a frame is known at compile time and can be optimized
-
-### Flow
-  * preprocess: prepare internal state at time t: UniformsSequenceParams
-  * for each effects:
-     ** bind the InputNode nodes (previous effect buffers, compute buffers, etc.)
-     ** runs the compute, vertex and fragment passes
-     ** fills its output Nodes
-  * process: turns its pre-declared input Nodes into its unique Sink node, ready for next sequence, or display
-
-## Requirement
-
-  * unified code to flow the engine
-  * textual description of the sequence/effects arrangement (similar to the .seq)
-  * update the HTML editor tool
-  * unified description of buffer, texture and compute buffers at compilation time
-    ** example, of a sequence's internal Node declaration:
-     "NODE Name1 u8x16_norm"
-     "NODE Name2 f32x4"
-     "NODE Name3 f16x8"
-     "Node Name4 u8x4_norm" <- Source/Sink of a sequence, four bytes
-  * each effect
-    ** declares its requirement as input Node.
-    ** declares its output Node
-    ** can access the C++ version and WebGPU versions of GlobalParams, UniformsSequenceParams and UniformsSequenceStaticParams
-    ** are not attached to a particular sequence, but can be used in many
-  * validation and optimization at compile time (generating c++ code) by seq_compiler
-  * compilation can generate boilerplate preprocess() / postprocess() functions  
-  * no backward compatibility needed. Sequence v1 can go.
-  * the HTML Editor overall code, look and functionalities need to be preserved though. Just adapted to v2.
-    ** basically the sequence box will need to show input Node and output Node and have an editable property panel for these
-    ** same for effects: ability to edit their input Node and output Node names
-  * a lot of v1 effects can be deleted (solarized, chroma aberration, etc.): they will be implemented ad-hoc in postprocess() with a single macro call within the final shader
-  * need a minimal migration plan for code.
+## Status & Limitations
+
+**Implemented** ✅:
+- DAG validation, topological sort, ping-pong optimization
+- Multi-input/multi-output effects
+- Node aliasing (compile-time optimization)
+- 7 effects ported (Passthrough, Placeholder, GaussianBlur, Heptagon, Particles, RotatingCube, Hybrid3D)
+
+**Missing/Future** ❌:
+- Flatten mode (--flatten generates same code as dev mode)
+- BPM handling (parsed but ignored)
+- GetDemoDuration() calculation (hardcoded 40.0f)
+- Sequence-relative time (uses global time)
+- Asset validation (not checked against AssetId enum)
+- Node type compatibility checking
+
+**TODO**:
+- Port remaining effects (10+ effects, CNN effects)
+- Implement flatten mode (inline effects, direct members)
+- Update HTML timeline editor for v2 graph visualization
+
+## Migration Notes
+
+**V1 → V2 Differences**:
+- V1: Implicit framebuffer ping-pong (framebuffer_a_ ↔ framebuffer_b_)
+- V2: Explicit node declarations with routing
+
+**Breaking Changes**:
+- Effect base class changed (Effect → EffectV2)
+- Constructor signature: `(GpuContext, inputs[], outputs[])`
+- Render signature: Added `NodeRegistry& nodes` parameter
+- No `is_post_process()` method (routing makes it explicit)
+
+**See Also**:
+- `doc/EFFECT_WORKFLOW.md` - Step-by-step effect creation
+- `tools/seq_compiler_v2.py` - Compiler implementation
+- `workspaces/main/timeline_v2.seq` - Example timeline
diff --git a/doc/archive/SEQUENCE_V1.md b/doc/archive/SEQUENCE_V1.md
new file mode 100644
index 0000000..03d0c45
--- /dev/null
+++ b/doc/archive/SEQUENCE_V1.md
@@ -0,0 +1,220 @@
+# Sequence System Documentation
+
+This document describes the `.seq` file format used to define demo timelines.
+
+## Overview
+
+Sequence files (`.seq`) define the timeline and layering of visual effects. They are compiled by `seq_compiler` into C++ code at build time.
+
+**Locations:**
+- Main demo: `workspaces/main/timeline.seq`
+- Test demo: `workspaces/test/timeline.seq`
+- Compiler: `tools/seq_compiler.cc`
+- Generated output: `src/generated/timeline.cc`
+
+---
+
+## Syntax Reference
+
+### BPM Declaration
+```
+# BPM 120
+```
+Specifies beats per minute. Required. Used to convert beats to physical seconds at runtime.
+
+### END_DEMO Directive
+```
+END_DEMO <time>
+```
+Optional auto-exit time in beats (e.g., `64` or `64b`) or explicit seconds (`32.0s`).
+
+### SEQUENCE Declaration
+```
+SEQUENCE <global_start> <priority> ["optional_name"] [optional_end]
+  EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...]
+```
+
+**Parameters:**
+- `global_start`: Sequence start time in beats (default) or explicit seconds (`2.5s`)
+- `priority`: Render order (0-9 for scenes, 10+ for post-processing)
+- `"optional_name"`: Optional display name for Gantt charts
+- `[optional_end]`: Optional sequence end time in beats (forces effect termination)
+
+**Examples:**
+```
+SEQUENCE 0 0                        # Basic sequence
+SEQUENCE 0 0 "Intro"                # Named sequence
+SEQUENCE 0 0 [5.0]                  # Explicit end time
+SEQUENCE 0 0 "Action Scene" [10.0]  # Both name and end time
+```
+
+### EFFECT Declaration
+```
+EFFECT <+|=|-> <EffectClassName> <local_start> <local_end> [constructor_args...]
+```
+
+**Priority Modifiers:**
+- `+`: Increment priority (or start at 0 if first)
+- `=`: Keep same priority as previous
+- `-`: Decrement priority (or start at -1 if first, for backgrounds)
+
+**Parameters:**
+- `EffectClassName`: C++ class from `demo_effects.h`
+- `local_start`, `local_end`: Time in beats relative to sequence start
+- `constructor_args`: Optional (rarely used, most effects use standard params only)
+
+---
+
+## Time Notation
+
+**Beat-based timing (default):** All times are in musical beats, ensuring alignment regardless of BPM changes.
+
+| Notation | Example | Description |
+|----------|---------|-------------|
+| **Beats (default)** | `0`, `4`, `16` | Integer or decimal, no suffix |
+| Explicit beats | `4b`, `16.5b` | Optional 'b' suffix for clarity |
+| Explicit seconds | `2.0s`, `8.25s` | Suffix 's' for physical time (rare) |
+
+**Conversion:** At 120 BPM, 1 beat = 0.5 seconds, 4 beats = 2 seconds
+
+**Why beats?**
+- Musical alignment: Sequences stay synchronized to music structure
+- BPM independence: Changing BPM preserves musical timing
+- Intuitive authoring: Timeline matches bars/beats
+
+---
+
+## Runtime Parameters
+
+All effects receive these parameters every frame in `render()` via `CommonPostProcessUniforms`:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resolution` | vec2 | Screen dimensions in pixels |
+| `aspect_ratio` | float | Screen width/height ratio |
+| `time` | float | Physical time in seconds (unaffected by tempo) |
+| `beat_time` | float | Musical time in beats (absolute) |
+| `beat_phase` | float | Fractional beat (0.0-1.0 within current beat) |
+| `audio_intensity` | float | Audio peak (0.0-1.0, for beat sync) |
+
+**Use cases:**
+- `time`: Physics-based animation (constant speed)
+- `beat_time`: Musical animation (sync to bars/beats)
+- `beat_phase`: Smooth oscillation per beat
+
+---
+
+## Priority System
+
+**Scene Effects (0-9):**
+- `-1`: Background (skybox, far objects)
+- `0-5`: Midground (main geometry)
+- `6-9`: Foreground (overlays, particles)
+
+**Post-Process (10+):**
+- Applied in order: blur → distortion → color grading
+- Higher priority = rendered later (on top)
+
+---
+
+## Examples
+
+### Basic Sequence
+```
+# BPM 120
+SEQUENCE 0 0
+  EFFECT + FlashEffect 0 1         # Priority 0, beats 0-1 (0-0.5s @ 120 BPM)
+  EFFECT + HeptagonEffect 0.4 20   # Priority 1, beats 0.4-20
+```
+
+### Same Priority Layering
+```
+SEQUENCE 0 0
+  EFFECT + Flash 0 1               # Priority 0
+  EFFECT = Fade 0.2 0.6            # Priority 0 (same layer)
+  EFFECT + Other 0.4 6             # Priority 1
+```
+
+### Background Elements
+```
+SEQUENCE 0 0
+  EFFECT - FlashCube 0 20          # Priority -1 (background)
+  EFFECT = BgEffect 0 10           # Priority -1 (same layer)
+  EFFECT + MainEffect 0 20         # Priority 0 (foreground)
+```
+
+### Sequence with Explicit End
+```
+SEQUENCE 16 0 [10]
+  EFFECT + Particles 0 240         # Runs until beat 26 (sequence end at 16+10)
+```
+
+### Post-Processing Chain
+```
+SEQUENCE 0 10
+  EFFECT + GaussianBlur 0 120      # Applied first
+  EFFECT + ChromaAberration 0 120  # Applied second
+  EFFECT + Solarize 0 120          # Applied last
+```
+
+### Four-Bar Sequence (16 beats)
+```
+# BPM 120
+SEQUENCE 0 0 "Intro"
+  EFFECT + Flash 0 1               # First beat
+  EFFECT + Heptagon 4 12           # Second bar through third bar
+  EFFECT + Fade 15 16              # Final beat
+```
+
+### Explicit Physical Time (Rare)
+```
+SEQUENCE 2.5s 0 "Intro timing"     # Start at 2.5 physical seconds
+  EFFECT + Fade 0 4                # Fade from beat 0-4 (relative)
+```
+
+---
+
+## Visualization
+
+### Gantt Charts
+
+**ASCII Chart (Terminal):**
+```bash
+./build/seq_compiler workspaces/main/timeline.seq --gantt=timeline.txt
+```
+
+**HTML/SVG Chart (Recommended):**
+```bash
+./build/seq_compiler workspaces/main/timeline.seq --gantt-html=timeline.html
+```
+Interactive visualization with hover tooltips, color coding, and zoom/pan.
+
+### Validation Only
+```bash
+./build/seq_compiler workspaces/main/timeline.seq
+```
+Validates syntax without generating code.
+
+---
+
+## Integration
+
+CMake automatically invokes the compiler on workspace timeline changes:
+
+```cmake
+add_custom_command(
+  OUTPUT ${GENERATED_DIR}/timeline.cc
+  COMMAND seq_compiler ${WORKSPACE_TIMELINE} ${GENERATED_DIR}/timeline.cc
+  DEPENDS ${WORKSPACE_TIMELINE}
+)
+```
+
+---
+
+## See Also
+
+- `workspaces/main/timeline.seq` - Main demo timeline
+- `workspaces/test/timeline.seq` - Test demo timeline
+- `doc/WORKSPACE_SYSTEM.md` - Workspace organization
+- `src/gpu/demo_effects.h` - Available effect classes
+- `doc/HOWTO.md` - Building and running
-- 
cgit v1.2.3