Fix: Resolver crash de nullptr en Engine::initialize() y documentar facade pattern

PROBLEMA CRÍTICO RESUELTO:
- El programa compilaba pero crasheaba inmediatamente al ejecutar
- Stack trace apuntaba a UIManager::updatePhysicalWindowSize() (línea 135)
- Root cause: Engine::initialize() llamaba updatePhysicalWindowSize() en línea 228
  ANTES de crear ui_manager_ en línea 232 → nullptr dereference

SOLUCIÓN:
- Calcular tamaño físico de ventana inline sin llamar al método completo
- Usar SDL_GetWindowSizeInPixels() directamente antes de crear ui_manager_
- Pasar valores calculados a UIManager::initialize()

CAMBIOS ADICIONALES:
1. engine.h: Documentar duplicación pragmática Engine ↔ StateManager
   - Variables de estado DEMO/LOGO mantenidas temporalmente en Engine
   - StateManager mantiene current_app_mode_ (fuente de verdad)
   - Comentarios explicativos para futuras migraciones

2. shape_manager.cpp: Documentar facade pattern completo
   - Añadidos comentarios extensivos explicando stubs
   - Cada método stub documenta por qué Engine mantiene implementación
   - Clarifica dependencias (SceneManager, UIManager, notificaciones)

RESULTADO:
✅ Compilación exitosa (sin errores)
✅ Aplicación ejecuta sin crashes
✅ Inicialización de UIManager correcta
✅ Todos los recursos cargan apropiadamente

Archivos modificados:
- source/engine.cpp: Fix de inicialización (líneas 227-238)
- source/engine.h: Documentación de estado duplicado
- source/shapes_mgr/shape_manager.cpp: Documentación facade

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

source/engine.cpp

@@ -225,10 +225,15 @@ bool Engine::initialize(int width, int height, int zoom, bool fullscreen) {
         scene_manager_->initialize(0, texture_, theme_manager_.get());  // Escenario 0 (10 bolas) por defecto
 
         // Calcular tamaño físico de ventana ANTES de inicializar UIManager
-        updatePhysicalWindowSize();
+        // NOTA: No llamar a updatePhysicalWindowSize() aquí porque ui_manager_ aún no existe
+        // Calcular manualmente para poder pasar valores al constructor de UIManager
+        int window_w = 0, window_h = 0;
+        SDL_GetWindowSizeInPixels(window_, &window_w, &window_h);
+        physical_window_width_ = window_w;
+        physical_window_height_ = window_h;
 
         // Inicializar UIManager (HUD, FPS, notificaciones)
-        // NOTA: Debe llamarse DESPUÉS de updatePhysicalWindowSize() y ThemeManager
+        // NOTA: Debe llamarse DESPUÉS de calcular physical_window_* y ThemeManager
         ui_manager_ = std::make_unique<UIManager>();
         ui_manager_->initialize(renderer_, theme_manager_.get(), physical_window_width_, physical_window_height_);