docs: Handoff state snapshot with WebGPU fixes

1 files changed, 55 insertions, 2 deletions

diff --git a/GEMINI.md b/GEMINI.md
index af6e282..6d92c0b 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -3,7 +3,6 @@
 @TODO.md
 
 # helping and quick-start tutorials
-
 @README.md
 @doc/HOWTO.md
 
@@ -20,7 +19,61 @@
 @doc/CONTRIBUTING.md
 @doc/AI_RULES.md
 
+# Current State Snapshot
+<state_snapshot>
+    <overall_goal>
+        Evolve the demo into a robust 3D engine with dynamic physics, BVH acceleration, and a modular shader architecture, targeting a 64k binary limit.
+    </overall_goal>
+
+    <active_constraints>
+        - **Skybox Pipeline**: Requires `depthWriteEnabled = WGPUOptionalBool_False` and `depthCompare = WGPUCompareFunction_Always` for Pass 1.
+        - **Asset Safety**: All assets must use `alignas(16)` and a null-terminator for safe C-string/float casting.
+        - **BVH Alignment**: `BVHNode` must be 32-byte aligned for GPU efficiency.
+        - **WGSL Traversal**: BVH traversal in shaders must be stack-based (no recursion allowed).
+        - **SDF Scale Safety**: `map_scene` must use conservative minimum scale (`min(scale_x, min(scale_y, scale_z))`) to prevent distance field overstepping.
+        - **WGPU String Safety**: On macOS/Darwin, dynamically composed shader strings MUST use the `str_view()` helper to ensure `WGPUStringView` compatibility (passing pointer AND length) to prevent validation errors.
+        - **Shader Modularization**: Use `#include "snippet_name"` in WGSL. Snippet names must match keys registered in `InitShaderComposer` (case-sensitive, usually folder/name without extension).
+        - **Platform Defines**: `CMakeLists.txt` MUST include platform-specific defines (e.g., `-DGLFW_EXPOSE_NATIVE_COCOA`) for `glfw3webgpu` to function.
+        - **Render Pass Config**: `WGPUSurfaceConfiguration` must have `usage = WGPUTextureUsage_RenderAttachment` to avoid validation errors.
+        - **Render Pass Init**: `WGPURenderPassColorAttachment` structs must have unused fields (like `resolveTarget`) explicitly set to `nullptr` to avoid validation errors.
+    </active_constraints>
+
+    <key_knowledge>
+        - **ShaderComposer**: Singleton using `std::map&lt;std::string, std::string&gt;` for snippets; `Compose` supports recursive resolution and cycle detection via `std::set`.
+        - **BVH Construction**: Rebuilt every frame on CPU via recursive midpoint split along the axis of largest variance; linearized into a `std::vector&lt;BVHNode&gt;`.
+        - **Mac-Specific WGPU**: `WGPUShaderSourceWGSL` in the current header version expects a `WGPUStringView` struct for the `code` field, not a raw pointer.
+        - **Physics Strategy**: "Proxy Point Probing" uses object corners/center as probes tested against neighbor analytical SDFs for narrow-phase resolution and normal calculation.
+    </key_knowledge>
+
+    <artifact_trail>
+        - `src/gpu/effects/shader_composer.cc`: Implemented `ResolveRecursive` for `#include` support and added unit tests.
+        - `assets/final/shaders/math/`: Created `sdf_shapes.wgsl` (shapes) and `sdf_utils.wgsl` (normals).
+        - `assets/final/shaders/render/`: Created `shadows.wgsl`, `scene_query.wgsl` (`map_scene`), and `lighting_utils.wgsl` (lighting logic).
+        - `assets/final/demo_assets.txt`: Registered 5 new modular shader assets.
+        - `src/gpu/effects/shaders.cc`: Updated `InitShaderComposer` to register the new granular snippet library.
+        - `src/3d/renderer.cc`: Refactored `create_pipeline` and `create_skybox_pipeline` to use internal `#include` instead of C++ side dependency injection.
+        - `src/gpu/gpu.cc`: Fixed `g_surface` assertion and render pass validation errors by correcting initialization.
+        - `CMakeLists.txt`: Added platform-specific defines for `glfw3webgpu`.
+    </artifact_trail>
+
+    <recent_actions>
+        - Implemented recursive `#include` resolution in `ShaderComposer` with duplicate prevention.
+        - Modularized the 3D rendering WGSL codebase into reusable math and render snippets.
+        - Resolved a critical macOS shader compilation bug by using `str_view()` for composed shader modules.
+        - Verified the refactor with `test_3d_render` and `ctest` (100% pass rate).
+        - Fixed `demo64k` runtime crash (g_surface assertion) and validation errors (texture usage, view dimension) on macOS.
+    </recent_actions>
+
+    <task_state>
+        1. [DONE] Task #50: WGSL Modularization (Infrastructure and initial refactor).
+        2. [NEXT] Task #49: Physics &amp; Collision (CPU SDF Lib, BVH Builder, Euler Solver). <-- CURRENT FOCUS
+        3. [TODO] Task #18: 3D System Enhancements (Blender Export, Binary Format).
+        4. [TODO] Task #36: Blender Exporter (Binary scene export).
+        5. [TODO] Task #39: Visual Debugging System (BVH and Physics visualization).
+    </task_state>
+</state_snapshot>
+
 follow rules in AI_RULES.md !
 You are working in a repo shared with Claude-Code.
 Work only on the tasks explicitly requested.
-Do not modify files outside the current scope.
+Do not modify files outside the current scope.
\ No newline at end of file