Investigation: Shader code reuse options analysis

Analyzed 36 duplicate common shaders across workspaces.
Documented 5 approaches with tradeoffs:
1. Shared common/ directory
2. Symbolic links
3. Build-time sync
4. Asset system extension
5. Status quo + documentation

See doc/SHADER_REUSE_INVESTIGATION.md for full analysis.

handoff(Claude): Shader reuse investigation complete

1 files changed, 222 insertions, 0 deletions

diff --git a/doc/SHADER_REUSE_INVESTIGATION.md b/doc/SHADER_REUSE_INVESTIGATION.md
new file mode 100644
index 0000000..4f83f1d
--- /dev/null
+++ b/doc/SHADER_REUSE_INVESTIGATION.md
@@ -0,0 +1,222 @@
+# Shader Code Reuse Investigation
+
+## Current State
+
+### Duplication Analysis
+- **36 duplicate shader files** between main and test workspaces
+- Common files include: math utilities, render helpers, compute shaders, uniforms
+- Files are byte-identical duplicates (verified)
+
+### Current System Architecture
+1. **ShaderComposer**: Runtime shader composition via `#include` directives
+2. **Asset System**: Shaders loaded from workspace `assets.txt`
+3. **Registration**: `InitShaderComposer()` registers snippets with paths like:
+   - `common_uniforms`
+   - `math/sdf_shapes`, `math/noise`, `math/common_utils`
+   - `render/shadows`, `render/scene_query_bvh`, `render/lighting_utils`
+
+### Duplicate Common Shaders
+```
+Common across both workspaces:
+- common_uniforms.wgsl
+- math/{common_utils, noise, sdf_shapes, sdf_utils}.wgsl
+- render/{lighting_utils, scene_query_bvh, scene_query_linear, shadows}.wgsl
+- compute/{gen_blend, gen_grid, gen_mask, gen_noise, gen_perlin}.wgsl
+- Various effect shaders (passthrough, lighting, ray_box, etc.)
+```
+
+---
+
+## Proposed Approaches
+
+### Option 1: Shared Common Directory (Original Design)
+**Structure:**
+```
+/common/
+  /shaders/
+    /math/          # Shared math utilities
+    /render/        # Shared rendering helpers
+    /compute/       # Shared compute shaders
+    common_uniforms.wgsl
+
+/workspaces/
+  /main/
+    /shaders/       # Workspace-specific only
+    /music/
+    /weights/
+    /obj/
+```
+
+**Pros:**
+- Single source of truth for common code
+- No duplication
+- Clear separation: common vs workspace-specific
+- Matches original design doc intent
+
+**Cons:**
+- Breaks workspace isolation (workspaces depend on external directory)
+- Harder to version control per-workspace
+- Need to update asset packer to handle cross-workspace references
+- Complicates workspace portability
+
+---
+
+### Option 2: Symbolic Links
+**Structure:**
+```
+/workspaces/
+  /main/
+    /shaders/
+      /common@ -> ../../common/shaders/  # Symlink
+      custom_effect.wgsl
+```
+
+**Pros:**
+- Maintains single source
+- Works with existing asset system
+- Simple filesystem solution
+
+**Cons:**
+- Windows symlink issues (requires admin or dev mode)
+- Git symlink handling varies
+- Still breaks workspace isolation
+- Can confuse developers
+
+---
+
+### Option 3: Build-Time Copy/Sync
+**Structure:**
+Workspaces keep duplicates, but sync from canonical source at build time.
+
+```
+/common/shaders/     # Canonical source
+/workspaces/*/shaders/  # Build-synced copies
+```
+
+**Implementation:**
+- CMake script copies common/ → workspaces/ before asset packing
+- Or: Pre-commit hook validates consistency
+
+**Pros:**
+- Workspaces remain self-contained
+- No runtime dependencies
+- Works across all platforms
+- Git shows actual files
+
+**Cons:**
+- Easy to forget sync
+- Merge conflicts if edited in workspace
+- Need tooling to maintain consistency
+
+---
+
+### Option 4: Asset System Extension
+**Enhance asset packer to support cross-workspace includes:**
+
+`workspaces/main/assets.txt`:
+```
+SHADER_COMMON_UTILS, NONE, @common/shaders/math/common_utils.wgsl
+SHADER_CUSTOM, NONE, shaders/custom_effect.wgsl
+```
+
+**Pros:**
+- Clean at asset definition level
+- ShaderComposer unchanged
+- Explicit common vs local
+
+**Cons:**
+- Asset packer modification needed
+- New syntax to learn
+- Breaks workspace portability
+
+---
+
+### Option 5: Status Quo + Documentation
+**Keep duplicates, document as intentional.**
+
+Add `common/shaders/` as reference templates that workspaces copy.
+
+**Pros:**
+- Workspaces fully independent
+- Can diverge per-workspace if needed
+- No build system changes
+- Simple mental model
+
+**Cons:**
+- Ongoing duplication
+- Manual sync required
+- Disk space (minimal impact)
+- Bug fixes need multi-workspace updates
+
+---
+
+## Recommendation Matrix
+
+| Criteria | Opt 1 | Opt 2 | Opt 3 | Opt 4 | Opt 5 |
+|----------|-------|-------|-------|-------|-------|
+| No duplication | ✓ | ✓ | ✗ | ✓ | ✗ |
+| Workspace isolation | ✗ | ✗ | ✓ | ✗ | ✓ |
+| Cross-platform | ✓ | ✗ | ✓ | ✓ | ✓ |
+| Low complexity | ✗ | ✓ | ✗ | ✗ | ✓ |
+| Easy maintenance | ✓ | ✓ | ✗ | ✓ | ✗ |
+
+---
+
+## Current Implementation Details
+
+### How Shaders Are Currently Included
+
+**In WGSL files:**
+```wgsl
+#include "common_uniforms"
+#include "math/sdf_shapes"
+#include "render/shadows"
+```
+
+**In C++ (shaders.cc):**
+```cpp
+void InitShaderComposer() {
+  auto& sc = ShaderComposer::Get();
+  sc.RegisterSnippet("common_uniforms", ...);
+  sc.RegisterSnippet("math/sdf_shapes", ...);
+  sc.RegisterSnippet("render/shadows", ...);
+}
+```
+
+**Asset Registration (assets.txt):**
+```
+SHADER_MATH_SDF_SHAPES, NONE, shaders/math/sdf_shapes.wgsl
+SHADER_RENDER_SHADOWS, NONE, shaders/render/shadows.wgsl
+```
+
+### ShaderComposer Flow
+1. Assets loaded from workspace `assets.txt`
+2. Snippets registered in `InitShaderComposer()`
+3. Effects call `Compose()` with dependencies
+4. `#include` directives recursively resolved
+5. Final shader string assembled
+
+---
+
+## Next Steps
+
+1. **Decide on approach** based on project priorities:
+   - Simplicity → Option 5
+   - True reuse → Option 1 or 4
+   - Compatibility → Option 3
+
+2. **If Option 1 chosen:**
+   - Create `/common/shaders/` with canonical sources
+   - Update `workspace.cfg` to reference common
+   - Update asset packer to resolve `../common/` paths
+   - Update docs
+
+3. **If Option 3 chosen:**
+   - Create sync script in `scripts/`
+   - Add to build process
+   - Document workflow
+
+4. **If Option 5 chosen:**
+   - Create `/common/shaders/` as templates
+   - Add `doc/SHADER_COMMON.md` explaining pattern
+   - Accept duplication as intentional