1 files changed, 90 insertions, 0 deletions
diff --git a/tools/shader_editor/README.md b/tools/shader_editor/README.md
new file mode 100644
index 0000000..ed3acf0
--- /dev/null
+++ b/tools/shader_editor/README.md
@@ -0,0 +1,90 @@
+# WGSL Shader Editor
+
+Live WebGPU shader editor with syntax highlighting and #include composition.
+
+## Quick Start
+
+```bash
+# Option 1: Direct file access
+open tools/shader_editor/index.html
+
+# Option 2: Local server (recommended)
+python3 -m http.server 8000
+# Then open http://localhost:8000/tools/shader_editor/
+```
+
+## Features
+
+- **Live WebGPU Preview** (57% screen) - Auto-plays on load
+- **Syntax Highlighting** (43% screen) - WGSL keywords, types, comments
+- **Shader Composition** - `#include` directive support
+- **Animation Controls** - Time, loop (0→1), audio peak
+- **File I/O** - Load/save .wgsl files
+- **Default Scene** - Animated gradient + pulsing circle
+
+## Controls
+
+**Animation:**
+- Auto-plays on load (Pause button to stop)
+- Loop Time: 0.0→1.0 progress bar (maps to `uniforms.beat`)
+- Loop Period: Adjustable cycle duration (default 2.0s)
+- Audio Peak: Manual slider or auto-pulse mode
+
+**Keyboard:**
+- `Ctrl/Cmd+S` - Save shader
+- `Ctrl/Cmd+O` - Load shader
+- `Space` - Play/Pause
+- `Tab` - Insert 4 spaces
+
+## Available Uniforms
+
+All shaders have access to `CommonUniforms` at `@binding(2)`:
+
+```wgsl
+struct CommonUniforms {
+    resolution: vec2<f32>,      // Canvas width/height
+    aspect_ratio: f32,          // width / height
+    time: f32,                  // Seconds since start (resetable)
+    beat: f32,                  // Loop time 0.0→1.0 (configurable period)
+    audio_intensity: f32,       // Manual slider or auto-pulse
+};
+@group(0) @binding(2) var<uniform> uniforms: CommonUniforms;
+```
+
+Standard bindings:
+- `@binding(0)` - Sampler
+- `@binding(1)` - Texture (1x1 black placeholder)
+- `@binding(2)` - CommonUniforms
+
+## Snippets
+
+Click "📚 Snippets" button to view available includes. Core snippet:
+
+```wgsl
+#include "common_uniforms"
+@group(0) @binding(2) var<uniform> uniforms: CommonUniforms;
+```
+
+Math: `math/sdf_shapes`, `math/sdf_utils`, `math/common_utils`, `math/noise`
+Render: `render/scene_query_linear`, `render/lighting_utils`, `render/shadows`
+Primitives: `sdf_primitives`, `lighting`, `ray_box`, `ray_triangle`
+
+## Technical Details
+
+See `SHADER_EDITOR_DETAILS.md` for:
+- Uniform buffer layout
+- Bind group specification
+- Example shaders
+- Architecture overview
+
+## Current Limitations
+
+- Fragment shaders only (no compute/vertex)
+- Single 1x1 black texture placeholder
+- Fixed 1280×720 resolution
+- Hardcoded snippet library
+- Basic syntax highlighting (no autocomplete)
+
+## Next Steps
+
+See `SHADER_EDITOR_PLAN.md` for roadmap.