refactor: move common/shaders/ to src/shaders/

Relocates shared WGSL shaders under src/ where all source code lives,
eliminating the top-level common/ directory.

- Update asset references in workspaces/main/assets.txt and workspaces/test/assets.txt
- Update docs: PROJECT_CONTEXT.md, ARCHITECTURE.md, WORKSPACE_SYSTEM.md, SHADER_REUSE_INVESTIGATION.md

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

6 files changed, 379 insertions, 0 deletions

diff --git a/src/shaders/math/color.wgsl b/src/shaders/math/color.wgsl
new file mode 100644
index 0000000..9352053
--- /dev/null
+++ b/src/shaders/math/color.wgsl
@@ -0,0 +1,27 @@
+// Common color space and tone mapping functions.
+
+// sRGB to Linear approximation
+// Note: Assumes input is in sRGB color space.
+fn sRGB(t: vec3f) -> vec3f {
+  return mix(1.055 * pow(t, vec3f(1.0/2.4)) - 0.055, 12.92 * t, step(t, vec3f(0.0031308)));
+}
+
+// ACES Filmic Tone Mapping (Approximate)
+// A common tone mapping algorithm used in games and film.
+fn aces_approx(v_in: vec3f) -> vec3f {
+  var v = max(v_in, vec3f(0.0));
+  v *= 0.6;
+  let a = 2.51;
+  let b = 0.03;
+  let c = 2.43;
+  let d = 0.59;
+  let e = 0.14;
+  return clamp((v * (a * v + b)) / (v * (c * v + d) + e), vec3f(0.0), vec3f(1.0));
+}
+
+// HSV to RGB conversion
+const hsv2rgb_K = vec4f(1.0, 2.0 / 3.0, 1.0 / 3.0, 3.0);
+fn hsv2rgb(c: vec3f) -> vec3f {
+  let p = abs(fract(c.xxx + hsv2rgb_K.xyz) * 6.0 - hsv2rgb_K.www);
+  return c.z * mix(hsv2rgb_K.xxx, clamp(p - hsv2rgb_K.xxx, vec3f(0.0), vec3f(1.0)), c.y);
+}
diff --git a/src/shaders/math/common_utils.wgsl b/src/shaders/math/common_utils.wgsl
new file mode 100644
index 0000000..6ebc25a
--- /dev/null
+++ b/src/shaders/math/common_utils.wgsl
@@ -0,0 +1,46 @@
+// Common utility functions for WGSL shaders.
+// Reduces duplication across renderer_3d, mesh_render, etc.
+
+// Constants
+const PI: f32 = 3.14159265359;
+const TAU: f32 = 6.28318530718;
+
+// Transform normal from local to world space using inverse model matrix
+fn transform_normal(inv_model: mat4x4f, normal_local: vec3f) -> vec3f {
+    let normal_matrix = mat3x3f(inv_model[0].xyz, inv_model[1].xyz, inv_model[2].xyz);
+    return normalize(normal_matrix * normal_local);
+}
+
+// Spherical UV mapping (sphere or any radial surface)
+// Returns UV in [0,1] range
+fn spherical_uv(p: vec3f) -> vec2f {
+    let u = atan2(p.x, p.z) / TAU + 0.5;
+    let v = acos(clamp(p.y / length(p), -1.0, 1.0)) / PI;
+    return vec2f(u, v);
+}
+
+// Spherical UV from direction vector (for skybox, etc.)
+fn spherical_uv_from_dir(dir: vec3f) -> vec2f {
+    let u = atan2(dir.z, dir.x) / TAU + 0.5;
+    let v = asin(clamp(dir.y, -1.0, 1.0)) / PI + 0.5;
+    return vec2f(u, v);
+}
+
+// Grid pattern for procedural texturing (checkerboard-like)
+fn grid_pattern(uv: vec2f) -> f32 {
+    let grid = 0.5 + 0.5 * sin(uv.x * PI) * sin(uv.y * PI);
+    return smoothstep(0.45, 0.55, grid);
+}
+
+// NOTE: calc_sdf_normal_bumped() removed - too specialized, depends on get_dist()
+// from scene_query snippets. Keep bump mapping code inline in shaders that use it.
+
+// Calculates normalized screen coordinates from fragment position and resolution.
+// Input `p` is the fragment's @builtin(position), `resolution` is the screen resolution.
+// Returns a vec2f in NDC space, with X adjusted for aspect ratio.
+fn getScreenCoord(p: vec4f, resolution: vec2f) -> vec2f {
+    let q = p.xy / resolution;
+    var coord = -1.0 + 2.0 * q;
+    coord.x *= resolution.x / resolution.y;
+    return coord;
+}
diff --git a/src/shaders/math/noise.wgsl b/src/shaders/math/noise.wgsl
new file mode 100644
index 0000000..dd97e02
--- /dev/null
+++ b/src/shaders/math/noise.wgsl
@@ -0,0 +1,147 @@
+// Random number generation and noise functions for WGSL shaders.
+// Collection of hash functions and noise generators.
+
+// ============================================
+// Hash Functions (Float Input)
+// ============================================
+
+// Hash: f32 -> f32
+// Fast fractional hash for floats
+fn hash_1f(x: f32) -> f32 {
+  var v = fract(x * 0.3351);
+  v *= v + 33.33;
+  v *= v + v;
+  return fract(v);
+}
+
+// Hash: vec2f -> f32
+// 2D coordinate to single hash value
+fn hash_2f(p: vec2f) -> f32 {
+  var h = dot(p, vec2f(127.1, 311.7));
+  return fract(sin(h) * 43758.5453123);
+}
+
+// Hash: vec2f -> vec2f
+// 2D coordinate to 2D hash (from Shadertoy 4djSRW)
+fn hash_2f_2f(p: vec2f) -> vec2f {
+  var p3 = fract(vec3f(p.x, p.y, p.x) * vec3f(0.1021, 0.1013, 0.0977));
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.xx + p3.yz) * p3.zy);
+}
+
+// Hash: vec3f -> f32
+// 3D coordinate to single hash value
+fn hash_3f(p: vec3f) -> f32 {
+  var h = dot(p, vec3f(127.1, 311.7, 74.7));
+  return fract(sin(h) * 43758.5453123);
+}
+
+// Hash: vec3f -> vec3f
+// 3D coordinate to 3D hash
+fn hash_3f_3f(p: vec3f) -> vec3f {
+  var v = fract(p);
+  v += dot(v, v.yxz + 32.41);
+  return fract((v.xxy + v.yzz) * v.zyx);
+}
+
+// ============================================
+// Hash Functions (Integer Input)
+// ============================================
+
+// Hash: u32 -> f32
+// Integer hash with bit operations (high quality)
+fn hash_1u(p: u32) -> f32 {
+  var P = (p << 13u) ^ p;
+  P = P * (P * P * 15731u + 789221u) + 1376312589u;
+  return bitcast<f32>((P >> 9u) | 0x3f800000u) - 1.0;
+}
+
+// Hash: u32 -> vec2f
+fn hash_1u_2f(p: u32) -> vec2f {
+  return vec2f(hash_1u(p), hash_1u(p + 1423u));
+}
+
+// Hash: u32 -> vec3f
+fn hash_1u_3f(p: u32) -> vec3f {
+  return vec3f(hash_1u(p), hash_1u(p + 1423u), hash_1u(p + 124453u));
+}
+
+// ============================================
+// Noise Functions
+// ============================================
+
+// Value Noise: 2D
+// Interpolated grid noise using smoothstep
+fn noise_2d(p: vec2f) -> f32 {
+  let i = floor(p);
+  let f = fract(p);
+  let u = f * f * (3.0 - 2.0 * f);
+  let n0 = hash_2f(i + vec2f(0.0, 0.0));
+  let n1 = hash_2f(i + vec2f(1.0, 0.0));
+  let n2 = hash_2f(i + vec2f(0.0, 1.0));
+  let n3 = hash_2f(i + vec2f(1.0, 1.0));
+  let ix0 = mix(n0, n1, u.x);
+  let ix1 = mix(n2, n3, u.x);
+  return mix(ix0, ix1, u.y);
+}
+
+// Value Noise: 3D
+fn noise_3d(p: vec3f) -> f32 {
+  let i = floor(p);
+  let f = fract(p);
+  let u = f * f * (3.0 - 2.0 * f);
+  let n000 = hash_3f(i + vec3f(0.0, 0.0, 0.0));
+  let n100 = hash_3f(i + vec3f(1.0, 0.0, 0.0));
+  let n010 = hash_3f(i + vec3f(0.0, 1.0, 0.0));
+  let n110 = hash_3f(i + vec3f(1.0, 1.0, 0.0));
+  let n001 = hash_3f(i + vec3f(0.0, 0.0, 1.0));
+  let n101 = hash_3f(i + vec3f(1.0, 0.0, 1.0));
+  let n011 = hash_3f(i + vec3f(0.0, 1.0, 1.0));
+  let n111 = hash_3f(i + vec3f(1.0, 1.0, 1.0));
+  let ix00 = mix(n000, n100, u.x);
+  let ix10 = mix(n010, n110, u.x);
+  let ix01 = mix(n001, n101, u.x);
+  let ix11 = mix(n011, n111, u.x);
+  let iy0 = mix(ix00, ix10, u.y);
+  let iy1 = mix(ix01, ix11, u.y);
+  return mix(iy0, iy1, u.z);
+}
+
+// ============================================
+// Special Functions
+// ============================================
+
+// Gyroid function (periodic triply-orthogonal minimal surface)
+// Useful for procedural patterns and cellular structures
+fn gyroid(p: vec3f) -> f32 {
+  return abs(0.04 + dot(sin(p), cos(p.zxy)));
+}
+
+// Fractional Brownian Motion (FBM) 2D
+// Multi-octave noise for natural-looking variation
+fn fbm_2d(p: vec2f, octaves: i32) -> f32 {
+  var value = 0.0;
+  var amplitude = 0.5;
+  var frequency = 1.0;
+  var pos = p;
+  for (var i = 0; i < octaves; i++) {
+    value += amplitude * noise_2d(pos * frequency);
+    frequency *= 2.0;
+    amplitude *= 0.5;
+  }
+  return value;
+}
+
+// Fractional Brownian Motion (FBM) 3D
+fn fbm_3d(p: vec3f, octaves: i32) -> f32 {
+  var value = 0.0;
+  var amplitude = 0.5;
+  var frequency = 1.0;
+  var pos = p;
+  for (var i = 0; i < octaves; i++) {
+    value += amplitude * noise_3d(pos * frequency);
+    frequency *= 2.0;
+    amplitude *= 0.5;
+  }
+  return value;
+}
diff --git a/src/shaders/math/sdf_shapes.wgsl b/src/shaders/math/sdf_shapes.wgsl
new file mode 100644
index 0000000..2dfae3e
--- /dev/null
+++ b/src/shaders/math/sdf_shapes.wgsl
@@ -0,0 +1,30 @@
+// 3D SDF primitives
+fn sdSphere(p: vec3f, r: f32) -> f32 {
+    return length(p) - r;
+}
+
+fn sdBox(p: vec3f, b: vec3f) -> f32 {
+    let q = abs(p) - b;
+    return length(max(q, vec3f(0.0))) + min(max(q.x, max(q.y, q.z)), 0.0);
+}
+
+fn sdTorus(p: vec3f, t: vec2f) -> f32 {
+    let q = vec2f(length(p.xz) - t.x, p.y);
+    return length(q) - t.y;
+}
+
+fn sdPlane(p: vec3f, n: vec3f, h: f32) -> f32 {
+    return dot(p, n) + h;
+}
+
+// 2D SDF primitives
+fn sdBox2D(p: vec2f, b: vec2f) -> f32 {
+    let d = abs(p) - b;
+    return length(max(d, vec2f(0.0))) + min(max(d.x, d.y), 0.0);
+}
+
+// Approximate
+fn sdEllipse(p: vec2f, ab: vec2f) -> f32 {
+    let d = length(p / ab);
+    return length(p) * (1.0 - 1.0 / d);
+}
diff --git a/src/shaders/math/sdf_utils.wgsl b/src/shaders/math/sdf_utils.wgsl
new file mode 100644
index 0000000..5a77c7e
--- /dev/null
+++ b/src/shaders/math/sdf_utils.wgsl
@@ -0,0 +1,115 @@
+fn get_normal_basic(p: vec3f, obj_params: vec4f) -> vec3f {
+    let obj_type = obj_params.x;
+    if (obj_type == 1.0) { return normalize(p); }
+    let e = vec2f(0.001, 0.0);
+    return normalize(vec3f(
+        get_dist(p + e.xyy, obj_params) - get_dist(p - e.xyy, obj_params),
+        get_dist(p + e.yxy, obj_params) - get_dist(p - e.yxy, obj_params),
+        get_dist(p + e.yyx, obj_params) - get_dist(p - e.yyx, obj_params)
+    ));
+}
+
+// Optimized normal estimation using tetrahedron pattern (4 SDF evals instead of 6).
+// Slightly less accurate than central differences but faster.
+// Uses tetrahedral gradient approximation with corners at (±1, ±1, ±1).
+fn get_normal_fast(p: vec3f, obj_params: vec4f) -> vec3f {
+    let obj_type = obj_params.x;
+    if (obj_type == 1.0) { return normalize(p); }
+    let eps = 0.0001;
+    let k = vec2f(1.0, -1.0);
+    return normalize(
+        k.xyy * get_dist(p + k.xyy * eps, obj_params) +
+        k.yyx * get_dist(p + k.yyx * eps, obj_params) +
+        k.yxy * get_dist(p + k.yxy * eps, obj_params) +
+        k.xxx * get_dist(p + k.xxx * eps, obj_params)
+    );
+}
+
+// Bump-mapped normal using central differences (6 samples: SDF + texture).
+// High quality, suitable for detailed surfaces with displacement mapping.
+// Note: Requires spherical_uv() function and get_dist() to be available in calling context.
+fn get_normal_bump(
+    p: vec3f,
+    obj_params: vec4f,
+    noise_tex: texture_2d<f32>,
+    noise_sampler: sampler,
+    disp_strength: f32
+) -> vec3f {
+    let e = vec2f(0.005, 0.0);
+
+    let q_x1 = p + e.xyy;
+    let uv_x1 = spherical_uv(q_x1);
+    let h_x1 = textureSample(noise_tex, noise_sampler, uv_x1).r;
+    let d_x1 = get_dist(q_x1, obj_params) - disp_strength * h_x1;
+
+    let q_x2 = p - e.xyy;
+    let uv_x2 = spherical_uv(q_x2);
+    let h_x2 = textureSample(noise_tex, noise_sampler, uv_x2).r;
+    let d_x2 = get_dist(q_x2, obj_params) - disp_strength * h_x2;
+
+    let q_y1 = p + e.yxy;
+    let uv_y1 = spherical_uv(q_y1);
+    let h_y1 = textureSample(noise_tex, noise_sampler, uv_y1).r;
+    let d_y1 = get_dist(q_y1, obj_params) - disp_strength * h_y1;
+
+    let q_y2 = p - e.yxy;
+    let uv_y2 = spherical_uv(q_y2);
+    let h_y2 = textureSample(noise_tex, noise_sampler, uv_y2).r;
+    let d_y2 = get_dist(q_y2, obj_params) - disp_strength * h_y2;
+
+    let q_z1 = p + e.yyx;
+    let uv_z1 = spherical_uv(q_z1);
+    let h_z1 = textureSample(noise_tex, noise_sampler, uv_z1).r;
+    let d_z1 = get_dist(q_z1, obj_params) - disp_strength * h_z1;
+
+    let q_z2 = p - e.yyx;
+    let uv_z2 = spherical_uv(q_z2);
+    let h_z2 = textureSample(noise_tex, noise_sampler, uv_z2).r;
+    let d_z2 = get_dist(q_z2, obj_params) - disp_strength * h_z2;
+
+    return normalize(vec3f(d_x1 - d_x2, d_y1 - d_y2, d_z1 - d_z2));
+}
+
+// Optimized bump-mapped normal using tetrahedron pattern (4 samples instead of 6).
+// 33% faster than get_normal_bump(), slightly less accurate.
+// Suitable for real-time rendering with displacement mapping.
+fn get_normal_bump_fast(
+    p: vec3f,
+    obj_params: vec4f,
+    noise_tex: texture_2d<f32>,
+    noise_sampler: sampler,
+    disp_strength: f32
+) -> vec3f {
+    let eps = 0.0005;
+    let k = vec2f(1.0, -1.0);
+
+    let q1 = p + k.xyy * eps;
+    let uv1 = spherical_uv(q1);
+    let h1 = textureSample(noise_tex, noise_sampler, uv1).r;
+    let d1 = get_dist(q1, obj_params) - disp_strength * h1;
+
+    let q2 = p + k.yyx * eps;
+    let uv2 = spherical_uv(q2);
+    let h2 = textureSample(noise_tex, noise_sampler, uv2).r;
+    let d2 = get_dist(q2, obj_params) - disp_strength * h2;
+
+    let q3 = p + k.yxy * eps;
+    let uv3 = spherical_uv(q3);
+    let h3 = textureSample(noise_tex, noise_sampler, uv3).r;
+    let d3 = get_dist(q3, obj_params) - disp_strength * h3;
+
+    let q4 = p + k.xxx * eps;
+    let uv4 = spherical_uv(q4);
+    let h4 = textureSample(noise_tex, noise_sampler, uv4).r;
+    let d4 = get_dist(q4, obj_params) - disp_strength * h4;
+
+    return normalize(k.xyy * d1 + k.yyx * d2 + k.yxy * d3 + k.xxx * d4);
+}
+
+// Distance to an Axis-Aligned Bounding Box
+fn aabb_sdf(p: vec3f, min_p: vec3f, max_p: vec3f) -> f32 {
+    let center = (min_p + max_p) * 0.5;
+    let extent = (max_p - min_p) * 0.5;
+    let q = abs(p - center) - extent;
+    return length(max(q, vec3f(0.0))) + min(max(q.x, max(q.y, q.z)), 0.0);
+}
diff --git a/src/shaders/math/utils.wgsl b/src/shaders/math/utils.wgsl
new file mode 100644
index 0000000..c75cb66
--- /dev/null
+++ b/src/shaders/math/utils.wgsl
@@ -0,0 +1,14 @@
+// General-purpose math utility functions.
+
+// Returns a 2x2 rotation matrix.
+fn rot(a: f32) -> mat2x2f {
+  let c = cos(a);
+  let s = sin(a);
+  return mat2x2f(c, s, -s, c);
+}
+
+// Fast approximation of tanh.
+fn tanh_approx(x: f32) -> f32 {
+  let x2 = x * x;
+  return clamp(x * (27.0 + x2) / (27.0 + 9.0 * x2), -1.0, 1.0);
+}