# ============================================
# TIER 1: CRITICAL CONTEXT (Always Loaded)
# ============================================
@PROJECT_CONTEXT.md
@TODO.md
@README.md

# ============================================
# TIER 2: TECHNICAL REFERENCE (Always Loaded)
# ============================================
@doc/HOWTO.md
@doc/CONTRIBUTING.md
@doc/AI_RULES.md

# ============================================
# TIER 3: DESIGN DOCS (Load On-Demand)
# ============================================
# Load these only when working on specific subsystems:
#
# Audio & Tracker:
#   @doc/SPEC_EDITOR.md - Spectral editor design
#   @doc/TRACKER.md - Audio tracker system
#   @doc/ANALYSIS_VARIABLE_TEMPO_V2.md - Variable tempo analysis
#
# 3D & Graphics:
#   @doc/3D.md - 3D rendering architecture
#   @doc/PROCEDURAL.md - Procedural generation
#
# Build & Assets:
#   @doc/ASSET_SYSTEM.md - Asset pipeline details
#   @doc/BUILD.md - Build system details
#   @doc/FETCH_DEPS.md - Dependency management
#
# Testing & Tools:
#   @doc/test_demo_README.md - test_demo tool documentation

# ============================================
# TIER 4: HISTORICAL ARCHIVE (Load Rarely)
# ============================================
# Load these only for historical context or debugging:
#
# Completion History:
#   @doc/COMPLETED.md - Detailed milestone history
#
# Technical Investigations:
#   @doc/GPU_EFFECTS_TEST_ANALYSIS.md
#   @doc/PLATFORM_ANALYSIS.md
#   @doc/PLATFORM_SIDE_QUEST_SUMMARY.md
#   @doc/PEAK_FIX_SUMMARY.md
#
# Agent Handoffs:
#   @doc/HANDOFF_CLAUDE.md
#   @doc/HANDOFF.md
#   @doc/HANDOFF_2026-02-04.md
#
# Task Tracking:
#   @doc/TASKS_SUMMARY.md

# ============================================
# PROJECT RULES (IMPORTANT)
# ============================================

IMPORTANT:
- Follow all rules in doc/AI_RULES.md
- This repository is shared with Claude-Code
- You are working in turns with another AI agent
- Work only on tasks explicitly requested by the user
- Do NOT modify files outside the current scope
- Do NOT perform refactors or cleanups unless explicitly asked

# Context Maintenance:
- See @doc/CONTEXT_MAINTENANCE.md for keeping context clean
- Archive completed work to doc/COMPLETED.md regularly
- Keep PROJECT_CONTEXT.md focused on current status
- Keep TODO.md focused on active/next tasks only

# ============================================
# CURRENT STATE SNAPSHOT (Gemini-Specific)
# ============================================
<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 CPU-side SDF library and BVH construction for physics acceleration.
        - Implemented PhysicsSystem with semi-implicit Euler integration and SDF-based collision resolution.
        - Integrated physics and BVH visualization into test_3d_render.
        - Verified physics stability with new test_physics unit test suite.
    </recent_actions>

    <task_state>
        1. [DONE] Task #50: WGSL Modularization (Infrastructure and initial refactor).
        2. [DONE] Task #49: Physics &amp; Collision (CPU SDF Lib, BVH Builder, Euler Solver).
        3. [NEXT] Task #18: 3D System Enhancements (Blender Export, Binary Format). <-- CURRENT FOCUS
        4. [TODO] Task #36: Blender Exporter (Binary scene export).
        5. [TODO] Task #39: Visual Debugging System (BVH and Physics visualization).
    </task_state>
</state_snapshot>