1 files changed, 82 insertions, 0 deletions
diff --git a/SHADER_REFACTOR_EXAMPLE.md b/SHADER_REFACTOR_EXAMPLE.md
new file mode 100644
index 0000000..c875c7e
--- /dev/null
+++ b/SHADER_REFACTOR_EXAMPLE.md
@@ -0,0 +1,82 @@
+# Shader Composability Improvement
+
+## Created: `math/common_utils.wgsl`
+
+Common utility functions to reduce duplication:
+- `transform_normal()` - Normal matrix transform (was in 2 shaders)
+- `spherical_uv()` - Spherical UV mapping (was in 7+ places)
+- `spherical_uv_from_dir()` - For skybox/direction vectors
+- `calc_sdf_normal_bumped()` - Bump-mapped normal (36 lines → 1 call)
+- Constants: `PI`, `TAU`
+
+## Usage in Shaders
+
+### Bump Mapping Note:
+`calc_sdf_normal_bumped()` was removed from common_utils - too specialized, depends on `get_dist()` from scene_query snippets. Keep bump mapping inline in shaders that use it.
+
+### Transform Normal (appears in renderer_3d.wgsl:174, mesh_render.wgsl:38):
+```wgsl
+// Before
+let normal_matrix = mat3x3<f32>(obj.inv_model[0].xyz, obj.inv_model[1].xyz, obj.inv_model[2].xyz);
+normal = normalize(normal_matrix * n_local);
+
+// After (if common_utils included)
+normal = transform_normal(obj.inv_model, n_local);
+```
+
+### Spherical UV (appears 6x in renderer_3d.wgsl):
+```wgsl
+// Before
+let uv = vec2<f32>(atan2(q.x, q.z) / 6.28 + 0.5,
+                   acos(clamp(q.y / length(q), -1.0, 1.0)) / 3.14);
+
+// After
+let uv = spherical_uv(q);
+```
+
+### Skybox (skybox.wgsl:41-42):
+```wgsl
+// Before
+let u = atan2(ray_dir.z, ray_dir.x) / 6.28318 + 0.5;
+let v = asin(clamp(ray_dir.y, -1.0, 1.0)) / 3.14159 + 0.5;
+
+// After
+let uv = spherical_uv_from_dir(ray_dir);
+```
+
+## Integration with ShaderComposer
+
+ShaderComposer already supports `#include` directives. To use:
+
+```cpp
+// In gpu/effects initialization
+ShaderComposer::Get().RegisterSnippet(
+    "math/common_utils",
+    GetAssetString(AssetId::SHADER_MATH_COMMON_UTILS)
+);
+
+// In shader composition
+composer.Compose(
+    {"common_uniforms", "math/common_utils"},
+    main_shader_code
+);
+```
+
+## Size Impact
+
+**Estimated binary size change:**
+- Add common_utils.wgsl: +800 bytes
+- Remove duplication: -1500 bytes (6 spherical_uv + bump mapping)
+- **Net savings: ~700 bytes**
+
+Plus improved maintainability and consistency.
+
+## Next Steps
+
+1. Refactor `renderer_3d.wgsl` to use new utilities
+2. Refactor `skybox.wgsl` to use `spherical_uv_from_dir()`
+3. Refactor `mesh_render.wgsl` to use `transform_normal()`
+4. Consider extracting more patterns:
+   - Grid pattern (appears 2x)
+   - Light direction constant
+   - Ray-box intersection variants