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, 270 insertions, 0 deletions

diff --git a/tools/shader_editor/SHADER_EDITOR_PLAN.md b/tools/shader_editor/SHADER_EDITOR_PLAN.md
new file mode 100644
index 0000000..f0298db
--- /dev/null
+++ b/tools/shader_editor/SHADER_EDITOR_PLAN.md
@@ -0,0 +1,270 @@
+# WGSL Shader Editor - Development Plan
+
+## Current State (MVP Complete)
+
+**Delivered:**
+- ✅ Live WebGPU preview (1280×720, 16:9)
+- ✅ Basic syntax highlighting (keywords, types, comments, functions)
+- ✅ Shader composition (#include directive resolution)
+- ✅ Animation controls (time, loop_time, audio_peak)
+- ✅ File I/O (load/save .wgsl)
+- ✅ Default animated scene (gradient + pulsing circle)
+- ✅ Autoplay on load
+- ✅ Keyboard shortcuts (Ctrl+S, Ctrl+O, Space)
+
+**Limitations:**
+- Fragment shaders only (vertex is fixed full-screen triangle)
+- Single 1x1 black texture placeholder at binding(1)
+- Fixed 1280×720 resolution
+- Basic regex-based syntax highlighting (no autocomplete)
+- Read-only snippet library
+
+---
+
+## Phase 1: Editor Enhancements
+
+### 1.1 Multi-Resolution Support
+**Goal:** Allow user to select canvas resolution
+
+**Tasks:**
+- [ ] Re-add resolution dropdown (move to collapsible settings panel)
+- [ ] Support custom resolution input (width×height)
+- [ ] Persist resolution in localStorage
+
+**Effort:** 1-2 hours
+
+### 1.2 Improved Syntax Highlighting
+**Goal:** Better highlighting accuracy, performance
+
+**Tasks:**
+- [ ] Add more WGSL types (texture_storage_2d, sampler_comparison, etc.)
+- [ ] Highlight built-in functions (sin, cos, normalize, mix, etc.)
+- [ ] Highlight operators (*, +, -, /, %, ==, !=, etc.)
+- [ ] Optimize regex execution (cache compiled patterns)
+- [ ] Add line numbers in gutter
+
+**Effort:** 3-4 hours
+
+### 1.3 Monaco Editor Integration
+**Goal:** Professional code editing experience
+
+**Tasks:**
+- [ ] Load Monaco Editor from CDN
+- [ ] Register WGSL language definition
+- [ ] Configure theme to match current dark theme
+- [ ] Add autocomplete for WGSL keywords/types
+- [ ] Add snippet autocomplete for #include directives
+- [ ] Add error squiggles from shader compilation errors
+
+**Effort:** 6-8 hours
+**Blocker:** Increases page load time, adds dependency
+
+---
+
+## Phase 2: Texture & Uniform Support
+
+### 2.1 Texture Upload
+**Goal:** Load external images as input textures
+
+**Tasks:**
+- [ ] Add "Upload Texture" button
+- [ ] Support JPG, PNG, WebP formats
+- [ ] Replace binding(1) texture with uploaded image
+- [ ] Add texture preview thumbnail
+- [ ] Support multiple texture slots (binding 1, 3, 4, etc.)
+- [ ] Persist textures in IndexedDB (optional)
+
+**Effort:** 4-6 hours
+
+### 2.2 Custom Uniform Parameters
+**Goal:** Parse and expose @binding(3) custom uniforms
+
+**Tasks:**
+- [ ] Parse shader code for custom uniform structs at binding(3)
+- [ ] Generate UI controls (sliders, color pickers, checkboxes)
+- [ ] Update uniform buffer on control change
+- [ ] Support basic types: f32, vec2, vec3, vec4, bool
+- [ ] Add preset saving/loading
+
+**Effort:** 8-10 hours
+**Challenge:** WGSL struct parsing, dynamic uniform buffer allocation
+
+---
+
+## Phase 3: Shader Library & Export
+
+### 3.1 Snippet Browser Improvements
+**Goal:** Better snippet discovery and management
+
+**Tasks:**
+- [ ] Fetch snippet list dynamically from workspace
+- [ ] Show snippet preview on hover
+- [ ] Add search/filter for snippets
+- [ ] Group snippets by category (Math, Render, SDF, etc.)
+- [ ] Show snippet dependencies (what it includes)
+
+**Effort:** 3-4 hours
+
+### 3.2 Shader Gallery
+**Goal:** Save and browse user-created shaders
+
+**Tasks:**
+- [ ] Add "Save to Gallery" button (stores in localStorage)
+- [ ] Thumbnail generation (render to canvas, toDataURL)
+- [ ] Gallery browser UI (grid of thumbnails)
+- [ ] Import/export gallery as JSON
+- [ ] Tag/name shaders
+
+**Effort:** 6-8 hours
+
+### 3.3 C++ Effect Export
+**Goal:** Generate C++ boilerplate for demo integration
+
+**Tasks:**
+- [ ] Template for Effect subclass (constructor, render, uniforms)
+- [ ] Extract custom uniform struct → C++ struct
+- [ ] Generate GetWGSLCode() method with embedded shader
+- [ ] Generate uniform buffer write code
+- [ ] Add to CLAUDE.md as snippet
+
+**Effort:** 4-6 hours
+
+---
+
+## Phase 4: Advanced Features
+
+### 4.1 Compute Shader Support
+**Goal:** Edit and run compute shaders
+
+**Tasks:**
+- [ ] Add "Shader Type" selector (Fragment / Compute)
+- [ ] Compute shader template (workgroup size, storage buffers)
+- [ ] Execute compute passes (dispatch N workgroups)
+- [ ] Visualize compute output (read storage buffer → texture)
+- [ ] Example: Image processing (blur, edge detect)
+
+**Effort:** 10-12 hours
+**Challenge:** Different pipeline, storage buffer management
+
+### 4.2 Multi-Pass Rendering
+**Goal:** Chain multiple shaders (render-to-texture)
+
+**Tasks:**
+- [ ] Add "Add Pass" button (create pipeline chain)
+- [ ] Intermediate texture allocation
+- [ ] Render pass dependency graph
+- [ ] Visualize pipeline (node graph UI)
+- [ ] Example: Bloom effect (downsample → blur → upsample → composite)
+
+**Effort:** 12-16 hours
+**Challenge:** Complex state management, texture resizing
+
+### 4.3 Hot Reload from Filesystem
+**Goal:** Live-reload shaders from workspace on file change
+
+**Tasks:**
+- [ ] File System Access API (Chrome) to watch workspace directory
+- [ ] Detect .wgsl file changes
+- [ ] Auto-reload shader in editor
+- [ ] Notification banner on reload
+
+**Effort:** 4-6 hours
+**Blocker:** Requires user permission, Chrome-only
+
+---
+
+## Phase 5: Integration & Optimization
+
+### 5.1 Demo Integration
+**Goal:** Embed editor in main demo for live shader editing
+
+**Tasks:**
+- [ ] Add `--shader-editor` flag to demo64k
+- [ ] Render demo in left pane, editor in right
+- [ ] Share GPU device and context
+- [ ] Live-patch demo shaders from editor
+- [ ] Debug overlay (frame time, uniform values)
+
+**Effort:** 8-10 hours
+**Challenge:** Embedding HTML UI in native app, IPC
+
+### 5.2 Size Optimization
+**Goal:** Reduce HTML file size for archival
+
+**Tasks:**
+- [ ] Minify JavaScript (UglifyJS, Terser)
+- [ ] Minify CSS (cssnano)
+- [ ] Strip comments, whitespace
+- [ ] Inline critical CSS only
+- [ ] Lazy-load snippet library
+- [ ] Target: <50KB gzipped
+
+**Effort:** 2-3 hours
+
+---
+
+## Prioritization
+
+**Next Sprint (High Priority):**
+1. Multi-resolution support (1.1) - Quick win
+2. Improved syntax highlighting (1.2) - Quality of life
+3. Texture upload (2.1) - Unlocks creative use cases
+
+**Medium Priority:**
+4. Custom uniform parameters (2.2) - Big feature, high value
+5. Snippet browser improvements (3.1) - Usability
+6. Shader gallery (3.2) - User retention
+
+**Low Priority (Nice to Have):**
+7. Monaco editor (1.3) - High effort, marginal benefit over current
+8. Compute shaders (4.1) - Niche use case
+9. Multi-pass rendering (4.2) - Complex, limited use
+10. C++ export (3.3) - Automation convenience
+
+**Future/Experimental:**
+- Hot reload (4.3) - Browser-specific
+- Demo integration (5.1) - Architecture overhaul
+
+---
+
+## Non-Goals
+
+- **Vertex shader editing:** Fixed full-screen triangle is sufficient for post-processing
+- **3D scene editing:** Out of scope, use Blender
+- **Audio synthesis:** Separate tool (spectral editor)
+- **GLSL/HLSL support:** WGSL only
+- **Mobile support:** Desktop-focused tool
+- **Collaborative editing:** Single-user workflow
+
+---
+
+## Success Metrics
+
+- **Adoption:** Used for >3 demo effects in production
+- **Iteration speed:** 50% faster shader prototyping vs. edit-compile-run cycle
+- **Code quality:** <10% of shaders require manual C++ integration fixes
+- **Performance:** 60 FPS preview at 1920×1080
+- **Reliability:** <1 crash per 100 shader compilations
+
+---
+
+## Current Commit Summary
+
+**Implemented (11 commits):**
+1. a954a77 - Initial shader editor tool
+2. 8b76fcc - Layout adjustment (70/30 → 64/36)
+3. adbf0ba - Fix mutable `var` for uv
+4. fa7b840 - Fix bind group layout (reference all bindings)
+5. 0285ffc - Canvas height fix
+6. 5631ab5 - 16:9 aspect ratio, default 1280×720
+7. 22116e2 - Remove resolution selector, enable autoplay
+8. 6a01474 - Fix JS error after removing resolution selector
+9. c267070 - Editor pane 43%, preview 57%
+10. 289ee4e - Add WGSL syntax highlighting
+11. a3e3823 - Improve highlighting to avoid overlaps
+12. f2e1251 - Placeholder-based highlighting fix
+
+**Next Commit:**
+- Update README.md (streamline, reference details doc)
+- Add SHADER_EDITOR_DETAILS.md (technical reference)
+- Add SHADER_EDITOR_PLAN.md (this file)