path: root/tools/shader_editor/SHADER_EDITOR_PLAN.md

# 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)