feat(cnn_v3): shadow→dif migration complete (ch18)

Replace raw shadow (ch18) with dif = max(0,dot(normal,KEY_LIGHT))*shadow
across all layers. Channel count stays 20, weight shapes unchanged.

- gbuf_pack.wgsl: t1.z = pack4x8unorm(mip2.g, mip2.b, dif, transp); t1.w = 0u
- gbuf_deferred.wgsl: read dif from unpack4x8unorm(t1.z).z
- gbuf_view.wgsl: revert to 4×5 grid, ch18=dif label, ch19=trns label
- tools/shaders.js: FULL_PACK_SHADER adds oct_decode + computes dif
- cnn_v3_utils.py: assemble_features() computes dif on-the-fly via oct_decode
- docs: CNN_V3.md, HOWTO.md, HOW_TO_CNN.md, GBUF_DIF_MIGRATION.md updated

handoff(Gemini): shadow→dif migration done, ready for first training pass

1 files changed, 9 insertions, 7 deletions

diff --git a/cnn_v3/docs/CNN_V3.md b/cnn_v3/docs/CNN_V3.md
index 3f8f7db..f86aa5a 100644
--- a/cnn_v3/docs/CNN_V3.md
+++ b/cnn_v3/docs/CNN_V3.md
@@ -156,7 +156,7 @@ Depth gradient captures surface discontinuities and orientation cues for the CNN
 |-----|--------|--------|--------|--------|
 | [0] | mat_id | prev.r | prev.g | prev.b |
 | [1] | mip1.r | mip1.g | mip1.b | mip2.r |
-| [2] | mip2.g | mip2.b | shadow | transp. |
+| [2] | mip2.g | mip2.b | dif | transp. |
 | [3] | — spare — | | | |
 
 All packed via `pack4x8unorm`. Channels:
@@ -164,7 +164,7 @@ All packed via `pack4x8unorm`. Channels:
 - **prev.rgb**: previous CNN output (temporal feedback, recurrent)
 - **mip1.rgb**: albedo at MIP 1 (½ resolution) — medium-frequency color context
 - **mip2.rgb**: albedo at MIP 2 (¼ resolution) — low-frequency color context
-- **shadow**: shadow intensity [0=fully shadowed, 1=fully lit] from shadow pass
+- **dif**: pre-multiplied occluded diffuse = `max(0, dot(normal, KEY_LIGHT)) * shadow` [0=dark, 1=fully lit]
 - **transp.**: volumetric transparency [0=opaque, 1=transparent] for fog/smoke/volumetric light
 
 **Texture 1 is fully packed. u32[3] is reserved for future use.**
@@ -188,6 +188,8 @@ fn pack_features(@builtin(global_invocation_id) id: vec3u) {
   let transp = textureLoad(gbuf_transp, coord, 0).r;
   let mat_id = unpack_mat_id(nm);            // u8 from rg16float packing
   let normal = unpack_oct_normal(nm.rg);     // vec2f
+  let nor3   = oct_decode(normal);           // vec3f unit normal
+  let dif    = max(0.0, dot(nor3, KEY_LIGHT)) * shadow;  // ch18
 
   let mip1 = textureSampleLevel(gbuf_albedo, smplr, uv, 1.0).rgb;
   let mip2 = textureSampleLevel(gbuf_albedo, smplr, uv, 2.0).rgb;
@@ -202,7 +204,7 @@ fn pack_features(@builtin(global_invocation_id) id: vec3u) {
   textureStore(feat_tex1, coord, vec4u(
     pack4x8unorm(vec4(mat_id, prev.r,  prev.g,  prev.b)),
     pack4x8unorm(vec4(mip1.r, mip1.g,  mip1.b,  mip2.r)),
-    pack4x8unorm(vec4(mip2.g, mip2.b,  shadow,  transp)),
+    pack4x8unorm(vec4(mip2.g, mip2.b,  dif,     transp)),
     0u,
   ));
 }
@@ -232,7 +234,7 @@ fn pack_features(@builtin(global_invocation_id) id: vec3u) {
 | 15 | mip2.r | u8 | Albedo MIP 2 (¼ res) |
 | 16 | mip2.g | u8 | |
 | 17 | mip2.b | u8 | |
-| 18 | shadow | u8 | Shadow intensity [0=dark, 1=lit] |
+| 18 | dif | u8 | max(0,dot(normal,KEY_LIGHT))×shadow [0=dark, 1=lit] |
 | 19 | transp. | u8 | Volumetric transparency [0=opaque, 1=clear] |
 
 UV computed in-shader. Bias = 1.0 implicit (standard NN, not stored).
@@ -244,7 +246,7 @@ Plus prev_cnn texture (RGBA8): **8 MB**.
 
 ### 16-byte fallback (budget-constrained)
 
-Drop temporal, MIPs, shadow, transparency. Geometric data only:
+Drop temporal, MIPs, dif, transparency. Geometric data only:
 
 | u32 | channels |
 |-----|----------|
@@ -436,7 +438,7 @@ Missing channels are **zero-filled** — the network degrades gracefully due to
 | prev.rgb | **0, 0, 0** (no history) |
 | mip1.rgb | Computed from photo (pyrDown ×1) |
 | mip2.rgb | Computed from photo (pyrDown ×2) |
-| shadow | **1.0** (assume fully lit) |
+| dif | **1.0** (assume fully lit; no normal/shadow data) |
 | transp. | **1 − alpha** (from photo alpha channel, or 0 if no alpha) |
 
 mip1/mip2 are still meaningful (they come from albedo, which we have).
@@ -464,7 +466,7 @@ Applied per-sample during dataloader `__getitem__`:
 
 ```python
 GEOMETRIC_CHANNELS = [3, 4, 5, 6, 7]   # normal.xy, depth, depth_grad.xy
-CONTEXT_CHANNELS   = [8, 18, 19]        # mat_id, shadow, transp
+CONTEXT_CHANNELS   = [8, 18, 19]        # mat_id, dif, transp
 TEMPORAL_CHANNELS  = [9, 10, 11]        # prev.rgb
 
 def apply_channel_dropout(feat, p_geom=0.3, p_context=0.2, p_temporal=0.5):