docs: Reorganize shader editor documentationHEADmain

README.md: Streamlined quick start and feature overview
SHADER_EDITOR_DETAILS.md: Technical reference (architecture, uniforms, examples)
SHADER_EDITOR_PLAN.md: Development roadmap with 5 phases

Summary of implemented features:
- Live WebGPU preview (1280×720, autoplay)
- Syntax highlighting (placeholder-based, prevents overlap)
- #include composition (recursive resolution)
- Animation controls (time, beat, audio_peak)
- File I/O (load/save .wgsl)

Next priorities:
1. Multi-resolution support
2. Improved syntax highlighting
3. Texture upload

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

1 files changed, 47 insertions, 78 deletions

diff --git a/tools/shader_editor/README.md b/tools/shader_editor/README.md
index d22fe5e..ed3acf0 100644
--- a/tools/shader_editor/README.md
+++ b/tools/shader_editor/README.md
@@ -1,27 +1,40 @@
 # WGSL Shader Editor
 
-ShaderToy-like web tool for live WGSL shader editing with WebGPU preview.
+Live WebGPU shader editor with syntax highlighting and #include composition.
 
-## Features
+## Quick Start
+
+```bash
+# Option 1: Direct file access
+open tools/shader_editor/index.html
 
-- **Live Preview**: WebGPU rendering with real-time shader updates
-- **Shader Composition**: `#include` directive support for modular shaders
-- **Animation Controls**: Configurable time, loop, and audio parameters
-- **File I/O**: Load/save `.wgsl` files directly from browser
-- **Snippet Library**: Pre-loaded math, SDF, and rendering utilities
+# Option 2: Local server (recommended)
+python3 -m http.server 8000
+# Then open http://localhost:8000/tools/shader_editor/
+```
+
+## Features
 
-## Usage
+- **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
 
-1. **Open**: `file:///path/to/tools/shader_editor/index.html` in Chrome/Edge
-2. **Edit**: Type WGSL code in right pane (auto-composes on change)
-3. **Preview**: View live output in left canvas
-4. **Save**: Click "Save .wgsl" to download
+## Controls
 
-## Keyboard Shortcuts
+**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 animation
+- `Space` - Play/Pause
+- `Tab` - Insert 4 spaces
 
 ## Available Uniforms
 
@@ -43,79 +56,35 @@ Standard bindings:
 - `@binding(1)` - Texture (1x1 black placeholder)
 - `@binding(2)` - CommonUniforms
 
-## Available Snippets
-
-Use `#include "name"` to import:
-
-- `common_uniforms` - CommonUniforms struct definition
-- `math/sdf_shapes` - Sphere, box, torus primitives
-- `math/sdf_utils` - SDF operations (union, smooth blend)
-- `math/common_utils` - Rotation matrices, utilities
-- `math/noise` - Noise functions
-- `render/scene_query_linear` - Linear scene traversal
-- `render/scene_query_bvh` - BVH scene traversal
-- `render/lighting_utils` - Lighting helpers
-- `render/shadows` - Shadow calculation
-- `sdf_primitives` - Additional SDF shapes
-- `lighting` - Phong/lighting models
-- `ray_box` - Ray-AABB intersection
-- `ray_triangle` - Ray-triangle intersection
-
-Click "📚 Snippets" to browse and insert.
-
-## Animation Controls
+## Snippets
 
-- **Play/Pause**: Start/stop animation
-- **Loop Time**: Progress bar showing 0.0→1.0 cycle
-- **Loop Period**: Adjust cycle duration (1-10s)
-- **Time**: Ever-increasing clock (reset button)
-- **Audio Peak**: Manual slider (0-1) or auto-pulse mode
-- **Resolution**: Preset canvas sizes
+Click "📚 Snippets" button to view available includes. Core snippet:
 
-## Example Shaders
-
-### Minimal (No Composition)
-```wgsl
-@group(0) @binding(2) var<uniform> uniforms: CommonUniforms;
-
-@fragment fn fs_main(@builtin(position) p: vec4<f32>) -> @location(0) vec4<f32> {
-    let uv = p.xy / uniforms.resolution;
-    return vec4<f32>(uv, 0.5 + 0.5 * sin(uniforms.time), 1.0);
-}
-```
-
-### With Includes
 ```wgsl
 #include "common_uniforms"
 @group(0) @binding(2) var<uniform> uniforms: CommonUniforms;
-
-#include "math/sdf_shapes"
-
-@fragment fn fs_main(@builtin(position) p: vec4<f32>) -> @location(0) vec4<f32> {
-    let uv = (p.xy / uniforms.resolution) * 2.0 - 1.0;
-    let d = sdSphere(vec3<f32>(uv, 0.0), 0.5);
-    return vec4<f32>(vec3<f32>(step(d, 0.0)), 1.0);
-}
 ```
 
-## Limitations
+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
 
-- **Fragment shaders only** (no compute/vertex customization)
-- **Single texture input** (1x1 black placeholder)
-- **No custom uniforms** (CommonUniforms only)
-- **Read-only snippet library** (hardcoded from workspace)
-- **No syntax highlighting** (plain textarea)
+See `SHADER_EDITOR_DETAILS.md` for:
+- Uniform buffer layout
+- Bind group specification
+- Example shaders
+- Architecture overview
 
-## Testing
+## Current Limitations
 
-Load existing shaders from workspace:
-- `../../workspaces/main/shaders/passthrough.wgsl` - Basic
-- `../../workspaces/main/shaders/distort.wgsl` - With includes
+- Fragment shaders only (no compute/vertex)
+- Single 1x1 black texture placeholder
+- Fixed 1280×720 resolution
+- Hardcoded snippet library
+- Basic syntax highlighting (no autocomplete)
 
-## Future Enhancements
+## Next Steps
 
-- Monaco editor (syntax highlighting, autocomplete)
-- Custom uniform parameter UI
-- Texture upload support
-- Compute shader support
-- Export C++ Effect class skeleton
+See `SHADER_EDITOR_PLAN.md` for roadmap.