diff --git a/.copilot-rules.md b/.copilot-rules.md
new file mode 100644
index 0000000..cafc1cc
--- /dev/null
+++ b/.copilot-rules.md
@@ -0,0 +1,168 @@
+# Copilot Rules — Spacetris (SDL3 / C++20)
+
+These rules define **non-negotiable constraints** for all AI-assisted changes.
+They exist to preserve determinism, performance, and architecture.
+
+If these rules conflict with `.github/copilot-instructions.md`,
+**follow `.github/copilot-instructions.md`.**
+
+---
+
+## Project Constraints (Non-Negotiable)
+
+- Language: **C++20**
+- Runtime: **SDL3** + **SDL3_ttf**
+- Build system: **CMake**
+- Dependencies via **vcpkg**
+- Assets must use **relative paths only**
+- Deterministic gameplay logic is mandatory
+
+Do not rewrite or refactor working systems unless explicitly requested.
+
+---
+
+## Repo Layout & Responsibilities
+
+- Core gameplay loop/state: `src/Game.*`
+- Entry point: `src/main.cpp`
+- Text/TTF: `src/Font.*`
+- Audio: `src/Audio.*`, `src/SoundEffect.*`
+- Effects: `src/LineEffect.*`, `src/Starfield*.cpp`
+- High scores: `src/Scores.*`
+- Packaging: `build-production.ps1`
+
+When adding a module:
+- Place it under `src/` (or an established subfolder)
+- Register it in `CMakeLists.txt`
+- Avoid circular includes
+- Keep headers minimal
+
+---
+
+## Build & Verification
+
+Prefer existing scripts:
+
+- Debug: `cmake --build build-msvc --config Debug`
+- Release:
+  - Configure: `cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release`
+  - Build: `cmake --build build-release --config Release`
+- Packaging (Windows): `./build-production.ps1`
+
+Before finalizing changes:
+- Debug build must succeed
+- Packaging must succeed if assets or DLLs are touched
+
+Do not introduce new build steps unless required.
+
+---
+
+## Coding & Architecture Rules
+
+- Match local file style (naming, braces, spacing)
+- Avoid large refactors
+- Prefer small, testable helpers
+- Avoid floating-point math in core gameplay state
+- Game logic must be deterministic
+- Rendering code must not mutate game state
+
+---
+
+## Rendering & Performance Rules
+
+- Do not allocate memory per frame
+- Do not load assets during rendering
+- No blocking calls in render loop
+- Visual effects must be time-based (`deltaTime`)
+- Rendering must not contain gameplay logic
+
+---
+
+## Threading Rules
+
+- SDL main thread:
+  - Rendering
+  - Input
+  - Game simulation
+- Networking must be **non-blocking** from the SDL main loop
+  - Either run networking on a separate thread, or poll ENet frequently with a 0 timeout
+  - Never wait/spin for remote inputs on the render thread
+- Cross-thread communication via queues or buffers only
+
+---
+
+## Assets, Fonts, and Paths
+
+- Runtime expects adjacent `assets/` directory
+- `FreeSans.ttf` must remain at repo root
+- New assets:
+  - Go under `assets/`
+  - Must be included in `build-production.ps1`
+
+Never hardcode machine-specific paths.
+
+---
+
+## AI Partner (COOPERATE Mode)
+
+- AI is **supportive**, not competitive
+- AI must respect sync timing and shared grid logic
+- AI must not “cheat” or see hidden future pieces
+- AI behavior must be deterministic per seed/difficulty
+
+---
+
+## Networking (COOPERATE Network Mode)
+
+Follow `docs/ai/cooperate_network.md`.
+If `network_cooperate_multiplayer.md` exists, keep it consistent with the canonical doc.
+
+Mandatory model:
+- **Input lockstep**
+- Transmit inputs only (no board state replication)
+
+Determinism requirements:
+- Fixed tick (e.g. 60 Hz)
+- Shared RNG seed
+- Deterministic gravity, rotation, locking, scoring
+
+Technology:
+- Use **ENet**
+- Do NOT use SDL_net or TCP-only networking
+
+Architecture:
+- Networking must be isolated (e.g. `src/network/NetSession.*`)
+- Game logic must not care if partner is local, AI, or network
+
+Robustness:
+- Input delay buffer (4–6 ticks)
+- Periodic desync hashing
+- Graceful disconnect handling
+
+Do NOT implement:
+- Rollback
+- Full state sync
+- Server-authoritative sim
+- Matchmaking SDKs
+- Versus mechanics
+
+---
+
+## Agent Behavior Rules (IMPORTANT)
+
+- Always read relevant markdown specs **before coding**
+- Treat markdown specs as authoritative
+- Do not invent APIs
+- Do not assume external libraries exist
+- Generate code **file by file**, not everything at once
+- Ask before changing architecture or ownership boundaries
+
+---
+
+## When to Ask Before Proceeding
+
+Ask the maintainer if unclear:
+- UX or menu flow decisions
+- Adding dependencies
+- Refactors vs local patches
+- Platform-specific behavior
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 351ae6b..8c9515b 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,4 +1,4 @@
-# Copilot Instructions — Tetris (C++ SDL3)
+# Copilot Instructions — Spacetris (C++ SDL3)
 
 Purpose: Speed up development on this native SDL3 Tetris. Follow these conventions to keep builds reproducible and packages shippable.
 
@@ -9,11 +9,9 @@ Purpose: Speed up development on this native SDL3 Tetris. Follow these conventio
 - Assets: `assets/` (images/music/fonts), plus `FreeSans.ttf` at repo root.
 
 ## Build and run
-- Configure and build Release:
   - CMake picks up vcpkg toolchain if found (`VCPKG_ROOT`, local `vcpkg/`, or user path). Required packages: `sdl3`, `sdl3-ttf` (see `vcpkg.json`).
   - Typical sequence (PowerShell): `cmake -S . -B build-release -DCMAKE_BUILD_TYPE=Release` then `cmake --build build-release --config Release`.
-- Packaging: `.\build-production.ps1` creates `dist/TetrisGame/` with exe, DLLs, assets, README, and ZIP; it can clean via `-Clean` and package-only via `-PackageOnly`.
-- MSVC generator builds are under `build-msvc/` when using Visual Studio.
+Packaging: `.\build-production.ps1` creates `dist/SpacetrisGame/` with exe, DLLs, assets, README, and ZIP; it can clean via `-Clean` and package-only via `-PackageOnly`.
 
 ## Runtime dependencies
 - Links: `SDL3::SDL3`, `SDL3_ttf::SDL3_ttf`; on Windows also `mfplat`, `mfreadwrite`, `mfuuid` for media.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 75a0a73..6e8095d 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -1,4 +1,4 @@
-name: Build and Package Tetris
+name: Build and Package Spacetris
 
 on:
   push:
@@ -43,20 +43,20 @@ jobs:
     - name: Upload artifacts
       uses: actions/upload-artifact@v4
       with:
-        name: tetris-windows-x64
-        path: dist/TetrisGame/
+        name: spacetris-windows-x64
+        path: dist/SpacetrisGame/
     
     - name: Create Release ZIP
       if: startsWith(github.ref, 'refs/tags/v')
       run: |
         cd dist
-        7z a ../TetrisGame-Windows-x64.zip TetrisGame/
+        7z a ../SpacetrisGame-Windows-x64.zip SpacetrisGame/
     
     - name: Release
       if: startsWith(github.ref, 'refs/tags/v')
       uses: softprops/action-gh-release@v1
       with:
-        files: TetrisGame-Windows-x64.zip
+        files: SpacetrisGame-Windows-x64.zip
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
@@ -83,32 +83,32 @@ jobs:
     
     - name: Package
       run: |
-        mkdir -p dist/TetrisGame-Linux
-        cp build/tetris dist/TetrisGame-Linux/
-        cp -r assets dist/TetrisGame-Linux/
-        cp FreeSans.ttf dist/TetrisGame-Linux/
-        echo '#!/bin/bash' > dist/TetrisGame-Linux/launch-tetris.sh
-        echo 'cd "$(dirname "$0")"' >> dist/TetrisGame-Linux/launch-tetris.sh
-        echo './tetris' >> dist/TetrisGame-Linux/launch-tetris.sh
-        chmod +x dist/TetrisGame-Linux/launch-tetris.sh
-        chmod +x dist/TetrisGame-Linux/tetris
+        mkdir -p dist/SpacetrisGame-Linux
+        cp build/spacetris dist/SpacetrisGame-Linux/
+        cp -r assets dist/SpacetrisGame-Linux/
+        cp FreeSans.ttf dist/SpacetrisGame-Linux/
+        echo '#!/bin/bash' > dist/SpacetrisGame-Linux/launch-spacetris.sh
+        echo 'cd "$(dirname "$0")"' >> dist/SpacetrisGame-Linux/launch-spacetris.sh
+        echo './spacetris' >> dist/SpacetrisGame-Linux/launch-spacetris.sh
+        chmod +x dist/SpacetrisGame-Linux/launch-spacetris.sh
+        chmod +x dist/SpacetrisGame-Linux/spacetris
     
     - name: Upload artifacts
       uses: actions/upload-artifact@v4
       with:
-        name: tetris-linux-x64
-        path: dist/TetrisGame-Linux/
+        name: spacetris-linux-x64
+        path: dist/SpacetrisGame-Linux/
     
     - name: Create Release TAR
       if: startsWith(github.ref, 'refs/tags/v')
       run: |
         cd dist
-        tar -czf ../TetrisGame-Linux-x64.tar.gz TetrisGame-Linux/
+        tar -czf ../SpacetrisGame-Linux-x64.tar.gz SpacetrisGame-Linux/
     
     - name: Release
       if: startsWith(github.ref, 'refs/tags/v')
       uses: softprops/action-gh-release@v1
       with:
-        files: TetrisGame-Linux-x64.tar.gz
+        files: SpacetrisGame-Linux-x64.tar.gz
       env:
         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.gitignore b/.gitignore
index b32beb6..8bba2aa 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,4 @@
-# .gitignore for Tetris (native C++ project and web subproject)
+# .gitignore for Spacetris (native C++ project and web subproject)
 
 # Visual Studio / VS artifacts
 .vs/
@@ -70,4 +70,7 @@ dist_package/
 # Local environment files (if any)
 .env
 
+# Ignore local settings file
+settings.ini
+
 # End of .gitignore
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 22a1a01..e64436a 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -9,7 +9,13 @@ elseif(EXISTS "C:/Users/Gregor Klevže/vcpkg/scripts/buildsystems/vcpkg.cmake")
     set(CMAKE_TOOLCHAIN_FILE "C:/Users/Gregor Klevže/vcpkg/scripts/buildsystems/vcpkg.cmake" CACHE STRING "")
 endif()
 
-project(tetris_sdl3 LANGUAGES CXX)
+# The toolchain file must be set before calling project()
+if(DEFINED CMAKE_TOOLCHAIN_FILE)
+    message(STATUS "Using vcpkg toolchain: ${CMAKE_TOOLCHAIN_FILE}")
+    set(CMAKE_TOOLCHAIN_FILE "${CMAKE_TOOLCHAIN_FILE}" CACHE STRING "" FORCE)
+endif()
+
+project(spacetris_sdl3 LANGUAGES CXX)
 
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -19,29 +25,94 @@ set(CMAKE_CXX_STANDARD_REQUIRED ON)
 # Homebrew: brew install sdl3
 find_package(SDL3 CONFIG REQUIRED)
 find_package(SDL3_ttf CONFIG REQUIRED)
+find_package(SDL3_image CONFIG REQUIRED)
+find_package(cpr CONFIG REQUIRED)
+find_package(nlohmann_json CONFIG REQUIRED)
+find_package(unofficial-enet CONFIG REQUIRED)
 
-add_executable(tetris
+set(TETRIS_SOURCES
     src/main.cpp
-    src/gameplay/Game.cpp
+    src/app/TetrisApp.cpp
+    src/gameplay/core/Game.cpp
+    src/gameplay/coop/CoopGame.cpp
+    src/gameplay/coop/CoopAIController.cpp
     src/core/GravityManager.cpp
-    src/core/StateManager.cpp
+    src/core/state/StateManager.cpp
+    # New core architecture classes
+    src/core/application/ApplicationManager.cpp
+    src/core/input/InputManager.cpp
+    src/core/assets/AssetManager.cpp
+    src/core/GlobalState.cpp
+    src/core/Settings.cpp
+    src/graphics/renderers/RenderManager.cpp
     src/persistence/Scores.cpp
-    src/graphics/Starfield.cpp
-    src/graphics/Starfield3D.cpp
-    src/graphics/Font.cpp
+    src/network/supabase_client.cpp
+    src/network/NetSession.cpp
+    src/graphics/effects/Starfield.cpp
+    src/graphics/effects/Starfield3D.cpp
+    src/graphics/effects/SpaceWarp.cpp
+    src/graphics/ui/Font.cpp
+    src/graphics/ui/HelpOverlay.cpp
+    src/graphics/renderers/GameRenderer.cpp
+    src/graphics/renderers/SyncLineRenderer.cpp
+    src/graphics/renderers/UIRenderer.cpp
     src/audio/Audio.cpp
-    src/gameplay/LineEffect.cpp
+    src/gameplay/effects/LineEffect.cpp
     src/audio/SoundEffect.cpp
+    src/video/VideoPlayer.cpp
+    src/ui/MenuLayout.cpp
+    src/ui/BottomMenu.cpp
+    src/app/BackgroundManager.cpp
+    src/app/Fireworks.cpp
+    src/app/AssetLoader.cpp
+    src/app/TextureLoader.cpp
+    src/states/LoadingManager.cpp
     # State implementations (new)
     src/states/LoadingState.cpp
+    src/states/VideoState.cpp
     src/states/MenuState.cpp
+    src/states/OptionsState.cpp
+    src/states/LevelSelectorState.cpp
     src/states/PlayingState.cpp
 )
 
+
+if(APPLE)
+    set(APP_ICON "${CMAKE_SOURCE_DIR}/assets/favicon/AppIcon.icns")
+    if(EXISTS "${APP_ICON}")
+        add_executable(spacetris MACOSX_BUNDLE ${TETRIS_SOURCES} "${APP_ICON}")
+        set_source_files_properties("${APP_ICON}" PROPERTIES MACOSX_PACKAGE_LOCATION "Resources")
+        set_target_properties(spacetris PROPERTIES 
+            MACOSX_BUNDLE_ICON_FILE "AppIcon"
+            MACOSX_BUNDLE_INFO_PLIST "${CMAKE_SOURCE_DIR}/cmake/MacBundleInfo.plist.in"
+        )
+    else()
+        message(WARNING "App icon not found at ${APP_ICON}; bundle will use default icon")
+        add_executable(spacetris MACOSX_BUNDLE ${TETRIS_SOURCES})
+        set_target_properties(spacetris PROPERTIES
+            MACOSX_BUNDLE_INFO_PLIST "${CMAKE_SOURCE_DIR}/cmake/MacBundleInfo.plist.in"
+        )
+    endif()
+else()
+    add_executable(spacetris ${TETRIS_SOURCES})
+endif()
+
+# Ensure the built executable is named `spacetris`.
+set_target_properties(spacetris PROPERTIES OUTPUT_NAME "spacetris")
+
+if (WIN32)
+    # No compatibility copy; built executable is `spacetris`.
+endif()
+
 if (WIN32)
     # Embed the application icon into the executable
     set_source_files_properties(src/app_icon.rc PROPERTIES LANGUAGE RC)
-    target_sources(tetris PRIVATE src/app_icon.rc)
+    target_sources(spacetris PRIVATE src/app_icon.rc)
+endif()
+
+if(MSVC)
+    # Prevent PDB write contention on MSVC by enabling /FS for this target
+    target_compile_options(spacetris PRIVATE /FS)
 endif()
 
 if (WIN32)
@@ -56,22 +127,58 @@ if (WIN32)
             COMMENT "Copy favicon.ico to build dir for resource compilation"
         )
         add_custom_target(copy_favicon ALL DEPENDS ${FAVICON_DEST})
-        add_dependencies(tetris copy_favicon)
+        add_dependencies(spacetris copy_favicon)
     else()
         message(WARNING "Favicon not found at ${FAVICON_SRC}; app icon may not compile")
     endif()
 
     # Also copy favicon into the runtime output folder (same dir as exe)
-    add_custom_command(TARGET tetris POST_BUILD
-        COMMAND ${CMAKE_COMMAND} -E copy_if_different ${FAVICON_SRC} $<TARGET_FILE_DIR:tetris>/favicon.ico
+    add_custom_command(TARGET spacetris POST_BUILD
+        COMMAND ${CMAKE_COMMAND} -E copy_if_different ${FAVICON_SRC} $<TARGET_FILE_DIR:spacetris>/favicon.ico
         COMMENT "Copy favicon.ico next to executable"
     )
 endif()
 
-target_link_libraries(tetris PRIVATE SDL3::SDL3 SDL3_ttf::SDL3_ttf)
+if(APPLE)
+    set(_mac_copy_commands)
+    if(EXISTS "${CMAKE_SOURCE_DIR}/assets")
+        list(APPEND _mac_copy_commands
+            COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_SOURCE_DIR}/assets" "$<TARGET_FILE_DIR:spacetris>/assets"
+        )
+    endif()
+    if(EXISTS "${CMAKE_SOURCE_DIR}/fonts")
+        list(APPEND _mac_copy_commands
+            COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_SOURCE_DIR}/fonts" "$<TARGET_FILE_DIR:spacetris>/fonts"
+        )
+    endif()
+    if(EXISTS "${CMAKE_SOURCE_DIR}/FreeSans.ttf")
+        list(APPEND _mac_copy_commands
+            COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_SOURCE_DIR}/FreeSans.ttf" "$<TARGET_FILE_DIR:spacetris>/FreeSans.ttf"
+        )
+    endif()
+    if(_mac_copy_commands)
+        add_custom_command(TARGET spacetris POST_BUILD
+            ${_mac_copy_commands}
+            COMMENT "Copying game assets into macOS bundle"
+        )
+    endif()
+endif()
+
+target_link_libraries(spacetris PRIVATE SDL3::SDL3 SDL3_ttf::SDL3_ttf SDL3_image::SDL3_image cpr::cpr nlohmann_json::nlohmann_json unofficial::enet::enet)
+
+find_package(FFMPEG REQUIRED)
+if(FFMPEG_FOUND)
+    target_include_directories(spacetris PRIVATE ${FFMPEG_INCLUDE_DIRS})
+    target_link_directories(spacetris PRIVATE ${FFMPEG_LIBRARY_DIRS})
+    target_link_libraries(spacetris PRIVATE ${FFMPEG_LIBRARIES})
+endif()
 
 if (WIN32)
-    target_link_libraries(tetris PRIVATE mfplat mfreadwrite mfuuid)
+    target_link_libraries(spacetris PRIVATE mfplat mfreadwrite mfuuid ws2_32 winmm)
+endif()
+if(APPLE)
+    # Needed for MP3 decoding via AudioToolbox on macOS
+    target_link_libraries(spacetris PRIVATE "-framework AudioToolbox" "-framework CoreFoundation")
 endif()
 
 # Include production build configuration
@@ -82,23 +189,26 @@ enable_testing()
 
 # Unit tests (simple runner)
 find_package(Catch2 CONFIG REQUIRED)
-add_executable(tetris_tests
+add_executable(spacetris_tests
     tests/GravityTests.cpp
     src/core/GravityManager.cpp
 )
-target_include_directories(tetris_tests PRIVATE ${CMAKE_SOURCE_DIR}/src)
-target_link_libraries(tetris_tests PRIVATE Catch2::Catch2WithMain)
-add_test(NAME GravityTests COMMAND tetris_tests)
+target_include_directories(spacetris_tests PRIVATE ${CMAKE_SOURCE_DIR}/src)
+target_link_libraries(spacetris_tests PRIVATE Catch2::Catch2WithMain)
+add_test(NAME GravityTests COMMAND spacetris_tests)
 
 if(EXISTS "${CMAKE_SOURCE_DIR}/vcpkg_installed/x64-windows/include")
-    target_include_directories(tetris_tests PRIVATE "${CMAKE_SOURCE_DIR}/vcpkg_installed/x64-windows/include")
+    target_include_directories(spacetris_tests PRIVATE "${CMAKE_SOURCE_DIR}/vcpkg_installed/x64-windows/include")
 endif()
 
 # Add new src subfolders to include path so old #includes continue to work
-target_include_directories(tetris PRIVATE
+target_include_directories(spacetris PRIVATE
     ${CMAKE_SOURCE_DIR}/src
     ${CMAKE_SOURCE_DIR}/src/audio
+    ${CMAKE_SOURCE_DIR}/src/video
     ${CMAKE_SOURCE_DIR}/src/gameplay
     ${CMAKE_SOURCE_DIR}/src/graphics
     ${CMAKE_SOURCE_DIR}/src/persistence
+    ${CMAKE_SOURCE_DIR}/src/core
+    ${CMAKE_SOURCE_DIR}/src/states
 )
\ No newline at end of file
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
index 4913e93..f065e35 100644
--- a/DEPLOYMENT.md
+++ b/DEPLOYMENT.md
@@ -1,4 +1,4 @@
-# Tetris SDL3 - Production Deployment Guide
+# Spacetris SDL3 - Production Deployment Guide
 
 ## 🚀 Build Scripts Available
 
@@ -9,7 +9,7 @@
 - Uses existing Debug/Release build from build-msvc
 - Creates distribution package with all dependencies
 - **Size: ~939 MB** (includes all assets and music)
-- **Output:** `dist/TetrisGame/` + ZIP file
+- **Output:** `dist/SpacetrisGame/` + ZIP file
 
 ### 2. Full Production Build
 ```powershell
@@ -31,8 +31,8 @@ build-production.bat
 The distribution package includes:
 
 ### Essential Files
-- ✅ `tetris.exe` - Main game executable
-- ✅ `Launch-Tetris.bat` - Safe launcher with error handling
+- ✅ `spacetris.exe` - Main game executable
+- ✅ `Launch-Spacetris.bat` - Safe launcher with error handling
 - ✅ `README.txt` - User instructions
 
 ### Dependencies  
@@ -49,9 +49,9 @@ The distribution package includes:
 ## 🎯 Distribution Options
 
 ### Option 1: ZIP Archive (Recommended)
-- **File:** `TetrisGame-YYYY.MM.DD.zip`
+- **File:** `SpacetrisGame-YYYY.MM.DD.zip`
 - **Size:** ~939 MB
-- **Usage:** Users extract and run `Launch-Tetris.bat`
+- **Usage:** Users extract and run `Launch-Spacetris.bat`
 
 ### Option 2: Installer (Future)
 - Use CMake CPack to create NSIS installer
@@ -60,14 +60,14 @@ The distribution package includes:
   ```
 
 ### Option 3: Portable Folder
-- Direct distribution of `dist/TetrisGame/` folder
+ Direct distribution of `dist/SpacetrisGame/` folder
 - Users copy folder and run executable
-
+ [ ] Launch-Spacetris.bat works
 ## 🔧 Build Requirements
-
+ **Solution:** Use `Launch-Spacetris.bat` for better error reporting
 ### Development Environment
 - **CMake** 3.20+
-- **Visual Studio 2022** (or compatible C++ compiler)
+- **Visual Studio 2026 (VS 18)** with Desktop development with C++ workload
 - **vcpkg** package manager
 - **SDL3** libraries (installed via vcpkg)
 
@@ -87,18 +87,21 @@ vcpkg install sdl3 sdl3-ttf --triplet=x64-windows
 - [ ] Font rendering works (both FreeSans and PressStart2P)
 - [ ] Game saves high scores
 
+### Package Validation
 ### Package Validation
 - [ ] All DLL files present
 - [ ] Assets folder complete
-- [ ] Launch-Tetris.bat works
+- [ ] Launch-Spacetris.bat works
 - [ ] README.txt is informative
 - [ ] Package size reasonable (~939 MB)
 
 ### Distribution
-- [ ] ZIP file created successfully
+### "spacetris.exe is not recognized"
+- **Solution:** Ensure all DLL files are in same folder as executable
 - [ ] Test extraction on clean system
 - [ ] Verify game runs on target machines
-- [ ] No missing dependencies
+### Game won't start
+- **Solution:** Use `Launch-Spacetris.bat` for better error reporting
 
 ## 📋 User System Requirements
 
@@ -118,7 +121,7 @@ vcpkg install sdl3 sdl3-ttf --triplet=x64-windows
 
 ## 🐛 Common Issues & Solutions
 
-### "tetris.exe is not recognized"
+### "spacetris.exe is not recognized"
 - **Solution:** Ensure all DLL files are in same folder as executable
 
 ### "Failed to initialize SDL"
diff --git a/FreeSans.ttf b/FreeSans.ttf
deleted file mode 100644
index 9db9585..0000000
Binary files a/FreeSans.ttf and /dev/null differ
diff --git a/I_PIECE_SPAWN_FIX.md b/I_PIECE_SPAWN_FIX.md
deleted file mode 100644
index 285af34..0000000
--- a/I_PIECE_SPAWN_FIX.md
+++ /dev/null
@@ -1,160 +0,0 @@
-# I-Piece Spawn Position Fix
-
-## Overview
-Fixed the I-piece (straight line tetromino) to spawn one row higher than other pieces, addressing the issue where the I-piece only occupied one line when spawning vertically, making its entry appear less natural.
-
-## Problem Analysis
-
-### Issue Identified
-The I-piece has unique spawn behavior because:
-- **Vertical I-piece**: When spawning in vertical orientation (rotation 0), it only occupies one row
-- **Visual Impact**: This made the I-piece appear to "pop in" at the top grid line rather than naturally entering
-- **Player Experience**: Less time to react and plan placement compared to other pieces
-
-### Other Pieces
-All other pieces (O, T, S, Z, J, L) were working perfectly at their current spawn position (`y = -1`) and should remain unchanged.
-
-## Solution Implemented
-
-### Targeted I-Piece Fix
-Instead of changing all pieces, implemented piece-type-specific spawn logic:
-
-```cpp
-// I-piece spawns higher due to its unique height characteristics
-int spawnY = (pieceType == I) ? -2 : -1;
-```
-
-### Code Changes
-
-#### 1. Updated spawn() function:
-```cpp
-void Game::spawn() {
-    if (bag.empty()) refillBag();
-    PieceType pieceType = bag.back();
-    
-    // I-piece needs to start one row higher due to its height when vertical
-    int spawnY = (pieceType == I) ? -2 : -1;
-    
-    cur = Piece{ pieceType, 0, 3, spawnY };
-    bag.pop_back();
-    blockCounts[cur.type]++; 
-    canHold = true;
-    
-    // Prepare next piece with same logic
-    if (bag.empty()) refillBag();
-    PieceType nextType = bag.back();
-    int nextSpawnY = (nextType == I) ? -2 : -1;
-    nextPiece = Piece{ nextType, 0, 3, nextSpawnY };
-}
-```
-
-#### 2. Updated holdCurrent() function:
-```cpp
-// Apply I-piece specific positioning in hold mechanics
-int holdSpawnY = (hold.type == I) ? -2 : -1;
-int currentSpawnY = (temp.type == I) ? -2 : -1;
-```
-
-## Technical Benefits
-
-### 1. Piece-Specific Optimization
-- **I-Piece**: Spawns at `y = -2` for natural vertical entry
-- **Other Pieces**: Remain at `y = -1` for optimal gameplay feel
-- **Consistency**: Each piece type gets appropriate spawn positioning
-
-### 2. Enhanced Gameplay
-- **I-Piece Visibility**: More natural entry animation and player reaction time
-- **Preserved Balance**: Other pieces maintain their optimized spawn positions
-- **Strategic Depth**: I-piece placement becomes more strategic with better entry timing
-
-### 3. Code Quality
-- **Targeted Solution**: Minimal code changes addressing specific issue
-- **Maintainable Logic**: Clear piece-type conditionals
-- **Extensible Design**: Easy to adjust other pieces if needed in future
-
-## Spawn Position Matrix
-
-```
-Piece Type | Spawn Y | Reasoning
------------|---------|------------------------------------------
-I-piece    | -2      | Vertical orientation needs extra height
-O-piece    | -1      | Perfect 2x2 square positioning  
-T-piece    | -1      | Optimal T-shape entry timing
-S-piece    | -1      | Natural S-shape appearance
-Z-piece    | -1      | Natural Z-shape appearance  
-J-piece    | -1      | Optimal L-shape entry
-L-piece    | -1      | Optimal L-shape entry
-```
-
-## Visual Comparison
-
-### I-Piece Spawn Behavior:
-```
-BEFORE (y = -1):            AFTER (y = -2):
-[        ]                  [        ]
-[   █    ] ← I-piece here   [        ] 
-[████████]                  [   █    ] ← I-piece here
-[████████]                  [████████]
-
-Problem: Abrupt entry       Solution: Natural entry
-```
-
-### Other Pieces (Unchanged):
-```
-T-Piece Example (y = -1):
-[        ]
-[ ███    ] ← T-piece entry (perfect)
-[████████]
-[████████]
-
-Status: No change needed ✅
-```
-
-## Testing Results
-
-### 1. I-Piece Verification
-✅ **Vertical Spawn**: I-piece now appears naturally from above  
-✅ **Entry Animation**: Smooth transition into visible grid area  
-✅ **Player Reaction**: More time to plan I-piece placement  
-✅ **Hold Function**: I-piece maintains correct positioning when held/swapped  
-
-### 2. Other Pieces Validation  
-✅ **O-Piece**: Maintains perfect 2x2 positioning  
-✅ **T-Piece**: Optimal T-shape entry preserved  
-✅ **S/Z-Pieces**: Natural zigzag entry unchanged  
-✅ **J/L-Pieces**: L-shape entry timing maintained  
-
-### 3. Game Mechanics
-✅ **Spawn Consistency**: Each piece type uses appropriate spawn height  
-✅ **Hold System**: Piece-specific positioning applied correctly  
-✅ **Bag Randomizer**: Next piece preview uses correct spawn height  
-✅ **Game Flow**: Smooth progression for all piece types  
-
-## Benefits Summary
-
-### 1. Improved I-Piece Experience
-- **Natural Entry**: I-piece now enters the play area smoothly
-- **Better Timing**: More reaction time for strategic placement
-- **Visual Polish**: Professional appearance matching commercial Tetris games
-
-### 2. Preserved Gameplay Balance
-- **Other Pieces Unchanged**: Maintain optimal spawn positions for 6 other piece types
-- **Consistent Feel**: Each piece type gets appropriate treatment
-- **Strategic Depth**: I-piece becomes more strategic without affecting other pieces
-
-### 3. Technical Excellence
-- **Minimal Changes**: Targeted fix without broad system changes
-- **Future-Proof**: Easy to adjust individual piece spawn behavior
-- **Code Quality**: Clear, maintainable piece-type logic
-
-## Status: ✅ COMPLETED
-
-- **I-Piece**: Now spawns at y = -2 for natural vertical entry
-- **Other Pieces**: Remain at y = -1 for optimal gameplay  
-- **Hold System**: Updated to handle piece-specific spawn positions
-- **Next Piece**: Preview system uses correct spawn heights
-- **Testing**: Validated all piece types work correctly
-
-## Conclusion
-
-The I-piece now provides a much more natural gameplay experience with proper entry timing, while all other pieces maintain their optimal spawn positions. This targeted fix addresses the specific issue without disrupting the carefully balanced gameplay of other tetrominos.
diff --git a/LAYOUT_IMPROVEMENTS.md b/LAYOUT_IMPROVEMENTS.md
deleted file mode 100644
index 1bff1cb..0000000
--- a/LAYOUT_IMPROVEMENTS.md
+++ /dev/null
@@ -1,145 +0,0 @@
-# Gameplay Layout Improvements - Enhancement Report
-
-## Overview
-Enhanced the gameplay state visual layout by repositioning the next piece preview higher above the main grid and adding subtle grid lines to improve gameplay visibility.
-
-## Changes Made
-
-### 1. Next Piece Preview Repositioning
-**Problem**: The next piece preview was positioned too close to the main game grid, causing visual overlap and crowded appearance.
-
-**Solution**:
-```cpp
-// BEFORE: Limited space for next piece
-const float NEXT_PIECE_HEIGHT = 80.0f; // Space reserved for next piece preview
-
-// AFTER: More breathing room
-const float NEXT_PIECE_HEIGHT = 120.0f; // Space reserved for next piece preview (increased)
-```
-
-**Result**: 
-- ✅ **50% more space** above the main grid (80px → 120px)
-- ✅ **Clear separation** between next piece and main game area
-- ✅ **Better visual hierarchy** in the gameplay layout
-
-### 2. Main Grid Visual Enhancement
-**Problem**: The main game grid lacked visual cell boundaries, making it difficult to precisely judge piece placement.
-
-**Solution**: Added subtle grid lines to show cell boundaries
-```cpp
-// Draw grid lines (subtle lines to show cell boundaries)
-SDL_SetRenderDrawColor(renderer, 40, 45, 60, 255); // Slightly lighter than background
-
-// Vertical grid lines
-for (int x = 1; x < Game::COLS; ++x) {
-    float lineX = gridX + x * finalBlockSize + contentOffsetX;
-    SDL_RenderLine(renderer, lineX, gridY + contentOffsetY, lineX, gridY + GRID_H + contentOffsetY);
-}
-
-// Horizontal grid lines
-for (int y = 1; y < Game::ROWS; ++y) {
-    float lineY = gridY + y * finalBlockSize + contentOffsetY;
-    SDL_RenderLine(renderer, gridX + contentOffsetX, lineY, gridX + GRID_W + contentOffsetX, lineY);
-}
-```
-
-**Grid Line Properties**:
-- **Color**: `RGB(40, 45, 60)` - Barely visible, subtle enhancement
-- **Coverage**: Complete 10×20 grid with proper cell boundaries
-- **Performance**: Minimal overhead with simple line drawing
-- **Visual Impact**: Clear cell separation without visual noise
-
-## Technical Details
-
-### Layout Calculation System
-The responsive layout system maintains perfect centering while accommodating the increased next piece space:
-
-```cpp
-// Layout Components:
-- Top Margin: 60px (UI spacing)
-- Next Piece Area: 120px (increased from 80px)
-- Main Grid: Dynamic based on window size
-- Bottom Margin: 60px (controls text)
-- Side Panels: 180px each (stats and score)
-```
-
-### Grid Line Implementation
-- **Rendering Order**: Background → Grid Lines → Game Blocks → UI Elements
-- **Line Style**: Single pixel lines with subtle contrast
-- **Integration**: Seamlessly integrated with existing rendering pipeline
-- **Responsiveness**: Automatically scales with dynamic block size
-
-## Visual Benefits
-
-### 1. Improved Gameplay Precision
-- **Grid Boundaries**: Clear visual cell separation for accurate piece placement
-- **Alignment Reference**: Easy to judge piece positioning and rotation
-- **Professional Appearance**: Matches modern Tetris game standards
-
-### 2. Enhanced Layout Flow
-- **Next Piece Visibility**: Higher positioning prevents overlap with main game
-- **Visual Balance**: Better proportions between UI elements
-- **Breathing Room**: More comfortable spacing throughout the interface
-
-### 3. Accessibility Improvements
-- **Visual Clarity**: Subtle grid helps players with visual impairments
-- **Reduced Eye Strain**: Better element separation reduces visual confusion
-- **Gameplay Flow**: Smoother visual transitions between game areas
-
-## Comparison: Before vs After
-
-### Next Piece Positioning:
-```
-BEFORE: [Next Piece]
-        [Main Grid ]  ← Too close, visual overlap
-
-AFTER:  [Next Piece]
-        
-        [Main Grid ]  ← Proper separation, clear hierarchy
-```
-
-### Grid Visibility:
-```
-BEFORE: Solid background, no cell boundaries
-        ■■■■■■■■■■
-        ■■■■■■■■■■  ← Difficult to judge placement
-
-AFTER:  Subtle grid lines show cell boundaries
-        ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
-        ├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤  ← Easy placement reference
-        └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
-```
-
-## Testing Results
-✅ **Build Success**: Clean compilation with no errors  
-✅ **Visual Layout**: Next piece properly positioned above grid  
-✅ **Grid Lines**: Subtle, barely visible lines enhance gameplay  
-✅ **Responsive Design**: All improvements work across window sizes  
-✅ **Performance**: No measurable impact on frame rate  
-✅ **Game Logic**: All existing functionality preserved  
-
-## User Experience Impact
-
-### 1. Gameplay Improvements
-- **Precision**: Easier to place pieces exactly where intended
-- **Speed**: Faster visual assessment of game state
-- **Confidence**: Clear visual references reduce placement errors
-
-### 2. Visual Polish
-- **Professional**: Matches commercial Tetris game standards
-- **Modern**: Clean, organized interface layout
-- **Consistent**: Maintains established visual design language
-
-### 3. Accessibility
-- **Clarity**: Better visual separation for all users
-- **Readability**: Improved layout hierarchy
-- **Comfort**: Reduced visual strain during extended play
-
-## Conclusion
-The layout improvements successfully address the visual overlap issue with the next piece preview and add essential grid lines for better gameplay precision. The changes maintain the responsive design system while providing a more polished and professional gaming experience.
-
-## Status: ✅ COMPLETED
-- Next piece repositioned higher above main grid
-- Subtle grid lines added to main game board
-- Layout maintains responsive design and perfect centering
-- All existing functionality preserved with enhanced visual clarity
diff --git a/LOADING_PROGRESS_FIX.md b/LOADING_PROGRESS_FIX.md
deleted file mode 100644
index 9f23312..0000000
--- a/LOADING_PROGRESS_FIX.md
+++ /dev/null
@@ -1,138 +0,0 @@
-# Loading Progress Fix - Issue Resolution
-
-## Problem Identified
-The loading progress was reaching 157% instead of stopping at 100%. This was caused by a mismatch between:
-- **Expected tracks**: 11 (hardcoded `totalTracks = 11`)
-- **Actual music files**: 24 total files (but only 11 numbered music tracks)
-
-## Root Cause Analysis
-
-### File Structure in `assets/music/`:
-```
-Numbered Music Tracks (Background Music):
-- music001.mp3 through music011.mp3 (11 files)
-
-Sound Effect Files:
-- amazing.mp3, boom_tetris.mp3, great_move.mp3, impressive.mp3
-- keep_that_ryhtm.mp3, lets_go.mp3, nice_combo.mp3, smooth_clear.mp3
-- triple_strike.mp3, well_played.mp3, wonderful.mp3, you_fire.mp3
-(13 sound effect files)
-```
-
-### Issue Details:
-1. **Hardcoded Count**: `totalTracks` was fixed at 11
-2. **Audio Loading**: The system was actually loading more than 11 files
-3. **Progress Calculation**: `currentTrackLoading / totalTracks * 0.7` exceeded 0.7 when `currentTrackLoading > 11`
-4. **Result**: Progress went beyond 100% (up to ~157%)
-
-## Solution Implemented
-
-### 1. Dynamic Track Counting
-```cpp
-// BEFORE: Fixed count
-const int totalTracks = 11;
-
-// AFTER: Dynamic detection
-int totalTracks = 0; // Will be set dynamically based on actual files
-```
-
-### 2. File Detection Logic
-```cpp
-// Count actual numbered music files (music001.mp3, music002.mp3, etc.)
-totalTracks = 0;
-for (int i = 1; i <= 100; ++i) {
-    char buf[64];
-    std::snprintf(buf, sizeof(buf), "assets/music/music%03d.mp3", i);
-    
-    // Check if file exists
-    SDL_IOStream* file = SDL_IOFromFile(buf, "rb");
-    if (file) {
-        SDL_CloseIO(file);
-        totalTracks++;
-    } else {
-        break; // No more consecutive files
-    }
-}
-```
-
-### 3. Progress Calculation Safety
-```cpp
-// BEFORE: Could exceed 100%
-double musicProgress = musicLoaded ? 0.7 : (double)currentTrackLoading / totalTracks * 0.7;
-
-// AFTER: Capped at maximum values
-double musicProgress = 0.0;
-if (totalTracks > 0) {
-    musicProgress = musicLoaded ? 0.7 : std::min(0.7, (double)currentTrackLoading / totalTracks * 0.7);
-}
-
-// Additional safety check
-loadingProgress = std::min(1.0, loadingProgress);
-```
-
-## Technical Verification
-
-### Test Results:
-✅ **Track Detection**: Correctly identifies 11 numbered music tracks  
-✅ **Progress Calculation**: 0/11 → 11/11 (never exceeds denominator)  
-✅ **Loading Phases**: 20% (assets) + 70% (music) + 10% (init) = 100% max  
-✅ **Safety Bounds**: `std::min(1.0, loadingProgress)` prevents overflow  
-✅ **Game Launch**: Smooth transition from loading to menu at exactly 100%  
-
-### Debug Output (Removed in Final):
-```
-Found 11 music tracks to load
-Loading progress: 0/11 tracks loaded
-...
-Loading progress: 11/11 tracks loaded
-All music tracks loaded successfully!
-```
-
-## Benefits of the Fix
-
-### 1. Accurate Progress Display
-- **Before**: Could show 157% (confusing and broken)
-- **After**: Always stops exactly at 100% (professional and accurate)
-
-### 2. Dynamic Adaptability
-- **Before**: Hardcoded for exactly 11 tracks
-- **After**: Automatically adapts to any number of numbered music tracks
-
-### 3. Asset Separation
-- **Music Tracks**: Only numbered files (`music001.mp3` - `music011.mp3`) for background music
-- **Sound Effects**: Named files (`amazing.mp3`, `boom_tetris.mp3`, etc.) handled separately
-
-### 4. Robust Error Handling
-- **File Detection**: Safe file existence checking with proper resource cleanup
-- **Progress Bounds**: Multiple safety checks prevent mathematical overflow
-- **Loading Logic**: Graceful handling of missing or incomplete file sequences
-
-## Code Quality Improvements
-
-### 1. Resource Management
-```cpp
-SDL_IOStream* file = SDL_IOFromFile(buf, "rb");
-if (file) {
-    SDL_CloseIO(file);  // Proper cleanup
-    totalTracks++;
-}
-```
-
-### 2. Mathematical Safety
-```cpp
-loadingProgress = std::min(1.0, loadingProgress);  // Never exceed 100%
-```
-
-### 3. Clear Phase Separation
-```cpp
-// Phase 1: Assets (20%) + Phase 2: Music (70%) + Phase 3: Init (10%) = 100%
-```
-
-## Conclusion
-The loading progress now correctly shows 0% → 100% progression, with proper file detection, safe mathematical calculations, and clean separation between background music tracks and sound effect files. The system is now robust and will adapt automatically if music tracks are added or removed.
-
-## Status: ✅ RESOLVED
-- Loading progress fixed: Never exceeds 100%
-- Dynamic track counting: Adapts to actual file count
-- Code quality: Improved safety and resource management
-- User experience: Professional loading screen with accurate progress
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9846bf5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,34 @@
+Spacetris SDL3
+=============
+
+A native C++20 SDL3-based Tetris-style game.
+
+Quick Start (Windows)
+- Install vcpkg and packages: `vcpkg install sdl3 sdl3-ttf --triplet=x64-windows`
+- Configure: `cmake -S . -B build-msvc -DCMAKE_BUILD_TYPE=Debug`
+- Build: `cmake --build build-msvc --config Debug`
+- Run (helper): `.
+build-debug-and-run.ps1` or run `build-msvc\Debug\spacetris.exe`
+
+Production Packaging
+- Quick package (uses existing build): `.
+package-quick.ps1`
+- Full production (clean Release build + package): `.
+build-production.ps1 -Clean`
+
+Tests
+- Unit tests target: `spacetris_tests` → exe `spacetris_tests.exe`
+- Run tests: configure+build then `ctest -C Debug` or run the test exe directly
+
+Where to look
+- Main app sources: `src/` (entry `src/main.cpp`, app `src/app`)
+- Build control: `CMakeLists.txt` and `cmake/ProductionBuild.cmake`
+- Packaging helpers: `build-production.ps1`, `package-quick.ps1`
+
+Notes
+- The canonical executable name is `spacetris` (`spacetris.exe` on Windows).
+- Assets live in `assets/` and are copied into the distribution package.
+
+If you want, I can:
+- Run a Debug build and confirm the test executable name,
+- Replace remaining legacy "tetris" tokens across generated files and docs.
diff --git a/SOUND_EFFECTS_IMPLEMENTATION.md b/SOUND_EFFECTS_IMPLEMENTATION.md
deleted file mode 100644
index dd4c072..0000000
--- a/SOUND_EFFECTS_IMPLEMENTATION.md
+++ /dev/null
@@ -1,118 +0,0 @@
-# Sound Effects Implementation
-
-## Overview
-This document describes the sound effects system implemented in the SDL C++ Tetris project, ported from the JavaScript version.
-
-## Sound Effects Implemented
-
-### 1. Line Clear Sounds
-- **Basic Line Clear**: `clear_line.wav` - Plays for all line clears (1-4 lines)
-- **Voice Feedback**: Plays after the basic sound with a slight delay
-
-### 2. Voice Lines by Line Count
-
-#### Single Line Clear
-- No specific voice lines (only basic clear sound plays)
-
-#### Double Line Clear (2 lines)
-- `nice_combo.mp3` - "Nice combo"
-- `you_fire.mp3` - "You're on fire"  
-- `well_played.mp3` - "Well played"
-- `keep_that_ryhtm.mp3` - "Keep that rhythm" (note: typo preserved from original)
-
-#### Triple Line Clear (3 lines)
-- `great_move.mp3` - "Great move"
-- `smooth_clear.mp3` - "Smooth clear"
-- `impressive.mp3` - "Impressive"
-- `triple_strike.mp3` - "Triple strike"
-
-#### Tetris (4 lines)
-- `amazing.mp3` - "Amazing"
-- `you_re_unstoppable.mp3` - "You're unstoppable"
-- `boom_tetris.mp3` - "Boom! Tetris!"
-- `wonderful.mp3` - "Wonderful"
-
-### 3. Level Up Sound
-- `lets_go.mp3` - "Let's go" - Plays when the player advances to a new level
-
-## Implementation Details
-
-### Core Classes
-1. **SoundEffect**: Handles individual sound file loading and playback
-   - Supports both WAV and MP3 formats
-   - Uses SDL3 audio streams for playback
-   - Volume control per sound effect
-
-2. **SoundEffectManager**: Manages all sound effects
-   - Singleton pattern for global access
-   - Random selection from sound groups
-   - Master volume and enable/disable controls
-
-### Audio Pipeline
-1. **Loading**: Sound files are loaded during game initialization
-   - WAV files use SDL's native loading
-   - MP3 files use Windows Media Foundation (Windows only)
-   - All audio is converted to 16-bit stereo 44.1kHz
-
-2. **Playback**: Uses SDL3 audio streams
-   - Each sound effect can be played independently
-   - Volume mixing with master volume control
-   - Non-blocking playback for game responsiveness
-
-### Integration with Game Logic
-- **Line Clear Callback**: Game class triggers sound effects when lines are cleared
-- **Level Up Callback**: Triggered when player advances levels
-- **Random Selection**: Multiple voice lines for same event are randomly selected
-
-### Controls
-- **M Key**: Toggle background music on/off
-- **S Key**: Toggle sound effects on/off
-- Settings popup shows current status of both music and sound effects
-
-### JavaScript Compatibility
-The implementation matches the JavaScript version exactly:
-- Same sound files used
-- Same triggering conditions (line counts, level ups)
-- Same random selection behavior for voice lines
-- Same volume levels and mixing
-
-## Audio Files Structure
-```
-assets/music/
-├── clear_line.wav              # Basic line clear sound
-├── nice_combo.mp3              # Double line voice
-├── you_fire.mp3                # Double line voice
-├── well_played.mp3             # Double line voice
-├── keep_that_ryhtm.mp3         # Double line voice (typo preserved)
-├── great_move.mp3              # Triple line voice
-├── smooth_clear.mp3            # Triple line voice
-├── impressive.mp3              # Triple line voice
-├── triple_strike.mp3           # Triple line voice
-├── amazing.mp3                 # Tetris voice
-├── you_re_unstoppable.mp3      # Tetris voice
-├── boom_tetris.mp3             # Tetris voice
-├── wonderful.mp3               # Tetris voice
-└── lets_go.mp3                 # Level up sound
-```
-
-## Technical Notes
-
-### Platform Support
-- **Windows**: Full MP3 support via Windows Media Foundation
-- **Other platforms**: WAV support only (MP3 requires additional libraries)
-
-### Performance
-- All sounds are pre-loaded during initialization
-- Minimal CPU overhead during gameplay
-- SDL3 handles audio mixing and buffering
-
-### Memory Usage
-- Sound effects are kept in memory for instant playback
-- Total memory usage approximately 50-100MB for all effects
-- Memory is freed on application shutdown
-
-## Future Enhancements
-- Add sound effects for piece placement/movement
-- Implement positional audio for stereo effects
-- Add configurable volume levels per sound type
-- Support for additional audio formats (OGG, FLAC)
diff --git a/SPAWN_AND_FONT_IMPROVEMENTS.md b/SPAWN_AND_FONT_IMPROVEMENTS.md
deleted file mode 100644
index e73de29..0000000
--- a/SPAWN_AND_FONT_IMPROVEMENTS.md
+++ /dev/null
@@ -1,182 +0,0 @@
-# Piece Spawning and Font Enhancement - Implementation Report
-
-## Overview
-Fixed piece spawning position to appear within the grid boundaries and updated the gameplay UI to consistently use the PressStart2P retro pixel font for authentic Tetris aesthetics.
-
-## Changes Made
-
-### 1. Piece Spawning Position Fix
-
-**Problem**: New pieces were spawning at `y = -2`, causing them to appear above the visible grid area, which is non-standard for Tetris gameplay.
-
-**Solution**: Updated spawn position to `y = 0` (top of the grid)
-
-#### Files Modified:
-- **`src/Game.cpp`** - `spawn()` function
-- **`src/Game.cpp`** - `holdCurrent()` function
-
-#### Code Changes:
-```cpp
-// BEFORE: Pieces spawn above grid
-cur = Piece{ bag.back(), 0, 3, -2 };
-nextPiece = Piece{ bag.back(), 0, 3, -2 };
-
-// AFTER: Pieces spawn within grid
-cur = Piece{ bag.back(), 0, 3, 0 };  // Spawn at top of visible grid
-nextPiece = Piece{ bag.back(), 0, 3, 0 };
-```
-
-#### Hold Function Updates:
-```cpp
-// BEFORE: Hold pieces reset above grid
-hold.x = 3; hold.y = -2; hold.rot = 0;
-cur.x = 3; cur.y = -2; cur.rot = 0;
-
-// AFTER: Hold pieces reset within grid
-hold.x = 3; hold.y = 0; hold.rot = 0;  // Within grid boundaries
-cur.x = 3; cur.y = 0; cur.rot = 0;
-```
-
-### 2. Font System Enhancement
-
-**Goal**: Replace FreeSans font with PressStart2P for authentic retro gaming experience
-
-#### Updated UI Elements:
-- **Next Piece Preview**: "NEXT" label
-- **Statistics Panel**: "BLOCKS" header and piece counts
-- **Score Panel**: "SCORE", "LINES", "LEVEL" headers and values
-- **Progress Indicators**: "NEXT LVL" and line count
-- **Time Display**: "TIME" header and timer
-- **Hold System**: "HOLD" label
-- **Pause Screen**: "PAUSED" text and resume instructions
-
-#### Font Scale Adjustments:
-```cpp
-// Optimized scales for PressStart2P readability
-Headers (SCORE, LINES, etc.): 1.0f scale
-Values (numbers, counts):      0.8f scale  
-Small labels:                  0.7f scale
-Pause text:                    2.0f scale
-```
-
-#### Before vs After:
-```
-BEFORE (FreeSans):          AFTER (PressStart2P):
-┌─────────────────┐         ┌─────────────────┐
-│ SCORE           │         │ SCORE           │ ← Retro pixel font
-│ 12,400          │         │ 12,400          │ ← Monospace numbers
-│ LINES           │         │ LINES           │ ← Consistent styling
-│ 042             │         │ 042             │ ← Authentic feel
-└─────────────────┘         └─────────────────┘
-```
-
-## Technical Benefits
-
-### 1. Standard Tetris Behavior
-- **Proper Spawning**: Pieces now appear at the standard Tetris spawn position
-- **Visible Entry**: Players can see pieces entering the game area
-- **Collision Detection**: Improved accuracy for top-of-grid scenarios
-- **Game Over Logic**: Clearer indication when pieces can't spawn
-
-### 2. Enhanced Visual Consistency
-- **Unified Typography**: All gameplay elements use the same retro font
-- **Authentic Aesthetics**: Matches classic arcade Tetris appearance
-- **Professional Polish**: Consistent branding throughout the game
-- **Improved Readability**: Monospace numbers for better score tracking
-
-### 3. Gameplay Improvements
-- **Predictable Spawning**: Pieces always appear in the expected location
-- **Strategic Planning**: Players can plan for pieces entering at the top
-- **Reduced Confusion**: No more pieces appearing from above the visible area
-- **Standard Experience**: Matches expectations from other Tetris games
-
-## Implementation Details
-
-### Spawn Position Logic
-```cpp
-// Standard Tetris spawning behavior:
-// - X position: 3 (center of 10-wide grid)
-// - Y position: 0 (top row of visible grid)  
-// - Rotation: 0 (default orientation)
-
-Piece newPiece = { pieceType, 0, 3, 0 };
-```
-
-### Font Rendering Optimization
-```cpp
-// Consistent retro UI with optimized scales
-pixelFont.draw(renderer, x, y, "SCORE", 1.0f, goldColor);      // Headers
-pixelFont.draw(renderer, x, y, "12400", 0.8f, whiteColor);     // Values
-pixelFont.draw(renderer, x, y, "5 LINES", 0.7f, whiteColor);   // Details
-```
-
-## Testing Results
-
-### 1. Spawn Position Verification
-✅ **New pieces appear at grid top**: Visible within game boundaries  
-✅ **Hold functionality**: Swapped pieces spawn correctly  
-✅ **Game over detection**: Proper collision when grid is full  
-✅ **Visual clarity**: No confusion about piece entry point  
-
-### 2. Font Rendering Validation
-✅ **PressStart2P loading**: Font loads correctly from assets  
-✅ **Text readability**: All UI elements clearly visible  
-✅ **Scale consistency**: Proper proportions across different text sizes  
-✅ **Color preservation**: Maintains original color scheme  
-✅ **Performance**: No rendering performance impact  
-
-### 3. User Experience Testing
-✅ **Gameplay flow**: Natural piece entry feels intuitive  
-✅ **Visual appeal**: Retro aesthetic enhances game experience  
-✅ **Information clarity**: Statistics and scores easily readable  
-✅ **Professional appearance**: Polished, consistent UI design  
-
-## Visual Comparison
-
-### Piece Spawning:
-```
-BEFORE: [   ■■   ] ← Pieces appear above grid (confusing)
-        [        ]
-        [████████] ← Actual game grid
-        [████████]
-
-AFTER:  [   ■■   ] ← Pieces appear within grid (clear)
-        [████████] ← Visible entry point
-        [████████]
-```
-
-### Font Aesthetics:
-```
-BEFORE (FreeSans):     AFTER (PressStart2P):
-Modern, clean font     8-bit pixel perfect font
-Variable spacing       Monospace alignment
-Smooth curves         Sharp pixel edges
-Generic appearance    Authentic retro feel
-```
-
-## Benefits Summary
-
-### 1. Gameplay Standards
-- **Tetris Compliance**: Matches standard Tetris piece spawning behavior
-- **Player Expectations**: Familiar experience for Tetris players
-- **Strategic Depth**: Proper visibility of incoming pieces
-
-### 2. Visual Enhancement
-- **Retro Authenticity**: True 8-bit arcade game appearance
-- **Consistent Branding**: Unified typography throughout gameplay
-- **Professional Polish**: Commercial-quality visual presentation
-
-### 3. User Experience
-- **Clarity**: Clear piece entry and movement
-- **Immersion**: Enhanced retro gaming atmosphere
-- **Accessibility**: Improved text readability and information hierarchy
-
-## Status: ✅ COMPLETED
-- Piece spawning fixed: Y position changed from -2 to 0
-- Font system updated: PressStart2P implemented for gameplay UI
-- Hold functionality: Updated to use correct spawn positions
-- Visual consistency: All gameplay text uses retro pixel font
-- Testing validated: Proper spawning behavior and enhanced aesthetics
-
-## Conclusion
-The game now provides a proper Tetris experience with pieces spawning within the visible grid and a consistently retro visual presentation that enhances the classic arcade gaming atmosphere.
diff --git a/SPAWN_AND_GRID_FIXES.md b/SPAWN_AND_GRID_FIXES.md
deleted file mode 100644
index 6e5a4dc..0000000
--- a/SPAWN_AND_GRID_FIXES.md
+++ /dev/null
@@ -1,167 +0,0 @@
-# Spawn Position and Grid Line Alignment Fix
-
-## Overview
-Fixed piece spawning to start one line higher (in the 2nd visible row) and corrected grid line alignment issues that occurred during window resizing and fullscreen mode.
-
-## Issues Resolved
-
-### 1. Piece Spawn Position Adjustment
-
-**Problem**: Pieces were spawning at the very top of the grid, user requested them to start one line higher (in the 2nd visible line).
-
-**Solution**: Changed spawn Y position from `0` to `-1`
-
-#### Code Changes:
-```cpp
-// BEFORE: Pieces spawn at top row (y = 0)
-cur = Piece{ bag.back(), 0, 3, 0 };
-nextPiece = Piece{ bag.back(), 0, 3, 0 };
-
-// AFTER: Pieces spawn one line higher (y = -1, appears in 2nd line)
-cur = Piece{ bag.back(), 0, 3, -1 };
-nextPiece = Piece{ bag.back(), 0, 3, -1 };
-```
-
-#### Files Modified:
-- **`src/Game.cpp`** - `spawn()` function
-- **`src/Game.cpp`** - `holdCurrent()` function
-
-**Result**: New pieces now appear in the 2nd visible line of the grid, giving players slightly more time to react and plan placement.
-
-### 2. Grid Line Alignment Fix
-
-**Problem**: Grid lines were appearing offset (to the right) instead of being properly centered within the game grid, especially noticeable during window resizing and fullscreen mode.
-
-**Root Cause**: Double application of content offsets - the grid position (`gridX`, `gridY`) already included content offsets, but the grid line drawing code was adding them again.
-
-#### Before (Incorrect):
-```cpp
-// Grid lines were offset due to double content offset application
-float lineX = gridX + x * finalBlockSize + contentOffsetX; // ❌ contentOffsetX added twice
-SDL_RenderLine(renderer, lineX, gridY + contentOffsetY, lineX, gridY + GRID_H + contentOffsetY);
-```
-
-#### After (Corrected):
-```cpp
-// Grid lines properly aligned within the grid boundaries
-float lineX = gridX + x * finalBlockSize; // ✅ contentOffsetX already in gridX
-SDL_RenderLine(renderer, lineX, gridY, lineX, gridY + GRID_H);
-```
-
-## Technical Details
-
-### Spawn Position Logic
-```cpp
-// Standard Tetris spawning with one-line buffer:
-// - X position: 3 (center of 10-wide grid)
-// - Y position: -1 (one line above top visible row)
-// - Rotation: 0 (default orientation)
-
-Piece newPiece = { pieceType, 0, 3, -1 };
-```
-
-### Grid Line Coordinate System
-```cpp
-// Proper coordinate calculation:
-// gridX and gridY already include contentOffsetX/Y for centering
-// Grid lines should be relative to these pre-offset coordinates
-
-// Vertical lines at each column boundary
-for (int x = 1; x < Game::COLS; ++x) {
-    float lineX = gridX + x * finalBlockSize;
-    SDL_RenderLine(renderer, lineX, gridY, lineX, gridY + GRID_H);
-}
-
-// Horizontal lines at each row boundary
-for (int y = 1; y < Game::ROWS; ++y) {
-    float lineY = gridY + y * finalBlockSize;
-    SDL_RenderLine(renderer, gridX, lineY, gridX + GRID_W, lineY);
-}
-```
-
-## Benefits
-
-### 1. Improved Gameplay Experience
-- **Better Timing**: Pieces appear one line higher, giving players more reaction time
-- **Strategic Advantage**: Slightly more space to plan piece placement
-- **Standard Feel**: Matches many classic Tetris implementations
-
-### 2. Visual Consistency
-- **Proper Grid Alignment**: Grid lines now perfectly align with cell boundaries
-- **Responsive Design**: Grid lines maintain proper alignment during window resize
-- **Fullscreen Compatibility**: Grid lines stay centered in fullscreen mode
-- **Professional Appearance**: Clean, precise visual grid structure
-
-### 3. Technical Robustness
-- **Coordinate System**: Simplified and corrected coordinate calculations
-- **Responsive Layout**: Grid lines properly scale with dynamic block sizes
-- **Window Management**: Handles all window states (windowed, maximized, fullscreen)
-
-## Testing Results
-
-### 1. Spawn Position Verification
-✅ **Visual Confirmation**: New pieces appear in 2nd visible line  
-✅ **Gameplay Feel**: Improved reaction time and strategic planning  
-✅ **Hold Function**: Held pieces also spawn at correct position  
-✅ **Game Flow**: Natural progression from spawn to placement  
-
-### 2. Grid Line Alignment Testing
-✅ **Windowed Mode**: Grid lines perfectly centered in normal window  
-✅ **Resize Behavior**: Grid lines stay aligned during window resize  
-✅ **Fullscreen Mode**: Grid lines maintain center alignment in fullscreen  
-✅ **Dynamic Scaling**: Grid lines scale correctly with different block sizes  
-
-### 3. Cross-Resolution Validation
-✅ **Multiple Resolutions**: Tested across various window sizes  
-✅ **Aspect Ratios**: Maintains alignment in different aspect ratios  
-✅ **Scaling Factors**: Proper alignment at all logical scale factors  
-
-## Visual Comparison
-
-### Spawn Position:
-```
-BEFORE:  [████████] ← Pieces spawn here (top line)
-         [        ]
-         [████████]
-
-AFTER:   [        ] ← Piece appears here first
-         [████████] ← Then moves into visible grid 
-         [████████]
-```
-
-### Grid Line Alignment:
-```
-BEFORE (Offset):        AFTER (Centered):
-┌─────────────┐         ┌─┬─┬─┬─┬─┬─┬─┬─┬─┬─┐
-│  ┬─┬─┬─┬─┬─┬│         ├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤ ← Perfect alignment
-│  ┼─┼─┼─┼─┼─┼│         ├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤
-│  ┼─┼─┼─┼─┼─┼│         └─┴─┴─┴─┴─┴─┴─┴─┴─┴─┘
-└─────────────┘
-↑ Lines offset right    ↑ Lines perfectly centered
-```
-
-## Impact on User Experience
-
-### 1. Gameplay Improvements
-- **Reaction Time**: Extra moment to assess and plan piece placement
-- **Strategic Depth**: More time for complex piece rotations and positioning
-- **Difficulty Balance**: Slightly more forgiving spawn timing
-
-### 2. Visual Polish
-- **Professional Grid**: Clean, precise cell boundaries
-- **Consistent Alignment**: Grid maintains perfection across all window states
-- **Enhanced Readability**: Clear visual reference for piece placement
-
-### 3. Technical Quality
-- **Responsive Design**: Proper scaling and alignment in all scenarios
-- **Code Quality**: Simplified and more maintainable coordinate system
-- **Cross-Platform**: Consistent behavior regardless of display configuration
-
-## Status: ✅ COMPLETED
-- Spawn position adjusted: Y coordinate moved from 0 to -1
-- Grid line alignment fixed: Removed duplicate content offset application
-- Testing validated: Proper alignment in windowed, resized, and fullscreen modes
-- User experience enhanced: Better gameplay timing and visual precision
-
-## Conclusion
-Both issues have been successfully resolved. The game now provides an optimal spawn experience with pieces appearing in the 2nd visible line, while the grid lines maintain perfect alignment regardless of window state or size changes. These improvements enhance both the gameplay experience and visual quality of the Tetris game.
diff --git a/UPGRADES.md b/UPGRADES.md
index 523ea5d..da5ea19 100644
--- a/UPGRADES.md
+++ b/UPGRADES.md
@@ -1,12 +1,14 @@
-# Tetris — Upgrade Roadmap
+# Spacetris — Upgrade Roadmap
 
 This document lists recommended code, architecture, tooling, and runtime upgrades for the native SDL3 Tetris project. Items are grouped, prioritized, and mapped to target files and effort estimates so you can plan incremental work.
 
 ## Short plan
+
 - Audit surface area and break tasks into small, testable PRs.
 - Start with low-risk safety and build improvements, then refactors (Gravity/Scoring/Board), then tests/CI, then UX polish and optional features.
 
 ## Checklist (high level)
+
 - [x] Make NES gravity table constant (constexpr) and move per-level multipliers out of a mutable global
   - Note: FRAMES_TABLE is now immutable inside `GravityManager`; per-level multipliers are instance-scoped in `GravityManager`.
 - [x] Extract GravityManager (SRP)
@@ -18,7 +20,7 @@ This document lists recommended code, architecture, tooling, and runtime upgrade
 - [x] Replace ad-hoc printf with SDL_Log or injected Logger service
   - Note: majority of printf/fprintf debug prints were replaced with `SDL_Log*` calls; a quick grep audit is recommended to find any remaining ad-hoc prints.
 - [x] Add unit tests (gravity conversion, level progression, line clear behavior)
-  - Note: a small test runner (`tests/GravityTests.cpp`) and the `tetris_tests` CMake target were added and run locally; gravity tests pass (see build-msvc test run). Converting to broader Catch2 suites is optional.
+  - Note: a small test runner (`tests/GravityTests.cpp`) and the `spacetris_tests` CMake target were added and run locally; gravity tests pass (see build-msvc test run). Converting to broader Catch2 suites is optional.
 - [ ] Add CI (build + tests) and code style checks
 - [ ] Improve input hit-testing for level popup and scalable UI
 - [ ] Add defensive guards (clamps, null checks) and const-correctness
@@ -27,6 +29,7 @@ This document lists recommended code, architecture, tooling, and runtime upgrade
 ---
 
 ## Rationale & Goals
+
 - Improve maintainability: split `Game` responsibilities into focused classes (SRP) so logic is testable.
 - Improve safety: remove mutable shared state (globals/`extern`) and minimize hidden side-effects.
 - Improve tuning: per-level and global gravity tuning must be instance-local and debug-friendly.
@@ -37,6 +40,7 @@ This document lists recommended code, architecture, tooling, and runtime upgrade
 ## Detailed tasks (prioritized)
 
 ### 1) Safety & small win (Low risk — 1–3 hours)
+
 - Make the NES frames-per-cell table `constexpr` and immutable.
   - File: `src/Game.cpp` (reverse any mutable anonymous namespace table changes)
   - Why: avoids accidental global mutation; makes compute deterministic.
@@ -48,18 +52,21 @@ This document lists recommended code, architecture, tooling, and runtime upgrade
 Deliverable: small patch to `Game.h`/`Game.cpp` and a rebuild verification.
 
 ### 2) Replace ad-hoc logging (Low risk — 0.5–1 hour)
+
 - Replace `printf` debug prints with `SDL_Log` or an injected `Logger` interface.
 - Prefer a build-time `#ifdef DEBUG` or runtime verbosity flag so release builds are quiet.
 
 Files: `src/Game.cpp`, any file using printf for debug.
 
 ### 3) Remove fragile globals / externs (Low risk — 1–2 hours)
+
 - Ensure all textures, fonts and shared resources are passed via `StateContext& ctx`.
 - Remove leftover `extern SDL_Texture* backgroundTex` or similar; make call-sites accept `SDL_Texture*` or read from `ctx`.
 
 Files: `src/main.cpp`, `src/states/MenuState.cpp`, other states.
 
 ### 4) Extract GravityManager (Medium risk — 2–6 hours)
+
 - Create `src/core/GravityManager.h|cpp` that encapsulates
   - the `constexpr` NES frames table (read-only)
   - per-instance multipliers
@@ -69,6 +76,7 @@ Files: `src/main.cpp`, `src/states/MenuState.cpp`, other states.
 Benefits: easier testing and isolated behavior change for future gravity models.
 
 ### 5) Extract Board/Scoring responsibilities (Medium — 4–8 hours)
+
 - Split `Game` into smaller collaborators:
   - `Board` — raw grid, collision, line detection/clear operations
   - `Scorer` — scoring rules, combo handling, level progression thresholds
@@ -78,6 +86,7 @@ Benefits: easier testing and isolated behavior change for future gravity models.
 Files: `src/Board.*`, `src/Scorer.*`, `src/PieceController.*`, adjust `Game` to compose them.
 
 ### 6) Unit tests & test infrastructure (Medium — 3–6 hours)
+
 - Add Catch2 or GoogleTest to `vcpkg.json` or as `FetchContent` in CMake.
 - Add tests:
   - Gravity conversion tests (frames→ms, per-level multipliers, global multiplier)
@@ -86,6 +95,7 @@ Files: `src/Board.*`, `src/Scorer.*`, `src/PieceController.*`, adjust `Game` to
 - Add a `tests/` CMake target and basic CI integration (see next section).
 
 ### 7) CI / Build checks (Medium — 2–4 hours)
+
 - Add GitHub Actions to build Debug/Release on Windows and run tests.
 - Add static analysis: clang-tidy/clang-format or cpplint configured for the project style.
 - Add a Pre-commit hook to run format checks.
@@ -93,6 +103,7 @@ Files: `src/Board.*`, `src/Scorer.*`, `src/PieceController.*`, adjust `Game` to
 Files: `.github/workflows/build.yml`, `.clang-format`, optional `clang-tidy` config.
 
 ### 8) UX and input correctness (Low–Medium — 1–3 hours)
+
 - Update level popup hit-testing to use the same computed button rectangles used for drawing.
   - Expose a function that returns vector<SDL_FRect> of button bounds from the popup draw logic.
 - Ensure popup background texture is stretched to the logical viewport and that overlay alpha is constant across window sizes.
@@ -101,6 +112,7 @@ Files: `.github/workflows/build.yml`, `.clang-format`, optional `clang-tidy` con
 Files: `src/main.cpp`, `src/states/MenuState.cpp`.
 
 ### 9) Runtime debug knobs (Low — 1 hour)
+
 - Add keys to increase/decrease `gravityGlobalMultiplier` (e.g., `[` and `]`) and reset to 1.0.
 - Show `gravityGlobalMultiplier` and per-level effective ms on HUD (already partly implemented).
 - Persist tuning to a small JSON file `settings/debug_tuning.json` (optional).
@@ -108,6 +120,7 @@ Files: `src/main.cpp`, `src/states/MenuState.cpp`.
 Files: `src/Game.h/cpp`, `src/main.cpp` HUD code.
 
 ### 10) Defensive & correctness improvements (Low — 2–4 hours)
+
 - Add null checks for SDL_CreateTextureFromSurface and related APIs; log and fallback gracefully.
 - Convert raw SDL_Texture* ownership to `std::unique_ptr` with custom deleter where appropriate, or centralize lifetime in a `ResourceManager`.
 - Add `const` qualifiers to getters where possible.
@@ -116,6 +129,7 @@ Files: `src/Game.h/cpp`, `src/main.cpp` HUD code.
 Files: various (`src/*.cpp`, `src/*.h`).
 
 ### 11) Packaging & build improvements (Low — 1–2 hours)
+
 - Verify `build-production.ps1` copies all required DLLs for SDL3 and SDL3_ttf from `vcpkg_installed` paths.
 - Add an automated packaging job to CI that creates a ZIP artifact on release tags.
 
@@ -124,6 +138,7 @@ Files: `build-production.ps1`, `.github/workflows/release.yml`.
 ---
 
 ## Suggested incremental PR plan
+
 1. Small safety PR: make frames table `constexpr`, move multipliers into `Game` instance, clamp values, and add SDL_Log usage. (1–3 hours)
 2. Global cleanup PR: remove `extern` textures and ensure all resource access goes through `StateContext`. (1–2 hours)
 3. Add debug knobs & HUD display improvements. (1 hour)
@@ -135,6 +150,7 @@ Files: `build-production.ps1`, `.github/workflows/release.yml`.
 ---
 
 ## Recommended quick wins (apply immediately)
+
 - Convert NES frames table to `constexpr` and clamp gravity to >= 1ms.
 - Replace `printf` with `SDL_Log` for debug output.
 - Pass `SDL_Texture*` via `StateContext` instead of `extern` globals (you already did this; check for leftovers with `grep` for "extern .*backgroundTex").
@@ -143,6 +159,7 @@ Files: `build-production.ps1`, `.github/workflows/release.yml`.
 ---
 
 ## Example: gravity computation (reference)
+
 ```cpp
 // gravity constants
 constexpr double NES_FPS = 60.0988;
@@ -162,9 +179,11 @@ double GravityManager::msForLevel(int level) const {
 ---
 
 ## Estimated total effort
+
 - Conservative: 16–36 hours depending on how far you split `Game` and add tests/CI.
 
 ## Next steps I can take for you now
+
 - Create a PR that converts the frames table to `constexpr` and moves multipliers into `Game` instance (small patch + build). (I can do this.)
 - Add a unit-test harness using Catch2 and a small GravityManager test.
 
diff --git a/assets/favicon/favicon.ico b/assets/favicon/favicon.ico
index 93f2c3d..0b70629 100644
Binary files a/assets/favicon/favicon.ico and b/assets/favicon/favicon.ico differ
diff --git a/assets/fonts/Exo2.ttf b/assets/fonts/Exo2.ttf
new file mode 100644
index 0000000..2170b15
Binary files /dev/null and b/assets/fonts/Exo2.ttf differ
diff --git a/assets/fonts/Orbitron.ttf b/assets/fonts/Orbitron.ttf
new file mode 100644
index 0000000..7d0d5e0
Binary files /dev/null and b/assets/fonts/Orbitron.ttf differ
diff --git a/assets/images/asteroids_001.png b/assets/images/asteroids_001.png
new file mode 100644
index 0000000..f488f51
Binary files /dev/null and b/assets/images/asteroids_001.png differ
diff --git a/assets/images/background.bmp b/assets/images/background.bmp
deleted file mode 100644
index 0274add..0000000
Binary files a/assets/images/background.bmp and /dev/null differ
diff --git a/assets/images/blocks90px_002.png b/assets/images/blocks90px_002.png
new file mode 100644
index 0000000..feb5a49
Binary files /dev/null and b/assets/images/blocks90px_002.png differ
diff --git a/assets/images/blocks90px_003.png b/assets/images/blocks90px_003.png
new file mode 100644
index 0000000..3757a67
Binary files /dev/null and b/assets/images/blocks90px_003.png differ
diff --git a/assets/images/cooperate_info.png b/assets/images/cooperate_info.png
new file mode 100644
index 0000000..4b586aa
Binary files /dev/null and b/assets/images/cooperate_info.png differ
diff --git a/assets/images/earth_back.jpg b/assets/images/earth_back.jpg
new file mode 100644
index 0000000..c9727b3
Binary files /dev/null and b/assets/images/earth_back.jpg differ
diff --git a/assets/images/game_over.bmp b/assets/images/game_over.bmp
deleted file mode 100644
index 5df819a..0000000
Binary files a/assets/images/game_over.bmp and /dev/null differ
diff --git a/assets/images/game_over.png b/assets/images/game_over.png
deleted file mode 100644
index 85397c8..0000000
Binary files a/assets/images/game_over.png and /dev/null differ
diff --git a/assets/images/gameplay.bmp b/assets/images/gameplay.bmp
deleted file mode 100644
index 348985a..0000000
Binary files a/assets/images/gameplay.bmp and /dev/null differ
diff --git a/assets/images/gameplay.webp b/assets/images/gameplay.webp
deleted file mode 100644
index 94909bc..0000000
Binary files a/assets/images/gameplay.webp and /dev/null differ
diff --git a/assets/images/gameplay1.bmp b/assets/images/gameplay1.bmp
deleted file mode 100644
index 85162a1..0000000
Binary files a/assets/images/gameplay1.bmp and /dev/null differ
diff --git a/assets/images/gameplay1.jpg b/assets/images/gameplay1.jpg
deleted file mode 100644
index 7fabbbc..0000000
Binary files a/assets/images/gameplay1.jpg and /dev/null differ
diff --git a/assets/images/gameplay2.bmp b/assets/images/gameplay2.bmp
deleted file mode 100644
index ed52e99..0000000
Binary files a/assets/images/gameplay2.bmp and /dev/null differ
diff --git a/assets/images/gameplay2.jpg b/assets/images/gameplay2.jpg
deleted file mode 100644
index 0081262..0000000
Binary files a/assets/images/gameplay2.jpg and /dev/null differ
diff --git a/assets/images/gameplay3.bmp b/assets/images/gameplay3.bmp
deleted file mode 100644
index 10ad47c..0000000
Binary files a/assets/images/gameplay3.bmp and /dev/null differ
diff --git a/assets/images/gameplay3.jpg b/assets/images/gameplay3.jpg
deleted file mode 100644
index 82fd36f..0000000
Binary files a/assets/images/gameplay3.jpg and /dev/null differ
diff --git a/assets/images/hold_panel.png b/assets/images/hold_panel.png
new file mode 100644
index 0000000..191ef4a
Binary files /dev/null and b/assets/images/hold_panel.png differ
diff --git a/assets/images/levels/level0.jpg b/assets/images/levels/level0.jpg
new file mode 100644
index 0000000..c2a0cf5
Binary files /dev/null and b/assets/images/levels/level0.jpg differ
diff --git a/assets/images/levels/level1.jpg b/assets/images/levels/level1.jpg
new file mode 100644
index 0000000..43d10a7
Binary files /dev/null and b/assets/images/levels/level1.jpg differ
diff --git a/assets/images/levels/level10.jpg b/assets/images/levels/level10.jpg
new file mode 100644
index 0000000..8b62e21
Binary files /dev/null and b/assets/images/levels/level10.jpg differ
diff --git a/assets/images/levels/level11.jpg b/assets/images/levels/level11.jpg
new file mode 100644
index 0000000..1588979
Binary files /dev/null and b/assets/images/levels/level11.jpg differ
diff --git a/assets/images/levels/level12.jpg b/assets/images/levels/level12.jpg
new file mode 100644
index 0000000..f553a7e
Binary files /dev/null and b/assets/images/levels/level12.jpg differ
diff --git a/assets/images/levels/level13.jpg b/assets/images/levels/level13.jpg
new file mode 100644
index 0000000..f505cf4
Binary files /dev/null and b/assets/images/levels/level13.jpg differ
diff --git a/assets/images/levels/level14.jpg b/assets/images/levels/level14.jpg
new file mode 100644
index 0000000..1c9801a
Binary files /dev/null and b/assets/images/levels/level14.jpg differ
diff --git a/assets/images/levels/level15.jpg b/assets/images/levels/level15.jpg
new file mode 100644
index 0000000..4de466b
Binary files /dev/null and b/assets/images/levels/level15.jpg differ
diff --git a/assets/images/levels/level16.jpg b/assets/images/levels/level16.jpg
new file mode 100644
index 0000000..256393d
Binary files /dev/null and b/assets/images/levels/level16.jpg differ
diff --git a/assets/images/levels/level17.jpg b/assets/images/levels/level17.jpg
new file mode 100644
index 0000000..f34534d
Binary files /dev/null and b/assets/images/levels/level17.jpg differ
diff --git a/assets/images/levels/level18.jpg b/assets/images/levels/level18.jpg
new file mode 100644
index 0000000..726b839
Binary files /dev/null and b/assets/images/levels/level18.jpg differ
diff --git a/assets/images/levels/level19.jpg b/assets/images/levels/level19.jpg
new file mode 100644
index 0000000..cb2a64d
Binary files /dev/null and b/assets/images/levels/level19.jpg differ
diff --git a/assets/images/levels/level2.jpg b/assets/images/levels/level2.jpg
new file mode 100644
index 0000000..e98da88
Binary files /dev/null and b/assets/images/levels/level2.jpg differ
diff --git a/assets/images/levels/level20.jpg b/assets/images/levels/level20.jpg
new file mode 100644
index 0000000..e2cc918
Binary files /dev/null and b/assets/images/levels/level20.jpg differ
diff --git a/assets/images/levels/level21.jpg b/assets/images/levels/level21.jpg
new file mode 100644
index 0000000..dd03a6b
Binary files /dev/null and b/assets/images/levels/level21.jpg differ
diff --git a/assets/images/levels/level22.jpg b/assets/images/levels/level22.jpg
new file mode 100644
index 0000000..1ec27fe
Binary files /dev/null and b/assets/images/levels/level22.jpg differ
diff --git a/assets/images/levels/level23.jpg b/assets/images/levels/level23.jpg
new file mode 100644
index 0000000..cf7aa39
Binary files /dev/null and b/assets/images/levels/level23.jpg differ
diff --git a/assets/images/levels/level24.jpg b/assets/images/levels/level24.jpg
new file mode 100644
index 0000000..f457f1e
Binary files /dev/null and b/assets/images/levels/level24.jpg differ
diff --git a/assets/images/levels/level25.jpg b/assets/images/levels/level25.jpg
new file mode 100644
index 0000000..cc83029
Binary files /dev/null and b/assets/images/levels/level25.jpg differ
diff --git a/assets/images/levels/level26.jpg b/assets/images/levels/level26.jpg
new file mode 100644
index 0000000..daf8d82
Binary files /dev/null and b/assets/images/levels/level26.jpg differ
diff --git a/assets/images/levels/level27.jpg b/assets/images/levels/level27.jpg
new file mode 100644
index 0000000..335fde2
Binary files /dev/null and b/assets/images/levels/level27.jpg differ
diff --git a/assets/images/levels/level28.jpg b/assets/images/levels/level28.jpg
new file mode 100644
index 0000000..5808398
Binary files /dev/null and b/assets/images/levels/level28.jpg differ
diff --git a/assets/images/levels/level29.jpg b/assets/images/levels/level29.jpg
new file mode 100644
index 0000000..e2d167d
Binary files /dev/null and b/assets/images/levels/level29.jpg differ
diff --git a/assets/images/levels/level3.jpg b/assets/images/levels/level3.jpg
new file mode 100644
index 0000000..fb34d25
Binary files /dev/null and b/assets/images/levels/level3.jpg differ
diff --git a/assets/images/levels/level30.jpg b/assets/images/levels/level30.jpg
new file mode 100644
index 0000000..31451a1
Binary files /dev/null and b/assets/images/levels/level30.jpg differ
diff --git a/assets/images/levels/level31.jpg b/assets/images/levels/level31.jpg
new file mode 100644
index 0000000..1544ada
Binary files /dev/null and b/assets/images/levels/level31.jpg differ
diff --git a/assets/images/levels/level32.jpg b/assets/images/levels/level32.jpg
new file mode 100644
index 0000000..9765ab6
Binary files /dev/null and b/assets/images/levels/level32.jpg differ
diff --git a/assets/images/levels/level4.jpg b/assets/images/levels/level4.jpg
new file mode 100644
index 0000000..3a614e4
Binary files /dev/null and b/assets/images/levels/level4.jpg differ
diff --git a/assets/images/levels/level5.jpg b/assets/images/levels/level5.jpg
new file mode 100644
index 0000000..6b8c544
Binary files /dev/null and b/assets/images/levels/level5.jpg differ
diff --git a/assets/images/levels/level6.jpg b/assets/images/levels/level6.jpg
new file mode 100644
index 0000000..7882fe9
Binary files /dev/null and b/assets/images/levels/level6.jpg differ
diff --git a/assets/images/levels/level7.jpg b/assets/images/levels/level7.jpg
new file mode 100644
index 0000000..415b12c
Binary files /dev/null and b/assets/images/levels/level7.jpg differ
diff --git a/assets/images/levels/level8.jpg b/assets/images/levels/level8.jpg
new file mode 100644
index 0000000..584c664
Binary files /dev/null and b/assets/images/levels/level8.jpg differ
diff --git a/assets/images/levels/level9.jpg b/assets/images/levels/level9.jpg
new file mode 100644
index 0000000..e2c69b4
Binary files /dev/null and b/assets/images/levels/level9.jpg differ
diff --git a/assets/images/logo.bmp b/assets/images/logo.bmp
deleted file mode 100644
index b7cc6c0..0000000
Binary files a/assets/images/logo.bmp and /dev/null differ
diff --git a/assets/images/logo.webp b/assets/images/logo.webp
deleted file mode 100644
index de63c6b..0000000
Binary files a/assets/images/logo.webp and /dev/null differ
diff --git a/assets/images/logo_small.bmp b/assets/images/logo_small.bmp
deleted file mode 100644
index 42557de..0000000
Binary files a/assets/images/logo_small.bmp and /dev/null differ
diff --git a/assets/images/logo_small.webp b/assets/images/logo_small.webp
deleted file mode 100644
index 18f1133..0000000
Binary files a/assets/images/logo_small.webp and /dev/null differ
diff --git a/assets/images/main_background.bmp b/assets/images/main_background.bmp
deleted file mode 100644
index 72ef709..0000000
Binary files a/assets/images/main_background.bmp and /dev/null differ
diff --git a/assets/images/main_screen.png b/assets/images/main_screen.png
new file mode 100644
index 0000000..fb37204
Binary files /dev/null and b/assets/images/main_screen.png differ
diff --git a/assets/images/main_screen_old.png b/assets/images/main_screen_old.png
new file mode 100644
index 0000000..3f593b8
Binary files /dev/null and b/assets/images/main_screen_old.png differ
diff --git a/assets/images/next_panel.png b/assets/images/next_panel.png
new file mode 100644
index 0000000..d57947a
Binary files /dev/null and b/assets/images/next_panel.png differ
diff --git a/assets/images/background.png b/assets/images/old/background.png
similarity index 100%
rename from assets/images/background.png
rename to assets/images/old/background.png
diff --git a/assets/images/background.webp b/assets/images/old/background.webp
similarity index 100%
rename from assets/images/background.webp
rename to assets/images/old/background.webp
diff --git a/assets/images/blocks001.bmp b/assets/images/old/blocks001.bmp
similarity index 100%
rename from assets/images/blocks001.bmp
rename to assets/images/old/blocks001.bmp
diff --git a/assets/images/blocks001.png b/assets/images/old/blocks001.png
similarity index 100%
rename from assets/images/blocks001.png
rename to assets/images/old/blocks001.png
diff --git a/assets/images/blocks3.bmp b/assets/images/old/blocks3.bmp
similarity index 100%
rename from assets/images/blocks3.bmp
rename to assets/images/old/blocks3.bmp
diff --git a/assets/images/blocks3.png b/assets/images/old/blocks3.png
similarity index 100%
rename from assets/images/blocks3.png
rename to assets/images/old/blocks3.png
diff --git a/assets/images/blocks90px_001.bmp b/assets/images/old/blocks90px_001.bmp
similarity index 100%
rename from assets/images/blocks90px_001.bmp
rename to assets/images/old/blocks90px_001.bmp
diff --git a/assets/images/main_background.webp b/assets/images/old/main_background.webp
similarity index 100%
rename from assets/images/main_background.webp
rename to assets/images/old/main_background.webp
diff --git a/assets/images/tetris_main_back_level0.jpg b/assets/images/old/tetris_main_back_level0.jpg
similarity index 100%
rename from assets/images/tetris_main_back_level0.jpg
rename to assets/images/old/tetris_main_back_level0.jpg
diff --git a/assets/images/tetris_main_level_0.webp b/assets/images/old/tetris_main_level_0.webp
similarity index 100%
rename from assets/images/tetris_main_level_0.webp
rename to assets/images/old/tetris_main_level_0.webp
diff --git a/assets/images/panel_score.png b/assets/images/panel_score.png
new file mode 100644
index 0000000..c0304cc
Binary files /dev/null and b/assets/images/panel_score.png differ
diff --git a/assets/images/spacetris.png b/assets/images/spacetris.png
new file mode 100644
index 0000000..0c7f249
Binary files /dev/null and b/assets/images/spacetris.png differ
diff --git a/assets/images/statistics_panel.png b/assets/images/statistics_panel.png
new file mode 100644
index 0000000..19a59c1
Binary files /dev/null and b/assets/images/statistics_panel.png differ
diff --git a/assets/images/tetris_main_back_level0.bmp b/assets/images/tetris_main_back_level0.bmp
deleted file mode 100644
index 0274add..0000000
Binary files a/assets/images/tetris_main_back_level0.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level0x.bmp b/assets/images/tetris_main_back_level0x.bmp
deleted file mode 100644
index 58ae7f9..0000000
Binary files a/assets/images/tetris_main_back_level0x.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level1.bmp b/assets/images/tetris_main_back_level1.bmp
deleted file mode 100644
index 4f68b82..0000000
Binary files a/assets/images/tetris_main_back_level1.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level1.jpg b/assets/images/tetris_main_back_level1.jpg
deleted file mode 100644
index 1e2e3e7..0000000
Binary files a/assets/images/tetris_main_back_level1.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level10.bmp b/assets/images/tetris_main_back_level10.bmp
deleted file mode 100644
index 0ef0916..0000000
Binary files a/assets/images/tetris_main_back_level10.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level10.jpg b/assets/images/tetris_main_back_level10.jpg
deleted file mode 100644
index 6a0d8a7..0000000
Binary files a/assets/images/tetris_main_back_level10.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level11.bmp b/assets/images/tetris_main_back_level11.bmp
deleted file mode 100644
index 5edc3c9..0000000
Binary files a/assets/images/tetris_main_back_level11.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level11.jpg b/assets/images/tetris_main_back_level11.jpg
deleted file mode 100644
index 68fbea9..0000000
Binary files a/assets/images/tetris_main_back_level11.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level12.bmp b/assets/images/tetris_main_back_level12.bmp
deleted file mode 100644
index 610aff7..0000000
Binary files a/assets/images/tetris_main_back_level12.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level12.jpg b/assets/images/tetris_main_back_level12.jpg
deleted file mode 100644
index 2236820..0000000
Binary files a/assets/images/tetris_main_back_level12.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level13.bmp b/assets/images/tetris_main_back_level13.bmp
deleted file mode 100644
index 42c52f8..0000000
Binary files a/assets/images/tetris_main_back_level13.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level13.jpg b/assets/images/tetris_main_back_level13.jpg
deleted file mode 100644
index 0f85309..0000000
Binary files a/assets/images/tetris_main_back_level13.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level14.bmp b/assets/images/tetris_main_back_level14.bmp
deleted file mode 100644
index 6a26df4..0000000
Binary files a/assets/images/tetris_main_back_level14.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level14.jpg b/assets/images/tetris_main_back_level14.jpg
deleted file mode 100644
index fb7b55a..0000000
Binary files a/assets/images/tetris_main_back_level14.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level15.bmp b/assets/images/tetris_main_back_level15.bmp
deleted file mode 100644
index d4759a3..0000000
Binary files a/assets/images/tetris_main_back_level15.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level15.jpg b/assets/images/tetris_main_back_level15.jpg
deleted file mode 100644
index fadc33e..0000000
Binary files a/assets/images/tetris_main_back_level15.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level16.bmp b/assets/images/tetris_main_back_level16.bmp
deleted file mode 100644
index 68e6540..0000000
Binary files a/assets/images/tetris_main_back_level16.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level16.jpg b/assets/images/tetris_main_back_level16.jpg
deleted file mode 100644
index 0506f1b..0000000
Binary files a/assets/images/tetris_main_back_level16.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level17.bmp b/assets/images/tetris_main_back_level17.bmp
deleted file mode 100644
index 2e3aa72..0000000
Binary files a/assets/images/tetris_main_back_level17.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level17.jpg b/assets/images/tetris_main_back_level17.jpg
deleted file mode 100644
index 238cfa2..0000000
Binary files a/assets/images/tetris_main_back_level17.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level18.bmp b/assets/images/tetris_main_back_level18.bmp
deleted file mode 100644
index ac921ec..0000000
Binary files a/assets/images/tetris_main_back_level18.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level18.jpg b/assets/images/tetris_main_back_level18.jpg
deleted file mode 100644
index a347b0a..0000000
Binary files a/assets/images/tetris_main_back_level18.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level19.bmp b/assets/images/tetris_main_back_level19.bmp
deleted file mode 100644
index 6d5f762..0000000
Binary files a/assets/images/tetris_main_back_level19.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level19.jpg b/assets/images/tetris_main_back_level19.jpg
deleted file mode 100644
index 2159b45..0000000
Binary files a/assets/images/tetris_main_back_level19.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level2.bmp b/assets/images/tetris_main_back_level2.bmp
deleted file mode 100644
index 3632a65..0000000
Binary files a/assets/images/tetris_main_back_level2.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level2.jpg b/assets/images/tetris_main_back_level2.jpg
deleted file mode 100644
index 276e092..0000000
Binary files a/assets/images/tetris_main_back_level2.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level20.bmp b/assets/images/tetris_main_back_level20.bmp
deleted file mode 100644
index 26c88ff..0000000
Binary files a/assets/images/tetris_main_back_level20.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level20.jpg b/assets/images/tetris_main_back_level20.jpg
deleted file mode 100644
index a805fcf..0000000
Binary files a/assets/images/tetris_main_back_level20.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level21.bmp b/assets/images/tetris_main_back_level21.bmp
deleted file mode 100644
index 8426613..0000000
Binary files a/assets/images/tetris_main_back_level21.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level21.jpg b/assets/images/tetris_main_back_level21.jpg
deleted file mode 100644
index b0b3c56..0000000
Binary files a/assets/images/tetris_main_back_level21.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level22.bmp b/assets/images/tetris_main_back_level22.bmp
deleted file mode 100644
index d835bbf..0000000
Binary files a/assets/images/tetris_main_back_level22.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level22.jpg b/assets/images/tetris_main_back_level22.jpg
deleted file mode 100644
index fa41309..0000000
Binary files a/assets/images/tetris_main_back_level22.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level23.bmp b/assets/images/tetris_main_back_level23.bmp
deleted file mode 100644
index 74fc4e5..0000000
Binary files a/assets/images/tetris_main_back_level23.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level23.jpg b/assets/images/tetris_main_back_level23.jpg
deleted file mode 100644
index a9f1165..0000000
Binary files a/assets/images/tetris_main_back_level23.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level24.bmp b/assets/images/tetris_main_back_level24.bmp
deleted file mode 100644
index 9157494..0000000
Binary files a/assets/images/tetris_main_back_level24.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level24.jpg b/assets/images/tetris_main_back_level24.jpg
deleted file mode 100644
index c2e1d1d..0000000
Binary files a/assets/images/tetris_main_back_level24.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level25.bmp b/assets/images/tetris_main_back_level25.bmp
deleted file mode 100644
index e30380b..0000000
Binary files a/assets/images/tetris_main_back_level25.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level25.jpg b/assets/images/tetris_main_back_level25.jpg
deleted file mode 100644
index ef6c890..0000000
Binary files a/assets/images/tetris_main_back_level25.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level26.bmp b/assets/images/tetris_main_back_level26.bmp
deleted file mode 100644
index 7785436..0000000
Binary files a/assets/images/tetris_main_back_level26.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level26.jpg b/assets/images/tetris_main_back_level26.jpg
deleted file mode 100644
index 96e9c26..0000000
Binary files a/assets/images/tetris_main_back_level26.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level27.bmp b/assets/images/tetris_main_back_level27.bmp
deleted file mode 100644
index fda9b7e..0000000
Binary files a/assets/images/tetris_main_back_level27.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level27.jpg b/assets/images/tetris_main_back_level27.jpg
deleted file mode 100644
index effe5a8..0000000
Binary files a/assets/images/tetris_main_back_level27.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level28.bmp b/assets/images/tetris_main_back_level28.bmp
deleted file mode 100644
index 5fa0311..0000000
Binary files a/assets/images/tetris_main_back_level28.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level28.jpg b/assets/images/tetris_main_back_level28.jpg
deleted file mode 100644
index caa71cd..0000000
Binary files a/assets/images/tetris_main_back_level28.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level29.bmp b/assets/images/tetris_main_back_level29.bmp
deleted file mode 100644
index 1d114c3..0000000
Binary files a/assets/images/tetris_main_back_level29.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level29.jpg b/assets/images/tetris_main_back_level29.jpg
deleted file mode 100644
index b77e3a5..0000000
Binary files a/assets/images/tetris_main_back_level29.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level3.bmp b/assets/images/tetris_main_back_level3.bmp
deleted file mode 100644
index c1f4530..0000000
Binary files a/assets/images/tetris_main_back_level3.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level3.jpg b/assets/images/tetris_main_back_level3.jpg
deleted file mode 100644
index 0ead72f..0000000
Binary files a/assets/images/tetris_main_back_level3.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level30.bmp b/assets/images/tetris_main_back_level30.bmp
deleted file mode 100644
index b55b99c..0000000
Binary files a/assets/images/tetris_main_back_level30.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level30.jpg b/assets/images/tetris_main_back_level30.jpg
deleted file mode 100644
index 6503d7e..0000000
Binary files a/assets/images/tetris_main_back_level30.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level31.bmp b/assets/images/tetris_main_back_level31.bmp
deleted file mode 100644
index 796c424..0000000
Binary files a/assets/images/tetris_main_back_level31.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level31.jpg b/assets/images/tetris_main_back_level31.jpg
deleted file mode 100644
index c480b0b..0000000
Binary files a/assets/images/tetris_main_back_level31.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level32.bmp b/assets/images/tetris_main_back_level32.bmp
deleted file mode 100644
index 65edfec..0000000
Binary files a/assets/images/tetris_main_back_level32.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level32.jpg b/assets/images/tetris_main_back_level32.jpg
deleted file mode 100644
index d345caa..0000000
Binary files a/assets/images/tetris_main_back_level32.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level4.bmp b/assets/images/tetris_main_back_level4.bmp
deleted file mode 100644
index a68f9ff..0000000
Binary files a/assets/images/tetris_main_back_level4.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level4.jpg b/assets/images/tetris_main_back_level4.jpg
deleted file mode 100644
index ce36388..0000000
Binary files a/assets/images/tetris_main_back_level4.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level5.bmp b/assets/images/tetris_main_back_level5.bmp
deleted file mode 100644
index d27d2d8..0000000
Binary files a/assets/images/tetris_main_back_level5.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level5.jpg b/assets/images/tetris_main_back_level5.jpg
deleted file mode 100644
index 37db308..0000000
Binary files a/assets/images/tetris_main_back_level5.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level6.bmp b/assets/images/tetris_main_back_level6.bmp
deleted file mode 100644
index ebaeca9..0000000
Binary files a/assets/images/tetris_main_back_level6.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level6.jpg b/assets/images/tetris_main_back_level6.jpg
deleted file mode 100644
index 559898d..0000000
Binary files a/assets/images/tetris_main_back_level6.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level7.bmp b/assets/images/tetris_main_back_level7.bmp
deleted file mode 100644
index f92d223..0000000
Binary files a/assets/images/tetris_main_back_level7.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level7.jpg b/assets/images/tetris_main_back_level7.jpg
deleted file mode 100644
index d010cbc..0000000
Binary files a/assets/images/tetris_main_back_level7.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level8.bmp b/assets/images/tetris_main_back_level8.bmp
deleted file mode 100644
index 8f392c1..0000000
Binary files a/assets/images/tetris_main_back_level8.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level8.jpg b/assets/images/tetris_main_back_level8.jpg
deleted file mode 100644
index 382468a..0000000
Binary files a/assets/images/tetris_main_back_level8.jpg and /dev/null differ
diff --git a/assets/images/tetris_main_back_level9.bmp b/assets/images/tetris_main_back_level9.bmp
deleted file mode 100644
index 2962513..0000000
Binary files a/assets/images/tetris_main_back_level9.bmp and /dev/null differ
diff --git a/assets/images/tetris_main_back_level9.jpg b/assets/images/tetris_main_back_level9.jpg
deleted file mode 100644
index 955c1c5..0000000
Binary files a/assets/images/tetris_main_back_level9.jpg and /dev/null differ
diff --git a/assets/music/48997.wav b/assets/music/48997.wav
deleted file mode 100644
index 4ea7d20..0000000
Binary files a/assets/music/48997.wav and /dev/null differ
diff --git a/assets/music/Every Block You Take.mp3 b/assets/music/Every Block You Take.mp3
new file mode 100644
index 0000000..d8534b5
Binary files /dev/null and b/assets/music/Every Block You Take.mp3 differ
diff --git a/assets/music/Every Block You Take.ogg b/assets/music/Every Block You Take.ogg
new file mode 100644
index 0000000..f3857b1
Binary files /dev/null and b/assets/music/Every Block You Take.ogg differ
diff --git a/assets/music/GONG0.WAV b/assets/music/GONG0.WAV
deleted file mode 100644
index 3a54e08..0000000
Binary files a/assets/music/GONG0.WAV and /dev/null differ
diff --git a/assets/music/amazing.ogg b/assets/music/amazing.ogg
new file mode 100644
index 0000000..fe54410
Binary files /dev/null and b/assets/music/amazing.ogg differ
diff --git a/assets/music/asteroid-destroy.mp3 b/assets/music/asteroid-destroy.mp3
new file mode 100644
index 0000000..f6338cc
Binary files /dev/null and b/assets/music/asteroid-destroy.mp3 differ
diff --git a/assets/music/boom_tetris.ogg b/assets/music/boom_tetris.ogg
new file mode 100644
index 0000000..00e9c3d
Binary files /dev/null and b/assets/music/boom_tetris.ogg differ
diff --git a/assets/music/great_move.ogg b/assets/music/great_move.ogg
new file mode 100644
index 0000000..4045c7e
Binary files /dev/null and b/assets/music/great_move.ogg differ
diff --git a/assets/music/hard_drop_001.mp3 b/assets/music/hard_drop_001.mp3
new file mode 100644
index 0000000..7b6f1fa
Binary files /dev/null and b/assets/music/hard_drop_001.mp3 differ
diff --git a/assets/music/hard_drop_001.ogg b/assets/music/hard_drop_001.ogg
new file mode 100644
index 0000000..81d7f32
Binary files /dev/null and b/assets/music/hard_drop_001.ogg differ
diff --git a/assets/music/impressive.ogg b/assets/music/impressive.ogg
new file mode 100644
index 0000000..e0eecf9
Binary files /dev/null and b/assets/music/impressive.ogg differ
diff --git a/assets/music/keep_that_ryhtm.ogg b/assets/music/keep_that_ryhtm.ogg
new file mode 100644
index 0000000..562c2f3
Binary files /dev/null and b/assets/music/keep_that_ryhtm.ogg differ
diff --git a/assets/music/lets_go.ogg b/assets/music/lets_go.ogg
new file mode 100644
index 0000000..caab19a
Binary files /dev/null and b/assets/music/lets_go.ogg differ
diff --git a/assets/music/new_level.mp3 b/assets/music/new_level.mp3
new file mode 100644
index 0000000..d8d4522
Binary files /dev/null and b/assets/music/new_level.mp3 differ
diff --git a/assets/music/new_level.ogg b/assets/music/new_level.ogg
new file mode 100644
index 0000000..116b95d
Binary files /dev/null and b/assets/music/new_level.ogg differ
diff --git a/assets/music/nice_combo.ogg b/assets/music/nice_combo.ogg
new file mode 100644
index 0000000..3b8c400
Binary files /dev/null and b/assets/music/nice_combo.ogg differ
diff --git a/assets/music/nice_combo.wav b/assets/music/nice_combo.wav
index 8f7e99c..2210784 100644
Binary files a/assets/music/nice_combo.wav and b/assets/music/nice_combo.wav differ
diff --git a/assets/music/smooth_clear.ogg b/assets/music/smooth_clear.ogg
new file mode 100644
index 0000000..87bf3d7
Binary files /dev/null and b/assets/music/smooth_clear.ogg differ
diff --git a/assets/music/triple_strike.ogg b/assets/music/triple_strike.ogg
new file mode 100644
index 0000000..f96843c
Binary files /dev/null and b/assets/music/triple_strike.ogg differ
diff --git a/assets/music/well_played.ogg b/assets/music/well_played.ogg
new file mode 100644
index 0000000..5e199e0
Binary files /dev/null and b/assets/music/well_played.ogg differ
diff --git a/assets/music/wonderful.ogg b/assets/music/wonderful.ogg
new file mode 100644
index 0000000..1bfee75
Binary files /dev/null and b/assets/music/wonderful.ogg differ
diff --git a/assets/music/you_fire.ogg b/assets/music/you_fire.ogg
new file mode 100644
index 0000000..3fabd06
Binary files /dev/null and b/assets/music/you_fire.ogg differ
diff --git a/assets/music/you_re_unstoppable.ogg b/assets/music/you_re_unstoppable.ogg
new file mode 100644
index 0000000..ed0fdf8
Binary files /dev/null and b/assets/music/you_re_unstoppable.ogg differ
diff --git a/assets/videos/spacetris_intro.mp4 b/assets/videos/spacetris_intro.mp4
new file mode 100644
index 0000000..f53718f
Binary files /dev/null and b/assets/videos/spacetris_intro.mp4 differ
diff --git a/build-debug-and-run.bat b/build-debug-and-run.bat
new file mode 100644
index 0000000..2444e97
--- /dev/null
+++ b/build-debug-and-run.bat
@@ -0,0 +1,11 @@
+@echo off
+REM Build and run debug executable for the Spacetris project
+SETLOCAL
+cd /d "%~dp0"
+cmake --build build-msvc --config Debug
+if errorlevel 1 (
+    echo Build failed.
+    exit /b %ERRORLEVEL%
+)
+"%~dp0build-msvc\Debug\spacetris.exe"
+ENDLOCAL
diff --git a/build-debug-and-run.ps1 b/build-debug-and-run.ps1
new file mode 100644
index 0000000..05f536a
--- /dev/null
+++ b/build-debug-and-run.ps1
@@ -0,0 +1,162 @@
+param(
+    [switch]$NoRun
+)
+
+# Ensure script runs from repo root (where this script lives)
+$root = Split-Path -Parent $MyInvocation.MyCommand.Path
+Set-Location $root
+
+Write-Host "Working directory: $PWD"
+
+# Require Visual Studio 18 (2026)
+function Find-VisualStudio {
+    $vswherePaths = @()
+    if ($env:ProgramFiles -ne $null) { $vswherePaths += Join-Path $env:ProgramFiles 'Microsoft Visual Studio\Installer\vswhere.exe' }
+    if (${env:ProgramFiles(x86)} -ne $null) { $vswherePaths += Join-Path ${env:ProgramFiles(x86)} 'Microsoft Visual Studio\Installer\vswhere.exe' }
+
+    foreach ($p in $vswherePaths) {
+        if (Test-Path $p) { return @{Tool=$p} }
+    }
+
+    return $null
+}
+
+function Get-VS18 {
+    $fv = Find-VisualStudio
+    $vswhere = $null
+    if ($fv -and $fv.Tool) { $vswhere = $fv.Tool }
+    if ($vswhere) {
+        try {
+            $inst18 = & $vswhere -version "[18.0,19.0)" -products * -requires Microsoft.Component.MSBuild -property installationPath 2>$null
+            if ($inst18) {
+                $candidate = 'Visual Studio 18 2026'
+                $has = & cmake --help | Select-String -Pattern $candidate -SimpleMatch -Quiet
+                if ($has) {
+                    $inst18Path = $inst18.Trim()
+                    $vcvars = Join-Path $inst18Path 'VC\\Auxiliary\\Build\\vcvarsall.bat'
+                    if (Test-Path $vcvars) { return @{Generator=$candidate; InstallPath=$inst18Path} }
+                    Write-Error "Visual Studio 18 detected at $inst18Path but C++ toolchain (vcvarsall.bat) is missing. Install the Desktop development with C++ workload."
+                }
+            }
+        } catch {
+            # fall through to path checks below
+        }
+    }
+
+    # fallback: check common install locations (allow for non-standard drive)
+    $commonPaths = @(
+        'D:\Program Files\Microsoft Visual Studio\2026\Community',
+        'D:\Program Files\Microsoft Visual Studio\2026\Professional',
+        'D:\Program Files\Microsoft Visual Studio\2026\Enterprise',
+        'C:\Program Files\Microsoft Visual Studio\2026\Community',
+        'C:\Program Files\Microsoft Visual Studio\2026\Professional',
+        'C:\Program Files\Microsoft Visual Studio\2026\Enterprise'
+    )
+    foreach ($p in $commonPaths) {
+        if (Test-Path $p) {
+            $vcvars = Join-Path $p 'VC\\Auxiliary\\Build\\vcvarsall.bat'
+            if (Test-Path $vcvars) { return @{Generator='Visual Studio 18 2026'; InstallPath=$p} }
+        }
+    }
+
+    return $null
+}
+
+# Resolve vcpkg root/toolchain (prefer env, then C:\vcpkg, then repo-local)
+$vcpkgRoot = $env:VCPKG_ROOT
+if (-not $vcpkgRoot -or -not (Test-Path $vcpkgRoot)) {
+    if (Test-Path 'C:\vcpkg') {
+        $vcpkgRoot = 'C:\vcpkg'
+        $env:VCPKG_ROOT = $vcpkgRoot
+    } elseif (Test-Path (Join-Path $root 'vcpkg')) {
+        $vcpkgRoot = Join-Path $root 'vcpkg'
+        $env:VCPKG_ROOT = $vcpkgRoot
+    }
+}
+
+$toolchainFile = $null
+if ($vcpkgRoot) {
+    $candidateToolchain = Join-Path $vcpkgRoot 'scripts\buildsystems\vcpkg.cmake'
+    if (Test-Path $candidateToolchain) { $toolchainFile = $candidateToolchain }
+}
+
+# Determine VS18 generator and reconfigure build-msvc if needed
+$preferred = Get-VS18
+if ($preferred) {
+    Write-Host "Detected Visual Studio: $($preferred.Generator) at $($preferred.InstallPath)"
+} else {
+    Write-Error "Visual Studio 18 (2026) with Desktop development with C++ workload not found. Install VS 2026 and retry."
+    exit 1
+}
+
+if (-not $toolchainFile) {
+    Write-Error "vcpkg toolchain not found. Set VCPKG_ROOT or install vcpkg (expected scripts/buildsystems/vcpkg.cmake)."
+    exit 1
+}
+
+# If build-msvc exists, check CMakeCache generator
+$cacheFile = Join-Path $root 'build-msvc\CMakeCache.txt'
+$reconfigured = $false
+if (-not (Test-Path $cacheFile)) {
+    Write-Host "Configuring build-msvc with generator $($preferred.Generator) and vcpkg toolchain $toolchainFile"
+    & cmake -S . -B build-msvc -G "$($preferred.Generator)" -A x64 -DCMAKE_TOOLCHAIN_FILE="$toolchainFile" -DVCPKG_TARGET_TRIPLET=x64-windows
+    $cfgExit = $LASTEXITCODE
+    if ($cfgExit -ne 0) { Write-Error "CMake configure failed with exit code $cfgExit"; exit $cfgExit }
+    $reconfigured = $true
+} else {
+    $genLine = Get-Content $cacheFile | Select-String -Pattern 'CMAKE_GENERATOR:INTERNAL=' -SimpleMatch
+    $toolLine = Get-Content $cacheFile | Select-String -Pattern 'CMAKE_TOOLCHAIN_FILE:FILEPATH=' -SimpleMatch
+    $currentGen = $null
+    $currentTool = $null
+    if ($genLine) { $currentGen = $genLine -replace '.*CMAKE_GENERATOR:INTERNAL=(.*)','$1' }
+    if ($toolLine) { $currentTool = $toolLine -replace '.*CMAKE_TOOLCHAIN_FILE:FILEPATH=(.*)','$1' }
+    $needsReconfigure = $false
+    if ($currentGen -ne $preferred.Generator) { $needsReconfigure = $true }
+    if (-not $currentTool -or ($currentTool -ne $toolchainFile)) { $needsReconfigure = $true }
+
+    if ($needsReconfigure) {
+        Write-Host "Generator or toolchain changed; cleaning build-msvc directory for fresh configure."
+        Remove-Item -Path (Join-Path $root 'build-msvc') -Recurse -Force -ErrorAction SilentlyContinue
+        Write-Host "Configuring build-msvc with generator $($preferred.Generator) and toolchain $toolchainFile"
+        & cmake -S . -B build-msvc -G "$($preferred.Generator)" -A x64 -DCMAKE_TOOLCHAIN_FILE="$toolchainFile" -DVCPKG_TARGET_TRIPLET=x64-windows
+        $cfgExit = $LASTEXITCODE
+        if ($cfgExit -ne 0) { Write-Error "CMake configure failed with exit code $cfgExit"; exit $cfgExit }
+        $reconfigured = $true
+    } else {
+        Write-Host "CMake cache matches required generator and toolchain."
+    }
+}
+
+# Build Debug configuration
+Write-Host "Running: cmake --build build-msvc --config Debug"
+& cmake --build build-msvc --config Debug
+$buildExit = $LASTEXITCODE
+if ($buildExit -ne 0) {
+    Write-Error "Build failed with exit code $buildExit"
+    $vcpkgLog = Join-Path $root 'build-msvc\vcpkg-manifest-install.log'
+    if (Test-Path $vcpkgLog) {
+        $log = Get-Content $vcpkgLog -Raw
+        if ($log -match 'Unable to find a valid Visual Studio instance') {
+            Write-Error "vcpkg could not locate a valid Visual Studio 18 toolchain. Install VS 2026 with Desktop development with C++ workload and retry."
+        }
+    }
+
+    exit $buildExit
+}
+
+if ($NoRun) {
+    Write-Host "Build succeeded; skipping run because -NoRun was specified."
+    exit 0
+}
+
+$exePath = Join-Path $root "build-msvc\Debug\spacetris.exe"
+if (-not (Test-Path $exePath)) {
+    Write-Error "Executable not found: $exePath"
+    exit 1
+}
+
+Write-Host "Launching: $exePath"
+# Launch the executable and wait for it to exit so the caller sees its output.
+& $exePath
+
+exit $LASTEXITCODE
diff --git a/build-production-mac.sh b/build-production-mac.sh
new file mode 100644
index 0000000..18191db
--- /dev/null
+++ b/build-production-mac.sh
@@ -0,0 +1,368 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# macOS Production Build Script for the SDL3 Spacetris project
+# Mirrors the Windows PowerShell workflow but uses common POSIX tooling so it
+# can be executed on macOS runners or local developer machines.
+
+PROJECT_NAME="spacetris"
+BUILD_DIR="build-release"
+OUTPUT_DIR="dist"
+PACKAGE_DIR=""
+VERSION="$(date +"%Y.%m.%d")"
+CLEAN=0
+PACKAGE_ONLY=0
+PACKAGE_RUNTIME_DIR=""
+APP_ICON_SRC="assets/favicon/favicon-512x512.png"
+APP_ICON_ICNS="assets/favicon/AppIcon.icns"
+
+print_usage() {
+    cat <<'USAGE'
+Usage: ./build-production-mac.sh [options]
+
+Options:
+  -c, --clean          Remove existing build + dist folders before running
+  -p, --package-only   Skip compilation and only rebuild the distributable
+  -o, --output DIR     Customize output directory (default: dist)
+  -h, --help           Show this help text
+USAGE
+}
+
+log() {
+    local level=$1; shift
+    case "$level" in
+        INFO) printf '\033[36m[INFO]\033[0m %s\n' "$*" ;;
+        OK) printf '\033[32m[ OK ]\033[0m %s\n' "$*" ;;
+        WARN) printf '\033[33m[WARN]\033[0m %s\n' "$*" ;;
+        ERR) printf '\033[31m[ERR ]\033[0m %s\n' "$*" ;;
+        *) printf '%s\n' "$*" ;;
+    esac
+}
+
+require_macos() {
+    if [[ $(uname) != "Darwin" ]]; then
+        log ERR "This script is intended for macOS hosts."
+        exit 1
+    fi
+}
+
+parse_args() {
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            -c|--clean) CLEAN=1; shift ;;
+            -p|--package-only) PACKAGE_ONLY=1; shift ;;
+            -o|--output)
+                if [[ $# -lt 2 ]]; then
+                    log ERR "--output requires a directory argument"
+                    exit 1
+                fi
+                OUTPUT_DIR="$2"; shift 2 ;;
+            -h|--help) print_usage; exit 0 ;;
+            *)
+                log ERR "Unknown argument: $1"
+                print_usage
+                exit 1 ;;
+        esac
+    done
+}
+
+configure_paths() {
+    PACKAGE_DIR="${OUTPUT_DIR}/SpacetrisGame-mac"
+}
+
+generate_icns_if_needed() {
+    if [[ -f "$APP_ICON_ICNS" ]]; then
+        return
+    fi
+    if [[ ! -f "$APP_ICON_SRC" ]]; then
+        log WARN "Icon source PNG not found ($APP_ICON_SRC); skipping .icns generation"
+        return
+    fi
+    if ! command -v iconutil >/dev/null 2>&1; then
+        log WARN "iconutil not available; skipping .icns generation"
+        return
+    fi
+    log INFO "Generating AppIcon.icns from $APP_ICON_SRC ..."
+    tmpdir=$(mktemp -d)
+    iconset="$tmpdir/AppIcon.iconset"
+    mkdir -p "$iconset"
+    # Generate required sizes from 512 base; sips will downscale
+    for size in 16 32 64 128 256 512; do
+        sips -s format png "$APP_ICON_SRC" --resampleHeightWidth $size $size --out "$iconset/icon_${size}x${size}.png" >/dev/null
+        sips -s format png "$APP_ICON_SRC" --resampleHeightWidth $((size*2)) $((size*2)) --out "$iconset/icon_${size}x${size}@2x.png" >/dev/null
+    done
+    iconutil -c icns "$iconset" -o "$APP_ICON_ICNS" || log WARN "iconutil failed to create .icns"
+    rm -rf "$tmpdir"
+    if [[ -f "$APP_ICON_ICNS" ]]; then
+        log OK "Created $APP_ICON_ICNS"
+    fi
+}
+
+clean_previous() {
+    if (( CLEAN )); then
+        log INFO "Cleaning previous build artifacts..."
+        rm -rf "$BUILD_DIR" "$OUTPUT_DIR"
+        log OK "Previous artifacts removed"
+    fi
+}
+
+configure_and_build() {
+    if (( PACKAGE_ONLY )); then
+        return
+    fi
+
+    log INFO "Configuring CMake (Release)..."
+    cmake -S . -B "$BUILD_DIR" -DCMAKE_BUILD_TYPE=Release
+    log OK "CMake configure complete"
+
+    log INFO "Building Release target..."
+    cmake --build "$BUILD_DIR" --config Release
+    log OK "Build finished"
+}
+
+resolve_executable() {
+    local candidates=(
+        "$BUILD_DIR/Release/${PROJECT_NAME}"
+        "$BUILD_DIR/${PROJECT_NAME}"
+        "$BUILD_DIR/${PROJECT_NAME}.app/Contents/MacOS/${PROJECT_NAME}"
+    )
+
+    for path in "${candidates[@]}"; do
+        if [[ -x "$path" ]]; then
+            EXECUTABLE_PATH="$path"
+            break
+        fi
+    done
+
+    if [[ -z ${EXECUTABLE_PATH:-} ]]; then
+        log ERR "Unable to locate built executable."
+        exit 1
+    fi
+
+    if [[ "$EXECUTABLE_PATH" == *.app/Contents/MacOS/* ]]; then
+        APP_BUNDLE_PATH="${EXECUTABLE_PATH%/Contents/MacOS/*}"
+    else
+        APP_BUNDLE_PATH=""
+    fi
+
+    log OK "Using executable: $EXECUTABLE_PATH"
+}
+
+prepare_package_dir() {
+    log INFO "Creating package directory $PACKAGE_DIR ..."
+    rm -rf "$PACKAGE_DIR"
+    mkdir -p "$PACKAGE_DIR"
+}
+
+copy_binary_or_bundle() {
+    if [[ -n ${APP_BUNDLE_PATH:-} ]]; then
+        log INFO "Copying app bundle..."
+        rsync -a "$APP_BUNDLE_PATH" "$PACKAGE_DIR/"
+        local app_name="${APP_BUNDLE_PATH##*/}"
+        PACKAGE_BINARY="${app_name}/Contents/MacOS/${PROJECT_NAME}"
+        PACKAGE_RUNTIME_DIR="$PACKAGE_DIR/${app_name}/Contents/MacOS"
+    else
+        log INFO "Copying executable..."
+        cp "$EXECUTABLE_PATH" "$PACKAGE_DIR/${PROJECT_NAME}"
+        chmod +x "$PACKAGE_DIR/${PROJECT_NAME}"
+        PACKAGE_BINARY="${PROJECT_NAME}"
+        PACKAGE_RUNTIME_DIR="$PACKAGE_DIR"
+    fi
+    log OK "Binary ready (${PACKAGE_BINARY})"
+}
+
+copy_assets() {
+    if [[ -n ${APP_BUNDLE_PATH:-} ]]; then
+        log INFO "Assets already bundled inside the .app; skipping external copy."
+        return
+    fi
+    log INFO "Copying assets..."
+    local folders=("assets" "fonts")
+    for folder in "${folders[@]}"; do
+        if [[ -d "$folder" ]]; then
+            rsync -a "$folder" "$PACKAGE_DIR/"
+            log OK "Copied $folder"
+        fi
+    done
+    if [[ -f "FreeSans.ttf" ]]; then
+        cp "FreeSans.ttf" "$PACKAGE_DIR/"
+        log OK "Copied FreeSans.ttf"
+    fi
+}
+
+copy_dependencies() {
+    log INFO "Collecting dynamic libraries from vcpkg..."
+    local triplets=("arm64-osx" "x64-osx" "universal-osx")
+    local bases=("$BUILD_DIR/vcpkg_installed" "vcpkg_installed")
+    local copied_names=()
+
+    for base in "${bases[@]}"; do
+        for triplet in "${triplets[@]}"; do
+            for sub in lib bin; do
+                local dir="$base/$triplet/$sub"
+                if [[ -d "$dir" ]]; then
+                    while IFS= read -r -d '' dylib; do
+                        local name=$(basename "$dylib")
+                        local seen=0
+                        for existing in "${copied_names[@]}"; do
+                            if [[ "$existing" == "$name" ]]; then
+                                seen=1
+                                break
+                            fi
+                        done
+                        if (( !seen )); then
+                            cp "$dylib" "$PACKAGE_RUNTIME_DIR/"
+                            copied_names+=("$name")
+                            log OK "Copied $name"
+                        fi
+                    done < <(find "$dir" -maxdepth 1 -type f -name '*.dylib' -print0)
+                fi
+            done
+        done
+    done
+
+    if [[ ${#copied_names[@]} -eq 0 ]]; then
+        log WARN "No .dylib files found; ensure vcpkg installed macOS triplet dependencies."
+    fi
+}
+
+ensure_rpath() {
+    local binary="$PACKAGE_DIR/$PACKAGE_BINARY"
+    if [[ ! -f "$binary" ]]; then
+        return
+    fi
+    if command -v otool >/dev/null 2>&1 && command -v install_name_tool >/dev/null 2>&1; then
+        if ! otool -l "$binary" | grep -A2 LC_RPATH | grep -q '@executable_path'; then
+            log INFO "Adding @executable_path rpath"
+            install_name_tool -add_rpath "@executable_path" "$binary"
+        fi
+    fi
+}
+
+create_launchers() {
+    local launch_command="./${PROJECT_NAME}"
+    if [[ "$PACKAGE_BINARY" == *.app/Contents/MacOS/* ]]; then
+        local app_dir="${PACKAGE_BINARY%%/Contents/*}"
+        launch_command="open \"./${app_dir}\""
+    fi
+
+        cat > "$PACKAGE_DIR/Launch-Spacetris.command" <<EOF
+    #!/usr/bin/env bash
+    cd "\$(dirname \"\$0\")"
+    ${launch_command}
+    EOF
+    chmod +x "$PACKAGE_DIR/Launch-Spacetris.command"
+
+    cat > "$PACKAGE_DIR/README-mac.txt" <<EOF
+Spacetris SDL3 Game - macOS Release $VERSION
+=========================================
+
+Requirements:
+- macOS 12 Monterey or newer (Apple Silicon or Intel)
+- GPU with Metal support
+
+Installation:
+1. Unzip the archive anywhere (e.g., ~/Games/Spacetris).
+2. Ensure the executable bit stays set (script already does this).
+3. Double-click Launch-Spacetris.command or run the binary/app manually from Terminal or Finder.
+
+Files:
+- spacetris / Launch-Spacetris.command (start the game)
+- assets/ (art, audio, fonts)
+- *.dylib from SDL3 and related dependencies
+- FreeSans.ttf font
+
+Enjoy!
+EOF
+    log OK "Created README and launcher"
+}
+
+validate_package() {
+    log INFO "Validating package contents..."
+    local missing=()
+    local required=("$PACKAGE_BINARY")
+    if [[ -z ${APP_BUNDLE_PATH:-} ]]; then
+        required+=(assets FreeSans.ttf)
+    fi
+    for required in "${required[@]}"; do
+        if [[ ! -e "$PACKAGE_DIR/$required" ]]; then
+            missing+=("$required")
+        fi
+    done
+    if (( ${#missing[@]} > 0 )); then
+        log WARN "Missing: ${missing[*]}"
+    else
+        log OK "Package looks complete"
+    fi
+}
+
+create_zip() {
+    mkdir -p "$OUTPUT_DIR"
+    local zip_name="SpacetrisGame-mac-${VERSION}.zip"
+    local zip_path="$OUTPUT_DIR/$zip_name"
+    log INFO "Creating zip archive $zip_path ..."
+    if command -v ditto >/dev/null 2>&1; then
+        ditto -c -k --keepParent "$PACKAGE_DIR" "$zip_path"
+    else
+        (cd "$OUTPUT_DIR" && zip -r "$zip_name" "$(basename "$PACKAGE_DIR")")
+    fi
+    log OK "Zip created"
+}
+
+main() {
+    parse_args "$@"
+    require_macos
+    configure_paths
+
+    if [[ ! -f "CMakeLists.txt" ]]; then
+        log ERR "Run from repository root (CMakeLists.txt missing)."
+        exit 1
+    fi
+
+    log INFO "======================================"
+    log INFO "   macOS Production Builder"
+    log INFO "======================================"
+    log INFO "Version: $VERSION"
+    log INFO "Output:  $OUTPUT_DIR"
+
+    clean_previous
+    generate_icns_if_needed
+    configure_and_build
+    resolve_executable
+    prepare_package_dir
+    copy_binary_or_bundle
+    copy_assets
+    copy_dependencies
+    ensure_rpath
+    create_launchers
+    validate_package
+    create_zip
+    create_dmg
+
+    log INFO "Done. Package available at $PACKAGE_DIR"
+}
+
+create_dmg() {
+    if [[ -z ${APP_BUNDLE_PATH:-} ]]; then
+        log INFO "No app bundle detected; skipping DMG creation"
+        return
+    fi
+    
+    local app_name="${APP_BUNDLE_PATH##*/}"
+    local dmg_name="SpacetrisGame-mac-${VERSION}.dmg"
+    local dmg_path="$OUTPUT_DIR/$dmg_name"
+    
+    if [[ ! -f "scripts/create-dmg.sh" ]]; then
+        log WARN "scripts/create-dmg.sh not found; skipping DMG creation"
+        return
+    fi
+    
+    log INFO "Creating DMG installer: $dmg_path"
+    bash scripts/create-dmg.sh "$PACKAGE_DIR/$app_name" "$dmg_path" || log WARN "DMG creation failed"
+    
+    if [[ -f "$dmg_path" ]]; then
+        log OK "DMG created: $dmg_path"
+    fi
+}
+
+main "$@"
diff --git a/build-production.bat b/build-production.bat
index 6d6dd6f..7d49444 100644
--- a/build-production.bat
+++ b/build-production.bat
@@ -1,11 +1,11 @@
 @echo off
-REM Simple Production Build Script for Tetris SDL3
+REM Simple Production Build Script for Spacetris SDL3
 REM This batch file builds and packages the game for distribution
 
 setlocal EnableDelayedExpansion
 
 echo ======================================
-echo    Tetris SDL3 Production Builder
+echo    Spacetris SDL3 Production Builder
 echo ======================================
 echo.
 
@@ -45,13 +45,13 @@ cd ..
 
 REM Create distribution directory
 echo Creating distribution package...
-mkdir "dist\TetrisGame"
+mkdir "dist\SpacetrisGame"
 
 REM Copy executable
-if exist "build-release\Release\tetris.exe" (
-    copy "build-release\Release\tetris.exe" "dist\TetrisGame\"
-) else if exist "build-release\tetris.exe" (
-    copy "build-release\tetris.exe" "dist\TetrisGame\"
+if exist "build-release\Release\spacetris.exe" (
+    copy "build-release\Release\spacetris.exe" "dist\SpacetrisGame\"
+) else if exist "build-release\spacetris.exe" (
+    copy "build-release\spacetris.exe" "dist\SpacetrisGame\"
 ) else (
     echo Error: Executable not found!
     pause
@@ -60,27 +60,52 @@ if exist "build-release\Release\tetris.exe" (
 
 REM Copy assets
 echo Copying game assets...
-if exist "assets" xcopy "assets" "dist\TetrisGame\assets\" /E /I /Y
-if exist "FreeSans.ttf" copy "FreeSans.ttf" "dist\TetrisGame\"
+if exist "assets" xcopy "assets" "dist\SpacetrisGame\assets\" /E /I /Y
+if exist "FreeSans.ttf" copy "FreeSans.ttf" "dist\SpacetrisGame\"
 
 REM Copy SDL DLLs (if available) - SDL_image no longer needed
 echo Copying dependencies...
-if exist "vcpkg_installed\x64-windows\bin\SDL3.dll" copy "vcpkg_installed\x64-windows\bin\SDL3.dll" "dist\TetrisGame\"
-if exist "vcpkg_installed\x64-windows\bin\SDL3_ttf.dll" copy "vcpkg_installed\x64-windows\bin\SDL3_ttf.dll" "dist\TetrisGame\"
+set "PackageDir=dist\SpacetrisGame"
+set "copiedDependencies=0"
+
+call :CopyDependencyDir "build-release\vcpkg_installed\x64-windows\bin"
+call :CopyDependencyDir "vcpkg_installed\x64-windows\bin"
+
+if "%copiedDependencies%"=="0" (
+    echo Warning: No dependency DLLs were copied. Ensure vcpkg release binaries exist.
+)
 
 REM Create launcher batch file
-echo @echo off > "dist\TetrisGame\Launch-Tetris.bat"
-echo cd /d "%%~dp0" >> "dist\TetrisGame\Launch-Tetris.bat"
-echo tetris.exe >> "dist\TetrisGame\Launch-Tetris.bat"
-echo pause >> "dist\TetrisGame\Launch-Tetris.bat"
+echo @echo off > "dist\SpacetrisGame\Launch-Spacetris.bat"
+echo cd /d "%%~dp0" >> "dist\SpacetrisGame\Launch-Spacetris.bat"
+echo spacetris.exe >> "dist\SpacetrisGame\Launch-Spacetris.bat"
+echo pause >> "dist\SpacetrisGame\Launch-Spacetris.bat"
 
 echo.
 echo ======================================
 echo    Build Completed Successfully!
 echo ======================================
-echo Package location: dist\TetrisGame
+echo Package location: dist\SpacetrisGame
 echo.
 echo The game is ready for distribution!
-echo Users can run tetris.exe or Launch-Tetris.bat
+echo Users can run spacetris.exe or Launch-Spacetris.bat
 echo.
 pause
+goto :eof
+
+:CopyDependencyDir
+set "dllDir=%~1"
+if not exist "%dllDir%" goto :eof
+echo Scanning %dllDir% for DLLs...
+for %%F in ("%dllDir%\*.dll") do (
+    if exist "%%~fF" (
+        if exist "%PackageDir%\%%~nxF" (
+            copy /Y "%%~fF" "%PackageDir%\%%~nxF" >nul
+        ) else (
+            copy "%%~fF" "%PackageDir%\" >nul
+        )
+        echo Copied %%~nxF
+        set "copiedDependencies=1"
+    )
+)
+goto :eof
diff --git a/build-production.ps1 b/build-production.ps1
index 7be74ea..53a672b 100644
--- a/build-production.ps1
+++ b/build-production.ps1
@@ -1,10 +1,10 @@
 #!/usr/bin/env pwsh
 <#
 .SYNOPSIS
-Production Build Script for Tetris SDL3 Game
+Production Build Script for Spacetris SDL3 Game
 
 .DESCRIPTION
-This script builds the Tetris game for production distribution, including:
+This script builds the Spacetris game for production distribution, including:
 - Clean Release build with optimizations
 - Dependency collection and packaging
 - Asset organization and validation
@@ -31,9 +31,9 @@ param(
 )
 
 # Configuration
-$ProjectName = "tetris"
+$ProjectName = "spacetris"
 $BuildDir = "build-release"
-$PackageDir = Join-Path $OutputDir "TetrisGame"
+$PackageDir = Join-Path $OutputDir "SpacetrisGame"
 $Version = Get-Date -Format "yyyy.MM.dd"
 
 # Colors for output
@@ -52,7 +52,7 @@ function Write-Warning { Write-ColorOutput Yellow $args }
 function Write-Error { Write-ColorOutput Red $args }
 
 Write-Info "======================================"
-Write-Info "   Tetris SDL3 Production Builder"
+Write-Info "   Spacetris SDL3 Production Builder"
 Write-Info "======================================"
 Write-Info "Version: $Version"
 Write-Info "Output: $PackageDir"
@@ -155,32 +155,28 @@ foreach ($font in $FontFiles) {
 }
 
 # Step 7: Copy dependencies (DLLs)
-Write-Info "Copying SDL3 dependencies..."
-$VcpkgInstalled = Join-Path "vcpkg_installed" "x64-windows"
-if (Test-Path $VcpkgInstalled) {
-    $DllPaths = @(
-        Join-Path $VcpkgInstalled "bin\SDL3.dll",
-        Join-Path $VcpkgInstalled "bin\SDL3_ttf.dll"
-    )
-    
-    $CopiedDlls = 0
-    foreach ($dll in $DllPaths) {
-        if (Test-Path $dll) {
-            Copy-Item $dll $PackageDir
-            $dllName = Split-Path $dll -Leaf
-            Write-Success "Copied $dllName"
-            $CopiedDlls++
-        } else {
-            Write-Warning "Warning: $dll not found"
+Write-Info "Copying runtime dependencies..."
+$buildVcpkgBin = Join-Path (Join-Path $BuildDir "vcpkg_installed") "x64-windows/bin"
+$repoVcpkgBin = "vcpkg_installed/x64-windows/bin"
+$DependencyDirs = @($buildVcpkgBin, $repoVcpkgBin) | Where-Object { $_ } | Select-Object -Unique
+
+$copiedNames = @{}
+foreach ($dir in $DependencyDirs) {
+    if (!(Test-Path $dir)) { continue }
+    Write-Info "Scanning $dir for DLLs..."
+    $dlls = Get-ChildItem -Path $dir -Filter "*.dll" -ErrorAction SilentlyContinue
+    foreach ($dll in $dlls) {
+        $dest = Join-Path $PackageDir $dll.Name
+        Copy-Item $dll.FullName $dest -Force
+        if (-not $copiedNames.ContainsKey($dll.Name)) {
+            Write-Success "Copied $($dll.Name)"
+            $copiedNames[$dll.Name] = $true
         }
     }
-    
-    if ($CopiedDlls -eq 0) {
-        Write-Warning "No SDL DLLs found in vcpkg installation"
-        Write-Warning "You may need to manually copy SDL3 DLLs to the package"
-    }
-} else {
-    Write-Warning "vcpkg installation not found. SDL DLLs must be manually copied."
+}
+
+if ($copiedNames.Count -eq 0) {
+    Write-Warning "No dependency DLLs were copied. Please ensure vcpkg has been built for Release."
 }
 
 # Step 8: Create README and batch file for easy launching
@@ -188,7 +184,7 @@ Write-Info "Creating distribution files..."
 
 # Create README
 $ReadmeContent = @"
-Tetris SDL3 Game - Release $Version
+Spacetris SDL3 Game - Release $Version
 =====================================
 
 ## System Requirements
@@ -198,7 +194,7 @@ Tetris SDL3 Game - Release $Version
 
 ## Installation
 1. Extract all files to a folder
-2. Run tetris.exe
+2. Run spacetris.exe
 
 ## Controls
 - Arrow Keys: Move pieces
@@ -210,17 +206,17 @@ Tetris SDL3 Game - Release $Version
 - Esc: Return to menu
 
 ## Troubleshooting
-- If the game doesn't start, ensure all DLL files are in the same folder as tetris.exe
+- If the game doesn't start, ensure all DLL files are in the same folder as spacetris.exe
 - For audio issues, check that your audio drivers are up to date
 - The game requires the assets folder to be in the same directory as the executable
 
 ## Files Included
-- tetris.exe - Main game executable
-- SDL3.dll, SDL3_ttf.dll - Required libraries
+- spacetris.exe - Main game executable
+- SDL3.dll, SDL3_ttf.dll, SDL3_image.dll - Required libraries
 - assets/ - Game assets (images, music, fonts)
 - FreeSans.ttf - Main font file
 
-Enjoy playing Tetris!
+Enjoy playing Spacetris!
 "@
 
 $ReadmeContent | Out-File -FilePath (Join-Path $PackageDir "README.txt") -Encoding UTF8
@@ -234,8 +230,8 @@ tetris.exe
 pause
 "@
 
-$BatchContent | Out-File -FilePath (Join-Path $PackageDir "Launch-Tetris.bat") -Encoding ASCII
-Write-Success "Created Launch-Tetris.bat"
+$BatchContent | Out-File -FilePath (Join-Path $PackageDir "Launch-Spacetris.bat") -Encoding ASCII
+Write-Success "Created Launch-Spacetris.bat"
 
 # Step 9: Validate package
 Write-Info "🔍 Validating package..."
@@ -263,7 +259,7 @@ $PackageSize = (Get-ChildItem $PackageDir -Recurse | Measure-Object -Property Le
 $PackageSizeMB = [math]::Round($PackageSize / 1MB, 2)
 
 # Step 11: Create ZIP archive (optional)
-$ZipPath = Join-Path $OutputDir "TetrisGame-$Version.zip"
+$ZipPath = Join-Path $OutputDir "SpacetrisGame-$Version.zip"
 Write-Info "📁 Creating ZIP archive..."
 try {
     Compress-Archive -Path $PackageDir -DestinationPath $ZipPath -Force
@@ -284,5 +280,5 @@ if (Test-Path $ZipPath) {
 }
 Write-Info ""
 Write-Info "The game is ready for distribution!"
-Write-Info "Users can run tetris.exe or Launch-Tetris.bat"
+Write-Info "Users can run spacetris.exe or Launch-Spacetris.bat"
 Write-Info ""
diff --git a/challenge_mode.md b/challenge_mode.md
new file mode 100644
index 0000000..22f6b0b
--- /dev/null
+++ b/challenge_mode.md
@@ -0,0 +1,287 @@
+# Spacetris — Challenge Mode (Asteroids) Implementation Spec for VS Code AI Agent
+
+> Goal: Implement/extend **CHALLENGE** gameplay in Spacetris (not a separate mode), based on 100 levels with **asteroid** prefilled blocks that must be destroyed to advance.
+
+---
+
+## 1) High-level Requirements
+
+### Modes
+- Existing mode remains **ENDLESS**.
+- Add/extend **CHALLENGE** mode with **100 levels**.
+
+### Core Challenge Loop
+- Each level starts with **prefilled obstacle blocks** called **Asteroids**.
+- **Level N** starts with **N asteroids** (placed increasingly higher as level increases).
+- Player advances to the next level when **ALL asteroids are destroyed**.
+- Gravity (and optionally lock pressure) increases per level.
+
+### Asteroid concept
+Asteroids are special blocks placed into the grid at level start:
+- They are **not** player-controlled pieces.
+- They have **types** and **hit points** (how many times they must be cleared via line clears).
+
+---
+
+## 2) Asteroid Types & Rules
+
+Define asteroid types and their behavior:
+
+### A) Normal Asteroid
+- `hitsRemaining = 1`
+- Removed when its row is cleared once.
+- Never moves (no gravity).
+
+### B) Armored Asteroid
+- `hitsRemaining = 2`
+- On first line clear that includes it: decrement hits and change to cracked visual state.
+- On second clear: removed.
+- Never moves (no gravity).
+
+### C) Falling Asteroid
+- `hitsRemaining = 2`
+- On first clear: decrement hits, then **becomes gravity-enabled** (drops until resting).
+- On second clear: removed.
+
+### D) Core Asteroid (late levels)
+- `hitsRemaining = 3`
+- On each clear: decrement hits and change visual state.
+- After first hit (or after any hit — choose consistent rule) it becomes gravity-enabled.
+- On final clear: removed (optionally trigger bigger VFX).
+
+**Important:** These are all within the same CHALLENGE mode.
+
+---
+
+## 3) Level Progression Rules (100 Levels)
+
+### Asteroid Count
+- `asteroidsToPlace = level` (Level 1 -> 1 asteroid, Level 2 -> 2 asteroids, …)
+- Recommendation for implementation safety:
+  - If `level` becomes too large to place comfortably, still place `level` but distribute across more rows and allow overlaps only if empty.
+  - If needed, implement a soft cap for placement attempts (avoid infinite loops). If cannot place all, place as many as possible and log/telemetry.
+
+### Placement Height / Region
+- Early levels: place in bottom 2–4 rows.
+- Mid levels: bottom 6–10 rows.
+- Late levels: up to ~half board height.
+- Use a function to define a `minRow..maxRow` region based on `level`.
+
+Example guidance:
+- `maxRow = boardHeight - 1`
+- `minRow = boardHeight - 1 - clamp(2 + level/3, 2, boardHeight/2)`
+
+### Type Distribution by Level (suggested)
+- Levels 1–9: Normal only
+- Levels 10–19: add Armored (small %)
+- Levels 20–59: add Falling (increasing %)
+- Levels 60–100: add Core (increasing %)
+
+---
+
+## 4) Difficulty Scaling
+
+### Gravity Speed Scaling
+Implement per-level gravity scale:
+- `gravity = baseGravity * (1.0f + level * 0.02f)` (tune)
+- Or use a curve/table.
+
+Optional additional scaling:
+- Reduced lock delay slightly at higher levels
+- Slightly faster DAS/ARR (if implemented)
+
+---
+
+## 5) Win/Lose Conditions
+
+### Level Completion
+- Level completes when: `asteroidsRemaining == 0`
+- Then:
+  - Clear board (or keep board — choose one consistent behavior; recommended: **clear board** for clean progression).
+  - Show short transition (optional).
+  - Load next level, until level 100.
+- After level 100 completion: show completion screen + stats.
+
+### Game Over
+- Standard Spacetris game over: stack reaches spawn/top (existing behavior).
+
+---
+
+## 6) Rendering / UI Requirements
+
+### Visual Differentiation
+Asteroids must be visually distinct from normal tetromino blocks.
+
+Provide visual states:
+- Normal: rock texture
+- Armored: plated / darker
+- Cracked: visible cracks
+- Falling: glow rim / hazard stripes
+- Core: pulsing inner core
+
+Minimum UI additions (Challenge):
+- Display `LEVEL: X/100`
+- Display `ASTEROIDS REMAINING: N` (or an icon counter)
+
+---
+
+## 7) Data Structures (C++ Guidance)
+
+### Cell Representation
+Each grid cell must store:
+- Whether occupied
+- If occupied: is it part of normal tetromino or an asteroid
+- If asteroid: type + hitsRemaining + gravityEnabled + visualState
+
+Suggested enums:
+```cpp
+enum class CellKind { Empty, Tetromino, Asteroid };
+
+enum class AsteroidType { Normal, Armored, Falling, Core };
+
+struct AsteroidCell {
+    AsteroidType type;
+    uint8_t hitsRemaining;
+    bool gravityEnabled;
+    uint8_t visualState; // optional (e.g. 0..n)
+};
+
+struct Cell {
+    CellKind kind;
+    // For Tetromino: color/type id
+    // For Asteroid: AsteroidCell data
+};
+````
+
+---
+
+## 8) Line Clear Processing Rules (Important)
+
+When a line is cleared:
+
+1. Detect full rows (existing).
+2. For each cleared row:
+
+   * For each cell:
+
+     * If `kind == Asteroid`:
+
+       * `hitsRemaining--`
+       * If `hitsRemaining == 0`: remove (cell becomes Empty)
+       * Else:
+
+         * Update its visual state (cracked/damaged)
+         * If asteroid type is Falling/Core and rule says it becomes gravity-enabled on first hit:
+
+           * `gravityEnabled = true`
+3. After clearing rows and collapsing the grid:
+
+   * Apply **asteroid gravity step**:
+
+     * For all gravity-enabled asteroid cells: let them fall until resting.
+     * Ensure stable iteration (bottom-up scan).
+4. Recount asteroids remaining; if 0 -> level complete.
+
+**Note:** Decide whether gravity-enabled asteroids fall immediately after the first hit (recommended) and whether they fall as individual cells (recommended) or as clusters (optional later).
+
+---
+
+## 9) Asteroid Gravity Algorithm (Simple + Stable)
+
+Implement a pass:
+
+* Iterate from bottom-2 to top (bottom-up).
+* If cell is gravity-enabled asteroid and below is empty:
+
+  * Move down by one
+* Repeat passes until no movement OR do a while-loop per cell to drop fully.
+
+Be careful to avoid skipping cells when moving:
+
+* Use bottom-up iteration and drop-to-bottom logic.
+
+---
+
+## 10) Level Generation (Deterministic Option)
+
+To make challenge reproducible:
+
+* Use a seed: `seed = baseSeed + level`
+* Place asteroids with RNG based on level seed.
+
+Placement constraints:
+
+* Avoid placing asteroids in the spawn zone/top rows.
+* Avoid creating impossible scenarios too early:
+
+  * For early levels, ensure at least one vertical shaft exists.
+
+---
+
+## 11) Tasks Checklist for AI Agent
+
+### A) Add Challenge Level System
+
+* [ ] Add `currentLevel (1..100)` and `mode == CHALLENGE`.
+* [ ] Add `StartChallengeLevel(level)` function.
+* [ ] Reset/prepare board state for each level (recommended: clear board).
+
+### B) Asteroid Placement
+
+* [ ] Implement `PlaceAsteroids(level)`:
+
+  * Determine region of rows
+  * Choose type distribution
+  * Place `level` asteroid cells into empty spots
+
+### C) Line Clear Hook
+
+* [ ] Modify existing line clear code:
+
+  * Apply asteroid hit logic
+  * Update visuals
+  * Enable gravity where required
+
+### D) Gravity-enabled Asteroids
+
+* [ ] Implement `ApplyAsteroidGravity()` after line clears and board collapse.
+
+### E) Level Completion
+
+* [ ] Track `asteroidsRemaining`.
+* [ ] When 0: trigger level transition and `StartChallengeLevel(level+1)`.
+
+### F) UI
+
+* [ ] Add level & asteroids remaining display.
+
+---
+
+## 12) Acceptance Criteria
+
+* Level 1 spawns exactly 1 asteroid.
+* Level N spawns N asteroids.
+* Destroying asteroids requires:
+
+  * Normal: 1 clear
+  * Armored: 2 clears
+  * Falling: 2 clears + becomes gravity-enabled after first hit
+  * Core: 3 clears (+ gravity-enabled rule)
+* Player advances only when all asteroids are destroyed.
+* Gravity increases by level and is clearly noticeable by mid-levels.
+* No infinite loops in placement or gravity.
+* Challenge works end-to-end through level 100.
+
+---
+
+## 13) Notes / Tuning Hooks
+
+Expose tuning constants:
+
+* `baseGravity`
+* `gravityPerLevel`
+* `minAsteroidRow(level)`
+* `typeDistribution(level)` weights
+* `coreGravityOnHit` rule
+
+---
\ No newline at end of file
diff --git a/cmake/MacBundleInfo.plist.in b/cmake/MacBundleInfo.plist.in
new file mode 100644
index 0000000..8720039
--- /dev/null
+++ b/cmake/MacBundleInfo.plist.in
@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>CFBundleDevelopmentRegion</key>
+    <string>English</string>
+    <key>CFBundleExecutable</key>
+    <string>${MACOSX_BUNDLE_EXECUTABLE_NAME}</string>
+    <key>CFBundleIdentifier</key>
+    <string>com.example.spacetris</string>
+    <key>CFBundleInfoDictionaryVersion</key>
+    <string>6.0</string>
+    <key>CFBundleName</key>
+    <string>Spacetris</string>
+    <key>CFBundlePackageType</key>
+    <string>APPL</string>
+    <key>CFBundleShortVersionString</key>
+    <string>1.0</string>
+    <key>CFBundleVersion</key>
+    <string>1.0</string>
+    <key>CFBundleIconFile</key>
+    <string>AppIcon</string>
+    <key>LSMinimumSystemVersion</key>
+    <string>12.0</string>
+    <key>NSHighResolutionCapable</key>
+    <true/>
+</dict>
+</plist>
diff --git a/cmake/ProductionBuild.cmake b/cmake/ProductionBuild.cmake
index d81c519..6c5a0d3 100644
--- a/cmake/ProductionBuild.cmake
+++ b/cmake/ProductionBuild.cmake
@@ -12,12 +12,19 @@ if(CMAKE_BUILD_TYPE STREQUAL "Release")
         set(CMAKE_EXE_LINKER_FLAGS_RELEASE "${CMAKE_EXE_LINKER_FLAGS_RELEASE} /OPT:REF /OPT:ICF")
         
         # Enable whole program optimization
-        set_target_properties(tetris PROPERTIES 
+        # Detect game target (spacetris only)
+        if(TARGET spacetris)
+            set(GAME_TARGET spacetris)
+        else()
+            message(FATAL_ERROR "No game target found (expected 'spacetris')")
+        endif()
+
+        set_target_properties(${GAME_TARGET} PROPERTIES 
             INTERPROCEDURAL_OPTIMIZATION_RELEASE TRUE
         )
-        
+
         # Set subsystem to Windows (no console) for release
-        set_target_properties(tetris PROPERTIES
+        set_target_properties(${GAME_TARGET} PROPERTIES
             WIN32_EXECUTABLE TRUE
             LINK_FLAGS_RELEASE "/SUBSYSTEM:WINDOWS /ENTRY:mainCRTStartup"
         )
@@ -30,53 +37,77 @@ if(CMAKE_BUILD_TYPE STREQUAL "Release")
     endif()
 endif()
 
+# Ensure we have a GAME_TARGET set (spacetris only)
+if(NOT DEFINED GAME_TARGET)
+    if(TARGET spacetris)
+        set(GAME_TARGET spacetris)
+    else()
+        message(FATAL_ERROR "No game target found (expected 'spacetris')")
+    endif()
+endif()
+
 # Custom target for creating distribution package (renamed to avoid conflict with CPack)
 if(WIN32)
     # Windows-specific packaging
-    add_custom_target(dist_package
-        COMMAND ${CMAKE_COMMAND} -E echo "Creating Windows distribution package..."
-        COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_BINARY_DIR}/package/TetrisGame"
-        COMMAND ${CMAKE_COMMAND} -E copy "$<TARGET_FILE:tetris>" "${CMAKE_BINARY_DIR}/package/TetrisGame/"
-        COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_SOURCE_DIR}/assets" "${CMAKE_BINARY_DIR}/package/TetrisGame/assets"
-        COMMAND ${CMAKE_COMMAND} -E copy_if_different "${CMAKE_SOURCE_DIR}/FreeSans.ttf" "${CMAKE_BINARY_DIR}/package/TetrisGame/"
-        COMMENT "Packaging Tetris for distribution"
-        DEPENDS tetris
-    )
+    if(GAME_TARGET)
+        add_custom_target(dist_package
+            COMMAND ${CMAKE_COMMAND} -E echo "Creating Windows distribution package..."
+            COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_BINARY_DIR}/package/SpacetrisGame"
+            COMMAND ${CMAKE_COMMAND} -E copy "$<TARGET_FILE:${GAME_TARGET}>" "${CMAKE_BINARY_DIR}/package/SpacetrisGame/"
+            COMMAND ${CMAKE_COMMAND} -E copy_directory "${CMAKE_SOURCE_DIR}/assets" "${CMAKE_BINARY_DIR}/package/SpacetrisGame/assets"
+            COMMAND ${CMAKE_COMMAND} -E copy_if_different "${CMAKE_SOURCE_DIR}/FreeSans.ttf" "${CMAKE_BINARY_DIR}/package/SpacetrisGame/"
+            COMMENT "Packaging Spacetris for distribution"
+            DEPENDS ${GAME_TARGET}
+        )
+    else()
+        message(WARNING "No game target detected; skipping dist_package target.")
+    endif()
     
     # Try to copy SDL DLLs automatically (SDL_image no longer needed)
     find_file(SDL3_DLL SDL3.dll PATHS "${CMAKE_BINARY_DIR}/vcpkg_installed/x64-windows/bin" NO_DEFAULT_PATH)
     find_file(SDL3_TTF_DLL SDL3_ttf.dll PATHS "${CMAKE_BINARY_DIR}/vcpkg_installed/x64-windows/bin" NO_DEFAULT_PATH)
-    
-    if(SDL3_DLL)
-        add_custom_command(TARGET dist_package POST_BUILD
-            COMMAND ${CMAKE_COMMAND} -E copy_if_different "${SDL3_DLL}" "${CMAKE_BINARY_DIR}/package/TetrisGame/"
-            COMMENT "Copying SDL3.dll"
-        )
-    endif()
-    
-    if(SDL3_TTF_DLL)
-        add_custom_command(TARGET dist_package POST_BUILD
-            COMMAND ${CMAKE_COMMAND} -E copy_if_different "${SDL3_TTF_DLL}" "${CMAKE_BINARY_DIR}/package/TetrisGame/"
-            COMMENT "Copying SDL3_ttf.dll"
-        )
+
+    if(GAME_TARGET)
+        if(SDL3_DLL)
+            add_custom_command(TARGET dist_package POST_BUILD
+                COMMAND ${CMAKE_COMMAND} -E copy_if_different "${SDL3_DLL}" "${CMAKE_BINARY_DIR}/package/SpacetrisGame/"
+                COMMENT "Copying SDL3.dll"
+            )
+        endif()
+
+        if(SDL3_TTF_DLL)
+            add_custom_command(TARGET dist_package POST_BUILD
+                COMMAND ${CMAKE_COMMAND} -E copy_if_different "${SDL3_TTF_DLL}" "${CMAKE_BINARY_DIR}/package/SpacetrisGame/"
+                COMMENT "Copying SDL3_ttf.dll"
+            )
+        endif()
     endif()
 endif()
 
 # Installation rules for system-wide installation
-install(TARGETS tetris 
-    RUNTIME DESTINATION bin
-    COMPONENT Runtime
-)
+if(GAME_TARGET)
+    if(APPLE)
+        install(TARGETS ${GAME_TARGET}
+            BUNDLE DESTINATION .
+            COMPONENT Runtime
+        )
+    else()
+        install(TARGETS ${GAME_TARGET} 
+            RUNTIME DESTINATION bin
+            COMPONENT Runtime
+        )
+    endif()
 
-install(DIRECTORY assets/
-    DESTINATION share/tetris/assets
-    COMPONENT Runtime
-)
+    install(DIRECTORY assets/
+        DESTINATION share/${GAME_TARGET}/assets
+        COMPONENT Runtime
+    )
 
-install(FILES FreeSans.ttf
-    DESTINATION share/tetris
-    COMPONENT Runtime
-)
+    install(FILES FreeSans.ttf
+        DESTINATION share/${GAME_TARGET}
+        COMPONENT Runtime
+    )
+endif()
 
 # CPack configuration for creating installers (commented out - requires LICENSE file)
 # set(CPACK_PACKAGE_NAME "Tetris")
diff --git a/convert_instructions.bat b/convert_instructions.bat
index bf2da84..41a3dea 100644
--- a/convert_instructions.bat
+++ b/convert_instructions.bat
@@ -1,14 +1,14 @@
 @echo off
-echo Converting MP3 files to WAV using Windows Media Player...
+echo Convert MP3 files to OGG (preferred) for cross-platform playback...
 echo.
 
 REM Check if we have access to Windows Media Format SDK
 set MUSIC_DIR=assets\music
 
 REM List of MP3 files to convert
-set FILES=amazing.mp3 boom_tetris.mp3 great_move.mp3 impressive.mp3 keep_that_ryhtm.mp3 lets_go.mp3 nice_combo.mp3 smooth_clear.mp3 triple_strike.mp3 well_played.mp3 wonderful.mp3 you_fire.mp3 you_re_unstoppable.mp3
+set FILES=amazing.mp3 boom_tetris.mp3 great_move.mp3 impressive.mp3 keep_that_ryhtm.mp3 lets_go.mp3 nice_combo.mp3 smooth_clear.mp3 triple_strike.mp3 well_played.mp3 wonderful.mp3 you_fire.mp3 you_re_unstoppable.mp3 hard_drop_001.mp3 new_level.mp3
 
-echo Please convert these MP3 files to WAV format manually:
+echo Please convert these MP3 files to OGG Vorbis manually (or run convert_to_ogg.ps1 on Windows):
 echo.
 for %%f in (%FILES%) do (
     echo - %MUSIC_DIR%\%%f
@@ -17,13 +17,12 @@ for %%f in (%FILES%) do (
 echo.
 echo Recommended settings for conversion:
 echo - Sample Rate: 44100 Hz
-echo - Bit Depth: 16-bit
 echo - Channels: Stereo (2)
-echo - Format: PCM WAV
+echo - Use OGG Vorbis quality ~4 (or convert to FLAC if you prefer lossless)
 echo.
 echo You can use:
 echo - Audacity (free): https://www.audacityteam.org/
 echo - VLC Media Player (free): Media ^> Convert/Save
-echo - Any audio converter software
+echo - ffmpeg (CLI): ffmpeg -i input.mp3 -c:a libvorbis -qscale:a 4 output.ogg
 echo.
 pause
diff --git a/convert_to_ogg.ps1 b/convert_to_ogg.ps1
new file mode 100644
index 0000000..35b5da8
--- /dev/null
+++ b/convert_to_ogg.ps1
@@ -0,0 +1,45 @@
+# Convert MP3 sound effects to OGG Vorbis format for cross-platform playback
+# Requires ffmpeg (https://ffmpeg.org/). OGG keeps files small while SDL's decoders
+# work everywhere the game ships.
+
+$musicDir = "assets\music"
+$sourceFiles = @(
+    "amazing.mp3",
+    "boom_tetris.mp3",
+    "great_move.mp3",
+    "impressive.mp3",
+    "keep_that_ryhtm.mp3",
+    "lets_go.mp3",
+    "nice_combo.mp3",
+    "smooth_clear.mp3",
+    "triple_strike.mp3",
+    "well_played.mp3",
+    "wonderful.mp3",
+    "you_fire.mp3",
+    "you_re_unstoppable.mp3",
+    "hard_drop_001.mp3",
+    "new_level.mp3",
+    "Every Block You Take.mp3"
+)
+
+if (!(Get-Command ffmpeg -ErrorAction SilentlyContinue)) {
+    Write-Host "ffmpeg is required. Install via https://ffmpeg.org/ or winget install Gyan.FFmpeg" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "Converting MP3 sound effects to OGG..." -ForegroundColor Cyan
+foreach ($file in $sourceFiles) {
+    $src = Join-Path $musicDir $file
+    if (!(Test-Path $src)) {
+        Write-Host "Skipping (missing): $src" -ForegroundColor Yellow
+        continue
+    }
+    $ogg = ($file -replace ".mp3$", ".ogg")
+    $dest = Join-Path $musicDir $ogg
+    Write-Host "-> $ogg" -ForegroundColor Green
+    & ffmpeg -y -i $src -c:a libvorbis -qscale:a 4 $dest > $null 2>&1
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "Failed to convert $file" -ForegroundColor Red
+    }
+}
+Write-Host "Conversion complete." -ForegroundColor Green
diff --git a/convert_to_wav.ps1 b/convert_to_wav.ps1
index 577f52b..d77e27f 100644
--- a/convert_to_wav.ps1
+++ b/convert_to_wav.ps1
@@ -1,63 +1,11 @@
-# Convert MP3 sound effects to WAV format
-# This script converts all MP3 sound effect files to WAV for better compatibility
+# Deprecated shim: point developers to the OGG conversion workflow
+Write-Host "convert_to_wav.ps1 is deprecated." -ForegroundColor Yellow
+Write-Host "Use convert_to_ogg.ps1 for generating assets with OGG Vorbis." -ForegroundColor Yellow
 
-$musicDir = "assets\music"
-$mp3Files = @(
-    "amazing.mp3",
-    "boom_tetris.mp3", 
-    "great_move.mp3",
-    "impressive.mp3",
-    "keep_that_ryhtm.mp3",
-    "lets_go.mp3",
-    "nice_combo.mp3",
-    "smooth_clear.mp3",
-    "triple_strike.mp3",
-    "well_played.mp3",
-    "wonderful.mp3",
-    "you_fire.mp3",
-    "you_re_unstoppable.mp3"
-)
-
-Write-Host "Converting MP3 sound effects to WAV format..." -ForegroundColor Green
-
-foreach ($mp3File in $mp3Files) {
-    $mp3Path = Join-Path $musicDir $mp3File
-    $wavFile = $mp3File -replace "\.mp3$", ".wav"
-    $wavPath = Join-Path $musicDir $wavFile
-    
-    if (Test-Path $mp3Path) {
-        Write-Host "Converting $mp3File to $wavFile..." -ForegroundColor Yellow
-        
-        # Try ffmpeg first (most common)
-        $ffmpegResult = $null
-        try {
-            $ffmpegResult = & ffmpeg -i $mp3Path -acodec pcm_s16le -ar 44100 -ac 2 $wavPath -y 2>&1
-            if ($LASTEXITCODE -eq 0) {
-                Write-Host "✓ Successfully converted $mp3File" -ForegroundColor Green
-                continue
-            }
-        } catch {
-            # FFmpeg not available, try other methods
-        }
-        
-        # Try Windows Media Format SDK (if available)
-        try {
-            Add-Type -AssemblyName System.Windows.Forms
-            Add-Type -AssemblyName Microsoft.VisualBasic
-            
-            # Use Windows built-in audio conversion
-            $shell = New-Object -ComObject Shell.Application
-            # This is a fallback method - may not work on all systems
-            Write-Host "⚠ FFmpeg not found. Please install FFmpeg or convert manually." -ForegroundColor Red
-        } catch {
-            Write-Host "⚠ Could not convert $mp3File automatically." -ForegroundColor Red
-        }
-    } else {
-        Write-Host "⚠ File not found: $mp3Path" -ForegroundColor Red
-    }
+$oggScript = Join-Path $PSScriptRoot "convert_to_ogg.ps1"
+if (Test-Path $oggScript) {
+    & $oggScript
+} else {
+    Write-Host "Missing convert_to_ogg.ps1" -ForegroundColor Red
+    exit 1
 }
-
-Write-Host "`nConversion complete! If FFmpeg was not found, please:" -ForegroundColor Cyan
-Write-Host "1. Install FFmpeg: https://ffmpeg.org/download.html" -ForegroundColor White
-Write-Host "2. Or use an audio converter like Audacity" -ForegroundColor White
-Write-Host "3. Convert to: 44.1kHz, 16-bit, Stereo WAV" -ForegroundColor White
diff --git a/cooperate_mode_plan.md b/cooperate_mode_plan.md
new file mode 100644
index 0000000..b3a61e1
--- /dev/null
+++ b/cooperate_mode_plan.md
@@ -0,0 +1,174 @@
+# Spacetris — COOPERATE Mode (Two-Player Co-Op)  
+## VS Code Copilot AI Agent Prompt
+
+> Implement a new **COOPERATE** play mode for Spacetris.  
+> This is a **two-player cooperative mode** with a shared board and synchronized line clears.
+
+---
+
+## 1. Mode Overview
+
+### Mode Name
+- **COOPERATE**
+
+### Core Concept
+- Two players play **together**, not versus.
+- One shared game board with **double width**.
+- Each player is responsible for **their own half** of the board.
+- A line clears **only when BOTH halves of the same row are full**.
+
+---
+
+## 2. Grid Layout
+
+- Grid width: **20 columns**
+- Grid height: **standard height** (same as Endless/Challenge)
+- Column ownership:
+  - Player 1 → columns `0–9` (left half)
+  - Player 2 → columns `10–19` (right half)
+
+### Visual Requirements
+- Draw a **vertical divider line** between columns 9 and 10.
+- Divider should be subtle but always visible.
+
+---
+
+## 3. Line Clear Rule (Critical)
+
+A row clears **only if**:
+- Player 1 half of the row is completely filled
+- AND Player 2 half of the row is completely filled
+
+If only one side is filled:
+- The row **does NOT clear**
+- Provide visual feedback:
+  - Glow or pulse on the completed half
+  - Optional hint on the incomplete half
+
+---
+
+## 4. Player Mechanics
+
+### Piece Streams
+- Each player has their **own active piece**
+- Each player has their **own NEXT queue**
+- Both queues use the **same RNG seed** for fairness
+
+### Controls
+- Player 1 controls only the left half
+- Player 2 controls only the right half
+- Players cannot move or rotate pieces into the other player’s half
+
+---
+
+## 5. Gravity & Timing
+
+- Gravity applies globally (same speed for both)
+- Lock delay is handled **per player**
+- One player locking does NOT block the other player
+
+---
+
+## 6. Failure Conditions
+
+Recommended:
+- Game over occurs only when **both players top out**
+
+Alternative (optional):
+- If either player tops out → shared loss
+
+---
+
+## 7. Scoring System
+
+- Score is **shared**
+- Line clears grant:
+  - Base score
+  - Cooperative bonus if both halves complete simultaneously
+  - Combo bonus for consecutive cooperative clears
+
+No competitive scoring between players.
+
+---
+
+## 8. UI / HUD Requirements
+
+- Two NEXT panels (one per player)
+- Shared score display
+- Shared level display
+- Visual feedback for:
+  - Half-filled rows
+  - Successful cooperative clears
+
+Optional:
+- SYNC meter for advanced cooperative mechanics (future)
+
+---
+
+## 9. Data Model Suggestions
+
+```cpp
+enum class PlayerSide {
+    Left,
+    Right
+};
+
+struct PlayerState {
+    PlayerSide side;
+    ActivePiece piece;
+    bool isAlive;
+};
+
+struct Cell {
+    bool occupied;
+    PlayerSide owner;
+};
+````
+
+---
+
+## 10. Line Clear Algorithm (Guidance)
+
+When checking for full rows:
+
+1. For each row:
+
+   * Check columns `0–9` for full (Player 1)
+   * Check columns `10–19` for full (Player 2)
+2. Only if **both are full**, mark row for clearing
+3. Clear row normally and apply gravity to both halves
+4. Update shared score and combos
+
+---
+
+## 11. Constraints
+
+* COOPERATE is a separate play mode
+* Do NOT reuse versus or garbage mechanics
+* Focus on clarity, fairness, and readability
+* Keep implementation modular (easy to expand later)
+
+---
+
+## 12. Acceptance Criteria
+
+* Two players can play simultaneously on one board
+* Each player fills only their half
+* Lines clear only when both halves are filled
+* Visual feedback clearly shows cooperative dependency
+* Mode integrates cleanly into the main menu
+
+---
+
+## 13. Optional Future Hooks (Do Not Implement Now)
+
+* Assist blocks
+* Shared power-ups
+* Cross-half interactions
+* Online co-op
+
+---
+
+## Short Summary for the Agent
+
+Implement a two-player COOPERATE mode with a 20-column board split into two halves. Each player fills their half independently. A line clears only when both halves of the same row are full. Score, level, and progress are shared. Add clear visual feedback and a divider between player halves.
diff --git a/docs/CODE_ORGANIZATION.md b/docs/CODE_ORGANIZATION.md
new file mode 100644
index 0000000..14b0a8b
--- /dev/null
+++ b/docs/CODE_ORGANIZATION.md
@@ -0,0 +1,425 @@
+# Code Organization & Structure Improvements
+
+## ✅ Progress Tracker
+
+### Phase 1: Core Reorganization - IN PROGRESS ⚠️
+
+**✅ Completed:**
+
+- ✅ Created new directory structure (interfaces/, application/, assets/, input/, state/, memory/)
+- ✅ Created core interfaces (IRenderer.h, IAudioSystem.h, IAssetLoader.h, IInputHandler.h, IGameRules.h)
+- ✅ Created ServiceContainer for dependency injection
+- ✅ Moved ApplicationManager to core/application/
+- ✅ Moved AssetManager to core/assets/
+- ✅ Moved InputManager to core/input/
+- ✅ Moved StateManager to core/state/
+- ✅ Moved Game files to gameplay/core/
+- ✅ Moved Font files to graphics/ui/
+- ✅ Moved Starfield files to graphics/effects/
+- ✅ Moved RenderManager and GameRenderer to graphics/renderers/
+- ✅ Moved LineEffect to gameplay/effects/
+- ✅ Cleaned up duplicate files
+- ✅ Audio and Scores files already properly located
+
+**⚠️ Currently In Progress:**
+
+- ✅ Updated critical include paths in main.cpp, state files, graphics renderers
+- ✅ Fixed RenderManager duplicate method declarations  
+- ✅ Resolved GameRenderer.h and LoadingState.cpp include paths
+- ⚠️ Still fixing remaining include path issues (ongoing)
+- ⚠️ Still debugging Game.h redefinition errors (ongoing)
+
+**❌ Next Steps:**
+
+- ❌ Complete all remaining #include statement updates
+- ❌ Resolve Game.h redefinition compilation errors
+- ❌ Test successful compilation of both tetris and tetris_refactored targets
+- ❌ Update documentation
+- ❌ Begin Phase 2 - Interface implementation
+
+### Phase 2: Interface Extraction - NOT STARTED ❌
+
+### Phase 3: Module Separation - NOT STARTED ❌
+
+### Phase 4: Documentation & Standards - NOT STARTED ❌
+
+## Current Structure Analysis
+
+### Strengths
+
+- ✅ Clear domain separation (core/, gameplay/, graphics/, audio/, etc.)
+- ✅ Consistent naming conventions
+- ✅ Modern C++ header organization
+- ✅ Proper forward declarations
+
+### Areas for Improvement
+
+- ⚠️ Some files in root src/ should be moved to appropriate subdirectories
+- ⚠️ Missing interfaces/contracts
+- ⚠️ Some circular dependencies
+- ⚠️ CMakeLists.txt has duplicate entries
+
+## Proposed Directory Restructure
+
+```text
+src/
+├── core/                           # Core engine systems
+│   ├── interfaces/                 # Abstract interfaces (NEW)
+│   │   ├── IRenderer.h
+│   │   ├── IAudioSystem.h
+│   │   ├── IAssetLoader.h
+│   │   ├── IInputHandler.h
+│   │   └── IGameRules.h
+│   ├── application/               # Application lifecycle (NEW)
+│   │   ├── ApplicationManager.cpp/h
+│   │   ├── ServiceContainer.cpp/h
+│   │   └── SystemCoordinator.cpp/h
+│   ├── assets/                    # Asset management
+│   │   ├── AssetManager.cpp/h
+│   │   └── AssetLoader.cpp/h
+│   ├── input/                     # Input handling
+│   │   └── InputManager.cpp/h
+│   ├── state/                     # State management
+│   │   └── StateManager.cpp/h
+│   ├── memory/                    # Memory management (NEW)
+│   │   ├── ObjectPool.h
+│   │   └── MemoryTracker.h
+│   └── Config.h
+│   └── GlobalState.cpp/h
+│   └── GravityManager.cpp/h
+├── gameplay/                       # Game logic
+│   ├── core/                      # Core game mechanics
+│   │   ├── Game.cpp/h
+│   │   ├── Board.cpp/h            # Extract from Game.cpp
+│   │   ├── Piece.cpp/h            # Extract from Game.cpp
+│   │   └── PieceFactory.cpp/h     # Extract from Game.cpp
+│   ├── rules/                     # Game rules (NEW)
+│   │   ├── ClassicTetrisRules.cpp/h
+│   │   ├── ModernTetrisRules.cpp/h
+│   │   └── ScoringSystem.cpp/h
+│   ├── effects/                   # Visual effects
+│   │   └── LineEffect.cpp/h
+│   └── mechanics/                 # Game mechanics (NEW)
+│       ├── RotationSystem.cpp/h
+│       ├── KickTable.cpp/h
+│       └── BagRandomizer.cpp/h
+├── graphics/                       # Rendering and visual
+│   ├── renderers/                 # Different renderers
+│   │   ├── RenderManager.cpp/h
+│   │   ├── GameRenderer.cpp/h
+│   │   ├── UIRenderer.cpp/h       # Extract from various places
+│   │   └── EffectRenderer.cpp/h   # New
+│   ├── effects/                   # Visual effects
+│   │   ├── Starfield.cpp/h
+│   │   ├── Starfield3D.cpp/h
+│   │   └── ParticleSystem.cpp/h   # New
+│   ├── ui/                        # UI components
+│   │   ├── Font.cpp/h
+│   │   ├── Button.cpp/h           # New
+│   │   ├── Panel.cpp/h            # New
+│   │   └── ScoreDisplay.cpp/h     # New
+│   └── resources/                 # Graphics resources
+│       ├── TextureAtlas.cpp/h     # New
+│       └── SpriteManager.cpp/h    # New
+├── audio/                          # Audio system
+│   ├── Audio.cpp/h
+│   ├── SoundEffect.cpp/h
+│   ├── MusicManager.cpp/h         # New
+│   └── AudioMixer.cpp/h           # New
+├── persistence/                    # Data persistence
+│   ├── Scores.cpp/h
+│   ├── Settings.cpp/h             # New
+│   ├── SaveGame.cpp/h             # New
+│   └── Serialization.cpp/h        # New
+├── states/                         # Game states
+│   ├── State.h                     # Base interface
+│   ├── LoadingState.cpp/h
+│   ├── MenuState.cpp/h
+│   ├── LevelSelectorState.cpp/h
+│   ├── PlayingState.cpp/h
+│   ├── PausedState.cpp/h          # New
+│   ├── GameOverState.cpp/h        # New
+│   └── SettingsState.cpp/h        # New
+├── network/                        # Future: Multiplayer (NEW)
+│   ├── NetworkManager.h
+│   ├── Protocol.h
+│   └── MultiplayerGame.h
+├── utils/                          # Utilities (NEW)
+│   ├── Logger.cpp/h
+│   ├── Timer.cpp/h
+│   ├── MathUtils.h
+│   └── StringUtils.h
+├── platform/                      # Platform-specific (NEW)
+│   ├── Platform.h
+│   ├── Windows/
+│   ├── Linux/
+│   └── macOS/
+└── main.cpp                       # Keep original main
+└── main_new.cpp                   # Refactored main
+```
+
+## Module Dependencies
+
+### Clean Dependency Graph
+
+```text
+Application Layer:    main.cpp → ApplicationManager
+Core Layer:          ServiceContainer → All Managers
+Gameplay Layer:      Game → Rules → Mechanics
+Graphics Layer:      RenderManager → Renderers → Resources
+Audio Layer:         AudioSystem → Concrete Implementations
+Persistence Layer:   SaveSystem → Serialization
+Platform Layer:      Platform Abstraction (lowest level)
+```
+
+### Dependency Rules
+
+1. **No circular dependencies**
+2. **Higher layers can depend on lower layers only**
+3. **Use interfaces for cross-layer communication**
+4. **Platform layer has no dependencies on other layers**
+
+## Header Organization
+
+### 1. Consistent Header Structure
+
+```cpp
+// Standard template for all headers
+#pragma once
+
+// System includes
+#include <vector>
+#include <memory>
+
+// External library includes
+#include <SDL3/SDL.h>
+
+// Internal includes (from most general to most specific)
+#include "core/interfaces/IRenderer.h"
+#include "graphics/resources/Texture.h"
+#include "MyClass.h"
+
+// Forward declarations
+class GameRenderer;
+class TextureAtlas;
+
+// Class definition
+class MyClass {
+    // Public interface first
+public:
+    // Constructors/Destructors
+    MyClass();
+    ~MyClass();
+    
+    // Core functionality
+    void update(double deltaTime);
+    void render();
+    
+    // Getters/Setters
+    int getValue() const { return value; }
+    void setValue(int v) { value = v; }
+
+// Private implementation
+private:
+    // Member variables
+    int value{0};
+    std::unique_ptr<GameRenderer> renderer;
+    
+    // Private methods
+    void initializeRenderer();
+};
+```
+
+### 2. Include Guards and PCH
+
+```cpp
+// PrecompiledHeaders.h (NEW)
+#pragma once
+
+// Standard library
+#include <vector>
+#include <memory>
+#include <string>
+#include <unordered_map>
+#include <chrono>
+#include <functional>
+#include <algorithm>
+
+// External libraries (stable)
+#include <SDL3/SDL.h>
+#include <SDL3_ttf/SDL_ttf.h>
+
+// Common project headers
+#include "core/Config.h"
+#include "core/interfaces/IRenderer.h"
+```
+
+## Code Style Improvements
+
+### 1. Consistent Naming Conventions
+
+```cpp
+// Classes: PascalCase
+class GameRenderer;
+class TextureAtlas;
+
+// Functions/Methods: camelCase
+void updateGameLogic();
+bool isValidPosition();
+
+// Variables: camelCase
+int currentScore;
+double deltaTime;
+
+// Constants: UPPER_SNAKE_CASE
+const int MAX_LEVEL = 30;
+const double GRAVITY_MULTIPLIER = 1.0;
+
+// Private members: camelCase with suffix
+class MyClass {
+private:
+    int memberVariable_;  // or m_memberVariable
+    static int staticCounter_;
+};
+```
+
+### 2. Documentation Standards
+
+```cpp
+/**
+ * @brief Manages the core game state and logic for Tetris
+ * 
+ * The Game class handles piece movement, rotation, line clearing,
+ * and scoring according to classic Tetris rules.
+ * 
+ * @example
+ * ```cpp
+ * Game game(startLevel);
+ * game.reset(0);
+ * game.move(-1);  // Move left
+ * game.rotate(1); // Rotate clockwise
+ * ```
+ */
+class Game {
+public:
+    /**
+     * @brief Moves the current piece horizontally
+     * @param dx Direction to move (-1 for left, +1 for right)
+     * @return true if the move was successful, false if blocked
+     */
+    bool move(int dx);
+    
+    /**
+     * @brief Gets the current score
+     * @return Current score value
+     * @note Score never decreases during gameplay
+     */
+    int score() const noexcept { return score_; }
+};
+```
+
+## CMake Improvements
+
+### 1. Modular CMakeLists.txt
+
+```cmake
+# CMakeLists.txt (main)
+cmake_minimum_required(VERSION 3.20)
+project(tetris_sdl3 LANGUAGES CXX)
+
+# Global settings
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Find packages
+find_package(SDL3 CONFIG REQUIRED)
+find_package(SDL3_ttf CONFIG REQUIRED)
+
+# Add subdirectories
+add_subdirectory(src/core)
+add_subdirectory(src/gameplay)
+add_subdirectory(src/graphics)
+add_subdirectory(src/audio)
+add_subdirectory(src/persistence)
+add_subdirectory(src/states)
+
+# Main executable
+add_executable(tetris src/main.cpp)
+target_link_libraries(tetris PRIVATE 
+    tetris::core
+    tetris::gameplay 
+    tetris::graphics
+    tetris::audio
+    tetris::persistence
+    tetris::states
+)
+
+# Tests
+if(BUILD_TESTING)
+    add_subdirectory(tests)
+endif()
+```
+
+### 2. Module CMakeLists.txt
+
+```cmake
+# src/core/CMakeLists.txt
+add_library(tetris_core
+    ApplicationManager.cpp
+    StateManager.cpp
+    InputManager.cpp
+    AssetManager.cpp
+    GlobalState.cpp
+    GravityManager.cpp
+)
+
+add_library(tetris::core ALIAS tetris_core)
+
+target_include_directories(tetris_core 
+    PUBLIC ${CMAKE_SOURCE_DIR}/src
+    PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}
+)
+
+target_link_libraries(tetris_core 
+    PUBLIC SDL3::SDL3 SDL3_ttf::SDL3_ttf
+)
+
+# Export for use by other modules
+target_compile_features(tetris_core PUBLIC cxx_std_20)
+```
+
+## Implementation Timeline
+
+### Phase 1: Core Reorganization (Week 1-2)
+
+1. Create new directory structure
+2. Move files to appropriate locations
+3. Update CMakeLists.txt files
+4. Fix include paths
+
+### Phase 2: Interface Extraction (Week 3-4)
+
+1. Create interface headers
+2. Update implementations to use interfaces
+3. Add dependency injection container
+
+### Phase 3: Module Separation (Week 5-6)
+
+1. Split large classes (Game, ApplicationManager)
+2. Create separate CMake modules
+3. Establish clean dependency graph
+
+### Phase 4: Documentation & Standards (Week 7-8)
+
+1. Add comprehensive documentation
+2. Implement coding standards
+3. Add static analysis tools
+4. Update build scripts
+
+## Benefits
+
+1. **Maintainability**: Clear module boundaries and responsibilities
+2. **Testability**: Easy to mock and test individual components
+3. **Scalability**: Easy to add new features without affecting existing code
+4. **Team Development**: Multiple developers can work on different modules
+5. **Code Reuse**: Modular design enables component reuse
diff --git a/docs/PERFORMANCE_OPTIMIZATION.md b/docs/PERFORMANCE_OPTIMIZATION.md
new file mode 100644
index 0000000..8dd0f91
--- /dev/null
+++ b/docs/PERFORMANCE_OPTIMIZATION.md
@@ -0,0 +1,163 @@
+# Performance Optimization Recommendations
+
+## Current Performance Analysis
+
+### Memory Management
+- **Good**: Proper RAII patterns, smart pointers
+- **Improvement**: Object pooling for frequently created/destroyed objects
+
+### Rendering Performance
+- **Current**: SDL3 with immediate mode rendering
+- **Optimization Opportunities**: Batch rendering, texture atlasing
+
+### Game Logic Performance
+- **Current**: Simple collision detection, adequate for Tetris
+- **Good**: Efficient board representation using flat array
+
+## Specific Optimizations
+
+### 1. Object Pooling for Game Pieces
+
+```cpp
+// src/gameplay/PiecePool.h
+class PiecePool {
+private:
+    std::vector<std::unique_ptr<Piece>> available;
+    std::vector<std::unique_ptr<Piece>> inUse;
+    
+public:
+    std::unique_ptr<Piece> acquire(PieceType type);
+    void release(std::unique_ptr<Piece> piece);
+    void preAllocate(size_t count);
+};
+```
+
+### 2. Texture Atlas for UI Elements
+
+```cpp
+// src/graphics/TextureAtlas.h
+class TextureAtlas {
+private:
+    SDL_Texture* atlasTexture;
+    std::unordered_map<std::string, SDL_Rect> regions;
+    
+public:
+    void loadAtlas(const std::string& atlasPath, const std::string& configPath);
+    SDL_Rect getRegion(const std::string& name) const;
+    SDL_Texture* getTexture() const { return atlasTexture; }
+};
+```
+
+### 3. Batch Rendering System
+
+```cpp
+// src/graphics/BatchRenderer.h
+class BatchRenderer {
+private:
+    struct RenderCommand {
+        SDL_Texture* texture;
+        SDL_Rect srcRect;
+        SDL_Rect dstRect;
+    };
+    
+    std::vector<RenderCommand> commands;
+    
+public:
+    void addSprite(SDL_Texture* texture, const SDL_Rect& src, const SDL_Rect& dst);
+    void flush();
+    void clear();
+};
+```
+
+### 4. Memory-Efficient Board Representation
+
+```cpp
+// Current: std::array<int, COLS*ROWS> board (40 integers = 160 bytes)
+// Optimized: Bitset representation for filled/empty + color array for occupied cells
+
+class OptimizedBoard {
+private:
+    std::bitset<COLS * ROWS> occupied;  // 25 bytes (200 bits)
+    std::array<uint8_t, COLS * ROWS> colors;  // 200 bytes, but only for occupied cells
+    
+public:
+    bool isOccupied(int x, int y) const;
+    uint8_t getColor(int x, int y) const;
+    void setCell(int x, int y, uint8_t color);
+    void clearCell(int x, int y);
+};
+```
+
+### 5. Cache-Friendly Data Structures
+
+```cpp
+// Group related data together for better cache locality
+struct GameState {
+    // Hot data (frequently accessed)
+    std::array<uint8_t, COLS * ROWS> board;
+    Piece currentPiece;
+    int score;
+    int level;
+    int lines;
+    
+    // Cold data (less frequently accessed)
+    std::vector<PieceType> bag;
+    Piece holdPiece;
+    bool gameOver;
+    bool paused;
+};
+```
+
+## Performance Measurement
+
+### 1. Add Profiling Infrastructure
+
+```cpp
+// src/core/Profiler.h
+class Profiler {
+private:
+    std::unordered_map<std::string, std::chrono::high_resolution_clock::time_point> startTimes;
+    std::unordered_map<std::string, double> averageTimes;
+    
+public:
+    void beginTimer(const std::string& name);
+    void endTimer(const std::string& name);
+    void printStats();
+};
+
+// Usage:
+// profiler.beginTimer("GameLogic");
+// game.update(deltaTime);
+// profiler.endTimer("GameLogic");
+```
+
+### 2. Frame Rate Optimization
+
+```cpp
+// Target 60 FPS with consistent frame timing
+class FrameRateManager {
+private:
+    std::chrono::high_resolution_clock::time_point lastFrame;
+    double targetFrameTime = 1000.0 / 60.0; // 16.67ms
+    
+public:
+    void beginFrame();
+    void endFrame();
+    double getDeltaTime() const;
+    bool shouldSkipFrame() const;
+};
+```
+
+## Expected Performance Gains
+
+1. **Object Pooling**: 30-50% reduction in allocation overhead
+2. **Texture Atlas**: 20-30% improvement in rendering performance
+3. **Batch Rendering**: 40-60% reduction in draw calls
+4. **Optimized Board**: 60% reduction in memory usage
+5. **Cache Optimization**: 10-20% improvement in game logic performance
+
+## Implementation Priority
+
+1. **High Impact, Low Effort**: Profiling infrastructure, frame rate management
+2. **Medium Impact, Medium Effort**: Object pooling, optimized board representation
+3. **High Impact, High Effort**: Texture atlas, batch rendering system
diff --git a/docs/REFACTORING_SOLID_PRINCIPLES.md b/docs/REFACTORING_SOLID_PRINCIPLES.md
new file mode 100644
index 0000000..d0e03a1
--- /dev/null
+++ b/docs/REFACTORING_SOLID_PRINCIPLES.md
@@ -0,0 +1,128 @@
+# SOLID Principles Refactoring Plan
+
+## Current Architecture Issues
+
+### 1. Single Responsibility Principle (SRP) Violations
+- `ApplicationManager` handles initialization, coordination, rendering coordination, and asset management
+- `Game` class mixes game logic with some presentation concerns
+
+### 2. Open/Closed Principle (OCP) Opportunities
+- Hard-coded piece types and behaviors
+- Limited extensibility for new game modes or rule variations
+
+### 3. Dependency Inversion Principle (DIP) Missing
+- Concrete dependencies instead of interfaces
+- Direct instantiation rather than dependency injection
+
+## Proposed Improvements
+
+### 1. Extract Interfaces
+
+```cpp
+// src/core/interfaces/IRenderer.h
+class IRenderer {
+public:
+    virtual ~IRenderer() = default;
+    virtual void clear(uint8_t r, uint8_t g, uint8_t b, uint8_t a) = 0;
+    virtual void present() = 0;
+    virtual SDL_Renderer* getSDLRenderer() = 0;
+};
+
+// src/core/interfaces/IAudioSystem.h
+class IAudioSystem {
+public:
+    virtual ~IAudioSystem() = default;
+    virtual void playSound(const std::string& name) = 0;
+    virtual void playMusic(const std::string& name) = 0;
+    virtual void setMasterVolume(float volume) = 0;
+};
+
+// src/core/interfaces/IAssetLoader.h
+class IAssetLoader {
+public:
+    virtual ~IAssetLoader() = default;
+    virtual SDL_Texture* loadTexture(const std::string& path) = 0;
+    virtual void loadFont(const std::string& name, const std::string& path, int size) = 0;
+};
+```
+
+### 2. Dependency Injection Container
+
+```cpp
+// src/core/ServiceContainer.h
+class ServiceContainer {
+private:
+    std::unordered_map<std::type_index, std::shared_ptr<void>> services;
+    
+public:
+    template<typename T>
+    void registerService(std::shared_ptr<T> service) {
+        services[std::type_index(typeid(T))] = service;
+    }
+    
+    template<typename T>
+    std::shared_ptr<T> getService() {
+        auto it = services.find(std::type_index(typeid(T)));
+        if (it != services.end()) {
+            return std::static_pointer_cast<T>(it->second);
+        }
+        return nullptr;
+    }
+};
+```
+
+### 3. Break Down ApplicationManager
+
+```cpp
+// src/core/ApplicationLifecycle.h
+class ApplicationLifecycle {
+public:
+    bool initialize(int argc, char* argv[]);
+    void run();
+    void shutdown();
+};
+
+// src/core/SystemCoordinator.h
+class SystemCoordinator {
+public:
+    void initializeSystems(ServiceContainer& container);
+    void updateSystems(double deltaTime);
+    void shutdownSystems();
+};
+```
+
+### 4. Strategy Pattern for Game Rules
+
+```cpp
+// src/gameplay/interfaces/IGameRules.h
+class IGameRules {
+public:
+    virtual ~IGameRules() = default;
+    virtual int calculateScore(int linesCleared, int level) = 0;
+    virtual double getGravitySpeed(int level) = 0;
+    virtual bool shouldLevelUp(int lines) = 0;
+};
+
+// src/gameplay/rules/ClassicTetrisRules.h
+class ClassicTetrisRules : public IGameRules {
+public:
+    int calculateScore(int linesCleared, int level) override;
+    double getGravitySpeed(int level) override;
+    bool shouldLevelUp(int lines) override;
+};
+```
+
+## Implementation Priority
+
+1. **Phase 1**: Extract core interfaces (IRenderer, IAudioSystem)
+2. **Phase 2**: Implement dependency injection container
+3. **Phase 3**: Break down ApplicationManager responsibilities
+4. **Phase 4**: Add strategy patterns for game rules
+5. **Phase 5**: Improve testability with mock implementations
+
+## Benefits
+
+- **Testability**: Easy to mock dependencies for unit tests
+- **Extensibility**: New features without modifying existing code
+- **Maintainability**: Clear responsibilities and loose coupling
+- **Flexibility**: Easy to swap implementations (e.g., different renderers)
diff --git a/docs/TESTING_STRATEGY.md b/docs/TESTING_STRATEGY.md
new file mode 100644
index 0000000..e90bea5
--- /dev/null
+++ b/docs/TESTING_STRATEGY.md
@@ -0,0 +1,309 @@
+# Testing Strategy Enhancement
+
+## Current Testing State
+
+### Existing Tests
+- ✅ GravityTests.cpp - Basic gravity manager testing
+- ✅ Catch2 framework integration
+- ✅ CTest integration in CMake
+
+### Coverage Gaps
+- ❌ Game logic testing (piece movement, rotation, line clearing)
+- ❌ Collision detection testing
+- ❌ Scoring system testing
+- ❌ State management testing
+- ❌ Integration tests
+- ❌ Performance tests
+
+## Comprehensive Testing Strategy
+
+### 1. Unit Tests Expansion
+
+```cpp
+// tests/GameLogicTests.cpp
+TEST_CASE("Piece Movement", "[game][movement]") {
+    Game game(0);
+    Piece originalPiece = game.current();
+    
+    SECTION("Move left when possible") {
+        game.move(-1);
+        REQUIRE(game.current().x == originalPiece.x - 1);
+    }
+    
+    SECTION("Cannot move left at boundary") {
+        // Move piece to left edge
+        while (game.current().x > 0) {
+            game.move(-1);
+        }
+        int edgeX = game.current().x;
+        game.move(-1);
+        REQUIRE(game.current().x == edgeX); // Should not move further
+    }
+}
+
+// tests/CollisionTests.cpp
+TEST_CASE("Collision Detection", "[game][collision]") {
+    Game game(0);
+    
+    SECTION("Piece collides with bottom") {
+        // Force piece to bottom
+        while (!game.isGameOver()) {
+            game.hardDrop();
+            if (game.isGameOver()) break;
+        }
+        // Verify collision behavior
+    }
+    
+    SECTION("Piece collides with placed blocks") {
+        // Place a block manually
+        // Test collision with new piece
+    }
+}
+
+// tests/ScoringTests.cpp
+TEST_CASE("Scoring System", "[game][scoring]") {
+    Game game(0);
+    int initialScore = game.score();
+    
+    SECTION("Single line clear") {
+        // Set up board with almost complete line
+        // Clear line and verify score increase
+    }
+    
+    SECTION("Tetris (4 lines)") {
+        // Set up board for Tetris
+        // Verify bonus scoring
+    }
+}
+```
+
+### 2. Mock Objects for Testing
+
+```cpp
+// tests/mocks/MockRenderer.h
+class MockRenderer : public IRenderer {
+private:
+    mutable std::vector<std::string> calls;
+    
+public:
+    void clear(uint8_t r, uint8_t g, uint8_t b, uint8_t a) override {
+        calls.push_back("clear");
+    }
+    
+    void present() override {
+        calls.push_back("present");
+    }
+    
+    SDL_Renderer* getSDLRenderer() override {
+        return nullptr; // Mock implementation
+    }
+    
+    const std::vector<std::string>& getCalls() const { return calls; }
+    void clearCalls() { calls.clear(); }
+};
+
+// tests/mocks/MockAudioSystem.h
+class MockAudioSystem : public IAudioSystem {
+private:
+    std::vector<std::string> playedSounds;
+    
+public:
+    void playSound(const std::string& name) override {
+        playedSounds.push_back(name);
+    }
+    
+    void playMusic(const std::string& name) override {
+        playedSounds.push_back("music:" + name);
+    }
+    
+    void setMasterVolume(float volume) override {
+        // Mock implementation
+    }
+    
+    const std::vector<std::string>& getPlayedSounds() const { return playedSounds; }
+};
+```
+
+### 3. Integration Tests
+
+```cpp
+// tests/integration/StateTransitionTests.cpp
+TEST_CASE("State Transitions", "[integration][states]") {
+    ApplicationManager app;
+    // Mock dependencies
+    
+    SECTION("Loading to Menu transition") {
+        // Simulate loading completion
+        // Verify menu state activation
+    }
+    
+    SECTION("Menu to Game transition") {
+        // Simulate start game action
+        // Verify game state initialization
+    }
+}
+
+// tests/integration/GamePlayTests.cpp
+TEST_CASE("Complete Game Session", "[integration][gameplay]") {
+    Game game(0);
+    
+    SECTION("Play until first line clear") {
+        // Simulate complete game session
+        // Verify all systems work together
+    }
+}
+```
+
+### 4. Performance Tests
+
+```cpp
+// tests/performance/PerformanceTests.cpp
+TEST_CASE("Game Logic Performance", "[performance]") {
+    Game game(0);
+    
+    SECTION("1000 piece drops should complete in reasonable time") {
+        auto start = std::chrono::high_resolution_clock::now();
+        
+        for (int i = 0; i < 1000; ++i) {
+            game.hardDrop();
+            if (game.isGameOver()) {
+                game.reset(0);
+            }
+        }
+        
+        auto end = std::chrono::high_resolution_clock::now();
+        auto duration = std::chrono::duration_cast<std::chrono::milliseconds>(end - start);
+        
+        REQUIRE(duration.count() < 100); // Should complete in under 100ms
+    }
+}
+
+// tests/performance/MemoryTests.cpp
+TEST_CASE("Memory Usage", "[performance][memory]") {
+    SECTION("No memory leaks during gameplay") {
+        size_t initialMemory = getCurrentMemoryUsage();
+        
+        {
+            Game game(0);
+            // Simulate gameplay
+            for (int i = 0; i < 100; ++i) {
+                game.hardDrop();
+                if (game.isGameOver()) game.reset(0);
+            }
+        }
+        
+        size_t finalMemory = getCurrentMemoryUsage();
+        REQUIRE(finalMemory <= initialMemory + 1024); // Allow small overhead
+    }
+}
+```
+
+### 5. Property-Based Testing
+
+```cpp
+// tests/property/PropertyTests.cpp
+TEST_CASE("Property: Game state consistency", "[property]") {
+    Game game(0);
+    
+    SECTION("Score never decreases") {
+        int previousScore = game.score();
+        
+        // Perform random valid actions
+        for (int i = 0; i < 100; ++i) {
+            performRandomValidAction(game);
+            REQUIRE(game.score() >= previousScore);
+            previousScore = game.score();
+        }
+    }
+    
+    SECTION("Board state remains valid") {
+        for (int i = 0; i < 1000; ++i) {
+            performRandomValidAction(game);
+            REQUIRE(isBoardStateValid(game));
+        }
+    }
+}
+```
+
+### 6. Test Data Management
+
+```cpp
+// tests/fixtures/GameFixtures.h
+class GameFixtures {
+public:
+    static Game createGameWithAlmostFullLine() {
+        Game game(0);
+        // Set up specific board state
+        return game;
+    }
+    
+    static Game createGameNearGameOver() {
+        Game game(0);
+        // Fill board almost to top
+        return game;
+    }
+    
+    static std::vector<PieceType> createTetrisPieceSequence() {
+        return {I, O, T, S, Z, J, L};
+    }
+};
+```
+
+## Test Automation & CI
+
+### 1. GitHub Actions Configuration
+
+```yaml
+# .github/workflows/tests.yml
+name: Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+        build-type: [Debug, Release]
+    
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install dependencies
+      run: |
+        # Install vcpkg and dependencies
+    - name: Configure CMake
+      run: cmake -B build -DCMAKE_BUILD_TYPE=${{ matrix.build-type }}
+    - name: Build
+      run: cmake --build build --config ${{ matrix.build-type }}
+    - name: Test
+      run: ctest --test-dir build --build-config ${{ matrix.build-type }}
+```
+
+### 2. Code Coverage
+
+```cmake
+# Add to CMakeLists.txt
+option(ENABLE_COVERAGE "Enable code coverage" OFF)
+
+if(ENABLE_COVERAGE)
+    target_compile_options(tetris PRIVATE --coverage)
+    target_link_libraries(tetris PRIVATE --coverage)
+endif()
+```
+
+## Quality Metrics Targets
+
+- **Unit Test Coverage**: > 80%
+- **Integration Test Coverage**: > 60%
+- **Performance Regression**: < 5% per release
+- **Memory Leak Detection**: 0 leaks in test suite
+- **Static Analysis**: 0 critical issues
+
+## Implementation Priority
+
+1. **Phase 1**: Core game logic unit tests (movement, rotation, collision)
+2. **Phase 2**: Mock objects and dependency injection for testability
+3. **Phase 3**: Integration tests for state management
+4. **Phase 4**: Performance and memory tests
+5. **Phase 5**: Property-based testing and fuzzing
+6. **Phase 6**: CI/CD pipeline with automated testing
diff --git a/docs/ai/cooperate_network.md b/docs/ai/cooperate_network.md
new file mode 100644
index 0000000..36f9882
--- /dev/null
+++ b/docs/ai/cooperate_network.md
@@ -0,0 +1,271 @@
+# Spacetris — COOPERATE Mode  
+## Network Multiplayer (2 PLAYER – NETWORK)  
+### VS Code Copilot AI Agent Prompt
+
+You are integrating **online cooperative multiplayer** into an existing **C++ / SDL3 game** called **Spacetris**.
+
+This feature extends the existing **COOPERATE mode** to support:
+- Local 2 players
+- Human + AI
+- **Human + Human over network (NEW)**
+
+The networking solution must be **deterministic, lightweight, and stable**.
+
+---
+
+## 1. High-Level Goal
+
+Add **COOPERATE 2 PLAYER (NETWORK)** mode where:
+- Two players play together over the internet
+- Each player controls one half of the shared grid
+- A line clears only when both halves are filled
+- Gameplay remains identical to local COOPERATE mode
+
+---
+
+## 2. Technology Constraints
+
+- Language: **C++**
+- Engine: **SDL3**
+- Networking: **ENet (UDP with reliability)**
+- No engine rewrite
+- No authoritative server logic required (co-op only)
+
+SDL3 is used ONLY for:
+- Rendering
+- Input
+- Timing
+
+Networking is a **separate layer**.
+
+---
+
+## 3. Network Model (MANDATORY)
+
+### Use **Input Lockstep Networking**
+
+#### Core idea:
+- Both clients run the same deterministic simulation
+- Only **player inputs** are sent over the network
+- No board state is transmitted
+- Both simulations must remain identical
+
+This model is ideal for Tetris-like games.
+
+---
+
+## 4. Determinism Requirements (CRITICAL)
+
+To ensure lockstep works:
+
+- Fixed simulation tick (e.g. 60 Hz)
+- Identical RNG seed for both clients
+- Deterministic piece generation (bag system)
+- No floating-point math in core gameplay
+- Same gravity, rotation, lock-delay logic
+- Identical line clear and scoring rules
+
+Before networking:
+- Input recording + replay must produce identical results
+
+---
+
+## 5. Network Topology
+
+### Host / Client Model (Initial Implementation)
+
+- One player hosts the game
+- One player joins
+- Host is authoritative for:
+  - RNG seed
+  - start tick
+  - game settings
+
+This is sufficient and fair for cooperative gameplay.
+
+---
+
+## 6. Network Library
+
+Use **ENet** for:
+- Reliable, ordered UDP packets
+- Low latency
+- Simple integration with C++
+
+Do NOT use:
+- SDL_net
+- TCP-only networking
+- High-level matchmaking SDKs
+
+---
+
+## 7. Network Packet Design
+
+### Input Packet (Minimal)
+
+```cpp
+struct InputPacket {
+    uint32_t tick;
+    uint8_t buttons; // bitmask
+};
+````
+
+Button bitmask example:
+
+* bit 0 → move left
+* bit 1 → move right
+* bit 2 → rotate
+* bit 3 → soft drop
+* bit 4 → hard drop
+* bit 5 → hold
+
+Packets must be:
+
+* Reliable
+* Ordered
+* Small
+
+---
+
+## 8. Tick & Latency Handling
+
+### Input Delay Buffer (RECOMMENDED)
+
+* Add fixed delay: **4–6 ticks**
+* Simulate tick `T` using inputs for `T + delay`
+* Prevents stalls due to latency spikes
+
+Strict lockstep without buffering is NOT recommended.
+
+---
+
+## 9. Desync Detection (IMPORTANT)
+
+Every N ticks (e.g. once per second):
+
+* Compute a hash of:
+
+  * Both grid halves
+  * Active pieces
+  * RNG index
+  * Score / lines / level
+* Exchange hashes
+* If mismatch:
+
+  * Log desync
+  * Stop game or mark session invalid
+
+This is required for debugging and stability.
+
+---
+
+## 10. Network Session Architecture
+
+Create a dedicated networking module:
+
+```
+/network
+  NetSession.h
+  NetSession.cpp
+```
+
+Responsibilities:
+
+* ENet host/client setup
+* Input packet send/receive
+* Tick synchronization
+* Latency buffering
+* Disconnect handling
+
+SDL main loop must NOT block on networking.
+
+---
+
+## 11. Integration with Existing COOPERATE Logic
+
+* COOPERATE grid logic stays unchanged
+* SyncLineRenderer remains unchanged
+* Scoring logic remains unchanged
+* Network layer only injects **remote inputs**
+
+Game logic should not know whether partner is:
+
+* Local human
+* AI
+* Network player
+
+---
+
+## 12. UI Integration (Menu Changes)
+
+In COOPERATE selection screen, add a new button:
+
+```
+[ LOCAL CO-OP ]   [ AI PARTNER ]   [ 2 PLAYER (NETWORK) ]
+```
+
+### On selecting 2 PLAYER (NETWORK):
+
+* Show:
+
+  * Host Game
+  * Join Game
+* Display join code or IP
+* Confirm connection before starting
+
+---
+
+## 13. Start Game Flow (Network)
+
+1. Host creates session
+2. Client connects
+3. Host sends:
+
+   * RNG seed
+   * start tick
+   * game settings
+4. Both wait until agreed start tick
+5. Simulation begins simultaneously
+
+---
+
+## 14. Disconnect & Error Handling
+
+* If connection drops:
+
+  * Pause game
+  * Show “Reconnecting…”
+  * After timeout:
+
+    * End match or switch to AI (optional)
+* Never crash
+* Never corrupt game state
+
+---
+
+## 15. What NOT to Implement
+
+* ❌ Full state synchronization
+* ❌ Prediction / rollback
+* ❌ Server-authoritative gameplay
+* ❌ Complex matchmaking
+* ❌ Versus mechanics
+
+This is cooperative, not competitive.
+
+---
+
+## 16. Acceptance Criteria
+
+* Two players can complete COOPERATE mode over network
+* Gameplay matches local COOPERATE exactly
+* No noticeable input lag under normal latency
+* Desync detection works
+* Offline / disconnect handled gracefully
+* SDL3 render loop remains smooth
+
+---
+
+## 17. Summary for Copilot
+
+Integrate networked cooperative multiplayer into Spacetris using SDL3 + C++ with ENet. Implement input lockstep networking with deterministic simulation, fixed tick rate, input buffering, and desync detection. Add a new COOPERATE menu option “2 PLAYER (NETWORK)” that allows host/join flow. Networking must be modular, non-blocking, and transparent to existing gameplay logic.
diff --git a/package-quick.ps1 b/package-quick.ps1
index 48eebdb..6740734 100644
--- a/package-quick.ps1
+++ b/package-quick.ps1
@@ -1,7 +1,7 @@
 #!/usr/bin/env pwsh
 <#
 .SYNOPSIS
-Quick Production Package Creator for Tetris SDL3
+Quick Production Package Creator for Spacetris SDL3
 
 .DESCRIPTION
 This script creates a production package using the existing build-msvc directory.
@@ -12,8 +12,8 @@ param(
     [string]$OutputDir = "dist"
 )
 
-$ProjectName = "tetris"
-$PackageDir = Join-Path $OutputDir "TetrisGame"
+$ProjectName = "spacetris"
+$PackageDir = Join-Path $OutputDir "SpacetrisGame"
 $Version = Get-Date -Format "yyyy.MM.dd"
 
 function Write-ColorOutput($ForegroundColor) {
@@ -29,13 +29,13 @@ function Write-Warning { Write-ColorOutput Yellow $args }
 function Write-Error { Write-ColorOutput Red $args }
 
 Write-Info "======================================"
-Write-Info "   Tetris Quick Package Creator"
+Write-Info "   Spacetris Quick Package Creator"
 Write-Info "======================================"
 
 # Check if build exists
-$ExecutablePath = "build-msvc\Debug\tetris.exe"
+$ExecutablePath = "build-msvc\Debug\spacetris.exe"
 if (!(Test-Path $ExecutablePath)) {
-    $ExecutablePath = "build-msvc\Release\tetris.exe"
+    $ExecutablePath = "build-msvc\Release\spacetris.exe"
     if (!(Test-Path $ExecutablePath)) {
         Write-Error "No executable found in build-msvc directory. Please build the project first."
         exit 1
@@ -52,7 +52,7 @@ New-Item -ItemType Directory -Path $PackageDir -Force | Out-Null
 
 # Copy executable
 Copy-Item $ExecutablePath $PackageDir
-Write-Success "Copied tetris.exe"
+Write-Success "Copied spacetris.exe"
 
 # Copy assets
 if (Test-Path "assets") {
@@ -82,7 +82,7 @@ if (Test-Path $VcpkgBin) {
 $LaunchContent = @"
 @echo off
 cd /d "%~dp0"
-tetris.exe
+spacetris.exe
 if %errorlevel% neq 0 (
     echo.
     echo Game crashed or failed to start!
@@ -91,22 +91,22 @@ if %errorlevel% neq 0 (
     pause
 )
 "@
-$LaunchContent | Out-File -FilePath (Join-Path $PackageDir "Launch-Tetris.bat") -Encoding ASCII
-Write-Success "Created Launch-Tetris.bat"
+$LaunchContent | Out-File -FilePath (Join-Path $PackageDir "Launch-Spacetris.bat") -Encoding ASCII
+Write-Success "Created Launch-Spacetris.bat"
 
 # Create README
 $ReadmeContent = @"
-Tetris SDL3 Game
-================
+Spacetris SDL3 Game
+===================
 
 ## Quick Start
-1. Run Launch-Tetris.bat or tetris.exe
+1. Run Launch-Spacetris.bat or spacetris.exe
 2. Use arrow keys to move, Z/X to rotate, Space to drop
 3. Press F11 for fullscreen, Esc for menu
 
 ## Files
-- tetris.exe: Main game
-- Launch-Tetris.bat: Safe launcher with error handling
+- spacetris.exe: Main game
+- Launch-Spacetris.bat: Safe launcher with error handling
 - assets/: Game resources (music, images, fonts)
 - *.dll: Required libraries
 
@@ -129,7 +129,7 @@ $PackageSize = (Get-ChildItem $PackageDir -Recurse | Measure-Object -Property Le
 $PackageSizeMB = [math]::Round($PackageSize / 1MB, 2)
 
 # Create ZIP
-$ZipPath = Join-Path $OutputDir "TetrisGame-$Version.zip"
+$ZipPath = Join-Path $OutputDir "SpacetrisGame-$Version.zip"
 try {
     Compress-Archive -Path $PackageDir -DestinationPath $ZipPath -Force
     Write-Success "Created ZIP: $ZipPath"
diff --git a/scripts/check_braces.ps1 b/scripts/check_braces.ps1
new file mode 100644
index 0000000..e69de29
diff --git a/scripts/check_comments.ps1 b/scripts/check_comments.ps1
new file mode 100644
index 0000000..e69de29
diff --git a/scripts/create-dmg.sh b/scripts/create-dmg.sh
new file mode 100644
index 0000000..ea0fff6
--- /dev/null
+++ b/scripts/create-dmg.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Create a distributable DMG for the macOS Spacetris app
+# Usage: ./scripts/create-dmg.sh <app-bundle-path> <output-dmg>
+# Example: ./scripts/create-dmg.sh dist/SpacetrisGame-mac/spacetris.app dist/SpacetrisGame.dmg
+
+if [[ $# -lt 2 ]]; then
+    echo "Usage: $0 <app-bundle-path> <output-dmg>"
+    echo "Example: $0 dist/SpacetrisGame-mac/spacetris.app dist/SpacetrisGame.dmg"
+    exit 1
+fi
+
+APP_BUNDLE="$1"
+OUTPUT_DMG="$2"
+
+if [[ ! -d "$APP_BUNDLE" ]]; then
+    echo "Error: App bundle not found at $APP_BUNDLE" >&2
+    exit 1
+fi
+
+if [[ ! "$APP_BUNDLE" =~ \.app$ ]]; then
+    echo "Error: First argument must be a .app bundle" >&2
+    exit 1
+fi
+
+# Remove existing DMG if present
+rm -f "$OUTPUT_DMG"
+
+APP_NAME=$(basename "$APP_BUNDLE" .app)
+VOLUME_NAME="$APP_NAME"
+TEMP_DMG="${OUTPUT_DMG%.dmg}-temp.dmg"
+
+echo "[create-dmg] Creating temporary DMG..."
+# Create a temporary read-write DMG (generous size to fit the app + padding)
+hdiutil create -size 200m -fs HFS+ -volname "$VOLUME_NAME" "$TEMP_DMG"
+
+echo "[create-dmg] Mounting temporary DMG..."
+MOUNT_DIR=$(hdiutil attach "$TEMP_DMG" -nobrowse | grep "/Volumes/$VOLUME_NAME" | awk '{print $3}')
+
+if [[ -z "$MOUNT_DIR" ]]; then
+    echo "Error: Failed to mount temporary DMG" >&2
+    exit 1
+fi
+
+echo "[create-dmg] Copying app bundle to DMG..."
+cp -R "$APP_BUNDLE" "$MOUNT_DIR/"
+
+# Create Applications symlink for drag-and-drop installation
+echo "[create-dmg] Creating Applications symlink..."
+ln -s /Applications "$MOUNT_DIR/Applications"
+
+# Set custom icon if available
+VOLUME_ICON="$APP_BUNDLE/Contents/Resources/AppIcon.icns"
+if [[ -f "$VOLUME_ICON" ]]; then
+    echo "[create-dmg] Setting custom volume icon..."
+    cp "$VOLUME_ICON" "$MOUNT_DIR/.VolumeIcon.icns"
+    SetFile -c icnC "$MOUNT_DIR/.VolumeIcon.icns" 2>/dev/null || true
+fi
+
+# Unmount
+echo "[create-dmg] Ejecting temporary DMG..."
+hdiutil detach "$MOUNT_DIR"
+
+# Convert to compressed read-only DMG
+echo "[create-dmg] Converting to compressed DMG..."
+hdiutil convert "$TEMP_DMG" -format UDZO -o "$OUTPUT_DMG"
+
+# Cleanup
+rm -f "$TEMP_DMG"
+
+echo "[create-dmg] Created: $OUTPUT_DMG"
diff --git a/scripts/find_unmatched.ps1 b/scripts/find_unmatched.ps1
new file mode 100644
index 0000000..e69de29
diff --git a/scripts/generate-mac-icon.sh b/scripts/generate-mac-icon.sh
new file mode 100644
index 0000000..331a320
--- /dev/null
+++ b/scripts/generate-mac-icon.sh
@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+    echo "Usage: $0 <source-png> <output-icns>"
+    exit 1
+fi
+
+ICON_SRC="$1"
+ICON_DEST="$2"
+
+if [[ -f "$ICON_DEST" ]]; then
+    exit 0
+fi
+
+if [[ ! -f "$ICON_SRC" ]]; then
+    echo "[generate-mac-icon] Source icon not found: $ICON_SRC" >&2
+    exit 1
+fi
+
+if ! command -v iconutil >/dev/null 2>&1; then
+    echo "[generate-mac-icon] iconutil not found" >&2
+    exit 1
+fi
+
+TMPDIR=$(mktemp -d)
+ICONSET="$TMPDIR/AppIcon.iconset"
+mkdir -p "$ICONSET"
+
+for SIZE in 16 32 64 128 256 512; do
+    sips -s format png "$ICON_SRC" --resampleHeightWidth $SIZE $SIZE --out "$ICONSET/icon_${SIZE}x${SIZE}.png" >/dev/null
+    sips -s format png "$ICON_SRC" --resampleHeightWidth $((SIZE * 2)) $((SIZE * 2)) --out "$ICONSET/icon_${SIZE}x${SIZE}@2x.png" >/dev/null
+done
+
+iconutil -c icns "$ICONSET" -o "$ICON_DEST"
+rm -rf "$TMPDIR"
+
+if [[ -f "$ICON_DEST" ]]; then
+    echo "[generate-mac-icon] Generated $ICON_DEST"
+else
+    echo "[generate-mac-icon] Failed to create $ICON_DEST" >&2
+    exit 1
+fi
diff --git a/settings.ini b/settings.ini
new file mode 100644
index 0000000..99029f7
--- /dev/null
+++ b/settings.ini
@@ -0,0 +1,20 @@
+; Tetris Game Settings
+; This file is auto-generated
+
+[Display]
+Fullscreen=1
+
+[Audio]
+Music=1
+Sound=1
+
+[Gameplay]
+SmoothScroll=1
+
+UpRotateClockwise=0
+
+[Player]
+Name=GREGOR
+
+[Debug]
+Enabled=1
diff --git a/src/app/AssetLoader.cpp b/src/app/AssetLoader.cpp
new file mode 100644
index 0000000..95d060e
--- /dev/null
+++ b/src/app/AssetLoader.cpp
@@ -0,0 +1,139 @@
+#include "app/AssetLoader.h"
+#include <SDL3_image/SDL_image.h>
+#include <algorithm>
+
+AssetLoader::AssetLoader() = default;
+
+AssetLoader::~AssetLoader() {
+    shutdown();
+}
+
+void AssetLoader::init(SDL_Renderer* renderer) {
+    m_renderer = renderer;
+}
+
+void AssetLoader::shutdown() {
+    // Destroy textures
+    {
+        std::lock_guard<std::mutex> lk(m_texturesMutex);
+        for (auto &p : m_textures) {
+            if (p.second) SDL_DestroyTexture(p.second);
+        }
+        m_textures.clear();
+    }
+
+    // Clear queue and errors
+    {
+        std::lock_guard<std::mutex> lk(m_queueMutex);
+        m_queue.clear();
+    }
+    {
+        std::lock_guard<std::mutex> lk(m_errorsMutex);
+        m_errors.clear();
+    }
+
+    m_totalTasks = 0;
+    m_loadedTasks = 0;
+    m_renderer = nullptr;
+}
+
+void AssetLoader::setBasePath(const std::string& basePath) {
+    m_basePath = basePath;
+}
+
+void AssetLoader::queueTexture(const std::string& path) {
+    {
+        std::lock_guard<std::mutex> lk(m_queueMutex);
+        m_queue.push_back(path);
+    }
+    m_totalTasks.fetch_add(1, std::memory_order_relaxed);
+}
+
+bool AssetLoader::performStep() {
+    std::string path;
+    {
+        std::lock_guard<std::mutex> lk(m_queueMutex);
+        if (m_queue.empty()) return true;
+        path = m_queue.front();
+        m_queue.erase(m_queue.begin());
+    }
+
+    {
+        std::lock_guard<std::mutex> lk(m_currentLoadingMutex);
+        m_currentLoading = path;
+    }
+
+    std::string fullPath = m_basePath.empty() ? path : (m_basePath + "/" + path);
+
+    SDL_Surface* surf = IMG_Load(fullPath.c_str());
+    if (!surf) {
+        std::lock_guard<std::mutex> lk(m_errorsMutex);
+        m_errors.push_back(std::string("IMG_Load failed: ") + fullPath + " -> " + SDL_GetError());
+    } else {
+        SDL_Texture* tex = SDL_CreateTextureFromSurface(m_renderer, surf);
+        SDL_DestroySurface(surf);
+        if (!tex) {
+            std::lock_guard<std::mutex> lk(m_errorsMutex);
+            m_errors.push_back(std::string("CreateTexture failed: ") + fullPath);
+        } else {
+            std::lock_guard<std::mutex> lk(m_texturesMutex);
+            auto& slot = m_textures[path];
+            if (slot && slot != tex) {
+                SDL_DestroyTexture(slot);
+            }
+            slot = tex;
+        }
+    }
+
+    m_loadedTasks.fetch_add(1, std::memory_order_relaxed);
+
+    {
+        std::lock_guard<std::mutex> lk(m_currentLoadingMutex);
+        m_currentLoading.clear();
+    }
+
+    // Return true when no more queued tasks
+    {
+        std::lock_guard<std::mutex> lk(m_queueMutex);
+        return m_queue.empty();
+    }
+}
+
+void AssetLoader::adoptTexture(const std::string& path, SDL_Texture* texture) {
+    if (!texture) {
+        return;
+    }
+
+    std::lock_guard<std::mutex> lk(m_texturesMutex);
+    auto& slot = m_textures[path];
+    if (slot && slot != texture) {
+        SDL_DestroyTexture(slot);
+    }
+    slot = texture;
+}
+
+float AssetLoader::getProgress() const {
+    int total = m_totalTasks.load(std::memory_order_relaxed);
+    if (total <= 0) return 1.0f;
+    int loaded = m_loadedTasks.load(std::memory_order_relaxed);
+    return static_cast<float>(loaded) / static_cast<float>(total);
+}
+
+std::vector<std::string> AssetLoader::getAndClearErrors() {
+    std::lock_guard<std::mutex> lk(m_errorsMutex);
+    std::vector<std::string> out = m_errors;
+    m_errors.clear();
+    return out;
+}
+
+SDL_Texture* AssetLoader::getTexture(const std::string& path) const {
+    std::lock_guard<std::mutex> lk(m_texturesMutex);
+    auto it = m_textures.find(path);
+    if (it == m_textures.end()) return nullptr;
+    return it->second;
+}
+
+std::string AssetLoader::getCurrentLoading() const {
+    std::lock_guard<std::mutex> lk(m_currentLoadingMutex);
+    return m_currentLoading;
+}
diff --git a/src/app/AssetLoader.h b/src/app/AssetLoader.h
new file mode 100644
index 0000000..fac6128
--- /dev/null
+++ b/src/app/AssetLoader.h
@@ -0,0 +1,68 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+#include <string>
+#include <vector>
+#include <mutex>
+#include <atomic>
+#include <unordered_map>
+
+// Lightweight AssetLoader scaffold.
+// Responsibilities:
+// - Queue textures to load (main thread) and perform incremental loads via performStep().
+// - Store loaded SDL_Texture* instances and provide accessors.
+// - Collect loading errors thread-safely.
+// NOTE: All SDL texture creation MUST happen on the thread that owns the SDL_Renderer.
+class AssetLoader {
+public:
+    AssetLoader();
+    ~AssetLoader();
+
+    void init(SDL_Renderer* renderer);
+    void shutdown();
+
+    void setBasePath(const std::string& basePath);
+
+    // Queue a texture path (relative to base path) for loading.
+    void queueTexture(const std::string& path);
+
+    // Perform a single loading step (load one queued asset).
+    // Returns true when all queued tasks are complete, false otherwise.
+    bool performStep();
+
+    // Progress in [0,1]. If no tasks, returns 1.0f.
+    float getProgress() const;
+
+    // Retrieve and clear accumulated error messages.
+    std::vector<std::string> getAndClearErrors();
+
+    // Get a loaded texture (or nullptr if not loaded).
+    SDL_Texture* getTexture(const std::string& path) const;
+
+    // Adopt an externally-created texture so AssetLoader owns its lifetime.
+    // If a texture is already registered for this path, it will be replaced.
+    void adoptTexture(const std::string& path, SDL_Texture* texture);
+
+    // Return currently-loading path (empty when idle).
+    std::string getCurrentLoading() const;
+
+private:
+    SDL_Renderer* m_renderer = nullptr;
+    std::string m_basePath;
+
+    // queued paths (simple FIFO)
+    std::vector<std::string> m_queue;
+    mutable std::mutex m_queueMutex;
+
+    std::unordered_map<std::string, SDL_Texture*> m_textures;
+    mutable std::mutex m_texturesMutex;
+
+    std::vector<std::string> m_errors;
+    mutable std::mutex m_errorsMutex;
+
+    std::atomic<int> m_totalTasks{0};
+    std::atomic<int> m_loadedTasks{0};
+
+    std::string m_currentLoading;
+    mutable std::mutex m_currentLoadingMutex;
+};
diff --git a/src/app/BackgroundManager.cpp b/src/app/BackgroundManager.cpp
new file mode 100644
index 0000000..c043b39
--- /dev/null
+++ b/src/app/BackgroundManager.cpp
@@ -0,0 +1,165 @@
+#include "app/BackgroundManager.h"
+#include <SDL3/SDL.h>
+#include <SDL3_image/SDL_image.h>
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+#include "utils/ImagePathResolver.h"
+
+struct BackgroundManager::Impl {
+    enum class Phase { Idle, ZoomOut, ZoomIn };
+    SDL_Texture* currentTex = nullptr;
+    SDL_Texture* nextTex = nullptr;
+    int currentLevel = -1;
+    int queuedLevel = -1;
+    float phaseElapsedMs = 0.0f;
+    float phaseDurationMs = 0.0f;
+    float fadeDurationMs = 1200.0f;
+    Phase phase = Phase::Idle;
+};
+
+static float getPhaseDurationMs(const BackgroundManager::Impl& fader, BackgroundManager::Impl::Phase ph) {
+    const float total = std::max(1200.0f, fader.fadeDurationMs);
+    switch (ph) {
+        case BackgroundManager::Impl::Phase::ZoomOut: return total * 0.45f;
+        case BackgroundManager::Impl::Phase::ZoomIn:  return total * 0.45f;
+        default: return 0.0f;
+    }
+}
+
+static void destroyTex(SDL_Texture*& t) {
+    if (t) { SDL_DestroyTexture(t); t = nullptr; }
+}
+
+BackgroundManager::BackgroundManager() : impl(new Impl()) {}
+BackgroundManager::~BackgroundManager() { reset(); delete impl; impl = nullptr; }
+
+bool BackgroundManager::queueLevelBackground(SDL_Renderer* renderer, int level) {
+    if (!renderer) return false;
+    level = std::clamp(level, 0, 32);
+    if (impl->currentLevel == level || impl->queuedLevel == level) return true;
+
+    char bgPath[256];
+    std::snprintf(bgPath, sizeof(bgPath), "assets/images/levels/level%d.jpg", level);
+    const std::string resolved = AssetPath::resolveImagePath(bgPath);
+
+    SDL_Surface* s = IMG_Load(resolved.c_str());
+    if (!s) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Background load failed: %s (%s)", bgPath, resolved.c_str());
+        return false;
+    }
+    SDL_Texture* tex = SDL_CreateTextureFromSurface(renderer, s);
+    SDL_DestroySurface(s);
+    if (!tex) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "CreateTexture failed for %s", resolved.c_str());
+        return false;
+    }
+
+    destroyTex(impl->nextTex);
+    impl->nextTex = tex;
+    impl->queuedLevel = level;
+
+    if (!impl->currentTex) {
+        impl->currentTex = impl->nextTex;
+        impl->currentLevel = impl->queuedLevel;
+        impl->nextTex = nullptr;
+        impl->queuedLevel = -1;
+        impl->phase = Impl::Phase::Idle;
+        impl->phaseElapsedMs = 0.0f;
+        impl->phaseDurationMs = 0.0f;
+    } else if (impl->phase == Impl::Phase::Idle) {
+        impl->phase = Impl::Phase::ZoomOut;
+        impl->phaseDurationMs = getPhaseDurationMs(*impl, impl->phase);
+        impl->phaseElapsedMs = 0.0f;
+    }
+    return true;
+}
+
+void BackgroundManager::update(float frameMs) {
+    if (impl->phase == Impl::Phase::Idle) return;
+    if (!impl->currentTex && !impl->nextTex) { impl->phase = Impl::Phase::Idle; return; }
+
+    impl->phaseElapsedMs += frameMs;
+    if (impl->phaseElapsedMs < std::max(1.0f, impl->phaseDurationMs)) return;
+
+    if (impl->phase == Impl::Phase::ZoomOut) {
+        if (impl->nextTex) {
+            destroyTex(impl->currentTex);
+            impl->currentTex = impl->nextTex;
+            impl->currentLevel = impl->queuedLevel;
+            impl->nextTex = nullptr;
+            impl->queuedLevel = -1;
+        }
+        impl->phase = Impl::Phase::ZoomIn;
+        impl->phaseDurationMs = getPhaseDurationMs(*impl, impl->phase);
+        impl->phaseElapsedMs = 0.0f;
+    } else if (impl->phase == Impl::Phase::ZoomIn) {
+        impl->phase = Impl::Phase::Idle;
+        impl->phaseElapsedMs = 0.0f;
+        impl->phaseDurationMs = 0.0f;
+    }
+}
+
+static void renderDynamic(SDL_Renderer* renderer, SDL_Texture* tex, int winW, int winH, float baseScale, float motionClockMs, float alphaMul) {
+    if (!renderer || !tex) return;
+    const float seconds = motionClockMs * 0.001f;
+    const float wobble = std::max(0.4f, baseScale + std::sin(seconds * 0.07f) * 0.02f + std::sin(seconds * 0.23f) * 0.01f);
+    const float rotation = std::sin(seconds * 0.035f) * 1.25f;
+    const float panX = std::sin(seconds * 0.11f) * winW * 0.02f;
+    const float panY = std::cos(seconds * 0.09f) * winH * 0.015f;
+    SDL_FRect dest{ (winW - winW * wobble) * 0.5f + panX, (winH - winH * wobble) * 0.5f + panY, winW * wobble, winH * wobble };
+    SDL_FPoint center{dest.w * 0.5f, dest.h * 0.5f};
+    Uint8 alpha = static_cast<Uint8>(std::clamp(alphaMul, 0.0f, 1.0f) * 255.0f);
+    SDL_SetTextureAlphaMod(tex, alpha);
+    SDL_RenderTextureRotated(renderer, tex, nullptr, &dest, rotation, &center, SDL_FLIP_NONE);
+    SDL_SetTextureAlphaMod(tex, 255);
+}
+
+void BackgroundManager::render(SDL_Renderer* renderer, int winW, int winH, float motionClockMs) {
+    if (!renderer) return;
+    SDL_FRect fullRect{0.f,0.f,(float)winW,(float)winH};
+    float duration = std::max(1.0f, impl->phaseDurationMs);
+    float progress = (impl->phase == Impl::Phase::Idle) ? 0.0f : std::clamp(impl->phaseElapsedMs / duration, 0.0f, 1.0f);
+    const float seconds = motionClockMs * 0.001f;
+
+    if (impl->phase == Impl::Phase::ZoomOut) {
+        float scale = 1.0f + progress * 0.15f;
+        if (impl->currentTex) {
+            renderDynamic(renderer, impl->currentTex, winW, winH, scale, motionClockMs, (1.0f - progress * 0.4f));
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+            SDL_SetRenderDrawColor(renderer, 0,0,0, Uint8(progress * 200.0f));
+            SDL_RenderFillRect(renderer, &fullRect);
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+        }
+    } else if (impl->phase == Impl::Phase::ZoomIn) {
+        float scale = 1.10f - progress * 0.10f;
+        Uint8 alpha = Uint8((0.4f + progress * 0.6f) * 255.0f);
+        if (impl->currentTex) {
+            renderDynamic(renderer, impl->currentTex, winW, winH, scale, motionClockMs, alpha / 255.0f);
+        }
+    } else {
+        if (impl->currentTex) {
+            renderDynamic(renderer, impl->currentTex, winW, winH, 1.02f, motionClockMs, 1.0f);
+            float pulse = 0.35f + 0.25f * (0.5f + 0.5f * std::sin(seconds * 0.5f));
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+            SDL_SetRenderDrawColor(renderer, 5,12,28, Uint8(pulse * 90.0f));
+            SDL_RenderFillRect(renderer, &fullRect);
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+        } else if (impl->nextTex) {
+            renderDynamic(renderer, impl->nextTex, winW, winH, 1.02f, motionClockMs, 1.0f);
+        } else {
+            SDL_SetRenderDrawColor(renderer, 0,0,0,255);
+            SDL_RenderFillRect(renderer, &fullRect);
+        }
+    }
+}
+
+void BackgroundManager::reset() {
+    destroyTex(impl->currentTex);
+    destroyTex(impl->nextTex);
+    impl->currentLevel = -1;
+    impl->queuedLevel = -1;
+    impl->phaseElapsedMs = 0.0f;
+    impl->phaseDurationMs = 0.0f;
+    impl->phase = Impl::Phase::Idle;
+}
diff --git a/src/app/BackgroundManager.h b/src/app/BackgroundManager.h
new file mode 100644
index 0000000..dc53cb8
--- /dev/null
+++ b/src/app/BackgroundManager.h
@@ -0,0 +1,18 @@
+#pragma once
+#include <SDL3/SDL.h>
+
+class BackgroundManager {
+public:
+    BackgroundManager();
+    ~BackgroundManager();
+
+    bool queueLevelBackground(SDL_Renderer* renderer, int level);
+    void update(float frameMs);
+    void render(SDL_Renderer* renderer, int winW, int winH, float motionClockMs);
+    void reset();
+
+    struct Impl;
+
+private:
+    Impl* impl;
+};
diff --git a/src/app/Fireworks.cpp b/src/app/Fireworks.cpp
new file mode 100644
index 0000000..4e25ae1
--- /dev/null
+++ b/src/app/Fireworks.cpp
@@ -0,0 +1,150 @@
+#include "app/Fireworks.h"
+#include <SDL3/SDL.h>
+#include <vector>
+#include <cstdlib>
+#include <cmath>
+#include <algorithm>
+
+namespace {
+struct BlockParticle {
+    float x{}, y{}, vx{}, vy{}, size{}, alpha{}, decay{}, wobblePhase{}, wobbleSpeed{}, coreHeat{};
+    BlockParticle(float sx, float sy) : x(sx), y(sy) {
+        const float spreadDeg = 35.0f;
+        const float angleDeg = -90.0f + spreadDeg * ((rand() % 200) / 100.0f - 1.0f);
+        const float angleRad = angleDeg * 3.1415926f / 180.0f;
+        float speed = 1.3f + (rand() % 220) / 80.0f;
+        vx = std::cos(angleRad) * speed * 0.55f;
+        vy = std::sin(angleRad) * speed;
+        size = 6.0f + (rand() % 40) / 10.0f;
+        alpha = 1.0f;
+        decay = 0.0095f + (rand() % 180) / 12000.0f;
+        wobblePhase = (rand() % 628) / 100.0f;
+        wobbleSpeed = 0.08f + (rand() % 60) / 600.0f;
+        coreHeat = 0.65f + (rand() % 35) / 100.0f;
+    }
+    bool update() {
+        vx *= 0.992f;
+        vy = vy * 0.985f - 0.015f;
+        x += vx;
+        y += vy;
+        wobblePhase += wobbleSpeed;
+        x += std::sin(wobblePhase) * 0.12f;
+        alpha -= decay;
+        size = std::max(1.8f, size - 0.03f);
+        coreHeat = std::max(0.0f, coreHeat - decay * 0.6f);
+        return alpha > 0.03f;
+    }
+};
+
+struct TetrisFirework {
+    std::vector<BlockParticle> particles;
+    TetrisFirework(float x, float y) {
+        int particleCount = 30 + rand() % 25;
+        particles.reserve(particleCount);
+        for (int i=0;i<particleCount;++i) particles.emplace_back(x,y);
+    }
+    bool update() {
+        for (auto it = particles.begin(); it != particles.end();) {
+            if (!it->update()) it = particles.erase(it);
+            else ++it;
+        }
+        return !particles.empty();
+    }
+};
+
+static std::vector<TetrisFirework> fireworks;
+static double logoAnimCounter = 0.0;
+static int hoveredButton = -1;
+
+static SDL_Color blendFireColor(float heat, float alphaScale, Uint8 minG, Uint8 minB) {
+    heat = std::clamp(heat, 0.0f, 1.0f);
+    Uint8 r = 255;
+    Uint8 g = static_cast<Uint8>(std::clamp(120.0f + heat * (255.0f - 120.0f), float(minG), 255.0f));
+    Uint8 b = static_cast<Uint8>(std::clamp(40.0f + (1.0f - heat) * 60.0f, float(minB), 255.0f));
+    Uint8 a = static_cast<Uint8>(std::clamp(alphaScale * 255.0f, 0.0f, 255.0f));
+    return SDL_Color{r,g,b,a};
+}
+} // namespace
+
+namespace AppFireworks {
+void update(double frameMs) {
+    if (fireworks.size() < 5 && (rand() % 100) < 2) {
+        float x = 1200.0f * 0.55f + float(rand() % int(1200.0f * 0.35f));
+        float y = 1000.0f * 0.80f + float(rand() % int(1000.0f * 0.15f));
+        fireworks.emplace_back(x,y);
+    }
+    for (auto it = fireworks.begin(); it != fireworks.end();) {
+        if (!it->update()) it = fireworks.erase(it);
+        else ++it;
+    }
+}
+
+void draw(SDL_Renderer* renderer, SDL_Texture*) {
+    if (!renderer) return;
+    SDL_BlendMode previousBlend = SDL_BLENDMODE_NONE;
+    SDL_GetRenderDrawBlendMode(renderer, &previousBlend);
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_ADD);
+    static constexpr int quadIdx[6] = {0,1,2,2,1,3};
+
+    auto makeV = [](float px, float py, SDL_Color c){
+        SDL_Vertex v{};
+        v.position.x = px;
+        v.position.y = py;
+        v.color = SDL_FColor{ c.r/255.0f, c.g/255.0f, c.b/255.0f, c.a/255.0f };
+        return v;
+    };
+
+    for (auto& f : fireworks) {
+        for (auto& p : f.particles) {
+            const float heat = std::clamp(p.alpha * 1.25f + p.coreHeat * 0.5f, 0.0f, 1.0f);
+            SDL_Color glow = blendFireColor(0.45f + heat * 0.55f, p.alpha * 0.55f, 100, 40);
+            SDL_Color tailBase = blendFireColor(heat * 0.75f, p.alpha * 0.5f, 70, 25);
+            SDL_Color tailTip = blendFireColor(heat * 0.35f, p.alpha * 0.2f, 40, 15);
+            SDL_Color core = blendFireColor(heat, std::min(1.0f, p.alpha * 1.1f), 150, 80);
+
+            float velLen = std::sqrt(p.vx*p.vx + p.vy*p.vy);
+            SDL_FPoint dir = velLen > 0.001f ? SDL_FPoint{p.vx/velLen,p.vy/velLen} : SDL_FPoint{0.0f,-1.0f};
+            SDL_FPoint perp{-dir.y, dir.x};
+            const float baseW = std::max(0.8f, p.size * 0.55f);
+            const float tipW = baseW * 0.35f;
+            const float tailLen = p.size * (3.0f + (1.0f - p.alpha) * 1.8f);
+
+            SDL_FPoint base{p.x,p.y};
+            SDL_FPoint tip{p.x + dir.x*tailLen, p.y + dir.y*tailLen};
+
+            SDL_Vertex tail[4];
+            tail[0] = makeV(base.x + perp.x * baseW, base.y + perp.y * baseW, tailBase);
+            tail[1] = makeV(base.x - perp.x * baseW, base.y - perp.y * baseW, tailBase);
+            tail[2] = makeV(tip.x + perp.x * tipW, tip.y + perp.y * tipW, tailTip);
+            tail[3] = makeV(tip.x - perp.x * tipW, tip.y - perp.y * tipW, tailTip);
+            SDL_RenderGeometry(renderer, nullptr, tail, 4, quadIdx, 6);
+
+            const float glowAlong = p.size * 0.95f;
+            const float glowAcross = p.size * 0.6f;
+            SDL_Vertex glowV[4];
+            glowV[0] = makeV(base.x + dir.x * glowAlong, base.y + dir.y * glowAlong, glow);
+            glowV[1] = makeV(base.x - dir.x * glowAlong, base.y - dir.y * glowAlong, glow);
+            glowV[2] = makeV(base.x + perp.x * glowAcross, base.y + perp.y * glowAcross, glow);
+            glowV[3] = makeV(base.x - perp.x * glowAcross, base.y - perp.y * glowAcross, glow);
+            SDL_RenderGeometry(renderer, nullptr, glowV, 4, quadIdx, 6);
+
+            const float coreW = p.size * 0.35f;
+            const float coreH = p.size * 0.9f;
+            SDL_Vertex coreV[4];
+            coreV[0] = makeV(base.x + perp.x * coreW, base.y + perp.y * coreW, core);
+            coreV[1] = makeV(base.x - perp.x * coreW, base.y - perp.y * coreW, core);
+            coreV[2] = makeV(base.x + dir.x * coreH, base.y + dir.y * coreH, core);
+            coreV[3] = makeV(base.x - dir.x * coreH, base.y - dir.y * coreH, core);
+            SDL_RenderGeometry(renderer, nullptr, coreV, 4, quadIdx, 6);
+        }
+    }
+
+    SDL_SetRenderDrawBlendMode(renderer, previousBlend);
+}
+
+double getLogoAnimCounter() { return logoAnimCounter; }
+int getHoveredButton() { return hoveredButton; }
+void spawn(float x, float y) {
+    fireworks.emplace_back(x, y);
+}
+} // namespace AppFireworks
diff --git a/src/app/Fireworks.h b/src/app/Fireworks.h
new file mode 100644
index 0000000..c28b419
--- /dev/null
+++ b/src/app/Fireworks.h
@@ -0,0 +1,10 @@
+#pragma once
+#include <SDL3/SDL.h>
+
+namespace AppFireworks {
+	void draw(SDL_Renderer* renderer, SDL_Texture* tex);
+	void update(double frameMs);
+	double getLogoAnimCounter();
+	int getHoveredButton();
+    void spawn(float x, float y);
+}
diff --git a/src/app/TetrisApp.cpp b/src/app/TetrisApp.cpp
new file mode 100644
index 0000000..0bd4d0b
--- /dev/null
+++ b/src/app/TetrisApp.cpp
@@ -0,0 +1,2735 @@
+// TetrisApp.cpp - Main application runtime split out from main.cpp.
+//
+// This file is intentionally "orchestration-heavy": it wires together SDL, audio,
+// asset loading, and the state machine. Keep gameplay mechanics in the gameplay/
+// and states/ modules.
+
+#include "app/TetrisApp.h"
+
+#include <SDL3/SDL.h>
+#include <SDL3_ttf/SDL_ttf.h>
+
+#include <algorithm>
+#include <array>
+#include <atomic>
+#include <cmath>
+#include <cstdio>
+#include <cstdlib>
+#include <filesystem>
+#include <mutex>
+#include <random>
+#include <sstream>
+#include <string>
+#include <thread>
+#include <vector>
+
+#include "app/AssetLoader.h"
+#include "app/BackgroundManager.h"
+#include "app/Fireworks.h"
+#include "app/TextureLoader.h"
+
+#include "audio/Audio.h"
+#include "audio/MenuWrappers.h"
+#include "audio/SoundEffect.h"
+
+#include "core/Config.h"
+#include "core/Settings.h"
+#include "core/state/StateManager.h"
+
+#include "gameplay/core/Game.h"
+#include "gameplay/coop/CoopGame.h"
+#include "gameplay/coop/CoopAIController.h"
+#include "gameplay/effects/LineEffect.h"
+
+#include "graphics/effects/SpaceWarp.h"
+#include "graphics/effects/Starfield.h"
+#include "graphics/effects/Starfield3D.h"
+#include "graphics/renderers/GameRenderer.h"
+#include "graphics/renderers/RenderPrimitives.h"
+#include "graphics/ui/Font.h"
+#include "graphics/ui/HelpOverlay.h"
+
+#include "network/CoopNetButtons.h"
+#include "network/NetSession.h"
+
+#include "persistence/Scores.h"
+
+#include "states/LevelSelectorState.h"
+#include "states/LoadingManager.h"
+#include "states/LoadingState.h"
+#include "states/MenuState.h"
+#include "states/OptionsState.h"
+#include "states/PlayingState.h"
+#include "states/VideoState.h"
+#include "states/State.h"
+
+#include "ui/BottomMenu.h"
+#include "../resources/AssetPaths.h"
+#include "ui/MenuLayout.h"
+
+#include "utils/ImagePathResolver.h"
+
+// ---------- Game config ----------
+static constexpr int LOGICAL_W = 1200;
+static constexpr int LOGICAL_H = 1000;
+static constexpr int WELL_W = Game::COLS * Game::TILE;
+static constexpr int WELL_H = Game::ROWS * Game::TILE;
+
+#include "ui/UIConstants.h"
+
+static const std::array<SDL_Color, PIECE_COUNT + 1> COLORS = {{
+    SDL_Color{20, 20, 26, 255},  // 0 empty
+    SDL_Color{0, 255, 255, 255}, // I
+    SDL_Color{255, 255, 0, 255}, // O
+    SDL_Color{160, 0, 255, 255}, // T
+    SDL_Color{0, 255, 0, 255},   // S
+    SDL_Color{255, 0, 0, 255},   // Z
+    SDL_Color{0, 0, 255, 255},   // J
+    SDL_Color{255, 160, 0, 255}, // L
+}};
+
+static std::string GetLevelStoryText(int level) {
+    int lvl = std::clamp(level, 1, 100);
+
+    // Milestones
+    switch (lvl) {
+        case 1: return "Launch log: training run, light debris ahead.";
+        case 25: return "Checkpoint: dense field reported, shields ready.";
+        case 50: return "Midway brief: hull stress rising, stay sharp.";
+        case 75: return "Emergency corridor: comms unstable, proceed blind.";
+        case 100: return "Final anomaly: unknown mass ahead, hold course.";
+        default: break;
+    }
+
+    struct Pool { int minL, maxL; std::vector<std::string> lines; };
+    static const std::vector<Pool> pools = {
+        {1, 10, {
+            "Departure logged: light debris, stay on vector.",
+            "Training sector: minimal drift, keep sensors warm.",
+            "Calm approach: verify thrusters and nav locks.",
+            "Outer ring dust: watch for slow movers.",
+            "Clear lanes ahead: focus on smooth rotations."
+        }},
+        {11, 25, {
+            "Asteroid belt thickening; micro-impacts likely.",
+            "Density rising: plot short burns only.",
+            "Field report: medium fragments, unpredictable spin.",
+            "Warning: overlapping paths, reduce horizontal drift.",
+            "Rock chorus ahead; keep payload stable."
+        }},
+        {26, 40, {
+            "Unstable sector: abandoned relays drifting erratic.",
+            "Salvage echoes detected; debris wakes may tug.",
+            "Hull groans recorded; inert structures nearby.",
+            "Navigation buoys dark; trust instruments only.",
+            "Magnetic static rising; expect odd rotations."
+        }},
+        {41, 60, {
+            "Core corridor: heavy asteroids, minimal clearance.",
+            "Impact risk high: armor checks recommended.",
+            "Dense stone flow; time burns carefully.",
+            "Grav eddies noted; blocks may drift late.",
+            "Core shards are brittle; expect sudden splits."
+        }},
+        {61, 80, {
+            "Critical zone: alarms pinned, route unstable.",
+            "Emergency pattern: glide, then cut thrust.",
+            "Sensors flare; debris ionized, visibility low.",
+            "Thermals spiking; keep pieces tight and fast.",
+            "Silent channel; assume worst-case collision."
+        }},
+        {81, 100, {
+            "Unknown space: signals warp, gravity unreliable.",
+            "Anomaly bloom ahead; shapes flicker unpredictably.",
+            "Final drift: void sings through hull plates.",
+            "Black sector: map useless, fly by instinct.",
+            "Edge of chart: nothing responds, just move."
+        }}
+    };
+
+    for (const auto& pool : pools) {
+        if (lvl >= pool.minL && lvl <= pool.maxL && !pool.lines.empty()) {
+            size_t idx = static_cast<size_t>((lvl - pool.minL) % pool.lines.size());
+            return pool.lines[idx];
+        }
+    }
+
+    return "Mission log update unavailable.";
+}
+
+struct TetrisApp::Impl {
+    // Global collector for asset loading errors shown on the loading screen
+    std::vector<std::string> assetLoadErrors;
+    std::mutex assetLoadErrorsMutex;
+    // Loading counters for progress UI and debug overlay
+    std::atomic<int> totalLoadingTasks{0};
+    std::atomic<int> loadedTasks{0};
+    std::string currentLoadingFile;
+    std::mutex currentLoadingMutex;
+
+    // Intro/Menu shared state (wired into StateContext as pointers)
+    double logoAnimCounter = 0.0;
+    bool showSettingsPopup = false;
+    bool showHelpOverlay = false;
+    bool showExitConfirmPopup = false;
+    int exitPopupSelectedButton = 1; // 0 = YES, 1 = NO
+    bool musicEnabled = true;
+    int hoveredButton = -1; // -1 = none, 0 = play, 1 = level, 2 = settings
+    bool isNewHighScore = false;
+    std::string playerName;
+    std::string player2Name;
+    int highScoreEntryIndex = 0; // 0 = entering player1, 1 = entering player2
+    bool helpOverlayPausedGame = false;
+
+    SDL_Window* window = nullptr;
+    SDL_Renderer* renderer = nullptr;
+
+    AssetLoader assetLoader;
+    std::unique_ptr<LoadingManager> loadingManager;
+    std::unique_ptr<TextureLoader> textureLoader;
+
+    FontAtlas pixelFont;
+    FontAtlas font;
+
+    ScoreManager scores;
+    std::atomic<bool> scoresLoadComplete{false};
+    std::jthread scoreLoader;
+    std::jthread menuTrackLoader;
+
+    Starfield starfield;
+    Starfield3D starfield3D;
+    SpaceWarp spaceWarp;
+    SpaceWarpFlightMode warpFlightMode = SpaceWarpFlightMode::Forward;
+    bool warpAutoPilotEnabled = true;
+
+    LineEffect lineEffect;
+
+    SDL_Texture* logoTex = nullptr;
+    SDL_Texture* logoSmallTex = nullptr;
+    int logoSmallW = 0;
+    int logoSmallH = 0;
+    SDL_Texture* backgroundTex = nullptr;
+    SDL_Texture* mainScreenTex = nullptr;
+    int mainScreenW = 0;
+    int mainScreenH = 0;
+
+    SDL_Texture* blocksTex = nullptr;
+    SDL_Texture* asteroidsTex = nullptr;
+    SDL_Texture* scorePanelTex = nullptr;
+    SDL_Texture* statisticsPanelTex = nullptr;
+    SDL_Texture* nextPanelTex = nullptr;
+    SDL_Texture* holdPanelTex = nullptr;
+
+    BackgroundManager levelBackgrounds;
+    int startLevelSelection = 0;
+
+    // Music loading tracking
+    int totalTracks = 0;
+    int currentTrackLoading = 0;
+    bool musicLoaded = false;
+    bool musicStarted = false;
+    bool musicLoadingStarted = false;
+
+    // Loader control: execute incrementally on main thread to avoid SDL threading issues
+    std::atomic_bool loadingStarted{false};
+    std::atomic_bool loadingComplete{false};
+    std::atomic<size_t> loadingStep{0};
+
+    std::unique_ptr<Game> game;
+    std::unique_ptr<CoopGame> coopGame;
+    std::vector<std::string> singleSounds;
+    std::vector<std::string> doubleSounds;
+    std::vector<std::string> tripleSounds;
+    std::vector<std::string> tetrisSounds;
+    bool suppressLineVoiceForLevelUp = false;
+    bool skipNextLevelUpJingle = false;
+
+    // COOPERATE option: when true, right player is AI-controlled.
+    bool coopVsAI = false;
+
+    CoopAIController coopAI;
+
+    AppState state = AppState::Loading;
+    double loadingProgress = 0.0;
+    Uint64 loadStart = 0;
+    bool running = true;
+    bool isFullscreen = false;
+    bool leftHeld = false;
+    bool rightHeld = false;
+    bool p1LeftHeld = false;
+    bool p1RightHeld = false;
+    bool p2LeftHeld = false;
+    bool p2RightHeld = false;
+    double moveTimerMs = 0.0;
+    double p1MoveTimerMs = 0.0;
+    double p2MoveTimerMs = 0.0;
+
+    // Network coop fixed-tick state (used only when ctx.coopNetEnabled is true)
+    double coopNetAccMs = 0.0;
+    uint32_t coopNetCachedTick = 0xFFFFFFFFu;
+    uint8_t coopNetCachedButtons = 0;
+    uint32_t coopNetLastHashSentTick = 0xFFFFFFFFu;
+    double DAS = 170.0;
+    double ARR = 40.0;
+    SDL_Rect logicalVP{0, 0, LOGICAL_W, LOGICAL_H};
+    float logicalScale = 1.f;
+    Uint64 lastMs = 0;
+
+    enum class MenuFadePhase { None, FadeOut, FadeIn };
+    MenuFadePhase menuFadePhase = MenuFadePhase::None;
+    double menuFadeClockMs = 0.0;
+    float menuFadeAlpha = 0.0f;
+    double MENU_PLAY_FADE_DURATION_MS = 450.0;
+    AppState menuFadeTarget = AppState::Menu;
+
+    enum class CountdownSource { MenuStart, ChallengeLevel };
+    bool menuPlayCountdownArmed = false;
+    bool gameplayCountdownActive = false;
+    double gameplayCountdownElapsed = 0.0;
+    int gameplayCountdownIndex = 0;
+    double GAMEPLAY_COUNTDOWN_STEP_MS = 400.0;
+    std::array<const char*, 4> GAMEPLAY_COUNTDOWN_LABELS = { "3", "2", "1", "START" };
+    CountdownSource gameplayCountdownSource = CountdownSource::MenuStart;
+    int countdownLevel = 0;
+    int countdownGoalAsteroids = 0;
+    bool countdownAdvancesChallenge = false;
+    bool challengeCountdownWaitingForSpace = false;
+    double gameplayBackgroundClockMs = 0.0;
+    std::string challengeStoryText;
+    int challengeStoryLevel = 0;
+    float challengeStoryAlpha = 0.0f;
+    double challengeStoryClockMs = 0.0;
+
+    // Challenge clear FX (celebratory board explosion before countdown)
+    bool challengeClearFxActive = false;
+    double challengeClearFxElapsedMs = 0.0;
+    double challengeClearFxDurationMs = 0.0;
+    int challengeClearFxNextLevel = 0;
+    std::vector<int> challengeClearFxOrder;
+    std::mt19937 challengeClearFxRng{std::random_device{}()};
+
+    std::unique_ptr<StateManager> stateMgr;
+    StateContext ctx{};
+    std::unique_ptr<LoadingState> loadingState;
+    std::unique_ptr<VideoState> videoState;
+    std::unique_ptr<MenuState> menuState;
+    std::unique_ptr<OptionsState> optionsState;
+    std::unique_ptr<LevelSelectorState> levelSelectorState;
+    std::unique_ptr<PlayingState> playingState;
+
+    // Startup fade-in overlay (used after intro video).
+    bool startupFadeActive = false;
+    float startupFadeAlpha = 0.0f; // 0..1 black overlay strength
+    double startupFadeClockMs = 0.0;
+    static constexpr double STARTUP_FADE_IN_MS = 650.0;
+
+    // Intro video path.
+    std::string introVideoPath = "assets/videos/spacetris_intro.mp4";
+
+    int init();
+    void runLoop();
+    void shutdown();
+};
+
+TetrisApp::TetrisApp()
+    : impl_(std::make_unique<Impl>())
+{
+}
+
+TetrisApp::~TetrisApp() = default;
+
+int TetrisApp::run()
+{
+    const int initRc = impl_->init();
+    if (initRc != 0) {
+        impl_->shutdown();
+        return initRc;
+    }
+
+    impl_->runLoop();
+    impl_->shutdown();
+    return 0;
+}
+
+int TetrisApp::Impl::init()
+{
+    // Initialize random seed for procedural effects
+    srand(static_cast<unsigned int>(SDL_GetTicks()));
+
+    // Load settings
+    Settings::instance().load();
+
+    // Sync shared variables with settings
+    musicEnabled = Settings::instance().isMusicEnabled();
+    playerName = Settings::instance().getPlayerName();
+    if (playerName.empty()) playerName = "Player";
+
+    // Apply sound settings to manager
+    SoundEffectManager::instance().setEnabled(Settings::instance().isSoundEnabled());
+
+    int sdlInitRes = SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO);
+    if (sdlInitRes < 0)
+    {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_Init failed: %s", SDL_GetError());
+        return 1;
+    }
+    int ttfInitRes = TTF_Init();
+    if (ttfInitRes < 0)
+    {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "TTF_Init failed");
+        SDL_Quit();
+        return 1;
+    }
+
+    SDL_WindowFlags windowFlags = SDL_WINDOW_RESIZABLE;
+    if (Settings::instance().isFullscreen()) {
+        windowFlags |= SDL_WINDOW_FULLSCREEN;
+    }
+
+    window = SDL_CreateWindow("SpaceTris (SDL3)", LOGICAL_W, LOGICAL_H, windowFlags);
+    if (!window)
+    {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_CreateWindow failed: %s", SDL_GetError());
+        TTF_Quit();
+        SDL_Quit();
+        return 1;
+    }
+    renderer = SDL_CreateRenderer(window, nullptr);
+    if (!renderer)
+    {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_CreateRenderer failed: %s", SDL_GetError());
+        SDL_DestroyWindow(window);
+        window = nullptr;
+        TTF_Quit();
+        SDL_Quit();
+        return 1;
+    }
+    SDL_SetRenderVSync(renderer, 1);
+
+    if (const char* basePathRaw = SDL_GetBasePath()) {
+        std::filesystem::path exeDir(basePathRaw);
+        AssetPath::setBasePath(exeDir.string());
+#if defined(__APPLE__)
+        // On macOS bundles launched from Finder start in /, so re-root relative paths.
+        std::error_code ec;
+        std::filesystem::current_path(exeDir, ec);
+        if (ec) {
+            SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION,
+                "Failed to set working directory to %s: %s",
+                exeDir.string().c_str(), ec.message().c_str());
+        }
+#endif
+    } else {
+        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION,
+            "SDL_GetBasePath() failed; asset lookups rely on current directory: %s",
+            SDL_GetError());
+    }
+
+    // Asset loader (creates SDL_Textures on the main thread)
+    assetLoader.init(renderer);
+    loadingManager = std::make_unique<LoadingManager>(&assetLoader);
+
+    // Legacy image loader (used only as a fallback when AssetLoader misses)
+    textureLoader = std::make_unique<TextureLoader>(
+        loadedTasks,
+        currentLoadingFile,
+        currentLoadingMutex,
+        assetLoadErrors,
+        assetLoadErrorsMutex);
+
+    // Load scores asynchronously but keep the worker alive until shutdown
+    scoreLoader = std::jthread([this]() {
+        scores.load();
+        scoresLoadComplete.store(true, std::memory_order_release);
+    });
+
+    starfield.init(200, LOGICAL_W, LOGICAL_H);
+    starfield3D.init(LOGICAL_W, LOGICAL_H, 200);
+    spaceWarp.init(LOGICAL_W, LOGICAL_H, 420);
+    spaceWarp.setFlightMode(warpFlightMode);
+    warpAutoPilotEnabled = true;
+    spaceWarp.setAutoPilotEnabled(true);
+
+    // Initialize line clearing effects
+    lineEffect.init(renderer);
+
+    game = std::make_unique<Game>(startLevelSelection);
+    game->setGravityGlobalMultiplier(Config::Gameplay::GRAVITY_SPEED_MULTIPLIER);
+    game->reset(startLevelSelection);
+
+    coopGame = std::make_unique<CoopGame>(startLevelSelection);
+
+    // Define voice line banks for gameplay callbacks
+    singleSounds = {"well_played", "smooth_clear", "great_move"};
+    doubleSounds = {"nice_combo", "you_fire", "keep_that_ryhtm"};
+    tripleSounds = {"impressive", "triple_strike"};
+    tetrisSounds = {"amazing", "you_re_unstoppable", "boom_tetris", "wonderful"};
+    suppressLineVoiceForLevelUp = false;
+
+    auto playVoiceCue = [this](int linesCleared) {
+        const std::vector<std::string>* bank = nullptr;
+        switch (linesCleared) {
+            case 1: bank = &singleSounds; break;
+            case 2: bank = &doubleSounds; break;
+            case 3: bank = &tripleSounds; break;
+            default:
+                if (linesCleared >= 4) {
+                    bank = &tetrisSounds;
+                }
+                break;
+        }
+        if (bank && !bank->empty()) {
+            SoundEffectManager::instance().playRandomSound(*bank, 1.0f);
+        }
+    };
+
+    game->setSoundCallback([this, playVoiceCue](int linesCleared) {
+        if (linesCleared <= 0) {
+            return;
+        }
+
+        SoundEffectManager::instance().playSound("clear_line", 1.0f);
+
+        if (!suppressLineVoiceForLevelUp) {
+            playVoiceCue(linesCleared);
+        }
+        suppressLineVoiceForLevelUp = false;
+    });
+
+    // Keep co-op line-clear SFX behavior identical to classic.
+    coopGame->setSoundCallback([this, playVoiceCue](int linesCleared) {
+        if (linesCleared <= 0) {
+            return;
+        }
+
+        SoundEffectManager::instance().playSound("clear_line", 1.0f);
+
+        if (!suppressLineVoiceForLevelUp) {
+            playVoiceCue(linesCleared);
+        }
+        suppressLineVoiceForLevelUp = false;
+    });
+
+    game->setLevelUpCallback([this](int /*newLevel*/) {
+        if (skipNextLevelUpJingle) {
+            skipNextLevelUpJingle = false;
+        } else {
+            SoundEffectManager::instance().playSound("new_level", 1.0f);
+            SoundEffectManager::instance().playSound("lets_go", 1.0f);
+        }
+        suppressLineVoiceForLevelUp = true;
+    });
+
+    // Mirror single-player level-up audio/visual behavior for Coop sessions
+    coopGame->setLevelUpCallback([this](int /*newLevel*/) {
+        if (skipNextLevelUpJingle) {
+            skipNextLevelUpJingle = false;
+        } else {
+            SoundEffectManager::instance().playSound("new_level", 1.0f);
+            SoundEffectManager::instance().playSound("lets_go", 1.0f);
+        }
+        suppressLineVoiceForLevelUp = true;
+    });
+
+    game->setAsteroidDestroyedCallback([](AsteroidType /*type*/) {
+        SoundEffectManager::instance().playSound("asteroid_destroy", 0.9f);
+    });
+
+    state = AppState::Loading;
+    loadingProgress = 0.0;
+    loadStart = SDL_GetTicks();
+    running = true;
+    isFullscreen = Settings::instance().isFullscreen();
+    leftHeld = false;
+    rightHeld = false;
+    p1LeftHeld = p1RightHeld = p2LeftHeld = p2RightHeld = false;
+    moveTimerMs = 0;
+    p1MoveTimerMs = 0.0;
+    p2MoveTimerMs = 0.0;
+    DAS = 170.0;
+    ARR = 40.0;
+    logicalVP = SDL_Rect{0, 0, LOGICAL_W, LOGICAL_H};
+    logicalScale = 1.f;
+    lastMs = SDL_GetPerformanceCounter();
+
+    menuFadePhase = MenuFadePhase::None;
+    menuFadeClockMs = 0.0;
+    menuFadeAlpha = 0.0f;
+    MENU_PLAY_FADE_DURATION_MS = 450.0;
+    menuFadeTarget = AppState::Menu;
+    menuPlayCountdownArmed = false;
+    gameplayCountdownActive = false;
+    gameplayCountdownElapsed = 0.0;
+    gameplayCountdownIndex = 0;
+    GAMEPLAY_COUNTDOWN_STEP_MS = 400.0;
+    GAMEPLAY_COUNTDOWN_LABELS = { "3", "2", "1", "START" };
+    gameplayBackgroundClockMs = 0.0;
+
+    // Instantiate state manager
+    stateMgr = std::make_unique<StateManager>(state);
+
+    // Prepare shared context for states
+    ctx = StateContext{};
+    ctx.stateManager = stateMgr.get();
+    ctx.game = game.get();
+    ctx.coopGame = coopGame.get();
+    ctx.scores = nullptr;
+    ctx.starfield = &starfield;
+    ctx.starfield3D = &starfield3D;
+    ctx.font = &font;
+    ctx.pixelFont = &pixelFont;
+    ctx.lineEffect = &lineEffect;
+    ctx.logoTex = logoTex;
+    ctx.logoSmallTex = logoSmallTex;
+    ctx.logoSmallW = logoSmallW;
+    ctx.logoSmallH = logoSmallH;
+    ctx.backgroundTex = nullptr;
+    ctx.asteroidsTex = asteroidsTex;
+    ctx.blocksTex = blocksTex;
+    ctx.scorePanelTex = scorePanelTex;
+    ctx.statisticsPanelTex = statisticsPanelTex;
+    ctx.nextPanelTex = nextPanelTex;
+    ctx.mainScreenTex = mainScreenTex;
+    ctx.mainScreenW = mainScreenW;
+    ctx.mainScreenH = mainScreenH;
+    ctx.musicEnabled = &musicEnabled;
+    ctx.coopVsAI = &coopVsAI;
+    ctx.startLevelSelection = &startLevelSelection;
+    ctx.hoveredButton = &hoveredButton;
+    ctx.showSettingsPopup = &showSettingsPopup;
+    ctx.showHelpOverlay = &showHelpOverlay;
+    ctx.showExitConfirmPopup = &showExitConfirmPopup;
+    ctx.exitPopupSelectedButton = &exitPopupSelectedButton;
+    ctx.gameplayCountdownActive = &gameplayCountdownActive;
+    ctx.menuPlayCountdownArmed = &menuPlayCountdownArmed;
+    ctx.skipNextLevelUpJingle = &skipNextLevelUpJingle;
+    ctx.challengeClearFxActive = &challengeClearFxActive;
+    ctx.challengeClearFxElapsedMs = &challengeClearFxElapsedMs;
+    ctx.challengeClearFxDurationMs = &challengeClearFxDurationMs;
+    ctx.challengeClearFxOrder = &challengeClearFxOrder;
+    ctx.challengeStoryText = &challengeStoryText;
+    ctx.challengeStoryLevel = &challengeStoryLevel;
+    ctx.challengeStoryAlpha = &challengeStoryAlpha;
+    ctx.playerName = &playerName;
+    ctx.fullscreenFlag = &isFullscreen;
+    ctx.applyFullscreen = [this](bool enable) {
+        SDL_SetWindowFullscreen(window, enable ? SDL_WINDOW_FULLSCREEN : 0);
+        isFullscreen = enable;
+    };
+    ctx.queryFullscreen = [this]() -> bool {
+        return (SDL_GetWindowFlags(window) & SDL_WINDOW_FULLSCREEN) != 0;
+    };
+    ctx.requestQuit = [this]() {
+        running = false;
+    };
+
+    auto beginStateFade = [this](AppState targetState, bool armGameplayCountdown) {
+        if (!ctx.stateManager) {
+            return;
+        }
+        if (state == targetState) {
+            return;
+        }
+        if (menuFadePhase != MenuFadePhase::None) {
+            return;
+        }
+
+        menuFadePhase = MenuFadePhase::FadeOut;
+        menuFadeClockMs = 0.0;
+        menuFadeAlpha = 0.0f;
+        menuFadeTarget = targetState;
+        menuPlayCountdownArmed = armGameplayCountdown;
+        gameplayCountdownActive = false;
+        gameplayCountdownIndex = 0;
+        gameplayCountdownElapsed = 0.0;
+
+        if (!armGameplayCountdown) {
+            if (game) {
+                game->setPaused(false);
+            }
+        }
+    };
+
+    auto startMenuPlayTransition = [this, beginStateFade]() {
+        if (!ctx.stateManager) {
+            return;
+        }
+        if (state != AppState::Menu) {
+            if (game && game->getMode() == GameMode::Cooperate && coopGame && coopVsAI) {
+                coopAI.reset();
+            }
+            state = AppState::Playing;
+            ctx.stateManager->setState(state);
+            return;
+        }
+
+        if (game && game->getMode() == GameMode::Cooperate && coopGame && coopVsAI) {
+            coopAI.reset();
+        }
+        beginStateFade(AppState::Playing, true);
+    };
+    ctx.startPlayTransition = startMenuPlayTransition;
+
+    auto requestStateFade = [this, startMenuPlayTransition, beginStateFade](AppState targetState) {
+        if (!ctx.stateManager) {
+            return;
+        }
+        if (targetState == AppState::Playing) {
+            startMenuPlayTransition();
+            return;
+        }
+        beginStateFade(targetState, false);
+    };
+    ctx.requestFadeTransition = requestStateFade;
+
+    ctx.startupFadeActive = &startupFadeActive;
+    ctx.startupFadeAlpha = &startupFadeAlpha;
+
+    loadingState = std::make_unique<LoadingState>(ctx);
+    videoState = std::make_unique<VideoState>(ctx);
+    menuState = std::make_unique<MenuState>(ctx);
+    optionsState = std::make_unique<OptionsState>(ctx);
+    levelSelectorState = std::make_unique<LevelSelectorState>(ctx);
+    playingState = std::make_unique<PlayingState>(ctx);
+
+    stateMgr->registerHandler(AppState::Loading, [this](const SDL_Event& e){ loadingState->handleEvent(e); });
+    stateMgr->registerOnEnter(AppState::Loading, [this](){ loadingState->onEnter(); loadingStarted.store(true); });
+    stateMgr->registerOnExit(AppState::Loading, [this](){ loadingState->onExit(); });
+
+    stateMgr->registerHandler(AppState::Video, [this](const SDL_Event& e){ if (videoState) videoState->handleEvent(e); });
+    stateMgr->registerOnEnter(AppState::Video, [this]() {
+        if (!videoState) return;
+        const bool ok = videoState->begin(renderer, introVideoPath);
+        if (!ok) {
+            SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "Intro video unavailable; skipping to Menu");
+            state = AppState::Menu;
+            stateMgr->setState(state);
+            return;
+        }
+        videoState->onEnter();
+    });
+    stateMgr->registerOnExit(AppState::Video, [this](){ if (videoState) videoState->onExit(); });
+
+    stateMgr->registerHandler(AppState::Menu, [this](const SDL_Event& e){ menuState->handleEvent(e); });
+    stateMgr->registerOnEnter(AppState::Menu, [this](){ menuState->onEnter(); });
+    stateMgr->registerOnExit(AppState::Menu, [this](){ menuState->onExit(); });
+
+    stateMgr->registerHandler(AppState::Options, [this](const SDL_Event& e){ optionsState->handleEvent(e); });
+    stateMgr->registerOnEnter(AppState::Options, [this](){ optionsState->onEnter(); });
+    stateMgr->registerOnExit(AppState::Options, [this](){ optionsState->onExit(); });
+
+    stateMgr->registerHandler(AppState::LevelSelector, [this](const SDL_Event& e){ levelSelectorState->handleEvent(e); });
+    stateMgr->registerOnEnter(AppState::LevelSelector, [this](){ levelSelectorState->onEnter(); });
+    stateMgr->registerOnExit(AppState::LevelSelector, [this](){ levelSelectorState->onExit(); });
+
+    stateMgr->registerHandler(AppState::Playing, [this](const SDL_Event& e){ playingState->handleEvent(e); });
+    stateMgr->registerOnEnter(AppState::Playing, [this](){ playingState->onEnter(); });
+    stateMgr->registerOnExit(AppState::Playing, [this](){ playingState->onExit(); });
+
+    loadingState->onEnter();
+    loadingStarted.store(true);
+
+    return 0;
+}
+
+void TetrisApp::Impl::runLoop()
+{
+    auto ensureScoresLoaded = [this]() {
+        if (scoreLoader.joinable()) {
+            scoreLoader.join();
+        }
+        if (!ctx.scores) {
+            ctx.scores = &scores;
+        }
+    };
+
+    auto startMenuPlayTransition = [this]() {
+        if (ctx.startPlayTransition) {
+            ctx.startPlayTransition();
+        }
+    };
+
+    auto requestStateFade = [this](AppState targetState) {
+        if (ctx.requestFadeTransition) {
+            ctx.requestFadeTransition(targetState);
+        }
+    };
+
+    auto captureChallengeStory = [this](int level) {
+        int lvl = std::clamp(level, 1, 100);
+        challengeStoryLevel = lvl;
+        challengeStoryText = GetLevelStoryText(lvl);
+        challengeStoryClockMs = 0.0;
+        challengeStoryAlpha = 0.0f;
+    };
+
+    auto startChallengeClearFx = [this](int nextLevel) {
+        challengeClearFxOrder.clear();
+        const auto& boardRef = game->boardRef();
+        const auto& asteroidRef = game->asteroidCells();
+        for (int idx = 0; idx < Game::COLS * Game::ROWS; ++idx) {
+            if (boardRef[idx] != 0 || asteroidRef[idx].has_value()) {
+                challengeClearFxOrder.push_back(idx);
+            }
+        }
+        if (challengeClearFxOrder.empty()) {
+            challengeClearFxOrder.reserve(Game::COLS * Game::ROWS);
+            for (int idx = 0; idx < Game::COLS * Game::ROWS; ++idx) {
+                challengeClearFxOrder.push_back(idx);
+            }
+        }
+        // Seed FX RNG deterministically from the game's challenge seed so animations
+        // are reproducible per-run and per-level. Fall back to a random seed if game absent.
+        if (game) {
+            challengeClearFxRng.seed(game->getChallengeSeedBase() + static_cast<uint32_t>(nextLevel));
+        } else {
+            challengeClearFxRng.seed(std::random_device{}());
+        }
+        std::shuffle(challengeClearFxOrder.begin(), challengeClearFxOrder.end(), challengeClearFxRng);
+
+        challengeClearFxElapsedMs = 0.0;
+        challengeClearFxDurationMs = std::clamp(800.0 + static_cast<double>(challengeClearFxOrder.size()) * 8.0, 900.0, 2600.0);
+        challengeClearFxNextLevel = nextLevel;
+        challengeClearFxActive = true;
+        gameplayCountdownActive = false;
+        gameplayCountdownElapsed = 0.0;
+        gameplayCountdownIndex = 0;
+        menuPlayCountdownArmed = false;
+        if (game) {
+            game->setPaused(true);
+        }
+        SoundEffectManager::instance().playSound("challenge_clear", 0.8f);
+    };
+
+    while (running)
+    {
+        if (!ctx.scores && scoresLoadComplete.load(std::memory_order_acquire)) {
+            ensureScoresLoaded();
+        }
+
+        int winW = 0, winH = 0;
+        SDL_GetWindowSize(window, &winW, &winH);
+
+        logicalScale = std::min(winW / (float)LOGICAL_W, winH / (float)LOGICAL_H);
+        if (logicalScale <= 0)
+            logicalScale = 1.f;
+
+        logicalVP.w = winW;
+        logicalVP.h = winH;
+        logicalVP.x = 0;
+        logicalVP.y = 0;
+
+        SDL_Event e;
+        while (SDL_PollEvent(&e))
+        {
+            if (e.type == SDL_EVENT_QUIT || e.type == SDL_EVENT_WINDOW_CLOSE_REQUESTED)
+                running = false;
+            else {
+                const bool isUserInputEvent =
+                    e.type == SDL_EVENT_KEY_DOWN ||
+                    e.type == SDL_EVENT_KEY_UP ||
+                    e.type == SDL_EVENT_TEXT_INPUT ||
+                    e.type == SDL_EVENT_MOUSE_BUTTON_DOWN ||
+                    e.type == SDL_EVENT_MOUSE_BUTTON_UP ||
+                    e.type == SDL_EVENT_MOUSE_MOTION;
+
+                if (!(showHelpOverlay && isUserInputEvent)) {
+                    stateMgr->handleEvent(e);
+                    state = stateMgr->getState();
+                }
+
+                if (e.type == SDL_EVENT_KEY_DOWN && !e.key.repeat) {
+                    if (e.key.scancode == SDL_SCANCODE_M)
+                    {
+                        Audio::instance().toggleMute();
+                        musicEnabled = !musicEnabled;
+                        Settings::instance().setMusicEnabled(musicEnabled);
+                    }
+                    if (e.key.scancode == SDL_SCANCODE_N)
+                    {
+                        Audio::instance().skipToNextTrack();
+                        if (!musicStarted && Audio::instance().getLoadedTrackCount() > 0) {
+                            musicStarted = true;
+                            musicEnabled = true;
+                            Settings::instance().setMusicEnabled(true);
+                        }
+                    }
+                    // K: Toggle sound effects (S is reserved for co-op movement)
+                    if (e.key.scancode == SDL_SCANCODE_K)
+                    {
+                        SoundEffectManager::instance().setEnabled(!SoundEffectManager::instance().isEnabled());
+                        Settings::instance().setSoundEnabled(SoundEffectManager::instance().isEnabled());
+                    }
+                    const bool helpToggleKey =
+                        (e.key.scancode == SDL_SCANCODE_F1 && state != AppState::Loading && state != AppState::Video && state != AppState::Menu);
+                    if (helpToggleKey)
+                    {
+                        showHelpOverlay = !showHelpOverlay;
+                        if (state == AppState::Playing) {
+                            if (showHelpOverlay) {
+                                if (!game->isPaused()) {
+                                    game->setPaused(true);
+                                    helpOverlayPausedGame = true;
+                                } else {
+                                    helpOverlayPausedGame = false;
+                                }
+                            } else if (helpOverlayPausedGame) {
+                                game->setPaused(false);
+                                helpOverlayPausedGame = false;
+                            }
+                        } else if (!showHelpOverlay) {
+                            helpOverlayPausedGame = false;
+                        }
+                    }
+                    if (e.key.scancode == SDL_SCANCODE_ESCAPE && showHelpOverlay) {
+                        showHelpOverlay = false;
+                        if (state == AppState::Playing && helpOverlayPausedGame) {
+                            game->setPaused(false);
+                        }
+                        helpOverlayPausedGame = false;
+                    }
+                    if (e.key.key == SDLK_F11 || (e.key.key == SDLK_RETURN && (e.key.mod & SDL_KMOD_ALT)))
+                    {
+                        isFullscreen = !isFullscreen;
+                        SDL_SetWindowFullscreen(window, isFullscreen ? SDL_WINDOW_FULLSCREEN : 0);
+                        Settings::instance().setFullscreen(isFullscreen);
+                    }
+                    if (e.key.scancode == SDL_SCANCODE_F5)
+                    {
+                        warpAutoPilotEnabled = false;
+                        warpFlightMode = SpaceWarpFlightMode::Forward;
+                        spaceWarp.setFlightMode(warpFlightMode);
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Space warp mode: forward");
+                    }
+                    if (e.key.scancode == SDL_SCANCODE_F6)
+                    {
+                        warpAutoPilotEnabled = false;
+                        warpFlightMode = SpaceWarpFlightMode::BankLeft;
+                        spaceWarp.setFlightMode(warpFlightMode);
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Space warp mode: bank left");
+                    }
+                    if (e.key.scancode == SDL_SCANCODE_F7)
+                    {
+                        warpAutoPilotEnabled = false;
+                        warpFlightMode = SpaceWarpFlightMode::BankRight;
+                        spaceWarp.setFlightMode(warpFlightMode);
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Space warp mode: bank right");
+                    }
+                    if (e.key.scancode == SDL_SCANCODE_F8)
+                    {
+                        warpAutoPilotEnabled = false;
+                        warpFlightMode = SpaceWarpFlightMode::Reverse;
+                        spaceWarp.setFlightMode(warpFlightMode);
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Space warp mode: reverse");
+                    }
+                    if (e.key.scancode == SDL_SCANCODE_F9)
+                    {
+                        warpAutoPilotEnabled = true;
+                        spaceWarp.setAutoPilotEnabled(true);
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Space warp autopilot engaged");
+                    }
+                }
+
+                if (!showHelpOverlay && state == AppState::GameOver && isNewHighScore && e.type == SDL_EVENT_TEXT_INPUT) {
+                    // Support single-player and coop two-name entry
+                    if (game && game->getMode() == GameMode::Cooperate && coopGame) {
+                        if (highScoreEntryIndex == 0) {
+                            if (playerName.length() < 12) playerName += e.text.text;
+                        } else {
+                            if (player2Name.length() < 12) player2Name += e.text.text;
+                        }
+                    } else {
+                        if (playerName.length() < 12) playerName += e.text.text;
+                    }
+                }
+
+                if (!showHelpOverlay && state == AppState::GameOver && e.type == SDL_EVENT_KEY_DOWN && !e.key.repeat) {
+                    if (isNewHighScore) {
+                        if (game && game->getMode() == GameMode::Cooperate && coopGame) {
+                            if (coopVsAI) {
+                                // One-name entry flow (CPU is LEFT, human enters RIGHT name)
+                                if (e.key.scancode == SDL_SCANCODE_BACKSPACE) {
+                                    if (!player2Name.empty()) player2Name.pop_back();
+                                } else if (e.key.scancode == SDL_SCANCODE_RETURN || e.key.scancode == SDL_SCANCODE_KP_ENTER) {
+                                    if (player2Name.empty()) player2Name = "P2";
+                                    std::string combined = std::string("CPU") + " & " + player2Name;
+                                    int leftScore = coopGame->score(CoopGame::PlayerSide::Left);
+                                    int rightScore = coopGame->score(CoopGame::PlayerSide::Right);
+                                    int combinedScore = leftScore + rightScore;
+                                    ensureScoresLoaded();
+                                    scores.submit(combinedScore, coopGame->lines(), coopGame->level(), coopGame->elapsed(), combined, "cooperate");
+                                    Settings::instance().setPlayerName(player2Name);
+                                    isNewHighScore = false;
+                                    SDL_StopTextInput(window);
+                                }
+                            } else {
+                                // Two-name entry flow
+                                if (e.key.scancode == SDL_SCANCODE_BACKSPACE) {
+                                    if (highScoreEntryIndex == 0 && !playerName.empty()) playerName.pop_back();
+                                    else if (highScoreEntryIndex == 1 && !player2Name.empty()) player2Name.pop_back();
+                                } else if (e.key.scancode == SDL_SCANCODE_RETURN || e.key.scancode == SDL_SCANCODE_KP_ENTER) {
+                                    if (highScoreEntryIndex == 0) {
+                                        if (playerName.empty()) playerName = "P1";
+                                        highScoreEntryIndex = 1; // move to second name
+                                    } else {
+                                        if (player2Name.empty()) player2Name = "P2";
+                                        // Submit combined name
+                                        std::string combined = playerName + " & " + player2Name;
+                                        int leftScore = coopGame->score(CoopGame::PlayerSide::Left);
+                                        int rightScore = coopGame->score(CoopGame::PlayerSide::Right);
+                                        int combinedScore = leftScore + rightScore;
+                                        ensureScoresLoaded();
+                                        scores.submit(combinedScore, coopGame->lines(), coopGame->level(), coopGame->elapsed(), combined, "cooperate");
+                                        Settings::instance().setPlayerName(playerName);
+                                        isNewHighScore = false;
+                                        SDL_StopTextInput(window);
+                                    }
+                                }
+                            }
+                        } else {
+                            if (e.key.scancode == SDL_SCANCODE_BACKSPACE && !playerName.empty()) {
+                                playerName.pop_back();
+                            } else if (e.key.scancode == SDL_SCANCODE_RETURN || e.key.scancode == SDL_SCANCODE_KP_ENTER) {
+                                if (playerName.empty()) playerName = "PLAYER";
+                                ensureScoresLoaded();
+                                std::string gt = (game->getMode() == GameMode::Challenge) ? "challenge" : "classic";
+                                scores.submit(game->score(), game->lines(), game->level(), game->elapsed(), playerName, gt);
+                                Settings::instance().setPlayerName(playerName);
+                                isNewHighScore = false;
+                                SDL_StopTextInput(window);
+                            }
+                        }
+                    } else {
+                        if (e.key.scancode == SDL_SCANCODE_RETURN || e.key.scancode == SDL_SCANCODE_KP_ENTER || e.key.scancode == SDL_SCANCODE_SPACE) {
+                            if (game->getMode() == GameMode::Challenge) {
+                                game->startChallengeRun(1);
+                                } else if (game->getMode() == GameMode::Cooperate) {
+                                    game->setMode(GameMode::Cooperate);
+                                    game->reset(startLevelSelection);
+                            } else {
+                                game->setMode(GameMode::Endless);
+                                game->reset(startLevelSelection);
+                            }
+                            state = AppState::Playing;
+                            stateMgr->setState(state);
+                        } else if (e.key.scancode == SDL_SCANCODE_ESCAPE) {
+                            state = AppState::Menu;
+                            stateMgr->setState(state);
+                        }
+                    }
+                }
+
+                if (!showHelpOverlay && e.type == SDL_EVENT_MOUSE_BUTTON_DOWN)
+                {
+                    float mx = (float)e.button.x, my = (float)e.button.y;
+                    if (mx >= logicalVP.x && my >= logicalVP.y && mx <= logicalVP.x + logicalVP.w && my <= logicalVP.y + logicalVP.h)
+                    {
+                        float lx = (mx - logicalVP.x) / logicalScale, ly = (my - logicalVP.y) / logicalScale;
+                        if (state == AppState::Menu)
+                        {
+                            if (showSettingsPopup) {
+                                showSettingsPopup = false;
+                            } else {
+                                ui::MenuLayoutParams params{ LOGICAL_W, LOGICAL_H, winW, winH, logicalScale };
+
+                                auto menuInput = ui::handleBottomMenuInput(params, e, lx, ly, hoveredButton, true);
+                                hoveredButton = menuInput.hoveredIndex;
+
+                                if (menuInput.activated) {
+                                    switch (*menuInput.activated) {
+                                        case ui::BottomMenuItem::Play:
+                                            if (game) game->setMode(GameMode::Endless);
+                                            startMenuPlayTransition();
+                                            break;
+                                        case ui::BottomMenuItem::Cooperate:
+                                            if (menuState) {
+                                                menuState->showCoopSetupPanel(true);
+                                            }
+                                            break;
+                                        case ui::BottomMenuItem::Challenge:
+                                            if (game) {
+                                                game->setMode(GameMode::Challenge);
+                                                // Suppress the initial level-up jingle when starting Challenge from menu
+                                                skipNextLevelUpJingle = true;
+                                                game->startChallengeRun(1);
+                                            }
+                                            startMenuPlayTransition();
+                                            break;
+                                        case ui::BottomMenuItem::Level:
+                                            requestStateFade(AppState::LevelSelector);
+                                            break;
+                                        case ui::BottomMenuItem::Options:
+                                            requestStateFade(AppState::Options);
+                                            break;
+                                        case ui::BottomMenuItem::Help:
+                                            if (menuState) menuState->showHelpPanel(true);
+                                            break;
+                                        case ui::BottomMenuItem::About:
+                                            if (menuState) menuState->showAboutPanel(true);
+                                            break;
+                                        case ui::BottomMenuItem::Exit:
+                                            showExitConfirmPopup = true;
+                                            exitPopupSelectedButton = 1;
+                                            break;
+                                    }
+                                }
+
+                                SDL_FRect settingsBtn{SETTINGS_BTN_X, SETTINGS_BTN_Y, SETTINGS_BTN_W, SETTINGS_BTN_H};
+                                if (lx >= settingsBtn.x && lx <= settingsBtn.x + settingsBtn.w && ly >= settingsBtn.y && ly <= settingsBtn.y + settingsBtn.h)
+                                {
+                                    showSettingsPopup = true;
+                                }
+                            }
+                        }
+                        else if (state == AppState::LevelSelect)
+                            startLevelSelection = (startLevelSelection + 1) % 20;
+                        else if (state == AppState::GameOver) {
+                            state = AppState::Menu;
+                            stateMgr->setState(state);
+                        }
+                        else if (state == AppState::Playing && showExitConfirmPopup) {
+                            float lx2 = (mx - logicalVP.x) / logicalScale;
+                            float ly2 = (my - logicalVP.y) / logicalScale;
+                            float contentW = LOGICAL_W * logicalScale;
+                            float contentH = LOGICAL_H * logicalScale;
+                            float contentOffsetX = (winW - contentW) * 0.5f / logicalScale;
+                            float contentOffsetY = (winH - contentH) * 0.5f / logicalScale;
+                            float localX = lx2 - contentOffsetX;
+                            float localY = ly2 - contentOffsetY;
+
+                            float popupW = 400, popupH = 200;
+                            float popupX = (LOGICAL_W - popupW) / 2.0f;
+                            float popupY = (LOGICAL_H - popupH) / 2.0f;
+                            float btnW = 120.0f, btnH = 40.0f;
+                            float yesX = popupX + popupW * 0.25f - btnW / 2.0f;
+                            float noX = popupX + popupW * 0.75f - btnW / 2.0f;
+                            float btnY = popupY + popupH - btnH - 20.0f;
+
+                            if (localX >= popupX && localX <= popupX + popupW && localY >= popupY && localY <= popupY + popupH) {
+                                if (localX >= yesX && localX <= yesX + btnW && localY >= btnY && localY <= btnY + btnH) {
+                                    showExitConfirmPopup = false;
+                                    game->reset(startLevelSelection);
+                                    state = AppState::Menu;
+                                    stateMgr->setState(state);
+                                } else if (localX >= noX && localX <= noX + btnW && localY >= btnY && localY <= btnY + btnH) {
+                                    showExitConfirmPopup = false;
+                                    game->setPaused(false);
+                                }
+                            } else {
+                                showExitConfirmPopup = false;
+                                game->setPaused(false);
+                            }
+                        }
+                        else if (state == AppState::Menu && showExitConfirmPopup) {
+                            float contentW = LOGICAL_W * logicalScale;
+                            float contentH = LOGICAL_H * logicalScale;
+                            float contentOffsetX = (winW - contentW) * 0.5f / logicalScale;
+                            float contentOffsetY = (winH - contentH) * 0.5f / logicalScale;
+                            float popupW = 420.0f;
+                            float popupH = 230.0f;
+                            float popupX = (LOGICAL_W - popupW) * 0.5f + contentOffsetX;
+                            float popupY = (LOGICAL_H - popupH) * 0.5f + contentOffsetY;
+                            float btnW = 140.0f;
+                            float btnH = 50.0f;
+                            float yesX = popupX + popupW * 0.3f - btnW / 2.0f;
+                            float noX = popupX + popupW * 0.7f - btnW / 2.0f;
+                            float btnY = popupY + popupH - btnH - 30.0f;
+                            bool insidePopup = lx >= popupX && lx <= popupX + popupW && ly >= popupY && ly <= popupY + popupH;
+                            if (insidePopup) {
+                                if (lx >= yesX && lx <= yesX + btnW && ly >= btnY && ly <= btnY + btnH) {
+                                    showExitConfirmPopup = false;
+                                    running = false;
+                                } else if (lx >= noX && lx <= noX + btnW && ly >= btnY && ly <= btnY + btnH) {
+                                    showExitConfirmPopup = false;
+                                }
+                            } else {
+                                showExitConfirmPopup = false;
+                            }
+                        }
+                    }
+                }
+                else if (!showHelpOverlay && e.type == SDL_EVENT_MOUSE_MOTION)
+                {
+                    float mx = (float)e.motion.x, my = (float)e.motion.y;
+                    if (mx >= logicalVP.x && my >= logicalVP.y && mx <= logicalVP.x + logicalVP.w && my <= logicalVP.y + logicalVP.h)
+                    {
+                        float lx = (mx - logicalVP.x) / logicalScale, ly = (my - logicalVP.y) / logicalScale;
+                        if (state == AppState::Menu && !showSettingsPopup)
+                        {
+                            ui::MenuLayoutParams params{ LOGICAL_W, LOGICAL_H, winW, winH, logicalScale };
+                            auto menuInput = ui::handleBottomMenuInput(params, e, lx, ly, hoveredButton, true);
+                            hoveredButton = menuInput.hoveredIndex;
+                        }
+                    }
+                }
+                else if (e.type == SDL_EVENT_KEY_DOWN && !e.key.repeat) {
+                    if (gameplayCountdownActive && gameplayCountdownSource == CountdownSource::ChallengeLevel && challengeCountdownWaitingForSpace) {
+                        if (e.key.scancode == SDL_SCANCODE_SPACE) {
+                            challengeCountdownWaitingForSpace = false;
+                            gameplayCountdownElapsed = 0.0;
+                            gameplayCountdownIndex = 0;
+                        } else if (e.key.scancode == SDL_SCANCODE_ESCAPE) {
+                            // Show quit popup, keep game paused, cancel countdown
+                            if (!showExitConfirmPopup) {
+                                showExitConfirmPopup = true;
+                                exitPopupSelectedButton = 1; // default to NO
+                            }
+                            gameplayCountdownActive = false;
+                            menuPlayCountdownArmed = false;
+                            gameplayCountdownElapsed = 0.0;
+                            gameplayCountdownIndex = 0;
+                            countdownAdvancesChallenge = false;
+                            challengeCountdownWaitingForSpace = false;
+                            if (game) game->setPaused(true);
+                        }
+                    }
+                }
+            }
+        }
+
+        // State transitions can be triggered from render/update (e.g. menu network handshake).
+        // Keep our cached `state` in sync every frame, not only when events occur.
+        state = stateMgr->getState();
+
+        Uint64 now = SDL_GetPerformanceCounter();
+        double frameMs = double(now - lastMs) * 1000.0 / double(SDL_GetPerformanceFrequency());
+        lastMs = now;
+        if (frameMs > 100.0) frameMs = 100.0;
+        gameplayBackgroundClockMs += frameMs;
+
+        if (startupFadeActive) {
+            if (startupFadeClockMs <= 0.0) {
+                startupFadeClockMs = STARTUP_FADE_IN_MS;
+                startupFadeAlpha = 1.0f;
+            }
+            startupFadeClockMs -= frameMs;
+            if (startupFadeClockMs <= 0.0) {
+                startupFadeClockMs = 0.0;
+                startupFadeAlpha = 0.0f;
+                startupFadeActive = false;
+            } else {
+                startupFadeAlpha = float(std::clamp(startupFadeClockMs / STARTUP_FADE_IN_MS, 0.0, 1.0));
+            }
+        }
+
+        auto clearChallengeStory = [this]() {
+            challengeStoryText.clear();
+            challengeStoryLevel = 0;
+            challengeStoryAlpha = 0.0f;
+            challengeStoryClockMs = 0.0;
+        };
+
+        // Update challenge story fade/timeout; during countdown wait we keep it fully visible
+        if (state == AppState::Playing && game && game->getMode() == GameMode::Challenge && !challengeStoryText.empty()) {
+            if (gameplayCountdownActive && gameplayCountdownSource == CountdownSource::ChallengeLevel && challengeCountdownWaitingForSpace) {
+                // Locked-visible while waiting
+                challengeStoryAlpha = 1.0f;
+            } else {
+                const double fadeInMs = 320.0;
+                const double holdMs = 3200.0;
+                const double fadeOutMs = 900.0;
+                const double totalMs = fadeInMs + holdMs + fadeOutMs;
+                challengeStoryClockMs += frameMs;
+                if (challengeStoryClockMs >= totalMs) {
+                    clearChallengeStory();
+                } else {
+                    double a = 1.0;
+                    if (challengeStoryClockMs < fadeInMs) {
+                        a = challengeStoryClockMs / fadeInMs;
+                    } else if (challengeStoryClockMs > fadeInMs + holdMs) {
+                        double t = challengeStoryClockMs - (fadeInMs + holdMs);
+                        a = std::max(0.0, 1.0 - t / fadeOutMs);
+                    }
+                    challengeStoryAlpha = static_cast<float>(std::clamp(a, 0.0, 1.0));
+                }
+            }
+        } else {
+            clearChallengeStory();
+        }
+
+        if (challengeClearFxActive) {
+            challengeClearFxElapsedMs += frameMs;
+            if (challengeClearFxElapsedMs >= challengeClearFxDurationMs) {
+                challengeClearFxElapsedMs = challengeClearFxDurationMs;
+                challengeClearFxActive = false;
+                if (challengeClearFxNextLevel > 0) {
+                    // Advance to the next challenge level immediately so the countdown shows the new board/asteroids
+                    if (game) {
+                        game->beginNextChallengeLevel();
+                        game->setPaused(true);
+                    }
+                    gameplayCountdownSource = CountdownSource::ChallengeLevel;
+                    countdownLevel = challengeClearFxNextLevel;
+                    countdownGoalAsteroids = challengeClearFxNextLevel;
+                    captureChallengeStory(countdownLevel);
+                    countdownAdvancesChallenge = false; // already advanced
+                    gameplayCountdownActive = true;
+                    challengeCountdownWaitingForSpace = true;
+                    menuPlayCountdownArmed = false;
+                    gameplayCountdownElapsed = 0.0;
+                    gameplayCountdownIndex = 0;
+                    SoundEffectManager::instance().playSound("new_level", 1.0f);
+                    skipNextLevelUpJingle = true;
+                }
+                challengeClearFxNextLevel = 0;
+            }
+        }
+
+        const bool *ks = SDL_GetKeyboardState(nullptr);
+        bool left = state == AppState::Playing && ks[SDL_SCANCODE_LEFT];
+        bool right = state == AppState::Playing && ks[SDL_SCANCODE_RIGHT];
+        bool down = state == AppState::Playing && ks[SDL_SCANCODE_DOWN];
+
+        if (state == AppState::Playing)
+            game->setSoftDropping(down && !game->isPaused());
+        else
+            game->setSoftDropping(false);
+
+        int moveDir = 0;
+        if (left && !right)
+            moveDir = -1;
+        else if (right && !left)
+            moveDir = +1;
+
+        if (moveDir != 0 && !game->isPaused())
+        {
+            if ((moveDir == -1 && leftHeld == false) || (moveDir == +1 && rightHeld == false))
+            {
+                game->move(moveDir);
+                moveTimerMs = DAS;
+            }
+            else
+            {
+                moveTimerMs -= frameMs;
+                if (moveTimerMs <= 0)
+                {
+                    game->move(moveDir);
+                    moveTimerMs += ARR;
+                }
+            }
+        }
+        else
+            moveTimerMs = 0;
+        leftHeld = left;
+        rightHeld = right;
+        if (down && !game->isPaused())
+            game->softDropBoost(frameMs);
+
+        if (musicLoadingStarted && !musicLoaded) {
+            currentTrackLoading = Audio::instance().getLoadedTrackCount();
+            if (Audio::instance().isLoadingComplete() || (totalTracks > 0 && currentTrackLoading >= totalTracks)) {
+                Audio::instance().shuffle();
+                musicLoaded = true;
+            }
+        }
+
+        if (state == AppState::Playing)
+        {
+            const bool coopActive = game && game->getMode() == GameMode::Cooperate && coopGame;
+
+            if (coopActive) {
+                // Coop DAS/ARR handling (per-side)
+                const bool* ks = SDL_GetKeyboardState(nullptr);
+
+                auto handleSide = [&](CoopGame::PlayerSide side,
+                                      bool leftHeldPrev,
+                                      bool rightHeldPrev,
+                                      double& timer,
+                                      SDL_Scancode leftKey,
+                                      SDL_Scancode rightKey,
+                                      SDL_Scancode downKey) {
+                    bool left = ks[leftKey];
+                    bool right = ks[rightKey];
+                    bool down = ks[downKey];
+
+                    coopGame->setSoftDropping(side, down);
+
+                    int moveDir = 0;
+                    if (left && !right) moveDir = -1;
+                    else if (right && !left) moveDir = +1;
+
+                    if (moveDir != 0) {
+                        if ((moveDir == -1 && !leftHeldPrev) || (moveDir == +1 && !rightHeldPrev)) {
+                            coopGame->move(side, moveDir);
+                            timer = DAS;
+                        } else {
+                            timer -= frameMs;
+                            if (timer <= 0) {
+                                coopGame->move(side, moveDir);
+                                timer += ARR;
+                            }
+                        }
+                    } else {
+                        timer = 0.0;
+                    }
+                };
+
+                if (game->isPaused()) {
+                    // While paused, suppress all continuous input changes so pieces don't drift.
+                    if (ctx.coopNetEnabled && ctx.coopNetSession) {
+                        ctx.coopNetSession->poll(0);
+                        ctx.coopNetStalled = false;
+                    }
+                    coopGame->setSoftDropping(CoopGame::PlayerSide::Left, false);
+                    coopGame->setSoftDropping(CoopGame::PlayerSide::Right, false);
+                    p1MoveTimerMs = 0.0;
+                    p2MoveTimerMs = 0.0;
+                    p1LeftHeld = false;
+                    p1RightHeld = false;
+                    p2LeftHeld = false;
+                    p2RightHeld = false;
+                } else {
+                    const bool coopNetActive = ctx.coopNetEnabled && ctx.coopNetSession;
+
+                    // If we just entered network co-op, reset per-session fixed-tick bookkeeping.
+                    if (coopNetActive && coopNetCachedTick != 0xFFFFFFFFu && ctx.coopNetTick == 0u) {
+                        coopNetAccMs = 0.0;
+                        coopNetCachedTick = 0xFFFFFFFFu;
+                        coopNetCachedButtons = 0;
+                        coopNetLastHashSentTick = 0xFFFFFFFFu;
+                        ctx.coopNetStalled = false;
+                    }
+
+                    // Define canonical key mappings for left and right players
+                    const SDL_Scancode leftLeftKey = SDL_SCANCODE_A;
+                    const SDL_Scancode leftRightKey = SDL_SCANCODE_D;
+                    const SDL_Scancode leftDownKey = SDL_SCANCODE_S;
+
+                    const SDL_Scancode rightLeftKey = SDL_SCANCODE_LEFT;
+                    const SDL_Scancode rightRightKey = SDL_SCANCODE_RIGHT;
+                    const SDL_Scancode rightDownKey = SDL_SCANCODE_DOWN;
+
+                    if (coopNetActive) {
+                        // Network co-op: fixed tick lockstep.
+                        // Use a fixed dt so both peers simulate identically.
+                        static constexpr double FIXED_DT_MS = 1000.0 / 60.0;
+                        static constexpr uint32_t HASH_INTERVAL_TICKS = 60; // ~1s
+
+                        ctx.coopNetSession->poll(0);
+
+                        // If the connection drops during gameplay, abort back to menu.
+                        if (ctx.coopNetSession->state() == NetSession::ConnState::Disconnected ||
+                            ctx.coopNetSession->state() == NetSession::ConnState::Error) {
+                            const std::string reason = (ctx.coopNetSession->state() == NetSession::ConnState::Error && !ctx.coopNetSession->lastError().empty())
+                                                           ? (std::string("NET ERROR: ") + ctx.coopNetSession->lastError())
+                                                           : std::string("NET DISCONNECTED");
+                            SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "[NET COOP] %s", reason.c_str());
+
+                            ctx.coopNetUiStatusText = reason;
+                            ctx.coopNetUiStatusRemainingMs = 6000.0;
+                            ctx.coopNetEnabled = false;
+                            ctx.coopNetStalled = false;
+                            ctx.coopNetDesyncDetected = false;
+                            ctx.coopNetTick = 0;
+                            ctx.coopNetPendingButtons = 0;
+                            if (ctx.coopNetSession) {
+                                ctx.coopNetSession->shutdown();
+                                ctx.coopNetSession.reset();
+                            }
+
+                            // Ensure we don't remain paused due to a previous net stall/desync.
+                            if (game) {
+                                game->setPaused(false);
+                            }
+                            state = AppState::Menu;
+                            stateMgr->setState(state);
+                            continue;
+                        }
+
+                        coopNetAccMs = std::min(coopNetAccMs + frameMs, FIXED_DT_MS * 8.0);
+
+                        auto buildLocalButtons = [&]() -> uint8_t {
+                            uint8_t b = 0;
+                            if (ctx.coopNetLocalIsLeft) {
+                                if (ks[leftLeftKey]) b |= coopnet::MoveLeft;
+                                if (ks[leftRightKey]) b |= coopnet::MoveRight;
+                                if (ks[leftDownKey]) b |= coopnet::SoftDrop;
+                            } else {
+                                if (ks[rightLeftKey]) b |= coopnet::MoveLeft;
+                                if (ks[rightRightKey]) b |= coopnet::MoveRight;
+                                if (ks[rightDownKey]) b |= coopnet::SoftDrop;
+                            }
+                            b |= ctx.coopNetPendingButtons;
+                            ctx.coopNetPendingButtons = 0;
+                            return b;
+                        };
+
+                        auto applyButtonsForSide = [&](CoopGame::PlayerSide side,
+                                                       uint8_t buttons,
+                                                       bool& leftHeldPrev,
+                                                       bool& rightHeldPrev,
+                                                       double& timer) {
+                            const bool leftHeldNow = coopnet::has(buttons, coopnet::MoveLeft);
+                            const bool rightHeldNow = coopnet::has(buttons, coopnet::MoveRight);
+                            const bool downHeldNow = coopnet::has(buttons, coopnet::SoftDrop);
+
+                            coopGame->setSoftDropping(side, downHeldNow);
+
+                            int moveDir = 0;
+                            if (leftHeldNow && !rightHeldNow) moveDir = -1;
+                            else if (rightHeldNow && !leftHeldNow) moveDir = +1;
+
+                            if (moveDir != 0) {
+                                if ((moveDir == -1 && !leftHeldPrev) || (moveDir == +1 && !rightHeldPrev)) {
+                                    coopGame->move(side, moveDir);
+                                    timer = DAS;
+                                } else {
+                                    timer -= FIXED_DT_MS;
+                                    if (timer <= 0.0) {
+                                        coopGame->move(side, moveDir);
+                                        timer += ARR;
+                                    }
+                                }
+                            } else {
+                                timer = 0.0;
+                            }
+
+                            if (coopnet::has(buttons, coopnet::RotCW)) {
+                                coopGame->rotate(side, +1);
+                            }
+                            if (coopnet::has(buttons, coopnet::RotCCW)) {
+                                coopGame->rotate(side, -1);
+                            }
+                            if (coopnet::has(buttons, coopnet::HardDrop)) {
+                                SoundEffectManager::instance().playSound("hard_drop", 0.7f);
+                                coopGame->hardDrop(side);
+                            }
+                            if (coopnet::has(buttons, coopnet::Hold)) {
+                                coopGame->holdCurrent(side);
+                            }
+
+                            leftHeldPrev = leftHeldNow;
+                            rightHeldPrev = rightHeldNow;
+                        };
+
+                        const char* roleStr = ctx.coopNetIsHost ? "HOST" : "CLIENT";
+
+                        int safetySteps = 0;
+                        bool advancedTick = false;
+                        ctx.coopNetStalled = false;
+                        while (coopNetAccMs >= FIXED_DT_MS && safetySteps++ < 8) {
+                            const uint32_t tick = ctx.coopNetTick;
+
+                            if (coopNetCachedTick != tick) {
+                                coopNetCachedTick = tick;
+                                coopNetCachedButtons = buildLocalButtons();
+                                if (!ctx.coopNetSession->sendLocalInput(tick, coopNetCachedButtons)) {
+                                    SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION,
+                                                "[NET COOP][%s] sendLocalInput failed (tick=%u)",
+                                                roleStr,
+                                                tick);
+                                }
+                            }
+
+                            auto remoteButtonsOpt = ctx.coopNetSession->getRemoteButtons(tick);
+                            if (!remoteButtonsOpt.has_value()) {
+                                if (!ctx.coopNetStalled) {
+                                    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION,
+                                                "[NET COOP][%s] STALL begin waitingForTick=%u",
+                                                roleStr,
+                                                tick);
+                                }
+                                ctx.coopNetStalled = true;
+                                break; // lockstep stall
+                            }
+
+                            const uint8_t remoteButtons = remoteButtonsOpt.value();
+                            const bool localIsLeft = ctx.coopNetLocalIsLeft;
+
+                            if (localIsLeft) {
+                                applyButtonsForSide(CoopGame::PlayerSide::Left, coopNetCachedButtons, p1LeftHeld, p1RightHeld, p1MoveTimerMs);
+                                applyButtonsForSide(CoopGame::PlayerSide::Right, remoteButtons, p2LeftHeld, p2RightHeld, p2MoveTimerMs);
+                            } else {
+                                applyButtonsForSide(CoopGame::PlayerSide::Right, coopNetCachedButtons, p2LeftHeld, p2RightHeld, p2MoveTimerMs);
+                                applyButtonsForSide(CoopGame::PlayerSide::Left, remoteButtons, p1LeftHeld, p1RightHeld, p1MoveTimerMs);
+                            }
+
+                            coopGame->tickGravity(FIXED_DT_MS);
+                            coopGame->updateVisualEffects(FIXED_DT_MS);
+
+                            if ((tick % HASH_INTERVAL_TICKS) == 0 && coopNetLastHashSentTick != tick) {
+                                coopNetLastHashSentTick = tick;
+                                const uint64_t hash = coopGame->computeStateHash();
+                                if (!ctx.coopNetSession->sendStateHash(tick, hash)) {
+                                    SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION,
+                                                "[NET COOP][%s] sendStateHash failed (tick=%u hash=0x%016llX)",
+                                                roleStr,
+                                                tick,
+                                                (unsigned long long)hash);
+                                }
+                                auto rh = ctx.coopNetSession->takeRemoteHash(tick);
+                                if (rh.has_value() && rh.value() != hash) {
+                                    ctx.coopNetDesyncDetected = true;
+                                    ctx.coopNetUiStatusText = "NET DESYNC";
+                                    ctx.coopNetUiStatusRemainingMs = 8000.0;
+                                    SDL_LogError(SDL_LOG_CATEGORY_APPLICATION,
+                                                 "[NET COOP][%s] DESYNC detected at tick=%u local=0x%016llX remote=0x%016llX",
+                                                 roleStr,
+                                                 tick,
+                                                 (unsigned long long)hash,
+                                                 (unsigned long long)rh.value());
+                                    game->setPaused(true);
+                                }
+                            }
+
+                            ctx.coopNetTick++;
+                            advancedTick = true;
+                            coopNetAccMs -= FIXED_DT_MS;
+                        }
+
+                        if (advancedTick) {
+                            if (ctx.coopNetStalled) {
+                                SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION,
+                                            "[NET COOP][%s] STALL end atTick=%u",
+                                            roleStr,
+                                            ctx.coopNetTick);
+                            }
+                            ctx.coopNetStalled = false;
+                        }
+                    } else if (!coopVsAI) {
+                        // Standard two-player: left uses WASD, right uses arrow keys
+                        handleSide(CoopGame::PlayerSide::Left, p1LeftHeld, p1RightHeld, p1MoveTimerMs, leftLeftKey, leftRightKey, leftDownKey);
+                        handleSide(CoopGame::PlayerSide::Right, p2LeftHeld, p2RightHeld, p2MoveTimerMs, rightLeftKey, rightRightKey, rightDownKey);
+
+                        p1LeftHeld = ks[leftLeftKey];
+                        p1RightHeld = ks[leftRightKey];
+                        p2LeftHeld = ks[rightLeftKey];
+                        p2RightHeld = ks[rightRightKey];
+                    } else {
+                        // Coop vs CPU: AI controls LEFT, human controls RIGHT (arrow keys).
+                        // Handle continuous input for the human on the right side.
+                        handleSide(CoopGame::PlayerSide::Right, p2LeftHeld, p2RightHeld, p2MoveTimerMs, rightLeftKey, rightRightKey, rightDownKey);
+
+                        // Mirror the human soft-drop to the AI-controlled left board so both fall together.
+                        const bool pRightSoftDrop = ks[rightDownKey];
+                        coopGame->setSoftDropping(CoopGame::PlayerSide::Left, pRightSoftDrop);
+
+                        // Reset left continuous timers/held flags (AI handles movement)
+                        p1MoveTimerMs = 0.0;
+                        p1LeftHeld = false;
+                        p1RightHeld = false;
+
+                        // Update AI for the left side
+                        coopAI.update(*coopGame, CoopGame::PlayerSide::Left, frameMs);
+                        // Update human-held flags for right-side controls so DAS/ARR state is tracked
+                        p2LeftHeld = ks[rightLeftKey];
+                        p2RightHeld = ks[rightRightKey];
+                    }
+
+                    if (!coopNetActive) {
+                        coopGame->tickGravity(frameMs);
+                        coopGame->updateVisualEffects(frameMs);
+                    }
+                }
+
+                if (coopGame->isGameOver()) {
+                    // Compute combined coop stats for Game Over
+                    int leftScore = coopGame->score(CoopGame::PlayerSide::Left);
+                    int rightScore = coopGame->score(CoopGame::PlayerSide::Right);
+                    int combinedScore = leftScore + rightScore;
+                    if (combinedScore > 0) {
+                        isNewHighScore = true;
+                        if (coopVsAI) {
+                            // AI is left, prompt human (right) for name
+                            playerName = "CPU";
+                            player2Name.clear();
+                            highScoreEntryIndex = 1; // enter P2 (human)
+                        } else {
+                            playerName.clear();
+                            player2Name.clear();
+                            highScoreEntryIndex = 0;
+                        }
+                        SDL_StartTextInput(window);
+                    } else {
+                        isNewHighScore = false;
+                        ensureScoresLoaded();
+                        // When AI is present, label should indicate CPU left and human right
+                        scores.submit(combinedScore, coopGame->lines(), coopGame->level(), coopGame->elapsed(), coopVsAI ? "CPU & P2" : "P1 & P2", "cooperate");
+                    }
+                    state = AppState::GameOver;
+                    stateMgr->setState(state);
+
+                    if (ctx.coopNetSession) {
+                        ctx.coopNetSession->shutdown();
+                        ctx.coopNetSession.reset();
+                    }
+                    ctx.coopNetEnabled = false;
+                }
+
+            } else {
+                if (!game->isPaused()) {
+                    game->tickGravity(frameMs);
+                    game->updateElapsedTime();
+
+                    if (lineEffect.isActive()) {
+                        if (lineEffect.update(frameMs / 1000.0f)) {
+                            game->clearCompletedLines();
+                        }
+                    }
+                }
+                if (game->isGameOver())
+                {
+                    if (game->score() > 0) {
+                        isNewHighScore = true;
+                        playerName.clear();
+                        SDL_StartTextInput(window);
+                    } else {
+                        isNewHighScore = false;
+                        ensureScoresLoaded();
+                        {
+                            std::string gt = (game->getMode() == GameMode::Challenge) ? "challenge" : "classic";
+                            scores.submit(game->score(), game->lines(), game->level(), game->elapsed(), "PLAYER", gt);
+                        }
+                    }
+                    state = AppState::GameOver;
+                    stateMgr->setState(state);
+                }
+            }
+        }
+        else if (state == AppState::Loading)
+        {
+            static int queuedTextureCount = 0;
+            if (loadingStarted.load() && !loadingComplete.load()) {
+                static bool queuedTextures = false;
+                static std::vector<std::string> queuedPaths;
+                if (!queuedTextures) {
+                    queuedTextures = true;
+                    constexpr int baseTasks = 25;
+                    totalLoadingTasks.store(baseTasks);
+                    loadedTasks.store(0);
+                    {
+                        std::lock_guard<std::mutex> lk(assetLoadErrorsMutex);
+                        assetLoadErrors.clear();
+                    }
+                    {
+                        std::lock_guard<std::mutex> lk(currentLoadingMutex);
+                        currentLoadingFile.clear();
+                    }
+
+                    Audio::instance().init();
+                    totalTracks = 0;
+                    for (int i = 1; i <= 100; ++i) {
+                        char base[128];
+                        std::snprintf(base, sizeof(base), "assets/music/music%03d", i);
+                        std::string path = AssetPath::resolveWithExtensions(base, { ".mp3" });
+                        if (path.empty()) break;
+                        Audio::instance().addTrackAsync(path);
+                        totalTracks++;
+                    }
+                    totalLoadingTasks.store(baseTasks + totalTracks);
+                    if (totalTracks > 0) {
+                        Audio::instance().startBackgroundLoading();
+                        musicLoadingStarted = true;
+                    } else {
+                        musicLoaded = true;
+                    }
+
+                    pixelFont.init(AssetPath::resolveWithBase(Assets::FONT_ORBITRON), 22);
+                    loadedTasks.fetch_add(1);
+                    font.init(AssetPath::resolveWithBase(Assets::FONT_EXO2), 20);
+                    loadedTasks.fetch_add(1);
+
+                    queuedPaths = {
+                        Assets::LOGO,
+                        Assets::LOGO,
+                        Assets::MAIN_SCREEN,
+                        Assets::BLOCKS_SPRITE,
+                        Assets::PANEL_SCORE,
+                        Assets::PANEL_STATS,
+                        Assets::NEXT_PANEL,
+                        Assets::HOLD_PANEL,
+                        Assets::ASTEROID_SPRITE
+                    };
+                    for (auto &p : queuedPaths) {
+                        loadingManager->queueTexture(p);
+                    }
+                    queuedTextureCount = static_cast<int>(queuedPaths.size());
+
+                    SoundEffectManager::instance().init();
+                    loadedTasks.fetch_add(1);
+
+                    const std::vector<std::string> audioIds = {"clear_line","nice_combo","you_fire","well_played","keep_that_ryhtm","great_move","smooth_clear","impressive","triple_strike","amazing","you_re_unstoppable","boom_tetris","wonderful","lets_go","hard_drop","new_level","asteroid_destroy","challenge_clear"};
+                    for (const auto &id : audioIds) {
+                        std::string basePath = "assets/music/" + (id == "hard_drop"
+                            ? "hard_drop_001"
+                            : (id == "challenge_clear"
+                                ? "GONG0"
+                                : (id == "asteroid_destroy"
+                                    ? "asteroid-destroy"
+                                    : id)));
+                        {
+                            std::lock_guard<std::mutex> lk(currentLoadingMutex);
+                            currentLoadingFile = basePath;
+                        }
+                        std::string resolved = AssetPath::resolveWithExtensions(basePath, { ".wav", ".mp3" });
+                        if (!resolved.empty()) {
+                            SoundEffectManager::instance().loadSound(id, resolved);
+                        }
+                        loadedTasks.fetch_add(1);
+                        {
+                            std::lock_guard<std::mutex> lk(currentLoadingMutex);
+                            currentLoadingFile.clear();
+                        }
+                    }
+                }
+
+                bool texturesDone = loadingManager->update();
+                if (texturesDone) {
+                    logoTex = assetLoader.getTexture(Assets::LOGO);
+                    logoSmallTex = assetLoader.getTexture(Assets::LOGO);
+                    mainScreenTex = assetLoader.getTexture(Assets::MAIN_SCREEN);
+                    blocksTex = assetLoader.getTexture(Assets::BLOCKS_SPRITE);
+                    asteroidsTex = assetLoader.getTexture(Assets::ASTEROID_SPRITE);
+                    scorePanelTex = assetLoader.getTexture(Assets::PANEL_SCORE);
+                    statisticsPanelTex = assetLoader.getTexture(Assets::PANEL_STATS);
+                    nextPanelTex = assetLoader.getTexture(Assets::NEXT_PANEL);
+                    holdPanelTex = assetLoader.getTexture(Assets::HOLD_PANEL);
+
+                    auto ensureTextureSize = [&](SDL_Texture* tex, int& outW, int& outH) {
+                        if (!tex) return;
+                        if (outW > 0 && outH > 0) return;
+                        float w = 0.0f, h = 0.0f;
+                        if (SDL_GetTextureSize(tex, &w, &h)) {
+                            outW = static_cast<int>(std::lround(w));
+                            outH = static_cast<int>(std::lround(h));
+                        }
+                    };
+
+                    ensureTextureSize(logoSmallTex, logoSmallW, logoSmallH);
+                    ensureTextureSize(mainScreenTex, mainScreenW, mainScreenH);
+
+                    auto legacyLoad = [&](const std::string& p, SDL_Texture*& outTex, int* outW = nullptr, int* outH = nullptr) {
+                        if (!outTex) {
+                            SDL_Texture* loaded = textureLoader->loadFromImage(renderer, p, outW, outH);
+                            if (loaded) {
+                                outTex = loaded;
+                                assetLoader.adoptTexture(p, loaded);
+                            }
+                        }
+                    };
+
+                    legacyLoad(Assets::LOGO, logoTex);
+                    legacyLoad(Assets::LOGO, logoSmallTex, &logoSmallW, &logoSmallH);
+                    legacyLoad(Assets::MAIN_SCREEN, mainScreenTex, &mainScreenW, &mainScreenH);
+                    legacyLoad(Assets::BLOCKS_SPRITE, blocksTex);
+                    legacyLoad(Assets::ASTEROID_SPRITE, asteroidsTex);
+                    legacyLoad(Assets::PANEL_SCORE, scorePanelTex);
+                    legacyLoad(Assets::PANEL_STATS, statisticsPanelTex);
+                    legacyLoad(Assets::NEXT_PANEL, nextPanelTex);
+                    legacyLoad(Assets::HOLD_PANEL, holdPanelTex);
+
+                    if (!blocksTex) {
+                        blocksTex = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_RGBA8888, SDL_TEXTUREACCESS_TARGET, 630, 90);
+                        SDL_SetRenderTarget(renderer, blocksTex);
+                        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 0);
+                        SDL_RenderClear(renderer);
+                        for (int i = 0; i < PIECE_COUNT; ++i) {
+                            SDL_Color c = COLORS[i + 1];
+                            SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, c.a);
+                            SDL_FRect rect{(float)(i * 90), 0, 90, 90};
+                            SDL_RenderFillRect(renderer, &rect);
+                        }
+                        SDL_SetRenderTarget(renderer, nullptr);
+
+                        // Ensure the generated fallback texture is cleaned up with other assets.
+                        assetLoader.adoptTexture(Assets::BLOCKS_SPRITE, blocksTex);
+                    }
+
+                    if (musicLoaded) {
+                        loadingComplete.store(true);
+                    }
+                }
+            }
+
+            const int totalTasks = totalLoadingTasks.load(std::memory_order_acquire);
+            const int musicDone = std::min(totalTracks, currentTrackLoading);
+            int doneTasks = loadedTasks.load(std::memory_order_acquire) + musicDone;
+            if (queuedTextureCount > 0) {
+                float texProg = loadingManager->getProgress();
+                int texDone = static_cast<int>(std::floor(texProg * queuedTextureCount + 0.5f));
+                if (texDone > queuedTextureCount) texDone = queuedTextureCount;
+                doneTasks += texDone;
+            }
+            if (doneTasks > totalTasks) doneTasks = totalTasks;
+            if (totalTasks > 0) {
+                loadingProgress = std::min(1.0, double(doneTasks) / double(totalTasks));
+                if (loadingProgress >= 1.0 && musicLoaded) {
+                    startupFadeActive = false;
+                    startupFadeAlpha = 0.0f;
+                    startupFadeClockMs = 0.0;
+
+                    if (std::filesystem::exists(introVideoPath)) {
+                        state = AppState::Video;
+                    } else {
+                        state = AppState::Menu;
+                    }
+                    stateMgr->setState(state);
+                }
+            } else {
+                double assetProgress = 0.2;
+                double musicProgress = 0.0;
+                if (totalTracks > 0) {
+                    musicProgress = musicLoaded ? 0.7 : std::min(0.7, (double)currentTrackLoading / totalTracks * 0.7);
+                } else {
+                    if (Audio::instance().isLoadingComplete()) {
+                        musicProgress = 0.7;
+                    } else if (Audio::instance().getLoadedTrackCount() > 0) {
+                        musicProgress = 0.35;
+                    } else {
+                        Uint32 elapsedMs = SDL_GetTicks() - static_cast<Uint32>(loadStart);
+                        if (elapsedMs > 1500) {
+                            musicProgress = 0.7;
+                            musicLoaded = true;
+                        } else {
+                            musicProgress = 0.0;
+                        }
+                    }
+                }
+                double timeProgress = std::min(0.1, (now - loadStart) / 500.0);
+                loadingProgress = std::min(1.0, assetProgress + musicProgress + timeProgress);
+                if (loadingProgress > 0.99) loadingProgress = 1.0;
+                if (!musicLoaded && timeProgress >= 0.1) loadingProgress = 1.0;
+                if (loadingProgress >= 1.0 && musicLoaded) {
+                    startupFadeActive = false;
+                    startupFadeAlpha = 0.0f;
+                    startupFadeClockMs = 0.0;
+
+                    if (std::filesystem::exists(introVideoPath)) {
+                        state = AppState::Video;
+                    } else {
+                        state = AppState::Menu;
+                    }
+                    stateMgr->setState(state);
+                }
+            }
+        }
+
+        if (state == AppState::Menu || state == AppState::Playing)
+        {
+            if (!musicStarted && musicLoaded)
+            {
+                static bool menuTrackLoaded = false;
+                if (!menuTrackLoaded) {
+                    if (menuTrackLoader.joinable()) {
+                        menuTrackLoader.join();
+                    }
+                    menuTrackLoader = std::jthread([]() {
+                        std::string menuTrack = AssetPath::resolveWithExtensions("assets/music/Every Block You Take", { ".mp3" });
+                        if (!menuTrack.empty()) {
+                            Audio::instance().setMenuTrack(menuTrack);
+                        } else {
+                            SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "Menu track not found (Every Block You Take)");
+                        }
+                    });
+                    menuTrackLoaded = true;
+                }
+
+                if (state == AppState::Menu) {
+                    Audio::instance().playMenuMusic();
+                } else {
+                    Audio::instance().playGameMusic();
+                }
+                musicStarted = true;
+            }
+        }
+
+        static AppState previousState = AppState::Loading;
+        if (state != previousState && musicStarted) {
+            if (state == AppState::Menu && previousState == AppState::Playing) {
+                Audio::instance().playMenuMusic();
+            } else if (state == AppState::Playing && previousState == AppState::Menu) {
+                Audio::instance().playGameMusic();
+            }
+        }
+        previousState = state;
+
+        if (state == AppState::Loading) {
+            starfield3D.update(float(frameMs / 1000.0f));
+            starfield3D.resize(winW, winH);
+        } else {
+            starfield.update(float(frameMs / 1000.0f), logicalVP.x * 2 + logicalVP.w, logicalVP.y * 2 + logicalVP.h);
+        }
+
+        if (state == AppState::Menu) {
+            spaceWarp.resize(winW, winH);
+            spaceWarp.update(float(frameMs / 1000.0f));
+        }
+
+        levelBackgrounds.update(float(frameMs));
+
+        if (state == AppState::Menu) {
+            logoAnimCounter += frameMs * 0.0008;
+        }
+
+        switch (stateMgr->getState()) {
+            case AppState::Loading:
+                loadingState->update(frameMs);
+                break;
+            case AppState::Video:
+                if (videoState) videoState->update(frameMs);
+                break;
+            case AppState::Menu:
+                menuState->update(frameMs);
+                break;
+            case AppState::Options:
+                optionsState->update(frameMs);
+                break;
+            case AppState::LevelSelector:
+                levelSelectorState->update(frameMs);
+                break;
+            case AppState::Playing:
+                playingState->update(frameMs);
+                break;
+            default:
+                break;
+        }
+
+        if (state == AppState::Playing && game && game->getMode() == GameMode::Challenge && !gameplayCountdownActive && !challengeClearFxActive) {
+            int queuedLevel = game->consumeQueuedChallengeLevel();
+            if (queuedLevel > 0) {
+                startChallengeClearFx(queuedLevel);
+            }
+        }
+
+        ctx.logoTex = logoTex;
+        ctx.logoSmallTex = logoSmallTex;
+        ctx.logoSmallW = logoSmallW;
+        ctx.logoSmallH = logoSmallH;
+        ctx.backgroundTex = backgroundTex;
+        ctx.blocksTex = blocksTex;
+        ctx.asteroidsTex = asteroidsTex;
+        ctx.scorePanelTex = scorePanelTex;
+        ctx.statisticsPanelTex = statisticsPanelTex;
+        ctx.nextPanelTex = nextPanelTex;
+        ctx.holdPanelTex = holdPanelTex;
+        ctx.mainScreenTex = mainScreenTex;
+        ctx.mainScreenW = mainScreenW;
+        ctx.mainScreenH = mainScreenH;
+
+        if (menuFadePhase == MenuFadePhase::FadeOut) {
+            menuFadeClockMs += frameMs;
+            menuFadeAlpha = std::min(1.0f, float(menuFadeClockMs / MENU_PLAY_FADE_DURATION_MS));
+            if (menuFadeClockMs >= MENU_PLAY_FADE_DURATION_MS) {
+                if (state != menuFadeTarget) {
+                    state = menuFadeTarget;
+                    stateMgr->setState(state);
+                }
+
+                if (menuFadeTarget == AppState::Playing) {
+                    gameplayCountdownSource = (game && game->getMode() == GameMode::Challenge)
+                        ? CountdownSource::ChallengeLevel
+                        : CountdownSource::MenuStart;
+                    countdownLevel = game ? game->challengeLevel() : 1;
+                    countdownGoalAsteroids = countdownLevel;
+                    if (gameplayCountdownSource == CountdownSource::ChallengeLevel) {
+                        captureChallengeStory(countdownLevel);
+                        challengeCountdownWaitingForSpace = true;
+                    } else {
+                        challengeStoryText.clear();
+                        challengeStoryLevel = 0;
+                        challengeCountdownWaitingForSpace = false;
+                    }
+                    countdownAdvancesChallenge = false;
+                    menuPlayCountdownArmed = true;
+                    gameplayCountdownActive = false;
+                    gameplayCountdownIndex = 0;
+                    gameplayCountdownElapsed = 0.0;
+                    game->setPaused(true);
+                } else {
+                    menuPlayCountdownArmed = false;
+                    gameplayCountdownActive = false;
+                    gameplayCountdownIndex = 0;
+                    gameplayCountdownElapsed = 0.0;
+                    challengeCountdownWaitingForSpace = false;
+                    game->setPaused(false);
+                }
+                menuFadePhase = MenuFadePhase::FadeIn;
+                menuFadeClockMs = MENU_PLAY_FADE_DURATION_MS;
+                menuFadeAlpha = 1.0f;
+            }
+        } else if (menuFadePhase == MenuFadePhase::FadeIn) {
+            menuFadeClockMs -= frameMs;
+            menuFadeAlpha = std::max(0.0f, float(menuFadeClockMs / MENU_PLAY_FADE_DURATION_MS));
+            if (menuFadeClockMs <= 0.0) {
+                menuFadePhase = MenuFadePhase::None;
+                menuFadeClockMs = 0.0;
+                menuFadeAlpha = 0.0f;
+            }
+        }
+
+        if (menuFadePhase == MenuFadePhase::None && menuPlayCountdownArmed && !gameplayCountdownActive && state == AppState::Playing) {
+            gameplayCountdownSource = (game && game->getMode() == GameMode::Challenge)
+                ? CountdownSource::ChallengeLevel
+                : CountdownSource::MenuStart;
+            countdownLevel = game ? game->challengeLevel() : 1;
+            countdownGoalAsteroids = countdownLevel;
+            if (gameplayCountdownSource == CountdownSource::ChallengeLevel) {
+                captureChallengeStory(countdownLevel);
+                challengeCountdownWaitingForSpace = true;
+            } else {
+                challengeStoryText.clear();
+                challengeStoryLevel = 0;
+                challengeCountdownWaitingForSpace = false;
+            }
+            countdownAdvancesChallenge = false;
+            gameplayCountdownActive = true;
+            menuPlayCountdownArmed = false;
+            gameplayCountdownElapsed = 0.0;
+            gameplayCountdownIndex = 0;
+            game->setPaused(true);
+        }
+
+        if (gameplayCountdownActive && state == AppState::Playing) {
+            if (!challengeCountdownWaitingForSpace || gameplayCountdownSource != CountdownSource::ChallengeLevel) {
+                gameplayCountdownElapsed += frameMs;
+                if (gameplayCountdownElapsed >= GAMEPLAY_COUNTDOWN_STEP_MS) {
+                    gameplayCountdownElapsed -= GAMEPLAY_COUNTDOWN_STEP_MS;
+                    ++gameplayCountdownIndex;
+                    if (gameplayCountdownIndex >= static_cast<int>(GAMEPLAY_COUNTDOWN_LABELS.size())) {
+                        gameplayCountdownActive = false;
+                        gameplayCountdownElapsed = 0.0;
+                        gameplayCountdownIndex = 0;
+                        if (gameplayCountdownSource == CountdownSource::ChallengeLevel && countdownAdvancesChallenge && game) {
+                            game->beginNextChallengeLevel();
+                        }
+                        countdownAdvancesChallenge = false;
+                        game->setPaused(false);
+                    }
+                }
+            }
+        }
+
+        if (state != AppState::Playing && gameplayCountdownActive) {
+            gameplayCountdownActive = false;
+            menuPlayCountdownArmed = false;
+            gameplayCountdownElapsed = 0.0;
+            gameplayCountdownIndex = 0;
+            countdownAdvancesChallenge = false;
+            challengeCountdownWaitingForSpace = false;
+            game->setPaused(false);
+        }
+
+        if (state != AppState::Playing && challengeClearFxActive) {
+            challengeClearFxActive = false;
+            challengeClearFxElapsedMs = 0.0;
+            challengeClearFxDurationMs = 0.0;
+            challengeClearFxNextLevel = 0;
+            challengeClearFxOrder.clear();
+        }
+
+        SDL_SetRenderViewport(renderer, nullptr);
+        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
+        SDL_RenderClear(renderer);
+
+        if (state == AppState::Playing) {
+            int bgLevel = std::clamp(game->level(), 0, 32);
+            levelBackgrounds.queueLevelBackground(renderer, bgLevel);
+            levelBackgrounds.render(renderer, winW, winH, static_cast<float>(gameplayBackgroundClockMs));
+        } else if (state == AppState::Loading) {
+            starfield3D.draw(renderer);
+        } else if (state == AppState::Menu) {
+            spaceWarp.draw(renderer, 1.0f);
+        } else if (state == AppState::LevelSelector || state == AppState::Options) {
+            // No background texture
+        } else {
+            starfield.draw(renderer);
+        }
+
+        SDL_SetRenderViewport(renderer, &logicalVP);
+        SDL_SetRenderScale(renderer, logicalScale, logicalScale);
+
+        switch (state)
+        {
+        case AppState::Loading:
+        {
+            float contentScale = logicalScale;
+            float contentW = LOGICAL_W * contentScale;
+            float contentH = LOGICAL_H * contentScale;
+            float contentOffsetX = (winW - contentW) * 0.5f / contentScale;
+            float contentOffsetY = (winH - contentH) * 0.5f / contentScale;
+
+            auto drawRect = [&](float x, float y, float w, float h, SDL_Color c)
+            { RenderPrimitives::fillRect(renderer, x + contentOffsetX, y + contentOffsetY, w, h, c); };
+
+            const bool isLimitedHeight = LOGICAL_H < 450;
+            const float logoHeight = logoTex ? (isLimitedHeight ? LOGICAL_H * 0.25f : LOGICAL_H * 0.4f) : 0;
+            const float loadingTextHeight = 20;
+            const float barHeight = 20;
+            const float barPaddingVertical = isLimitedHeight ? 15 : 35;
+            const float percentTextHeight = 24;
+            const float spacingBetweenElements = isLimitedHeight ? 5 : 15;
+
+            const float totalContentHeight = logoHeight +
+                                           (logoHeight > 0 ? spacingBetweenElements : 0) +
+                                           loadingTextHeight +
+                                           barPaddingVertical +
+                                           barHeight +
+                                           spacingBetweenElements +
+                                           percentTextHeight;
+
+            float currentY = (LOGICAL_H - totalContentHeight) / 2.0f;
+
+            if (logoTex)
+            {
+                const int lw = 872, lh = 273;
+                const float maxLogoWidth = std::min(LOGICAL_W * 0.9f, 600.0f);
+                const float availableHeight = isLimitedHeight ? LOGICAL_H * 0.25f : LOGICAL_H * 0.4f;
+                const float availableWidth = maxLogoWidth;
+
+                const float scaleFactorWidth = availableWidth / static_cast<float>(lw);
+                const float scaleFactorHeight = availableHeight / static_cast<float>(lh);
+                const float scaleFactor = std::min(scaleFactorWidth, scaleFactorHeight);
+
+                const float displayWidth = lw * scaleFactor;
+                const float displayHeight = lh * scaleFactor;
+                const float logoX = (LOGICAL_W - displayWidth) / 2.0f;
+
+                SDL_FRect dst{logoX + contentOffsetX, currentY + contentOffsetY, displayWidth, displayHeight};
+                SDL_RenderTexture(renderer, logoTex, nullptr, &dst);
+
+                currentY += displayHeight + spacingBetweenElements;
+            }
+
+            const char* loadingText = "LOADING";
+            float textWidth = strlen(loadingText) * 12.0f;
+            float textX = (LOGICAL_W - textWidth) / 2.0f;
+            pixelFont.draw(renderer, textX + contentOffsetX, currentY + contentOffsetY, loadingText, 1.0f, {255, 204, 0, 255});
+
+            currentY += loadingTextHeight + barPaddingVertical;
+
+            const int barW = 400, barH = 20;
+            const int bx = (LOGICAL_W - barW) / 2;
+
+            drawRect(bx - 3, currentY - 3, barW + 6, barH + 6, {68, 68, 80, 255});
+            drawRect(bx, currentY, barW, barH, {34, 34, 34, 255});
+            drawRect(bx, currentY, int(barW * loadingProgress), barH, {255, 204, 0, 255});
+
+            currentY += barH + spacingBetweenElements;
+
+            int percentage = int(loadingProgress * 100);
+            char percentText[16];
+            std::snprintf(percentText, sizeof(percentText), "%d%%", percentage);
+
+            float percentWidth = strlen(percentText) * 12.0f;
+            float percentX = (LOGICAL_W - percentWidth) / 2.0f;
+            pixelFont.draw(renderer, percentX + contentOffsetX, currentY + contentOffsetY, percentText, 1.5f, {255, 204, 0, 255});
+
+            {
+                std::lock_guard<std::mutex> lk(assetLoadErrorsMutex);
+                const int maxShow = 5;
+                int count = static_cast<int>(assetLoadErrors.size());
+                if (count > 0) {
+                    int start = std::max(0, count - maxShow);
+                    float errY = currentY + spacingBetweenElements + 8.0f;
+
+                    std::string latest = assetLoadErrors.back();
+                    std::string shortTitle = "SpaceTris - Missing assets";
+                    if (!latest.empty()) {
+                        std::string trimmed = latest;
+                        if (trimmed.size() > 48) trimmed = trimmed.substr(0, 45) + "...";
+                        shortTitle += ": ";
+                        shortTitle += trimmed;
+                    }
+                    SDL_SetWindowTitle(window, shortTitle.c_str());
+
+                    FILE* tf = fopen("tetris_trace.log", "a");
+                    if (tf) {
+                        fprintf(tf, "Loading error: %s\n", assetLoadErrors.back().c_str());
+                        fclose(tf);
+                    }
+
+                    for (int i = start; i < count; ++i) {
+                        const std::string& msg = assetLoadErrors[i];
+                        std::string display = msg;
+                        if (display.size() > 80) display = display.substr(0, 77) + "...";
+                        pixelFont.draw(renderer, 80 + contentOffsetX, errY + contentOffsetY, display.c_str(), 0.85f, {255, 100, 100, 255});
+                        errY += 20.0f;
+                    }
+                }
+            }
+
+            if (Settings::instance().isDebugEnabled()) {
+                std::string cur;
+                {
+                    std::lock_guard<std::mutex> lk(currentLoadingMutex);
+                    cur = currentLoadingFile;
+                }
+                char buf[128];
+                int loaded = loadedTasks.load();
+                int total = totalLoadingTasks.load();
+                std::snprintf(buf, sizeof(buf), "Loaded: %d / %d", loaded, total);
+                float debugX = 20.0f + contentOffsetX;
+                float debugY = LOGICAL_H - 48.0f + contentOffsetY;
+                pixelFont.draw(renderer, debugX, debugY, buf, 0.9f, SDL_Color{200,200,200,255});
+                if (!cur.empty()) {
+                    std::string display = "Loading: ";
+                    display += cur;
+                    if (display.size() > 80) display = display.substr(0,77) + "...";
+                    pixelFont.draw(renderer, debugX, debugY + 18.0f, display.c_str(), 0.85f, SDL_Color{200,180,120,255});
+                }
+            }
+        }
+        break;
+        case AppState::Video:
+            if (videoState) {
+                videoState->render(renderer, logicalScale, logicalVP);
+            }
+            break;
+        case AppState::Menu:
+            if (!mainScreenTex) {
+                mainScreenTex = assetLoader.getTexture(Assets::MAIN_SCREEN);
+            }
+            if (!mainScreenTex) {
+                SDL_Texture* loaded = textureLoader->loadFromImage(renderer, Assets::MAIN_SCREEN, &mainScreenW, &mainScreenH);
+                if (loaded) {
+                    assetLoader.adoptTexture(Assets::MAIN_SCREEN, loaded);
+                    mainScreenTex = loaded;
+                }
+            }
+            if (menuState) {
+                menuState->drawMainButtonNormally = false;
+                menuState->render(renderer, logicalScale, logicalVP);
+            }
+            if (mainScreenTex) {
+                SDL_SetRenderViewport(renderer, nullptr);
+                SDL_SetRenderScale(renderer, 1.f, 1.f);
+                float texW = mainScreenW > 0 ? static_cast<float>(mainScreenW) : 0.0f;
+                float texH = mainScreenH > 0 ? static_cast<float>(mainScreenH) : 0.0f;
+                if (texW <= 0.0f || texH <= 0.0f) {
+                    float iwf = 0.0f, ihf = 0.0f;
+                    if (!SDL_GetTextureSize(mainScreenTex, &iwf, &ihf)) {
+                        iwf = ihf = 0.0f;
+                    }
+                    texW = iwf;
+                    texH = ihf;
+                }
+                if (texW > 0.0f && texH > 0.0f) {
+                    const float drawH = static_cast<float>(winH);
+                    const float scale = drawH / texH;
+                    const float drawW = texW * scale;
+                    SDL_FRect dst{
+                        (winW - drawW) * 0.5f,
+                        0.0f,
+                        drawW,
+                        drawH
+                    };
+                    SDL_SetTextureBlendMode(mainScreenTex, SDL_BLENDMODE_BLEND);
+                    SDL_SetTextureScaleMode(mainScreenTex, SDL_SCALEMODE_LINEAR);
+                    SDL_RenderTexture(renderer, mainScreenTex, nullptr, &dst);
+                }
+                SDL_SetRenderViewport(renderer, &logicalVP);
+                SDL_SetRenderScale(renderer, logicalScale, logicalScale);
+            }
+            if (menuState) {
+                menuState->renderMainButtonTop(renderer, logicalScale, logicalVP);
+            }
+            break;
+        case AppState::Options:
+            optionsState->render(renderer, logicalScale, logicalVP);
+            break;
+        case AppState::LevelSelector:
+            levelSelectorState->render(renderer, logicalScale, logicalVP);
+            break;
+        case AppState::LevelSelect:
+        {
+            const std::string title = "SELECT LEVEL";
+            int tW = 0, tH = 0;
+            font.measure(title, 2.5f, tW, tH);
+            float titleX = (LOGICAL_W - (float)tW) / 2.0f;
+            font.draw(renderer, titleX, 80, title, 2.5f, SDL_Color{255, 220, 0, 255});
+
+            char buf[64];
+            std::snprintf(buf, sizeof(buf), "LEVEL: %d", startLevelSelection);
+            font.draw(renderer, LOGICAL_W * 0.5f - 80, 180, buf, 2.0f, SDL_Color{200, 240, 255, 255});
+            font.draw(renderer, LOGICAL_W * 0.5f - 180, 260, "ARROWS CHANGE  ENTER=OK  ESC=BACK", 1.2f, SDL_Color{200, 200, 220, 255});
+        }
+            break;
+        case AppState::Playing:
+            playingState->render(renderer, logicalScale, logicalVP);
+            break;
+        case AppState::GameOver:
+            GameRenderer::renderPlayingState(
+                renderer,
+                game.get(),
+                &pixelFont,
+                &lineEffect,
+                blocksTex,
+                asteroidsTex,
+                ctx.statisticsPanelTex,
+                scorePanelTex,
+                nextPanelTex,
+                holdPanelTex,
+                false,
+                (float)LOGICAL_W,
+                (float)LOGICAL_H,
+                logicalScale,
+                (float)winW,
+                (float)winH
+            );
+
+            {
+                SDL_SetRenderViewport(renderer, nullptr);
+                SDL_SetRenderDrawColor(renderer, 0, 0, 0, 180);
+                SDL_FRect fullWin{0.f, 0.f, (float)winW, (float)winH};
+                SDL_RenderFillRect(renderer, &fullWin);
+
+                SDL_SetRenderViewport(renderer, &logicalVP);
+                SDL_SetRenderScale(renderer, logicalScale, logicalScale);
+
+                float contentScale = logicalScale;
+                float contentW = LOGICAL_W * contentScale;
+                float contentH = LOGICAL_H * contentScale;
+                float contentOffsetX = (winW - contentW) * 0.5f / contentScale;
+                float contentOffsetY = (winH - contentH) * 0.5f / contentScale;
+
+                float boxW = 500.0f;
+                float boxH = 350.0f;
+                float boxX = (LOGICAL_W - boxW) * 0.5f;
+                float boxY = (LOGICAL_H - boxH) * 0.5f;
+
+                SDL_SetRenderDrawColor(renderer, 20, 25, 35, 255);
+                SDL_FRect boxRect{boxX + contentOffsetX, boxY + contentOffsetY, boxW, boxH};
+                SDL_RenderFillRect(renderer, &boxRect);
+
+                SDL_SetRenderDrawColor(renderer, 100, 120, 200, 255);
+                SDL_FRect borderRect{boxX + contentOffsetX - 3, boxY + contentOffsetY - 3, boxW + 6, boxH + 6};
+                SDL_RenderFillRect(renderer, &borderRect);
+                SDL_SetRenderDrawColor(renderer, 20, 25, 35, 255);
+                SDL_RenderFillRect(renderer, &boxRect);
+
+                ensureScoresLoaded();
+                // Choose display values based on mode (single-player vs coop)
+                int displayScore = 0;
+                int displayLines = 0;
+                int displayLevel = 0;
+                if (game && game->getMode() == GameMode::Cooperate && coopGame) {
+                    int leftScore = coopGame->score(CoopGame::PlayerSide::Left);
+                    int rightScore = coopGame->score(CoopGame::PlayerSide::Right);
+                    displayScore = leftScore + rightScore;
+                    displayLines = coopGame->lines();
+                    displayLevel = coopGame->level();
+                } else if (game) {
+                    displayScore = game->score();
+                    displayLines = game->lines();
+                    displayLevel = game->level();
+                }
+
+                bool realHighScore = scores.isHighScore(displayScore);
+                const char* title = realHighScore ? "NEW HIGH SCORE!" : "GAME OVER";
+                int tW=0, tH=0; pixelFont.measure(title, 2.0f, tW, tH);
+                pixelFont.draw(renderer, boxX + (boxW - tW) * 0.5f + contentOffsetX, boxY + 40 + contentOffsetY, title, 2.0f, realHighScore ? SDL_Color{255, 220, 0, 255} : SDL_Color{255, 60, 60, 255});
+
+                char scoreStr[64];
+                snprintf(scoreStr, sizeof(scoreStr), "SCORE: %d", displayScore);
+                int sW=0, sH=0; pixelFont.measure(scoreStr, 1.2f, sW, sH);
+                pixelFont.draw(renderer, boxX + (boxW - sW) * 0.5f + contentOffsetX, boxY + 100 + contentOffsetY, scoreStr, 1.2f, {255, 255, 255, 255});
+
+                if (isNewHighScore) {
+                    const bool isCoopEntry = (game && game->getMode() == GameMode::Cooperate && coopGame);
+                    const char* enterName = isCoopEntry ? "ENTER NAMES:" : "ENTER NAME:";
+                    int enW=0, enH=0; pixelFont.measure(enterName, 1.0f, enW, enH);
+                    if (!isCoopEntry) {
+                        pixelFont.draw(renderer, boxX + (boxW - enW) * 0.5f + contentOffsetX, boxY + 160 + contentOffsetY, enterName, 1.0f, {200, 200, 220, 255});
+                    }
+
+                    const float inputW = isCoopEntry ? 260.0f : 300.0f;
+                    const float inputH = 40.0f;
+                    const float inputX = boxX + (boxW - inputW) * 0.5f;
+                    const float inputY = boxY + 200.0f;
+
+                    const float nameScale = 1.2f;
+                    const bool showCursor = ((SDL_GetTicks() / 500) % 2) == 0;
+
+                    int metricsW = 0, metricsH = 0;
+                    pixelFont.measure("A", nameScale, metricsW, metricsH);
+                    if (metricsH == 0) metricsH = 24;
+
+                    // Single name entry (non-coop) --- keep original behavior
+                    if (!isCoopEntry) {
+                        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
+                        SDL_FRect inputRect{inputX + contentOffsetX, inputY + contentOffsetY, inputW, inputH};
+                        SDL_RenderFillRect(renderer, &inputRect);
+                        SDL_SetRenderDrawColor(renderer, 255, 220, 0, 255);
+                        SDL_RenderRect(renderer, &inputRect);
+
+                        int nameW = 0, nameH = 0;
+                        if (!playerName.empty()) pixelFont.measure(playerName, nameScale, nameW, nameH);
+                        else nameH = metricsH;
+
+                        float textX = inputX + (inputW - static_cast<float>(nameW)) * 0.5f + contentOffsetX;
+                        float textY = inputY + (inputH - static_cast<float>(metricsH)) * 0.5f + contentOffsetY;
+
+                        if (!playerName.empty()) pixelFont.draw(renderer, textX, textY, playerName, nameScale, {255,255,255,255});
+
+                        if (showCursor) {
+                            int cursorW = 0, cursorH = 0; pixelFont.measure("_", nameScale, cursorW, cursorH);
+                            float cursorX = playerName.empty() ? inputX + (inputW - static_cast<float>(cursorW)) * 0.5f + contentOffsetX : textX + static_cast<float>(nameW);
+                            float cursorY = inputY + (inputH - static_cast<float>(cursorH)) * 0.5f + contentOffsetY;
+                            pixelFont.draw(renderer, cursorX, cursorY, "_", nameScale, {255,255,255,255});
+                        }
+
+                        const char* hint = "PRESS ENTER TO SUBMIT";
+                        int hW=0, hH=0; pixelFont.measure(hint, 0.8f, hW, hH);
+                        pixelFont.draw(renderer, boxX + (boxW - hW) * 0.5f + contentOffsetX, boxY + 280 + contentOffsetY, hint, 0.8f, {150, 150, 150, 255});
+                    } else {
+                        // Coop: prompt sequentially. First ask Player 1, then ask Player 2 after Enter.
+                        const bool askingP1 = (highScoreEntryIndex == 0);
+                        const char* label = askingP1 ? "PLAYER 1:" : "PLAYER 2:";
+                        int labW=0, labH=0; pixelFont.measure(label, 1.0f, labW, labH);
+                        pixelFont.draw(renderer, boxX + (boxW - labW) * 0.5f + contentOffsetX, boxY + 160 + contentOffsetY, label, 1.0f, {200,200,220,255});
+
+                        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
+                        SDL_FRect rect{inputX + contentOffsetX, inputY + contentOffsetY, inputW, inputH};
+                        SDL_RenderFillRect(renderer, &rect);
+                        SDL_SetRenderDrawColor(renderer, 255, 220, 0, 255);
+                        SDL_RenderRect(renderer, &rect);
+
+                        const std::string &activeName = askingP1 ? playerName : player2Name;
+                        int nameW = 0, nameH = 0;
+                        if (!activeName.empty()) pixelFont.measure(activeName, nameScale, nameW, nameH);
+                        else nameH = metricsH;
+
+                        float textX = inputX + (inputW - static_cast<float>(nameW)) * 0.5f + contentOffsetX;
+                        float textY = inputY + (inputH - static_cast<float>(metricsH)) * 0.5f + contentOffsetY;
+                        if (!activeName.empty()) pixelFont.draw(renderer, textX, textY, activeName, nameScale, {255,255,255,255});
+
+                        if (showCursor) {
+                            int cursorW=0, cursorH=0; pixelFont.measure("_", nameScale, cursorW, cursorH);
+                            float cursorX = activeName.empty() ? inputX + (inputW - static_cast<float>(cursorW)) * 0.5f + contentOffsetX : textX + static_cast<float>(nameW);
+                            float cursorY = inputY + (inputH - static_cast<float>(cursorH)) * 0.5f + contentOffsetY;
+                            pixelFont.draw(renderer, cursorX, cursorY, "_", nameScale, {255,255,255,255});
+                        }
+
+                        const char* hint = askingP1 ? "PRESS ENTER FOR NEXT NAME" : "PRESS ENTER TO SUBMIT";
+                        int hW=0, hH=0; pixelFont.measure(hint, 0.8f, hW, hH);
+                        pixelFont.draw(renderer, boxX + (boxW - hW) * 0.5f + contentOffsetX, boxY + 300 + contentOffsetY, hint, 0.8f, {150, 150, 150, 255});
+                    }
+
+                } else {
+                    char linesStr[64];
+                    snprintf(linesStr, sizeof(linesStr), "LINES: %d", game->lines());
+                    int lW=0, lH=0; pixelFont.measure(linesStr, 1.2f, lW, lH);
+                    pixelFont.draw(renderer, boxX + (boxW - lW) * 0.5f + contentOffsetX, boxY + 140 + contentOffsetY, linesStr, 1.2f, {255, 255, 255, 255});
+
+                    char levelStr[64];
+                    snprintf(levelStr, sizeof(levelStr), "LEVEL: %d", game->level());
+                    int lvW=0, lvH=0; pixelFont.measure(levelStr, 1.2f, lvW, lvH);
+                    pixelFont.draw(renderer, boxX + (boxW - lvW) * 0.5f + contentOffsetX, boxY + 180 + contentOffsetY, levelStr, 1.2f, {255, 255, 255, 255});
+
+                    const char* instr = "PRESS ENTER TO RESTART";
+                    int iW=0, iH=0; pixelFont.measure(instr, 0.9f, iW, iH);
+                    pixelFont.draw(renderer, boxX + (boxW - iW) * 0.5f + contentOffsetX, boxY + 260 + contentOffsetY, instr, 0.9f, {255, 220, 0, 255});
+
+                    const char* instr2 = "PRESS ESC FOR MENU";
+                    int iW2=0, iH2=0; pixelFont.measure(instr2, 0.9f, iW2, iH2);
+                    pixelFont.draw(renderer, boxX + (boxW - iW2) * 0.5f + contentOffsetX, boxY + 290 + contentOffsetY, instr2, 0.9f, {255, 220, 0, 255});
+                }
+            }
+            break;
+        }
+
+        if (menuFadeAlpha > 0.0f) {
+            SDL_SetRenderViewport(renderer, nullptr);
+            SDL_SetRenderScale(renderer, 1.f, 1.f);
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+            Uint8 alpha = Uint8(std::clamp(menuFadeAlpha, 0.0f, 1.0f) * 255.0f);
+            SDL_SetRenderDrawColor(renderer, 0, 0, 0, alpha);
+            SDL_FRect fadeRect{0.f, 0.f, (float)winW, (float)winH};
+            SDL_RenderFillRect(renderer, &fadeRect);
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+            SDL_SetRenderViewport(renderer, &logicalVP);
+            SDL_SetRenderScale(renderer, logicalScale, logicalScale);
+        }
+
+        if (gameplayCountdownActive && state == AppState::Playing) {
+            SDL_SetRenderViewport(renderer, nullptr);
+            SDL_SetRenderScale(renderer, 1.f, 1.f);
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+
+            int cappedIndex = std::min(gameplayCountdownIndex, static_cast<int>(GAMEPLAY_COUNTDOWN_LABELS.size()) - 1);
+            const char* label = GAMEPLAY_COUNTDOWN_LABELS[cappedIndex];
+            bool isFinalCue = (cappedIndex == static_cast<int>(GAMEPLAY_COUNTDOWN_LABELS.size()) - 1);
+            float textScale = isFinalCue ? 4.5f : 5.0f;
+            int textW = 0, textH = 0;
+            pixelFont.measure(label, textScale, textW, textH);
+
+            float textX = (winW - static_cast<float>(textW)) * 0.5f;
+            float textY = (winH - static_cast<float>(textH)) * 0.5f;
+            if (gameplayCountdownSource == CountdownSource::ChallengeLevel) {
+                char levelBuf[32];
+                std::snprintf(levelBuf, sizeof(levelBuf), "LEVEL %d", countdownLevel);
+                int lvlW = 0, lvlH = 0;
+                float lvlScale = 2.5f;
+                pixelFont.measure(levelBuf, lvlScale, lvlW, lvlH);
+                float levelX = (winW - static_cast<float>(lvlW)) * 0.5f;
+                float levelY = winH * 0.32f;
+                pixelFont.draw(renderer, levelX, levelY, levelBuf, lvlScale, SDL_Color{140, 210, 255, 255});
+
+                char goalBuf[64];
+                std::snprintf(goalBuf, sizeof(goalBuf), "ASTEROIDS: %d", countdownGoalAsteroids);
+                int goalW = 0, goalH = 0;
+                float goalScale = 1.7f;
+                pixelFont.measure(goalBuf, goalScale, goalW, goalH);
+                float goalX = (winW - static_cast<float>(goalW)) * 0.5f;
+                float goalY = levelY + static_cast<float>(lvlH) + 14.0f;
+                pixelFont.draw(renderer, goalX, goalY, goalBuf, goalScale, SDL_Color{220, 245, 255, 255});
+
+                // Optional story/briefing line
+                if (!challengeStoryText.empty() && challengeStoryAlpha > 0.0f) {
+                    SDL_Color storyColor{170, 230, 255, static_cast<Uint8>(std::lround(255.0f * challengeStoryAlpha))};
+                    SDL_Color shadowColor{0, 0, 0, static_cast<Uint8>(std::lround(160.0f * challengeStoryAlpha))};
+
+                    auto drawCenteredWrapped = [&](const std::string& text, float y, float maxWidth, float scale) {
+                        std::istringstream iss(text);
+                        std::string word;
+                        std::string line;
+                        float cursorY = y;
+                        int lastH = 0;
+                        while (iss >> word) {
+                            std::string candidate = line.empty() ? word : (line + " " + word);
+                            int candidateW = 0, candidateH = 0;
+                            pixelFont.measure(candidate, scale, candidateW, candidateH);
+                            if (candidateW > maxWidth && !line.empty()) {
+                                int lineW = 0, lineH = 0;
+                                pixelFont.measure(line, scale, lineW, lineH);
+                                float lineX = (winW - static_cast<float>(lineW)) * 0.5f;
+                                pixelFont.draw(renderer, lineX + 1.0f, cursorY + 1.0f, line, scale, shadowColor);
+                                pixelFont.draw(renderer, lineX, cursorY, line, scale, storyColor);
+                                cursorY += lineH + 6.0f;
+                                line = word;
+                                lastH = lineH;
+                            } else {
+                                line = candidate;
+                                lastH = candidateH;
+                            }
+                        }
+                        if (!line.empty()) {
+                            int w = 0, h = 0;
+                            pixelFont.measure(line, scale, w, h);
+                            float lineX = (winW - static_cast<float>(w)) * 0.5f;
+                            pixelFont.draw(renderer, lineX + 1.0f, cursorY + 1.0f, line, scale, shadowColor);
+                            pixelFont.draw(renderer, lineX, cursorY, line, scale, storyColor);
+                            cursorY += h + 6.0f;
+                        }
+                        return cursorY;
+                    };
+
+                    float storyStartY = goalY + static_cast<float>(goalH) + 22.0f;
+                    float usedY = drawCenteredWrapped(challengeStoryText, storyStartY, std::min<float>(winW * 0.7f, 720.0f), 1.0f);
+                    float promptY = usedY + 10.0f;
+                    if (challengeCountdownWaitingForSpace) {
+                        const char* prompt = "PRESS SPACE";
+                        int pW = 0, pH = 0;
+                        float pScale = 1.35f;
+                        pixelFont.measure(prompt, pScale, pW, pH);
+                        float px = (winW - static_cast<float>(pW)) * 0.5f;
+                        pixelFont.draw(renderer, px + 2.0f, promptY + 2.0f, prompt, pScale, SDL_Color{0, 0, 0, 200});
+                        pixelFont.draw(renderer, px, promptY, prompt, pScale, SDL_Color{255, 220, 40, 255});
+                        promptY += pH + 14.0f;
+                    }
+                    textY = promptY + 10.0f;
+                } else {
+                    if (challengeCountdownWaitingForSpace) {
+                        const char* prompt = "PRESS SPACE";
+                        int pW = 0, pH = 0;
+                        float pScale = 1.35f;
+                        pixelFont.measure(prompt, pScale, pW, pH);
+                        float px = (winW - static_cast<float>(pW)) * 0.5f;
+                        float py = goalY + static_cast<float>(goalH) + 18.0f;
+                        pixelFont.draw(renderer, px + 2.0f, py + 2.0f, prompt, pScale, SDL_Color{0, 0, 0, 200});
+                        pixelFont.draw(renderer, px, py, prompt, pScale, SDL_Color{255, 220, 40, 255});
+                        textY = py + pH + 24.0f;
+                    } else {
+                        textY = goalY + static_cast<float>(goalH) + 38.0f;
+                    }
+                }
+            } else {
+                textY = winH * 0.38f;
+            }
+            if (!(gameplayCountdownSource == CountdownSource::ChallengeLevel && challengeCountdownWaitingForSpace)) {
+                SDL_Color textColor = isFinalCue ? SDL_Color{255, 230, 90, 255} : SDL_Color{255, 255, 255, 255};
+                pixelFont.draw(renderer, textX, textY, label, textScale, textColor);
+            }
+
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+        }
+
+        if (showHelpOverlay) {
+            SDL_SetRenderViewport(renderer, &logicalVP);
+            SDL_SetRenderScale(renderer, logicalScale, logicalScale);
+            float contentOffsetX = 0.0f;
+            float contentOffsetY = 0.0f;
+            if (logicalScale > 0.0f) {
+                float scaledW = LOGICAL_W * logicalScale;
+                float scaledH = LOGICAL_H * logicalScale;
+                contentOffsetX = (winW - scaledW) * 0.5f / logicalScale;
+                contentOffsetY = (winH - scaledH) * 0.5f / logicalScale;
+            }
+            HelpOverlay::Render(renderer, pixelFont, LOGICAL_W, LOGICAL_H, contentOffsetX, contentOffsetY);
+        }
+
+        if (startupFadeActive && startupFadeAlpha > 0.0f) {
+            SDL_SetRenderViewport(renderer, nullptr);
+            SDL_SetRenderScale(renderer, 1.0f, 1.0f);
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+            const Uint8 a = (Uint8)std::clamp((int)std::lround(startupFadeAlpha * 255.0f), 0, 255);
+            SDL_SetRenderDrawColor(renderer, 0, 0, 0, a);
+            SDL_FRect full{0.f, 0.f, (float)winW, (float)winH};
+            SDL_RenderFillRect(renderer, &full);
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+        }
+
+        SDL_RenderPresent(renderer);
+        SDL_SetRenderScale(renderer, 1.f, 1.f);
+    }
+}
+
+void TetrisApp::Impl::shutdown()
+{
+    Settings::instance().save();
+
+    // BackgroundManager owns its own textures.
+    levelBackgrounds.reset();
+
+    // All textures are owned by AssetLoader (including legacy fallbacks adopted above).
+    logoTex = nullptr;
+    logoSmallTex = nullptr;
+    backgroundTex = nullptr;
+    mainScreenTex = nullptr;
+    blocksTex = nullptr;
+    scorePanelTex = nullptr;
+    statisticsPanelTex = nullptr;
+    nextPanelTex = nullptr;
+
+    if (scoreLoader.joinable()) {
+        scoreLoader.join();
+        if (!ctx.scores) {
+            ctx.scores = &scores;
+        }
+    }
+    if (menuTrackLoader.joinable()) {
+        menuTrackLoader.join();
+    }
+
+    lineEffect.shutdown();
+    Audio::instance().shutdown();
+    SoundEffectManager::instance().shutdown();
+
+    // Destroy textures before tearing down the renderer/window.
+    assetLoader.shutdown();
+
+    pixelFont.shutdown();
+    font.shutdown();
+
+    TTF_Quit();
+
+    if (renderer) {
+        SDL_DestroyRenderer(renderer);
+        renderer = nullptr;
+    }
+    if (window) {
+        SDL_DestroyWindow(window);
+        window = nullptr;
+    }
+    SDL_Quit();
+}
diff --git a/src/app/TetrisApp.h b/src/app/TetrisApp.h
new file mode 100644
index 0000000..1b795d0
--- /dev/null
+++ b/src/app/TetrisApp.h
@@ -0,0 +1,29 @@
+#pragma once
+
+#include <memory>
+
+// TetrisApp is the top-level application orchestrator.
+//
+// Responsibilities:
+// - SDL/TTF init + shutdown
+// - Asset/music loading + loading screen
+// - Main loop + state transitions
+//
+// It uses a PIMPL to keep `TetrisApp.h` light (faster builds) and to avoid leaking
+// SDL-heavy includes into every translation unit.
+class TetrisApp {
+public:
+    TetrisApp();
+    ~TetrisApp();
+
+    TetrisApp(const TetrisApp&) = delete;
+    TetrisApp& operator=(const TetrisApp&) = delete;
+
+    // Runs the application until exit is requested.
+    // Returns a non-zero exit code on initialization failure.
+    int run();
+
+private:
+    struct Impl;
+    std::unique_ptr<Impl> impl_;
+};
diff --git a/src/app/TextureLoader.cpp b/src/app/TextureLoader.cpp
new file mode 100644
index 0000000..ef9af8e
--- /dev/null
+++ b/src/app/TextureLoader.cpp
@@ -0,0 +1,91 @@
+#include "app/TextureLoader.h"
+
+#include <SDL3_image/SDL_image.h>
+
+#include <algorithm>
+#include <mutex>
+#include <sstream>
+
+#include "utils/ImagePathResolver.h"
+
+TextureLoader::TextureLoader(
+    std::atomic<int>& loadedTasks,
+    std::string& currentLoadingFile,
+    std::mutex& currentLoadingMutex,
+    std::vector<std::string>& assetLoadErrors,
+    std::mutex& assetLoadErrorsMutex)
+    : loadedTasks_(loadedTasks)
+    , currentLoadingFile_(currentLoadingFile)
+    , currentLoadingMutex_(currentLoadingMutex)
+    , assetLoadErrors_(assetLoadErrors)
+    , assetLoadErrorsMutex_(assetLoadErrorsMutex)
+{
+}
+
+void TextureLoader::setCurrentLoadingFile(const std::string& filename) {
+    std::lock_guard<std::mutex> lk(currentLoadingMutex_);
+    currentLoadingFile_ = filename;
+}
+
+void TextureLoader::clearCurrentLoadingFile() {
+    std::lock_guard<std::mutex> lk(currentLoadingMutex_);
+    currentLoadingFile_.clear();
+}
+
+void TextureLoader::recordAssetLoadError(const std::string& message) {
+    std::lock_guard<std::mutex> lk(assetLoadErrorsMutex_);
+    assetLoadErrors_.emplace_back(message);
+}
+
+SDL_Texture* TextureLoader::loadFromImage(SDL_Renderer* renderer, const std::string& path, int* outW, int* outH) {
+    if (!renderer) {
+        return nullptr;
+    }
+
+    const std::string resolvedPath = AssetPath::resolveImagePath(path);
+    setCurrentLoadingFile(resolvedPath.empty() ? path : resolvedPath);
+
+    SDL_Surface* surface = IMG_Load(resolvedPath.c_str());
+    if (!surface) {
+        {
+            std::ostringstream ss;
+            ss << "Image load failed: " << path << " (" << resolvedPath << "): " << SDL_GetError();
+            recordAssetLoadError(ss.str());
+        }
+        loadedTasks_.fetch_add(1);
+        clearCurrentLoadingFile();
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to load image %s (resolved: %s): %s", path.c_str(), resolvedPath.c_str(), SDL_GetError());
+        return nullptr;
+    }
+
+    if (outW) {
+        *outW = surface->w;
+    }
+    if (outH) {
+        *outH = surface->h;
+    }
+
+    SDL_Texture* texture = SDL_CreateTextureFromSurface(renderer, surface);
+    SDL_DestroySurface(surface);
+
+    if (!texture) {
+        {
+            std::ostringstream ss;
+            ss << "Texture create failed: " << resolvedPath << ": " << SDL_GetError();
+            recordAssetLoadError(ss.str());
+        }
+        loadedTasks_.fetch_add(1);
+        clearCurrentLoadingFile();
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to create texture from %s: %s", resolvedPath.c_str(), SDL_GetError());
+        return nullptr;
+    }
+
+    loadedTasks_.fetch_add(1);
+    clearCurrentLoadingFile();
+
+    if (resolvedPath != path) {
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Loaded %s via %s", path.c_str(), resolvedPath.c_str());
+    }
+
+    return texture;
+}
diff --git a/src/app/TextureLoader.h b/src/app/TextureLoader.h
new file mode 100644
index 0000000..d807fe7
--- /dev/null
+++ b/src/app/TextureLoader.h
@@ -0,0 +1,31 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+
+#include <atomic>
+#include <mutex>
+#include <string>
+#include <vector>
+
+class TextureLoader {
+public:
+    TextureLoader(
+        std::atomic<int>& loadedTasks,
+        std::string& currentLoadingFile,
+        std::mutex& currentLoadingMutex,
+        std::vector<std::string>& assetLoadErrors,
+        std::mutex& assetLoadErrorsMutex);
+
+    SDL_Texture* loadFromImage(SDL_Renderer* renderer, const std::string& path, int* outW = nullptr, int* outH = nullptr);
+
+private:
+    std::atomic<int>& loadedTasks_;
+    std::string& currentLoadingFile_;
+    std::mutex& currentLoadingMutex_;
+    std::vector<std::string>& assetLoadErrors_;
+    std::mutex& assetLoadErrorsMutex_;
+
+    void setCurrentLoadingFile(const std::string& filename);
+    void clearCurrentLoadingFile();
+    void recordAssetLoadError(const std::string& message);
+};
diff --git a/src/audio/Audio.cpp b/src/audio/Audio.cpp
index 38ecf48..582f7b5 100644
--- a/src/audio/Audio.cpp
+++ b/src/audio/Audio.cpp
@@ -20,6 +20,15 @@
 #pragma comment(lib, "mfuuid.lib")
 #pragma comment(lib, "ole32.lib")
 using Microsoft::WRL::ComPtr;
+#ifdef max
+#undef max
+#endif
+#ifdef min
+#undef min
+#endif
+#elif defined(__APPLE__)
+#include <AudioToolbox/AudioToolbox.h>
+#include <CoreFoundation/CoreFoundation.h>
 #endif
 
 Audio& Audio::instance(){ static Audio inst; return inst; }
@@ -30,7 +39,7 @@ bool Audio::init(){ if(outSpec.freq!=0) return true; outSpec.format=SDL_AUDIO_S1
 #endif
  return true; }
 
-#ifdef _WIN32
+#if defined(_WIN32)
 static bool decodeMP3(const std::string& path, std::vector<int16_t>& outPCM, int& outRate, int& outCh){
   outPCM.clear(); outRate=44100; outCh=2; 
   ComPtr<IMFSourceReader> reader; 
@@ -41,15 +50,85 @@ static bool decodeMP3(const std::string& path, std::vector<int16_t>& outPCM, int
   reader->SetStreamSelection(MF_SOURCE_READER_FIRST_AUDIO_STREAM, TRUE);
   while(true){ DWORD flags=0; ComPtr<IMFSample> sample; if(FAILED(reader->ReadSample(MF_SOURCE_READER_FIRST_AUDIO_STREAM,0,nullptr,&flags,nullptr,&sample))) break; if(flags & MF_SOURCE_READERF_ENDOFSTREAM) break; if(!sample) continue; ComPtr<IMFMediaBuffer> buffer; if(FAILED(sample->ConvertToContiguousBuffer(&buffer))) continue; BYTE* data=nullptr; DWORD maxLen=0, curLen=0; if(SUCCEEDED(buffer->Lock(&data,&maxLen,&curLen)) && curLen){ size_t samples = curLen/2; size_t oldSz = outPCM.size(); outPCM.resize(oldSz + samples); std::memcpy(outPCM.data()+oldSz, data, curLen); } if(data) buffer->Unlock(); }
   outRate=44100; outCh=2; return !outPCM.empty(); }
+#elif defined(__APPLE__)
+// Decode MP3 files using macOS AudioToolbox so music works on Apple builds.
+static bool decodeMP3(const std::string& path, std::vector<int16_t>& outPCM, int& outRate, int& outCh){
+    outPCM.clear();
+    outRate = 44100;
+    outCh = 2;
+
+    CFURLRef url = CFURLCreateFromFileSystemRepresentation(nullptr, reinterpret_cast<const UInt8*>(path.c_str()), path.size(), false);
+    if (!url) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] Failed to create URL for %s", path.c_str());
+        return false;
+    }
+
+    ExtAudioFileRef audioFile = nullptr;
+    OSStatus status = ExtAudioFileOpenURL(url, &audioFile);
+    CFRelease(url);
+    if (status != noErr || !audioFile) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] ExtAudioFileOpenURL failed (%d) for %s", static_cast<int>(status), path.c_str());
+        return false;
+    }
+
+    AudioStreamBasicDescription clientFormat{};
+    clientFormat.mSampleRate = 44100.0;
+    clientFormat.mFormatID = kAudioFormatLinearPCM;
+    clientFormat.mFormatFlags = kAudioFormatFlagIsSignedInteger | kAudioFormatFlagIsPacked;
+    clientFormat.mBitsPerChannel = 16;
+    clientFormat.mChannelsPerFrame = 2;
+    clientFormat.mFramesPerPacket = 1;
+    clientFormat.mBytesPerFrame = (clientFormat.mBitsPerChannel / 8) * clientFormat.mChannelsPerFrame;
+    clientFormat.mBytesPerPacket = clientFormat.mBytesPerFrame * clientFormat.mFramesPerPacket;
+
+    status = ExtAudioFileSetProperty(audioFile, kExtAudioFileProperty_ClientDataFormat, sizeof(clientFormat), &clientFormat);
+    if (status != noErr) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] Failed to set client format (%d) for %s", static_cast<int>(status), path.c_str());
+        ExtAudioFileDispose(audioFile);
+        return false;
+    }
+
+    const UInt32 framesPerBuffer = 4096;
+    std::vector<int16_t> buffer(framesPerBuffer * clientFormat.mChannelsPerFrame);
+    while (true) {
+        AudioBufferList abl{};
+        abl.mNumberBuffers = 1;
+        abl.mBuffers[0].mNumberChannels = clientFormat.mChannelsPerFrame;
+        abl.mBuffers[0].mDataByteSize = framesPerBuffer * clientFormat.mBytesPerFrame;
+        abl.mBuffers[0].mData = buffer.data();
+
+        UInt32 framesToRead = framesPerBuffer;
+        status = ExtAudioFileRead(audioFile, &framesToRead, &abl);
+        if (status != noErr) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] ExtAudioFileRead failed (%d) for %s", static_cast<int>(status), path.c_str());
+            ExtAudioFileDispose(audioFile);
+            return false;
+        }
+
+        if (framesToRead == 0) {
+            break; // EOF
+        }
+
+        size_t samplesRead = static_cast<size_t>(framesToRead) * clientFormat.mChannelsPerFrame;
+        outPCM.insert(outPCM.end(), buffer.data(), buffer.data() + samplesRead);
+    }
+
+    ExtAudioFileDispose(audioFile);
+    outRate = static_cast<int>(clientFormat.mSampleRate);
+    outCh = static_cast<int>(clientFormat.mChannelsPerFrame);
+    return !outPCM.empty();
+}
+#else
+static bool decodeMP3(const std::string& path, std::vector<int16_t>& outPCM, int& outRate, int& outCh){
+    (void)outPCM; (void)outRate; (void)outCh; (void)path;
+    SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] MP3 unsupported on this platform: %s", path.c_str());
+    return false;
+}
 #endif
 
 void Audio::addTrack(const std::string& path){ AudioTrack t; t.path=path; 
-#ifdef _WIN32
-    if(decodeMP3(path, t.pcm, t.rate, t.channels)) t.ok=true; else SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] Failed to decode %s", path.c_str());
-#else
-    SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] MP3 unsupported on this platform (stub): %s", path.c_str());
-#endif
-  tracks.push_back(std::move(t)); }
+        if(decodeMP3(path, t.pcm, t.rate, t.channels)) t.ok=true; else SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] Failed to decode %s", path.c_str());
+    tracks.push_back(std::move(t)); }
 
 void Audio::shuffle(){ 
     std::lock_guard<std::mutex> lock(tracksMutex);
@@ -58,19 +137,63 @@ void Audio::shuffle(){
 
 bool Audio::ensureStream(){
     if(audioStream) return true;
+    // Ensure audio spec is initialized
+    if (!init()) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] Failed to initialize audio spec before opening device stream");
+        return false;
+    }
     audioStream = SDL_OpenAudioDeviceStream(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &outSpec, &Audio::streamCallback, this);
     if(!audioStream){
         SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] SDL_OpenAudioDeviceStream failed: %s", SDL_GetError());
         return false;
     }
+    // Ensure the device is running so SFX can be heard even before music starts
+    SDL_ResumeAudioStreamDevice(audioStream);
     return true;
 }
 
-void Audio::start(){ if(!ensureStream()) return; if(!playing){ current=-1; nextTrack(); SDL_ResumeAudioStreamDevice(audioStream); playing=true; } }
+void Audio::start(){
+    if(!ensureStream()) return;
+    // If no track is selected yet, try to select one now (in case tracks loaded after initial start)
+    if(current < 0) {
+        nextTrack();
+    }
+    SDL_ResumeAudioStreamDevice(audioStream);
+    playing = true;
+}
+
+void Audio::skipToNextTrack(){
+    if(!ensureStream()) return;
+
+    // If menu music is active, just restart the looped menu track
+    if(isMenuMusic){
+        if(menuTrack.ok){
+            menuTrack.cursor = 0;
+            playing = true;
+            SDL_ResumeAudioStreamDevice(audioStream);
+        }
+        return;
+    }
+
+    if(tracks.empty()) return;
+    nextTrack();
+    playing = true;
+    SDL_ResumeAudioStreamDevice(audioStream);
+}
 
 void Audio::toggleMute(){ muted=!muted; }
+void Audio::setMuted(bool m){ muted=m; }
 
-void Audio::nextTrack(){ if(tracks.empty()) return; for(size_t i=0;i<tracks.size(); ++i){ current = (current + 1) % (int)tracks.size(); if(tracks[current].ok){ tracks[current].cursor=0; return; } } current=-1; }
+void Audio::nextTrack(){
+    if(tracks.empty()) { current = -1; return; }
+    // Try every track once to find a decodable one
+    int start = current;
+    for(size_t i=0;i<tracks.size(); ++i){
+        current = (current + 1) % (int)tracks.size();
+        if(tracks[current].ok){ tracks[current].cursor=0; return; }
+    }
+    current=-1;
+}
 
 void Audio::feed(Uint32 bytesWanted, SDL_AudioStream* stream){
   if(bytesWanted==0) return;
@@ -79,25 +202,52 @@ void Audio::feed(Uint32 bytesWanted, SDL_AudioStream* stream){
     std::vector<int16_t> mix(outSamples, 0);
 
     // 1) Mix music into buffer (if not muted)
-    if(!muted && current >= 0){
+    // 1) Mix music into buffer (if not muted)
+    if(!muted && playing){
         size_t cursorBytes = 0;
         while(cursorBytes < bytesWanted){
-            if(current < 0) break;
-            auto &trk = tracks[current];
-            size_t samplesAvail = trk.pcm.size() - trk.cursor; // samples (int16)
-            if(samplesAvail == 0){ nextTrack(); if(current < 0) break; continue; }
+            AudioTrack* trk = nullptr;
+            
+            if (isMenuMusic) {
+                if (menuTrack.ok) trk = &menuTrack;
+            } else {
+                if (current >= 0 && current < (int)tracks.size()) trk = &tracks[current];
+            }
+            
+            if (!trk) break;
+
+            size_t samplesAvail = trk->pcm.size() - trk->cursor; // samples (int16)
+            if(samplesAvail == 0){ 
+                if (isMenuMusic) {
+                    trk->cursor = 0; // Loop menu music
+                    continue;
+                } else {
+                    nextTrack(); 
+                    if(current < 0) break; 
+                    continue; 
+                }
+            }
+            
             size_t samplesNeeded = (bytesWanted - cursorBytes) / sizeof(int16_t);
             size_t toCopy = (samplesAvail < samplesNeeded) ? samplesAvail : samplesNeeded;
             if(toCopy == 0) break;
+            
             // Mix add with clamp
             size_t startSample = cursorBytes / sizeof(int16_t);
             for(size_t i=0;i<toCopy;++i){
-                int v = (int)mix[startSample+i] + (int)trk.pcm[trk.cursor+i];
+                int v = (int)mix[startSample+i] + (int)trk->pcm[trk->cursor+i];
                 if(v>32767) v=32767; if(v<-32768) v=-32768; mix[startSample+i] = (int16_t)v;
             }
-            trk.cursor += toCopy;
+            trk->cursor += toCopy;
             cursorBytes += (Uint32)(toCopy * sizeof(int16_t));
-            if(trk.cursor >= trk.pcm.size()) nextTrack();
+            
+            if(trk->cursor >= trk->pcm.size()) {
+                if (isMenuMusic) {
+                    trk->cursor = 0; // Loop menu music
+                } else {
+                    nextTrack();
+                }
+            }
         }
     }
 
@@ -156,7 +306,16 @@ void Audio::addTrackAsync(const std::string& path) {
 }
 
 void Audio::startBackgroundLoading() {
-    if (loadingThread.joinable()) return; // Already running
+    // If a previous loading thread exists but has finished, join it so we can start anew
+    if (loadingThread.joinable()) {
+        if (loadingComplete) {
+            loadingThread.join();
+        } else {
+            // Already running
+            return;
+        }
+    }
+    loadingAbort = false;
     loadingComplete = false;
     loadedCount = 0;
     loadingThread = std::thread(&Audio::backgroundLoadingThread, this);
@@ -174,36 +333,46 @@ void Audio::backgroundLoadingThread() {
     }
 #endif
 
-    // Copy pending tracks to avoid holding the mutex during processing
-    std::vector<std::string> tracksToProcess;
-    {
-        std::lock_guard<std::mutex> lock(pendingTracksMutex);
-        tracksToProcess = pendingTracks;
-    }
-
-    for (const std::string& path : tracksToProcess) {
+    while (true) {
+        if (loadingAbort.load()) {
+            break;
+        }
+        std::string path;
+        {
+            std::lock_guard<std::mutex> lock(pendingTracksMutex);
+            if (pendingTracks.empty()) break;
+            path = std::move(pendingTracks.front());
+            pendingTracks.erase(pendingTracks.begin());
+            if (loadingAbort.load()) {
+                break;
+            }
+        }
         AudioTrack t;
         t.path = path;
-#ifdef _WIN32
-        if (mfInitialized && decodeMP3(path, t.pcm, t.rate, t.channels)) {
+        if (decodeMP3(path, t.pcm, t.rate, t.channels)) {
             t.ok = true;
         } else {
             SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] Failed to decode %s", path.c_str());
         }
-#else
-    SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] MP3 unsupported on this platform (stub): %s", path.c_str());
-#endif
         
         // Thread-safe addition to tracks
+        if (loadingAbort.load()) {
+            break;
+        }
+
         {
             std::lock_guard<std::mutex> lock(tracksMutex);
             tracks.push_back(std::move(t));
         }
         
-        loadedCount++;
+    loadedCount++;
         
-        // Small delay to prevent overwhelming the system
-        std::this_thread::sleep_for(std::chrono::milliseconds(10));
+        // Small delay to prevent overwhelming the system (unless abort requested)
+        if (!loadingAbort.load()) {
+            std::this_thread::sleep_for(std::chrono::milliseconds(10));
+        } else {
+            break;
+        }
     }
     
 #ifdef _WIN32
@@ -233,11 +402,43 @@ int Audio::getLoadedTrackCount() const {
     return loadedCount;
 }
 
+void Audio::setMenuTrack(const std::string& path) {
+    menuTrack.path = path;
+    if (decodeMP3(path, menuTrack.pcm, menuTrack.rate, menuTrack.channels)) {
+        menuTrack.ok = true;
+    } else {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[Audio] Failed to decode menu track %s", path.c_str());
+    }
+}
+
+void Audio::playMenuMusic() {
+    isMenuMusic = true;
+    if (menuTrack.ok) {
+        menuTrack.cursor = 0;
+    }
+    start();
+}
+
+void Audio::playGameMusic() {
+    isMenuMusic = false;
+    // If we were playing menu music, we might want to pick a random track or resume
+    if (current < 0 && !tracks.empty()) {
+        nextTrack();
+    }
+    start();
+}
+
 void Audio::shutdown(){ 
     // Stop background loading thread first
+    loadingAbort = true;
+    {
+        std::lock_guard<std::mutex> lock(pendingTracksMutex);
+        pendingTracks.clear();
+    }
     if (loadingThread.joinable()) {
         loadingThread.join();
     }
+    loadingComplete = true;
     
     if(audioStream){ SDL_DestroyAudioStream(audioStream); audioStream=nullptr; } 
     tracks.clear(); 
@@ -250,3 +451,40 @@ void Audio::shutdown(){
  if(mfStarted){ MFShutdown(); mfStarted=false; }
 #endif
 }
+
+// IAudioSystem interface implementation
+void Audio::playSound(const std::string& name) {
+    // This is a simplified implementation - in a full implementation,
+    // you would load sound effects by name from assets
+    // For now, we'll just trigger a generic sound effect
+    // In practice, this would load a sound file and play it via playSfx
+}
+
+void Audio::playMusic(const std::string& name) {
+    // This is a simplified implementation - in a full implementation,
+    // you would load music tracks by name
+    // For now, we'll just start the current playlist
+    if (!tracks.empty() && !playing) {
+        start();
+    }
+}
+
+void Audio::stopMusic() {
+    playing = false;
+}
+
+void Audio::setMasterVolume(float volume) {
+    m_masterVolume = std::max(0.0f, std::min(1.0f, volume));
+}
+
+void Audio::setMusicVolume(float volume) {
+    m_musicVolume = std::max(0.0f, std::min(1.0f, volume));
+}
+
+void Audio::setSoundVolume(float volume) {
+    m_sfxVolume = std::max(0.0f, std::min(1.0f, volume));
+}
+
+bool Audio::isMusicPlaying() const {
+    return playing;
+}
diff --git a/src/audio/Audio.h b/src/audio/Audio.h
index 7275b3d..35f520a 100644
--- a/src/audio/Audio.h
+++ b/src/audio/Audio.h
@@ -8,6 +8,7 @@
 #include <thread>
 #include <mutex>
 #include <atomic>
+#include "../core/interfaces/IAudioSystem.h"
 
 struct AudioTrack {
     std::string path;
@@ -18,9 +19,20 @@ struct AudioTrack {
     bool ok = false;
 };
 
-class Audio {
+class Audio : public IAudioSystem {
 public:
     static Audio& instance();
+    
+    // IAudioSystem interface implementation
+    void playSound(const std::string& name) override;
+    void playMusic(const std::string& name) override;
+    void stopMusic() override;
+    void setMasterVolume(float volume) override;
+    void setMusicVolume(float volume) override;
+    void setSoundVolume(float volume) override;
+    bool isMusicPlaying() const override;
+
+    // Existing Audio class methods
     bool init();                  // initialize backend (MF on Windows)
     void addTrack(const std::string& path); // decode MP3 -> PCM16 stereo 44100
     void addTrackAsync(const std::string& path); // add track for background loading
@@ -30,7 +42,16 @@ public:
     int getLoadedTrackCount() const; // get number of tracks loaded so far
     void shuffle();               // randomize order
     void start();                 // begin playback
+    void skipToNextTrack();       // advance to the next music track
     void toggleMute();
+    void setMuted(bool m);
+    bool isMuted() const { return muted; }
+    
+    // Menu music support
+    void setMenuTrack(const std::string& path);
+    void playMenuMusic();
+    void playGameMusic();
+    
     // Queue a sound effect to mix over the music (pcm can be mono/stereo, any rate; will be converted)
     void playSfx(const std::vector<int16_t>& pcm, int channels, int rate, float volume);
     void shutdown();
@@ -42,7 +63,10 @@ private:
     bool ensureStream();
     void backgroundLoadingThread(); // background thread function
     
-    std::vector<AudioTrack> tracks; int current=-1; bool playing=false; bool muted=false; std::mt19937 rng{std::random_device{}()};
+    std::vector<AudioTrack> tracks; 
+    AudioTrack menuTrack;
+    bool isMenuMusic = false;
+    int current=-1; bool playing=false; bool muted=false; std::mt19937 rng{std::random_device{}()};
     SDL_AudioStream* audioStream=nullptr; SDL_AudioSpec outSpec{}; int outChannels=2; int outRate=44100; bool mfStarted=false;
     
     // Threading support
@@ -51,10 +75,16 @@ private:
     std::mutex tracksMutex;
     std::mutex pendingTracksMutex;
     std::atomic<bool> loadingComplete{false};
+    std::atomic<bool> loadingAbort{false};
     std::atomic<int> loadedCount{0};
 
     // SFX mixing support
     struct SfxPlay { std::vector<int16_t> pcm; size_t cursor=0; };
     std::vector<SfxPlay> activeSfx;
     std::mutex sfxMutex;
+    
+    // Volume control
+    float m_masterVolume = 1.0f;
+    float m_musicVolume = 1.0f;
+    float m_sfxVolume = 1.0f;
 };
diff --git a/src/audio/MenuWrappers.h b/src/audio/MenuWrappers.h
index 68847af..ad2e98c 100644
--- a/src/audio/MenuWrappers.h
+++ b/src/audio/MenuWrappers.h
@@ -12,11 +12,7 @@ void menu_updateFireworks(double frameMs);
 double menu_getLogoAnimCounter();
 int menu_getHoveredButton();
 
-void menu_drawEnhancedButton(SDL_Renderer* renderer, FontAtlas& font, float cx, float cy, float w, float h,
-                            const std::string& label, bool isHovered, bool isSelected);
-
-void menu_drawMenuButton(SDL_Renderer* renderer, FontAtlas& font, float cx, float cy, float w, float h,
-                         const std::string& label, SDL_Color bgColor, SDL_Color borderColor);
-
-void menu_drawLevelSelectionPopup(SDL_Renderer* renderer, FontAtlas& font, SDL_Texture* bgTex, int selectedLevel);
-void menu_drawSettingsPopup(SDL_Renderer* renderer, FontAtlas& font, bool musicEnabled);
+// Legacy wrappers removed
+// void menu_drawEnhancedButton(...);
+// void menu_drawMenuButton(...);
+// void menu_drawSettingsPopup(...);
diff --git a/src/audio/SoundEffect.cpp b/src/audio/SoundEffect.cpp
index 24317bd..ecc34ee 100644
--- a/src/audio/SoundEffect.cpp
+++ b/src/audio/SoundEffect.cpp
@@ -20,6 +20,9 @@
 #pragma comment(lib, "mfuuid.lib")
 #pragma comment(lib, "ole32.lib")
 using Microsoft::WRL::ComPtr;
+#elif defined(__APPLE__)
+#include <AudioToolbox/AudioToolbox.h>
+#include <CoreFoundation/CoreFoundation.h>
 #endif
 
 // SoundEffect implementation
@@ -43,7 +46,6 @@ bool SoundEffect::load(const std::string& filePath) {
     }
     
     loaded = true;
-    //std::printf("[SoundEffect] Loaded: %s (%d channels, %d Hz, %zu samples)\n", filePath.c_str(), channels, sampleRate, pcmData.size());
     return true;
 }
 
@@ -52,9 +54,7 @@ void SoundEffect::play(float volume) {
     SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "[SoundEffect] Cannot play - loaded=%d, pcmData.size()=%zu", loaded, pcmData.size());
         return;
     }
-    
-    //std::printf("[SoundEffect] Playing sound with %zu samples at volume %.2f\n", pcmData.size(), volume);
-    
+        
     // Calculate final volume
     float finalVolume = defaultVolume * volume;
     finalVolume = (std::max)(0.0f, (std::min)(1.0f, finalVolume));
@@ -143,7 +143,7 @@ bool SoundEffect::loadWAV(const std::string& filePath) {
 }
 
 bool SoundEffect::loadMP3(const std::string& filePath) {
-#ifdef _WIN32
+#if defined(_WIN32)
     static bool mfInitialized = false;
     if (!mfInitialized) {
         if (FAILED(MFStartup(MF_VERSION))) {
@@ -222,6 +222,67 @@ bool SoundEffect::loadMP3(const std::string& filePath) {
     channels = 2;
     sampleRate = 44100;
     return true;
+#elif defined(__APPLE__)
+    CFURLRef url = CFURLCreateFromFileSystemRepresentation(nullptr, reinterpret_cast<const UInt8*>(filePath.c_str()), filePath.size(), false);
+    if (!url) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[SoundEffect] Failed to create URL for %s", filePath.c_str());
+        return false;
+    }
+
+    ExtAudioFileRef audioFile = nullptr;
+    OSStatus status = ExtAudioFileOpenURL(url, &audioFile);
+    CFRelease(url);
+    if (status != noErr || !audioFile) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[SoundEffect] ExtAudioFileOpenURL failed (%d) for %s", static_cast<int>(status), filePath.c_str());
+        return false;
+    }
+
+    AudioStreamBasicDescription clientFormat{};
+    clientFormat.mSampleRate = 44100.0;
+    clientFormat.mFormatID = kAudioFormatLinearPCM;
+    clientFormat.mFormatFlags = kAudioFormatFlagIsSignedInteger | kAudioFormatFlagIsPacked;
+    clientFormat.mBitsPerChannel = 16;
+    clientFormat.mChannelsPerFrame = 2;
+    clientFormat.mFramesPerPacket = 1;
+    clientFormat.mBytesPerFrame = (clientFormat.mBitsPerChannel / 8) * clientFormat.mChannelsPerFrame;
+    clientFormat.mBytesPerPacket = clientFormat.mBytesPerFrame * clientFormat.mFramesPerPacket;
+
+    status = ExtAudioFileSetProperty(audioFile, kExtAudioFileProperty_ClientDataFormat, sizeof(clientFormat), &clientFormat);
+    if (status != noErr) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[SoundEffect] Failed to set client format (%d) for %s", static_cast<int>(status), filePath.c_str());
+        ExtAudioFileDispose(audioFile);
+        return false;
+    }
+
+    const UInt32 framesPerBuffer = 2048;
+    std::vector<int16_t> buffer(framesPerBuffer * clientFormat.mChannelsPerFrame);
+    while (true) {
+        AudioBufferList abl{};
+        abl.mNumberBuffers = 1;
+        abl.mBuffers[0].mNumberChannels = clientFormat.mChannelsPerFrame;
+        abl.mBuffers[0].mDataByteSize = framesPerBuffer * clientFormat.mBytesPerFrame;
+        abl.mBuffers[0].mData = buffer.data();
+
+        UInt32 framesToRead = framesPerBuffer;
+        status = ExtAudioFileRead(audioFile, &framesToRead, &abl);
+        if (status != noErr) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[SoundEffect] ExtAudioFileRead failed (%d) for %s", static_cast<int>(status), filePath.c_str());
+            ExtAudioFileDispose(audioFile);
+            return false;
+        }
+
+        if (framesToRead == 0) {
+            break; // EOF
+        }
+
+        size_t samplesRead = static_cast<size_t>(framesToRead) * clientFormat.mChannelsPerFrame;
+        pcmData.insert(pcmData.end(), buffer.data(), buffer.data() + samplesRead);
+    }
+
+    ExtAudioFileDispose(audioFile);
+    channels = static_cast<int>(clientFormat.mChannelsPerFrame);
+    sampleRate = static_cast<int>(clientFormat.mSampleRate);
+    return !pcmData.empty();
 #else
     SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[SoundEffect] MP3 support not available on this platform");
     return false;
diff --git a/src/core/Config.h b/src/core/Config.h
new file mode 100644
index 0000000..9d8ea3d
--- /dev/null
+++ b/src/core/Config.h
@@ -0,0 +1,163 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+
+/**
+ * Config - Centralized configuration constants
+ * 
+ * Replaces magic numbers and scattered constants throughout main.cpp
+ * Organized by functional area for easy maintenance and modification
+ */
+namespace Config {
+    
+    // Window and Display Settings
+    namespace Window {
+        constexpr int DEFAULT_WIDTH = 1200;
+        constexpr int DEFAULT_HEIGHT = 1000;
+        constexpr const char* DEFAULT_TITLE = "SpaceTris (SDL3)";
+        constexpr bool DEFAULT_VSYNC = true;
+    }
+    
+    // Logical rendering dimensions (internal coordinate system)
+    namespace Logical {
+        constexpr int WIDTH = 1200;
+        constexpr int HEIGHT = 1000;
+    }
+    
+    // Gameplay constants
+    namespace Gameplay {
+        constexpr double DAS_DELAY = 170.0;        // Delayed Auto Shift delay in ms
+        constexpr double ARR_RATE = 40.0;          // Auto Repeat Rate in ms
+        constexpr float LEVEL_FADE_DURATION = 5000.0f; // Level background fade time in ms
+        constexpr int MAX_LEVELS = 20;             // Maximum selectable starting level
+        
+        // Gravity speed multiplier: 1.0 = normal, 2.0 = 2x slower, 0.5 = 2x faster
+        constexpr double GRAVITY_SPEED_MULTIPLIER = 2; // increase drop interval by ~100% to slow gravity
+    }
+    
+    // UI Layout constants  
+    namespace UI {
+        constexpr float MIN_MARGIN = 40.0f;
+        constexpr float PANEL_WIDTH = 180.0f;
+        constexpr float PANEL_SPACING = 30.0f;
+        constexpr float BUTTON_HEIGHT_SMALL = 60.0f;
+        constexpr float BUTTON_HEIGHT_NORMAL = 70.0f;
+        constexpr float BUTTON_WIDTH_SMALL = 0.4f;   // Fraction of screen width
+        constexpr float BUTTON_WIDTH_NORMAL = 300.0f;
+        constexpr float SETTINGS_GEAR_SIZE = 50.0f;
+        constexpr float SETTINGS_GEAR_MARGIN = 10.0f;
+        
+        // Screen size breakpoints
+        constexpr float SMALL_SCREEN_BREAKPOINT = 700.0f;
+        
+        // Menu positioning
+        constexpr float MENU_BUTTON_Y_OFFSET = 40.0f;
+        constexpr float MENU_BUTTON_Y_BASE = 0.86f;  // Fraction of screen height
+    }
+    
+    // Loading screen constants
+    namespace Loading {
+        constexpr float LOGO_HEIGHT_FACTOR_LIMITED = 0.25f;  // When height < 450
+        constexpr float LOGO_HEIGHT_FACTOR_NORMAL = 0.4f;
+        constexpr float LOGO_MAX_WIDTH_FACTOR = 0.9f;        // Fraction of screen width
+        constexpr float LOGO_MAX_WIDTH_ABSOLUTE = 600.0f;
+        constexpr int LOGO_ORIGINAL_WIDTH = 872;
+        constexpr int LOGO_ORIGINAL_HEIGHT = 273;
+        constexpr float LOADING_TEXT_HEIGHT = 20.0f;
+        constexpr float LOADING_BAR_HEIGHT = 20.0f;
+        constexpr float LOADING_BAR_PADDING_LIMITED = 15.0f;
+        constexpr float LOADING_BAR_PADDING_NORMAL = 35.0f;
+        constexpr float LOADING_PERCENTAGE_HEIGHT = 24.0f;
+        constexpr float LOADING_ELEMENT_SPACING_LIMITED = 5.0f;
+        constexpr float LOADING_ELEMENT_SPACING_NORMAL = 15.0f;
+        constexpr int LIMITED_HEIGHT_THRESHOLD = 450;
+    }
+    
+    // Animation constants
+    namespace Animation {
+        constexpr double LOGO_ANIM_SPEED = 0.0008;  // Logo animation speed multiplier
+        constexpr float STARFIELD_UPDATE_DIVISOR = 1000.0f; // Convert ms to seconds
+    }
+    
+    // HUD and Game Display
+    namespace HUD {
+        constexpr float GRAVITY_DISPLAY_X = 260.0f;  // Distance from right edge
+        constexpr float GRAVITY_DISPLAY_Y = 10.0f;
+        constexpr float SCORE_PANEL_X_OFFSET = 120.0f; // Distance from center
+        constexpr float SCORE_PANEL_BASE_Y = 220.0f;
+        constexpr float CONTROLS_HINT_Y_OFFSET = 30.0f; // Distance from bottom
+    }
+    
+    // Popup and Modal constants
+    namespace Popup {
+        constexpr float EXIT_CONFIRM_WIDTH = 400.0f;
+        constexpr float EXIT_CONFIRM_HEIGHT = 200.0f;
+        constexpr float SETTINGS_POPUP_WIDTH = 300.0f;
+        constexpr float SETTINGS_POPUP_HEIGHT = 250.0f;
+    }
+    
+    // Color definitions (commonly used colors)
+    namespace Colors {
+        constexpr SDL_Color WHITE = {255, 255, 255, 255};
+        constexpr SDL_Color BLACK = {0, 0, 0, 255};
+        constexpr SDL_Color YELLOW_TITLE = {255, 220, 0, 255};
+        constexpr SDL_Color GRAY_TEXT = {220, 220, 230, 255};
+        constexpr SDL_Color BLUE_HIGHLIGHT = {200, 240, 255, 255};
+        constexpr SDL_Color RED_ERROR = {255, 80, 60, 255};
+        constexpr SDL_Color GREEN_SUCCESS = {0, 255, 0, 255};
+        constexpr SDL_Color RED_DISABLED = {255, 0, 0, 255};
+        constexpr SDL_Color CONTROL_HINT = {150, 150, 170, 255};
+        constexpr SDL_Color PAUSED_TEXT = {255, 255, 255, 255};
+        constexpr SDL_Color PAUSED_HINT = {200, 200, 220, 255};
+        constexpr SDL_Color SHADOW = {0, 0, 0, 200};
+    }
+    
+    // Font configuration
+    namespace Fonts {
+        constexpr int DEFAULT_FONT_SIZE = 24;
+        constexpr int PIXEL_FONT_SIZE = 16;
+        constexpr const char* DEFAULT_FONT_PATH = "FreeSans.ttf";
+        constexpr const char* PIXEL_FONT_PATH = "assets/fonts/PressStart2P-Regular.ttf";
+    }
+    
+    // Asset paths
+    namespace Assets {
+        constexpr const char* IMAGES_DIR = "assets/images/";
+        constexpr const char* MUSIC_DIR = "assets/music/";
+        constexpr const char* FONTS_DIR = "assets/fonts/";
+        
+        // Specific asset files
+        constexpr const char* LOGO_BMP = "assets/images/logo.bmp";
+        constexpr const char* LOGO_SMALL_BMP = "assets/images/logo_small.bmp";
+        constexpr const char* BACKGROUND_BMP = "assets/images/main_background.bmp";
+        constexpr const char* BLOCKS_BMP = "assets/images/2.png";
+    }
+    
+    // Audio settings
+    namespace Audio {
+        constexpr float DEFAULT_VOLUME = 1.0f;
+        constexpr float LETS_GO_VOLUME = 1.0f;
+        constexpr int MAX_MUSIC_TRACKS = 100;  // Maximum number of music files to scan
+    }
+    
+    // Input settings  
+    namespace Input {
+        constexpr int MOUSE_BUTTON_PRIMARY = SDL_BUTTON_LEFT;
+        constexpr Uint32 MODIFIER_SHIFT = SDL_KMOD_SHIFT;
+        constexpr Uint32 MODIFIER_CTRL = SDL_KMOD_CTRL;
+    }
+    
+    // Performance settings
+    namespace Performance {
+        constexpr float MIN_FRAME_TIME = 0.05f;  // Cap at 20 FPS minimum (prevent spiral of death)
+        constexpr int STARFIELD_PARTICLE_COUNT = 200;
+        constexpr int STARFIELD_3D_PARTICLE_COUNT = 200;
+    }
+
+    // Visual effects settings
+    namespace Visuals {
+        constexpr int PAUSE_BLUR_ITERATIONS = 8; // Number of blur passes (higher = more blur)
+        constexpr int PAUSE_BLUR_OFFSET = 3;     // Pixel spread of the blur
+        constexpr int PAUSE_BLUR_ALPHA = 40;     // Alpha intensity of blur layers
+    }
+}
diff --git a/src/core/GlobalState.cpp b/src/core/GlobalState.cpp
new file mode 100644
index 0000000..b5ad912
--- /dev/null
+++ b/src/core/GlobalState.cpp
@@ -0,0 +1,420 @@
+#include "GlobalState.h"
+#include "Config.h"
+#include <SDL3/SDL.h>
+#include <algorithm>
+#include <random>
+#include <cmath>
+
+namespace {
+constexpr float PI_F = 3.14159265358979323846f;
+
+float randRange(float minVal, float maxVal) {
+    return minVal + (static_cast<float>(rand()) / static_cast<float>(RAND_MAX)) * (maxVal - minVal);
+}
+
+SDL_Color randomFireworkColor() {
+    static const SDL_Color palette[] = {
+        {255, 120, 80, 255},
+        {255, 190, 60, 255},
+        {120, 210, 255, 255},
+        {170, 120, 255, 255},
+        {255, 90, 180, 255},
+        {120, 255, 170, 255},
+        {255, 255, 180, 255}
+    };
+    size_t idx = static_cast<size_t>(rand() % (sizeof(palette) / sizeof(palette[0])));
+    return palette[idx];
+}
+
+SDL_Color scaleColor(SDL_Color color, float factor, Uint8 alphaOverride = 0) {
+    auto clampChannel = [](float value) -> Uint8 {
+        return static_cast<Uint8>(std::max(0.0f, std::min(255.0f, std::round(value))));
+    };
+    SDL_Color result;
+    result.r = clampChannel(color.r * factor);
+    result.g = clampChannel(color.g * factor);
+    result.b = clampChannel(color.b * factor);
+    result.a = alphaOverride ? alphaOverride : color.a;
+    return result;
+}
+
+SDL_Color mixColors(SDL_Color a, SDL_Color b, float t) {
+    t = std::clamp(t, 0.0f, 1.0f);
+    auto lerpChannel = [t](Uint8 ca, Uint8 cb) -> Uint8 {
+        float blended = ca + (cb - ca) * t;
+        return static_cast<Uint8>(std::max(0.0f, std::min(255.0f, blended)));
+    };
+    SDL_Color result;
+    result.r = lerpChannel(a.r, b.r);
+    result.g = lerpChannel(a.g, b.g);
+    result.b = lerpChannel(a.b, b.b);
+    result.a = lerpChannel(a.a, b.a);
+    return result;
+}
+}
+
+GlobalState& GlobalState::instance() {
+    static GlobalState instance;
+    return instance;
+}
+
+void GlobalState::initialize() {
+    if (m_initialized) {
+        return;
+    }
+
+    // Initialize timing
+    lastMs = SDL_GetTicks();
+    loadStart = SDL_GetTicks();
+
+    // Initialize viewport to logical dimensions
+    logicalVP = {0, 0, Config::Logical::WIDTH, Config::Logical::HEIGHT};
+
+    // Initialize fireworks system
+    fireworks.clear();
+    lastFireworkTime = 0;
+
+    m_initialized = true;
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[GlobalState] Initialized");
+}
+
+void GlobalState::shutdown() {
+    if (!m_initialized) {
+        return;
+    }
+
+    // Clear fireworks
+    fireworks.clear();
+
+    m_initialized = false;
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[GlobalState] Shutdown complete");
+}
+
+namespace {
+using Firework = GlobalState::TetrisFirework;
+using BlockParticle = GlobalState::BlockParticle;
+using SparkParticle = GlobalState::SparkParticle;
+void spawnSparks(Firework& firework, float cx, float cy, SDL_Color baseColor, float speedBase) {
+    int sparkCount = 10 + (rand() % 10);
+    for (int i = 0; i < sparkCount; ++i) {
+        SparkParticle spark;
+        spark.x = cx;
+        spark.y = cy;
+        float angle = randRange(0.0f, PI_F * 2.0f);
+        float speed = speedBase * randRange(1.05f, 1.6f);
+        spark.vx = std::cos(angle) * speed;
+        spark.vy = std::sin(angle) * speed - randRange(30.0f, 90.0f);
+        spark.life = 0.0f;
+        spark.maxLife = 260.0f + randRange(0.0f, 200.0f);
+        spark.thickness = randRange(0.8f, 2.2f);
+        spark.color = scaleColor(baseColor, randRange(0.85f, 1.2f), 255);
+        firework.sparks.push_back(spark);
+    }
+}
+
+void triggerFireworkBurst(Firework& firework, int burstIndex) {
+    SDL_Color burstColor = firework.burstColors[burstIndex % firework.burstColors.size()];
+    float centerX = firework.originX + randRange(-30.0f, 30.0f);
+    float centerY = firework.originY - burstIndex * randRange(14.0f, 24.0f) + randRange(-10.0f, 10.0f);
+    int particleCount = 22 + (rand() % 16);
+    float speedBase = 90.0f + burstIndex * 40.0f;
+
+    for (int i = 0; i < particleCount; ++i) {
+        BlockParticle particle;
+        particle.x = centerX;
+        particle.y = centerY;
+        float angle = randRange(0.0f, PI_F * 2.0f);
+        float speed = speedBase + randRange(-20.0f, 70.0f);
+        particle.vx = std::cos(angle) * speed;
+        particle.vy = std::sin(angle) * speed - randRange(35.0f, 95.0f);
+        particle.maxLife = 950.0f + randRange(0.0f, 420.0f) + burstIndex * 220.0f;
+        particle.life = particle.maxLife;
+        particle.crackle = (rand() % 100) < 75;
+        particle.flickerSeed = randRange(0.0f, PI_F * 2.0f);
+        if (particle.crackle) {
+            particle.size = randRange(1.4f, 3.2f);
+        } else {
+            particle.size = 3.2f + randRange(0.0f, 2.6f) + burstIndex * 0.6f;
+        }
+        particle.color = scaleColor(burstColor, randRange(0.85f, 1.2f));
+        particle.dualColor = (rand() % 100) < 55;
+        if (particle.dualColor) {
+            SDL_Color alt = randomFireworkColor();
+            float luminanceDiff = std::abs(static_cast<float>(alt.r + alt.g + alt.b) - (particle.color.r + particle.color.g + particle.color.b));
+            if (luminanceDiff < 40.0f) {
+                alt = scaleColor(particle.color, randRange(0.6f, 1.4f));
+            }
+            particle.accentColor = alt;
+            particle.colorBlendSpeed = randRange(0.6f, 1.4f);
+        } else {
+            particle.accentColor = particle.color;
+            particle.colorBlendSpeed = 1.0f;
+        }
+        firework.particles.push_back(particle);
+    }
+
+    spawnSparks(firework, centerX, centerY, burstColor, speedBase);
+}
+}
+
+void GlobalState::updateFireworks(double frameMs) {
+    if (frameMs <= 0.0) {
+        frameMs = 16.0;
+    }
+
+    const Uint64 currentTime = SDL_GetTicks();
+    size_t activeCount = 0;
+    for (const auto& fw : fireworks) {
+        if (fw.active) {
+            ++activeCount;
+        }
+    }
+
+    constexpr size_t MAX_SIMULTANEOUS_FIREWORKS = 2;
+    bool canSpawnNew = activeCount < MAX_SIMULTANEOUS_FIREWORKS;
+    bool spawnedFirework = false;
+
+    if (canSpawnNew) {
+        Uint64 interval = 1300 + static_cast<Uint64>(rand() % 1400);
+        if (currentTime - lastFireworkTime > interval) {
+            float x = Config::Logical::WIDTH * (0.15f + randRange(0.0f, 0.70f));
+            float y = Config::Logical::HEIGHT * (0.18f + randRange(0.0f, 0.40f));
+            createFirework(x, y);
+            lastFireworkTime = currentTime;
+            lastFireworkX = x;
+            lastFireworkY = y;
+            pendingStaggerFirework = (rand() % 100) < 65;
+            if (pendingStaggerFirework) {
+                nextStaggerFireworkTime = currentTime + 250 + static_cast<Uint64>(rand() % 420);
+            }
+            spawnedFirework = true;
+        }
+    }
+
+    if (!spawnedFirework && pendingStaggerFirework && canSpawnNew && currentTime >= nextStaggerFireworkTime) {
+        float x = lastFireworkX + randRange(-140.0f, 140.0f);
+        float y = lastFireworkY + randRange(-80.0f, 50.0f);
+        x = std::clamp(x, Config::Logical::WIDTH * 0.10f, Config::Logical::WIDTH * 0.90f);
+        y = std::clamp(y, Config::Logical::HEIGHT * 0.15f, Config::Logical::HEIGHT * 0.70f);
+        createFirework(x, y);
+        lastFireworkTime = currentTime;
+        lastFireworkX = x;
+        lastFireworkY = y;
+        pendingStaggerFirework = false;
+        spawnedFirework = true;
+    }
+
+    const float dtSeconds = static_cast<float>(frameMs / 1000.0);
+    const float deltaMs = static_cast<float>(frameMs);
+
+    for (auto& firework : fireworks) {
+        if (!firework.active) {
+            continue;
+        }
+
+        firework.elapsedMs += deltaMs;
+        while (firework.nextBurst < static_cast<int>(firework.burstSchedule.size()) &&
+               firework.elapsedMs >= firework.burstSchedule[firework.nextBurst]) {
+            triggerFireworkBurst(firework, firework.nextBurst);
+            firework.nextBurst++;
+        }
+
+        for (auto it = firework.particles.begin(); it != firework.particles.end();) {
+            it->life -= deltaMs;
+            if (it->life <= 0.0f) {
+                it = firework.particles.erase(it);
+                continue;
+            }
+            it->x += it->vx * dtSeconds;
+            it->y += it->vy * dtSeconds;
+            it->vx *= 0.986f;
+            it->vy = it->vy * 0.972f + 70.0f * dtSeconds;
+            ++it;
+        }
+
+        for (auto it = firework.sparks.begin(); it != firework.sparks.end();) {
+            it->life += deltaMs;
+            if (it->life >= it->maxLife) {
+                it = firework.sparks.erase(it);
+                continue;
+            }
+            it->x += it->vx * dtSeconds;
+            it->y += it->vy * dtSeconds;
+            it->vx *= 0.992f;
+            it->vy = it->vy * 0.965f + 120.0f * dtSeconds;
+            ++it;
+        }
+
+        bool pendingBursts = firework.nextBurst < static_cast<int>(firework.burstSchedule.size());
+        firework.active = pendingBursts || !firework.particles.empty() || !firework.sparks.empty();
+    }
+}
+
+void GlobalState::createFirework(float x, float y) {
+    // Find an inactive firework to reuse
+    TetrisFirework* firework = nullptr;
+    for (auto& fw : fireworks) {
+        if (!fw.active) {
+            firework = &fw;
+            break;
+        }
+    }
+
+    // If no inactive firework found, create a new one
+    if (!firework) {
+        fireworks.emplace_back();
+        firework = &fireworks.back();
+    }
+
+    firework->active = true;
+    firework->particles.clear();
+    firework->sparks.clear();
+    firework->originX = x;
+    firework->originY = y;
+    firework->elapsedMs = 0.0f;
+    firework->nextBurst = 0;
+    firework->burstSchedule = {
+        0.0f,
+        220.0f + randRange(0.0f, 160.0f),
+        420.0f + randRange(0.0f, 260.0f)
+    };
+
+    SDL_Color baseColor = randomFireworkColor();
+    for (int i = 0; i < 3; ++i) {
+        float wobble = randRange(-0.08f, 0.08f);
+        firework->burstColors[i] = scaleColor(baseColor, 1.0f - i * 0.12f + wobble, 255);
+    }
+}
+
+void GlobalState::drawFireworks(SDL_Renderer* renderer, SDL_Texture* blocksTex) {
+    (void)blocksTex;
+
+    auto renderCircle = [renderer](float cx, float cy, float radius) {
+        int ir = static_cast<int>(std::ceil(radius));
+        for (int dy = -ir; dy <= ir; ++dy) {
+            float row = std::sqrt(std::max(0.0f, radius * radius - static_cast<float>(dy * dy)));
+            SDL_FRect line{cx - row, cy + dy, row * 2.0f, 1.0f};
+            SDL_RenderFillRect(renderer, &line);
+        }
+    };
+
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_ADD);
+    for (const auto& firework : fireworks) {
+        if (!firework.active) continue;
+
+        for (const auto& spark : firework.sparks) {
+            if (spark.life >= spark.maxLife) continue;
+            float progress = spark.life / spark.maxLife;
+            Uint8 alpha = static_cast<Uint8>((1.0f - progress) * 255.0f);
+            if (alpha == 0) continue;
+            SDL_SetRenderDrawColor(renderer, spark.color.r, spark.color.g, spark.color.b, alpha);
+            float trailScale = 0.015f * spark.thickness;
+            float tailX = spark.x - spark.vx * trailScale;
+            float tailY = spark.y - spark.vy * trailScale;
+            SDL_RenderLine(renderer,
+                           static_cast<int>(spark.x),
+                           static_cast<int>(spark.y),
+                           static_cast<int>(tailX),
+                           static_cast<int>(tailY));
+        }
+    }
+
+    auto sampleParticleColor = [](const BlockParticle& particle) -> SDL_Color {
+        if (!particle.dualColor) {
+            return particle.color;
+        }
+        float elapsed = particle.maxLife - particle.life;
+        float phase = particle.flickerSeed * 1.8f + elapsed * 0.0025f * particle.colorBlendSpeed;
+        float mixFactor = 0.5f + 0.5f * std::sin(phase);
+        return mixColors(particle.color, particle.accentColor, mixFactor);
+    };
+
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+    for (const auto& firework : fireworks) {
+        if (!firework.active) continue;
+
+        for (const auto& particle : firework.particles) {
+            if (particle.life <= 0.0f) continue;
+            float lifeRatio = particle.life / particle.maxLife;
+            float alphaF = std::pow(std::max(0.0f, lifeRatio), 0.75f);
+            if (particle.crackle) {
+                SDL_Color dynamicColor = sampleParticleColor(particle);
+                float flicker = 0.55f + 0.45f * std::sin(particle.flickerSeed + particle.life * 0.018f);
+                Uint8 alpha = static_cast<Uint8>(alphaF * flicker * 255.0f);
+                if (alpha == 0) continue;
+                SDL_SetRenderDrawColor(renderer, dynamicColor.r, dynamicColor.g, dynamicColor.b, alpha);
+                float stretch = particle.size * (2.5f + (1.0f - lifeRatio) * 1.3f);
+                float angle = particle.flickerSeed * 3.0f + particle.life * 0.004f;
+                float dx = std::cos(angle) * stretch;
+                float dy = std::sin(angle) * stretch * 0.7f;
+                SDL_RenderLine(renderer,
+                               static_cast<int>(particle.x - dx),
+                               static_cast<int>(particle.y - dy),
+                               static_cast<int>(particle.x + dx),
+                               static_cast<int>(particle.y + dy));
+                SDL_RenderLine(renderer,
+                               static_cast<int>(particle.x - dy * 0.45f),
+                               static_cast<int>(particle.y + dx * 0.45f),
+                               static_cast<int>(particle.x + dy * 0.45f),
+                               static_cast<int>(particle.y - dx * 0.45f));
+            } else {
+                SDL_Color dynamicColor = sampleParticleColor(particle);
+                Uint8 alpha = static_cast<Uint8>(alphaF * 255.0f);
+                SDL_SetRenderDrawColor(renderer, dynamicColor.r, dynamicColor.g, dynamicColor.b, alpha);
+                float radius = particle.size * (0.5f + 0.3f * lifeRatio);
+                renderCircle(particle.x, particle.y, radius);
+            }
+        }
+    }
+
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+}
+
+void GlobalState::resetGameState() {
+    // Reset game-related state
+    leftHeld = false;
+    rightHeld = false;
+    moveTimerMs = 0.0;
+    startLevelSelection = 0;
+}
+
+void GlobalState::resetUIState() {
+    // Reset UI state
+    showSettingsPopup = false;
+    showExitConfirmPopup = false;
+    hoveredButton = -1;
+}
+
+void GlobalState::resetAnimationState() {
+    // Reset animation state
+    logoAnimCounter = 0.0;
+    fireworks.clear();
+    lastFireworkTime = 0;
+}
+
+void GlobalState::updateLogicalDimensions(int windowWidth, int windowHeight) {
+    // For now, keep logical dimensions proportional to window size
+    // You can adjust this logic based on your specific needs
+    
+    // Option 1: Keep fixed aspect ratio and scale uniformly
+    const float targetAspect = static_cast<float>(Config::Logical::WIDTH) / static_cast<float>(Config::Logical::HEIGHT);
+    const float windowAspect = static_cast<float>(windowWidth) / static_cast<float>(windowHeight);
+    
+    if (windowAspect > targetAspect) {
+        // Window is wider than target aspect - fit to height
+        currentLogicalHeight = Config::Logical::HEIGHT;
+        currentLogicalWidth = static_cast<int>(currentLogicalHeight * windowAspect);
+    } else {
+        // Window is taller than target aspect - fit to width  
+        currentLogicalWidth = Config::Logical::WIDTH;
+        currentLogicalHeight = static_cast<int>(currentLogicalWidth / windowAspect);
+    }
+    
+    // Ensure minimum sizes
+    currentLogicalWidth = std::max(currentLogicalWidth, 800);
+    currentLogicalHeight = std::max(currentLogicalHeight, 600);
+    
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, 
+        "[GlobalState] Updated logical dimensions: %dx%d (window: %dx%d)", 
+        currentLogicalWidth, currentLogicalHeight, windowWidth, windowHeight);
+}
diff --git a/src/core/GlobalState.h b/src/core/GlobalState.h
new file mode 100644
index 0000000..d3df436
--- /dev/null
+++ b/src/core/GlobalState.h
@@ -0,0 +1,158 @@
+#pragma once
+
+#include <vector>
+#include <array>
+#include <memory>
+#include <SDL3/SDL.h>
+
+// Forward declarations
+class FontAtlas;
+class Game;
+class ScoreManager;
+class Starfield;
+class Starfield3D;
+class LineEffect;
+
+/**
+ * GlobalState - Centralized management of application-wide state
+ * 
+ * Replaces global variables scattered throughout main.cpp
+ * Provides controlled access to shared state between systems
+ * Will eventually be replaced by proper dependency injection
+ */
+class GlobalState {
+public:
+    // Singleton access (temporary until dependency injection is implemented)
+    static GlobalState& instance();
+
+    // Initialization and cleanup
+    void initialize();
+    void shutdown();
+
+    // Application state flags
+    bool running = true;
+    bool isFullscreen = false;
+    bool musicEnabled = true;
+    bool musicStarted = false;
+    bool musicLoaded = false;
+
+    // UI state flags
+    bool showSettingsPopup = false;
+    bool showExitConfirmPopup = false;
+    int hoveredButton = -1;  // -1 = none, 0 = play, 1 = level, 2 = settings
+
+    // Input state (will be migrated to InputManager)
+    bool leftHeld = false;
+    bool rightHeld = false;
+    double moveTimerMs = 0.0;
+
+    // Loading state
+    double loadingProgress = 0.0;
+    int currentTrackLoading = 0;
+    int totalTracks = 0;
+    int startLevelSelection = 0;
+
+    // Timing
+    Uint64 lastMs = 0;
+    Uint64 loadStart = 0;
+
+    // Animation state
+    double logoAnimCounter = 0.0;
+
+    // Level background caching
+    int cachedLevel = -1;
+    float levelFadeAlpha = 0.0f;
+    float levelFadeElapsed = 0.0f;
+
+    // Viewport and scaling
+    SDL_Rect logicalVP{0, 0, 1200, 1000};  // Will use Config::Logical constants
+    float logicalScale = 1.0f;
+    
+    // Dynamic logical dimensions (computed from window size)
+    int currentLogicalWidth = 1200;
+    int currentLogicalHeight = 1000;
+
+    // Fireworks system (for menu animation)
+    struct BlockParticle {
+        float x = 0.0f;
+        float y = 0.0f;
+        float vx = 0.0f;
+        float vy = 0.0f;
+        float size = 0.0f;
+        float life = 0.0f;
+        float maxLife = 0.0f;
+        SDL_Color color{255, 255, 255, 255};
+        SDL_Color accentColor{255, 255, 255, 255};
+        int generation = 0;
+        bool hasExploded = false;
+        bool crackle = false;
+        float flickerSeed = 0.0f;
+        bool dualColor = false;
+        float colorBlendSpeed = 0.0f;
+    };
+
+    struct SparkParticle {
+        float x = 0.0f;
+        float y = 0.0f;
+        float vx = 0.0f;
+        float vy = 0.0f;
+        float life = 0.0f;
+        float maxLife = 0.0f;
+        float thickness = 1.0f;
+        SDL_Color color{255, 255, 255, 255};
+    };
+
+    struct TetrisFirework {
+        std::vector<BlockParticle> particles;
+        std::vector<SparkParticle> sparks;
+        bool active = false;
+        float originX = 0.0f;
+        float originY = 0.0f;
+        float elapsedMs = 0.0f;
+        int nextBurst = 0;
+        std::array<float, 3> burstSchedule{0.0f, 250.0f, 520.0f};
+        std::array<SDL_Color, 3> burstColors{};
+    };
+
+    std::vector<TetrisFirework> fireworks;
+    Uint64 lastFireworkTime = 0;
+    bool pendingStaggerFirework = false;
+    Uint64 nextStaggerFireworkTime = 0;
+    float lastFireworkX = 0.0f;
+    float lastFireworkY = 0.0f;
+
+    // Fireworks management methods
+    void updateFireworks(double frameMs);
+    void createFirework(float x, float y);
+    void drawFireworks(SDL_Renderer* renderer, SDL_Texture* blocksTex);
+
+    // Logical dimensions management
+    void updateLogicalDimensions(int windowWidth, int windowHeight);
+    int getLogicalWidth() const { return currentLogicalWidth; }
+    int getLogicalHeight() const { return currentLogicalHeight; }
+
+    // Reset methods for different states
+    void resetGameState();
+    void resetUIState();
+    void resetAnimationState();
+
+private:
+    GlobalState() = default;
+    ~GlobalState() = default;
+    GlobalState(const GlobalState&) = delete;
+    GlobalState& operator=(const GlobalState&) = delete;
+
+    bool m_initialized = false;
+};
+
+// Convenience accessors (temporary until proper dependency injection)
+namespace Globals {
+    inline GlobalState& state() { return GlobalState::instance(); }
+    
+    // Quick access to commonly used flags
+    inline bool& running() { return state().running; }
+    inline bool& musicEnabled() { return state().musicEnabled; }
+    inline bool& showSettingsPopup() { return state().showSettingsPopup; }
+    inline int& hoveredButton() { return state().hoveredButton; }
+    inline double& logoAnimCounter() { return state().logoAnimCounter; }
+}
diff --git a/src/core/GravityManager.cpp b/src/core/GravityManager.cpp
index 7bfc238..e3b10b1 100644
--- a/src/core/GravityManager.cpp
+++ b/src/core/GravityManager.cpp
@@ -14,19 +14,19 @@ double GravityManager::getGlobalMultiplier() const { return globalMultiplier; }
 
 void GravityManager::setLevelMultiplier(int level, double m) {
     if (level < 0) return;
-    int idx = level >= 29 ? 29 : level;
+    int idx = level >= 19 ? 19 : level;
     levelMultipliers[idx] = std::clamp(m, 0.01, 100.0);
 }
 
 double GravityManager::getLevelMultiplier(int level) const {
-    int idx = level < 0 ? 0 : (level >= 29 ? 29 : level);
+    int idx = level < 0 ? 0 : (level >= 19 ? 19 : level);
     return levelMultipliers[idx];
 }
 
 double GravityManager::getMsForLevel(int level) const {
-    int idx = level < 0 ? 0 : (level >= 29 ? 29 : level);
-    double frames = static_cast<double>(FRAMES_TABLE[idx]) * levelMultipliers[idx];
-    double result = frames * FRAME_MS * globalMultiplier;
+    int idx = level < 0 ? 0 : (level >= 19 ? 19 : level);
+    double baseMs = LEVEL_SPEEDS_MS[idx];
+    double result = baseMs * levelMultipliers[idx] * globalMultiplier;
     return std::max(1.0, result);
 }
 
diff --git a/src/core/GravityManager.h b/src/core/GravityManager.h
index a2c05e8..e75d767 100644
--- a/src/core/GravityManager.h
+++ b/src/core/GravityManager.h
@@ -18,14 +18,11 @@ public:
     double getFpsForLevel(int level) const;
 
 private:
-    static constexpr double NES_FPS = 60.0988;
-    static constexpr double FRAME_MS = 1000.0 / NES_FPS;
-    static constexpr int FRAMES_TABLE[30] = {
-        48,43,38,33,28,23,18,13,8,6,
-        5,5,5,4,4,4,3,3,3,2,
-        2,2,2,2,2,2,2,2,2,1
+    static constexpr double LEVEL_SPEEDS_MS[20] = {
+        1000.0, 920.0, 840.0, 760.0, 680.0, 600.0, 520.0, 440.0, 360.0, 280.0,
+        200.0,  160.0, 160.0, 120.0, 120.0, 100.0, 100.0, 80.0,  80.0,  60.0
     };
 
     double globalMultiplier{1.0};
-    std::array<double,30> levelMultipliers{}; // default 1.0
+    std::array<double,20> levelMultipliers{}; // default 1.0
 };
diff --git a/src/core/ServiceContainer.h b/src/core/ServiceContainer.h
new file mode 100644
index 0000000..4809487
--- /dev/null
+++ b/src/core/ServiceContainer.h
@@ -0,0 +1,92 @@
+#pragma once
+
+#include <memory>
+#include <unordered_map>
+#include <typeindex>
+#include <stdexcept>
+
+/**
+ * @brief Dependency injection container for managing services
+ * 
+ * Provides a centralized way to register and retrieve services,
+ * enabling loose coupling and better testability.
+ */
+class ServiceContainer {
+private:
+    std::unordered_map<std::type_index, std::shared_ptr<void>> services_;
+    
+public:
+    /**
+     * @brief Register a service instance
+     * @tparam T Service type
+     * @param service Shared pointer to service instance
+     */
+    template<typename T>
+    void registerService(std::shared_ptr<T> service) {
+        services_[std::type_index(typeid(T))] = service;
+    }
+    
+    /**
+     * @brief Get a service instance
+     * @tparam T Service type
+     * @return Shared pointer to service instance
+     * @throws std::runtime_error if service is not registered
+     */
+    template<typename T>
+    std::shared_ptr<T> getService() {
+        auto it = services_.find(std::type_index(typeid(T)));
+        if (it != services_.end()) {
+            return std::static_pointer_cast<T>(it->second);
+        }
+        throw std::runtime_error("Service not registered: " + std::string(typeid(T).name()));
+    }
+    
+    /**
+     * @brief Get a service instance (const version)
+     * @tparam T Service type
+     * @return Shared pointer to service instance
+     * @throws std::runtime_error if service is not registered
+     */
+    template<typename T>
+    std::shared_ptr<const T> getService() const {
+        auto it = services_.find(std::type_index(typeid(T)));
+        if (it != services_.end()) {
+            return std::static_pointer_cast<const T>(it->second);
+        }
+        throw std::runtime_error("Service not registered: " + std::string(typeid(T).name()));
+    }
+    
+    /**
+     * @brief Check if a service is registered
+     * @tparam T Service type
+     * @return true if service is registered, false otherwise
+     */
+    template<typename T>
+    bool hasService() const {
+        return services_.find(std::type_index(typeid(T))) != services_.end();
+    }
+    
+    /**
+     * @brief Unregister a service
+     * @tparam T Service type
+     */
+    template<typename T>
+    void unregisterService() {
+        services_.erase(std::type_index(typeid(T)));
+    }
+    
+    /**
+     * @brief Clear all registered services
+     */
+    void clear() {
+        services_.clear();
+    }
+    
+    /**
+     * @brief Get the number of registered services
+     * @return Number of registered services
+     */
+    size_t getServiceCount() const {
+        return services_.size();
+    }
+};
diff --git a/src/core/Settings.cpp b/src/core/Settings.cpp
new file mode 100644
index 0000000..3982a4f
--- /dev/null
+++ b/src/core/Settings.cpp
@@ -0,0 +1,126 @@
+#include "Settings.h"
+#include <fstream>
+#include <sstream>
+#include <SDL3/SDL.h>
+
+// Singleton instance
+Settings& Settings::instance() {
+    static Settings s_instance;
+    return s_instance;
+}
+
+Settings::Settings() {
+    // Constructor - defaults already set in header
+}
+
+std::string Settings::getSettingsPath() {
+    // Save settings.ini in the game's directory
+    return "settings.ini";
+}
+
+bool Settings::load() {
+    std::ifstream file(getSettingsPath());
+    if (!file.is_open()) {
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Settings file not found, using defaults. Creating settings file with defaults.");
+        // Persist defaults so next run has an explicit settings.ini
+        try {
+            save();
+        } catch (...) {}
+        return false;
+    }
+    
+    std::string line;
+    std::string currentSection;
+    
+    while (std::getline(file, line)) {
+        // Trim whitespace
+        size_t start = line.find_first_not_of(" \t\r\n");
+        size_t end = line.find_last_not_of(" \t\r\n");
+        if (start == std::string::npos) continue; // Empty line
+        line = line.substr(start, end - start + 1);
+        
+        // Skip comments
+        if (line[0] == ';' || line[0] == '#') continue;
+        
+        // Check for section header
+        if (line[0] == '[' && line[line.length() - 1] == ']') {
+            currentSection = line.substr(1, line.length() - 2);
+            continue;
+        }
+        
+        // Parse key=value
+        size_t equalsPos = line.find('=');
+        if (equalsPos == std::string::npos) continue;
+        
+        std::string key = line.substr(0, equalsPos);
+        std::string value = line.substr(equalsPos + 1);
+        
+        // Trim key and value
+        key.erase(key.find_last_not_of(" \t") + 1);
+        value.erase(0, value.find_first_not_of(" \t"));
+        
+        // Parse settings
+        if (currentSection == "Display") {
+            if (key == "Fullscreen") {
+                m_fullscreen = (value == "1" || value == "true" || value == "True");
+            }
+        } else if (currentSection == "Audio") {
+            if (key == "Music") {
+                m_musicEnabled = (value == "1" || value == "true" || value == "True");
+            } else if (key == "Sound") {
+                m_soundEnabled = (value == "1" || value == "true" || value == "True");
+            }
+        } else if (currentSection == "Gameplay") {
+            if (key == "SmoothScroll") {
+                m_smoothScrollEnabled = (value == "1" || value == "true" || value == "True");
+                } else if (key == "UpRotateClockwise") {
+                    m_upRotateClockwise = (value == "1" || value == "true" || value == "True");
+            }
+        } else if (currentSection == "Player") {
+            if (key == "Name") {
+                m_playerName = value;
+            }
+        } else if (currentSection == "Debug") {
+            if (key == "Enabled") {
+                m_debugEnabled = (value == "1" || value == "true" || value == "True");
+            }
+        }
+    }
+    
+    file.close();
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Settings loaded from %s", getSettingsPath().c_str());
+    return true;
+}
+
+bool Settings::save() {
+    std::ofstream file(getSettingsPath());
+    if (!file.is_open()) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to save settings to %s", getSettingsPath().c_str());
+        return false;
+    }
+    
+    // Write settings in INI format
+    file << "; Tetris Game Settings\n";
+    file << "; This file is auto-generated\n\n";
+    
+    file << "[Display]\n";
+    file << "Fullscreen=" << (m_fullscreen ? "1" : "0") << "\n\n";
+    
+    file << "[Audio]\n";
+    file << "Music=" << (m_musicEnabled ? "1" : "0") << "\n";
+    file << "Sound=" << (m_soundEnabled ? "1" : "0") << "\n\n";
+    
+    file << "[Gameplay]\n";
+    file << "SmoothScroll=" << (m_smoothScrollEnabled ? "1" : "0") << "\n\n";
+    file << "UpRotateClockwise=" << (m_upRotateClockwise ? "1" : "0") << "\n\n";
+
+    file << "[Player]\n";
+    file << "Name=" << m_playerName << "\n\n";
+    
+    file << "[Debug]\n";
+    file << "Enabled=" << (m_debugEnabled ? "1" : "0") << "\n";
+    
+    file.close();
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Settings saved to %s", getSettingsPath().c_str());
+    return true;
+}
diff --git a/src/core/Settings.h b/src/core/Settings.h
new file mode 100644
index 0000000..6e158a4
--- /dev/null
+++ b/src/core/Settings.h
@@ -0,0 +1,60 @@
+#pragma once
+#include <string>
+
+/**
+ * Settings - Persistent game settings manager
+ * Handles loading/saving settings to settings.ini
+ */
+class Settings {
+public:
+    // Singleton access
+    static Settings& instance();
+    
+    // Load settings from file (returns true if file existed)
+    bool load();
+    
+    // Save settings to file
+    bool save();
+    
+    // Settings accessors
+    bool isFullscreen() const { return m_fullscreen; }
+    void setFullscreen(bool value) { m_fullscreen = value; }
+    
+    bool isMusicEnabled() const { return m_musicEnabled; }
+    void setMusicEnabled(bool value) { m_musicEnabled = value; }
+    
+    bool isSoundEnabled() const { return m_soundEnabled; }
+    void setSoundEnabled(bool value) { m_soundEnabled = value; }
+    
+    bool isDebugEnabled() const { return m_debugEnabled; }
+    void setDebugEnabled(bool value) { m_debugEnabled = value; }
+
+    bool isSmoothScrollEnabled() const { return m_smoothScrollEnabled; }
+    void setSmoothScrollEnabled(bool value) { m_smoothScrollEnabled = value; }
+
+    // Rotation behavior: should pressing UP rotate clockwise? (true = clockwise)
+    bool isUpRotateClockwise() const { return m_upRotateClockwise; }
+    void setUpRotateClockwise(bool value) { m_upRotateClockwise = value; }
+    
+    const std::string& getPlayerName() const { return m_playerName; }
+    void setPlayerName(const std::string& name) { m_playerName = name; }
+    
+    // Get the settings file path
+    static std::string getSettingsPath();
+
+private:
+    Settings(); // Private constructor for singleton
+    Settings(const Settings&) = delete;
+    Settings& operator=(const Settings&) = delete;
+    
+    // Settings values
+    // Default to fullscreen on first run when no settings.ini exists
+    bool m_fullscreen = true;
+    bool m_musicEnabled = true;
+    bool m_soundEnabled = true;
+    bool m_debugEnabled = false;
+    bool m_smoothScrollEnabled = true;
+    std::string m_playerName = "Player";
+    // Default: UP rotates clockwise
+    bool m_upRotateClockwise = true;
+};
diff --git a/src/core/StateManager.cpp b/src/core/StateManager.cpp
deleted file mode 100644
index cfb0fee..0000000
--- a/src/core/StateManager.cpp
+++ /dev/null
@@ -1,46 +0,0 @@
-#include "StateManager.h"
-
-StateManager::StateManager(AppState initial)
-    : currentState(initial)
-{
-}
-
-void StateManager::registerHandler(AppState s, EventHandler h) {
-    handlers[static_cast<int>(s)].push_back(std::move(h));
-}
-
-void StateManager::registerOnEnter(AppState s, Hook h) {
-    onEnter[static_cast<int>(s)].push_back(std::move(h));
-}
-
-void StateManager::registerOnExit(AppState s, Hook h) {
-    onExit[static_cast<int>(s)].push_back(std::move(h));
-}
-
-// Overload accepting a no-arg function as handler (wraps it into an EventHandler)
-void StateManager::registerHandler(AppState s, std::function<void()> h) {
-    EventHandler wrapper = [h = std::move(h)](const SDL_Event&) { h(); };
-    registerHandler(s, std::move(wrapper));
-}
-
-void StateManager::setState(AppState s) {
-    if (s == currentState) return;
-    // call exit hooks for current
-    auto it = onExit.find(static_cast<int>(currentState));
-    if (it != onExit.end()) {
-        for (auto &h : it->second) h();
-    }
-    currentState = s;
-    auto it2 = onEnter.find(static_cast<int>(currentState));
-    if (it2 != onEnter.end()) {
-        for (auto &h : it2->second) h();
-    }
-}
-
-AppState StateManager::getState() const { return currentState; }
-
-void StateManager::handleEvent(const SDL_Event& e) {
-    auto it = handlers.find(static_cast<int>(currentState));
-    if (it == handlers.end()) return;
-    for (auto &h : it->second) h(e);
-}
diff --git a/src/core/StateManager.h b/src/core/StateManager.h
deleted file mode 100644
index 8f9bcf1..0000000
--- a/src/core/StateManager.h
+++ /dev/null
@@ -1,41 +0,0 @@
-#pragma once
-
-#include <functional>
-#include <unordered_map>
-#include <vector>
-#include <SDL3/SDL.h>
-
-// Application states used across the app
-enum class AppState {
-    Loading,
-    Menu,
-    Playing,
-    LevelSelect,
-    GameOver
-};
-
-// State manager used by main to route events and lifecycle hooks
-class StateManager {
-public:
-    using EventHandler = std::function<void(const SDL_Event&)>;
-    using Hook = std::function<void()>;
-
-    StateManager(AppState initial);
-
-    void registerHandler(AppState s, EventHandler h);
-    void registerOnEnter(AppState s, Hook h);
-    void registerOnExit(AppState s, Hook h);
-
-    void registerHandler(AppState s, std::function<void()> h); // overload used in some places
-
-    void setState(AppState s);
-    AppState getState() const;
-
-    void handleEvent(const SDL_Event& e);
-
-private:
-    AppState currentState;
-    std::unordered_map<int, std::vector<EventHandler>> handlers;
-    std::unordered_map<int, std::vector<Hook>> onEnter;
-    std::unordered_map<int, std::vector<Hook>> onExit;
-};
diff --git a/src/core/application/ApplicationManager.cpp b/src/core/application/ApplicationManager.cpp
new file mode 100644
index 0000000..9e4da60
--- /dev/null
+++ b/src/core/application/ApplicationManager.cpp
@@ -0,0 +1,1681 @@
+#include "ApplicationManager.h"
+#include "../state/StateManager.h"
+#include "../input/InputManager.h"
+#include "../interfaces/IAudioSystem.h"
+#include "../interfaces/IRenderer.h"
+#include "../interfaces/IAssetLoader.h"
+#include "../interfaces/IInputHandler.h"
+#include <filesystem>
+#include "../../audio/Audio.h"
+#include "../../audio/SoundEffect.h"
+#include "../../persistence/Scores.h"
+#include "../../states/State.h"
+#include "../../states/LoadingState.h"
+#include "../../states/MenuState.h"
+#include "../../states/OptionsState.h"
+#include "../../states/LevelSelectorState.h"
+#include "../../states/PlayingState.h"
+#include "../assets/AssetManager.h"
+#include "../Config.h"
+#include "../GlobalState.h"
+#include "../../graphics/renderers/RenderManager.h"
+#include "../../graphics/ui/Font.h"
+#include "../../graphics/ui/HelpOverlay.h"
+#include "../../graphics/effects/Starfield3D.h"
+#include "../../graphics/effects/Starfield.h"
+#include "../../graphics/renderers/GameRenderer.h"
+#include "../../gameplay/core/Game.h"
+#include "../../gameplay/coop/CoopGame.h"
+#include "../../gameplay/effects/LineEffect.h"
+#include <SDL3/SDL.h>
+#include <SDL3_image/SDL_image.h>
+#include <SDL3_ttf/SDL_ttf.h>
+#include "../../utils/ImagePathResolver.h"
+#include <iostream>
+#include "../../video/VideoPlayer.h"
+#include <cmath>
+#include <fstream>
+#include <algorithm>
+#ifdef _WIN32
+#define WIN32_LEAN_AND_MEAN
+#ifndef NOMINMAX
+#define NOMINMAX
+#endif
+#include <windows.h>
+#include <shellapi.h>
+#endif
+// (Intro video playback is now handled in-process via VideoPlayer)
+
+ApplicationManager::ApplicationManager() = default;
+
+static void traceFile(const char* msg) {
+    std::ofstream f("spacetris_trace.log", std::ios::app);
+    if (f) f << msg << "\n";
+}
+
+// Helper: extracted from inline lambda to avoid MSVC parsing issues with complex lambdas
+void ApplicationManager::renderLoading(ApplicationManager* app, RenderManager& renderer) {
+    // Clear background first
+    renderer.clear(0, 0, 0, 255);
+
+    // Use 3D starfield for loading screen (full screen)
+    if (app->m_starfield3D) {
+        int winW_actual = 0, winH_actual = 0;
+        if (app->m_renderManager) app->m_renderManager->getWindowSize(winW_actual, winH_actual);
+        if (winW_actual > 0 && winH_actual > 0) app->m_starfield3D->resize(winW_actual, winH_actual);
+        app->m_starfield3D->draw(renderer.getSDLRenderer());
+    }
+    // If intro video is playing, render it instead of the loading UI
+    if (app->m_introStarted && app->m_videoPlayer) {
+        SDL_Renderer* sdlR = renderer.getSDLRenderer();
+        int winW=0, winH=0; renderer.getWindowSize(winW, winH);
+        app->m_videoPlayer->render(sdlR, winW, winH);
+        SDL_SetRenderViewport(renderer.getSDLRenderer(), nullptr);
+        SDL_SetRenderScale(renderer.getSDLRenderer(), 1.0f, 1.0f);
+        return;
+    }
+    SDL_Rect logicalVP = {0,0,0,0};
+    float logicalScale = 1.0f;
+    if (app->m_renderManager) {
+        logicalVP = app->m_renderManager->getLogicalViewport();
+        logicalScale = app->m_renderManager->getLogicalScale();
+    }
+    SDL_SetRenderViewport(renderer.getSDLRenderer(), &logicalVP);
+    SDL_SetRenderScale(renderer.getSDLRenderer(), logicalScale, logicalScale);
+
+    float contentOffsetX = 0.0f;
+    float contentOffsetY = 0.0f;
+
+    auto drawRectOriginal = [&](float x, float y, float w, float h, SDL_Color c) {
+        SDL_SetRenderDrawColor(renderer.getSDLRenderer(), c.r, c.g, c.b, c.a);
+        SDL_FRect fr;
+        fr.x = x + contentOffsetX;
+        fr.y = y + contentOffsetY;
+        fr.w = w;
+        fr.h = h;
+        SDL_RenderFillRect(renderer.getSDLRenderer(), &fr);
+    };
+
+    // Compute dynamic logical width/height based on the RenderManager's
+    // computed viewport and scale so the loading UI sizes itself to the
+    // actual content area rather than a hardcoded design size.
+    float LOGICAL_W = static_cast<float>(Config::Logical::WIDTH);
+    float LOGICAL_H = static_cast<float>(Config::Logical::HEIGHT);
+    if (logicalScale > 0.0f && logicalVP.w > 0 && logicalVP.h > 0) {
+        // logicalVP is in window pixels; divide by scale to get logical units
+        LOGICAL_W = static_cast<float>(logicalVP.w) / logicalScale;
+        LOGICAL_H = static_cast<float>(logicalVP.h) / logicalScale;
+    }
+    const bool isLimitedHeight = LOGICAL_H < 450.0f;
+    SDL_Texture* logoTex = app->m_assetManager->getTexture("logo");
+    const float logoHeight = logoTex ? (isLimitedHeight ? LOGICAL_H * 0.25f : LOGICAL_H * 0.4f) : 0;
+    const float loadingTextHeight = 20;
+    const float barHeight = 20;
+    const float barPaddingVertical = isLimitedHeight ? 15 : 35;
+    const float percentTextHeight = 24;
+    const float spacingBetweenElements = isLimitedHeight ? 5 : 15;
+
+    const float totalContentHeight = logoHeight + (logoHeight > 0 ? spacingBetweenElements : 0) + loadingTextHeight + barPaddingVertical + barHeight + spacingBetweenElements + percentTextHeight;
+
+    float currentY = (LOGICAL_H - totalContentHeight) / 2.0f;
+
+    if (logoTex) {
+        const int lw = 872, lh = 273;
+    const float maxLogoWidth = std::min(LOGICAL_W * 0.9f, 600.0f);
+        const float availableHeight = isLimitedHeight ? LOGICAL_H * 0.25f : LOGICAL_H * 0.4f;
+        const float availableWidth = maxLogoWidth;
+        const float scaleFactorWidth = availableWidth / static_cast<float>(lw);
+        const float scaleFactorHeight = availableHeight / static_cast<float>(lh);
+        const float scaleFactor = std::min(scaleFactorWidth, scaleFactorHeight);
+        const float displayWidth = lw * scaleFactor;
+        const float displayHeight = lh * scaleFactor;
+        const float logoX = (LOGICAL_W - displayWidth) / 2.0f;
+        SDL_FRect dst{logoX + contentOffsetX, currentY + contentOffsetY, displayWidth, displayHeight};
+        SDL_RenderTexture(renderer.getSDLRenderer(), logoTex, nullptr, &dst);
+        currentY += displayHeight + spacingBetweenElements;
+    }
+
+    FontAtlas* pixelFont = (FontAtlas*)app->m_assetManager->getFont("pixel_font");
+    FontAtlas* fallbackFont = (FontAtlas*)app->m_assetManager->getFont("main_font");
+    FontAtlas* loadingFont = pixelFont ? pixelFont : fallbackFont;
+    if (loadingFont) {
+        const std::string loadingText = "LOADING";
+        int tW=0, tH=0; loadingFont->measure(loadingText, 1.0f, tW, tH);
+        float textX = (LOGICAL_W - (float)tW) * 0.5f;
+        loadingFont->draw(renderer.getSDLRenderer(), textX + contentOffsetX, currentY + contentOffsetY, loadingText, 1.0f, {255,204,0,255});
+    }
+
+    currentY += loadingTextHeight + barPaddingVertical;
+
+    const int barW = 400, barH = 20;
+    const int bx = (LOGICAL_W - barW) / 2;
+    float loadingProgress = app->m_assetManager->getLoadingProgress();
+    drawRectOriginal(bx - 3, currentY - 3, barW + 6, barH + 6, {68,68,80,255});
+    drawRectOriginal(bx, currentY, barW, barH, {34,34,34,255});
+    drawRectOriginal(bx, currentY, int(barW * loadingProgress), barH, {255,204,0,255});
+    currentY += barH + spacingBetweenElements;
+
+    if (loadingFont) {
+        int percentage = int(loadingProgress * 100);
+        char percentText[16];
+        std::snprintf(percentText, sizeof(percentText), "%d%%", percentage);
+        std::string pStr(percentText);
+        int pW=0, pH=0; loadingFont->measure(pStr, 1.5f, pW, pH);
+        float percentX = (LOGICAL_W - (float)pW) * 0.5f;
+        loadingFont->draw(renderer.getSDLRenderer(), percentX + contentOffsetX, currentY + contentOffsetY, pStr, 1.5f, {255,204,0,255});
+    }
+
+    SDL_SetRenderViewport(renderer.getSDLRenderer(), nullptr);
+    SDL_SetRenderScale(renderer.getSDLRenderer(), 1.0f, 1.0f);
+}
+
+
+ApplicationManager::~ApplicationManager() {
+    if (m_initialized) {
+        shutdown();
+    }
+}
+
+bool ApplicationManager::initialize(int argc, char* argv[]) {
+    if (m_initialized) {
+        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "ApplicationManager already initialized");
+        return true;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Initializing ApplicationManager...");
+
+    // Initialize GlobalState
+    GlobalState::instance().initialize();
+    
+    // Set initial logical dimensions
+    GlobalState::instance().updateLogicalDimensions(m_windowWidth, m_windowHeight);
+
+    // Initialize SDL first
+    if (!initializeSDL()) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to initialize SDL");
+        return false;
+    }
+
+    // Initialize managers
+    if (!initializeManagers()) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to initialize managers");
+        cleanupSDL();
+        return false;
+    }
+
+    // Register services for dependency injection
+    registerServices();
+
+    // Initialize game systems
+    if (!initializeGame()) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to initialize game systems");
+        cleanupManagers();
+        cleanupSDL();
+        return false;
+    }
+
+    m_initialized = true;
+    m_running = true;
+    m_lastFrameTime = SDL_GetTicks();
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "ApplicationManager initialized successfully");
+    return true;
+}
+
+void ApplicationManager::run() {
+    if (!m_initialized) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "ApplicationManager not initialized");
+        return;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Starting main application loop");
+    traceFile("Main loop starting");
+
+    while (m_running) {
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "Main loop iteration start: m_running=%d", m_running ? 1 : 0);
+    traceFile("Main loop iteration");
+        // Calculate delta time
+        uint64_t currentTime = SDL_GetTicks();
+        float deltaTime = (currentTime - m_lastFrameTime) / 1000.0f;
+        m_lastFrameTime = currentTime;
+
+        // Limit delta time to prevent spiral of death
+        if (deltaTime > Config::Performance::MIN_FRAME_TIME) {
+            deltaTime = Config::Performance::MIN_FRAME_TIME;
+        }
+
+        // Main loop phases
+        processEvents();
+        
+        if (m_running) {
+            update(deltaTime);
+            traceFile("about to call render");
+            render();
+        }
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Main application loop ended");
+}
+
+void ApplicationManager::shutdown() {
+    if (!m_initialized) {
+        return;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Shutting down ApplicationManager...");
+
+    m_running = false;
+
+    // Stop audio systems before tearing down SDL to avoid aborts/asserts
+    Audio::instance().shutdown();
+    SoundEffectManager::instance().shutdown();
+
+    // Cleanup in reverse order of initialization
+    cleanupManagers();
+    cleanupSDL();
+    
+    // Shutdown GlobalState last
+    GlobalState::instance().shutdown();
+
+    m_initialized = false;
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "ApplicationManager shutdown complete");
+}
+
+bool ApplicationManager::initializeSDL() {
+    // Initialize SDL subsystems
+    int sdlResult = SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO);
+    if (sdlResult < 0) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_Init failed: %s", SDL_GetError());
+        return false;
+    }
+
+    // Initialize SDL_ttf
+    int ttfResult = TTF_Init();
+    if (ttfResult < 0) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "TTF_Init failed: %s", SDL_GetError());
+        SDL_Quit();
+        return false;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "SDL initialized successfully");
+    return true;
+}
+
+bool ApplicationManager::initializeManagers() {
+    // Create and initialize RenderManager
+    m_renderManager = std::make_unique<RenderManager>();
+    if (!m_renderManager->initialize(m_windowWidth, m_windowHeight, m_windowTitle)) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to initialize RenderManager");
+        return false;
+    }
+    m_isFullscreen = m_renderManager->isFullscreen();
+
+    // Create InputManager
+    m_inputManager = std::make_unique<InputManager>();
+    if (!m_inputManager) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to create InputManager");
+        return false;
+    }
+
+    // Create and initialize AssetManager
+    m_assetManager = std::make_unique<AssetManager>();
+    if (!m_assetManager->initialize(m_renderManager->getSDLRenderer())) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to initialize AssetManager");
+        return false;
+    }
+
+    // Ensure SoundEffectManager is initialized early so SFX loads work
+    SoundEffectManager::instance().init();
+
+    // Create StateManager (will be enhanced in next steps)
+    m_stateManager = std::make_unique<StateManager>(AppState::Loading);
+
+    // Create and initialize starfields
+    m_starfield3D = std::make_unique<Starfield3D>();
+    m_starfield3D->init(Config::Logical::WIDTH, Config::Logical::HEIGHT, 200);
+    
+    m_starfield = std::make_unique<Starfield>();
+    m_starfield->init(Config::Logical::WIDTH, Config::Logical::HEIGHT, 50);
+
+    // Register InputManager handlers to forward events to StateManager so
+    // state-specific event handlers receive SDL_Event objects just like main.cpp.
+    if (m_inputManager && m_stateManager) {
+        m_inputManager->registerKeyHandler([this](SDL_Scancode sc, bool pressed){
+            if (!m_stateManager) return;
+
+            bool consume = false;
+
+            // Global hotkeys (handled across all states)
+            if (pressed) {
+                // While the help overlay is visible, swallow input so gameplay/menu doesn't react.
+                // Allow only help-toggle/close keys to pass through this global handler.
+                if (m_showHelpOverlay) {
+                    if (sc == SDL_SCANCODE_ESCAPE) {
+                        m_showHelpOverlay = false;
+                        if (m_helpOverlayPausedGame && m_game) {
+                            m_game->setPaused(false);
+                        }
+                        m_helpOverlayPausedGame = false;
+                    } else if (sc == SDL_SCANCODE_F1) {
+                        // Toggle off
+                        m_showHelpOverlay = false;
+                        if (m_helpOverlayPausedGame && m_game) {
+                            m_game->setPaused(false);
+                        }
+                        m_helpOverlayPausedGame = false;
+                    }
+                    consume = true;
+                }
+
+                // Toggle fullscreen on F, F11 or Alt+Enter (or Alt+KP_Enter)
+                if (sc == SDL_SCANCODE_F || sc == SDL_SCANCODE_F11 ||
+                    ((sc == SDL_SCANCODE_RETURN || sc == SDL_SCANCODE_RETURN2 || sc == SDL_SCANCODE_KP_ENTER) &&
+                     (SDL_GetModState() & SDL_KMOD_ALT))) {
+                    if (m_renderManager) {
+                        bool fs = m_renderManager->isFullscreen();
+                        m_renderManager->setFullscreen(!fs);
+                        m_isFullscreen = m_renderManager->isFullscreen();
+                    }
+                    consume = true;
+                }
+
+                // M: Toggle/mute music; start playback if unmuting and not started yet
+                if (!consume && sc == SDL_SCANCODE_M) {
+                    Audio::instance().toggleMute();
+                    m_musicEnabled = !m_musicEnabled;
+                    if (m_musicEnabled && !m_musicStarted && Audio::instance().getLoadedTrackCount() > 0) {
+                        Audio::instance().shuffle();
+                        Audio::instance().start();
+                        m_musicStarted = true;
+                    }
+                    consume = true;
+                }
+
+                // N: Skip to next song in the playlist (or restart menu track)
+                if (!consume && sc == SDL_SCANCODE_N) {
+                    Audio::instance().skipToNextTrack();
+                    if (!m_musicStarted && Audio::instance().getLoadedTrackCount() > 0) {
+                        m_musicStarted = true;
+                        m_musicEnabled = true;
+                    }
+                    consume = true;
+                }
+
+                if (!consume && (sc == SDL_SCANCODE_F1)) {
+                    AppState currentState = m_stateManager ? m_stateManager->getState() : AppState::Loading;
+                    // F1 is global (except Loading).
+                    if (currentState != AppState::Loading) {
+                        m_showHelpOverlay = !m_showHelpOverlay;
+                        if (currentState == AppState::Playing && m_game) {
+                        if (m_showHelpOverlay) {
+                            if (!m_game->isPaused()) {
+                                m_game->setPaused(true);
+                                m_helpOverlayPausedGame = true;
+                            } else {
+                                m_helpOverlayPausedGame = false;
+                            }
+                        } else if (m_helpOverlayPausedGame) {
+                            m_game->setPaused(false);
+                            m_helpOverlayPausedGame = false;
+                        }
+                        } else if (!m_showHelpOverlay) {
+                            m_helpOverlayPausedGame = false;
+                        }
+                    }
+                    consume = true;
+                }
+            }
+
+            // Forward to current state unless consumed
+            if (!consume) {
+                SDL_Event ev{};
+                ev.type = pressed ? SDL_EVENT_KEY_DOWN : SDL_EVENT_KEY_UP;
+                ev.key.scancode = sc;
+                ev.key.repeat = 0;
+                m_stateManager->handleEvent(ev);
+            }
+        });
+
+        m_inputManager->registerMouseButtonHandler([this](int button, bool pressed, float x, float y){
+            if (!m_stateManager) return;
+            if (m_showHelpOverlay) return;
+            SDL_Event ev{};
+            ev.type = pressed ? SDL_EVENT_MOUSE_BUTTON_DOWN : SDL_EVENT_MOUSE_BUTTON_UP;
+            ev.button.button = button;
+            ev.button.x = int(x);
+            ev.button.y = int(y);
+            m_stateManager->handleEvent(ev);
+        });
+
+        m_inputManager->registerMouseMotionHandler([this](float x, float y, float dx, float dy){
+            if (!m_stateManager) return;
+            if (m_showHelpOverlay) return;
+            SDL_Event ev{};
+            ev.type = SDL_EVENT_MOUSE_MOTION;
+            ev.motion.x = int(x);
+            ev.motion.y = int(y);
+            ev.motion.xrel = int(dx);
+            ev.motion.yrel = int(dy);
+            m_stateManager->handleEvent(ev);
+        });
+
+        m_inputManager->registerWindowEventHandler([this](const SDL_WindowEvent& we){
+            // Handle window resize events for RenderManager
+            if (we.type == SDL_EVENT_WINDOW_RESIZED && m_renderManager) {
+                m_renderManager->handleWindowResize(we.data1, we.data2);
+                
+                // Update GlobalState logical dimensions when window resizes
+                GlobalState::instance().updateLogicalDimensions(we.data1, we.data2);
+            }
+            
+            // Forward all window events to StateManager
+            if (!m_stateManager) return;
+            SDL_Event ev{};
+            ev.type = we.type;
+            ev.window = we;
+            m_stateManager->handleEvent(ev);
+        });
+
+        m_inputManager->registerQuitHandler([this](){
+            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[QUIT] InputManager quit handler invoked - setting running=false");
+            traceFile("ApplicationManager: quit handler -> m_running=false");
+            m_running = false;
+        });
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Managers initialized successfully");
+    return true;
+}
+
+void ApplicationManager::registerServices() {
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Registering services for dependency injection...");
+    
+    // Register concrete implementations as interface singletons
+    if (m_renderManager) {
+        std::shared_ptr<RenderManager> renderPtr(m_renderManager.get(), [](RenderManager*) {
+            // Custom deleter that does nothing since the unique_ptr manages lifetime
+        });
+        m_serviceContainer.registerSingleton<IRenderer>(renderPtr);
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Registered IRenderer service");
+    }
+    
+    if (m_assetManager) {
+        std::shared_ptr<AssetManager> assetPtr(m_assetManager.get(), [](AssetManager*) {
+            // Custom deleter that does nothing since the unique_ptr manages lifetime
+        });
+        m_serviceContainer.registerSingleton<IAssetLoader>(assetPtr);
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Registered IAssetLoader service");
+    }
+    
+    if (m_inputManager) {
+        std::shared_ptr<InputManager> inputPtr(m_inputManager.get(), [](InputManager*) {
+            // Custom deleter that does nothing since the unique_ptr manages lifetime
+        });
+        m_serviceContainer.registerSingleton<IInputHandler>(inputPtr);
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Registered IInputHandler service");
+    }
+    
+    // Register Audio system singleton
+    auto& audioInstance = Audio::instance();
+    auto audioPtr = std::shared_ptr<Audio>(&audioInstance, [](Audio*) {
+        // Custom deleter that does nothing since Audio is a singleton
+    });
+    m_serviceContainer.registerSingleton<IAudioSystem>(audioPtr);
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Registered IAudioSystem service");
+    
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Service registration completed successfully");
+}
+
+bool ApplicationManager::initializeGame() {
+    // Load essential assets using AssetManager
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Loading essential assets...");
+    
+    // Set up asset loading tasks
+    AssetManager::LoadingTask logoTask{AssetManager::LoadingTask::TEXTURE, "logo", Config::Assets::LOGO_BMP};
+    AssetManager::LoadingTask backgroundTask{AssetManager::LoadingTask::TEXTURE, "background", Config::Assets::BACKGROUND_BMP};
+    AssetManager::LoadingTask blocksTask{AssetManager::LoadingTask::TEXTURE, "blocks", Config::Assets::BLOCKS_BMP};
+    AssetManager::LoadingTask fontTask{AssetManager::LoadingTask::FONT, "main_font", Config::Fonts::DEFAULT_FONT_PATH, Config::Fonts::DEFAULT_FONT_SIZE};
+    AssetManager::LoadingTask pixelFontTask{AssetManager::LoadingTask::FONT, "pixel_font", Config::Fonts::PIXEL_FONT_PATH, Config::Fonts::PIXEL_FONT_SIZE};
+
+    // Pre-load the pixel (retro) font synchronously so the loading screen can render text immediately
+    if (!m_assetManager->getFont("pixel_font")) {
+        if (m_assetManager->loadFont("pixel_font", Config::Fonts::PIXEL_FONT_PATH, Config::Fonts::PIXEL_FONT_SIZE)) {
+            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Preloaded pixel_font for loading screen");
+        } else {
+            SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "Failed to preload pixel_font; loading screen will fallback to main_font");
+        }
+    }
+
+    // Add tasks to AssetManager (pixel font task will be skipped if already loaded)
+    m_assetManager->addLoadingTask(logoTask);
+    m_assetManager->addLoadingTask(backgroundTask);
+    m_assetManager->addLoadingTask(blocksTask);
+    m_assetManager->addLoadingTask(fontTask);
+    m_assetManager->addLoadingTask(pixelFontTask);
+    
+    // Execute loading tasks with progress callback
+    m_assetManager->executeLoadingTasks([](float progress) {
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Asset loading progress: %.1f%%", progress * 100.0f);
+    });
+    
+    // Load sound effects with fallback (SoundEffectManager already initialized)
+    m_assetManager->loadSoundEffectWithFallback("clear_line", "clear_line");
+    m_assetManager->loadSoundEffectWithFallback("nice_combo", "nice_combo");
+    m_assetManager->loadSoundEffectWithFallback("great_move", "great_move");
+    m_assetManager->loadSoundEffectWithFallback("amazing", "amazing");
+    m_assetManager->loadSoundEffectWithFallback("lets_go", "lets_go");
+    
+    // Start background music loading
+    m_assetManager->startBackgroundMusicLoading();
+    
+    // Create and populate shared StateContext similar to main.cpp so states like MenuState
+    // receive the same pointers and flags they expect.
+    // Create ScoreManager and load scores
+    m_scoreManager = std::make_unique<ScoreManager>();
+    if (m_scoreManager) m_scoreManager->load();
+
+    // Create gameplay and line effect objects to populate StateContext like main.cpp
+    m_lineEffect = std::make_unique<LineEffect>();
+    if (m_renderManager && m_renderManager->getSDLRenderer()) {
+        m_lineEffect->init(m_renderManager->getSDLRenderer());
+    }
+    m_game = std::make_unique<Game>(m_startLevelSelection);
+    m_coopGame = std::make_unique<CoopGame>(m_startLevelSelection);
+    // Wire up sound callbacks as main.cpp did
+    if (m_game) {
+        // Apply global gravity speed multiplier from config
+        m_game->setGravityGlobalMultiplier(Config::Gameplay::GRAVITY_SPEED_MULTIPLIER);
+        // Reset to recalculate gravity with the new multiplier
+        m_game->reset(m_startLevelSelection);
+        
+        m_game->setSoundCallback([&](int linesCleared){
+            SoundEffectManager::instance().playSound("clear_line", 1.0f);
+            // voice lines handled via asset manager loaded sounds
+            if (linesCleared == 2) SoundEffectManager::instance().playRandomSound({"nice_combo"}, 1.0f);
+            else if (linesCleared == 3) SoundEffectManager::instance().playRandomSound({"great_move"}, 1.0f);
+            else if (linesCleared == 4) SoundEffectManager::instance().playRandomSound({"amazing"}, 1.0f);
+        });
+        m_game->setLevelUpCallback([&](int newLevel){
+            SoundEffectManager::instance().playSound("lets_go", 1.0f);
+        });
+    }
+
+    if (m_coopGame) {
+        // TODO: tune gravity with Config and shared level scaling once coop rules are finalized
+        m_coopGame->reset(m_startLevelSelection);
+        // Wire coop sound callback to reuse same clear-line VO/SFX behavior
+        m_coopGame->setSoundCallback([&](int linesCleared){
+            SoundEffectManager::instance().playSound("clear_line", 1.0f);
+            if (linesCleared == 2) SoundEffectManager::instance().playRandomSound({"nice_combo"}, 1.0f);
+            else if (linesCleared == 3) SoundEffectManager::instance().playRandomSound({"great_move"}, 1.0f);
+            else if (linesCleared == 4) SoundEffectManager::instance().playRandomSound({"amazing"}, 1.0f);
+        });
+    }
+
+    // Prepare a StateContext-like struct by setting up handlers that capture
+    // pointers and flags. State objects in this refactor expect these to be
+    // available via StateManager event/update/render hooks, so we'll store them
+    // as lambdas that reference members here.
+
+    // Start background music loading similar to main.cpp: Audio init + file discovery
+    Audio::instance().init();
+    // Discover available tracks (up to 100) and queue for background loading
+    m_totalTracks = 0;
+    std::vector<std::string> trackPaths;
+    trackPaths.reserve(100);
+    for (int i = 1; i <= 100; ++i) {
+        char base[128];
+        std::snprintf(base, sizeof(base), "assets/music/music%03d", i);
+        std::string path = AssetPath::resolveWithExtensions(base, { ".mp3" });
+        if (path.empty()) {
+            break;
+        }
+        trackPaths.push_back(path);
+    }
+    m_totalTracks = static_cast<int>(trackPaths.size());
+    for (const auto& path : trackPaths) {
+        Audio::instance().addTrackAsync(path);
+    }
+    if (m_totalTracks > 0) {
+        Audio::instance().startBackgroundLoading();
+    // Kick off playback now; Audio will pick a track once decoded.
+    // Do not mark as started yet; we'll flip the flag once a track is actually loaded.
+    if (m_musicEnabled) {
+            Audio::instance().shuffle();
+            Audio::instance().start();
+        }
+        m_currentTrackLoading = 1; // mark started
+    }
+
+    // Instantiate state objects and populate a StateContext similar to main.cpp
+    // so that existing state classes (MenuState, LoadingState, etc.) receive
+    // the resources they expect.
+    {
+        m_stateContext.stateManager = m_stateManager.get();
+        m_stateContext.game = m_game.get();
+        m_stateContext.coopGame = m_coopGame.get();
+        m_stateContext.scores = m_scoreManager.get();
+        m_stateContext.starfield = m_starfield.get();
+        m_stateContext.starfield3D = m_starfield3D.get();
+        m_stateContext.font = (FontAtlas*)m_assetManager->getFont("main_font");
+        m_stateContext.pixelFont = (FontAtlas*)m_assetManager->getFont("pixel_font");
+        m_stateContext.lineEffect = m_lineEffect.get();
+        m_stateContext.logoTex = m_assetManager->getTexture("logo");
+        // Attempt to load a small logo variant if present to match original UX
+        SDL_Texture* logoSmall = m_assetManager->getTexture("logo_small");
+        if (!logoSmall) {
+            // Try to load image from disk and register with AssetManager
+            if (m_assetManager->loadTexture("logo_small", "assets/images/logo_small.bmp")) {
+                logoSmall = m_assetManager->getTexture("logo_small");
+            }
+        }
+        m_stateContext.logoSmallTex = logoSmall;
+        if (logoSmall) {
+            int w = 0, h = 0; if (m_renderManager) m_renderManager->getTextureSize(logoSmall, w, h);
+            m_stateContext.logoSmallW = w; m_stateContext.logoSmallH = h;
+        } else { m_stateContext.logoSmallW = 0; m_stateContext.logoSmallH = 0; }
+        m_stateContext.backgroundTex = m_assetManager->getTexture("background");
+        m_stateContext.blocksTex = m_assetManager->getTexture("blocks");
+        m_stateContext.asteroidsTex = m_assetManager->getTexture("asteroids");
+        m_stateContext.musicEnabled = &m_musicEnabled;
+        m_stateContext.musicStarted = &m_musicStarted;
+        m_stateContext.musicLoaded = &m_musicLoaded;
+        m_stateContext.startLevelSelection = &m_startLevelSelection;
+        m_stateContext.hoveredButton = &m_hoveredButton;
+        m_stateContext.showSettingsPopup = &m_showSettingsPopup;
+        m_stateContext.showHelpOverlay = &m_showHelpOverlay;
+        m_stateContext.showExitConfirmPopup = &m_showExitConfirmPopup;
+        m_stateContext.exitPopupSelectedButton = &m_exitPopupSelectedButton;
+        m_stateContext.playerName = &m_playerName;
+        m_stateContext.fullscreenFlag = &m_isFullscreen;
+        m_stateContext.applyFullscreen = [this](bool enable) {
+            if (m_renderManager) {
+                m_renderManager->setFullscreen(enable);
+                m_isFullscreen = m_renderManager->isFullscreen();
+            } else {
+                m_isFullscreen = enable;
+            }
+        };
+        m_stateContext.queryFullscreen = [this]() -> bool {
+            if (m_renderManager) {
+                return m_renderManager->isFullscreen();
+            }
+            return m_isFullscreen;
+        };
+        m_stateContext.requestQuit = [this]() {
+            requestShutdown();
+        };
+
+        // Create state instances
+        m_loadingState = std::make_unique<LoadingState>(m_stateContext);
+        m_menuState = std::make_unique<MenuState>(m_stateContext);
+        m_optionsState = std::make_unique<OptionsState>(m_stateContext);
+        m_levelSelectorState = std::make_unique<LevelSelectorState>(m_stateContext);
+        m_playingState = std::make_unique<PlayingState>(m_stateContext);
+
+        // Register handlers that forward to these state objects
+        if (m_stateManager) {
+            m_stateManager->registerEventHandler(AppState::Loading, [this](const SDL_Event& e){ if (m_loadingState) m_loadingState->handleEvent(e); });
+            m_stateManager->registerOnEnter(AppState::Loading, [this](){ if (m_loadingState) m_loadingState->onEnter(); });
+            m_stateManager->registerOnExit(AppState::Loading, [this](){ if (m_loadingState) m_loadingState->onExit(); });
+
+            m_stateManager->registerEventHandler(AppState::Menu, [this](const SDL_Event& e){ if (m_menuState) m_menuState->handleEvent(e); });
+            m_stateManager->registerOnEnter(AppState::Menu, [this](){ if (m_menuState) m_menuState->onEnter(); });
+            m_stateManager->registerOnExit(AppState::Menu, [this](){ if (m_menuState) m_menuState->onExit(); });
+
+            m_stateManager->registerEventHandler(AppState::Options, [this](const SDL_Event& e){ if (m_optionsState) m_optionsState->handleEvent(e); });
+            m_stateManager->registerOnEnter(AppState::Options, [this](){ if (m_optionsState) m_optionsState->onEnter(); });
+            m_stateManager->registerOnExit(AppState::Options, [this](){ if (m_optionsState) m_optionsState->onExit(); });
+
+            m_stateManager->registerEventHandler(AppState::LevelSelector, [this](const SDL_Event& e){ if (m_levelSelectorState) m_levelSelectorState->handleEvent(e); });
+            m_stateManager->registerOnEnter(AppState::LevelSelector, [this](){ if (m_levelSelectorState) m_levelSelectorState->onEnter(); });
+            m_stateManager->registerOnExit(AppState::LevelSelector, [this](){ if (m_levelSelectorState) m_levelSelectorState->onExit(); });
+
+            m_stateManager->registerEventHandler(AppState::Playing, [this](const SDL_Event& e){ if (m_playingState) m_playingState->handleEvent(e); });
+            m_stateManager->registerOnEnter(AppState::Playing, [this](){ if (m_playingState) m_playingState->onEnter(); });
+            m_stateManager->registerOnExit(AppState::Playing, [this](){ if (m_playingState) m_playingState->onExit(); });
+        }
+    }
+
+    // Finally call setupStateHandlers for inline visuals and additional hooks
+    setupStateHandlers();
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Game systems initialized with asset loading");
+    return true;
+}
+
+void ApplicationManager::setupStateHandlers() {
+    // Helper function for drawing rectangles
+    auto drawRect = [](SDL_Renderer* renderer, float x, float y, float w, float h, uint8_t r, uint8_t g, uint8_t b, uint8_t a) {
+        SDL_SetRenderDrawColor(renderer, r, g, b, a);
+        SDL_FRect rect = { x, y, w, h };
+        SDL_RenderFillRect(renderer, &rect);
+    };
+
+    // Helper function for drawing menu buttons with enhanced styling
+    auto drawEnhancedButton = [drawRect](SDL_Renderer* renderer, FontAtlas* font, float cx, float cy, float w, float h, 
+                                        const std::string& label, bool isHovered, bool isSelected) {
+        float x = cx - w/2;
+        float y = cy - h/2;
+        
+        // Button styling based on state
+        SDL_Color bgColor = isSelected ? SDL_Color{100, 150, 255, 255} : 
+                           isHovered ? SDL_Color{80, 120, 200, 255} : 
+                           SDL_Color{60, 90, 160, 255};
+        
+        // Draw border and background
+        drawRect(renderer, x-2, y-2, w+4, h+4, 60, 80, 140, 255); // Border
+        drawRect(renderer, x, y, w, h, bgColor.r, bgColor.g, bgColor.b, bgColor.a); // Background
+        
+        // Draw text if font is available
+        if (font) {
+            float textScale = 1.8f;
+            float approxCharW = 12.0f * textScale;
+            float textW = label.length() * approxCharW;
+            float textX = x + (w - textW) / 2.0f;
+            float textY = y + (h - 20.0f * textScale) / 2.0f;
+            
+            // Draw shadow
+            font->draw(renderer, textX + 2, textY + 2, label, textScale, {0, 0, 0, 180});
+            // Draw main text
+            font->draw(renderer, textX, textY, label, textScale, {255, 255, 255, 255});
+        }
+    };
+
+    // Loading State Handlers (matching original main.cpp implementation)
+    // Extracted to a helper to avoid complex inline lambda parsing issues on MSVC
+    auto loadingRenderForwarder = [this](RenderManager& renderer) {
+        // forward to helper defined below
+        renderLoading(this, renderer);
+    };
+    m_stateManager->registerRenderHandler(AppState::Loading, loadingRenderForwarder);
+
+    m_stateManager->registerUpdateHandler(AppState::Loading,
+        [this](float deltaTime) {
+            // Update 3D starfield so stars move during loading
+            if (m_starfield3D) {
+                // deltaTime here is in milliseconds; Starfield3D expects seconds
+                m_starfield3D->update(deltaTime / 1000.0f);
+            }
+
+            // Check if loading is complete and transition to next stage
+            if (m_assetManager->isLoadingComplete()) {
+                SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Loading complete, handling post-load flow");
+
+                // Update texture pointers now that assets are loaded
+                m_stateContext.backgroundTex = m_assetManager->getTexture("background");
+                m_stateContext.blocksTex = m_assetManager->getTexture("blocks");
+
+                            // If an intro video exists and hasn't been started, attempt to play it in-process
+                            std::filesystem::path introPath = m_introPath;
+                            if (!m_introStarted && std::filesystem::exists(introPath)) {
+                                SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Intro video found: %s", introPath.string().c_str());
+                                try {
+                                    if (!m_videoPlayer) m_videoPlayer = std::make_unique<VideoPlayer>();
+                                    SDL_Renderer* sdlRend = (m_renderManager) ? m_renderManager->getSDLRenderer() : nullptr;
+                                    if (m_videoPlayer->open(introPath.string(), sdlRend)) {
+                                        m_introStarted = true;
+                                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Intro video started in-process");
+                                    } else {
+                                        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "VideoPlayer failed to open intro; skipping");
+                                        m_stateManager->setState(AppState::Playing);
+                                    }
+                                } catch (const std::exception& ex) {
+                                    SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "Exception while starting VideoPlayer: %s", ex.what());
+                                    m_stateManager->setState(AppState::Playing);
+                                }
+                            } else if (m_introStarted) {
+                                // Let VideoPlayer decode frames; once finished, transition to playing
+                                if (m_videoPlayer) m_videoPlayer->update();
+                                if (!m_videoPlayer || m_videoPlayer->isFinished()) {
+                                    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Intro video finished (in-process), transitioning to Playing");
+                                    m_stateManager->setState(AppState::Playing);
+                                }
+                            } else {
+                                // No intro to play; transition directly to Playing
+                                SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "No intro video; transitioning to Playing");
+                                m_stateManager->setState(AppState::Playing);
+                            }
+            }
+        });
+
+    // Menu State render: draw background full-screen, then delegate to MenuState::render
+    m_stateManager->registerRenderHandler(AppState::Menu,
+        [this](RenderManager& renderer) {
+            // Clear and draw background to full window
+            renderer.clear(0, 0, 20, 255);
+            int winW = 0, winH = 0;
+            if (m_renderManager) m_renderManager->getWindowSize(winW, winH);
+            SDL_Texture* background = m_assetManager->getTexture("background");
+            if (background && winW > 0 && winH > 0) {
+                SDL_FRect bgRect = { 0, 0, (float)winW, (float)winH };
+                renderer.renderTexture(background, nullptr, &bgRect);
+            }
+
+            // Use RenderManager's computed logical viewport/scale for exact centering
+            SDL_Rect logicalVP = {0,0,0,0};
+            float logicalScale = 1.0f;
+            if (m_renderManager) {
+                logicalVP = m_renderManager->getLogicalViewport();
+                logicalScale = m_renderManager->getLogicalScale();
+            }
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), &logicalVP);
+            SDL_SetRenderScale(renderer.getSDLRenderer(), logicalScale, logicalScale);
+            if (m_menuState) {
+                m_menuState->render(renderer.getSDLRenderer(), logicalScale, logicalVP);
+            }
+            // Reset to defaults
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), nullptr);
+            SDL_SetRenderScale(renderer.getSDLRenderer(), 1.0f, 1.0f);
+        });
+
+    m_stateManager->registerRenderHandler(AppState::Options,
+        [this](RenderManager& renderer) {
+            renderer.clear(0, 0, 20, 255);
+            int winW = 0, winH = 0;
+            if (m_renderManager) m_renderManager->getWindowSize(winW, winH);
+            SDL_Texture* background = m_assetManager->getTexture("background");
+            if (background && winW > 0 && winH > 0) {
+                SDL_FRect bgRect = { 0, 0, (float)winW, (float)winH };
+                renderer.renderTexture(background, nullptr, &bgRect);
+            }
+
+            SDL_Rect logicalVP = {0,0,0,0};
+            float logicalScale = 1.0f;
+            if (m_renderManager) {
+                logicalVP = m_renderManager->getLogicalViewport();
+                logicalScale = m_renderManager->getLogicalScale();
+            }
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), &logicalVP);
+            SDL_SetRenderScale(renderer.getSDLRenderer(), logicalScale, logicalScale);
+            if (m_optionsState) {
+                m_optionsState->render(renderer.getSDLRenderer(), logicalScale, logicalVP);
+            }
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), nullptr);
+            SDL_SetRenderScale(renderer.getSDLRenderer(), 1.0f, 1.0f);
+        });
+
+    // LevelSelector State render: draw background full-screen, then delegate to LevelSelectorState::render
+    m_stateManager->registerRenderHandler(AppState::LevelSelector,
+        [this](RenderManager& renderer) {
+            // Clear and draw background to full window
+            renderer.clear(0, 0, 20, 255);
+            int winW = 0, winH = 0;
+            if (m_renderManager) m_renderManager->getWindowSize(winW, winH);
+            SDL_Texture* background = m_assetManager->getTexture("background");
+            if (background && winW > 0 && winH > 0) {
+                SDL_FRect bgRect = { 0, 0, (float)winW, (float)winH };
+                renderer.renderTexture(background, nullptr, &bgRect);
+            }
+
+            // Use RenderManager's computed logical viewport/scale for exact centering
+            SDL_Rect logicalVP = {0,0,0,0};
+            float logicalScale = 1.0f;
+            if (m_renderManager) {
+                logicalVP = m_renderManager->getLogicalViewport();
+                logicalScale = m_renderManager->getLogicalScale();
+            }
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), &logicalVP);
+            SDL_SetRenderScale(renderer.getSDLRenderer(), logicalScale, logicalScale);
+            if (m_levelSelectorState) {
+                m_levelSelectorState->render(renderer.getSDLRenderer(), logicalScale, logicalVP);
+            }
+            // Reset to defaults
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), nullptr);
+            SDL_SetRenderScale(renderer.getSDLRenderer(), 1.0f, 1.0f);
+        });
+
+    m_stateManager->registerUpdateHandler(AppState::Menu,
+        [this](float deltaTime) {
+            // Update logo animation counter
+            // deltaTime is in milliseconds; keep same behavior as main.cpp: counter += frameMs * 0.0008
+            m_logoAnimCounter += (deltaTime * static_cast<float>(Config::Animation::LOGO_ANIM_SPEED));
+            // Also keep GlobalState's counter in sync for UI effects that read from it
+            GlobalState::instance().logoAnimCounter += (deltaTime * Config::Animation::LOGO_ANIM_SPEED);
+            
+            // Update fireworks effect
+            GlobalState& globalState = GlobalState::instance();
+            // updateFireworks expects milliseconds
+            globalState.updateFireworks(deltaTime);
+
+            // Start music as soon as at least one track has decoded (don’t wait for all)
+                // Start music as soon as at least one track has decoded (don't wait for all)
+            if (m_musicEnabled && !m_musicStarted) {
+                if (Audio::instance().getLoadedTrackCount() > 0) {
+                    Audio::instance().shuffle();
+                    Audio::instance().start();
+                    m_musicStarted = true;
+                }
+            }
+            // Track completion status for UI
+            if (!m_musicLoaded && Audio::instance().isLoadingComplete()) {
+                m_musicLoaded = true;
+            }
+        });
+
+    m_stateManager->registerEventHandler(AppState::Menu,
+        [this](const SDL_Event& event) {
+            // Forward keyboard events (Enter/Escape) to trigger actions, match original main.cpp
+            if (event.type == SDL_EVENT_KEY_DOWN && !event.key.repeat) {
+                if (event.key.scancode == SDL_SCANCODE_RETURN || event.key.scancode == SDL_SCANCODE_RETURN2 || event.key.scancode == SDL_SCANCODE_KP_ENTER) {
+                    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Starting game from menu (Enter)");
+                    // Reset start level and transition
+                    // In the original main, game.reset(...) was called; here we only switch state.
+                    m_stateManager->setState(AppState::Playing);
+                    return;
+                }
+                if (event.key.scancode == SDL_SCANCODE_ESCAPE) {
+                    // If an exit confirmation is already showing, accept it and quit.
+                    if (m_showExitConfirmPopup) {
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Quitting from menu (Escape confirmed)");
+                        m_running = false;
+                        return;
+                    }
+
+                    // Otherwise, show the exit confirmation popup instead of quitting immediately.
+                    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Showing exit confirmation (Escape)");
+                    m_showExitConfirmPopup = true;
+                    return;
+                }
+                // K: toggle SFX enable state (music handled globally)
+                if (event.key.scancode == SDL_SCANCODE_K) {
+                    SoundEffectManager::instance().setEnabled(!SoundEffectManager::instance().isEnabled());
+                }
+            }
+
+            // Mouse handling: map SDL mouse coords into logical content coords and
+            // perform hit-tests for menu buttons similar to main.cpp.
+            if (event.type == SDL_EVENT_MOUSE_BUTTON_DOWN) {
+                float mx = (float)event.button.x;
+                float my = (float)event.button.y;
+                // Use RenderManager's computed logical viewport/scale for precise mapping
+                SDL_Rect logicalVP{0,0,0,0}; float logicalScale = 1.0f;
+                if (m_renderManager) { logicalVP = m_renderManager->getLogicalViewport(); logicalScale = m_renderManager->getLogicalScale(); }
+                // Check bounds and compute content-local coords
+                if (mx >= logicalVP.x && my >= logicalVP.y && mx <= logicalVP.x + logicalVP.w && my <= logicalVP.y + logicalVP.h) {
+                    float lx = (mx - logicalVP.x) / logicalScale;
+                    float ly = (my - logicalVP.y) / logicalScale;
+
+                    // Compute dynamic logical dimensions from viewport/scale
+                    float dynW = (logicalScale > 0.f && logicalVP.w > 0) ? (float)logicalVP.w / logicalScale : (float)Config::Logical::WIDTH;
+                    float dynH = (logicalScale > 0.f && logicalVP.h > 0) ? (float)logicalVP.h / logicalScale : (float)Config::Logical::HEIGHT;
+
+                    // Respect settings popup
+                    if (m_showSettingsPopup) {
+                        m_showSettingsPopup = false;
+                    } else {
+                        bool isSmall = ((dynW * logicalScale) < 700.0f);
+                        float btnW = isSmall ? (dynW * 0.4f) : 300.0f;
+                        float btnH = isSmall ? 60.0f : 70.0f;
+                        float btnCX = dynW * 0.5f;
+                        const float btnYOffset = 40.0f;
+                        float btnCY = dynH * 0.86f + btnYOffset;
+                        SDL_FRect playBtn{btnCX - btnW * 0.6f - btnW/2.0f, btnCY - btnH/2.0f, btnW, btnH};
+                        SDL_FRect levelBtn{btnCX + btnW * 0.6f - btnW/2.0f, btnCY - btnH/2.0f, btnW, btnH};
+
+                        if (lx >= playBtn.x && lx <= playBtn.x + playBtn.w && ly >= playBtn.y && ly <= playBtn.y + playBtn.h) {
+                            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Menu: Play button clicked");
+                            m_stateManager->setState(AppState::Playing);
+                        } else if (lx >= levelBtn.x && lx <= levelBtn.x + levelBtn.w && ly >= levelBtn.y && ly <= levelBtn.y + levelBtn.h) {
+                            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Menu: Level button clicked");
+                            m_stateManager->setState(AppState::LevelSelector);
+                        } else {
+                            // Settings area detection (top-right small area)
+                            SDL_FRect settingsBtn{dynW - 60, 10, 50, 30};
+                            if (lx >= settingsBtn.x && lx <= settingsBtn.x + settingsBtn.w && ly >= settingsBtn.y && ly <= settingsBtn.y + settingsBtn.h) {
+                                m_showSettingsPopup = true;
+                            }
+                        }
+                    }
+                }
+            }
+
+            // Mouse motion handling for hover
+            if (event.type == SDL_EVENT_MOUSE_MOTION) {
+                float mx = (float)event.motion.x;
+                float my = (float)event.motion.y;
+                // Use RenderManager's computed logical viewport/scale for precise mapping
+                SDL_Rect logicalVP{0,0,0,0}; float logicalScale = 1.0f;
+                if (m_renderManager) { logicalVP = m_renderManager->getLogicalViewport(); logicalScale = m_renderManager->getLogicalScale(); }
+                if (mx >= logicalVP.x && my >= logicalVP.y && mx <= logicalVP.x + logicalVP.w && my <= logicalVP.y + logicalVP.h) {
+                    float lx = (mx - logicalVP.x) / logicalScale;
+                    float ly = (my - logicalVP.y) / logicalScale;
+                    if (!m_showSettingsPopup) {
+                        // Compute dynamic logical dimensions
+                        float dynW = (logicalScale > 0.f && logicalVP.w > 0) ? (float)logicalVP.w / logicalScale : (float)Config::Logical::WIDTH;
+                        float dynH = (logicalScale > 0.f && logicalVP.h > 0) ? (float)logicalVP.h / logicalScale : (float)Config::Logical::HEIGHT;
+                        bool isSmall = ((dynW * logicalScale) < 700.0f);
+                        float btnW = isSmall ? (dynW * 0.4f) : 300.0f;
+                        float btnH = isSmall ? 60.0f : 70.0f;
+                        float btnCX = dynW * 0.5f;
+                        const float btnYOffset = 40.0f;
+                        float btnCY = dynH * 0.86f + btnYOffset;
+                        SDL_FRect playBtn{btnCX - btnW * 0.6f - btnW/2.0f, btnCY - btnH/2.0f, btnW, btnH};
+                        SDL_FRect levelBtn{btnCX + btnW * 0.6f - btnW/2.0f, btnCY - btnH/2.0f, btnW, btnH};
+                        m_hoveredButton = -1;
+                        if (lx >= playBtn.x && lx <= playBtn.x + playBtn.w && ly >= playBtn.y && ly <= playBtn.y + playBtn.h) {
+                            m_hoveredButton = 0;
+                        } else if (lx >= levelBtn.x && lx <= levelBtn.x + levelBtn.w && ly >= levelBtn.y && ly <= levelBtn.y + levelBtn.h) {
+                            m_hoveredButton = 1;
+                        }
+                    }
+                }
+            }
+        });
+
+    // GameOver State - Handle restart and return to menu
+    m_stateManager->registerEventHandler(AppState::GameOver,
+        [this](const SDL_Event& event) {
+            if (event.type == SDL_EVENT_KEY_DOWN && !event.key.repeat) {
+                // Enter/Space - restart game
+                if (event.key.scancode == SDL_SCANCODE_RETURN || 
+                    event.key.scancode == SDL_SCANCODE_RETURN2 || 
+                    event.key.scancode == SDL_SCANCODE_KP_ENTER ||
+                    event.key.scancode == SDL_SCANCODE_SPACE) {
+                    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Restarting game from GameOver (Enter/Space)");
+                    // Reset game with current start level and transition to Playing
+                    if (m_stateContext.game) {
+                        m_stateContext.game->reset(m_startLevelSelection);
+                    }
+                    m_stateManager->setState(AppState::Playing);
+                    return;
+                }
+                // Escape - return to menu
+                if (event.key.scancode == SDL_SCANCODE_ESCAPE) {
+                    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Returning to menu from GameOver (Escape)");
+                    m_stateManager->setState(AppState::Menu);
+                    return;
+                }
+            }
+        });
+
+    // Playing State - Full game rendering
+    m_stateManager->registerEventHandler(AppState::Playing,
+        [this](const SDL_Event& event) {
+            // Handle mouse clicks on the exit confirmation popup
+            if (event.type == SDL_EVENT_MOUSE_BUTTON_DOWN && m_showExitConfirmPopup) {
+                float mx = (float)event.button.x;
+                float my = (float)event.button.y;
+
+                int winW = 0, winH = 0;
+                if (m_renderManager) m_renderManager->getWindowSize(winW, winH);
+
+                const float LOGICAL_W = static_cast<float>(Config::Logical::WIDTH);
+                const float LOGICAL_H = static_cast<float>(Config::Logical::HEIGHT);
+                float scaleX = (winW > 0) ? (float)winW / LOGICAL_W : 1.0f;
+                float scaleY = (winH > 0) ? (float)winH / LOGICAL_H : 1.0f;
+                float logicalScale = std::min(scaleX, scaleY);
+
+                SDL_Rect logicalVP{0, 0, winW, winH};
+                if (mx < logicalVP.x || my < logicalVP.y || mx > logicalVP.x + logicalVP.w || my > logicalVP.y + logicalVP.h) return;
+
+                float lx = (mx - logicalVP.x) / (logicalScale > 0.f ? logicalScale : 1.f);
+                float ly = (my - logicalVP.y) / (logicalScale > 0.f ? logicalScale : 1.f);
+
+                // Compute content offsets to convert to content-local logical coords (what renderer uses)
+                float contentW = LOGICAL_W * logicalScale;
+                float contentH = LOGICAL_H * logicalScale;
+                float contentOffsetX = (winW - contentW) * 0.5f / (logicalScale > 0.f ? logicalScale : 1.f);
+                float contentOffsetY = (winH - contentH) * 0.5f / (logicalScale > 0.f ? logicalScale : 1.f);
+                float localX = lx - contentOffsetX;
+                float localY = ly - contentOffsetY;
+
+                // Popup geometry (must match GameRenderer)
+                float popupW = 420.0f, popupH = 180.0f;
+                float popupX = (LOGICAL_W - popupW) * 0.5f;
+                float popupY = (LOGICAL_H - popupH) * 0.5f;
+                float btnW = 140.0f, btnH = 46.0f;
+                float yesX = popupX + popupW * 0.25f - btnW * 0.5f;
+                float noX  = popupX + popupW * 0.75f - btnW * 0.5f;
+                float btnY = popupY + popupH - 60.0f;
+
+                // Only react if click is inside popup
+                if (localX >= popupX && localX <= popupX + popupW && localY >= popupY && localY <= popupY + popupH) {
+                    if (localX >= yesX && localX <= yesX + btnW && localY >= btnY && localY <= btnY + btnH) {
+                        // YES: go back to menu (reset game)
+                        m_showExitConfirmPopup = false;
+                        if (m_stateContext.game) m_stateContext.game->reset(m_startLevelSelection);
+                        if (m_stateManager) m_stateManager->setState(AppState::Menu);
+                        return;
+                    }
+                    if (localX >= noX && localX <= noX + btnW && localY >= btnY && localY <= btnY + btnH) {
+                        // NO: close popup and resume
+                        m_showExitConfirmPopup = false;
+                        if (m_stateContext.game) m_stateContext.game->setPaused(false);
+                        return;
+                    }
+                }
+            }
+        });
+    m_stateManager->registerRenderHandler(AppState::Playing,
+        [this](RenderManager& renderer) {
+            // Clear the screen first
+            renderer.clear(0, 0, 0, 255);
+
+            // Window size
+            int winW = 0, winH = 0;
+            renderer.getWindowSize(winW, winH);
+
+            // Draw per-level background stretched to full window, with fade
+            if (m_stateContext.game) {
+                // Update fade progression (ms based on frame time not available here; approximate using SDL ticks delta if desired)
+                // We'll keep alpha as-is; Loading/Menu update can adjust if we wire a timer. For now, simply show the correct background.
+                int currentLevel = m_stateContext.game->level();
+                int bgLevel = (currentLevel > 32) ? 32 : currentLevel; // Cap at 32 like main.cpp
+
+                if (m_cachedBgLevel != bgLevel) {
+                    if (m_nextLevelBackgroundTex) { SDL_DestroyTexture(m_nextLevelBackgroundTex); m_nextLevelBackgroundTex = nullptr; }
+                    char bgPath[256];
+                    std::snprintf(bgPath, sizeof(bgPath), "assets/images/tetris_main_back_level%d.jpg", bgLevel);
+                    const std::string resolvedBgPath = AssetPath::resolveImagePath(bgPath);
+                    SDL_Surface* s = IMG_Load(resolvedBgPath.c_str());
+                    if (s && renderer.getSDLRenderer()) {
+                        m_nextLevelBackgroundTex = SDL_CreateTextureFromSurface(renderer.getSDLRenderer(), s);
+                        SDL_DestroySurface(s);
+                        m_levelFadeAlpha = 0.0f;
+                        m_levelFadeElapsed = 0.0f;
+                        m_cachedBgLevel = bgLevel;
+                        if (resolvedBgPath != bgPath) {
+                            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Loaded level %d background via %s", bgLevel, resolvedBgPath.c_str());
+                        }
+                    } else {
+                        m_cachedBgLevel = -1; // don't change if missing
+                        if (s) SDL_DestroySurface(s);
+                    }
+                }
+
+                if (winW > 0 && winH > 0) {
+                    SDL_FRect full{0,0,(float)winW,(float)winH};
+                    if (m_nextLevelBackgroundTex && m_levelFadeAlpha < 1.0f && m_levelBackgroundTex) {
+                        SDL_SetTextureAlphaMod(m_levelBackgroundTex, Uint8((1.0f - m_levelFadeAlpha) * 255));
+                        SDL_RenderTexture(renderer.getSDLRenderer(), m_levelBackgroundTex, nullptr, &full);
+                        SDL_SetTextureAlphaMod(m_nextLevelBackgroundTex, Uint8(m_levelFadeAlpha * 255));
+                        SDL_RenderTexture(renderer.getSDLRenderer(), m_nextLevelBackgroundTex, nullptr, &full);
+                        SDL_SetTextureAlphaMod(m_levelBackgroundTex, 255);
+                        SDL_SetTextureAlphaMod(m_nextLevelBackgroundTex, 255);
+                    } else if (m_nextLevelBackgroundTex && (!m_levelBackgroundTex || m_levelFadeAlpha >= 1.0f)) {
+                        if (m_levelBackgroundTex) SDL_DestroyTexture(m_levelBackgroundTex);
+                        m_levelBackgroundTex = m_nextLevelBackgroundTex;
+                        m_nextLevelBackgroundTex = nullptr;
+                        m_levelFadeAlpha = 0.0f;
+                        SDL_RenderTexture(renderer.getSDLRenderer(), m_levelBackgroundTex, nullptr, &full);
+                    } else if (m_levelBackgroundTex) {
+                        SDL_RenderTexture(renderer.getSDLRenderer(), m_levelBackgroundTex, nullptr, &full);
+                    }
+                }
+            }
+
+            // Compute logical scale from logical design size
+            const float LOGICAL_W = static_cast<float>(Config::Logical::WIDTH);
+            const float LOGICAL_H = static_cast<float>(Config::Logical::HEIGHT);
+            float scaleX = (winW > 0) ? (float)winW / LOGICAL_W : 1.0f;
+            float scaleY = (winH > 0) ? (float)winH / LOGICAL_H : 1.0f;
+            float logicalScale = std::min(scaleX, scaleY);
+
+            // Use full-window viewport; GameRenderer applies its own content offsets for centering
+            SDL_Rect logicalVP = {0, 0, winW, winH};
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), &logicalVP);
+
+            // Use GameRenderer for actual game rendering
+            GameRenderer::renderPlayingState(
+                renderer.getSDLRenderer(),
+                m_stateContext.game,
+                m_stateContext.pixelFont,
+                m_stateContext.lineEffect,
+                m_stateContext.blocksTex,
+                m_stateContext.asteroidsTex,
+                m_stateContext.statisticsPanelTex,
+                m_stateContext.scorePanelTex,
+                m_stateContext.nextPanelTex,
+                m_stateContext.holdPanelTex,
+                false,
+                LOGICAL_W,
+                LOGICAL_H,
+                logicalScale,
+                static_cast<float>(winW),
+                static_cast<float>(winH)
+            );
+
+            // Reset viewport
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), nullptr);
+        });
+
+    // GameOver State - Simple game over screen
+    m_stateManager->registerRenderHandler(AppState::GameOver,
+        [this](RenderManager& renderer) {
+            // Clear the screen first
+            renderer.clear(12, 12, 16, 255);
+            
+            // Calculate viewport and scale for responsive layout
+            int winW = 0, winH = 0;
+            renderer.getWindowSize(winW, winH);
+            
+            const float LOGICAL_W = static_cast<float>(Config::Window::DEFAULT_WIDTH);
+            const float LOGICAL_H = static_cast<float>(Config::Window::DEFAULT_HEIGHT);
+            
+            float scaleX = static_cast<float>(winW) / LOGICAL_W;
+            float scaleY = static_cast<float>(winH) / LOGICAL_H;
+            float logicalScale = std::min(scaleX, scaleY);
+            
+            int scaledW = static_cast<int>(LOGICAL_W * logicalScale);
+            int scaledH = static_cast<int>(LOGICAL_H * logicalScale);
+            int offsetX = (winW - scaledW) / 2;
+            int offsetY = (winH - scaledH) / 2;
+            
+            SDL_Rect logicalVP = {offsetX, offsetY, scaledW, scaledH};
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), &logicalVP);
+            
+            // Draw starfield background
+            if (m_starfield) {
+                m_starfield->draw(renderer.getSDLRenderer());
+            }
+            
+            // Game over text and stats
+            if (m_stateContext.pixelFont && m_stateContext.game) {
+                FontAtlas& font = *m_stateContext.pixelFont;
+                
+                // "GAME OVER" title
+                font.draw(renderer.getSDLRenderer(), LOGICAL_W * 0.5f - 120, 140, "GAME OVER", 3.0f, {255, 80, 60, 255});
+                
+                // Game stats (single-player or coop combined)
+                char buf[128];
+                if (m_stateContext.game && m_stateContext.game->getMode() == GameMode::Cooperate && m_stateContext.coopGame) {
+                    int leftScore = m_stateContext.coopGame->score(::CoopGame::PlayerSide::Left);
+                    int rightScore = m_stateContext.coopGame->score(::CoopGame::PlayerSide::Right);
+                    int total = leftScore + rightScore;
+                    std::snprintf(buf, sizeof(buf), "SCORE %d + %d = %d  LINES %d  LEVEL %d",
+                        leftScore,
+                        rightScore,
+                        total,
+                        m_stateContext.coopGame->lines(),
+                        m_stateContext.coopGame->level());
+                } else {
+                    std::snprintf(buf, sizeof(buf), "SCORE %d  LINES %d  LEVEL %d",
+                        m_stateContext.game ? m_stateContext.game->score() : 0,
+                        m_stateContext.game ? m_stateContext.game->lines() : 0,
+                        m_stateContext.game ? m_stateContext.game->level() : 0);
+                }
+                font.draw(renderer.getSDLRenderer(), LOGICAL_W * 0.5f - 220, 220, buf, 1.2f, {220, 220, 230, 255});
+                
+                // Instructions
+                font.draw(renderer.getSDLRenderer(), LOGICAL_W * 0.5f - 120, 270, "PRESS ENTER / SPACE", 1.2f, {200, 200, 220, 255});
+            }
+            
+            // Reset viewport
+            SDL_SetRenderViewport(renderer.getSDLRenderer(), nullptr);
+        });
+
+    // Playing State - Update handler for DAS/ARR movement timing
+    m_stateManager->registerUpdateHandler(AppState::Playing,
+        [this](double frameMs) {
+            if (!m_stateContext.game) return;
+
+            const bool coopActive = m_stateContext.game->getMode() == GameMode::Cooperate && m_stateContext.coopGame;
+
+            // Get current keyboard state
+            const bool *ks = SDL_GetKeyboardState(nullptr);
+
+            if (coopActive) {
+                // Paused: suppress all continuous input so pieces don't drift while paused.
+                if (m_stateContext.game->isPaused()) {
+                    m_stateContext.coopGame->setSoftDropping(CoopGame::PlayerSide::Left, false);
+                    m_stateContext.coopGame->setSoftDropping(CoopGame::PlayerSide::Right, false);
+                    m_p1MoveTimerMs = 0.0;
+                    m_p2MoveTimerMs = 0.0;
+                    m_p1LeftHeld = false;
+                    m_p1RightHeld = false;
+                    m_p2LeftHeld = false;
+                    m_p2RightHeld = false;
+                    return;
+                }
+
+                auto handleSide = [&](CoopGame::PlayerSide side,
+                                      bool leftHeld,
+                                      bool rightHeld,
+                                      double& timer,
+                                      SDL_Scancode leftKey,
+                                      SDL_Scancode rightKey,
+                                      SDL_Scancode downKey) {
+                    bool left = ks[leftKey];
+                    bool right = ks[rightKey];
+                    bool down = ks[downKey];
+
+                    // Soft drop flag
+                    m_stateContext.coopGame->setSoftDropping(side, down);
+
+                    int moveDir = 0;
+                    if (left && !right) moveDir = -1;
+                    else if (right && !left) moveDir = +1;
+
+                    if (moveDir != 0) {
+                        if ((moveDir == -1 && !leftHeld) || (moveDir == +1 && !rightHeld)) {
+                            // First press - immediate movement
+                            m_stateContext.coopGame->move(side, moveDir);
+                            timer = DAS;
+                        } else {
+                            timer -= frameMs;
+                            if (timer <= 0) {
+                                m_stateContext.coopGame->move(side, moveDir);
+                                timer += ARR;
+                            }
+                        }
+                    } else {
+                        timer = 0.0;
+                    }
+
+                    // Soft drop boost: coop uses same gravity path; fall acceleration handled inside tickGravity
+                };
+
+                // Left player (WASD): A/D horizontal, S soft drop
+                handleSide(CoopGame::PlayerSide::Left, m_p1LeftHeld, m_p1RightHeld, m_p1MoveTimerMs,
+                           SDL_SCANCODE_A, SDL_SCANCODE_D, SDL_SCANCODE_S);
+                // Right player (arrows): Left/Right horizontal, Down soft drop
+                handleSide(CoopGame::PlayerSide::Right, m_p2LeftHeld, m_p2RightHeld, m_p2MoveTimerMs,
+                           SDL_SCANCODE_LEFT, SDL_SCANCODE_RIGHT, SDL_SCANCODE_DOWN);
+
+                // Update held flags for next frame
+                m_p1LeftHeld = ks[SDL_SCANCODE_A];
+                m_p1RightHeld = ks[SDL_SCANCODE_D];
+                m_p2LeftHeld = ks[SDL_SCANCODE_LEFT];
+                m_p2RightHeld = ks[SDL_SCANCODE_RIGHT];
+
+                // Gravity / effects
+                m_stateContext.coopGame->tickGravity(frameMs);
+                m_stateContext.coopGame->updateVisualEffects(frameMs);
+
+                // Delegate to PlayingState for any ancillary updates (renderer transport bookkeeping)
+                if (m_playingState) {
+                    m_playingState->update(frameMs);
+                }
+
+                // Game over transition for coop
+                if (m_stateContext.coopGame->isGameOver()) {
+                    m_stateManager->setState(AppState::GameOver);
+                }
+
+            } else {
+                bool left = ks[SDL_SCANCODE_LEFT] || ks[SDL_SCANCODE_A];
+                bool right = ks[SDL_SCANCODE_RIGHT] || ks[SDL_SCANCODE_D];
+                bool down = ks[SDL_SCANCODE_DOWN] || ks[SDL_SCANCODE_S];
+                
+                // Handle soft drop
+                m_stateContext.game->setSoftDropping(down && !m_stateContext.game->isPaused());
+                
+                // Handle DAS/ARR movement timing (from original main.cpp)
+                int moveDir = 0;
+                if (left && !right)
+                    moveDir = -1;
+                else if (right && !left)
+                    moveDir = +1;
+                
+                if (moveDir != 0 && !m_stateContext.game->isPaused()) {
+                    if ((moveDir == -1 && !m_leftHeld) || (moveDir == +1 && !m_rightHeld)) {
+                        // First press - immediate movement
+                        m_stateContext.game->move(moveDir);
+                        m_moveTimerMs = DAS;  // Set initial delay
+                    } else {
+                        // Key held - handle repeat timing
+                        m_moveTimerMs -= frameMs;
+                        if (m_moveTimerMs <= 0) {
+                            m_stateContext.game->move(moveDir);
+                            m_moveTimerMs += ARR;  // Set repeat rate
+                        }
+                    }
+                } else {
+                    m_moveTimerMs = 0;  // Reset timer when no movement
+                }
+                
+                // Update held state for next frame
+                m_leftHeld = left;
+                m_rightHeld = right;
+                
+                // Handle soft drop boost
+                if (down && !m_stateContext.game->isPaused()) {
+                    m_stateContext.game->softDropBoost(frameMs);
+                }
+                
+                // Delegate to PlayingState for other updates (gravity, line effects)
+                if (m_playingState) {
+                    m_playingState->update(frameMs);
+                }
+
+                // Update background fade progression (match main.cpp semantics approx)
+                // Duration 1200ms fade (same as LEVEL_FADE_DURATION used in main.cpp snippets)
+                const float LEVEL_FADE_DURATION = 1200.0f;
+                if (m_nextLevelBackgroundTex) {
+                    m_levelFadeElapsed += (float)frameMs;
+                    m_levelFadeAlpha = std::min(1.0f, m_levelFadeElapsed / LEVEL_FADE_DURATION);
+                }
+                
+                // Check for game over and transition to GameOver state
+                if (m_stateContext.game->isGameOver()) {
+                    // Submit score before transitioning
+                    if (m_stateContext.scores) {
+                        std::string gt = (m_stateContext.game->getMode() == GameMode::Challenge) ? "challenge" : "classic";
+                        m_stateContext.scores->submit(
+                            m_stateContext.game->score(), 
+                            m_stateContext.game->lines(), 
+                            m_stateContext.game->level(), 
+                            m_stateContext.game->elapsed(),
+                            std::string("PLAYER"),
+                            gt
+                        );
+                    }
+                    m_stateManager->setState(AppState::GameOver);
+                }
+            }
+        });
+    // Debug overlay: show current window and logical sizes on the right side of the screen
+    auto debugOverlay = [this](RenderManager& renderer) {
+        // Window size
+        int winW = 0, winH = 0;
+        renderer.getWindowSize(winW, winH);
+
+        // Logical viewport and scale
+        SDL_Rect logicalVP{0,0,0,0};
+        float logicalScale = 1.0f;
+        if (m_renderManager) {
+            logicalVP = m_renderManager->getLogicalViewport();
+            logicalScale = m_renderManager->getLogicalScale();
+        }
+
+        // Use dynamic logical dimensions from GlobalState
+        float LOGICAL_W = static_cast<float>(GlobalState::instance().getLogicalWidth());
+        float LOGICAL_H = static_cast<float>(GlobalState::instance().getLogicalHeight());
+
+        // Use logical viewport so overlay is aligned with game content
+        SDL_SetRenderViewport(renderer.getSDLRenderer(), &logicalVP);
+        SDL_SetRenderScale(renderer.getSDLRenderer(), logicalScale, logicalScale);
+
+        // Choose font (pixel first, fallback to main)
+        FontAtlas* pixelFont = (FontAtlas*)(m_assetManager ? m_assetManager->getFont("pixel_font") : nullptr);
+        FontAtlas* mainFont = (FontAtlas*)(m_assetManager ? m_assetManager->getFont("main_font") : nullptr);
+        FontAtlas* font = pixelFont ? pixelFont : mainFont;
+
+        // Inline small helper for drawing a filled rect in logical coords
+        auto fillRect = [&](float x, float y, float w, float h, SDL_Color c) {
+            SDL_SetRenderDrawColor(renderer.getSDLRenderer(), c.r, c.g, c.b, c.a);
+            SDL_FRect r{ x, y, w, h };
+            SDL_RenderFillRect(renderer.getSDLRenderer(), &r);
+        };
+
+        // Prepare text lines
+        char buf[128];
+        std::snprintf(buf, sizeof(buf), "Win: %d x %d", winW, winH);
+        std::string sWin(buf);
+        std::snprintf(buf, sizeof(buf), "Logical: %.0f x %.0f", LOGICAL_W, LOGICAL_H);
+        std::string sLogical(buf);
+        std::snprintf(buf, sizeof(buf), "Scale: %.2f", logicalScale);
+        std::string sScale(buf);
+
+        // Determine size of longest line
+        int w1=0,h1=0, w2=0,h2=0, w3=0,h3=0;
+        if (font) {
+            font->measure(sWin, 1.0f, w1, h1);
+            font->measure(sLogical, 1.0f, w2, h2);
+            font->measure(sScale, 1.0f, w3, h3);
+        }
+        int maxW = std::max({w1,w2,w3});
+        int totalH = (h1 + h2 + h3) + 8; // small padding
+
+        // Position based on actual screen width (center horizontally)
+        const float margin = 8.0f;
+        //        float x = (LOGICAL_W - (float)maxW) * 0.5f; // Center horizontally
+        //        float y = margin;
+                // Desired position in window (pixel) coords
+                int winW_px = 0, winH_px = 0;
+                renderer.getWindowSize(winW_px, winH_px);
+                float desiredWinX = (float(winW_px) - (float)maxW) * 0.5f; // center on full window width
+                float desiredWinY = margin; // near top of the window
+
+                // Convert window coords to logical coords under current viewport/scale
+                float invScale = (logicalScale > 0.0f) ? (1.0f / logicalScale) : 1.0f;
+                float x = (desiredWinX - float(logicalVP.x)) * invScale;
+                float y = (desiredWinY - float(logicalVP.y)) * invScale;
+
+        // Draw background box for readability
+        fillRect(x - 6.0f, y - 6.0f, (float)maxW + 12.0f, (float)totalH + 8.0f, {0, 0, 0, 180});
+
+        // Draw text lines
+        SDL_Color textColor = {255, 204, 0, 255};
+        if (font) {
+            font->draw(renderer.getSDLRenderer(), x, y, sWin, 1.0f, textColor);
+            font->draw(renderer.getSDLRenderer(), x, y + (float)h1, sLogical, 1.0f, textColor);
+            font->draw(renderer.getSDLRenderer(), x, y + (float)(h1 + h2), sScale, 1.0f, textColor);
+        }
+
+        // Reset viewport/scale
+        SDL_SetRenderViewport(renderer.getSDLRenderer(), nullptr);
+        SDL_SetRenderScale(renderer.getSDLRenderer(), 1.0f, 1.0f);
+    };
+
+    // Register debug overlay for all primary states so it draws on top
+    if (m_stateManager) {
+        m_stateManager->registerRenderHandler(AppState::Loading, debugOverlay);
+        m_stateManager->registerRenderHandler(AppState::Menu, debugOverlay);
+        m_stateManager->registerRenderHandler(AppState::LevelSelector, debugOverlay);
+        m_stateManager->registerRenderHandler(AppState::Playing, debugOverlay);
+        m_stateManager->registerRenderHandler(AppState::GameOver, debugOverlay);
+    }
+
+    auto helpOverlayRender = [this](RenderManager& renderer) {
+        if (!m_showHelpOverlay || !m_stateContext.pixelFont) {
+            return;
+        }
+
+        SDL_Renderer* sdlRenderer = renderer.getSDLRenderer();
+        if (!sdlRenderer) {
+            return;
+        }
+
+        SDL_Rect logicalVP = renderer.getLogicalViewport();
+        float logicalScale = renderer.getLogicalScale();
+        SDL_SetRenderViewport(sdlRenderer, &logicalVP);
+        SDL_SetRenderScale(sdlRenderer, logicalScale, logicalScale);
+        HelpOverlay::Render(
+            sdlRenderer,
+            *m_stateContext.pixelFont,
+            static_cast<float>(Config::Logical::WIDTH),
+            static_cast<float>(Config::Logical::HEIGHT),
+            0.0f,
+            0.0f
+        );
+        SDL_SetRenderViewport(sdlRenderer, nullptr);
+        SDL_SetRenderScale(sdlRenderer, 1.0f, 1.0f);
+    };
+
+    if (m_stateManager) {
+        m_stateManager->registerRenderHandler(AppState::Loading, helpOverlayRender);
+        m_stateManager->registerRenderHandler(AppState::Menu, helpOverlayRender);
+        m_stateManager->registerRenderHandler(AppState::Options, helpOverlayRender);
+        m_stateManager->registerRenderHandler(AppState::LevelSelector, helpOverlayRender);
+        m_stateManager->registerRenderHandler(AppState::Playing, helpOverlayRender);
+        m_stateManager->registerRenderHandler(AppState::GameOver, helpOverlayRender);
+    }
+}
+
+void ApplicationManager::processEvents() {
+    // Let InputManager process all SDL events
+    if (m_inputManager) {
+        m_inputManager->processEvents();
+        
+        // Check if InputManager detected a quit request
+        if (m_inputManager->shouldQuit()) {
+            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "InputManager reports shouldQuit() == true — requesting shutdown");
+            requestShutdown();
+            return;
+        }
+    }
+
+    // Handle any additional events not processed by InputManager
+    // (In this case, we rely on InputManager for most event handling)
+}
+
+void ApplicationManager::update(float deltaTime) {
+    // Update AssetManager for progressive loading
+    if (m_assetManager) {
+        m_assetManager->update(deltaTime);
+    }
+    
+    // Update InputManager
+    if (m_inputManager) {
+        m_inputManager->update(deltaTime);
+    }
+
+    // Always update 3D starfield so background animates even during loading/menu
+    if (m_starfield3D) {
+        m_starfield3D->update(deltaTime);
+    }
+
+    // Update StateManager
+    if (m_stateManager) {
+    // NOTE: State update handlers expect milliseconds (frameMs). Convert seconds -> ms here.
+    float frameMs = deltaTime * 1000.0f;
+    m_stateManager->update(frameMs);
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "ApplicationManager::update - state update completed for state %s", m_stateManager->getStateName(m_stateManager->getState()));
+    traceFile("update completed");
+    }
+}
+
+void ApplicationManager::render() {
+    if (!m_renderManager) {
+        return;
+    }
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "ApplicationManager::render - about to begin frame");
+    // Trace render begin
+    traceFile("render begin");
+    m_renderManager->beginFrame();
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "ApplicationManager::render - beginFrame complete");
+    
+    // Delegate rendering to StateManager
+    if (m_stateManager) {
+        m_stateManager->render(*m_renderManager);
+        SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "ApplicationManager::render - state render completed for state %s", m_stateManager->getStateName(m_stateManager->getState()));
+    }
+    
+    m_renderManager->endFrame();
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "ApplicationManager::render - endFrame complete");
+    traceFile("render endFrame complete");
+}
+
+void ApplicationManager::cleanupManagers() {
+    // Cleanup managers in reverse order
+    // Destroy gameplay background textures
+    if (m_levelBackgroundTex) { SDL_DestroyTexture(m_levelBackgroundTex); m_levelBackgroundTex = nullptr; }
+    if (m_nextLevelBackgroundTex) { SDL_DestroyTexture(m_nextLevelBackgroundTex); m_nextLevelBackgroundTex = nullptr; }
+    // Shutdown subsystems that own GPU resources before renderer destruction
+    if (m_lineEffect) { m_lineEffect->shutdown(); }
+    // Fonts are managed by AssetManager; ensure it shuts down after we stop states
+    m_stateManager.reset();
+    m_assetManager.reset();
+    m_inputManager.reset();
+    m_renderManager.reset();
+    
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Managers cleaned up");
+}
+
+void ApplicationManager::cleanupSDL() {
+    TTF_Quit();
+    SDL_Quit();
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "SDL cleaned up");
+}
diff --git a/src/core/application/ApplicationManager.h b/src/core/application/ApplicationManager.h
new file mode 100644
index 0000000..ee6002a
--- /dev/null
+++ b/src/core/application/ApplicationManager.h
@@ -0,0 +1,167 @@
+#pragma once
+
+#include "../Config.h"
+#include "../../states/State.h"
+#include "../container/ServiceContainer.h"
+#include <memory>
+#include <string>
+
+// Forward declarations
+class RenderManager;
+class InputManager;
+class StateManager;
+class AssetManager;
+class Game;
+class ScoreManager;
+class Starfield;
+class Starfield3D;
+class FontAtlas;
+class LineEffect;
+class CoopGame;
+
+// Forward declare state classes (top-level, defined under src/states)
+class LoadingState;
+class MenuState;
+class OptionsState;
+class LevelSelectorState;
+class PlayingState;
+
+/**
+ * ApplicationManager - Central coordinator for the entire application lifecycle
+ * 
+ * Responsibilities:
+ * - Initialize and shutdown all subsystems
+ * - Coordinate the main application loop
+ * - Manage high-level application state
+ * - Provide clean separation between main() and application logic
+ */
+class ApplicationManager {
+public:
+    ApplicationManager();
+    ~ApplicationManager();
+
+    // Core lifecycle methods
+    bool initialize(int argc, char* argv[]);
+    void run();
+    void shutdown();
+
+    // Application state
+    bool isRunning() const { return m_running; }
+    void requestShutdown() { m_running = false; }
+
+    // Access to managers (for now, will be replaced with dependency injection later)
+    RenderManager* getRenderManager() const { return m_renderManager.get(); }
+    InputManager* getInputManager() const { return m_inputManager.get(); }
+    AssetManager* getAssetManager() const { return m_assetManager.get(); }
+    StateManager* getStateManager() const { return m_stateManager.get(); }
+
+    // Service container access
+    ServiceContainer& getServiceContainer() { return m_serviceContainer; }
+
+private:
+    // Helper used by setupStateHandlers (defined in cpp)
+    static void renderLoading(ApplicationManager* app, RenderManager& renderer);
+    // Initialization methods
+    bool initializeSDL();
+    bool initializeManagers();
+    bool initializeGame();
+    void setupStateHandlers();
+    void registerServices();
+    
+    // Main loop methods
+    void processEvents();
+    void update(float deltaTime);
+    void render();
+    
+    // Cleanup methods
+    void cleanupManagers();
+    void cleanupSDL();
+
+    // Core managers
+    std::unique_ptr<RenderManager> m_renderManager;
+    std::unique_ptr<InputManager> m_inputManager;
+    std::unique_ptr<AssetManager> m_assetManager;
+    std::unique_ptr<StateManager> m_stateManager;
+
+    // Dependency injection container
+    ServiceContainer m_serviceContainer;
+    
+    // Visual effects
+    std::unique_ptr<Starfield3D> m_starfield3D;
+    std::unique_ptr<Starfield> m_starfield;
+
+    // Menu / UI state pieces mirrored from main.cpp
+    bool m_musicEnabled = true;
+    int m_startLevelSelection = 0;
+    int m_hoveredButton = -1;
+    bool m_showSettingsPopup = false;
+    bool m_showHelpOverlay = false;
+    bool m_showExitConfirmPopup = false;
+    int m_exitPopupSelectedButton = 1; // 0 = YES, 1 = NO
+    bool m_isFullscreen = false;
+    std::string m_playerName = "PLAYER";
+    uint64_t m_loadStartTicks = 0;
+    bool m_musicStarted = false;
+    bool m_musicLoaded = false;
+    int m_currentTrackLoading = 0;
+    int m_totalTracks = 0;
+
+    // Persistence (ScoreManager declared at top-level)
+    std::unique_ptr<ScoreManager> m_scoreManager;
+    // Gameplay pieces
+    std::unique_ptr<Game> m_game;
+    std::unique_ptr<CoopGame> m_coopGame;
+    std::unique_ptr<LineEffect> m_lineEffect;
+    
+    // DAS/ARR movement timing (from original main.cpp)
+    bool m_leftHeld = false;
+    bool m_rightHeld = false;
+    double m_moveTimerMs = 0.0;
+    static constexpr double DAS = 170.0;  // Delayed Auto Shift
+    static constexpr double ARR = 40.0;   // Auto Repeat Rate
+
+    // Coop DAS/ARR per player
+    bool m_p1LeftHeld = false;
+    bool m_p1RightHeld = false;
+    bool m_p2LeftHeld = false;
+    bool m_p2RightHeld = false;
+    double m_p1MoveTimerMs = 0.0;
+    double m_p2MoveTimerMs = 0.0;
+
+    // State context (must be a member to ensure lifetime)
+    StateContext m_stateContext;
+    
+    // State objects (mirror main.cpp pattern)
+    std::unique_ptr<LoadingState> m_loadingState;
+    std::unique_ptr<MenuState> m_menuState;
+    std::unique_ptr<OptionsState> m_optionsState;
+    std::unique_ptr<LevelSelectorState> m_levelSelectorState;
+    std::unique_ptr<PlayingState> m_playingState;
+    // Application state
+    bool m_running = false;
+    bool m_initialized = false;
+    
+    // Timing
+    uint64_t m_lastFrameTime = 0;
+    
+    // Configuration
+    int m_windowWidth = Config::Window::DEFAULT_WIDTH;
+    int m_windowHeight = Config::Window::DEFAULT_HEIGHT;
+    std::string m_windowTitle = Config::Window::DEFAULT_TITLE;
+    
+    // Animation state
+    float m_logoAnimCounter = 0.0f;
+    bool m_helpOverlayPausedGame = false;
+
+    // Intro video playback (in-process via FFmpeg)
+    bool m_introStarted = false;
+    std::string m_introPath = "assets/videos/spacetris_intro.mp4";
+    std::unique_ptr<class VideoPlayer> m_videoPlayer;
+
+    // Gameplay background (per-level) with fade, mirroring main.cpp behavior
+    SDL_Texture* m_levelBackgroundTex = nullptr;
+    SDL_Texture* m_nextLevelBackgroundTex = nullptr; // used during fade transitions
+    float m_levelFadeAlpha = 0.0f; // 0..1 blend factor
+    float m_levelFadeElapsed = 0.0f; // ms
+    int m_cachedBgLevel = -1; // last loaded background level index
+};
diff --git a/src/core/assets/AssetManager.cpp b/src/core/assets/AssetManager.cpp
new file mode 100644
index 0000000..dc1d23d
--- /dev/null
+++ b/src/core/assets/AssetManager.cpp
@@ -0,0 +1,482 @@
+#include "AssetManager.h"
+#include "../../graphics/ui/Font.h"
+#include "../../audio/Audio.h"
+#include "../../audio/SoundEffect.h"
+#include <SDL3/SDL.h>
+#include <SDL3_image/SDL_image.h>
+#include <SDL3_ttf/SDL_ttf.h>
+#include <filesystem>
+#include "../../utils/ImagePathResolver.h"
+
+AssetManager::AssetManager() 
+    : m_renderer(nullptr)
+    , m_audioSystem(nullptr)
+    , m_soundSystem(nullptr)
+    , m_totalLoadingTasks(0)
+    , m_completedLoadingTasks(0)
+    , m_loadingComplete(false)
+    , m_defaultTexturePath("assets/images/")
+    , m_defaultFontPath("assets/fonts/")
+    , m_initialized(false) {
+}
+
+AssetManager::~AssetManager() {
+    shutdown();
+}
+
+bool AssetManager::initialize(SDL_Renderer* renderer) {
+    if (m_initialized) {
+        logError("AssetManager already initialized");
+        return false;
+    }
+
+    if (!renderer) {
+        setError("Invalid renderer provided to AssetManager");
+        return false;
+    }
+
+    m_renderer = renderer;
+    
+    // Get references to singleton systems
+    m_audioSystem = &Audio::instance();
+    m_soundSystem = &SoundEffectManager::instance();
+
+    m_initialized = true;
+    logInfo("AssetManager initialized successfully");
+    return true;
+}
+
+void AssetManager::shutdown() {
+    if (!m_initialized) {
+        return;
+    }
+
+    logInfo("Shutting down AssetManager...");
+
+    // Clear loading tasks
+    clearLoadingTasks();
+
+    // Cleanup textures
+    for (auto& [id, texture] : m_textures) {
+        if (texture) {
+            SDL_DestroyTexture(texture);
+            logInfo("Destroyed texture: " + id);
+        }
+    }
+    m_textures.clear();
+
+    // Cleanup fonts (unique_ptr handles destruction)
+    m_fonts.clear();
+
+    // Reset state
+    m_renderer = nullptr;
+    m_audioSystem = nullptr;
+    m_soundSystem = nullptr;
+    m_initialized = false;
+
+    logInfo("AssetManager shutdown complete");
+}
+
+SDL_Texture* AssetManager::loadTexture(const std::string& id, const std::string& filepath) {
+    if (!validateRenderer()) {
+        return nullptr;
+    }
+
+    // Check if already loaded
+    auto it = m_textures.find(id);
+    if (it != m_textures.end()) {
+        logInfo("Texture already loaded: " + id);
+        return it->second;
+    }
+
+    // Load new texture
+    SDL_Texture* texture = loadTextureFromFile(filepath);
+    if (!texture) {
+        setError("Failed to load texture: " + filepath);
+        return nullptr;
+    }
+
+    m_textures[id] = texture;
+    logInfo("Loaded texture: " + id + " from " + filepath);
+    return texture;
+}
+
+SDL_Texture* AssetManager::getTexture(const std::string& id) const {
+    auto it = m_textures.find(id);
+    return (it != m_textures.end()) ? it->second : nullptr;
+}
+
+bool AssetManager::unloadTexture(const std::string& id) {
+    auto it = m_textures.find(id);
+    if (it == m_textures.end()) {
+        setError("Texture not found: " + id);
+        return false;
+    }
+
+    if (it->second) {
+        SDL_DestroyTexture(it->second);
+    }
+    
+    m_textures.erase(it);
+    logInfo("Unloaded texture: " + id);
+    return true;
+}
+
+bool AssetManager::loadFont(const std::string& id, const std::string& filepath, int baseSize) {
+    // Check if already loaded
+    auto it = m_fonts.find(id);
+    if (it != m_fonts.end()) {
+        logInfo("Font already loaded: " + id);
+        return true;
+    }
+
+    // Create new font
+    std::string resolvedPath = AssetPath::resolveWithBase(filepath);
+    auto font = std::make_unique<FontAtlas>();
+    if (!font->init(resolvedPath, baseSize)) {
+        setError("Failed to initialize font: " + resolvedPath);
+        return false;
+    }
+
+    m_fonts[id] = std::move(font);
+    logInfo("Loaded font: " + id + " from " + resolvedPath + " (size: " + std::to_string(baseSize) + ")");
+    return true;
+}
+
+FontAtlas* AssetManager::getFont(const std::string& id) const {
+    auto it = m_fonts.find(id);
+    return (it != m_fonts.end()) ? it->second.get() : nullptr;
+}
+
+bool AssetManager::unloadFont(const std::string& id) {
+    auto it = m_fonts.find(id);
+    if (it == m_fonts.end()) {
+        setError("Font not found: " + id);
+        return false;
+    }
+
+    // Shutdown the font before removing
+    it->second->shutdown();
+    m_fonts.erase(it);
+    logInfo("Unloaded font: " + id);
+    return true;
+}
+
+bool AssetManager::loadMusicTrack(const std::string& filepath) {
+    if (!m_audioSystem) {
+        setError("Audio system not available");
+        return false;
+    }
+
+    std::string resolvedPath = AssetPath::resolveWithBase(filepath);
+
+    if (!fileExists(resolvedPath)) {
+        setError("Music file not found: " + resolvedPath);
+        return false;
+    }
+
+    try {
+        m_audioSystem->addTrackAsync(resolvedPath);
+        logInfo("Added music track for loading: " + resolvedPath);
+        return true;
+    } catch (const std::exception& e) {
+        setError("Failed to add music track: " + std::string(e.what()));
+        return false;
+    }
+}
+
+bool AssetManager::loadSoundEffect(const std::string& id, const std::string& filepath) {
+    if (!m_soundSystem) {
+        setError("Sound effect system not available");
+        return false;
+    }
+
+    std::string resolvedPath = AssetPath::resolveWithBase(filepath);
+
+    if (!fileExists(resolvedPath)) {
+        setError("Sound effect file not found: " + resolvedPath);
+        return false;
+    }
+
+    if (m_soundSystem->loadSound(id, resolvedPath)) {
+        logInfo("Loaded sound effect: " + id + " from " + resolvedPath);
+        return true;
+    } else {
+        setError("Failed to load sound effect: " + id + " from " + resolvedPath);
+        return false;
+    }
+}
+
+bool AssetManager::loadSoundEffectWithFallback(const std::string& id, const std::string& baseName) {
+    if (!m_soundSystem) {
+        setError("Sound effect system not available");
+        return false;
+    }
+
+    const std::string basePath = "assets/music/" + baseName;
+    std::string resolved = AssetPath::resolveWithExtensions(basePath, { ".wav", ".mp3" });
+    if (!resolved.empty() && m_soundSystem->loadSound(id, resolved)) {
+        logInfo("Loaded sound effect: " + id + " from " + resolved);
+        return true;
+    }
+
+    setError("Failed to load sound effect: " + id + " (no supported audio extension found)");
+    return false;
+}
+
+void AssetManager::startBackgroundMusicLoading() {
+    if (!m_audioSystem) {
+        setError("Audio system not available");
+        return;
+    }
+
+    m_audioSystem->startBackgroundLoading();
+    logInfo("Started background music loading");
+}
+
+bool AssetManager::isMusicLoadingComplete() const {
+    if (!m_audioSystem) {
+        return false;
+    }
+
+    return m_audioSystem->isLoadingComplete();
+}
+
+int AssetManager::getLoadedMusicTrackCount() const {
+    if (!m_audioSystem) {
+        return 0;
+    }
+
+    return m_audioSystem->getLoadedTrackCount();
+}
+
+void AssetManager::addLoadingTask(const LoadingTask& task) {
+    m_loadingTasks.push_back(task);
+    logInfo("Added loading task: " + task.id + " (" + task.filepath + ")");
+}
+
+void AssetManager::executeLoadingTasks(std::function<void(float)> progressCallback) {
+    if (m_loadingTasks.empty()) {
+        m_loadingComplete = true;
+        if (progressCallback) progressCallback(1.0f);
+        return;
+    }
+
+    logInfo("Starting progressive loading of " + std::to_string(m_loadingTasks.size()) + " loading tasks...");
+
+    m_totalLoadingTasks = m_loadingTasks.size();
+    m_completedLoadingTasks = 0;
+    m_currentTaskIndex = 0;
+    m_loadingComplete = false;
+    m_isProgressiveLoading = true;
+    m_lastLoadTime = SDL_GetTicks();
+    m_musicLoadingStarted = false;
+    m_musicLoadingProgress = 0.0f;
+    
+    // Don't execute tasks immediately - let update() handle them progressively
+}
+
+void AssetManager::update(float deltaTime) {
+    if (!m_isProgressiveLoading || m_loadingTasks.empty()) {
+        // Handle music loading progress simulation if assets are done
+        if (m_musicLoadingStarted && !m_loadingComplete) {
+            m_musicLoadingProgress += deltaTime * 0.4f; // Simulate music loading progress
+            if (m_musicLoadingProgress >= 1.0f) {
+                m_musicLoadingProgress = 1.0f;
+                m_loadingComplete = true;
+                logInfo("Background music loading simulation complete");
+            }
+        }
+        return;
+    }
+    
+    Uint64 currentTime = SDL_GetTicks();
+    
+    // Add minimum delay between loading items (600ms per item for visual effect)
+    if (currentTime - m_lastLoadTime < 600) {
+        return;
+    }
+    
+    // Load one item at a time
+    if (m_currentTaskIndex < m_loadingTasks.size()) {
+        const auto& task = m_loadingTasks[m_currentTaskIndex];
+        
+        bool success = false;
+        switch (task.type) {
+            case LoadingTask::TEXTURE:
+                success = (loadTexture(task.id, task.filepath) != nullptr);
+                break;
+            case LoadingTask::FONT:
+                success = loadFont(task.id, task.filepath, task.fontSize);
+                break;
+            case LoadingTask::MUSIC:
+                success = loadMusicTrack(task.filepath);
+                break;
+            case LoadingTask::SOUND_EFFECT:
+                success = loadSoundEffect(task.id, task.filepath);
+                break;
+        }
+        
+        if (!success) {
+            logError("Failed to load asset: " + task.id + " (" + task.filepath + ")");
+        }
+        
+        m_currentTaskIndex++;
+        m_completedLoadingTasks = m_currentTaskIndex;
+        m_lastLoadTime = currentTime;
+        
+        logInfo("Asset loading progress: " + std::to_string((float)m_completedLoadingTasks / m_totalLoadingTasks * 100.0f) + "%");
+        
+        // Check if all asset tasks are complete
+        if (m_currentTaskIndex >= m_loadingTasks.size()) {
+            m_isProgressiveLoading = false;
+            logInfo("Completed " + std::to_string(m_completedLoadingTasks) + "/" + std::to_string(m_totalLoadingTasks) + " loading tasks");
+            
+            // Start background music loading simulation
+            m_musicLoadingStarted = true;
+            m_musicLoadingProgress = 0.0f;
+            startBackgroundMusicLoading();
+        }
+    }
+}
+
+void AssetManager::clearLoadingTasks() {
+    m_loadingTasks.clear();
+    logInfo("Cleared loading tasks");
+}
+
+bool AssetManager::isResourceLoaded(const std::string& id) const {
+    return (m_textures.find(id) != m_textures.end()) || 
+           (m_fonts.find(id) != m_fonts.end());
+}
+
+std::string AssetManager::getAssetPath(const std::string& relativePath) {
+    // Simple path construction - could be enhanced with proper path handling
+    if (relativePath.find("assets/") == 0) {
+        return relativePath; // Already has assets/ prefix
+    }
+    return "assets/" + relativePath;
+}
+
+bool AssetManager::fileExists(const std::string& filepath) {
+    std::string resolved = AssetPath::resolveWithBase(filepath);
+    // Use SDL file I/O for consistency with main.cpp pattern
+    SDL_IOStream* file = SDL_IOFromFile(resolved.c_str(), "rb");
+    if (file) {
+        SDL_CloseIO(file);
+        return true;
+    }
+    return false;
+}
+
+SDL_Texture* AssetManager::loadTextureFromFile(const std::string& filepath) {
+    if (!validateRenderer()) {
+        return nullptr;
+    }
+
+    const std::string resolvedPath = AssetPath::resolveImagePath(filepath);
+    SDL_Texture* texture = IMG_LoadTexture(m_renderer, resolvedPath.c_str());
+    if (!texture) {
+        std::string message = "Failed to load texture from: ";
+        message += filepath;
+        message += " (resolved: ";
+        message += resolvedPath;
+        message += ") - ";
+        message += SDL_GetError();
+        setError(message);
+        return nullptr;
+    }
+
+    if (resolvedPath != filepath) {
+        std::string message = "Loaded alternative image path for ";
+        message += filepath;
+        message += ": ";
+        message += resolvedPath;
+        logInfo(message);
+    }
+
+    return texture;
+}
+
+bool AssetManager::validateRenderer() const {
+    if (!m_initialized) {
+        const_cast<AssetManager*>(this)->setError("AssetManager not initialized");
+        return false;
+    }
+
+    if (!m_renderer) {
+        const_cast<AssetManager*>(this)->setError("Invalid renderer");
+        return false;
+    }
+
+    return true;
+}
+
+void AssetManager::setError(const std::string& error) {
+    m_lastError = error;
+    logError(error);
+}
+
+void AssetManager::logInfo(const std::string& message) const {
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[AssetManager] %s", message.c_str());
+}
+
+void AssetManager::logError(const std::string& message) const {
+    SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "[AssetManager] %s", message.c_str());
+}
+
+// Loading progress tracking methods
+bool AssetManager::isLoadingComplete() const {
+    // Loading is complete when both asset tasks and music loading are done
+    return m_loadingComplete && (!m_musicLoadingStarted || m_musicLoadingProgress >= 1.0f);
+}
+
+float AssetManager::getLoadingProgress() const {
+    if (m_totalLoadingTasks == 0) {
+        return 1.0f; // No tasks = complete
+    }
+    
+    // Asset loading progress (80% of total progress)
+    float assetProgress = static_cast<float>(m_completedLoadingTasks) / static_cast<float>(m_totalLoadingTasks) * 0.8f;
+    
+    // Music loading progress (20% of total progress)
+    float musicProgress = m_musicLoadingStarted ? m_musicLoadingProgress * 0.2f : 0.0f;
+    
+    return assetProgress + musicProgress;
+}
+
+// IAssetLoader interface implementation
+SDL_Texture* AssetManager::loadTextureFromPath(const std::string& path) {
+    // Use the path as both ID and filepath for the interface implementation
+    return loadTexture(path, path);
+}
+
+bool AssetManager::loadFontAsset(const std::string& name, const std::string& path, int size) {
+    // Delegate to the existing loadFont method
+    return loadFont(name, path, size);
+}
+
+bool AssetManager::loadAudioAsset(const std::string& name, const std::string& path) {
+    return loadSoundEffect(name, path);
+}
+
+SDL_Texture* AssetManager::getTextureAsset(const std::string& name) {
+    // Delegate to the existing getTexture method
+    return getTexture(name);
+}
+
+bool AssetManager::hasAsset(const std::string& name) const {
+    return m_textures.find(name) != m_textures.end() || 
+           m_fonts.find(name) != m_fonts.end();
+}
+
+void AssetManager::unloadAsset(const std::string& name) {
+    // Try to unload as texture first, then as font
+    if (!unloadTexture(name)) {
+        unloadFont(name);
+    }
+}
+
+void AssetManager::unloadAll() {
+    shutdown();
+}
diff --git a/src/core/assets/AssetManager.h b/src/core/assets/AssetManager.h
new file mode 100644
index 0000000..fbec918
--- /dev/null
+++ b/src/core/assets/AssetManager.h
@@ -0,0 +1,139 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+#include <SDL3_ttf/SDL_ttf.h>
+#include <string>
+#include <unordered_map>
+#include <memory>
+#include <functional>
+#include "../interfaces/IAssetLoader.h"
+#include "../interfaces/IAssetLoader.h"
+
+// Forward declarations
+class FontAtlas;
+class Audio;
+class SoundEffectManager;
+
+/**
+ * AssetManager - Centralized resource management following SOLID principles
+ * 
+ * Responsibilities:
+ * - Texture loading and management (BMP, PNG via SDL)
+ * - Font loading and caching (TTF via FontAtlas)
+ * - Audio resource coordination (MP3 via Audio, WAV via SoundEffectManager)
+ * - Resource lifecycle management (loading, caching, cleanup)
+ * - Error handling and fallback mechanisms
+ * 
+ * Design Principles:
+ * - Single Responsibility: Only handles asset loading/management
+ * - Open/Closed: Easy to extend with new asset types
+ * - Dependency Inversion: Uses interfaces for audio systems
+ * - Interface Segregation: Separate methods for different asset types
+ */
+class AssetManager : public IAssetLoader {
+public:
+    AssetManager();
+    ~AssetManager();
+
+    // Lifecycle management
+    bool initialize(SDL_Renderer* renderer);
+    void shutdown();
+
+    // IAssetLoader interface implementation
+    SDL_Texture* loadTextureFromPath(const std::string& path) override;
+    bool loadFontAsset(const std::string& name, const std::string& path, int size) override;
+    bool loadAudioAsset(const std::string& name, const std::string& path) override;
+    SDL_Texture* getTextureAsset(const std::string& name) override;
+    bool hasAsset(const std::string& name) const override;
+    void unloadAsset(const std::string& name) override;
+    void unloadAll() override;
+
+    // Existing AssetManager methods with specific implementations
+    SDL_Texture* loadTexture(const std::string& id, const std::string& filepath);
+    SDL_Texture* getTexture(const std::string& id) const;
+    bool unloadTexture(const std::string& id);
+    void setDefaultTexturePath(const std::string& path) { m_defaultTexturePath = path; }
+
+    // Font management
+    bool loadFont(const std::string& id, const std::string& filepath, int baseSize = 24);
+    FontAtlas* getFont(const std::string& id) const;
+    bool unloadFont(const std::string& id);
+    void setDefaultFontPath(const std::string& path) { m_defaultFontPath = path; }
+
+    // Audio management (coordinates with existing Audio and SoundEffectManager)
+    bool loadMusicTrack(const std::string& filepath);
+    bool loadSoundEffect(const std::string& id, const std::string& filepath);
+    bool loadSoundEffectWithFallback(const std::string& id, const std::string& baseName);
+    void startBackgroundMusicLoading();
+    bool isMusicLoadingComplete() const;
+    int getLoadedMusicTrackCount() const;
+
+    // Batch loading operations
+    struct LoadingTask {
+        enum Type { TEXTURE, FONT, MUSIC, SOUND_EFFECT };
+        Type type;
+        std::string id;
+        std::string filepath;
+        int fontSize = 24; // For fonts only
+    };
+    
+    void addLoadingTask(const LoadingTask& task);
+    void executeLoadingTasks(std::function<void(float)> progressCallback = nullptr);
+    void clearLoadingTasks();
+    void update(float deltaTime); // New: Progressive loading update
+    
+    // Loading progress tracking
+    bool isLoadingComplete() const;
+    float getLoadingProgress() const;
+    size_t getTotalLoadingTasks() const { return m_totalLoadingTasks; }
+    size_t getCompletedLoadingTasks() const { return m_completedLoadingTasks; }
+
+    // Resource queries
+    size_t getTextureCount() const { return m_textures.size(); }
+    size_t getFontCount() const { return m_fonts.size(); }
+    bool isResourceLoaded(const std::string& id) const;
+
+    // Error handling
+    std::string getLastError() const { return m_lastError; }
+    void clearLastError() { m_lastError.clear(); }
+
+    // Asset path utilities
+    static std::string getAssetPath(const std::string& relativePath);
+    static bool fileExists(const std::string& filepath);
+
+private:
+    // Resource storage
+    std::unordered_map<std::string, SDL_Texture*> m_textures;
+    std::unordered_map<std::string, std::unique_ptr<FontAtlas>> m_fonts;
+    std::vector<LoadingTask> m_loadingTasks;
+    
+    // Loading progress tracking
+    size_t m_totalLoadingTasks = 0;
+    size_t m_completedLoadingTasks = 0;
+    bool m_loadingComplete = false;
+    
+    // Progressive loading state
+    bool m_isProgressiveLoading = false;
+    size_t m_currentTaskIndex = 0;
+    Uint64 m_lastLoadTime = 0;
+    bool m_musicLoadingStarted = false;
+    float m_musicLoadingProgress = 0.0f;
+
+    // System references
+    SDL_Renderer* m_renderer;
+    Audio* m_audioSystem;              // Pointer to singleton
+    SoundEffectManager* m_soundSystem; // Pointer to singleton
+
+    // Configuration
+    std::string m_defaultTexturePath;
+    std::string m_defaultFontPath;
+    std::string m_lastError;
+    bool m_initialized;
+
+    // Helper methods
+    SDL_Texture* loadTextureFromFile(const std::string& filepath);
+    bool validateRenderer() const;
+    void setError(const std::string& error);
+    void logInfo(const std::string& message) const;
+    void logError(const std::string& message) const;
+};
diff --git a/src/core/container/ServiceContainer.h b/src/core/container/ServiceContainer.h
new file mode 100644
index 0000000..310f208
--- /dev/null
+++ b/src/core/container/ServiceContainer.h
@@ -0,0 +1,93 @@
+#pragma once
+
+#include <memory>
+#include <unordered_map>
+#include <typeindex>
+#include <functional>
+
+/**
+ * @brief Simple dependency injection container
+ * 
+ * Provides service registration and resolution for dependency injection.
+ * Supports both singleton and factory-based service creation.
+ */
+class ServiceContainer {
+public:
+    ServiceContainer() = default;
+    ~ServiceContainer() = default;
+
+    /**
+     * @brief Register a singleton service instance
+     * @tparam TInterface Interface type
+     * @tparam TImplementation Implementation type
+     * @param instance Shared pointer to the service instance
+     */
+    template<typename TInterface, typename TImplementation>
+    void registerSingleton(std::shared_ptr<TImplementation> instance) {
+        static_assert(std::is_base_of_v<TInterface, TImplementation>, 
+                      "TImplementation must inherit from TInterface");
+        
+        m_singletons[std::type_index(typeid(TInterface))] = instance;
+    }
+
+    /**
+     * @brief Register a factory function for service creation
+     * @tparam TInterface Interface type
+     * @param factory Factory function that creates the service
+     */
+    template<typename TInterface>
+    void registerFactory(std::function<std::shared_ptr<TInterface>()> factory) {
+        m_factories[std::type_index(typeid(TInterface))] = [factory]() -> std::shared_ptr<void> {
+            return std::static_pointer_cast<void>(factory());
+        };
+    }
+
+    /**
+     * @brief Resolve a service by its interface type
+     * @tparam TInterface Interface type to resolve
+     * @return Shared pointer to the service instance, nullptr if not found
+     */
+    template<typename TInterface>
+    std::shared_ptr<TInterface> resolve() {
+        std::type_index typeIndex(typeid(TInterface));
+        
+        // Check singletons first
+        auto singletonIt = m_singletons.find(typeIndex);
+        if (singletonIt != m_singletons.end()) {
+            return std::static_pointer_cast<TInterface>(singletonIt->second);
+        }
+        
+        // Check factories
+        auto factoryIt = m_factories.find(typeIndex);
+        if (factoryIt != m_factories.end()) {
+            auto instance = factoryIt->second();
+            return std::static_pointer_cast<TInterface>(instance);
+        }
+        
+        return nullptr;
+    }
+
+    /**
+     * @brief Check if a service is registered
+     * @tparam TInterface Interface type to check
+     * @return true if service is registered, false otherwise
+     */
+    template<typename TInterface>
+    bool isRegistered() const {
+        std::type_index typeIndex(typeid(TInterface));
+        return m_singletons.find(typeIndex) != m_singletons.end() ||
+               m_factories.find(typeIndex) != m_factories.end();
+    }
+
+    /**
+     * @brief Clear all registered services
+     */
+    void clear() {
+        m_singletons.clear();
+        m_factories.clear();
+    }
+
+private:
+    std::unordered_map<std::type_index, std::shared_ptr<void>> m_singletons;
+    std::unordered_map<std::type_index, std::function<std::shared_ptr<void>()>> m_factories;
+};
diff --git a/src/core/input/InputManager.cpp b/src/core/input/InputManager.cpp
new file mode 100644
index 0000000..b1b69f3
--- /dev/null
+++ b/src/core/input/InputManager.cpp
@@ -0,0 +1,361 @@
+#include "InputManager.h"
+#include <SDL3/SDL.h>
+#include <algorithm>
+
+InputManager::InputManager() {
+    SDL_LogInfo(SDL_LOG_CATEGORY_INPUT, "InputManager initialized");
+}
+
+void InputManager::processEvents() {
+    // Update previous state before processing new events
+    updateInputState();
+
+    // Reset mouse delta
+    m_mouseDeltaX = 0.0f;
+    m_mouseDeltaY = 0.0f;
+
+    SDL_Event event;
+    while (SDL_PollEvent(&event)) {
+        // Trace every polled event type for debugging abrupt termination
+        {
+            FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "InputManager: polled event type=%d\n", (int)event.type); fclose(f); }
+        }
+        switch (event.type) {
+            case SDL_EVENT_QUIT:
+            case SDL_EVENT_WINDOW_CLOSE_REQUESTED:
+                handleQuitEvent();
+                break;
+
+            case SDL_EVENT_KEY_DOWN:
+            case SDL_EVENT_KEY_UP:
+                handleKeyEvent(event.key);
+                break;
+
+            case SDL_EVENT_MOUSE_BUTTON_DOWN:
+            case SDL_EVENT_MOUSE_BUTTON_UP:
+                handleMouseButtonEvent(event.button);
+                break;
+
+            case SDL_EVENT_MOUSE_MOTION:
+                handleMouseMotionEvent(event.motion);
+                break;
+
+            case SDL_EVENT_WINDOW_RESIZED:
+            case SDL_EVENT_WINDOW_MOVED:
+            case SDL_EVENT_WINDOW_MINIMIZED:
+            case SDL_EVENT_WINDOW_MAXIMIZED:
+            case SDL_EVENT_WINDOW_RESTORED:
+                handleWindowEvent(event.window);
+                break;
+
+            default:
+                // Unhandled event types
+                break;
+        }
+    }
+}
+
+void InputManager::update(float deltaTime) {
+    updateDAS(deltaTime);
+}
+
+bool InputManager::isKeyPressed(SDL_Scancode key) const {
+    auto current = m_currentKeyState.find(key);
+    auto previous = m_previousKeyState.find(key);
+    
+    bool currentlyPressed = (current != m_currentKeyState.end() && current->second);
+    bool previouslyPressed = (previous != m_previousKeyState.end() && previous->second);
+    
+    return currentlyPressed && !previouslyPressed;
+}
+
+bool InputManager::isKeyReleased(SDL_Scancode key) const {
+    auto current = m_currentKeyState.find(key);
+    auto previous = m_previousKeyState.find(key);
+    
+    bool currentlyPressed = (current != m_currentKeyState.end() && current->second);
+    bool previouslyPressed = (previous != m_previousKeyState.end() && previous->second);
+    
+    return !currentlyPressed && previouslyPressed;
+}
+
+bool InputManager::isKeyHeld(SDL_Scancode key) const {
+    auto it = m_currentKeyState.find(key);
+    return (it != m_currentKeyState.end() && it->second);
+}
+
+bool InputManager::isMouseButtonPressed(int button) const {
+    auto current = m_currentMouseState.find(button);
+    auto previous = m_previousMouseState.find(button);
+    
+    bool currentlyPressed = (current != m_currentMouseState.end() && current->second);
+    bool previouslyPressed = (previous != m_previousMouseState.end() && previous->second);
+    
+    return currentlyPressed && !previouslyPressed;
+}
+
+bool InputManager::isMouseButtonReleased(int button) const {
+    auto current = m_currentMouseState.find(button);
+    auto previous = m_previousMouseState.find(button);
+    
+    bool currentlyPressed = (current != m_currentMouseState.end() && current->second);
+    bool previouslyPressed = (previous != m_previousMouseState.end() && previous->second);
+    
+    return !currentlyPressed && previouslyPressed;
+}
+
+bool InputManager::isMouseButtonHeld(int button) const {
+    auto it = m_currentMouseState.find(button);
+    return (it != m_currentMouseState.end() && it->second);
+}
+
+void InputManager::getMousePosition(float& x, float& y) const {
+    x = m_mouseX;
+    y = m_mouseY;
+}
+
+void InputManager::getMouseDelta(float& deltaX, float& deltaY) const {
+    deltaX = m_mouseDeltaX;
+    deltaY = m_mouseDeltaY;
+}
+
+void InputManager::registerKeyHandler(KeyHandler handler) {
+    m_keyHandlers.push_back(std::move(handler));
+}
+
+void InputManager::registerMouseButtonHandler(MouseButtonHandler handler) {
+    m_mouseButtonHandlers.push_back(std::move(handler));
+}
+
+void InputManager::registerMouseMotionHandler(MouseMotionHandler handler) {
+    m_mouseMotionHandlers.push_back(std::move(handler));
+}
+
+void InputManager::registerWindowEventHandler(WindowEventHandler handler) {
+    m_windowEventHandlers.push_back(std::move(handler));
+}
+
+void InputManager::registerQuitHandler(QuitHandler handler) {
+    m_quitHandlers.push_back(std::move(handler));
+}
+
+void InputManager::configureDAS(float delayMs, float repeatMs) {
+    m_dasDelay = delayMs;
+    m_dasRepeat = repeatMs;
+    SDL_LogInfo(SDL_LOG_CATEGORY_INPUT, "DAS configured: delay=%.1fms, repeat=%.1fms", delayMs, repeatMs);
+}
+
+bool InputManager::checkDASMovement(SDL_Scancode leftKey, SDL_Scancode rightKey, int& direction) {
+    bool leftHeld = isKeyHeld(leftKey);
+    bool rightHeld = isKeyHeld(rightKey);
+
+    // Determine current direction
+    int currentDirection = 0;
+    if (leftHeld && !rightHeld) {
+        currentDirection = -1;
+    } else if (rightHeld && !leftHeld) {
+        currentDirection = 1;
+    }
+
+    // If no direction or direction changed, reset DAS
+    if (currentDirection == 0 || 
+        (m_dasState.isActive && 
+         ((currentDirection == -1 && m_dasState.activeKey != leftKey) ||
+          (currentDirection == 1 && m_dasState.activeKey != rightKey)))) {
+        resetDAS();
+        direction = 0;
+        return false;
+    }
+
+    // Check for initial key press (immediate movement)
+    if ((currentDirection == -1 && isKeyPressed(leftKey)) ||
+        (currentDirection == 1 && isKeyPressed(rightKey))) {
+        m_dasState.isActive = true;
+        m_dasState.delayTimer = m_dasDelay;
+        m_dasState.repeatTimer = 0.0f;
+        m_dasState.activeKey = (currentDirection == -1) ? leftKey : rightKey;
+        direction = currentDirection;
+        return true;
+    }
+
+    // If DAS is active and delay/repeat timers expired, trigger movement
+    if (m_dasState.isActive && m_dasState.delayTimer <= 0.0f && m_dasState.repeatTimer <= 0.0f) {
+        m_dasState.repeatTimer = m_dasRepeat;
+        direction = currentDirection;
+        return true;
+    }
+
+    direction = 0;
+    return false;
+}
+
+void InputManager::handleKeyEvent(const SDL_KeyboardEvent& event) {
+    SDL_Scancode scancode = event.scancode;
+    bool pressed = (event.type == SDL_EVENT_KEY_DOWN) && !event.repeat;
+    bool released = (event.type == SDL_EVENT_KEY_UP);
+
+    if (pressed) {
+        m_currentKeyState[scancode] = true;
+    } else if (released) {
+        m_currentKeyState[scancode] = false;
+    }
+
+    // Notify handlers
+    for (auto& handler : m_keyHandlers) {
+        try {
+            handler(scancode, pressed);
+        } catch (const std::exception& e) {
+            SDL_LogError(SDL_LOG_CATEGORY_INPUT, "Exception in key handler: %s", e.what());
+        }
+    }
+}
+
+void InputManager::handleMouseButtonEvent(const SDL_MouseButtonEvent& event) {
+    int button = event.button;
+    bool pressed = (event.type == SDL_EVENT_MOUSE_BUTTON_DOWN);
+    
+    m_currentMouseState[button] = pressed;
+
+    // Notify handlers
+    for (auto& handler : m_mouseButtonHandlers) {
+        try {
+            handler(button, pressed, event.x, event.y);
+        } catch (const std::exception& e) {
+            SDL_LogError(SDL_LOG_CATEGORY_INPUT, "Exception in mouse button handler: %s", e.what());
+        }
+    }
+}
+
+void InputManager::handleMouseMotionEvent(const SDL_MouseMotionEvent& event) {
+    float newX = event.x;
+    float newY = event.y;
+    
+    m_mouseDeltaX = newX - m_mouseX;
+    m_mouseDeltaY = newY - m_mouseY;
+    m_mouseX = newX;
+    m_mouseY = newY;
+
+    // Notify handlers
+    for (auto& handler : m_mouseMotionHandlers) {
+        try {
+            handler(m_mouseX, m_mouseY, m_mouseDeltaX, m_mouseDeltaY);
+        } catch (const std::exception& e) {
+            SDL_LogError(SDL_LOG_CATEGORY_INPUT, "Exception in mouse motion handler: %s", e.what());
+        }
+    }
+}
+
+void InputManager::handleWindowEvent(const SDL_WindowEvent& event) {
+    if (event.type == SDL_EVENT_WINDOW_CLOSE_REQUESTED) {
+        handleQuitEvent();
+    }
+
+    // Notify handlers
+    for (auto& handler : m_windowEventHandlers) {
+        try {
+            handler(event);
+        } catch (const std::exception& e) {
+            SDL_LogError(SDL_LOG_CATEGORY_INPUT, "Exception in window event handler: %s", e.what());
+        }
+    }
+}
+
+void InputManager::updateInputState() {
+    // Copy current state to previous state
+    m_previousKeyState = m_currentKeyState;
+    m_previousMouseState = m_currentMouseState;
+}
+
+void InputManager::updateDAS(float deltaTime) {
+    if (!m_dasState.isActive) {
+        return;
+    }
+
+    float deltaMs = deltaTime * 1000.0f; // Convert to milliseconds
+
+    // Update delay timer
+    if (m_dasState.delayTimer > 0.0f) {
+        m_dasState.delayTimer -= deltaMs;
+    }
+
+    // Update repeat timer (only if delay has expired)
+    if (m_dasState.delayTimer <= 0.0f && m_dasState.repeatTimer > 0.0f) {
+        m_dasState.repeatTimer -= deltaMs;
+    }
+}
+
+void InputManager::resetDAS() {
+    m_dasState.isActive = false;
+    m_dasState.delayTimer = 0.0f;
+    m_dasState.repeatTimer = 0.0f;
+    m_dasState.activeKey = SDL_SCANCODE_UNKNOWN;
+}
+
+// IInputHandler interface implementation
+bool InputManager::processEvent(const SDL_Event& event) {
+    // Process individual event and return if it was handled
+    switch (event.type) {
+        case SDL_EVENT_KEY_DOWN:
+        case SDL_EVENT_KEY_UP:
+            handleKeyEvent(event.key);
+            return true;
+        case SDL_EVENT_MOUSE_BUTTON_DOWN:
+        case SDL_EVENT_MOUSE_BUTTON_UP:
+            handleMouseButtonEvent(event.button);
+            return true;
+        case SDL_EVENT_MOUSE_MOTION:
+            handleMouseMotionEvent(event.motion);
+            return true;
+        case SDL_EVENT_WINDOW_RESIZED:
+        case SDL_EVENT_WINDOW_CLOSE_REQUESTED:
+        case SDL_EVENT_WINDOW_MINIMIZED:
+        case SDL_EVENT_WINDOW_RESTORED:
+            handleWindowEvent(event.window);
+            return true;
+        case SDL_EVENT_QUIT:
+            handleQuitEvent();
+            return true;
+        default:
+            return false;
+    }
+}
+
+void InputManager::update(double deltaTime) {
+    update(static_cast<float>(deltaTime));
+}
+
+bool InputManager::isKeyCurrentlyPressed(SDL_Scancode scancode) const {
+    return isKeyHeld(scancode);
+}
+
+bool InputManager::isKeyJustPressed(SDL_Scancode scancode) const {
+    return isKeyPressed(scancode);
+}
+
+bool InputManager::isKeyJustReleased(SDL_Scancode scancode) const {
+    return isKeyReleased(scancode);
+}
+
+bool InputManager::isQuitRequested() const {
+    return shouldQuit();
+}
+
+void InputManager::reset() {
+    // Clear pressed/released states, keep held states
+    // In the current InputManager implementation, we use previous/current state
+    // so we just copy current to previous to reset the "just pressed/released" states
+    m_previousKeyState = m_currentKeyState;
+    m_previousMouseState = m_currentMouseState;
+}
+
+void InputManager::handleQuitEvent() {
+    FILE* f = fopen("spacetris_trace.log", "a");
+    if (f) {
+        fprintf(f, "InputManager::handleQuitEvent invoked\n");
+        fclose(f);
+    }
+    m_shouldQuit = true;
+    for (auto& handler : m_quitHandlers) {
+        handler();
+    }
+}
diff --git a/src/core/input/InputManager.h b/src/core/input/InputManager.h
new file mode 100644
index 0000000..e3419f4
--- /dev/null
+++ b/src/core/input/InputManager.h
@@ -0,0 +1,115 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+#include <unordered_map>
+#include <functional>
+#include <vector>
+#include "../interfaces/IInputHandler.h"
+
+/**
+ * InputManager - Centralized input handling system
+ * 
+ * Responsibilities:
+ * - Process SDL events and maintain input state
+ * - Provide clean interface for input queries
+ * - Handle keyboard and mouse input
+ * - Support event handler registration
+ * - Implement game-specific input logic (DAS/ARR)
+ */
+class InputManager : public IInputHandler {
+public:
+    // Event handler types
+    using KeyHandler = std::function<void(SDL_Scancode key, bool pressed)>;
+    using MouseButtonHandler = std::function<void(int button, bool pressed, float x, float y)>;
+    using MouseMotionHandler = std::function<void(float x, float y, float deltaX, float deltaY)>;
+    using WindowEventHandler = std::function<void(const SDL_WindowEvent& event)>;
+    using QuitHandler = std::function<void()>;
+
+    InputManager();
+    ~InputManager() = default;
+
+    // IInputHandler interface implementation
+    bool processEvent(const SDL_Event& event) override;
+    void update(double deltaTime) override;
+    bool isKeyCurrentlyPressed(SDL_Scancode scancode) const override;
+    bool isKeyJustPressed(SDL_Scancode scancode) const override;
+    bool isKeyJustReleased(SDL_Scancode scancode) const override;
+    bool isQuitRequested() const override;
+    void reset() override;
+
+    // Existing InputManager methods
+    void processEvents();
+    void update(float deltaTime);
+
+    // Keyboard state queries
+    bool isKeyPressed(SDL_Scancode key) const;      // True only on the frame key was pressed
+    bool isKeyReleased(SDL_Scancode key) const;     // True only on the frame key was released  
+    bool isKeyHeld(SDL_Scancode key) const;         // True while key is down
+
+    // Mouse state queries
+    bool isMouseButtonPressed(int button) const;
+    bool isMouseButtonReleased(int button) const;
+    bool isMouseButtonHeld(int button) const;
+    void getMousePosition(float& x, float& y) const;
+    void getMouseDelta(float& deltaX, float& deltaY) const;
+
+    // Event handler registration
+    void registerKeyHandler(KeyHandler handler);
+    void registerMouseButtonHandler(MouseButtonHandler handler);
+    void registerMouseMotionHandler(MouseMotionHandler handler);
+    void registerWindowEventHandler(WindowEventHandler handler);
+    void registerQuitHandler(QuitHandler handler);
+
+    // Game-specific input utilities (DAS/ARR system for Tetris)
+    struct DASState {
+        bool isActive = false;
+        float delayTimer = 0.0f;
+        float repeatTimer = 0.0f;
+        SDL_Scancode activeKey = SDL_SCANCODE_UNKNOWN;
+    };
+
+    void configureDAS(float delayMs, float repeatMs);
+    bool checkDASMovement(SDL_Scancode leftKey, SDL_Scancode rightKey, int& direction);
+
+    // Application control
+    bool shouldQuit() const { return m_shouldQuit; }
+    void requestQuit() { m_shouldQuit = true; }
+
+private:
+    // Input state tracking
+    std::unordered_map<SDL_Scancode, bool> m_currentKeyState;
+    std::unordered_map<SDL_Scancode, bool> m_previousKeyState;
+    std::unordered_map<int, bool> m_currentMouseState;
+    std::unordered_map<int, bool> m_previousMouseState;
+
+    // Mouse position tracking
+    float m_mouseX = 0.0f;
+    float m_mouseY = 0.0f;
+    float m_mouseDeltaX = 0.0f;
+    float m_mouseDeltaY = 0.0f;
+
+    // Event handlers
+    std::vector<KeyHandler> m_keyHandlers;
+    std::vector<MouseButtonHandler> m_mouseButtonHandlers;
+    std::vector<MouseMotionHandler> m_mouseMotionHandlers;
+    std::vector<WindowEventHandler> m_windowEventHandlers;
+    std::vector<QuitHandler> m_quitHandlers;
+
+    // Application state
+    bool m_shouldQuit = false;
+
+    // DAS/ARR system for Tetris-style movement
+    DASState m_dasState;
+    float m_dasDelay = 170.0f;    // Default DAS delay in ms
+    float m_dasRepeat = 40.0f;    // Default ARR (Auto Repeat Rate) in ms
+
+    // Helper methods
+    void handleKeyEvent(const SDL_KeyboardEvent& event);
+    void handleMouseButtonEvent(const SDL_MouseButtonEvent& event);
+    void handleMouseMotionEvent(const SDL_MouseMotionEvent& event);
+    void handleWindowEvent(const SDL_WindowEvent& event);
+    void handleQuitEvent();
+    void updateInputState();
+    void updateDAS(float deltaTime);
+    void resetDAS();
+};
diff --git a/src/core/interfaces/IAssetLoader.h b/src/core/interfaces/IAssetLoader.h
new file mode 100644
index 0000000..440425c
--- /dev/null
+++ b/src/core/interfaces/IAssetLoader.h
@@ -0,0 +1,64 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+#include <string>
+
+/**
+ * @brief Abstract interface for asset loading operations
+ * 
+ * Provides a common interface for loading different types of assets,
+ * enabling dependency injection and easier testing.
+ */
+class IAssetLoader {
+public:
+    virtual ~IAssetLoader() = default;
+    
+    /**
+     * @brief Load a texture from file (interface method)
+     * @param path Path to the texture file
+     * @return Pointer to loaded SDL_Texture, nullptr on failure
+     */
+    virtual SDL_Texture* loadTextureFromPath(const std::string& path) = 0;
+    
+    /**
+     * @brief Load a font from file (interface method)
+     * @param name Font identifier/name
+     * @param path Path to the font file
+     * @param size Font size in pixels
+     * @return true if font was loaded successfully, false otherwise
+     */
+    virtual bool loadFontAsset(const std::string& name, const std::string& path, int size) = 0;
+    
+    /**
+     * @brief Load an audio file (interface method)
+     * @param name Audio identifier/name
+     * @param path Path to the audio file
+     * @return true if audio was loaded successfully, false otherwise
+     */
+    virtual bool loadAudioAsset(const std::string& name, const std::string& path) = 0;
+    
+    /**
+     * @brief Get a previously loaded texture (interface method)
+     * @param name Texture identifier/name
+     * @return Pointer to SDL_Texture, nullptr if not found
+     */
+    virtual SDL_Texture* getTextureAsset(const std::string& name) = 0;
+    
+    /**
+     * @brief Check if an asset exists
+     * @param name Asset identifier/name
+     * @return true if asset exists, false otherwise
+     */
+    virtual bool hasAsset(const std::string& name) const = 0;
+    
+    /**
+     * @brief Unload a specific asset
+     * @param name Asset identifier/name
+     */
+    virtual void unloadAsset(const std::string& name) = 0;
+    
+    /**
+     * @brief Unload all assets
+     */
+    virtual void unloadAll() = 0;
+};
diff --git a/src/core/interfaces/IAudioSystem.h b/src/core/interfaces/IAudioSystem.h
new file mode 100644
index 0000000..4e4ac95
--- /dev/null
+++ b/src/core/interfaces/IAudioSystem.h
@@ -0,0 +1,55 @@
+#pragma once
+
+#include <string>
+
+/**
+ * @brief Abstract interface for audio system operations
+ * 
+ * Provides a common interface for audio playback, enabling
+ * dependency injection and easier testing.
+ */
+class IAudioSystem {
+public:
+    virtual ~IAudioSystem() = default;
+    
+    /**
+     * @brief Play a sound effect
+     * @param name Sound effect name/identifier
+     */
+    virtual void playSound(const std::string& name) = 0;
+    
+    /**
+     * @brief Play background music
+     * @param name Music track name/identifier
+     */
+    virtual void playMusic(const std::string& name) = 0;
+    
+    /**
+     * @brief Stop currently playing music
+     */
+    virtual void stopMusic() = 0;
+    
+    /**
+     * @brief Set master volume for all audio
+     * @param volume Volume level (0.0 to 1.0)
+     */
+    virtual void setMasterVolume(float volume) = 0;
+    
+    /**
+     * @brief Set music volume
+     * @param volume Volume level (0.0 to 1.0)
+     */
+    virtual void setMusicVolume(float volume) = 0;
+    
+    /**
+     * @brief Set sound effects volume
+     * @param volume Volume level (0.0 to 1.0)
+     */
+    virtual void setSoundVolume(float volume) = 0;
+    
+    /**
+     * @brief Check if music is currently playing
+     * @return true if music is playing, false otherwise
+     */
+    virtual bool isMusicPlaying() const = 0;
+};
diff --git a/src/core/interfaces/IGameRules.h b/src/core/interfaces/IGameRules.h
new file mode 100644
index 0000000..58bdbdf
--- /dev/null
+++ b/src/core/interfaces/IGameRules.h
@@ -0,0 +1,73 @@
+#pragma once
+
+/**
+ * @brief Abstract interface for game rules
+ * 
+ * Provides a common interface for different Tetris rule implementations,
+ * enabling different game modes and rule variations.
+ */
+class IGameRules {
+public:
+    virtual ~IGameRules() = default;
+    
+    /**
+     * @brief Calculate score for cleared lines
+     * @param linesCleared Number of lines cleared simultaneously
+     * @param level Current game level
+     * @return Score points to award
+     */
+    virtual int calculateScore(int linesCleared, int level) const = 0;
+    
+    /**
+     * @brief Get gravity speed for a given level
+     * @param level Game level
+     * @return Time in milliseconds for one gravity drop
+     */
+    virtual double getGravitySpeed(int level) const = 0;
+    
+    /**
+     * @brief Check if level should increase
+     * @param totalLines Total lines cleared so far
+     * @param currentLevel Current game level
+     * @return true if level should increase, false otherwise
+     */
+    virtual bool shouldLevelUp(int totalLines, int currentLevel) const = 0;
+    
+    /**
+     * @brief Calculate next level based on lines cleared
+     * @param totalLines Total lines cleared so far
+     * @param startLevel Starting level
+     * @return New level
+     */
+    virtual int calculateLevel(int totalLines, int startLevel) const = 0;
+    
+    /**
+     * @brief Get soft drop speed multiplier
+     * @return Multiplier for gravity when soft dropping
+     */
+    virtual double getSoftDropMultiplier() const = 0;
+    
+    /**
+     * @brief Get hard drop score per cell
+     * @return Points awarded per cell for hard drop
+     */
+    virtual int getHardDropScore() const = 0;
+    
+    /**
+     * @brief Get soft drop score per cell
+     * @return Points awarded per cell for soft drop
+     */
+    virtual int getSoftDropScore() const = 0;
+    
+    /**
+     * @brief Check if T-spins are enabled in this rule set
+     * @return true if T-spins are supported, false otherwise
+     */
+    virtual bool supportsTSpins() const = 0;
+    
+    /**
+     * @brief Check if hold feature is enabled in this rule set
+     * @return true if hold is supported, false otherwise
+     */
+    virtual bool supportsHold() const = 0;
+};
diff --git a/src/core/interfaces/IInputHandler.h b/src/core/interfaces/IInputHandler.h
new file mode 100644
index 0000000..ac37264
--- /dev/null
+++ b/src/core/interfaces/IInputHandler.h
@@ -0,0 +1,59 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+
+/**
+ * @brief Abstract interface for input handling operations
+ * 
+ * Provides a common interface for input processing,
+ * enabling dependency injection and easier testing.
+ */
+class IInputHandler {
+public:
+    virtual ~IInputHandler() = default;
+    
+    /**
+     * @brief Process SDL events
+     * @param event SDL event to process
+     * @return true if event was handled, false otherwise
+     */
+    virtual bool processEvent(const SDL_Event& event) = 0;
+    
+    /**
+     * @brief Update input state (called per frame)
+     * @param deltaTime Time elapsed since last frame in milliseconds
+     */
+    virtual void update(double deltaTime) = 0;
+    
+    /**
+     * @brief Check if a key is currently pressed (interface method)
+     * @param scancode SDL scancode of the key
+     * @return true if key is pressed, false otherwise
+     */
+    virtual bool isKeyCurrentlyPressed(SDL_Scancode scancode) const = 0;
+    
+    /**
+     * @brief Check if a key was just pressed this frame
+     * @param scancode SDL scancode of the key
+     * @return true if key was just pressed, false otherwise
+     */
+    virtual bool isKeyJustPressed(SDL_Scancode scancode) const = 0;
+    
+    /**
+     * @brief Check if a key was just released this frame
+     * @param scancode SDL scancode of the key
+     * @return true if key was just released, false otherwise
+     */
+    virtual bool isKeyJustReleased(SDL_Scancode scancode) const = 0;
+    
+    /**
+     * @brief Check if quit was requested (e.g., Alt+F4, window close)
+     * @return true if quit was requested, false otherwise
+     */
+    virtual bool isQuitRequested() const = 0;
+    
+    /**
+     * @brief Reset input state (typically called at frame start)
+     */
+    virtual void reset() = 0;
+};
diff --git a/src/core/interfaces/IRenderer.h b/src/core/interfaces/IRenderer.h
new file mode 100644
index 0000000..b8bb187
--- /dev/null
+++ b/src/core/interfaces/IRenderer.h
@@ -0,0 +1,56 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+#include <cstdint>
+
+/**
+ * @brief Abstract interface for rendering operations
+ * 
+ * Provides a common interface for different rendering implementations,
+ * enabling dependency injection and easier testing.
+ */
+class IRenderer {
+public:
+    virtual ~IRenderer() = default;
+    
+    /**
+     * @brief Clear the render target with specified color (interface method)
+     * @param r Red component (0-255)
+     * @param g Green component (0-255)
+     * @param b Blue component (0-255)
+     * @param a Alpha component (0-255)
+     */
+    virtual void clearScreen(uint8_t r, uint8_t g, uint8_t b, uint8_t a) = 0;
+    
+    /**
+     * @brief Present the rendered frame to the display
+     */
+    virtual void present() = 0;
+    
+    /**
+     * @brief Get the underlying SDL renderer for direct operations
+     * @return Pointer to SDL_Renderer
+     * @note This is provided for compatibility with existing code
+     */
+    virtual SDL_Renderer* getSDLRenderer() = 0;
+    
+    /**
+     * @brief Get the current window size (interface method)
+     * @param width Output parameter for window width
+     * @param height Output parameter for window height
+     */
+    virtual void getWindowDimensions(int& width, int& height) const = 0;
+    
+    /**
+     * @brief Set the render viewport
+     * @param viewport Viewport rectangle
+     */
+    virtual void setViewport(const SDL_Rect* viewport) = 0;
+    
+    /**
+     * @brief Set the render scale
+     * @param scaleX Horizontal scale factor
+     * @param scaleY Vertical scale factor
+     */
+    virtual void setScale(float scaleX, float scaleY) = 0;
+};
diff --git a/src/core/state/StateManager.cpp b/src/core/state/StateManager.cpp
new file mode 100644
index 0000000..7d526a2
--- /dev/null
+++ b/src/core/state/StateManager.cpp
@@ -0,0 +1,236 @@
+#include "StateManager.h"
+#include "../../graphics/renderers/RenderManager.h"
+#include <SDL3/SDL.h>
+
+StateManager::StateManager(AppState initial)
+    : m_currentState(initial)
+    , m_previousState(initial)
+{
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "StateManager initialized with state: %s", getStateName(initial));
+}
+
+void StateManager::registerEventHandler(AppState state, EventHandler handler) {
+    if (!isValidState(state)) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Invalid state for event handler registration");
+        return;
+    }
+    
+    m_eventHandlers[stateToInt(state)].push_back(std::move(handler));
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "Event handler registered for state: %s", getStateName(state));
+}
+
+void StateManager::registerUpdateHandler(AppState state, UpdateHandler handler) {
+    if (!isValidState(state)) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Invalid state for update handler registration");
+        return;
+    }
+    
+    m_updateHandlers[stateToInt(state)].push_back(std::move(handler));
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "Update handler registered for state: %s", getStateName(state));
+}
+
+void StateManager::registerRenderHandler(AppState state, RenderHandler handler) {
+    if (!isValidState(state)) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Invalid state for render handler registration");
+        return;
+    }
+    
+    m_renderHandlers[stateToInt(state)].push_back(std::move(handler));
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "Render handler registered for state: %s", getStateName(state));
+}
+
+void StateManager::registerOnEnter(AppState state, Hook hook) {
+    if (!isValidState(state)) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Invalid state for enter hook registration");
+        return;
+    }
+    
+    m_onEnterHooks[stateToInt(state)].push_back(std::move(hook));
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "Enter hook registered for state: %s", getStateName(state));
+}
+
+void StateManager::registerOnExit(AppState state, Hook hook) {
+    if (!isValidState(state)) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Invalid state for exit hook registration");
+        return;
+    }
+    
+    m_onExitHooks[stateToInt(state)].push_back(std::move(hook));
+    SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "Exit hook registered for state: %s", getStateName(state));
+}
+
+// Legacy compatibility: overload accepting a no-arg function as handler
+void StateManager::registerHandler(AppState s, std::function<void()> h) {
+    EventHandler wrapper = [h = std::move(h)](const SDL_Event&) { h(); };
+    registerEventHandler(s, std::move(wrapper));
+}
+
+bool StateManager::setState(AppState newState) {
+    if (!isValidState(newState)) {
+        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Attempted to set invalid state");
+        return false;
+    }
+
+    if (newState == m_currentState) {
+        SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "Attempted to set same state: %s", getStateName(newState));
+        return true;
+    }
+
+    if (!canTransitionTo(newState)) {
+        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "Invalid state transition from %s to %s", 
+                   getStateName(m_currentState), getStateName(newState));
+        return false;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "State transition: %s -> %s", 
+               getStateName(m_currentState), getStateName(newState));
+    // Persistent trace for debugging abrupt exits
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "setState start %s -> %s\n", getStateName(m_currentState), getStateName(newState)); fclose(f); }
+    }
+
+    // Execute exit hooks for current state
+    executeExitHooks(m_currentState);
+
+    // Update state
+    m_previousState = m_currentState;
+    m_currentState = newState;
+
+    // Execute enter hooks for new state
+    executeEnterHooks(m_currentState);
+
+    // Trace completion
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "setState end %s\n", getStateName(m_currentState)); fclose(f); }
+    }
+
+    return true;
+}
+
+void StateManager::handleEvent(const SDL_Event& event) {
+    auto it = m_eventHandlers.find(stateToInt(m_currentState));
+    if (it == m_eventHandlers.end()) {
+        return;
+    }
+
+    for (auto& handler : it->second) {
+        try {
+            handler(event);
+        } catch (const std::exception& e) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Exception in event handler for state %s: %s", 
+                        getStateName(m_currentState), e.what());
+        }
+    }
+}
+
+void StateManager::update(float deltaTime) {
+    auto it = m_updateHandlers.find(stateToInt(m_currentState));
+    if (it == m_updateHandlers.end()) {
+        return;
+    }
+
+    for (auto& handler : it->second) {
+        try {
+            handler(deltaTime);
+        } catch (const std::exception& e) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Exception in update handler for state %s: %s", 
+                        getStateName(m_currentState), e.what());
+        }
+    }
+}
+
+void StateManager::render(RenderManager& renderer) {
+    auto it = m_renderHandlers.find(stateToInt(m_currentState));
+    if (it == m_renderHandlers.end()) {
+        return;
+    }
+
+    for (auto& handler : it->second) {
+        try {
+            handler(renderer);
+        } catch (const std::exception& e) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Exception in render handler for state %s: %s", 
+                        getStateName(m_currentState), e.what());
+        }
+    }
+}
+
+bool StateManager::isValidState(AppState state) const {
+    switch (state) {
+        case AppState::Loading:
+        case AppState::Video:
+        case AppState::Menu:
+        case AppState::Options:
+        case AppState::LevelSelector:
+        case AppState::Playing:
+        case AppState::LevelSelect:
+        case AppState::GameOver:
+            return true;
+        default:
+            return false;
+    }
+}
+
+bool StateManager::canTransitionTo(AppState newState) const {
+    // For now, allow all transitions. Can be enhanced later with state machine validation
+    return isValidState(newState);
+}
+
+const char* StateManager::getStateName(AppState state) const {
+    switch (state) {
+        case AppState::Loading: return "Loading";
+        case AppState::Video: return "Video";
+        case AppState::Menu: return "Menu";
+        case AppState::Options: return "Options";
+        case AppState::LevelSelector: return "LevelSelector";
+        case AppState::Playing: return "Playing";
+        case AppState::LevelSelect: return "LevelSelect";
+        case AppState::GameOver: return "GameOver";
+        default: return "Unknown";
+    }
+}
+
+void StateManager::executeEnterHooks(AppState state) {
+    auto it = m_onEnterHooks.find(stateToInt(state));
+    if (it == m_onEnterHooks.end()) {
+        return;
+    }
+
+    int idx = 0;
+    for (auto& hook : it->second) {
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Executing enter hook %d for state %s", idx, getStateName(state));
+        // Also write to trace file for persistent record
+        {
+            FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "executeEnterHook %d %s\n", idx, getStateName(state)); fclose(f); }
+        }
+        try {
+            hook();
+        } catch (const std::exception& e) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Exception in enter hook for state %s: %s", 
+                        getStateName(state), e.what());
+        }
+        ++idx;
+    }
+}
+
+void StateManager::executeExitHooks(AppState state) {
+    auto it = m_onExitHooks.find(stateToInt(state));
+    if (it == m_onExitHooks.end()) {
+        return;
+    }
+
+    int idx = 0;
+    for (auto& hook : it->second) {
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "Executing exit hook %d for state %s", idx, getStateName(state));
+        {
+            FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "executeExitHook %d %s\n", idx, getStateName(state)); fclose(f); }
+        }
+        try {
+            hook();
+        } catch (const std::exception& e) {
+            SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Exception in exit hook for state %s: %s", 
+                        getStateName(state), e.what());
+        }
+        ++idx;
+    }
+}
diff --git a/src/core/state/StateManager.h b/src/core/state/StateManager.h
new file mode 100644
index 0000000..20379da
--- /dev/null
+++ b/src/core/state/StateManager.h
@@ -0,0 +1,88 @@
+#pragma once
+
+#include <functional>
+#include <unordered_map>
+#include <vector>
+#include <string>
+#include <SDL3/SDL.h>
+
+// Forward declarations
+class RenderManager;
+
+// Application states used across the app
+enum class AppState {
+    Loading,
+    Video,
+    Menu,
+    Options,
+    LevelSelector,
+    Playing,
+    LevelSelect,
+    GameOver
+};
+
+/**
+ * Enhanced StateManager - Manages application state transitions and lifecycle
+ * 
+ * Improvements over original:
+ * - Better error handling and validation
+ * - Support for update and render cycles
+ * - State transition validation
+ * - Logging for debugging
+ * - Cleaner API design
+ */
+class StateManager {
+public:
+    using EventHandler = std::function<void(const SDL_Event&)>;
+    using UpdateHandler = std::function<void(float deltaTime)>;
+    using RenderHandler = std::function<void(RenderManager& renderer)>;
+    using Hook = std::function<void()>;
+
+    StateManager(AppState initial);
+    ~StateManager() = default;
+
+    // State registration
+    void registerEventHandler(AppState state, EventHandler handler);
+    void registerUpdateHandler(AppState state, UpdateHandler handler);
+    void registerRenderHandler(AppState state, RenderHandler handler);
+    void registerOnEnter(AppState state, Hook hook);
+    void registerOnExit(AppState state, Hook hook);
+
+    // Legacy compatibility
+    void registerHandler(AppState s, EventHandler h) { registerEventHandler(s, std::move(h)); }
+    void registerHandler(AppState s, std::function<void()> h); // overload used in some places
+
+    // State management
+    bool setState(AppState newState);
+    AppState getState() const { return m_currentState; }
+    AppState getPreviousState() const { return m_previousState; }
+
+    // State operations
+    void handleEvent(const SDL_Event& event);
+    void update(float deltaTime);
+    void render(RenderManager& renderer);
+
+    // Validation
+    bool isValidState(AppState state) const;
+    bool canTransitionTo(AppState newState) const;
+
+    // Utility
+    const char* getStateName(AppState state) const;
+
+private:
+    // State data
+    AppState m_currentState;
+    AppState m_previousState;
+    
+    // Handler storage
+    std::unordered_map<int, std::vector<EventHandler>> m_eventHandlers;
+    std::unordered_map<int, std::vector<UpdateHandler>> m_updateHandlers;
+    std::unordered_map<int, std::vector<RenderHandler>> m_renderHandlers;
+    std::unordered_map<int, std::vector<Hook>> m_onEnterHooks;
+    std::unordered_map<int, std::vector<Hook>> m_onExitHooks;
+
+    // Helper methods
+    void executeEnterHooks(AppState state);
+    void executeExitHooks(AppState state);
+    int stateToInt(AppState state) const { return static_cast<int>(state); }
+};
diff --git a/src/gameplay/Game.cpp b/src/gameplay/Game.cpp
deleted file mode 100644
index 6255150..0000000
--- a/src/gameplay/Game.cpp
+++ /dev/null
@@ -1,334 +0,0 @@
-// Game.cpp - Implementation of core Tetris game logic
-#include "gameplay/Game.h"
-#include <algorithm>
-#include <cmath>
-
-// Piece rotation bitmasks (row-major 4x4). Bit 0 = (0,0).
-static const std::array<Shape, PIECE_COUNT> SHAPES = {{
-    Shape{ 0x0F00, 0x2222, 0x00F0, 0x4444 }, // I
-    Shape{ 0x0660, 0x0660, 0x0660, 0x0660 }, // O
-    Shape{ 0x0E40, 0x4C40, 0x4E00, 0x4640 }, // T
-    Shape{ 0x06C0, 0x4620, 0x06C0, 0x4620 }, // S
-    Shape{ 0x0C60, 0x2640, 0x0C60, 0x2640 }, // Z
-    Shape{ 0x08E0, 0x6440, 0x0E20, 0x44C0 }, // J
-    Shape{ 0x02E0, 0x4460, 0x0E80, 0xC440 }, // L
-}};
-
-// NES (NTSC) gravity table: frames per grid cell for each level.
-// Based on: 0-9, 10-12: 5, 13-15: 4, 16-18: 3, 19-28: 2, 29+: 1
-namespace {
-    constexpr double NES_FPS = 60.0988;
-    constexpr double FRAME_MS = 1000.0 / NES_FPS;
-    
-    struct LevelGravity { int framesPerCell; double levelMultiplier; };
-
-    // Default table following NES values; levelMultiplier starts at 1.0 and can be tuned per-level
-    LevelGravity LEVEL_TABLE[30] = {
-        {48,1.0}, {43,1.0}, {38,1.0}, {33,1.0}, {28,1.0}, {23,1.0}, {18,1.0}, {13,1.0}, {8,1.0}, {6,1.0},
-        {5,1.0}, {5,1.0}, {5,1.0}, {4,1.0}, {4,1.0}, {4,1.0}, {3,1.0}, {3,1.0}, {3,1.0}, {2,1.0},
-        {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {1,1.0}
-    };
-
-    inline double gravityMsForLevel(int level, double globalMultiplier)
-    {
-        int idx = level < 0 ? 0 : (level >= 29 ? 29 : level);
-        const LevelGravity &lg = LEVEL_TABLE[idx];
-        double frames = lg.framesPerCell * lg.levelMultiplier;
-        double result = frames * FRAME_MS * globalMultiplier;
-
-        static int debug_calls = 0;
-        if (debug_calls < 3) {
-            printf("Level %d: %d frames per cell (mult %.2f) = %.1f ms per cell (global x%.2f)\\n",
-                   level, lg.framesPerCell, lg.levelMultiplier, result, globalMultiplier);
-            debug_calls++;
-        }
-        return result;
-    }
-}
-
-void Game::reset(int startLevel_) {
-    std::fill(board.begin(), board.end(), 0);
-    std::fill(blockCounts.begin(), blockCounts.end(), 0);
-    bag.clear();
-    _score = 0; _lines = 0; _level = startLevel_; startLevel = startLevel_;
-    // Initialize gravity using NES timing table (ms per cell by level)
-    gravityMs = gravityMsForLevel(_level, gravityGlobalMultiplier);
-    fallAcc = 0; _elapsedSec = 0; gameOver=false; paused=false;
-    hold = Piece{}; hold.type = PIECE_COUNT; canHold=true;
-    refillBag(); spawn();
-}
-
-void Game::refillBag() {
-    bag.clear();
-    for (int i=0;i<PIECE_COUNT;++i) bag.push_back(static_cast<PieceType>(i));
-    std::shuffle(bag.begin(), bag.end(), rng);
-}
-
-double Game::getGravityGlobalMultiplier() const { return gravityGlobalMultiplier; }
-double Game::getGravityMs() const { return gravityMs; }
-
-void Game::setLevelGravityMultiplier(int level, double m) {
-    if (level < 0) return;
-    int idx = level >= 29 ? 29 : level;
-    LEVEL_TABLE[idx].levelMultiplier = m;
-    // If current level changed, refresh gravityMs
-    if (_level == idx) gravityMs = gravityMsForLevel(_level, gravityGlobalMultiplier);
-}
-
-
-void Game::spawn() {
-    if (bag.empty()) refillBag();
-    PieceType pieceType = bag.back();
-    
-    // I-piece needs to start one row higher due to its height when vertical
-    int spawnY = (pieceType == I) ? -2 : -1;
-    
-    cur = Piece{ pieceType, 0, 3, spawnY };
-    
-    // Check if the newly spawned piece collides with existing blocks
-    if (collides(cur)) {
-        gameOver = true;
-        return; // Don't proceed with spawning if it causes a collision
-    }
-    
-    bag.pop_back();
-    blockCounts[cur.type]++; // Increment count for this piece type
-    canHold = true;
-    
-    // Prepare next piece
-    if (bag.empty()) refillBag();
-    PieceType nextType = bag.back();
-    int nextSpawnY = (nextType == I) ? -2 : -1;
-    nextPiece = Piece{ nextType, 0, 3, nextSpawnY };
-}
-
-bool Game::cellFilled(const Piece& p, int cx, int cy) {
-    if (p.type == PIECE_COUNT) return false;
-    const uint16_t mask = SHAPES[p.type][p.rot];
-    const int bit = cy*4 + cx;
-    return (mask >> bit) & 1;
-}
-
-bool Game::collides(const Piece& p) const {
-    for (int cy=0; cy<4; ++cy) {
-        for (int cx=0; cx<4; ++cx) if (cellFilled(p,cx,cy)) {
-            int gx = p.x + cx; int gy = p.y + cy;
-            if (gx < 0 || gx >= COLS || gy >= ROWS) return true;
-            if (gy >= 0 && board[gy*COLS + gx] != 0) return true;
-        }
-    }
-    return false;
-}
-
-void Game::lockPiece() {
-    for (int cy=0; cy<4; ++cy) {
-        for (int cx=0; cx<4; ++cx) if (cellFilled(cur,cx,cy)) {
-            int gx = cur.x + cx; int gy = cur.y + cy;
-            if (gy >= 0 && gy < ROWS) board[gy*COLS + gx] = static_cast<int>(cur.type)+1;
-            if (gy < 0) gameOver = true;
-        }
-    }
-    
-    // Check for completed lines but don't clear them yet - let the effect system handle it
-    int cleared = checkLines();
-    if (cleared > 0) {
-        // JS scoring system: base points per clear, multiplied by (level+1) in JS.
-        // Our _level is 1-based (JS level + 1), so multiplier == _level.
-        int base = 0;
-        switch (cleared) {
-            case 1: base = 40; break;      // SINGLE
-            case 2: base = 100; break;     // DOUBLE
-            case 3: base = 300; break;     // TRIPLE
-            case 4: base = 1200; break;    // TETRIS
-            default: base = 0; break;
-        }
-    // multiplier is level+1 to match original scoring where level 0 => x1
-    _score += base * (_level + 1);
-
-        // Update total lines
-        _lines += cleared;
-
-        // JS level progression (NES-like) using starting level rules
-        // Both startLevel and _level are 0-based now.
-        const int threshold = (startLevel + 1) * 10; // first promotion after this many lines
-        int oldLevel = _level;
-        // First level up happens when total lines equal threshold
-        // After that, every 10 lines (when (lines - threshold) % 10 == 0)
-        if (_lines == threshold) {
-            _level += 1;
-        } else if (_lines > threshold && ((_lines - threshold) % 10 == 0)) {
-            _level += 1;
-        }
-
-        if (_level > oldLevel) {
-            // Update gravity to exact NES speed for the new level
-            gravityMs = gravityMsForLevel(_level, gravityGlobalMultiplier);
-            if (levelUpCallback) levelUpCallback(_level);
-        }
-
-        // Trigger sound effect callback for line clears
-        if (soundCallback) {
-            soundCallback(cleared);
-        }
-    }
-    
-    if (!gameOver) spawn();
-}
-
-int Game::checkLines() {
-    completedLines.clear();
-    
-    // Check each row from bottom to top
-    for (int y = ROWS - 1; y >= 0; --y) {
-        bool full = true;
-        for (int x = 0; x < COLS; ++x) {
-            if (board[y*COLS + x] == 0) {
-                full = false;
-                break;
-            }
-        }
-        if (full) {
-            completedLines.push_back(y);
-        }
-    }
-    
-    return static_cast<int>(completedLines.size());
-}
-
-void Game::clearCompletedLines() {
-    if (completedLines.empty()) return;
-    
-    actualClearLines();
-    completedLines.clear();
-}
-
-void Game::actualClearLines() {
-    if (completedLines.empty()) return;
-    
-    int write = ROWS - 1;
-    for (int y = ROWS - 1; y >= 0; --y) {
-        // Check if this row should be cleared
-        bool shouldClear = std::find(completedLines.begin(), completedLines.end(), y) != completedLines.end();
-        
-        if (!shouldClear) {
-            // Keep this row, move it down if necessary
-            if (write != y) {
-                for (int x = 0; x < COLS; ++x) {
-                    board[write*COLS + x] = board[y*COLS + x];
-                }
-            }
-            --write;
-        }
-        // If shouldClear is true, we skip this row (effectively removing it)
-    }
-    
-    // Clear the top rows that are now empty
-    for (int y = write; y >= 0; --y) {
-        for (int x = 0; x < COLS; ++x) {
-            board[y*COLS + x] = 0;
-        }
-    }
-}
-
-bool Game::tryMoveDown() {
-    Piece p = cur; p.y += 1; if (!collides(p)) { cur = p; return true; } return false;
-}
-
-void Game::tickGravity(double frameMs) {
-    if (paused) return; // Don't tick gravity when paused
-    fallAcc += frameMs;
-    while (fallAcc >= gravityMs) {
-        // Attempt to move down by one row
-        if (tryMoveDown()) {
-            // Award soft drop points only if player is actively holding Down
-            // JS: POINTS.SOFT_DROP = 1 per cell for soft drop
-            if (softDropping) {
-                _score += 1;
-            }
-        } else {
-            // Can't move down further, lock piece
-            lockPiece();
-            if (gameOver) break;
-        }
-        fallAcc -= gravityMs;
-    }
-}
-
-void Game::softDropBoost(double frameMs) { 
-    // Reduce soft drop speed multiplier from 10.0 to 3.0 to make it less aggressive
-    if (!paused) fallAcc += frameMs * 3.0; 
-}
-
-void Game::hardDrop() { 
-    if (paused) return;
-    // Count how many rows we drop for scoring parity with JS
-    int rows = 0;
-    while (tryMoveDown()) { rows++; }
-    // JS: POINTS.HARD_DROP = 1 per cell
-    if (rows > 0) {
-        _score += rows * 1;
-    }
-    lockPiece(); 
-}
-
-void Game::rotate(int dir) {
-    if (paused) return;
-    
-    Piece p = cur;
-    p.rot = (p.rot + dir + 4) % 4;
-    
-    // Try rotation at current position first
-    if (!collides(p)) {
-        cur = p;
-        return;
-    }
-    
-    // JavaScript-style wall kicks: try horizontal, up, then larger horizontal offsets
-    const std::pair<int,int> kicks[] = {
-        {1, 0},   // right
-        {-1, 0},  // left  
-        {0, -1},  // up (key difference from our previous approach)
-        {2, 0},   // 2 right (for I piece)
-        {-2, 0},  // 2 left (for I piece)
-    };
-    
-    for (auto kick : kicks) {
-        Piece test = p;
-        test.x = cur.x + kick.first;
-        test.y = cur.y + kick.second;
-        if (!collides(test)) {
-            cur = test;
-            return;
-        }
-    }
-}
-
-void Game::move(int dx) {
-    if (paused) return;
-    Piece p = cur; p.x += dx; if (!collides(p)) cur = p;
-}
-
-void Game::holdCurrent() {
-    if (paused || !canHold) return;
-    
-    if (hold.type == PIECE_COUNT) {
-        // First hold - just store current piece and spawn new one
-        hold = cur;
-        // I-piece needs to start one row higher due to its height when vertical
-        int holdSpawnY = (hold.type == I) ? -2 : -1;
-        hold.x = 3; hold.y = holdSpawnY; hold.rot = 0;
-        spawn();
-    } else {
-        // Swap current with held piece
-        Piece temp = hold;
-        hold = cur;
-        // I-piece needs to start one row higher due to its height when vertical
-        int holdSpawnY = (hold.type == I) ? -2 : -1;
-        int currentSpawnY = (temp.type == I) ? -2 : -1;
-        hold.x = 3; hold.y = holdSpawnY; hold.rot = 0;
-        cur = temp;
-        cur.x = 3; cur.y = currentSpawnY; cur.rot = 0;
-    }
-    
-    canHold = false; // Can only hold once per piece spawn
-}
diff --git a/src/gameplay/Game.h b/src/gameplay/Game.h
deleted file mode 100644
index 0c95fdc..0000000
--- a/src/gameplay/Game.h
+++ /dev/null
@@ -1,116 +0,0 @@
-
-// Game.h - Core Tetris game logic (board, piece mechanics, scoring events only)
-#pragma once
-#include <array>
-#include <vector>
-#include <random>
-#include <cstdint>
-#include <functional>
-#include <memory>
-#include "core/GravityManager.h"
-
-enum PieceType { I, O, T, S, Z, J, L, PIECE_COUNT };
-using Shape = std::array<uint16_t, 4>; // four rotation bitmasks
-
-class Game {
-public:
-    static constexpr int COLS = 10;
-    static constexpr int ROWS = 20;
-    static constexpr int TILE = 28; // logical cell size in pixels (render layer decides use)
-
-    struct Piece { PieceType type{PIECE_COUNT}; int rot{0}; int x{3}; int y{-2}; };
-
-    explicit Game(int startLevel = 0) { reset(startLevel); }
-    void reset(int startLevel = 0);
-
-    // Simulation -----------------------------------------------------------
-    void tickGravity(double frameMs);          // advance gravity accumulator & drop
-    void softDropBoost(double frameMs);        // accelerate fall while held
-    void hardDrop();                           // instant drop & lock
-    void setSoftDropping(bool on) { softDropping = on; } // mark if player holds Down
-    void move(int dx);                         // horizontal move
-    void rotate(int dir);                      // +1 cw, -1 ccw (simple wall-kick)
-    void holdCurrent();                        // swap with hold (once per spawn)
-
-    // Accessors -----------------------------------------------------------
-    const std::array<int, COLS*ROWS>& boardRef() const { return board; }
-    const Piece& current() const { return cur; }
-    const Piece& next() const { return nextPiece; }
-    const Piece& held() const { return hold; }
-    bool canHoldPiece() const { return canHold; }
-    bool isGameOver() const { return gameOver; }
-    bool isPaused() const { return paused; }
-    void setPaused(bool p) { paused = p; }
-    int score() const { return _score; }
-    int lines() const { return _lines; }
-    int level() const { return _level; }
-    int startLevelBase() const { return startLevel; }
-    double elapsed() const { return _elapsedSec; }
-    void addElapsed(double frameMs) { if (!paused) _elapsedSec += frameMs/1000.0; }
-    
-    // Block statistics
-    const std::array<int, PIECE_COUNT>& getBlockCounts() const { return blockCounts; }
-    
-    // Line clearing effects support
-    bool hasCompletedLines() const { return !completedLines.empty(); }
-    const std::vector<int>& getCompletedLines() const { return completedLines; }
-    void clearCompletedLines(); // Actually remove the lines from the board
-    
-    // Sound effect callbacks
-    using SoundCallback = std::function<void(int)>; // Callback for line clear sounds (number of lines)
-    using LevelUpCallback = std::function<void(int)>; // Callback for level up sounds
-    void setSoundCallback(SoundCallback callback) { soundCallback = callback; }
-    void setLevelUpCallback(LevelUpCallback callback) { levelUpCallback = callback; }
-
-    // Shape helper --------------------------------------------------------
-    static bool cellFilled(const Piece& p, int cx, int cy);
-
-    // Gravity tuning accessors (public API for HUD/tuning)
-    void setGravityGlobalMultiplier(double m) { gravityGlobalMultiplier = m; }
-    double getGravityGlobalMultiplier() const;
-    double getGravityMs() const;
-    void setLevelGravityMultiplier(int level, double m);
-
-private:
-    std::array<int, COLS*ROWS> board{}; // 0 empty else color index
-    Piece cur{}, hold{}, nextPiece{};   // current, held & next piece
-    bool canHold{true};
-    bool paused{false};
-    std::vector<PieceType> bag;         // 7-bag randomizer
-    std::mt19937 rng{ std::random_device{}() };
-    std::array<int, PIECE_COUNT> blockCounts{}; // Count of each piece type used
-
-    int _score{0};
-    int _lines{0};
-    int _level{1};
-    double gravityMs{800.0};
-    double fallAcc{0.0};
-    double _elapsedSec{0.0};
-    bool gameOver{false};
-    int startLevel{0};
-    bool softDropping{false}; // true while player holds Down key
-    
-    // Line clearing support
-    std::vector<int> completedLines; // Rows that are complete and ready for effects
-    
-    // Sound effect callbacks
-    SoundCallback soundCallback;
-    LevelUpCallback levelUpCallback;
-    // Gravity tuning -----------------------------------------------------
-    // Global multiplier applied to all level timings (use to slow/speed whole-game gravity)
-    double gravityGlobalMultiplier{2.8};
-    // Gravity manager encapsulates frames table, multipliers and conversions
-    GravityManager gravityMgr;
-    // Backwards-compatible accessors (delegate to gravityMgr)
-    double computeGravityMsForLevel(int level) const;
-
-    // Internal helpers ----------------------------------------------------
-    void refillBag();
-    void spawn();
-    bool collides(const Piece& p) const;
-    void lockPiece();
-    int checkLines(); // Find completed lines and store them
-    void actualClearLines(); // Actually remove lines from board
-    bool tryMoveDown(); // one-row fall; returns true if moved
-    // Gravity tuning helpers (public API declared above)
-};
diff --git a/src/gameplay/LineEffect.cpp b/src/gameplay/LineEffect.cpp
index 6c80cbd..250ab05 100644
--- a/src/gameplay/LineEffect.cpp
+++ b/src/gameplay/LineEffect.cpp
@@ -2,6 +2,7 @@
 #include "LineEffect.h"
 #include <algorithm>
 #include <cmath>
+#include "audio/Audio.h"
 
 #ifndef M_PI
 #define M_PI 3.14159265358979323846
@@ -80,15 +81,11 @@ bool LineEffect::init(SDL_Renderer* r) {
 }
 
 void LineEffect::shutdown() {
-    if (audioStream) {
-        SDL_DestroyAudioStream(audioStream);
-        audioStream = nullptr;
-    }
+    // No separate audio stream anymore; SFX go through shared Audio mixer
 }
 
 void LineEffect::initAudio() {
-    // For now, we'll generate simple beep sounds procedurally
-    // In a full implementation, you'd load WAV files
+    // Generate simple beep sounds procedurally (fallback when voice SFX not provided)
     
     // Generate a simple line clear beep (440Hz for 0.2 seconds)
     int sampleRate = 44100;
@@ -265,33 +262,10 @@ void LineEffect::renderExplosion() {
 }
 
 void LineEffect::playLineClearSound(int lineCount) {
-    if (!audioStream) {
-        // Create audio stream for sound effects
-        SDL_AudioSpec spec = {};
-        spec.format = SDL_AUDIO_S16;
-        spec.channels = 2;
-        spec.freq = 44100;
-        
-        audioStream = SDL_OpenAudioDeviceStream(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &spec, nullptr, nullptr);
-        if (!audioStream) {
-            SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "Warning: Could not create audio stream for line clear effects");
-            return;
-        }
-    }
-    
     // Choose appropriate sound based on line count
-    const std::vector<int16_t>* sample = nullptr;
-    
-    if (lineCount == 4) {
-        sample = &tetrisSample; // Special sound for Tetris
-        //printf("TETRIS! 4 lines cleared!\n");
-    } else {
-        sample = &lineClearSample; // Regular line clear sound
-        //printf("Line clear: %d lines\n", lineCount);
-    }
-    
+    const std::vector<int16_t>* sample = (lineCount == 4) ? &tetrisSample : &lineClearSample;
     if (sample && !sample->empty()) {
-        SDL_PutAudioStreamData(audioStream, sample->data(), 
-                              static_cast<int>(sample->size() * sizeof(int16_t)));
+        // Mix via shared Audio device so it layers with music
+        Audio::instance().playSfx(*sample, 2, 44100, (lineCount == 4) ? 0.9f : 0.7f);
     }
 }
diff --git a/src/gameplay/coop/CoopAIController.cpp b/src/gameplay/coop/CoopAIController.cpp
new file mode 100644
index 0000000..956fe9a
--- /dev/null
+++ b/src/gameplay/coop/CoopAIController.cpp
@@ -0,0 +1,317 @@
+#include "CoopAIController.h"
+
+#include "CoopGame.h"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <limits>
+
+namespace {
+
+static bool canPlacePieceForSide(const std::array<CoopGame::Cell, CoopGame::COLS * CoopGame::ROWS>& board,
+                                 const CoopGame::Piece& p,
+                                 CoopGame::PlayerSide side) {
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (!CoopGame::cellFilled(p, cx, cy)) {
+                continue;
+            }
+
+            const int bx = p.x + cx;
+            const int by = p.y + cy;
+
+            // Keep the AI strictly in the correct half.
+            if (side == CoopGame::PlayerSide::Right) {
+                if (bx < 10 || bx >= CoopGame::COLS) {
+                    return false;
+                }
+            } else {
+                if (bx < 0 || bx >= 10) {
+                    return false;
+                }
+            }
+
+            // Above the visible board is allowed.
+            if (by < 0) {
+                continue;
+            }
+
+            if (by >= CoopGame::ROWS) {
+                return false;
+            }
+
+            if (board[by * CoopGame::COLS + bx].occupied) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+
+static int dropYFor(const std::array<CoopGame::Cell, CoopGame::COLS * CoopGame::ROWS>& board,
+                    CoopGame::Piece p,
+                    CoopGame::PlayerSide side) {
+    // Assumes p is currently placeable.
+    while (true) {
+        CoopGame::Piece next = p;
+        next.y += 1;
+        if (!canPlacePieceForSide(board, next, side)) {
+            return p.y;
+        }
+        p = next;
+        if (p.y > CoopGame::ROWS) {
+            return p.y;
+        }
+    }
+}
+
+static void applyPiece(std::array<uint8_t, CoopGame::COLS * CoopGame::ROWS>& occ,
+                      const CoopGame::Piece& p) {
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (!CoopGame::cellFilled(p, cx, cy)) {
+                continue;
+            }
+            const int bx = p.x + cx;
+            const int by = p.y + cy;
+            if (by < 0 || by >= CoopGame::ROWS || bx < 0 || bx >= CoopGame::COLS) {
+                continue;
+            }
+            occ[by * CoopGame::COLS + bx] = 1;
+        }
+    }
+}
+
+struct Eval {
+    double score = -std::numeric_limits<double>::infinity();
+    int rot = 0;
+    int x = 10;
+};
+
+static Eval evaluateBestPlacementForSide(const CoopGame& game, CoopGame::PlayerSide side) {
+    const auto& board = game.boardRef();
+
+    std::array<uint8_t, CoopGame::COLS * CoopGame::ROWS> occ{};
+    for (int i = 0; i < CoopGame::COLS * CoopGame::ROWS; ++i) {
+        occ[i] = board[i].occupied ? 1 : 0;
+    }
+
+    const CoopGame::Piece cur = game.current(side);
+
+    Eval best{};
+
+    // Iterate rotations and x positions. IMPORTANT: allow x to go slightly out of bounds
+    // because our pieces are represented in a 4x4 mask and many rotations have leading
+    // empty columns. For example, placing a vertical I/J/L into column 0 often requires
+    // p.x == -1 or p.x == -2 so the filled cells land at bx==0.
+    // canPlacePieceForSide() enforces the actual half-board bounds.
+    for (int rot = 0; rot < 4; ++rot) {
+        int xmin = (side == CoopGame::PlayerSide::Right) ? 6 : -3;
+        int xmax = (side == CoopGame::PlayerSide::Right) ? 22 : 13;
+        for (int x = xmin; x <= xmax; ++x) {
+            CoopGame::Piece p = cur;
+            p.rot = rot;
+            p.x = x;
+
+            // If this rotation/x is illegal at the current y, try near the top spawn band.
+            if (!canPlacePieceForSide(board, p, side)) {
+                p.y = -2;
+                if (!canPlacePieceForSide(board, p, side)) {
+                    continue;
+                }
+            }
+
+            p.y = dropYFor(board, p, side);
+
+            auto occ2 = occ;
+            applyPiece(occ2, p);
+
+            // Count completed full rows (all 20 cols) after placement.
+            int fullRows = 0;
+            for (int y = 0; y < CoopGame::ROWS; ++y) {
+                bool full = true;
+                for (int cx = 0; cx < CoopGame::COLS; ++cx) {
+                    if (!occ2[y * CoopGame::COLS + cx]) {
+                        full = false;
+                        break;
+                    }
+                }
+                if (full) {
+                    ++fullRows;
+                }
+            }
+
+            // Right-half column heights + holes + bumpiness.
+            std::array<int, 10> heights{};
+            int aggregateHeight = 0;
+            int holes = 0;
+
+            for (int c = 0; c < 10; ++c) {
+                const int bx = (side == CoopGame::PlayerSide::Right) ? (10 + c) : c;
+                int h = 0;
+                bool found = false;
+                for (int y = 0; y < CoopGame::ROWS; ++y) {
+                    if (occ2[y * CoopGame::COLS + bx]) {
+                        h = CoopGame::ROWS - y;
+                        found = true;
+                        // Count holes below the first filled cell.
+                        for (int yy = y + 1; yy < CoopGame::ROWS; ++yy) {
+                            if (!occ2[yy * CoopGame::COLS + bx]) {
+                                ++holes;
+                            }
+                        }
+                        break;
+                    }
+                }
+                heights[c] = found ? h : 0;
+                aggregateHeight += heights[c];
+            }
+
+            int bump = 0;
+            for (int i = 0; i < 9; ++i) {
+                bump += std::abs(heights[i] - heights[i + 1]);
+            }
+
+            // Reward sync potential: rows where the right half is full (10..19).
+            int sideHalfFullRows = 0;
+            for (int y = 0; y < CoopGame::ROWS; ++y) {
+                bool full = true;
+                int start = (side == CoopGame::PlayerSide::Right) ? 10 : 0;
+                int end = (side == CoopGame::PlayerSide::Right) ? 20 : 10;
+                for (int bx = start; bx < end; ++bx) {
+                    if (!occ2[y * CoopGame::COLS + bx]) {
+                        full = false;
+                        break;
+                    }
+                }
+                if (full) {
+                    ++sideHalfFullRows;
+                }
+            }
+
+            // Simple heuristic:
+            // - Strongly prefer completed full rows
+            // - Prefer making the right half complete (helps cooperative clears)
+            // - Penalize holes and excessive height/bumpiness
+            double s = 0.0;
+            // Strongly prefer full-line clears across the whole board (rare but best).
+            s += static_cast<double>(fullRows) * 12000.0;
+            // Heavily prefer completing the player's half — make this a primary objective.
+            s += static_cast<double>(sideHalfFullRows) * 6000.0;
+            // Penalize holes and height less aggressively so completing half-rows is prioritized.
+            s -= static_cast<double>(holes) * 180.0;
+            s -= static_cast<double>(aggregateHeight) * 4.0;
+            s -= static_cast<double>(bump) * 10.0;
+
+            // Reduce center bias so edge placements to complete rows are not punished.
+            double centerTarget = (side == CoopGame::PlayerSide::Right) ? 15.0 : 4.5;
+            const double centerBias = -std::abs((x + 1.5) - centerTarget) * 1.0;
+            s += centerBias;
+
+            if (s > best.score) {
+                best.score = s;
+                best.rot = rot;
+                best.x = x;
+            }
+        }
+    }
+
+    return best;
+}
+
+} // namespace
+
+void CoopAIController::reset() {
+    m_lastPieceSeq = 0;
+    m_hasPlan = false;
+    m_targetRot = 0;
+    m_targetX = 10;
+    m_moveTimerMs = 0.0;
+    m_moveDir = 0;
+    m_rotateTimerMs = 0.0;
+}
+
+void CoopAIController::computePlan(const CoopGame& game, CoopGame::PlayerSide side) {
+    const Eval best = evaluateBestPlacementForSide(game, side);
+    m_targetRot = best.rot;
+    m_targetX = best.x;
+    m_hasPlan = true;
+    m_moveTimerMs = 0.0;
+    m_moveDir = 0;
+    m_rotateTimerMs = 0.0;
+}
+
+void CoopAIController::update(CoopGame& game, CoopGame::PlayerSide side, double frameMs) {
+    const uint64_t seq = game.currentPieceSequence(side);
+    if (seq != m_lastPieceSeq) {
+        m_lastPieceSeq = seq;
+        m_hasPlan = false;
+        m_moveTimerMs = 0.0;
+        m_moveDir = 0;
+        m_rotateTimerMs = 0.0;
+    }
+
+    if (!m_hasPlan) {
+        computePlan(game, side);
+    }
+
+    const CoopGame::Piece cur = game.current(side);
+
+    // Clamp negative deltas (defensive; callers should pass >= 0).
+    const double dt = std::max(0.0, frameMs);
+
+    // Update timers.
+    if (m_moveTimerMs > 0.0) {
+        m_moveTimerMs -= dt;
+        if (m_moveTimerMs < 0.0) m_moveTimerMs = 0.0;
+    }
+    if (m_rotateTimerMs > 0.0) {
+        m_rotateTimerMs -= dt;
+        if (m_rotateTimerMs < 0.0) m_rotateTimerMs = 0.0;
+    }
+
+    // Rotate toward target first.
+    const int curRot = ((cur.rot % 4) + 4) % 4;
+    const int tgtRot = ((m_targetRot % 4) + 4) % 4;
+    int diff = (tgtRot - curRot + 4) % 4;
+    if (diff != 0) {
+        // Human-ish rotation rate limiting.
+        if (m_rotateTimerMs <= 0.0) {
+            const int dir = (diff == 3) ? -1 : 1;
+            game.rotate(side, dir);
+            m_rotateTimerMs = m_rotateIntervalMs;
+        }
+        // While rotating, do not also slide horizontally in the same frame.
+        m_moveDir = 0;
+        m_moveTimerMs = 0.0;
+        return;
+    }
+
+    // Move horizontally toward target.
+    int desiredDir = 0;
+    if (cur.x < m_targetX) desiredDir = +1;
+    else if (cur.x > m_targetX) desiredDir = -1;
+
+    if (desiredDir == 0) {
+        // Aligned: do nothing. Gravity controls fall speed (no AI hard drops).
+        m_moveDir = 0;
+        m_moveTimerMs = 0.0;
+        return;
+    }
+
+    // DAS/ARR-style horizontal movement pacing.
+    if (m_moveDir != desiredDir) {
+        // New direction / initial press: move immediately, then wait DAS.
+        game.move(side, desiredDir);
+        m_moveDir = desiredDir;
+        m_moveTimerMs = m_dasMs;
+        return;
+    }
+
+    // Holding direction: repeat every ARR once DAS has elapsed.
+    if (m_moveTimerMs <= 0.0) {
+        game.move(side, desiredDir);
+        m_moveTimerMs = m_arrMs;
+    }
+}
diff --git a/src/gameplay/coop/CoopAIController.h b/src/gameplay/coop/CoopAIController.h
new file mode 100644
index 0000000..2379e08
--- /dev/null
+++ b/src/gameplay/coop/CoopAIController.h
@@ -0,0 +1,36 @@
+#pragma once
+
+#include <cstdint>
+#include "CoopGame.h"
+
+// Minimal, lightweight AI driver for a CoopGame player side (left or right).
+// It chooses a target rotation/x placement using a simple board heuristic,
+// then steers the active piece toward that target at a human-like input rate.
+class CoopAIController {
+public:
+    CoopAIController() = default;
+
+    void reset();
+
+    // frameMs is the frame delta in milliseconds (same unit used across the gameplay loop).
+    void update(CoopGame& game, CoopGame::PlayerSide side, double frameMs);
+
+private:
+    uint64_t m_lastPieceSeq = 0;
+    bool m_hasPlan = false;
+
+    int m_targetRot = 0;
+    int m_targetX = 10;
+
+    // Input pacing (ms). These intentionally mirror the defaults used for human input.
+    double m_dasMs = 170.0;
+    double m_arrMs = 40.0;
+    double m_rotateIntervalMs = 110.0;
+
+    // Internal timers/state for rate limiting.
+    double m_moveTimerMs = 0.0;
+    int m_moveDir = 0; // -1, 0, +1
+    double m_rotateTimerMs = 0.0;
+
+    void computePlan(const CoopGame& game, CoopGame::PlayerSide side);
+};
diff --git a/src/gameplay/coop/CoopGame.cpp b/src/gameplay/coop/CoopGame.cpp
new file mode 100644
index 0000000..010978f
--- /dev/null
+++ b/src/gameplay/coop/CoopGame.cpp
@@ -0,0 +1,600 @@
+#include "CoopGame.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstring>
+
+namespace {
+// NES (NTSC) gravity table reused from single-player for level progression (ms per cell)
+constexpr double NES_FPS = 60.0988;
+constexpr double FRAME_MS = 1000.0 / NES_FPS;
+
+struct LevelGravity { int framesPerCell; double levelMultiplier; };
+
+LevelGravity LEVEL_TABLE[30] = {
+    {48,1.0}, {43,1.0}, {38,1.0}, {33,1.0}, {28,1.0}, {23,1.0}, {18,1.0}, {13,1.0}, {8,1.0}, {6,1.0},
+    {5,1.0}, {5,1.0}, {5,1.0}, {4,1.0}, {4,1.0}, {4,1.0}, {3,1.0}, {3,1.0}, {3,1.0}, {2,1.0},
+    {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {1,1.0}
+};
+
+inline double gravityMsForLevelInternal(int level, double globalMultiplier) {
+    int idx = level < 0 ? 0 : (level >= 29 ? 29 : level);
+    const LevelGravity& lg = LEVEL_TABLE[idx];
+    double frames = lg.framesPerCell * lg.levelMultiplier;
+    return frames * FRAME_MS * globalMultiplier;
+}
+}
+
+namespace {
+// Piece rotation bitmasks (row-major 4x4). Bit 0 = (0,0).
+static const std::array<Shape, PIECE_COUNT> SHAPES = {{
+    Shape{ 0x0F00, 0x2222, 0x00F0, 0x4444 }, // I
+    Shape{ 0x0660, 0x0660, 0x0660, 0x0660 }, // O
+    Shape{ 0x0E40, 0x4C40, 0x4E00, 0x4640 }, // T
+    Shape{ 0x06C0, 0x4620, 0x06C0, 0x4620 }, // S
+    Shape{ 0x0C60, 0x2640, 0x0C60, 0x2640 }, // Z
+    Shape{ 0x08E0, 0x6440, 0x0E20, 0x44C0 }, // J
+    Shape{ 0x02E0, 0x4460, 0x0E80, 0xC440 }, // L
+}};
+}
+
+CoopGame::CoopGame(int startLevel_) {
+    reset(startLevel_);
+}
+
+namespace {
+uint64_t fnv1a64(uint64_t h, const void* data, size_t size) {
+    const uint8_t* p = static_cast<const uint8_t*>(data);
+    for (size_t i = 0; i < size; ++i) {
+        h ^= static_cast<uint64_t>(p[i]);
+        h *= 1099511628211ull;
+    }
+    return h;
+}
+
+template <typename T>
+uint64_t hashPod(uint64_t h, const T& v) {
+    return fnv1a64(h, &v, sizeof(T));
+}
+}
+
+void CoopGame::resetInternal(int startLevel_, const std::optional<uint32_t>& seedOpt) {
+    std::fill(board.begin(), board.end(), Cell{});
+    rowStates.fill(RowHalfState{});
+    completedLines.clear();
+    hardDropCells.clear();
+    hardDropFxId = 0;
+    hardDropShakeTimerMs = 0.0;
+    _score = 0;
+    _lines = 0;
+    _level = startLevel_;
+    startLevel = startLevel_;
+    gravityMs = gravityMsForLevel(_level);
+    gameOver = false;
+    pieceSequence = 0;
+    elapsedMs = 0.0;
+
+    left = PlayerState{};
+    right = PlayerState{ PlayerSide::Right };
+
+    auto initPlayer = [&](PlayerState& ps, uint32_t seed) {
+        ps.canHold = true;
+        ps.hold.type = PIECE_COUNT;
+        ps.softDropping = false;
+        ps.toppedOut = false;
+        ps.fallAcc = 0.0;
+        ps.lockAcc = 0.0;
+        ps.pieceSeq = 0;
+        ps.score = 0;
+        ps.lines = 0;
+        ps.level = startLevel_;
+        ps.tetrisesMade = 0;
+        ps.currentCombo = 0;
+        ps.maxCombo = 0;
+        ps.comboCount = 0;
+        ps.bag.clear();
+        ps.next.type = PIECE_COUNT;
+        ps.rng.seed(seed);
+        refillBag(ps);
+    };
+
+    if (seedOpt.has_value()) {
+        const uint32_t seed = seedOpt.value();
+        initPlayer(left, seed);
+        initPlayer(right, seed ^ 0x9E3779B9u);
+    } else {
+        // Preserve existing behavior: random seed when not in deterministic mode.
+        std::random_device rd;
+        initPlayer(left, static_cast<uint32_t>(rd()));
+        initPlayer(right, static_cast<uint32_t>(rd()));
+    }
+
+    spawn(left);
+    spawn(right);
+    updateRowStates();
+}
+
+void CoopGame::reset(int startLevel_) {
+    resetInternal(startLevel_, std::nullopt);
+}
+
+void CoopGame::resetDeterministic(int startLevel_, uint32_t seed) {
+    resetInternal(startLevel_, seed);
+}
+
+void CoopGame::setSoftDropping(PlayerSide side, bool on) {
+    PlayerState& ps = player(side);
+    auto stepFor = [&](bool soft)->double { return soft ? std::max(5.0, gravityMs / 5.0) : gravityMs; };
+    double oldStep = stepFor(ps.softDropping);
+    double newStep = stepFor(on);
+    if (oldStep <= 0.0 || newStep <= 0.0) {
+        ps.softDropping = on;
+        return;
+    }
+
+    double progress = ps.fallAcc / oldStep;
+    progress = std::clamp(progress, 0.0, 1.0);
+    ps.fallAcc = progress * newStep;
+    ps.softDropping = on;
+}
+
+uint64_t CoopGame::computeStateHash() const {
+    uint64_t h = 1469598103934665603ull;
+
+    // Board
+    for (const auto& c : board) {
+        const uint8_t occ = c.occupied ? 1u : 0u;
+        const uint8_t owner = (c.owner == PlayerSide::Left) ? 0u : 1u;
+        const uint8_t val = static_cast<uint8_t>(std::clamp(c.value, 0, 255));
+        h = hashPod(h, occ);
+        h = hashPod(h, owner);
+        h = hashPod(h, val);
+    }
+
+    auto hashPiece = [&](const Piece& p) {
+        const uint8_t type = static_cast<uint8_t>(p.type);
+        const int32_t rot = p.rot;
+        const int32_t x = p.x;
+        const int32_t y = p.y;
+        h = hashPod(h, type);
+        h = hashPod(h, rot);
+        h = hashPod(h, x);
+        h = hashPod(h, y);
+    };
+
+    auto hashPlayer = [&](const PlayerState& ps) {
+        const uint8_t side = (ps.side == PlayerSide::Left) ? 0u : 1u;
+        h = hashPod(h, side);
+        hashPiece(ps.cur);
+        hashPiece(ps.next);
+        hashPiece(ps.hold);
+        const uint8_t canHoldB = ps.canHold ? 1u : 0u;
+        const uint8_t toppedOutB = ps.toppedOut ? 1u : 0u;
+        h = hashPod(h, canHoldB);
+        h = hashPod(h, toppedOutB);
+        h = hashPod(h, ps.score);
+        h = hashPod(h, ps.lines);
+        h = hashPod(h, ps.level);
+        h = hashPod(h, ps.tetrisesMade);
+        h = hashPod(h, ps.currentCombo);
+        h = hashPod(h, ps.maxCombo);
+        h = hashPod(h, ps.comboCount);
+        h = hashPod(h, ps.pieceSeq);
+
+        const uint32_t bagSize = static_cast<uint32_t>(ps.bag.size());
+        h = hashPod(h, bagSize);
+        for (auto t : ps.bag) {
+            const uint8_t tt = static_cast<uint8_t>(t);
+            h = hashPod(h, tt);
+        }
+    };
+
+    hashPlayer(left);
+    hashPlayer(right);
+
+    // Session-wide counters/stats
+    h = hashPod(h, _score);
+    h = hashPod(h, _lines);
+    h = hashPod(h, _level);
+    h = hashPod(h, _tetrisesMade);
+    h = hashPod(h, _currentCombo);
+    h = hashPod(h, _maxCombo);
+    h = hashPod(h, _comboCount);
+    h = hashPod(h, startLevel);
+    h = hashPod(h, pieceSequence);
+
+    return h;
+}
+
+void CoopGame::move(PlayerSide side, int dx) {
+    PlayerState& ps = player(side);
+    if (gameOver || ps.toppedOut) return;
+    tryMove(ps, dx, 0);
+}
+
+void CoopGame::rotate(PlayerSide side, int dir) {
+    PlayerState& ps = player(side);
+    if (gameOver || ps.toppedOut) return;
+
+    auto minOccupiedY = [&](const Piece& p) -> int {
+        int minY = 999;
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!cellFilled(p, cx, cy)) continue;
+                minY = std::min(minY, p.y + cy);
+            }
+        }
+        return (minY == 999) ? p.y : minY;
+    };
+
+    auto tryApplyWithTopKick = [&](const Piece& candidate) -> bool {
+        // If rotation would place any occupied cell above the visible grid,
+        // kick it down just enough to keep all blocks visible.
+        int minY = minOccupiedY(candidate);
+        int baseDy = (minY < 0) ? -minY : 0;
+
+        // Try minimal adjustment first; allow a couple extra pixels/rows for safety.
+        for (int dy = baseDy; dy <= baseDy + 2; ++dy) {
+            Piece test = candidate;
+            test.y += dy;
+            if (!collides(ps, test)) {
+                ps.cur = test;
+                return true;
+            }
+        }
+        return false;
+    };
+
+    Piece rotated = ps.cur;
+    rotated.rot = (rotated.rot + dir + 4) % 4;
+
+    // Simple wall kick: try in place, then left, then right.
+    if (tryApplyWithTopKick(rotated)) return;
+    rotated.x -= 1;
+    if (tryApplyWithTopKick(rotated)) return;
+    rotated.x += 2;
+    if (tryApplyWithTopKick(rotated)) return;
+}
+
+void CoopGame::hardDrop(PlayerSide side) {
+    PlayerState& ps = player(side);
+    if (gameOver || ps.toppedOut) return;
+
+    hardDropCells.clear();
+    bool moved = false;
+    int dropped = 0;
+    while (tryMove(ps, 0, 1)) {
+        moved = true;
+        dropped++;
+        // Record path for potential effects
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!cellFilled(ps.cur, cx, cy)) continue;
+                int px = ps.cur.x + cx;
+                int py = ps.cur.y + cy;
+                if (py >= 0) {
+                    hardDropCells.push_back(SDL_Point{ px, py });
+                }
+            }
+        }
+    }
+    if (moved) {
+        _score += dropped; // 1 point per cell, matches single-player hard drop
+        ps.score += dropped;
+        hardDropShakeTimerMs = HARD_DROP_SHAKE_DURATION_MS;
+        hardDropFxId++;
+    }
+    lock(ps);
+}
+
+void CoopGame::holdCurrent(PlayerSide side) {
+    PlayerState& ps = player(side);
+    if (gameOver || ps.toppedOut) return;
+    if (!ps.canHold) return;
+    if (ps.hold.type == PIECE_COUNT) {
+        ps.hold = ps.cur;
+        spawn(ps);
+    } else {
+        std::swap(ps.cur, ps.hold);
+        ps.cur.rot = 0;
+        ps.cur.x = columnMin(ps.side) + 3;
+        // Match single-player spawn height (I starts higher)
+        ps.cur.y = (ps.cur.type == PieceType::I) ? -2 : -1;
+        ps.pieceSeq++;
+        pieceSequence++;
+    }
+    ps.canHold = false;
+    ps.lockAcc = 0.0;
+}
+
+void CoopGame::tickGravity(double frameMs) {
+    if (gameOver) return;
+
+    elapsedMs += frameMs;
+
+    auto stepPlayer = [&](PlayerState& ps) {
+        if (ps.toppedOut) return;
+        double step = ps.softDropping ? std::max(5.0, gravityMs / 5.0) : gravityMs;
+        ps.fallAcc += frameMs;
+        while (ps.fallAcc >= step) {
+            ps.fallAcc -= step;
+            if (!tryMove(ps, 0, 1)) {
+                ps.lockAcc += step;
+                if (ps.lockAcc >= LOCK_DELAY_MS) {
+                    lock(ps);
+                    break;
+                }
+            } else {
+                // Award soft drop points when actively holding down
+                if (ps.softDropping) {
+                    _score += 1;
+                    ps.score += 1;
+                }
+                ps.lockAcc = 0.0;
+            }
+        }
+    };
+
+    stepPlayer(left);
+    stepPlayer(right);
+
+    updateRowStates();
+}
+
+void CoopGame::updateVisualEffects(double frameMs) {
+    if (hardDropShakeTimerMs > 0.0) {
+        hardDropShakeTimerMs = std::max(0.0, hardDropShakeTimerMs - frameMs);
+    }
+}
+
+double CoopGame::hardDropShakeStrength() const {
+    if (hardDropShakeTimerMs <= 0.0) return 0.0;
+    return std::clamp(hardDropShakeTimerMs / HARD_DROP_SHAKE_DURATION_MS, 0.0, 1.0);
+}
+
+double CoopGame::gravityMsForLevel(int level) const {
+    return gravityMsForLevelInternal(level, gravityGlobalMultiplier);
+}
+
+bool CoopGame::cellFilled(const Piece& p, int cx, int cy) {
+    if (p.type >= PIECE_COUNT) return false;
+    const Shape& shape = SHAPES[p.type];
+    uint16_t mask = shape[p.rot % 4];
+    int bitIndex = cy * 4 + cx;
+    // Masks are defined row-major 4x4 with bit 0 = (0,0) (same convention as classic).
+    return (mask >> bitIndex) & 1;
+}
+
+void CoopGame::clearCompletedLines() {
+    if (completedLines.empty()) return;
+    clearLinesInternal();
+    completedLines.clear();
+    updateRowStates();
+}
+
+void CoopGame::refillBag(PlayerState& ps) {
+    ps.bag.clear();
+    ps.bag.reserve(PIECE_COUNT);
+    for (int i = 0; i < PIECE_COUNT; ++i) {
+        ps.bag.push_back(static_cast<PieceType>(i));
+    }
+    std::shuffle(ps.bag.begin(), ps.bag.end(), ps.rng);
+}
+
+CoopGame::Piece CoopGame::drawFromBag(PlayerState& ps) {
+    if (ps.bag.empty()) {
+        refillBag(ps);
+    }
+    PieceType t = ps.bag.back();
+    ps.bag.pop_back();
+    Piece p{};
+    p.type = t;
+    return p;
+}
+
+void CoopGame::spawn(PlayerState& ps) {
+    if (ps.next.type == PIECE_COUNT) {
+        ps.next = drawFromBag(ps);
+    }
+    ps.cur = ps.next;
+    ps.cur.rot = 0;
+    ps.cur.x = columnMin(ps.side) + 3; // center within side
+    // Match single-player spawn height (I starts higher)
+    ps.cur.y = (ps.cur.type == PieceType::I) ? -2 : -1;
+    ps.next = drawFromBag(ps);
+    ps.canHold = true;
+    ps.softDropping = false;
+    ps.lockAcc = 0.0;
+    ps.fallAcc = 0.0;
+    ps.pieceSeq++;
+    pieceSequence++;
+    if (collides(ps, ps.cur)) {
+        ps.toppedOut = true;
+        // Cooperative mode: game ends when any player tops out.
+        gameOver = true;
+    }
+}
+
+bool CoopGame::collides(const PlayerState& ps, const Piece& p) const {
+    int minX = columnMin(ps.side);
+    int maxX = columnMax(ps.side);
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (!cellFilled(p, cx, cy)) continue;
+            int px = p.x + cx;
+            int py = p.y + cy;
+            if (px < minX || px > maxX) return true;
+            if (py >= ROWS) return true;
+            if (py < 0) continue; // allow spawn above board
+            int idx = py * COLS + px;
+            if (board[idx].occupied) return true;
+        }
+    }
+    return false;
+}
+
+bool CoopGame::tryMove(PlayerState& ps, int dx, int dy) {
+    Piece test = ps.cur;
+    test.x += dx;
+    test.y += dy;
+    if (collides(ps, test)) return false;
+    ps.cur = test;
+    if (dy > 0) {
+        ps.lockAcc = 0.0;
+    }
+    return true;
+}
+
+void CoopGame::lock(PlayerState& ps) {
+    // Write piece into the board
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (!cellFilled(ps.cur, cx, cy)) continue;
+            int px = ps.cur.x + cx;
+            int py = ps.cur.y + cy;
+            if (py < 0 || py >= ROWS) continue;
+            int idx = py * COLS + px;
+            board[idx].occupied = true;
+            board[idx].owner = ps.side;
+            board[idx].value = static_cast<int>(ps.cur.type) + 1;
+        }
+    }
+    // Detect completed lines and apply rewards but DO NOT clear them here.
+    // Clearing is deferred to the visual `LineEffect` system (as in single-player)
+    findCompletedLines();
+    if (!completedLines.empty()) {
+        int cleared = static_cast<int>(completedLines.size());
+        applyLineClearRewards(ps, cleared);
+        // Notify audio layer if present (matches single-player behavior)
+        if (soundCallback) soundCallback(cleared);
+        // Leave `completedLines` populated; `clearCompletedLines()` will be
+        // invoked by the state when the LineEffect finishes.
+    } else {
+        _currentCombo = 0;
+        ps.currentCombo = 0;
+    }
+    spawn(ps);
+}
+
+void CoopGame::findCompletedLines() {
+    completedLines.clear();
+    for (int r = 0; r < ROWS; ++r) {
+        bool leftFull = true;
+        bool rightFull = true;
+        for (int c = 0; c < COLS; ++c) {
+            const Cell& cell = board[r * COLS + c];
+            if (!cell.occupied) {
+                if (c < 10) leftFull = false; else rightFull = false;
+            }
+        }
+        rowStates[r].leftFull = leftFull;
+        rowStates[r].rightFull = rightFull;
+        if (leftFull && rightFull) {
+            completedLines.push_back(r);
+        }
+    }
+}
+
+void CoopGame::applyLineClearRewards(PlayerState& creditPlayer, int cleared) {
+    if (cleared <= 0) return;
+
+    // Base NES scoring scaled by shared level (level 0 => 1x multiplier)
+    int base = 0;
+    switch (cleared) {
+        case 1: base = 40; break;
+        case 2: base = 100; break;
+        case 3: base = 300; break;
+        case 4: base = 1200; break;
+        default: base = 0; break;
+    }
+    _score += base * (_level + 1);
+    creditPlayer.score += base * (creditPlayer.level + 1);
+
+    // Also award a trivial per-line bonus to both players so clears benefit
+    // both participants equally (as requested).
+    if (cleared > 0) {
+        left.score += cleared;
+        right.score += cleared;
+    }
+
+    _lines += cleared;
+    // Credit both players with the cleared lines so cooperative play counts for both
+    left.lines += cleared;
+    right.lines += cleared;
+
+    _currentCombo += 1;
+    if (_currentCombo > _maxCombo) _maxCombo = _currentCombo;
+    if (cleared > 1) {
+        _comboCount += 1;
+    }
+    if (cleared == 4) {
+        _tetrisesMade += 1;
+    }
+
+    creditPlayer.currentCombo += 1;
+    if (creditPlayer.currentCombo > creditPlayer.maxCombo) creditPlayer.maxCombo = creditPlayer.currentCombo;
+    if (cleared > 1) {
+        creditPlayer.comboCount += 1;
+    }
+    if (cleared == 4) {
+        creditPlayer.tetrisesMade += 1;
+    }
+
+    // Level progression mirrors single-player: threshold after (startLevel+1)*10 then every 10 lines
+    int targetLevel = startLevel;
+    int firstThreshold = (startLevel + 1) * 10;
+    if (_lines >= firstThreshold) {
+        targetLevel = startLevel + 1 + (_lines - firstThreshold) / 10;
+    }
+    if (targetLevel > _level) {
+        _level = targetLevel;
+        gravityMs = gravityMsForLevel(_level);
+        if (levelUpCallback) levelUpCallback(_level);
+    }
+
+    // Per-player level progression mirrors the shared rules but is driven by
+    // that player's credited line clears.
+    {
+        int pTargetLevel = startLevel;
+        int pFirstThreshold = (startLevel + 1) * 10;
+        if (creditPlayer.lines >= pFirstThreshold) {
+            pTargetLevel = startLevel + 1 + (creditPlayer.lines - pFirstThreshold) / 10;
+        }
+        creditPlayer.level = std::max(creditPlayer.level, pTargetLevel);
+    }
+}
+
+void CoopGame::clearLinesInternal() {
+    if (completedLines.empty()) return;
+    std::sort(completedLines.begin(), completedLines.end());
+    for (int idx = static_cast<int>(completedLines.size()) - 1; idx >= 0; --idx) {
+        int row = completedLines[idx];
+        for (int y = row; y > 0; --y) {
+            for (int x = 0; x < COLS; ++x) {
+                board[y * COLS + x] = board[(y - 1) * COLS + x];
+            }
+        }
+        for (int x = 0; x < COLS; ++x) {
+            board[x] = Cell{};
+        }
+    }
+}
+
+// Sound callback (optional) - invoked when lines are detected so audio can play
+// (set via setSoundCallback)
+// NOTE: defined inline in header as a std::function member; forward usage above
+
+void CoopGame::updateRowStates() {
+    for (int r = 0; r < ROWS; ++r) {
+        bool leftFull = true;
+        bool rightFull = true;
+        for (int c = 0; c < COLS; ++c) {
+            const Cell& cell = board[r * COLS + c];
+            if (!cell.occupied) {
+                if (c < 10) leftFull = false; else rightFull = false;
+            }
+        }
+        rowStates[r].leftFull = leftFull;
+        rowStates[r].rightFull = rightFull;
+    }
+}
diff --git a/src/gameplay/coop/CoopGame.h b/src/gameplay/coop/CoopGame.h
new file mode 100644
index 0000000..996b775
--- /dev/null
+++ b/src/gameplay/coop/CoopGame.h
@@ -0,0 +1,167 @@
+#pragma once
+
+#include <array>
+#include <optional>
+#include <random>
+#include <functional>
+#include <vector>
+#include <cstdint>
+#include <SDL3/SDL.h>
+
+#include "../core/Game.h" // For PieceType enums and gravity table helpers
+
+// Cooperative two-player session with a shared 20-column board split into halves.
+// This is an early scaffold: rules and rendering hooks will be iterated in follow-up passes.
+class CoopGame {
+public:
+    enum class PlayerSide { Left, Right };
+
+    static constexpr int COLS = 20;
+    static constexpr int ROWS = Game::ROWS;
+    static constexpr int TILE = Game::TILE;
+
+    struct Piece { PieceType type{PIECE_COUNT}; int rot{0}; int x{0}; int y{-2}; };
+
+    struct Cell {
+        int value{0};              // 0 empty else color index (1..7)
+        PlayerSide owner{PlayerSide::Left};
+        bool occupied{false};
+    };
+
+    struct RowHalfState {
+        bool leftFull{false};
+        bool rightFull{false};
+    };
+
+    struct PlayerState {
+        PlayerSide side{PlayerSide::Left};
+        Piece cur{};
+        Piece hold{};
+        Piece next{};
+        uint64_t pieceSeq{0};
+        bool canHold{true};
+        bool softDropping{false};
+        bool toppedOut{false};
+        double fallAcc{0.0};
+        double lockAcc{0.0};
+        int score{0};
+        int lines{0};
+        int level{0};
+        int tetrisesMade{0};
+        int currentCombo{0};
+        int maxCombo{0};
+        int comboCount{0};
+        std::vector<PieceType> bag{}; // 7-bag queue
+        std::mt19937 rng{ std::random_device{}() };
+    };
+
+    explicit CoopGame(int startLevel = 0);
+    using SoundCallback = std::function<void(int)>;
+    using LevelUpCallback = std::function<void(int)>;
+    void setSoundCallback(SoundCallback cb) { soundCallback = cb; }
+    void setLevelUpCallback(LevelUpCallback cb) { levelUpCallback = cb; }
+
+    void reset(int startLevel = 0);
+    void resetDeterministic(int startLevel, uint32_t seed);
+    void tickGravity(double frameMs);
+    void updateVisualEffects(double frameMs);
+
+    // Determinism / desync detection
+    uint64_t computeStateHash() const;
+
+    // Per-player inputs -----------------------------------------------------
+    void setSoftDropping(PlayerSide side, bool on);
+    void move(PlayerSide side, int dx);
+    void rotate(PlayerSide side, int dir); // +1 cw, -1 ccw
+    void hardDrop(PlayerSide side);
+    void holdCurrent(PlayerSide side);
+
+    // Accessors -------------------------------------------------------------
+    const std::array<Cell, COLS * ROWS>& boardRef() const { return board; }
+    const Piece& current(PlayerSide s) const { return player(s).cur; }
+    const Piece& next(PlayerSide s) const { return player(s).next; }
+    const Piece& held(PlayerSide s) const { return player(s).hold; }
+    bool canHold(PlayerSide s) const { return player(s).canHold; }
+    bool isGameOver() const { return gameOver; }
+    int score() const { return _score; }
+    int score(PlayerSide s) const { return player(s).score; }
+    int lines() const { return _lines; }
+    int lines(PlayerSide s) const { return player(s).lines; }
+    int level() const { return _level; }
+    int level(PlayerSide s) const { return player(s).level; }
+    int comboCount() const { return _comboCount; }
+    int maxCombo() const { return _maxCombo; }
+    int tetrisesMade() const { return _tetrisesMade; }
+    int elapsed() const { return static_cast<int>(elapsedMs / 1000.0); }
+    int elapsed(PlayerSide) const { return elapsed(); }
+    int startLevelBase() const { return startLevel; }
+    double getGravityMs() const { return gravityMs; }
+    double getFallAccumulator(PlayerSide s) const { return player(s).fallAcc; }
+    bool isSoftDropping(PlayerSide s) const { return player(s).softDropping; }
+    uint64_t currentPieceSequence(PlayerSide s) const { return player(s).pieceSeq; }
+    const std::vector<int>& getCompletedLines() const { return completedLines; }
+    bool hasCompletedLines() const { return !completedLines.empty(); }
+    void clearCompletedLines();
+    const std::array<RowHalfState, ROWS>& rowHalfStates() const { return rowStates; }
+
+    // Simple visual-effect compatibility (stubbed for now)
+    bool hasHardDropShake() const { return hardDropShakeTimerMs > 0.0; }
+    double hardDropShakeStrength() const;
+    const std::vector<SDL_Point>& getHardDropCells() const { return hardDropCells; }
+    uint32_t getHardDropFxId() const { return hardDropFxId; }
+
+    static bool cellFilled(const Piece& p, int cx, int cy);
+
+private:
+    static constexpr double LOCK_DELAY_MS = 500.0;
+
+    void resetInternal(int startLevel_, const std::optional<uint32_t>& seedOpt);
+
+    std::array<Cell, COLS * ROWS> board{};
+    std::array<RowHalfState, ROWS> rowStates{};
+    PlayerState left{};
+    PlayerState right{ PlayerSide::Right };
+
+    int _score{0};
+    int _lines{0};
+    int _level{1};
+    int _tetrisesMade{0};
+    int _currentCombo{0};
+    int _maxCombo{0};
+    int _comboCount{0};
+    int startLevel{0};
+    double gravityMs{800.0};
+    double gravityGlobalMultiplier{1.0};
+    bool gameOver{false};
+
+    double elapsedMs{0.0};
+
+    std::vector<int> completedLines;
+
+    // Impact FX
+    double hardDropShakeTimerMs{0.0};
+    static constexpr double HARD_DROP_SHAKE_DURATION_MS = 320.0;
+    std::vector<SDL_Point> hardDropCells;
+    uint32_t hardDropFxId{0};
+    uint64_t pieceSequence{0};
+    SoundCallback soundCallback;
+    LevelUpCallback levelUpCallback;
+
+    // Helpers ---------------------------------------------------------------
+    PlayerState& player(PlayerSide s) { return s == PlayerSide::Left ? left : right; }
+    const PlayerState& player(PlayerSide s) const { return s == PlayerSide::Left ? left : right; }
+
+    void refillBag(PlayerState& ps);
+    Piece drawFromBag(PlayerState& ps);
+    void spawn(PlayerState& ps);
+    bool collides(const PlayerState& ps, const Piece& p) const;
+    bool tryMove(PlayerState& ps, int dx, int dy);
+    void lock(PlayerState& ps);
+    void findCompletedLines();
+    void clearLinesInternal();
+    void updateRowStates();
+    void applyLineClearRewards(PlayerState& creditPlayer, int cleared);
+    double gravityMsForLevel(int level) const;
+    int columnMin(PlayerSide s) const { return s == PlayerSide::Left ? 0 : 10; }
+    int columnMax(PlayerSide s) const { return s == PlayerSide::Left ? 9 : 19; }
+};
diff --git a/src/gameplay/core/Game.cpp b/src/gameplay/core/Game.cpp
new file mode 100644
index 0000000..8a560a0
--- /dev/null
+++ b/src/gameplay/core/Game.cpp
@@ -0,0 +1,946 @@
+// Game.cpp - Implementation of core Tetris game logic
+#include "Game.h"
+#include <algorithm>
+#include <cmath>
+#include <limits>
+#include <SDL3/SDL.h>
+
+// Piece rotation bitmasks (row-major 4x4). Bit 0 = (0,0).
+static const std::array<Shape, PIECE_COUNT> SHAPES = {{
+    Shape{ 0x0F00, 0x2222, 0x00F0, 0x4444 }, // I
+    Shape{ 0x0660, 0x0660, 0x0660, 0x0660 }, // O
+    Shape{ 0x0E40, 0x4C40, 0x4E00, 0x4640 }, // T
+    Shape{ 0x06C0, 0x4620, 0x06C0, 0x4620 }, // S
+    Shape{ 0x0C60, 0x2640, 0x0C60, 0x2640 }, // Z
+    Shape{ 0x08E0, 0x6440, 0x0E20, 0x44C0 }, // J
+    Shape{ 0x02E0, 0x4460, 0x0E80, 0xC440 }, // L
+}};
+
+// NES (NTSC) gravity table: frames per grid cell for each level.
+// Based on: 0-9, 10-12: 5, 13-15: 4, 16-18: 3, 19-28: 2, 29+: 1
+namespace {
+    constexpr double NES_FPS = 60.0988;
+    constexpr double FRAME_MS = 1000.0 / NES_FPS;
+    
+    struct LevelGravity { int framesPerCell; double levelMultiplier; };
+
+    // Default table following NES values; levelMultiplier starts at 1.0 and can be tuned per-level
+    LevelGravity LEVEL_TABLE[30] = {
+        {48,1.0}, {43,1.0}, {38,1.0}, {33,1.0}, {28,1.0}, {23,1.0}, {18,1.0}, {13,1.0}, {8,1.0}, {6,1.0},
+        {5,1.0}, {5,1.0}, {5,1.0}, {4,1.0}, {4,1.0}, {4,1.0}, {3,1.0}, {3,1.0}, {3,1.0}, {2,1.0},
+        {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {2,1.0}, {1,1.0}
+    };
+
+    inline double gravityMsForLevel(int level, double globalMultiplier)
+    {
+        int idx = level < 0 ? 0 : (level >= 29 ? 29 : level);
+        const LevelGravity &lg = LEVEL_TABLE[idx];
+        double frames = lg.framesPerCell * lg.levelMultiplier;
+        double result = frames * FRAME_MS * globalMultiplier;
+
+        static int debug_calls = 0;
+        /*
+        if (debug_calls < 3) {
+            printf("Level %d: %d frames per cell (mult %.2f) = %.1f ms per cell (global x%.2f)\\n",
+                   level, lg.framesPerCell, lg.levelMultiplier, result, globalMultiplier);
+            debug_calls++;
+        }
+        */
+        return result;
+    }
+}
+
+void Game::reset(int startLevel_) {
+    // Standard reset is primarily for endless; Challenge reuses the same pipeline and then
+    // immediately sets up its own level state.
+    std::fill(board.begin(), board.end(), 0);
+    clearAsteroidGrid();
+    recentAsteroidExplosions.clear();
+    std::fill(blockCounts.begin(), blockCounts.end(), 0);
+    bag.clear();
+    _score = 0; _lines = 0; _level = startLevel_; startLevel = startLevel_;
+    _tetrisesMade = 0;
+    _currentCombo = 0;
+    _maxCombo = 0;
+    _comboCount = 0;
+    challengeComplete = false;
+    challengeLevelActive = false;
+    challengeAdvanceQueued = false;
+    challengeQueuedLevel = 0;
+    // Initialize gravity using NES timing table (ms per cell by level)
+    gravityMs = gravityMsForLevel(_level, gravityGlobalMultiplier);
+    fallAcc = 0; gameOver=false; paused=false;
+    hardDropShakeTimerMs = 0.0;
+    hardDropCells.clear();
+    hardDropFxId = 0;
+    _startTime = SDL_GetPerformanceCounter();
+    _pausedTime = 0;
+    _lastPauseStart = 0;
+    hold = Piece{}; hold.type = PIECE_COUNT; canHold=true;
+    refillBag();
+    pieceSequence = 0;
+    spawn();
+
+    if (mode == GameMode::Challenge) {
+        int lvl = startLevel_ <= 0 ? 1 : startLevel_;
+        startChallengeRun(lvl);
+    }
+}
+
+void Game::clearAsteroidGrid() {
+    for (auto &cell : asteroidGrid) {
+        cell.reset();
+    }
+    asteroidsRemainingCount = 0;
+    asteroidsTotalThisLevel = 0;
+}
+
+void Game::startChallengeRun(int startingLevel) {
+    mode = GameMode::Challenge;
+    int lvl = std::clamp(startingLevel, 1, ASTEROID_MAX_LEVEL);
+    // Reset all stats and timers like a fresh run
+    _score = 0; _lines = 0; _level = lvl; startLevel = lvl;
+    _tetrisesMade = 0;
+    _currentCombo = 0;
+    _maxCombo = 0;
+    _comboCount = 0;
+    _startTime = SDL_GetPerformanceCounter();
+    _pausedTime = 0;
+    _lastPauseStart = 0;
+    // Reseed challenge RNG so levels are deterministic per run but distinct per session
+    if (challengeSeedBase == 0) {
+        challengeSeedBase = static_cast<uint32_t>(SDL_GetTicks());
+    }
+    challengeRng.seed(challengeSeedBase + static_cast<uint32_t>(lvl));
+    challengeAdvanceQueued = false;
+    challengeQueuedLevel = 0;
+    setupChallengeLevel(lvl, false);
+}
+
+void Game::beginNextChallengeLevel() {
+    if (mode != GameMode::Challenge || challengeComplete) {
+        return;
+    }
+    challengeAdvanceQueued = false;
+    challengeQueuedLevel = 0;
+    int next = challengeLevelIndex + 1;
+    if (next > ASTEROID_MAX_LEVEL) {
+        challengeComplete = true;
+        challengeLevelActive = false;
+        return;
+    }
+    setupChallengeLevel(next, true);
+}
+
+void Game::setupChallengeLevel(int level, bool preserveStats) {
+    challengeLevelIndex = std::clamp(level, 1, ASTEROID_MAX_LEVEL);
+    _level = challengeLevelIndex;
+    startLevel = challengeLevelIndex;
+    challengeComplete = false;
+    challengeLevelActive = true;
+    challengeAdvanceQueued = false;
+    challengeQueuedLevel = 0;
+    // Refresh deterministic RNG for this level
+    challengeRng.seed(challengeSeedBase + static_cast<uint32_t>(challengeLevelIndex));
+
+    // Optionally reset cumulative stats (new run) or keep them (between levels)
+    if (!preserveStats) {
+        std::fill(blockCounts.begin(), blockCounts.end(), 0);
+        _score = 0;
+        _lines = 0;
+        _tetrisesMade = 0;
+        _currentCombo = 0;
+        _comboCount = 0;
+        _maxCombo = 0;
+        _startTime = SDL_GetPerformanceCounter();
+        _pausedTime = 0;
+        _lastPauseStart = 0;
+    } else {
+        _currentCombo = 0;
+    }
+
+    // Clear playfield and piece state
+    std::fill(board.begin(), board.end(), 0);
+    clearAsteroidGrid();
+    completedLines.clear();
+    hardDropCells.clear();
+    hardDropFxId = 0;
+    recentAsteroidExplosions.clear();
+    fallAcc = 0.0;
+    gameOver = false;
+    paused = false;
+    softDropping = false;
+    hold = Piece{};
+    hold.type = PIECE_COUNT;
+    canHold = true;
+    bag.clear();
+    refillBag();
+    pieceSequence = 0;
+    spawn();
+
+    // Challenge gravity scales upward per level (faster = smaller ms per cell)
+    double baseMs = gravityMsForLevel(0, gravityGlobalMultiplier);
+    double speedFactor = 1.0 + static_cast<double>(challengeLevelIndex) * 0.02;
+    gravityMs = (speedFactor > 0.0) ? (baseMs / speedFactor) : baseMs;
+
+    // Place asteroids for this level
+    placeAsteroidsForLevel(challengeLevelIndex);
+
+    if (levelUpCallback) {
+        levelUpCallback(_level);
+    }
+}
+
+AsteroidType Game::chooseAsteroidTypeForLevel(int level) {
+    // Simple weight distribution by level bands
+    int normalWeight = 100;
+    int armoredWeight = 0;
+    int fallingWeight = 0;
+    int coreWeight = 0;
+
+    if (level >= 10) {
+        armoredWeight = 20;
+        normalWeight = 80;
+    }
+    if (level >= 20) {
+        fallingWeight = 20;
+        normalWeight = 60;
+    }
+    if (level >= 40) {
+        fallingWeight = 30;
+        armoredWeight = 25;
+        normalWeight = 45;
+    }
+    if (level >= 60) {
+        coreWeight = 20;
+        fallingWeight = 30;
+        armoredWeight = 25;
+        normalWeight = 25;
+    }
+
+    int total = normalWeight + armoredWeight + fallingWeight + coreWeight;
+    if (total <= 0) return AsteroidType::Normal;
+    std::uniform_int_distribution<int> dist(0, total - 1);
+    int pick = dist(challengeRng);
+    if (pick < normalWeight) return AsteroidType::Normal;
+    pick -= normalWeight;
+    if (pick < armoredWeight) return AsteroidType::Armored;
+    pick -= armoredWeight;
+    if (pick < fallingWeight) return AsteroidType::Falling;
+    return AsteroidType::Core;
+}
+
+AsteroidCell Game::makeAsteroidForType(AsteroidType t) const {
+    AsteroidCell cell{};
+    cell.type = t;
+    switch (t) {
+        case AsteroidType::Normal:
+            cell.hitsRemaining = 1;
+            cell.gravityEnabled = false;
+            break;
+        case AsteroidType::Armored:
+            cell.hitsRemaining = 2;
+            cell.gravityEnabled = false;
+            break;
+        case AsteroidType::Falling:
+            cell.hitsRemaining = 2;
+            cell.gravityEnabled = false;
+            break;
+        case AsteroidType::Core:
+            cell.hitsRemaining = 3;
+            cell.gravityEnabled = false;
+            break;
+    }
+    cell.visualState = 0;
+    return cell;
+}
+
+void Game::placeAsteroidsForLevel(int level) {
+    int desired = std::clamp(level, 1, ASTEROID_MAX_LEVEL);
+    // Placement window grows upward with level but caps at half board
+    int height = std::clamp(2 + level / 3, 2, ROWS / 2);
+    int minRow = ROWS - 1 - height;
+    int maxRow = ROWS - 1;
+    minRow = std::max(0, minRow);
+
+    std::uniform_int_distribution<int> xDist(0, COLS - 1);
+    std::uniform_int_distribution<int> yDist(minRow, maxRow);
+
+    int attempts = 0;
+    const int maxAttempts = desired * 16;
+    while (asteroidsRemainingCount < desired && attempts < maxAttempts) {
+        int x = xDist(challengeRng);
+        int y = yDist(challengeRng);
+        int idx = y * COLS + x;
+        attempts++;
+        if (board[idx] != 0 || asteroidGrid[idx].has_value()) {
+            continue;
+        }
+        AsteroidType type = chooseAsteroidTypeForLevel(level);
+        AsteroidCell cell = makeAsteroidForType(type);
+        board[idx] = asteroidBoardValue(type);
+        asteroidGrid[idx] = cell;
+        ++asteroidsRemainingCount;
+        ++asteroidsTotalThisLevel;
+    }
+
+    if (asteroidsRemainingCount < desired) {
+        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "[CHALLENGE] Placed %d/%d asteroids for level %d", asteroidsRemainingCount, desired, level);
+    }
+}
+
+// Helper implementations for asteroid board encoding
+bool Game::isAsteroidValue(int boardValue) {
+    return boardValue >= ASTEROID_BASE;
+}
+
+AsteroidType Game::asteroidTypeFromValue(int boardValue) {
+    int idx = boardValue - ASTEROID_BASE;
+    if (idx < 0) return AsteroidType::Normal;
+    if (idx > static_cast<int>(AsteroidType::Core)) idx = static_cast<int>(AsteroidType::Core);
+    return static_cast<AsteroidType>(idx);
+}
+
+int Game::asteroidBoardValue(AsteroidType t) {
+    return ASTEROID_BASE + static_cast<int>(t);
+}
+
+double Game::elapsed() const {
+    if (!_startTime) return 0.0;
+    
+    Uint64 currentTime = SDL_GetPerformanceCounter();
+    Uint64 totalPausedTime = _pausedTime;
+    
+    // If currently paused, add time since pause started
+    if (paused && _lastPauseStart > 0) {
+        totalPausedTime += (currentTime - _lastPauseStart);
+    }
+    
+    Uint64 activeTime = currentTime - _startTime - totalPausedTime;
+    double seconds = (double)activeTime / (double)SDL_GetPerformanceFrequency();
+    return seconds;
+}
+
+void Game::updateElapsedTime() {
+    // This method is now just for API compatibility
+    // Actual elapsed time is calculated on-demand in elapsed()
+}
+
+void Game::setPaused(bool p) {
+    if (p == paused) return; // No change
+    
+    if (p) {
+        // Pausing - record when pause started
+        _lastPauseStart = SDL_GetPerformanceCounter();
+    } else {
+        // Unpausing - add elapsed pause time to total
+        if (_lastPauseStart > 0) {
+            Uint64 currentTime = SDL_GetPerformanceCounter();
+            _pausedTime += (currentTime - _lastPauseStart);
+            _lastPauseStart = 0;
+        }
+    }
+    
+    paused = p;
+}
+
+int Game::consumeQueuedChallengeLevel() {
+    if (!challengeAdvanceQueued) {
+        return 0;
+    }
+    int next = challengeQueuedLevel;
+    challengeAdvanceQueued = false;
+    challengeQueuedLevel = 0;
+    return next;
+}
+
+void Game::setSoftDropping(bool on) {
+    if (softDropping == on) {
+        return;
+    }
+
+    double oldStep = softDropping ? (gravityMs / 5.0) : gravityMs;
+    softDropping = on;
+    double newStep = softDropping ? (gravityMs / 5.0) : gravityMs;
+
+    if (oldStep <= 0.0 || newStep <= 0.0) {
+        return;
+    }
+
+    double progress = fallAcc / oldStep;
+    progress = std::clamp(progress, 0.0, 1.0);
+    fallAcc = progress * newStep;
+}
+
+void Game::refillBag() {
+    bag.clear();
+    for (int i=0;i<PIECE_COUNT;++i) bag.push_back(static_cast<PieceType>(i));
+    std::shuffle(bag.begin(), bag.end(), rng);
+}
+
+double Game::getGravityGlobalMultiplier() const { return gravityGlobalMultiplier; }
+double Game::getGravityMs() const { return gravityMs; }
+
+void Game::setLevelGravityMultiplier(int level, double m) {
+    if (level < 0) return;
+    int idx = level >= 29 ? 29 : level;
+    LEVEL_TABLE[idx].levelMultiplier = m;
+    // If current level changed, refresh gravityMs
+    if (_level == idx) gravityMs = gravityMsForLevel(_level, gravityGlobalMultiplier);
+}
+
+
+void Game::spawn() {
+    if (bag.empty()) refillBag();
+    PieceType pieceType = bag.back();
+    
+    // I-piece needs to start one row higher due to its height when vertical
+    int spawnY = (pieceType == I) ? -2 : -1;
+    
+    cur = Piece{ pieceType, 0, 3, spawnY };
+    
+    // Check if the newly spawned piece collides with existing blocks
+    if (collides(cur)) {
+        gameOver = true;
+        return; // Don't proceed with spawning if it causes a collision
+    }
+    
+    bag.pop_back();
+    blockCounts[cur.type]++; // Increment count for this piece type
+    canHold = true;
+    
+    // Prepare next piece
+    if (bag.empty()) refillBag();
+    PieceType nextType = bag.back();
+    int nextSpawnY = (nextType == I) ? -2 : -1;
+    nextPiece = Piece{ nextType, 0, 3, nextSpawnY };
+        ++pieceSequence;
+}
+
+bool Game::cellFilled(const Piece& p, int cx, int cy) {
+    if (p.type == PIECE_COUNT) return false;
+    const uint16_t mask = SHAPES[p.type][p.rot];
+    const int bit = cy*4 + cx;
+    return (mask >> bit) & 1;
+}
+
+bool Game::collides(const Piece& p) const {
+    for (int cy=0; cy<4; ++cy) {
+        for (int cx=0; cx<4; ++cx) if (cellFilled(p,cx,cy)) {
+            int gx = p.x + cx; int gy = p.y + cy;
+            if (gx < 0 || gx >= COLS || gy >= ROWS) return true;
+            if (gy >= 0 && board[gy*COLS + gx] != 0) return true;
+        }
+    }
+    return false;
+}
+
+void Game::lockPiece() {
+    for (int cy=0; cy<4; ++cy) {
+        for (int cx=0; cx<4; ++cx) if (cellFilled(cur,cx,cy)) {
+            int gx = cur.x + cx; int gy = cur.y + cy;
+            if (gy >= 0 && gy < ROWS) board[gy*COLS + gx] = static_cast<int>(cur.type)+1;
+            if (gy < 0) gameOver = true;
+        }
+    }
+    
+    // Check for completed lines but don't clear them yet - let the effect system handle it
+    int cleared = checkLines();
+    if (cleared > 0) {
+        // JS scoring system: base points per clear, multiplied by (level+1) in JS.
+        // Our _level is 1-based (JS level + 1), so multiplier == _level.
+        int base = 0;
+        switch (cleared) {
+            case 1: base = 40; break;      // SINGLE
+            case 2: base = 100; break;     // DOUBLE
+            case 3: base = 300; break;     // TRIPLE
+            case 4: base = 1200; break;    // TETRIS
+            default: base = 0; break;
+        }
+    // multiplier is level+1 to match original scoring where level 0 => x1
+    _score += base * (_level + 1);
+
+        // Update total lines
+        _lines += cleared;
+
+        // Update combo counters: consecutive clears increase combo; reset when no clear
+        _currentCombo += 1;
+        if (_currentCombo > _maxCombo) _maxCombo = _currentCombo;
+        // Count combos as any single clear that removes more than 1 line
+        if (cleared > 1) {
+            _comboCount += 1;
+        }
+
+        // Track tetrises made
+        if (cleared == 4) {
+            _tetrisesMade += 1;
+        }
+
+        if (mode != GameMode::Challenge) {
+            // JS level progression (NES-like) using starting level rules
+            // Both startLevel and _level are 0-based now.
+            int targetLevel = startLevel;
+            int firstThreshold = (startLevel + 1) * 10;
+
+            if (_lines >= firstThreshold) {
+                targetLevel = startLevel + 1 + (_lines - firstThreshold) / 10;
+            }
+
+            // If we haven't reached the first threshold yet, we are still at startLevel.
+            // The above logic handles this (targetLevel initialized to startLevel).
+
+            if (targetLevel > _level) {
+                _level = targetLevel;
+                // Update gravity to exact NES speed for the new level
+                gravityMs = gravityMsForLevel(_level, gravityGlobalMultiplier);
+                if (levelUpCallback) levelUpCallback(_level);
+            }
+        } else {
+            // Challenge keeps level tied to the current challenge stage; gravity already set there
+            _level = challengeLevelIndex;
+        }
+
+        // Trigger sound effect callback for line clears
+        if (soundCallback) {
+            soundCallback(cleared);
+        }
+    }
+    else {
+        // No clear -> reset combo
+        _currentCombo = 0;
+    }
+    if (!gameOver) spawn();
+}
+
+int Game::checkLines() {
+    completedLines.clear();
+    
+    // Check each row from bottom to top
+    for (int y = ROWS - 1; y >= 0; --y) {
+        bool full = true;
+        for (int x = 0; x < COLS; ++x) {
+            if (board[y*COLS + x] == 0) {
+                full = false;
+                break;
+            }
+        }
+        if (full) {
+            completedLines.push_back(y);
+        }
+    }
+
+    // Pre-play asteroid destroy SFX immediately when a clearing line contains asteroids (reduces latency)
+    if (!completedLines.empty() && mode == GameMode::Challenge) {
+        std::optional<AsteroidType> foundType;
+        for (int y : completedLines) {
+            for (int x = 0; x < COLS; ++x) {
+                int idx = y * COLS + x;
+                if (isAsteroidValue(board[idx])) {
+                    foundType = asteroidTypeFromValue(board[idx]);
+                } else if (idx >= 0 && idx < static_cast<int>(asteroidGrid.size()) && asteroidGrid[idx].has_value()) {
+                    foundType = asteroidGrid[idx]->type;
+                }
+            }
+        }
+        if (foundType.has_value()) {
+            pendingAsteroidDestroyType = foundType;
+            if (!asteroidDestroySoundPreplayed && asteroidDestroyedCallback) {
+                asteroidDestroySoundPreplayed = true;
+                asteroidDestroyedCallback(*foundType);
+            }
+        }
+    }
+    
+    return static_cast<int>(completedLines.size());
+}
+
+void Game::clearCompletedLines() {
+    if (completedLines.empty()) return;
+    
+    actualClearLines();
+    completedLines.clear();
+}
+
+void Game::actualClearLines() {
+    if (completedLines.empty()) return;
+        recentAsteroidExplosions.clear();
+
+    std::array<int, COLS*ROWS> newBoard{};
+    std::array<std::optional<AsteroidCell>, COLS*ROWS> newAst{};
+    for (auto &cell : newAst) cell.reset();
+    std::fill(newBoard.begin(), newBoard.end(), 0);
+
+    handleAsteroidsOnClearedRows(completedLines, newBoard, newAst);
+
+    board = newBoard;
+    asteroidGrid = newAst;
+
+    // Apply asteroid-specific gravity after the board collapses
+    applyAsteroidGravity();
+
+    // Reset preplay latch so future destroys can fire again
+    pendingAsteroidDestroyType.reset();
+    asteroidDestroySoundPreplayed = false;
+
+    if (mode == GameMode::Challenge) {
+        if (asteroidsRemainingCount <= 0) {
+            int nextLevel = challengeLevelIndex + 1;
+            if (nextLevel > ASTEROID_MAX_LEVEL) {
+                challengeComplete = true;
+                challengeLevelActive = false;
+                challengeAdvanceQueued = false;
+                challengeQueuedLevel = 0;
+            } else {
+                challengeAdvanceQueued = true;
+                challengeQueuedLevel = nextLevel;
+                challengeLevelActive = false;
+                setPaused(true);
+            }
+        }
+    }
+}
+
+void Game::handleAsteroidsOnClearedRows(const std::vector<int>& clearedRows,
+                                         std::array<int, COLS*ROWS>& outBoard,
+                                         std::array<std::optional<AsteroidCell>, COLS*ROWS>& outAsteroids) {
+    std::vector<bool> clearedFlags(ROWS, false);
+    for (int r : clearedRows) {
+        if (r >= 0 && r < ROWS) {
+            clearedFlags[r] = true;
+        }
+    }
+
+    // Track asteroid count updates during processing
+    int destroyedThisPass = 0;
+    std::optional<AsteroidType> lastDestroyedType;
+
+    // Precompute how many cleared rows are at or below each row to reposition survivors
+    std::array<int, ROWS> clearedBelow{};
+    int running = 0;
+    for (int y = ROWS - 1; y >= 0; --y) {
+        clearedBelow[y] = running;
+        if (clearedFlags[y]) {
+            ++running;
+        }
+    }
+
+    for (int y = ROWS - 1; y >= 0; --y) {
+        for (int x = 0; x < COLS; ++x) {
+            int srcIdx = y * COLS + x;
+            bool rowCleared = clearedFlags[y];
+            bool isAsteroid = asteroidGrid[srcIdx].has_value();
+
+            if (rowCleared) {
+                if (!isAsteroid) {
+                    continue; // normal blocks in cleared rows vanish
+                }
+
+                AsteroidCell cell = *asteroidGrid[srcIdx];
+                if (cell.hitsRemaining > 0) {
+                    --cell.hitsRemaining;
+                }
+                if (cell.hitsRemaining == 0) {
+                    destroyedThisPass++;
+                    lastDestroyedType = cell.type;
+                    continue;
+                }
+
+                // Update visual/gravity state for surviving asteroids
+                cell.visualState = static_cast<uint8_t>(std::min<int>(3, cell.visualState + 1));
+                if (cell.type == AsteroidType::Falling || cell.type == AsteroidType::Core) {
+                    cell.gravityEnabled = true;
+                }
+
+                int destY = y + clearedBelow[y]; // shift down by cleared rows below
+                if (destY >= ROWS) {
+                    continue; // off the board after collapse
+                }
+                int destIdx = destY * COLS + x;
+                outBoard[destIdx] = asteroidBoardValue(cell.type);
+                outAsteroids[destIdx] = cell;
+            } else {
+                int destY = y + clearedBelow[y];
+                if (destY >= ROWS) {
+                    continue;
+                }
+                int destIdx = destY * COLS + x;
+                outBoard[destIdx] = board[srcIdx];
+                if (isAsteroid) {
+                    outAsteroids[destIdx] = asteroidGrid[srcIdx];
+                }
+            }
+        }
+    }
+
+    if (destroyedThisPass > 0) {
+        asteroidsRemainingCount = std::max(0, asteroidsRemainingCount - destroyedThisPass);
+        if (!asteroidDestroySoundPreplayed && asteroidDestroyedCallback && lastDestroyedType.has_value()) {
+            asteroidDestroyedCallback(*lastDestroyedType);
+        }
+    }
+}
+
+void Game::applyAsteroidGravity() {
+    if (asteroidsRemainingCount <= 0) {
+        return;
+    }
+    bool moved = false;
+    do {
+        moved = false;
+        for (int y = ROWS - 2; y >= 0; --y) {
+            for (int x = 0; x < COLS; ++x) {
+                int idx = y * COLS + x;
+                if (!asteroidGrid[idx].has_value()) {
+                    continue;
+                }
+                if (!asteroidGrid[idx]->gravityEnabled) {
+                    continue;
+                }
+                int belowIdx = (y + 1) * COLS + x;
+                if (board[belowIdx] == 0) {
+                    // Move asteroid down one cell
+                    board[belowIdx] = board[idx];
+                    asteroidGrid[belowIdx] = asteroidGrid[idx];
+                    board[idx] = 0;
+                    asteroidGrid[idx].reset();
+                    moved = true;
+                }
+            }
+        }
+    } while (moved);
+}
+
+bool Game::tryMoveDown() {
+    Piece p = cur; p.y += 1; if (!collides(p)) { cur = p; return true; } return false;
+}
+
+void Game::tickGravity(double frameMs) {
+    if (paused) return; // Don't tick gravity when paused
+    
+    // Soft drop: 20x faster for rapid continuous dropping
+    double effectiveGravityMs = softDropping ? (gravityMs / 5.0) : gravityMs;
+    
+    fallAcc += frameMs;
+    
+    while (fallAcc >= effectiveGravityMs) {
+        // Attempt to move down by one row
+        if (tryMoveDown()) {
+            // Award soft drop points only if player is actively holding Down
+            if (softDropping) {
+                _score += 1;
+            }
+        } else {
+            // Can't move down further, lock piece
+            lockPiece();
+            if (gameOver) break;
+        }
+        fallAcc -= effectiveGravityMs;
+    }
+}
+
+void Game::softDropBoost(double frameMs) { 
+    // This method is now deprecated - soft drop is handled in tickGravity
+    // Kept for API compatibility but does nothing
+    (void)frameMs;
+}
+
+void Game::updateVisualEffects(double frameMs) {
+    if (frameMs <= 0.0) {
+        return;
+    }
+
+    if (hardDropShakeTimerMs <= 0.0) {
+        hardDropShakeTimerMs = 0.0;
+        if (!hardDropCells.empty()) {
+            hardDropCells.clear();
+        }
+        return;
+    }
+
+    hardDropShakeTimerMs = std::max(0.0, hardDropShakeTimerMs - frameMs);
+    if (hardDropShakeTimerMs <= 0.0 && !hardDropCells.empty()) {
+        hardDropCells.clear();
+    }
+}
+
+void Game::hardDrop() { 
+    if (paused) return;
+    // Count how many rows we drop for scoring parity with JS
+    int rows = 0;
+    while (tryMoveDown()) { rows++; }
+    // JS: POINTS.HARD_DROP = 1 per cell
+    if (rows > 0) {
+        _score += rows * 1;
+    }
+    hardDropCells.clear();
+    hardDropCells.reserve(8);
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (!cellFilled(cur, cx, cy)) {
+                continue;
+            }
+            int gx = cur.x + cx;
+            int gy = cur.y + cy;
+            if (gx < 0 || gx >= COLS || gy >= ROWS) {
+                continue;
+            }
+            if (gy >= 0) {
+                hardDropCells.push_back(SDL_Point{gx, gy});
+            }
+        }
+    }
+
+    ++hardDropFxId;
+    lockPiece();
+    hardDropShakeTimerMs = HARD_DROP_SHAKE_DURATION_MS;
+}
+
+double Game::hardDropShakeStrength() const {
+    if (hardDropShakeTimerMs <= 0.0) {
+        return 0.0;
+    }
+    return std::clamp(hardDropShakeTimerMs / HARD_DROP_SHAKE_DURATION_MS, 0.0, 1.0);
+}
+
+void Game::rotate(int dir) {
+    if (paused) return;
+    
+    Piece p = cur;
+    p.rot = (p.rot + dir + 4) % 4;
+    
+    // Try rotation at current position first
+    if (!collides(p)) {
+        // If rotation at current position would place cells above the top,
+        // attempt to shift it down so the topmost block sits at gy == 0.
+        int minGy = std::numeric_limits<int>::max();
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!cellFilled(p, cx, cy)) continue;
+                minGy = std::min(minGy, p.y + cy);
+            }
+        }
+
+        if (minGy < 0) {
+            Piece adj = p;
+            adj.y += -minGy;
+            if (!collides(adj)) {
+                cur = adj;
+                return;
+            }
+            // Can't shift into place without collision - fall through to kicks
+        } else {
+            cur = p;
+            return;
+        }
+    }
+    
+    // Standard SRS Wall Kicks
+    // See: https://tetris.wiki/Super_Rotation_System#Wall_kicks
+    
+    // JLSTZ Wall Kicks (0->R, R->2, 2->L, L->0)
+    // We only implement the clockwise (0->1, 1->2, 2->3, 3->0) and counter-clockwise (0->3, 3->2, 2->1, 1->0)
+    // For simplicity in this codebase, we'll use a unified set of tests that covers most cases
+    // or we can implement the full table.
+    
+    // Let's use a robust set of kicks that covers most standard situations
+    std::vector<std::pair<int,int>> kicks;
+    
+    if (p.type == I) {
+        // I-piece kicks
+        kicks = {
+            {0, 0},   // Basic rotation
+            {-2, 0}, {1, 0}, {-2, -1}, {1, 2}, // 0->1 (R)
+            {2, 0}, {-1, 0}, {2, 1}, {-1, -2}, // 1->0 (L)
+            {-1, 0}, {2, 0}, {-1, 2}, {2, -1}, // 1->2 (R)
+            {1, 0}, {-2, 0}, {1, -2}, {-2, 1}, // 2->1 (L)
+            {2, 0}, {-1, 0}, {2, 1}, {-1, -2}, // 2->3 (R)
+            {-2, 0}, {1, 0}, {-2, -1}, {1, 2}, // 3->2 (L)
+            {1, 0}, {-2, 0}, {1, -2}, {-2, 1}, // 3->0 (R)
+            {-1, 0}, {2, 0}, {-1, 2}, {2, -1}  // 0->3 (L)
+        };
+        // The above is a superset; for a specific rotation state transition we should pick the right row.
+        // However, since we don't track "last rotation state" easily here (we just have p.rot),
+        // we'll try a generally permissive set of kicks that works for I-piece.
+        // A simplified "try everything" approach for I-piece:
+        kicks = {
+            {0, 0},
+            {-2, 0}, { 2, 0},
+            {-1, 0}, { 1, 0},
+            { 0,-1}, { 0, 1}, // Up/Down
+            {-2,-1}, { 2,-1}, // Diagonal up
+            { 1, 2}, {-1, 2}, // Diagonal down
+            {-2, 1}, { 2, 1}
+        };
+    } else {
+        // JLSTZ kicks
+        kicks = {
+            {0, 0},
+            {-1, 0}, { 1, 0}, // Left/Right
+            { 0,-1},          // Up (floor kick)
+            {-1,-1}, { 1,-1}, // Diagonal up
+            { 0, 1}           // Down (rare but possible)
+        };
+    }
+
+    for (auto kick : kicks) {
+        Piece test = p;
+        test.x = cur.x + kick.first;
+        test.y = cur.y + kick.second;
+        if (!collides(test)) {
+            // Prevent rotated piece from ending up above the visible playfield.
+            // If any cell of `test` is above the top (gy < 0), try shifting it
+            // downward so the highest block sits at row 0. Accept the shift
+            // only if it doesn't collide; otherwise keep searching kicks.
+            int minGy = std::numeric_limits<int>::max();
+            for (int cy = 0; cy < 4; ++cy) {
+                for (int cx = 0; cx < 4; ++cx) {
+                    if (!cellFilled(test, cx, cy)) continue;
+                    minGy = std::min(minGy, test.y + cy);
+                }
+            }
+
+            if (minGy < 0) {
+                Piece adj = test;
+                adj.y += -minGy; // shift down so topmost block is at gy == 0
+                if (!collides(adj)) {
+                    cur = adj;
+                    return;
+                }
+                // couldn't shift without collision, try next kick
+            } else {
+                cur = test;
+                return;
+            }
+        }
+    }
+}
+
+void Game::move(int dx) {
+    if (paused) return;
+    Piece p = cur; p.x += dx; if (!collides(p)) cur = p;
+}
+
+void Game::holdCurrent() {
+    if (paused || !canHold) return;
+    
+    if (hold.type == PIECE_COUNT) {
+        // First hold - just store current piece and spawn new one
+        hold = cur;
+        // I-piece needs to start one row higher due to its height when vertical
+        int holdSpawnY = (hold.type == I) ? -2 : -1;
+        hold.x = 3; hold.y = holdSpawnY; hold.rot = 0;
+        spawn();
+    } else {
+        // Swap current with held piece
+        Piece temp = hold;
+        hold = cur;
+        // I-piece needs to start one row higher due to its height when vertical
+        int holdSpawnY = (hold.type == I) ? -2 : -1;
+        int currentSpawnY = (temp.type == I) ? -2 : -1;
+        hold.x = 3; hold.y = holdSpawnY; hold.rot = 0;
+        cur = temp;
+        cur.x = 3; cur.y = currentSpawnY; cur.rot = 0;
+    }
+    
+    canHold = false; // Can only hold once per piece spawn
+}
diff --git a/src/gameplay/core/Game.h b/src/gameplay/core/Game.h
new file mode 100644
index 0000000..4af1b53
--- /dev/null
+++ b/src/gameplay/core/Game.h
@@ -0,0 +1,216 @@
+
+// Game.h - Core Tetris game logic (board, piece mechanics, scoring events only)
+#pragma once
+#include <array>
+#include <vector>
+#include <random>
+#include <cstdint>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <SDL3/SDL.h>
+#include "../../core/GravityManager.h"
+
+enum PieceType { I, O, T, S, Z, J, L, PIECE_COUNT };
+using Shape = std::array<uint16_t, 4>; // four rotation bitmasks
+
+// Game runtime mode
+enum class GameMode { Endless, Cooperate, Challenge };
+
+// Special obstacle blocks used by Challenge mode
+enum class AsteroidType : uint8_t { Normal = 0, Armored = 1, Falling = 2, Core = 3 };
+
+struct AsteroidCell {
+    AsteroidType type{AsteroidType::Normal};
+    uint8_t hitsRemaining{1};
+    bool gravityEnabled{false};
+    uint8_t visualState{0};
+};
+
+class Game {
+public:
+    static constexpr int COLS = 10;
+    static constexpr int ROWS = 20;
+    static constexpr int TILE = 28; // logical cell size in pixels (render layer decides use)
+
+    struct Piece { PieceType type{PIECE_COUNT}; int rot{0}; int x{3}; int y{-2}; };
+
+    explicit Game(int startLevel = 0, GameMode mode = GameMode::Endless) : mode(mode) { reset(startLevel); }
+    void reset(int startLevel = 0);
+    void startChallengeRun(int startingLevel = 1); // resets stats and starts challenge level 1 (or provided)
+    void beginNextChallengeLevel(); // advances to the next challenge level preserving score/time
+
+    // Simulation -----------------------------------------------------------
+    void tickGravity(double frameMs);          // advance gravity accumulator & drop
+    void softDropBoost(double frameMs);        // accelerate fall while held
+    void hardDrop();                           // instant drop & lock
+    void setSoftDropping(bool on);             // mark if player holds Down
+    void move(int dx);                         // horizontal move
+    void rotate(int dir);                      // +1 cw, -1 ccw (simple wall-kick)
+    void holdCurrent();                        // swap with hold (once per spawn)
+
+    // Accessors -----------------------------------------------------------
+    const std::array<int, COLS*ROWS>& boardRef() const { return board; }
+    const Piece& current() const { return cur; }
+    const Piece& next() const { return nextPiece; }
+    const Piece& held() const { return hold; }
+    bool canHoldPiece() const { return canHold; }
+    bool isGameOver() const { return gameOver; }
+    bool isPaused() const { return paused; }
+    void setPaused(bool p);
+    GameMode getMode() const { return mode; }
+    void setMode(GameMode m) { mode = m; }
+    int score() const { return _score; }
+    int lines() const { return _lines; }
+    int level() const { return _level; }
+    int challengeLevel() const { return challengeLevelIndex; }
+    int asteroidsRemaining() const { return asteroidsRemainingCount; }
+    int asteroidsTotal() const { return asteroidsTotalThisLevel; }
+    bool isChallengeComplete() const { return challengeComplete; }
+    bool isChallengeLevelActive() const { return challengeLevelActive; }
+    bool isChallengeAdvanceQueued() const { return challengeAdvanceQueued; }
+    int queuedChallengeLevel() const { return challengeQueuedLevel; }
+    int consumeQueuedChallengeLevel(); // returns next level if queued, else 0
+    int startLevelBase() const { return startLevel; }
+    double elapsed() const; // Now calculated from start time
+    void updateElapsedTime(); // Update elapsed time from system clock
+    bool isSoftDropping() const { return softDropping; }
+    const std::array<std::optional<AsteroidCell>, COLS*ROWS>& asteroidCells() const { return asteroidGrid; }
+    const std::vector<SDL_Point>& getRecentAsteroidExplosions() const { return recentAsteroidExplosions; }
+    void clearRecentAsteroidExplosions() { recentAsteroidExplosions.clear(); }
+    
+    // Block statistics
+    const std::array<int, PIECE_COUNT>& getBlockCounts() const { return blockCounts; }
+    
+    // Line clearing effects support
+    bool hasCompletedLines() const { return !completedLines.empty(); }
+    const std::vector<int>& getCompletedLines() const { return completedLines; }
+    void clearCompletedLines(); // Actually remove the lines from the board
+    
+    // Sound effect callbacks
+    using SoundCallback = std::function<void(int)>; // Callback for line clear sounds (number of lines)
+    using LevelUpCallback = std::function<void(int)>; // Callback for level up sounds
+    using AsteroidDestroyedCallback = std::function<void(AsteroidType)>; // Callback when an asteroid is fully destroyed
+    void setSoundCallback(SoundCallback callback) { soundCallback = callback; }
+    void setLevelUpCallback(LevelUpCallback callback) { levelUpCallback = callback; }
+    void setAsteroidDestroyedCallback(AsteroidDestroyedCallback callback) { asteroidDestroyedCallback = callback; }
+
+    // Shape helper --------------------------------------------------------
+    static bool cellFilled(const Piece& p, int cx, int cy);
+
+    // Gravity tuning accessors (public API for HUD/tuning)
+    void setGravityGlobalMultiplier(double m) { gravityGlobalMultiplier = m; }
+    double getGravityGlobalMultiplier() const;
+    double getGravityMs() const;
+    double getFallAccumulator() const { return fallAcc; } // Debug: time accumulated toward next drop
+    void setLevelGravityMultiplier(int level, double m);
+
+    // Visual effect hooks
+    void updateVisualEffects(double frameMs);
+    bool hasHardDropShake() const { return hardDropShakeTimerMs > 0.0; }
+    double hardDropShakeStrength() const;
+    const std::vector<SDL_Point>& getHardDropCells() const { return hardDropCells; }
+    uint32_t getHardDropFxId() const { return hardDropFxId; }
+    uint64_t getCurrentPieceSequence() const { return pieceSequence; }
+    // Additional stats
+    int tetrisesMade() const { return _tetrisesMade; }
+    int maxCombo() const { return _maxCombo; }
+    int comboCount() const { return _comboCount; }
+
+private:
+    static constexpr int ASTEROID_BASE = 100; // sentinel offset for board encoding
+    static constexpr int ASTEROID_MAX_LEVEL = 100;
+
+    std::array<int, COLS*ROWS> board{}; // 0 empty else color index
+    Piece cur{}, hold{}, nextPiece{};   // current, held & next piece
+    bool canHold{true};
+    bool paused{false};
+    std::vector<PieceType> bag;         // 7-bag randomizer
+    std::mt19937 rng{ std::random_device{}() };
+    std::array<int, PIECE_COUNT> blockCounts{}; // Count of each piece type used
+
+    int _score{0};
+    int _lines{0};
+    int _level{1};
+    int _tetrisesMade{0};
+    int _currentCombo{0};
+    int _maxCombo{0};
+    int _comboCount{0};
+    double gravityMs{800.0};
+    double fallAcc{0.0};
+    Uint64 _startTime{0}; // Performance counter at game start
+    Uint64 _pausedTime{0}; // Time spent paused (in performance counter ticks)
+    Uint64 _lastPauseStart{0}; // When the current pause started
+    bool gameOver{false};
+    int startLevel{0};
+    bool softDropping{false}; // true while player holds Down key
+    
+    // Line clearing support
+    std::vector<int> completedLines; // Rows that are complete and ready for effects
+    
+    // Sound effect callbacks
+    SoundCallback soundCallback;
+    LevelUpCallback levelUpCallback;
+    AsteroidDestroyedCallback asteroidDestroyedCallback;
+    // Gravity tuning -----------------------------------------------------
+    // Global multiplier applied to all level timings (use to slow/speed whole-game gravity)
+    double gravityGlobalMultiplier{1.0};
+    // Gravity manager encapsulates frames table, multipliers and conversions
+    GravityManager gravityMgr;
+    // Backwards-compatible accessors (delegate to gravityMgr)
+    double computeGravityMsForLevel(int level) const;
+
+    // Impact FX timers
+    double hardDropShakeTimerMs{0.0};
+    static constexpr double HARD_DROP_SHAKE_DURATION_MS = 320.0;
+    std::vector<SDL_Point> hardDropCells;
+    uint32_t hardDropFxId{0};
+    uint64_t pieceSequence{0};
+
+    // Challenge mode state -------------------------------------------------
+    GameMode mode{GameMode::Endless};
+    int challengeLevelIndex{1};
+    int asteroidsRemainingCount{0};
+    int asteroidsTotalThisLevel{0};
+    bool challengeComplete{false};
+    std::array<std::optional<AsteroidCell>, COLS*ROWS> asteroidGrid{};
+    uint32_t challengeSeedBase{0};
+    std::mt19937 challengeRng{ std::random_device{}() };
+    bool challengeLevelActive{false};
+    bool challengeAdvanceQueued{false};
+    int challengeQueuedLevel{0};
+    // Asteroid SFX latency mitigation
+    std::optional<AsteroidType> pendingAsteroidDestroyType;
+    bool asteroidDestroySoundPreplayed{false};
+
+    // Recent asteroid explosion positions (grid coords) for renderer FX
+    std::vector<SDL_Point> recentAsteroidExplosions;
+    
+    // Expose the internal challenge seed base for deterministic FX/RNG coordination
+public:
+    uint32_t getChallengeSeedBase() const { return challengeSeedBase; }
+
+    // Helpers for board encoding of asteroids
+    static bool isAsteroidValue(int boardValue);
+    static AsteroidType asteroidTypeFromValue(int boardValue);
+    static int asteroidBoardValue(AsteroidType t);
+
+    // Internal helpers ----------------------------------------------------
+    void refillBag();
+    void spawn();
+    bool collides(const Piece& p) const;
+    void lockPiece();
+    int checkLines(); // Find completed lines and store them
+    void actualClearLines(); // Actually remove lines from board
+    bool tryMoveDown(); // one-row fall; returns true if moved
+    void clearAsteroidGrid();
+    void setupChallengeLevel(int level, bool preserveStats);
+    void placeAsteroidsForLevel(int level);
+    AsteroidType chooseAsteroidTypeForLevel(int level);
+    AsteroidCell makeAsteroidForType(AsteroidType t) const;
+    void handleAsteroidsOnClearedRows(const std::vector<int>& clearedRows,
+                                      std::array<int, COLS*ROWS>& outBoard,
+                                      std::array<std::optional<AsteroidCell>, COLS*ROWS>& outAsteroids);
+    void applyAsteroidGravity();
+    // Gravity tuning helpers (public API declared above)
+};
diff --git a/src/gameplay/effects/LineEffect.cpp b/src/gameplay/effects/LineEffect.cpp
new file mode 100644
index 0000000..713718d
--- /dev/null
+++ b/src/gameplay/effects/LineEffect.cpp
@@ -0,0 +1,478 @@
+// LineEffect.cpp - Implementation of line clearing visual and audio effects
+#include "LineEffect.h"
+#include <algorithm>
+#include <cmath>
+#include "audio/Audio.h"
+#include "gameplay/core/Game.h"
+
+#ifndef M_PI
+#define M_PI 3.14159265358979323846
+#endif
+
+namespace {
+float randRange(float min, float max) {
+    return min + (static_cast<float>(rand()) / static_cast<float>(RAND_MAX)) * (max - min);
+}
+}
+
+LineEffect::Particle::Particle(float px, float py, Style particleStyle, SDL_Color tint)
+    : x(px), y(py), size(0.0f), alpha(1.0f), life(0.0f), lifeSpan(0.0f),
+      blockType(rand() % 7), color(tint), style(particleStyle) {
+    float angle = randRange(0.0f, static_cast<float>(M_PI) * 2.0f);
+    float speed = (style == Style::Shard) ? randRange(140.0f, 260.0f) : randRange(70.0f, 140.0f);
+    vx = std::cos(angle) * speed;
+    vy = std::sin(angle) * speed - ((style == Style::Shard) ? randRange(40.0f, 110.0f) : randRange(10.0f, 40.0f));
+    size = (style == Style::Shard) ? randRange(8.0f, 16.0f) : randRange(5.0f, 10.0f);
+    lifeSpan = (style == Style::Shard) ? randRange(0.70f, 1.20f) : randRange(1.00f, 1.50f);
+}
+
+void LineEffect::Particle::update(float dt) {
+    life += dt;
+    if (life >= lifeSpan) {
+        alpha = 0.0f;
+        return;
+    }
+
+    const float progress = life / lifeSpan;
+    x += vx * dt;
+    y += vy * dt;
+    float gravity = (style == Style::Shard) ? 520.0f : 240.0f;
+    vy += gravity * dt;
+    vx *= (style == Style::Shard) ? 0.96f : 0.985f;
+    float shrinkRate = (style == Style::Shard) ? 24.0f : 10.0f;
+    size = std::max(2.0f, size - shrinkRate * dt);
+    alpha = 1.0f - progress;
+}
+
+void LineEffect::Particle::render(SDL_Renderer* renderer, SDL_Texture* blocksTex) {
+    if (alpha <= 0.0f) return;
+
+    if (blocksTex) {
+        Uint8 prevA = 255;
+        SDL_GetTextureAlphaMod(blocksTex, &prevA);
+        SDL_SetTextureAlphaMod(blocksTex, static_cast<Uint8>(alpha * 255.0f));
+
+        const int SPRITE_SIZE = 90;
+        float srcX = blockType * SPRITE_SIZE + 2;
+        float srcY = 2;
+        float srcW = SPRITE_SIZE - 4;
+        float srcH = SPRITE_SIZE - 4;
+
+        SDL_FRect srcRect = {srcX, srcY, srcW, srcH};
+        SDL_FRect dstRect = {x - size/2.0f, y - size/2.0f, size, size};
+        SDL_RenderTexture(renderer, blocksTex, &srcRect, &dstRect);
+        SDL_SetTextureAlphaMod(blocksTex, prevA);
+    } else {
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+        Uint8 adjustedAlpha = static_cast<Uint8>(alpha * 255.0f);
+        SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, adjustedAlpha);
+        float radius = size * 0.5f;
+        for (int iy = -static_cast<int>(radius); iy <= static_cast<int>(radius); ++iy) {
+            for (int ix = -static_cast<int>(radius); ix <= static_cast<int>(radius); ++ix) {
+                float dist2 = float(ix * ix + iy * iy);
+                if (dist2 <= radius * radius) {
+                    SDL_RenderPoint(renderer, x + ix, y + iy);
+                }
+            }
+        }
+    }
+}
+
+LineEffect::Spark::Spark(float px, float py, SDL_Color tint)
+    : x(px), y(py), vx(0.0f), vy(0.0f), life(0.0f), maxLife(randRange(0.40f, 0.80f)),
+      thickness(randRange(1.0f, 2.0f)), color(tint) {
+    float angle = randRange(0.0f, static_cast<float>(M_PI) * 2.0f);
+    float speed = randRange(240.0f, 520.0f);
+    vx = std::cos(angle) * speed;
+    vy = std::sin(angle) * speed - randRange(80.0f, 150.0f);
+}
+
+void LineEffect::Spark::update(float dt) {
+    life += dt;
+    x += vx * dt;
+    y += vy * dt;
+    vy += 420.0f * dt;
+    vx *= 0.99f;
+}
+
+void LineEffect::Spark::render(SDL_Renderer* renderer) const {
+    if (life >= maxLife) return;
+    float progress = life / maxLife;
+    float alpha = (1.0f - progress) * 255.0f;
+    if (alpha <= 0.0f) return;
+
+    SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, static_cast<Uint8>(alpha));
+    float trail = 0.018f * (1.2f - progress) * thickness;
+    SDL_FPoint tail{ x - vx * trail, y - vy * trail };
+    SDL_RenderLine(renderer, x, y, tail.x, tail.y);
+}
+
+LineEffect::GlowPulse::GlowPulse(float px, float py, float baseR, float maxR, SDL_Color tint)
+        : x(px), y(py), baseRadius(baseR), maxRadius(maxR), life(0.0f),
+            maxLife(randRange(0.45f, 0.70f)), color(tint) {
+    if (color.a == 0) color.a = 200;
+}
+
+void LineEffect::GlowPulse::update(float dt) {
+    life += dt;
+    if (life > maxLife) life = maxLife;
+}
+
+void LineEffect::GlowPulse::render(SDL_Renderer* renderer) const {
+    if (life >= maxLife) return;
+    float progress = life / maxLife;
+    float radius = baseRadius + (maxRadius - baseRadius) * progress;
+    float baseAlpha = (1.0f - progress) * (color.a / 255.0f);
+    int intRadius = static_cast<int>(std::ceil(radius));
+    for (int iy = -intRadius; iy <= intRadius; ++iy) {
+        float dy = static_cast<float>(iy);
+        float rowWidth = std::sqrt(std::max(0.0f, radius * radius - dy * dy));
+        float falloff = std::max(0.0f, 1.0f - std::abs(dy) / radius);
+        Uint8 alpha = static_cast<Uint8>(baseAlpha * falloff * 255.0f);
+        if (alpha == 0) continue;
+        SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, alpha);
+        SDL_FRect segment{
+            x - rowWidth,
+            y + dy,
+            rowWidth * 2.0f,
+            1.4f
+        };
+        SDL_RenderFillRect(renderer, &segment);
+    }
+}
+
+LineEffect::LineEffect() : renderer(nullptr), state(AnimationState::IDLE), timer(0.0f), 
+                          rng(std::random_device{}()), audioStream(nullptr) {
+}
+
+LineEffect::~LineEffect() {
+    shutdown();
+}
+
+bool LineEffect::init(SDL_Renderer* r) {
+    renderer = r;
+    initAudio();
+    return true;
+}
+
+void LineEffect::shutdown() {
+    // No separate audio stream anymore; SFX go through shared Audio mixer
+}
+
+void LineEffect::initAudio() {
+    // Generate simple beep sounds procedurally (fallback when voice SFX not provided)
+    
+    // Generate a simple line clear beep (440Hz for 0.2 seconds)
+    int sampleRate = 44100;
+    int duration = static_cast<int>(0.2f * sampleRate);
+    lineClearSample.resize(duration * 2); // Stereo
+    
+    for (int i = 0; i < duration; ++i) {
+        float t = static_cast<float>(i) / sampleRate;
+        float wave = std::sin(2.0f * M_PI * 440.0f * t) * 0.3f; // 440Hz sine wave
+        int16_t sample = static_cast<int16_t>(wave * 32767.0f);
+        lineClearSample[i * 2] = sample;     // Left channel
+        lineClearSample[i * 2 + 1] = sample; // Right channel
+    }
+    
+    // Generate a higher pitched tetris sound (880Hz for 0.4 seconds)
+    duration = static_cast<int>(0.4f * sampleRate);
+    tetrisSample.resize(duration * 2);
+    
+    for (int i = 0; i < duration; ++i) {
+        float t = static_cast<float>(i) / sampleRate;
+        float wave = std::sin(2.0f * M_PI * 880.0f * t) * 0.4f; // 880Hz sine wave
+        int16_t sample = static_cast<int16_t>(wave * 32767.0f);
+        tetrisSample[i * 2] = sample;     // Left channel
+        tetrisSample[i * 2 + 1] = sample; // Right channel
+    }
+}
+
+void LineEffect::startLineClear(const std::vector<int>& rows, int gridX, int gridY, int blockSize, int gridCols, int gapPx, int gapAfterCol) {
+    if (rows.empty()) return;
+    
+    clearingRows = rows;
+    effectGridCols = std::max(1, gridCols);
+    effectGapPx = std::max(0, gapPx);
+    effectGapAfterCol = std::clamp(gapAfterCol, 0, effectGridCols);
+    state = AnimationState::FLASH_WHITE;
+    timer = 0.0f;
+    dropProgress = 0.0f;
+    dropBlockSize = blockSize;
+    rowDropTargets.fill(0.0f);
+    particles.clear();
+    sparks.clear();
+    glowPulses.clear();
+
+    std::array<bool, Game::ROWS> rowClearing{};
+    for (int row : rows) {
+        if (row >= 0 && row < Game::ROWS) {
+            rowClearing[row] = true;
+        }
+    }
+
+    int clearedBelow = 0;
+    for (int row = Game::ROWS - 1; row >= 0; --row) {
+        if (rowClearing[row]) {
+            ++clearedBelow;
+        } else if (clearedBelow > 0) {
+            rowDropTargets[row] = static_cast<float>(clearedBelow * blockSize);
+        }
+    }
+    
+    // Create particles for each clearing row
+    for (int row : rows) {
+        createParticles(row, gridX, gridY, blockSize);
+    }
+    
+    // Play appropriate sound
+    playLineClearSound(static_cast<int>(rows.size()));
+}
+
+void LineEffect::createParticles(int row, int gridX, int gridY, int blockSize) {
+    const float centerY = gridY + row * blockSize + blockSize * 0.5f;
+    for (int col = 0; col < effectGridCols; ++col) {
+        float centerX = gridX + col * blockSize + blockSize * 0.5f;
+        if (effectGapPx > 0 && effectGapAfterCol > 0 && col >= effectGapAfterCol) {
+            centerX += static_cast<float>(effectGapPx);
+        }
+        SDL_Color tint = pickFireColor();
+        spawnGlowPulse(centerX, centerY, static_cast<float>(blockSize), tint);
+        spawnShardBurst(centerX, centerY, tint);
+        spawnSparkBurst(centerX, centerY, tint);
+    }
+}
+
+void LineEffect::spawnShardBurst(float x, float y, SDL_Color tint) {
+    int shardCount = 3 + rand() % 4;
+    for (int i = 0; i < shardCount; ++i) {
+        particles.emplace_back(x, y, Particle::Style::Shard, tint);
+    }
+    int emberCount = 2 + rand() % 3;
+    for (int i = 0; i < emberCount; ++i) {
+        particles.emplace_back(x, y, Particle::Style::Ember, tint);
+    }
+}
+
+void LineEffect::spawnSparkBurst(float x, float y, SDL_Color tint) {
+    int sparkCount = 4 + rand() % 5;
+    for (int i = 0; i < sparkCount; ++i) {
+        sparks.emplace_back(x, y, tint);
+    }
+}
+
+void LineEffect::spawnGlowPulse(float x, float y, float blockSize, SDL_Color tint) {
+    glowPulses.emplace_back(x, y, blockSize * 0.45f, blockSize * 2.3f, tint);
+}
+
+bool LineEffect::update(float deltaTime) {
+    if (state == AnimationState::IDLE) return true;
+    
+    timer += deltaTime;
+    
+    switch (state) {
+        case AnimationState::FLASH_WHITE:
+            if (timer >= FLASH_DURATION) {
+                state = AnimationState::EXPLODE_BLOCKS;
+                timer = 0.0f;
+            }
+            break;
+            
+        case AnimationState::EXPLODE_BLOCKS:
+            updateParticles(deltaTime);
+            updateSparks(deltaTime);
+            updateGlowPulses(deltaTime);
+            if (timer >= EXPLODE_DURATION) {
+                state = AnimationState::BLOCKS_DROP;
+                timer = 0.0f;
+            }
+            break;
+            
+        case AnimationState::BLOCKS_DROP:
+            updateParticles(deltaTime);
+            updateSparks(deltaTime);
+            updateGlowPulses(deltaTime);
+            dropProgress = std::min(1.0f, timer / DROP_DURATION);
+            if (timer >= DROP_DURATION) {
+                state = AnimationState::IDLE;
+                clearingRows.clear();
+                particles.clear();
+                sparks.clear();
+                glowPulses.clear();
+                rowDropTargets.fill(0.0f);
+                dropProgress = 0.0f;
+                dropBlockSize = 0;
+                return true; // Effect complete
+            }
+            break;
+            
+        case AnimationState::IDLE:
+            return true;
+    }
+    
+    return false; // Effect still running
+}
+
+void LineEffect::updateParticles(float dt) {
+    for (auto& particle : particles) {
+        particle.update(dt);
+    }
+    particles.erase(
+        std::remove_if(particles.begin(), particles.end(),
+                      [](const Particle& p) { return !p.isAlive(); }),
+        particles.end());
+}
+
+void LineEffect::updateSparks(float dt) {
+    for (auto& spark : sparks) {
+        spark.update(dt);
+    }
+    sparks.erase(
+        std::remove_if(sparks.begin(), sparks.end(),
+                      [](const Spark& s) { return !s.isAlive(); }),
+        sparks.end());
+}
+
+void LineEffect::updateGlowPulses(float dt) {
+    for (auto& pulse : glowPulses) {
+        pulse.update(dt);
+    }
+    glowPulses.erase(
+        std::remove_if(glowPulses.begin(), glowPulses.end(),
+                      [](const GlowPulse& p) { return !p.isAlive(); }),
+        glowPulses.end());
+}
+
+void LineEffect::render(SDL_Renderer* renderer, SDL_Texture* blocksTex, int gridX, int gridY, int blockSize, int gapPx, int gapAfterCol) {
+    if (state == AnimationState::IDLE) return;
+
+    // Allow caller to override gap mapping (useful for Coop renderer that inserts a mid-gap).
+    effectGapPx = std::max(0, gapPx);
+    effectGapAfterCol = std::clamp(gapAfterCol, 0, effectGridCols);
+    
+    switch (state) {
+        case AnimationState::FLASH_WHITE:
+            renderFlash(gridX, gridY, blockSize);
+            break;
+            
+        case AnimationState::EXPLODE_BLOCKS:
+            renderExplosion(blocksTex);
+            break;
+            
+        case AnimationState::BLOCKS_DROP:
+            renderExplosion(blocksTex);
+            break;
+            
+        case AnimationState::IDLE:
+            break;
+    }
+}
+
+float LineEffect::getRowDropOffset(int row) const {
+    if (state != AnimationState::BLOCKS_DROP) {
+        return 0.0f;
+    }
+    if (row < 0 || row >= Game::ROWS) {
+        return 0.0f;
+    }
+    float target = rowDropTargets[row];
+    if (target <= 0.0f) {
+        return 0.0f;
+    }
+    float eased = dropProgress * dropProgress * dropProgress;
+    return target * eased;
+}
+
+void LineEffect::renderFlash(int gridX, int gridY, int blockSize) {
+    // Create a flashing white effect with varying opacity
+    float progress = timer / FLASH_DURATION;
+    float flashIntensity = std::sin(progress * M_PI * 6.0f) * 0.5f + 0.5f;
+    
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+    Uint8 alpha = static_cast<Uint8>(flashIntensity * 180.0f);
+    
+    for (int row : clearingRows) {
+        SDL_SetRenderDrawColor(renderer, 255, 255, 255, alpha);
+        const int gapW = (effectGapPx > 0 && effectGapAfterCol > 0 && effectGapAfterCol < effectGridCols) ? effectGapPx : 0;
+        SDL_FRect flashRect = {
+            static_cast<float>(gridX - 4),
+            static_cast<float>(gridY + row * blockSize - 4),
+            static_cast<float>(effectGridCols * blockSize + gapW + 8),
+            static_cast<float>(blockSize + 8)
+        };
+        SDL_RenderFillRect(renderer, &flashRect);
+        
+        SDL_SetRenderDrawColor(renderer, 100, 150, 255, alpha / 2);
+        for (int i = 1; i <= 3; ++i) {
+            SDL_FRect glowRect = {
+                flashRect.x - i,
+                flashRect.y - i,
+                flashRect.w + 2*i,
+                flashRect.h + 2*i
+            };
+            SDL_RenderRect(renderer, &glowRect);
+        }
+    }
+}
+
+void LineEffect::renderExplosion(SDL_Texture* blocksTex) {
+    renderGlowPulses();
+    renderSparks();
+    renderParticleGlows();
+    for (auto& particle : particles) {
+        particle.render(renderer, blocksTex);
+    }
+}
+
+void LineEffect::renderGlowPulses() {
+    if (glowPulses.empty()) return;
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_ADD);
+    for (const auto& pulse : glowPulses) {
+        pulse.render(renderer);
+    }
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+}
+
+void LineEffect::renderSparks() {
+    if (sparks.empty()) return;
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_ADD);
+    for (const auto& spark : sparks) {
+        spark.render(renderer);
+    }
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+}
+
+void LineEffect::renderParticleGlows() {
+    if (particles.empty()) return;
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_ADD);
+    for (const auto& particle : particles) {
+        if (particle.alpha <= 0.0f) continue;
+        float radius = particle.size * 0.6f;
+        SDL_SetRenderDrawColor(renderer, particle.color.r, particle.color.g, particle.color.b,
+                               static_cast<Uint8>(particle.alpha * 150.0f));
+        SDL_FRect glowRect{ particle.x - radius, particle.y - radius, radius * 2.0f, radius * 2.0f };
+        SDL_RenderFillRect(renderer, &glowRect);
+    }
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+}
+
+void LineEffect::playLineClearSound(int lineCount) {
+    // Choose appropriate sound based on line count
+    const std::vector<int16_t>* sample = (lineCount == 4) ? &tetrisSample : &lineClearSample;
+    if (sample && !sample->empty()) {
+        // Mix via shared Audio device so it layers with music
+        Audio::instance().playSfx(*sample, 2, 44100, (lineCount == 4) ? 0.9f : 0.7f);
+    }
+}
+
+SDL_Color LineEffect::pickFireColor() const {
+    static const SDL_Color palette[] = {
+        {255, 200, 120, 210},
+        {255, 150, 90, 220},
+        {255, 100, 160, 200},
+        {120, 200, 255, 200},
+        {255, 255, 200, 210}
+    };
+    const size_t count = sizeof(palette) / sizeof(palette[0]);
+    return palette[rand() % count];
+}
diff --git a/src/gameplay/effects/LineEffect.h b/src/gameplay/effects/LineEffect.h
new file mode 100644
index 0000000..49a5263
--- /dev/null
+++ b/src/gameplay/effects/LineEffect.h
@@ -0,0 +1,126 @@
+// LineEffect.h - Line clearing visual and audio effects
+#pragma once
+#include <SDL3/SDL.h>
+#include <vector>
+#include <random>
+#include <array>
+
+#include "../core/Game.h"
+
+class LineEffect {
+public:
+    struct Particle {
+        enum class Style { Shard, Ember };
+        float x, y;
+        float vx, vy;
+        float size;
+        float alpha;
+        float life;
+        float lifeSpan;
+        int blockType;
+        SDL_Color color;
+        Style style;
+
+        Particle(float px, float py, Style particleStyle, SDL_Color tint);
+        void update(float dt);
+        void render(SDL_Renderer* renderer, SDL_Texture* blocksTex);
+        bool isAlive() const { return life < lifeSpan && alpha > 0.01f; }
+    };
+
+    struct Spark {
+        float x, y;
+        float vx, vy;
+        float life;
+        float maxLife;
+        float thickness;
+        SDL_Color color;
+
+        Spark(float px, float py, SDL_Color tint);
+        void update(float dt);
+        void render(SDL_Renderer* renderer) const;
+        bool isAlive() const { return life < maxLife; }
+    };
+
+    struct GlowPulse {
+        float x, y;
+        float baseRadius;
+        float maxRadius;
+        float life;
+        float maxLife;
+        SDL_Color color;
+
+        GlowPulse(float px, float py, float baseR, float maxR, SDL_Color tint);
+        void update(float dt);
+        void render(SDL_Renderer* renderer) const;
+        bool isAlive() const { return life < maxLife; }
+    };
+
+    enum class AnimationState {
+        IDLE,
+        FLASH_WHITE,
+        EXPLODE_BLOCKS,
+        BLOCKS_DROP
+    };
+
+    LineEffect();
+    ~LineEffect();
+    
+    bool init(SDL_Renderer* renderer);
+    void shutdown();
+    
+    // Start line clear effect for the specified rows
+    void startLineClear(const std::vector<int>& rows, int gridX, int gridY, int blockSize, int gridCols = Game::COLS, int gapPx = 0, int gapAfterCol = 0);
+    
+    // Update and render the effect
+    bool update(float deltaTime); // Returns true if effect is complete
+    void render(SDL_Renderer* renderer, SDL_Texture* blocksTex, int gridX, int gridY, int blockSize, int gapPx = 0, int gapAfterCol = 0);
+    float getRowDropOffset(int row) const;
+    
+    // Audio
+    void playLineClearSound(int lineCount);
+    
+    bool isActive() const { return state != AnimationState::IDLE; }
+
+private:
+    SDL_Renderer* renderer{nullptr};
+    AnimationState state{AnimationState::IDLE};
+    float timer{0.0f};
+    std::vector<int> clearingRows;
+    std::vector<Particle> particles;
+    std::vector<Spark> sparks;
+    std::vector<GlowPulse> glowPulses;
+    std::mt19937 rng{std::random_device{}()};
+    
+    // Audio resources
+    SDL_AudioStream* audioStream{nullptr};
+    std::vector<int16_t> lineClearSample;
+    std::vector<int16_t> tetrisSample;
+    
+    // Animation timing - Flash then immediate explosion effect
+    static constexpr float FLASH_DURATION = 0.18f;   // Slightly longer flash for anticipation
+    static constexpr float EXPLODE_DURATION = 0.9f;  // Extended fireworks time
+    static constexpr float DROP_DURATION = 0.35f;    // Allow lingering sparks before collapse
+    
+    void createParticles(int row, int gridX, int gridY, int blockSize);
+    void spawnShardBurst(float x, float y, SDL_Color tint);
+    void spawnSparkBurst(float x, float y, SDL_Color tint);
+    void spawnGlowPulse(float x, float y, float blockSize, SDL_Color tint);
+    void updateParticles(float dt);
+    void updateSparks(float dt);
+    void updateGlowPulses(float dt);
+    void renderFlash(int gridX, int gridY, int blockSize);
+    void renderExplosion(SDL_Texture* blocksTex);
+    void renderGlowPulses();
+    void renderSparks();
+    void renderParticleGlows();
+    bool loadAudioSample(const std::string& path, std::vector<int16_t>& sample);
+    void initAudio();
+    SDL_Color pickFireColor() const;
+
+    std::array<float, Game::ROWS> rowDropTargets{};
+    float dropProgress = 0.0f;
+    int dropBlockSize = 0;
+    int effectGridCols = Game::COLS;
+    int effectGapPx = 0;
+    int effectGapAfterCol = 0;
+};
diff --git a/src/graphics/Font.cpp b/src/graphics/Font.cpp
index 145da63..6520720 100644
--- a/src/graphics/Font.cpp
+++ b/src/graphics/Font.cpp
@@ -19,3 +19,18 @@ void FontAtlas::draw(SDL_Renderer* r, float x, float y, const std::string& text,
     if (tex) { SDL_FRect dst{ x, y, (float)surf->w, (float)surf->h }; SDL_RenderTexture(r, tex, nullptr, &dst); SDL_DestroyTexture(tex); }
     SDL_DestroySurface(surf);
 }
+
+void FontAtlas::measure(const std::string& text, float scale, int& outW, int& outH) {
+    outW = 0; outH = 0;
+    if (scale <= 0) return;
+    int pt = int(baseSize * scale);
+    if (pt < 1) pt = 1;
+    TTF_Font* f = getSized(pt);
+    if (!f) return;
+    // Use render-to-surface measurement to avoid dependency on specific TTF_* measurement API variants
+    SDL_Color dummy = {255,255,255,255};
+    SDL_Surface* surf = TTF_RenderText_Blended(f, text.c_str(), text.length(), dummy);
+    if (!surf) return;
+    outW = surf->w; outH = surf->h;
+    SDL_DestroySurface(surf);
+}
diff --git a/src/graphics/Font.h b/src/graphics/Font.h
index ba4b2a9..3ff2846 100644
--- a/src/graphics/Font.h
+++ b/src/graphics/Font.h
@@ -10,6 +10,8 @@ public:
     bool init(const std::string& path, int basePt);
     void shutdown();
     void draw(SDL_Renderer* r, float x, float y, const std::string& text, float scale, SDL_Color color);
+    // Measure rendered text size in pixels for a given scale
+    void measure(const std::string& text, float scale, int& outW, int& outH);
 private:
     std::string fontPath;
     int baseSize{24};
diff --git a/src/graphics/GameRenderer.cpp b/src/graphics/GameRenderer.cpp
new file mode 100644
index 0000000..fcac0a9
--- /dev/null
+++ b/src/graphics/GameRenderer.cpp
@@ -0,0 +1,703 @@
+#include "GameRenderer.h"
+#include "../gameplay/Game.h"
+#include "../graphics/Font.h"
+#include "../gameplay/LineEffect.h"
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstdio>
+#include <random>
+#include <vector>
+
+namespace {
+
+// Color constants (copied from main.cpp)
+static const SDL_Color COLORS[] = {
+    {0, 0, 0, 255},        // 0: BLACK (empty)
+    {0, 255, 255, 255},    // 1: I-piece - cyan
+    {255, 255, 0, 255},    // 2: O-piece - yellow
+    {128, 0, 128, 255},    // 3: T-piece - purple
+    {0, 255, 0, 255},      // 4: S-piece - green
+    {255, 0, 0, 255},      // 5: Z-piece - red
+    {0, 0, 255, 255},      // 6: J-piece - blue
+    {255, 165, 0, 255}     // 7: L-piece - orange
+};
+
+void GameRenderer::drawRect(SDL_Renderer* renderer, float x, float y, float w, float h, SDL_Color c) {
+    SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, c.a);
+    SDL_FRect fr{x, y, w, h};
+    SDL_RenderFillRect(renderer, &fr);
+}
+
+void GameRenderer::drawBlockTexture(SDL_Renderer* renderer, SDL_Texture* blocksTex, float x, float y, float size, int blockType) {
+    if (!blocksTex || blockType < 0 || blockType >= PIECE_COUNT) {
+        // Fallback to colored rectangle if texture isn't available
+        SDL_Color color = (blockType >= 0 && blockType < PIECE_COUNT) ? COLORS[blockType + 1] : SDL_Color{128, 128, 128, 255};
+        drawRect(renderer, x, y, size-1, size-1, color);
+        return;
+    }
+    
+    // JavaScript uses: sx = type * spriteSize, sy = 0, with 2px padding
+    // Each sprite is 90px wide in the horizontal sprite sheet
+    const int SPRITE_SIZE = 90;
+    float srcX = blockType * SPRITE_SIZE + 2;  // Add 2px padding like JS
+    float srcY = 2;                            // Add 2px padding from top like JS
+    float srcW = SPRITE_SIZE - 4;              // Subtract 4px total padding like JS
+    float srcH = SPRITE_SIZE - 4;              // Subtract 4px total padding like JS
+    
+    SDL_FRect srcRect = {srcX, srcY, srcW, srcH};
+    SDL_FRect dstRect = {x, y, size, size};
+    SDL_RenderTexture(renderer, blocksTex, &srcRect, &dstRect);
+}
+
+void GameRenderer::drawPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, const Game::Piece& piece, float ox, float oy, float tileSize, bool isGhost) {
+    if (piece.type >= PIECE_COUNT) return;
+    
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (Game::cellFilled(piece, cx, cy)) {
+                float px = ox + (piece.x + cx) * tileSize;
+                float py = oy + (piece.y + cy) * tileSize;
+                
+                if (isGhost) {
+                    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+                    
+                    // Draw ghost piece as barely visible gray outline
+                    SDL_SetRenderDrawColor(renderer, 180, 180, 180, 20); // Very faint gray
+                    SDL_FRect rect = {px + 2, py + 2, tileSize - 4, tileSize - 4};
+                    SDL_RenderFillRect(renderer, &rect);
+                    
+                    // Draw thin gray border
+                    SDL_SetRenderDrawColor(renderer, 180, 180, 180, 30);
+                    SDL_FRect border = {px + 1, py + 1, tileSize - 2, tileSize - 2};
+                    SDL_RenderRect(renderer, &border);
+                } else {
+                    drawBlockTexture(renderer, blocksTex, px, py, tileSize, piece.type);
+                }
+            }
+        }
+    }
+}
+
+void GameRenderer::drawSmallPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, PieceType pieceType, float x, float y, float tileSize) {
+    if (pieceType >= PIECE_COUNT) return;
+    
+    // Use the first rotation (index 0) for preview
+    Game::Piece previewPiece;
+    previewPiece.type = pieceType;
+    previewPiece.rot = 0;
+    previewPiece.x = 0;
+    previewPiece.y = 0;
+    
+    // Center the piece in the preview area
+    float offsetX = 0, offsetY = 0;
+    if (pieceType == 0) { offsetX = tileSize * 0.5f; } // I-piece centering (assuming I = 0)
+    else if (pieceType == 1) { offsetX = tileSize * 0.5f; } // O-piece centering (assuming O = 1)
+    
+    // Use semi-transparent alpha for preview blocks
+    Uint8 previewAlpha = 180;
+    if (blocksTex) {
+        SDL_SetTextureAlphaMod(blocksTex, previewAlpha);
+    }
+    
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (Game::cellFilled(previewPiece, cx, cy)) {
+                float px = x + offsetX + cx * tileSize;
+                float py = y + offsetY + cy * tileSize;
+                drawBlockTexture(renderer, blocksTex, px, py, tileSize, pieceType);
+            }
+        }
+    }
+    
+    // Reset alpha
+    if (blocksTex) {
+        SDL_SetTextureAlphaMod(blocksTex, 255);
+    }
+}
+
+// Draw the hold panel (extracted for readability).
+static void drawHoldPanel(SDL_Renderer* renderer,
+                          Game* game,
+                          FontAtlas* pixelFont,
+                          SDL_Texture* blocksTex,
+                          SDL_Texture* holdPanelTex,
+                          float scoreX,
+                          float statsW,
+                          float gridY,
+                          float finalBlockSize,
+                          float statsY,
+                          float statsH) {
+    float holdBlockH = (finalBlockSize * 0.6f) * 4.0f;
+    // Base panel height; enforce minimum but allow larger to fit texture
+    float panelH = std::max(holdBlockH + 12.0f, 420.0f);
+    // Increase height by ~20% of the hold block to give more vertical room
+    float extraH = holdBlockH * 0.20f;
+    panelH += extraH;
+
+    const float holdGap = 18.0f;
+
+    // Align X to the bottom score label (`scoreX`) plus an offset to the right
+    float panelX = scoreX + 30.0f; // move ~30px right to align with score label
+    float panelW = statsW + 32.0f;
+    float panelY = gridY - panelH - holdGap;
+    // Move panel a bit higher for spacing (about half the extra height)
+    panelY -= extraH * 0.5f;
+    float labelX = panelX + 40.0f; // shift HOLD label ~30px to the right
+    float labelY = panelY + 8.0f;
+
+    if (holdPanelTex) {
+        int texW = 0, texH = 0;
+        SDL_QueryTexture(holdPanelTex, nullptr, nullptr, &texW, &texH);
+        if (texW > 0 && texH > 0) {
+            // Fill panel width and compute destination height from texture aspect ratio
+            float texAspect = float(texH) / float(texW);
+            float dstW = panelW;
+            float dstH = dstW * texAspect;
+            // If texture height exceeds panel, expand panelH to fit texture comfortably
+            if (dstH + 12.0f > panelH) {
+                panelH = dstH + 12.0f;
+                panelY = gridY - panelH - holdGap;
+                labelY = panelY + 8.0f;
+            }
+            float dstX = panelX;
+            float dstY = panelY + (panelH - dstH) * 0.5f;
+
+            SDL_FRect panelDst{dstX, dstY, dstW, dstH};
+            SDL_SetTextureBlendMode(holdPanelTex, SDL_BLENDMODE_BLEND);
+            SDL_SetTextureScaleMode(holdPanelTex, SDL_SCALEMODE_LINEAR);
+            SDL_RenderTexture(renderer, holdPanelTex, nullptr, &panelDst);
+        } else {
+            // Fallback to filling panel area if texture metrics unavailable
+            SDL_SetRenderDrawColor(renderer, 12, 18, 32, 220);
+            SDL_FRect panelDst{panelX, panelY, panelW, panelH};
+            SDL_RenderFillRect(renderer, &panelDst);
+        }
+    } else {
+        SDL_SetRenderDrawColor(renderer, 12, 18, 32, 220);
+        SDL_FRect panelDst{panelX, panelY, panelW, panelH};
+        SDL_RenderFillRect(renderer, &panelDst);
+    }
+
+    pixelFont->draw(renderer, labelX, labelY, "HOLD", 1.0f, {255, 220, 0, 255});
+
+    if (game->held().type < PIECE_COUNT) {
+        float previewW = finalBlockSize * 0.6f * 4.0f;
+        float previewX = panelX + (panelW - previewW) * 0.5f;
+        float previewY = panelY + (panelH - holdBlockH) * 0.5f;
+        drawSmallPiece(renderer, blocksTex, static_cast<PieceType>(game->held().type), previewX, previewY, finalBlockSize * 0.6f);
+    }
+}
+
+// Draw next piece panel (border/texture + preview)
+static void drawNextPanel(SDL_Renderer* renderer,
+                          FontAtlas* pixelFont,
+                          SDL_Texture* nextPanelTex,
+                          SDL_Texture* blocksTex,
+                          Game* game,
+                          float nextX,
+                          float nextY,
+                          float nextW,
+                          float nextH,
+                          float contentOffsetX,
+                          float contentOffsetY,
+                          float finalBlockSize) {
+    if (nextPanelTex) {
+        SDL_FRect dst{ nextX - contentOffsetX, nextY - contentOffsetY, nextW, nextH };
+        SDL_SetTextureBlendMode(nextPanelTex, SDL_BLENDMODE_BLEND);
+        SDL_RenderTexture(renderer, nextPanelTex, nullptr, &dst);
+    } else {
+        // Draw bordered panel as before
+        SDL_SetRenderDrawColor(renderer, 100, 120, 200, 255);
+        SDL_FRect outer{ nextX - 3 - contentOffsetX, nextY - 3 - contentOffsetY, nextW + 6, nextH + 6 };
+        SDL_RenderFillRect(renderer, &outer);
+        SDL_SetRenderDrawColor(renderer, 30, 35, 50, 255);
+        SDL_FRect inner{ nextX - contentOffsetX, nextY - contentOffsetY, nextW, nextH };
+        SDL_RenderFillRect(renderer, &inner);
+    }
+
+    // Label and small preview
+    pixelFont->draw(renderer, nextX + 10, nextY - 20, "NEXT", 1.0f, {255, 220, 0, 255});
+    if (game->next().type < PIECE_COUNT) {
+        drawSmallPiece(renderer, blocksTex, static_cast<PieceType>(game->next().type), nextX + 10, nextY + 5, finalBlockSize * 0.6f);
+    }
+}
+
+// Draw score panel (right side)
+static void drawScorePanel(SDL_Renderer* renderer,
+                          FontAtlas* pixelFont,
+                          Game* game,
+                          float scoreX,
+                          float gridY,
+                          float GRID_H,
+                          float finalBlockSize) {
+    const float contentTopOffset = 0.0f;
+    const float contentBottomOffset = 290.0f;
+    const float contentPad = 36.0f;
+    float scoreContentH = (contentBottomOffset - contentTopOffset) + contentPad;
+    float baseY = gridY + (GRID_H - scoreContentH) * 0.5f;
+
+    pixelFont->draw(renderer, scoreX, baseY + 0, "SCORE", 1.0f, {255, 220, 0, 255});
+    char scoreStr[32];
+    snprintf(scoreStr, sizeof(scoreStr), "%d", game->score());
+    pixelFont->draw(renderer, scoreX, baseY + 25, scoreStr, 0.9f, {255, 255, 255, 255});
+
+    pixelFont->draw(renderer, scoreX, baseY + 70, "LINES", 1.0f, {255, 220, 0, 255});
+    char linesStr[16];
+    snprintf(linesStr, sizeof(linesStr), "%03d", game->lines());
+    pixelFont->draw(renderer, scoreX, baseY + 95, linesStr, 0.9f, {255, 255, 255, 255});
+
+    pixelFont->draw(renderer, scoreX, baseY + 140, "LEVEL", 1.0f, {255, 220, 0, 255});
+    char levelStr[16];
+    snprintf(levelStr, sizeof(levelStr), "%02d", game->level());
+    pixelFont->draw(renderer, scoreX, baseY + 165, levelStr, 0.9f, {255, 255, 255, 255});
+
+    // Next level progress
+    int startLv = game->startLevelBase();
+    int firstThreshold = (startLv + 1) * 10;
+    int linesDone = game->lines();
+    int nextThreshold = 0;
+    if (linesDone < firstThreshold) {
+        nextThreshold = firstThreshold;
+    } else {
+        int blocksPast = linesDone - firstThreshold;
+        nextThreshold = firstThreshold + ((blocksPast / 10) + 1) * 10;
+    }
+    int linesForNext = std::max(0, nextThreshold - linesDone);
+    pixelFont->draw(renderer, scoreX, baseY + 200, "NEXT LVL", 1.0f, {255, 220, 0, 255});
+    char nextStr[32];
+    snprintf(nextStr, sizeof(nextStr), "%d  LINES", linesForNext);
+    pixelFont->draw(renderer, scoreX, baseY + 225, nextStr, 0.9f, {80, 255, 120, 255});
+
+    // Time display
+    pixelFont->draw(renderer, scoreX, baseY + 265, "TIME", 1.0f, {255, 220, 0, 255});
+    int totalSecs = static_cast<int>(game->elapsed());
+    int mins = totalSecs / 60;
+    int secs = totalSecs % 60;
+    char timeStr[16];
+    snprintf(timeStr, sizeof(timeStr), "%02d:%02d", mins, secs);
+    pixelFont->draw(renderer, scoreX, baseY + 290, timeStr, 0.9f, {255, 255, 255, 255});
+}
+
+void GameRenderer::renderPlayingState(
+    SDL_Renderer* renderer,
+    Game* game,
+    FontAtlas* pixelFont,
+    LineEffect* lineEffect,
+    SDL_Texture* blocksTex,
+    SDL_Texture* statisticsPanelTex,
+    SDL_Texture* scorePanelTex,
+    SDL_Texture* nextPanelTex,
+    SDL_Texture* holdPanelTex,
+    float logicalW,
+    float logicalH,
+    float logicalScale,
+    float winW,
+    float winH,
+        bool showExitConfirmPopup,
+        int exitPopupSelectedButton,
+        bool suppressPauseVisuals
+) {
+    (void)exitPopupSelectedButton;
+    if (!game || !pixelFont) return;
+    
+    // Calculate actual content area (centered within the window)
+    float contentScale = logicalScale;
+    float contentW = logicalW * contentScale;
+    float contentH = logicalH * contentScale;
+    float contentOffsetX = (winW - contentW) * 0.5f / contentScale;
+    float contentOffsetY = (winH - contentH) * 0.5f / contentScale;
+    
+    // Helper lambda for drawing rectangles with content offset
+    auto drawRectWithOffset = [&](float x, float y, float w, float h, SDL_Color c) {
+        SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, c.a);
+        SDL_FRect fr{x + contentOffsetX, y + contentOffsetY, w, h};
+        SDL_RenderFillRect(renderer, &fr);
+    };
+
+    // Responsive layout that scales with window size while maintaining margins
+    const float MIN_MARGIN = 40.0f;
+    const float TOP_MARGIN = 60.0f;
+    const float PANEL_WIDTH = 180.0f;
+    const float PANEL_SPACING = 30.0f;
+    const float NEXT_PIECE_HEIGHT = 120.0f;
+    const float BOTTOM_MARGIN = 60.0f;
+    
+        float yCursor = statsY + 44.0f;
+    const float availableWidth = logicalW - (MIN_MARGIN * 2) - (PANEL_WIDTH * 2) - (PANEL_SPACING * 2);
+    const float availableHeight = logicalH - TOP_MARGIN - BOTTOM_MARGIN - NEXT_PIECE_HEIGHT;
+    
+    const float maxBlockSizeW = availableWidth / Game::COLS;
+        // Draw hold panel via helper
+        drawHoldPanel(renderer, game, pixelFont, blocksTex, holdPanelTex, scoreX, statsW, gridY, finalBlockSize, statsY, statsH);
+    
+    // Draw grid lines (solid so grid remains legible over background)
+    SDL_SetRenderDrawColor(renderer, 40, 45, 60, 255);
+    for (int x = 1; x < Game::COLS; ++x) {
+        float lineX = gridX + x * finalBlockSize;
+        SDL_RenderLine(renderer, lineX, gridY, lineX, gridY + GRID_H);
+    }
+    for (int y = 1; y < Game::ROWS; ++y) {
+        float lineY = gridY + y * finalBlockSize;
+        SDL_RenderLine(renderer, gridX, lineY, gridX + GRID_W, lineY);
+    }
+
+    Uint64 nowTicks = SDL_GetTicks();
+    float deltaSeconds = (g_lastSparkTick == 0) ? (1.0f / 60.0f) : static_cast<float>(nowTicks - g_lastSparkTick) / 1000.0f;
+    g_lastSparkTick = nowTicks;
+    updateSparks(std::max(0.0f, deltaSeconds));
+    drawSparks(renderer, gridX, gridY, finalBlockSize);
+    
+    // Draw block statistics panel border
+    drawRectWithOffset(statsX - 3 - contentOffsetX, statsY - 3 - contentOffsetY, statsW + 6, statsH + 6, {100, 120, 200, 255});
+    drawRectWithOffset(statsX - contentOffsetX, statsY - contentOffsetY, statsW, statsH, {30, 35, 50, 255});
+    
+    // Draw next piece panel
+    drawNextPanel(renderer, pixelFont, nextPanelTex, blocksTex, game, nextX, nextY, nextW, nextH, contentOffsetX, contentOffsetY, finalBlockSize);
+
+    // Draw the game board
+    const auto &board = game->boardRef();
+    for (int y = 0; y < Game::ROWS; ++y) {
+        for (int x = 0; x < Game::COLS; ++x) {
+            int v = board[y * Game::COLS + x];
+            if (v > 0) {
+                float bx = gridX + x * finalBlockSize;
+                float by = gridY + y * finalBlockSize;
+                drawBlockTexture(renderer, blocksTex, bx, by, finalBlockSize, v - 1);
+            }
+        }
+    }
+    
+    bool allowActivePieceRender = !game->isPaused() || suppressPauseVisuals;
+
+    // Draw ghost piece (where current piece will land)
+    if (allowActivePieceRender) {
+        Game::Piece ghostPiece = game->current();
+        // Find landing position
+        while (true) {
+            Game::Piece testPiece = ghostPiece;
+            testPiece.y++;
+            bool collision = false;
+            
+            // Simple collision check
+            for (int cy = 0; cy < 4; ++cy) {
+                for (int cx = 0; cx < 4; ++cx) {
+                    if (Game::cellFilled(testPiece, cx, cy)) {
+                        int gx = testPiece.x + cx;
+                        int gy = testPiece.y + cy;
+                        if (gy >= Game::ROWS || gx < 0 || gx >= Game::COLS || 
+                            (gy >= 0 && board[gy * Game::COLS + gx] != 0)) {
+                            collision = true;
+                            break;
+                        }
+                    }
+                }
+                if (collision) break;
+            }
+            
+            if (collision) break;
+            ghostPiece = testPiece;
+        }
+        
+        // Draw ghost piece
+        drawPiece(renderer, blocksTex, ghostPiece, gridX, gridY, finalBlockSize, true);
+    }
+    
+    // Draw the falling piece
+    if (allowActivePieceRender) {
+        drawPiece(renderer, blocksTex, game->current(), gridX, gridY, finalBlockSize, false);
+    }
+    
+    // Draw line clearing effects
+    if (lineEffect && lineEffect->isActive()) {
+        lineEffect->render(renderer, static_cast<int>(gridX), static_cast<int>(gridY), static_cast<int>(finalBlockSize));
+    }
+                                float yCursor = statsY + 44.0f;
+    // Draw next piece preview
+    pixelFont->draw(renderer, nextX + 10, nextY - 20, "NEXT", 1.0f, {255, 220, 0, 255});
+    if (game->next().type < PIECE_COUNT) {
+        // Nudge preview slightly upward to remove thin bottom artifact
+        drawSmallPiece(renderer, blocksTex, static_cast<PieceType>(game->next().type), nextX + 10, nextY + 5, finalBlockSize * 0.6f);
+    }
+    
+    // Draw block statistics (left panel)
+    pixelFont->draw(renderer, statsX + 10, statsY + 10, "BLOCKS", 1.0f, {255, 220, 0, 255});
+    
+    const auto& blockCounts = game->getBlockCounts();
+                                    float previewY = rowTop - 4.0f;
+    for (int i = 0; i < PIECE_COUNT; ++i) totalBlocks += blockCounts[i];
+
+    const float rowPadding = 18.0f;
+    const float rowWidth = statsW - rowPadding * 2.0f;
+    const float rowSpacing = 12.0f;
+    float yCursor = statsY + 44.0f;
+
+    for (int i = 0; i < PIECE_COUNT; ++i) {
+        float rowTop = yCursor;
+        float previewSize = finalBlockSize * 0.52f;
+        float previewX = statsX + rowPadding;
+        float previewY = rowTop - 14.0f;
+
+        // Determine actual piece height so bars never overlap blocks
+        Game::Piece previewPiece{};
+        previewPiece.type = static_cast<PieceType>(i);
+        previewPiece.rot = 0;
+        previewPiece.x = 0;
+        previewPiece.y = 0;
+        int maxCy = -1;
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (Game::cellFilled(previewPiece, cx, cy)) {
+                    maxCy = std::max(maxCy, cy);
+                }
+            }
+        }
+        float pieceHeight = (maxCy >= 0 ? maxCy + 1.0f : 1.0f) * previewSize;
+
+        int count = blockCounts[i];
+        char countStr[16];
+        snprintf(countStr, sizeof(countStr), "%d", count);
+        int countW = 0, countH = 0;
+        pixelFont->measure(countStr, 1.0f, countW, countH);
+        // Horizontal shift to push the counts/percent a bit more to the right
+        const float statsNumbersShift = 20.0f;
+        // Small left shift for progress bar so the track aligns better with the design
+        const float statsBarShift = -10.0f;
+        float countX = previewX + rowWidth - static_cast<float>(countW) + statsNumbersShift;
+        float countY = previewY + 9.0f;
+
+        int perc = (totalBlocks > 0) ? int(std::round(100.0 * double(count) / double(totalBlocks))) : 0;
+        char percStr[16];
+        snprintf(percStr, sizeof(percStr), "%d%%", perc);
+        int percW = 0, percH = 0;
+        pixelFont->measure(percStr, 0.8f, percW, percH);
+
+        float barX = previewX + statsBarShift;
+        float barY = previewY + pieceHeight + 12.0f;
+        float barH = 6.0f;
+        float barW = rowWidth;
+        float percY = barY + barH + 8.0f;
+        float fillW = barW * (perc / 100.0f);
+        fillW = std::clamp(fillW, 0.0f, barW);
+
+        float cardTop = rowTop - 14.0f;
+        float rowBottom = percY + 16.0f;
+        SDL_FRect rowBg{
+            previewX - 12.0f,
+            cardTop,
+            rowWidth + 24.0f,
+            rowBottom - cardTop
+        };
+        SDL_SetRenderDrawColor(renderer, 18, 26, 40, 200);
+        SDL_RenderFillRect(renderer, &rowBg);
+        SDL_SetRenderDrawColor(renderer, 70, 100, 150, 210);
+        SDL_RenderRect(renderer, &rowBg);
+
+        drawSmallPiece(renderer, blocksTex, static_cast<PieceType>(i), previewX, previewY, previewSize);
+        pixelFont->draw(renderer, countX, countY, countStr, 1.0f, {245, 245, 255, 255});
+        // Draw percent right-aligned near the same right edge as the count
+        float percX = previewX + rowWidth - static_cast<float>(percW) + statsNumbersShift;
+        pixelFont->draw(renderer, percX, percY, percStr, 0.8f, {215, 225, 240, 255});
+
+        SDL_SetRenderDrawColor(renderer, 110, 120, 140, 200);
+        SDL_FRect track{barX, barY, barW, barH};
+        SDL_RenderFillRect(renderer, &track);
+        SDL_Color pc = COLORS[i + 1];
+        SDL_SetRenderDrawColor(renderer, pc.r, pc.g, pc.b, 255);
+        SDL_FRect fill{barX, barY, fillW, barH};
+        SDL_RenderFillRect(renderer, &fill);
+
+        yCursor = rowBottom + rowSpacing;
+    }
+    
+    // Draw score panel
+    drawScorePanel(renderer, pixelFont, game, scoreX, gridY, GRID_H, finalBlockSize);
+    
+    // Gravity HUD
+    char gms[64];
+    double gms_val = game->getGravityMs();
+    double gfps = gms_val > 0.0 ? (1000.0 / gms_val) : 0.0;
+    snprintf(gms, sizeof(gms), "GRAV: %.0f ms (%.2f fps)", gms_val, gfps);
+    pixelFont->draw(renderer, logicalW - 260, 10, gms, 0.9f, {200, 200, 220, 255});
+    
+    // Hold panel (always visible): draw background & label; preview shown only when a piece is held.
+    {
+        float holdBlockH = (finalBlockSize * 0.6f) * 4.0f;
+        // Base panel height; enforce minimum but allow larger to fit texture
+        float panelH = std::max(holdBlockH + 12.0f, 420.0f);
+        // Increase height by ~20% of the hold block to give more vertical room
+        float extraH = holdBlockH * 0.50f;
+        panelH += extraH;
+        const float holdGap = 18.0f;
+
+        // Align X to the bottom score label (`scoreX`) plus an offset to the right
+        float panelX = scoreX + 30.0f; // move ~30px right to align with score label
+        float panelW = statsW + 32.0f;
+        float panelY = gridY - panelH - holdGap;
+        // Move panel a bit higher for spacing (about half the extra height)
+        panelY -= extraH * 0.5f;
+        float labelX = panelX + 40.0f; // shift HOLD label ~30px to the right
+        float labelY = panelY + 8.0f;
+
+        if (holdPanelTex) {
+            int texW = 0, texH = 0;
+            SDL_QueryTexture(holdPanelTex, nullptr, nullptr, &texW, &texH);
+            if (texW > 0 && texH > 0) {
+                // If the texture is taller than the current panel, expand panelH
+                float texAspect = float(texH) / float(texW);
+                float desiredTexH = panelW * texAspect;
+                if (desiredTexH + 12.0f > panelH) {
+                    panelH = desiredTexH + 12.0f;
+                    // Recompute vertical placement after growing panelH
+                    panelY = gridY - panelH - holdGap;
+                    labelY = panelY + 8.0f;
+                }
+
+                // Fill panel width and compute destination height from texture aspect ratio
+                float texAspect = float(texH) / float(texW);
+                float dstW = panelW;
+                float dstH = dstW * texAspect * 1.2f;
+                // If texture height exceeds panel, expand panelH to fit texture comfortably
+                if (dstH + 12.0f > panelH) {
+                    panelH = dstH + 12.0f;
+                    panelY = gridY - panelH - holdGap;
+                    labelY = panelY + 8.0f;
+                }
+                float dstX = panelX;
+                float dstY = panelY + (panelH - dstH) * 0.5f;
+
+                SDL_FRect panelDst{dstX, dstY, dstW, dstH};
+                SDL_SetTextureBlendMode(holdPanelTex, SDL_BLENDMODE_BLEND);
+                SDL_SetTextureScaleMode(holdPanelTex, SDL_SCALEMODE_LINEAR);
+                SDL_RenderTexture(renderer, holdPanelTex, nullptr, &panelDst);
+            } else {
+                // Fallback to filling panel area if texture metrics unavailable
+                SDL_SetRenderDrawColor(renderer, 12, 18, 32, 220);
+                SDL_FRect panelDst{panelX, panelY, panelW, panelH};
+                SDL_RenderFillRect(renderer, &panelDst);
+            }
+        } else {
+            SDL_SetRenderDrawColor(renderer, 12, 18, 32, 220);
+            SDL_FRect panelDst{panelX, panelY, panelW, panelH};
+            SDL_RenderFillRect(renderer, &panelDst);
+        }
+
+        pixelFont->draw(renderer, labelX, labelY, "HOLD", 1.0f, {255, 220, 0, 255});
+
+        if (game->held().type < PIECE_COUNT) {
+            float previewW = finalBlockSize * 0.6f * 4.0f;
+            float previewX = panelX + (panelW - previewW) * 0.5f;
+            float previewY = panelY + (panelH - holdBlockH) * 0.5f;
+            drawSmallPiece(renderer, blocksTex, static_cast<PieceType>(game->held().type), previewX, previewY, finalBlockSize * 0.6f);
+        }
+    }
+    
+    // Pause overlay (suppressed when requested, e.g., countdown)
+    if (!suppressPauseVisuals && game->isPaused() && !showExitConfirmPopup) {
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+        for (int i = -4; i <= 4; ++i) {
+            float spread = static_cast<float>(std::abs(i));
+            Uint8 alpha = Uint8(std::max(8.f, 32.f - spread * 4.f));
+            SDL_SetRenderDrawColor(renderer, 24, 32, 48, alpha);
+            SDL_FRect blurRect{
+                gridX - spread * 2.0f,
+                gridY - spread * 1.5f,
+                GRID_W + spread * 4.0f,
+                GRID_H + spread * 3.0f
+            };
+            SDL_RenderFillRect(renderer, &blurRect);
+        }
+        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 180);
+        SDL_FRect pauseOverlay{0, 0, logicalW, logicalH};
+        SDL_RenderFillRect(renderer, &pauseOverlay);
+        
+        pixelFont->draw(renderer, logicalW * 0.5f - 80, logicalH * 0.5f - 20, "PAUSED", 2.0f, {255, 255, 255, 255});
+        pixelFont->draw(renderer, logicalW * 0.5f - 120, logicalH * 0.5f + 30, "Press P to resume", 0.8f, {200, 200, 220, 255});
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+    }
+    
+    if (showExitConfirmPopup) {
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 200);
+        SDL_FRect fullWin{0.f, 0.f, winW, winH};
+        SDL_RenderFillRect(renderer, &fullWin);
+
+        const float panelW = 640.0f;
+        const float panelH = 320.0f;
+        SDL_FRect panel{
+            (logicalW - panelW) * 0.5f + contentOffsetX,
+            (logicalH - panelH) * 0.5f + contentOffsetY,
+            panelW,
+            panelH
+        };
+
+        SDL_FRect shadow{panel.x + 6.0f, panel.y + 10.0f, panel.w, panel.h};
+        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 140);
+        SDL_RenderFillRect(renderer, &shadow);
+        for (int i = 0; i < 5; ++i) {
+            SDL_FRect glow{panel.x - float(i * 2), panel.y - float(i * 2), panel.w + float(i * 4), panel.h + float(i * 4)};
+            SDL_SetRenderDrawColor(renderer, 0, 180, 255, Uint8(44 - i * 7));
+            SDL_RenderRect(renderer, &glow);
+        }
+
+        SDL_SetRenderDrawColor(renderer, 18, 30, 52, 255);
+        SDL_RenderFillRect(renderer, &panel);
+        SDL_SetRenderDrawColor(renderer, 70, 120, 210, 255);
+        SDL_RenderRect(renderer, &panel);
+
+        SDL_FRect inner{panel.x + 24.0f, panel.y + 98.0f, panel.w - 48.0f, panel.h - 146.0f};
+        SDL_SetRenderDrawColor(renderer, 16, 24, 40, 235);
+        SDL_RenderFillRect(renderer, &inner);
+        SDL_SetRenderDrawColor(renderer, 40, 80, 140, 235);
+        SDL_RenderRect(renderer, &inner);
+
+        const std::string title = "EXIT GAME?";
+        int titleW = 0, titleH = 0;
+        const float titleScale = 1.8f;
+        pixelFont->measure(title, titleScale, titleW, titleH);
+        pixelFont->draw(renderer, panel.x + (panel.w - titleW) * 0.5f, panel.y + 30.0f, title, titleScale, {255, 230, 140, 255});
+
+        std::array<std::string, 2> lines = {
+            "Are you sure you want to quit?",
+            "Current progress will be lost."
+        };
+        float lineY = inner.y + 22.0f;
+        const float lineScale = 1.05f;
+        for (const auto& line : lines) {
+            int lineW = 0, lineH = 0;
+            pixelFont->measure(line, lineScale, lineW, lineH);
+            float textX = panel.x + (panel.w - lineW) * 0.5f;
+            pixelFont->draw(renderer, textX, lineY, line, lineScale, SDL_Color{210, 220, 240, 255});
+            lineY += lineH + 10.0f;
+        }
+
+        const float horizontalPad = 28.0f;
+        const float buttonGap = 32.0f;
+        const float buttonH = 66.0f;
+        float buttonW = (inner.w - horizontalPad * 2.0f - buttonGap) * 0.5f;
+        float buttonY = inner.y + inner.h - buttonH - 24.0f;
+
+        auto drawButton = [&](float x, const char* label, SDL_Color base) {
+            SDL_FRect btn{x, buttonY, buttonW, buttonH};
+            SDL_SetRenderDrawColor(renderer, 0, 0, 0, 120);
+            SDL_FRect btnShadow{btn.x + 4.0f, btn.y + 6.0f, btn.w, btn.h};
+            SDL_RenderFillRect(renderer, &btnShadow);
+            SDL_SetRenderDrawColor(renderer, base.r, base.g, base.b, base.a);
+            SDL_RenderFillRect(renderer, &btn);
+            SDL_SetRenderDrawColor(renderer, 90, 130, 200, 255);
+            SDL_RenderRect(renderer, &btn);
+
+            int textW = 0, textH = 0;
+            const float labelScale = 1.4f;
+            pixelFont->measure(label, labelScale, textW, textH);
+            float textX = btn.x + (btn.w - textW) * 0.5f;
+            float textY = btn.y + (btn.h - textH) * 0.5f;
+            pixelFont->draw(renderer, textX, textY, label, labelScale, SDL_Color{255, 255, 255, 255});
+        };
+
+        float yesX = inner.x + horizontalPad;
+        float noX = yesX + buttonW + buttonGap;
+        drawButton(yesX, "YES", SDL_Color{185, 70, 70, 255});
+        drawButton(noX, "NO", SDL_Color{60, 95, 150, 255});
+    }
+}
diff --git a/src/graphics/GameRenderer.h b/src/graphics/GameRenderer.h
new file mode 100644
index 0000000..a677748
--- /dev/null
+++ b/src/graphics/GameRenderer.h
@@ -0,0 +1,46 @@
+#pragma once
+#include <SDL3/SDL.h>
+#include "../gameplay/Game.h"
+
+// Forward declarations
+class FontAtlas;
+class LineEffect;
+
+/**
+ * GameRenderer - Utility class for rendering the Tetris game board and HUD.
+ * 
+ * This class encapsulates all the game-specific rendering logic that was
+ * previously in main.cpp, making it reusable across different contexts.
+ */
+class GameRenderer {
+public:
+    // Render the complete playing state including game board, HUD, and effects
+    static void renderPlayingState(
+        SDL_Renderer* renderer,
+        Game* game,
+        FontAtlas* pixelFont,
+        LineEffect* lineEffect,
+            SDL_Texture* blocksTex,
+            SDL_Texture* statisticsPanelTex,
+            SDL_Texture* scorePanelTex,
+            SDL_Texture* nextPanelTex,
+            SDL_Texture* holdPanelTex,
+            float logicalW,
+        float logicalH,
+        float logicalScale,
+        float winW,
+        float winH,
+        bool showExitConfirmPopup,
+        int exitPopupSelectedButton = 1,
+        bool suppressPauseVisuals = false
+    );
+
+private:
+    // Helper functions for drawing game elements
+    static void drawBlockTexture(SDL_Renderer* renderer, SDL_Texture* blocksTex, float x, float y, float size, int blockType);
+    static void drawPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, const Game::Piece& piece, float ox, float oy, float tileSize, bool isGhost = false);
+    static void drawSmallPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, PieceType pieceType, float x, float y, float tileSize);
+    
+    // Helper function for drawing rectangles
+    static void drawRect(SDL_Renderer* renderer, float x, float y, float w, float h, SDL_Color c);
+};
diff --git a/src/graphics/RenderManager.cpp b/src/graphics/RenderManager.cpp
new file mode 100644
index 0000000..2f2eba0
--- /dev/null
+++ b/src/graphics/RenderManager.cpp
@@ -0,0 +1,298 @@
+#include "RenderManager.h"
+#include <SDL3/SDL.h>
+#include <algorithm>
+
+RenderManager::RenderManager() = default;
+
+RenderManager::~RenderManager() {
+    if (m_initialized) {
+        shutdown();
+    }
+}
+
+bool RenderManager::initialize(int width, int height, const std::string& title) {
+    if (m_initialized) {
+        SDL_LogWarn(SDL_LOG_CATEGORY_RENDER, "RenderManager already initialized");
+        return true;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "Initializing RenderManager (%dx%d)", width, height);
+
+    // Create window
+    m_window = SDL_CreateWindow(
+        title.c_str(),
+        width, height,
+        SDL_WINDOW_RESIZABLE
+    );
+
+    if (!m_window) {
+        SDL_LogError(SDL_LOG_CATEGORY_RENDER, "Failed to create window: %s", SDL_GetError());
+        return false;
+    }
+
+    // Create renderer
+    m_renderer = SDL_CreateRenderer(m_window, nullptr);
+    if (!m_renderer) {
+        SDL_LogError(SDL_LOG_CATEGORY_RENDER, "Failed to create renderer: %s", SDL_GetError());
+        SDL_DestroyWindow(m_window);
+        m_window = nullptr;
+        return false;
+    }
+
+    // Enable VSync
+    SDL_SetRenderVSync(m_renderer, 1);
+
+    // Store window dimensions
+    m_windowWidth = width;
+    m_windowHeight = height;
+    m_logicalWidth = width;
+    m_logicalHeight = height;
+
+    // Set initial logical size
+    setLogicalSize(width, height);
+
+    m_initialized = true;
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "RenderManager initialized successfully");
+    return true;
+}
+
+void RenderManager::shutdown() {
+    if (!m_initialized) {
+        return;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "Shutting down RenderManager");
+
+    if (m_renderer) {
+        SDL_DestroyRenderer(m_renderer);
+        m_renderer = nullptr;
+    }
+
+    if (m_window) {
+        SDL_DestroyWindow(m_window);
+        m_window = nullptr;
+    }
+
+    m_initialized = false;
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "RenderManager shutdown complete");
+}
+
+void RenderManager::beginFrame() {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    // Trace beginFrame entry
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::beginFrame entry\n"); fclose(f); }
+    }
+
+    // Clear the screen (wrapped with trace)
+    clear(12, 12, 16, 255); // Dark background similar to original
+
+    // Trace after clear
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::beginFrame after clear\n"); fclose(f); }
+    }
+}
+
+void RenderManager::endFrame() {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+    // Trace before present
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::endFrame before present\n"); fclose(f); }
+    }
+
+    SDL_RenderPresent(m_renderer);
+
+    // Trace after present
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::endFrame after present\n"); fclose(f); }
+    }
+}
+
+void RenderManager::setLogicalSize(int width, int height) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    m_logicalWidth = width;
+    m_logicalHeight = height;
+    updateLogicalScale();
+}
+
+void RenderManager::setViewport(int x, int y, int width, int height) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_Rect viewport = { x, y, width, height };
+    SDL_SetRenderViewport(m_renderer, &viewport);
+    // Keep cached logical viewport in sync if this matches our computed logical scale
+    m_logicalVP = viewport;
+}
+
+void RenderManager::setScale(float scaleX, float scaleY) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    m_scaleX = scaleX;
+    m_scaleY = scaleY;
+    SDL_SetRenderScale(m_renderer, scaleX, scaleY);
+}
+
+void RenderManager::resetViewport() {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    // Reset to full window viewport and recompute logical scale/viewport
+    SDL_SetRenderViewport(m_renderer, nullptr);
+    updateLogicalScale();
+}
+
+void RenderManager::clear(Uint8 r, Uint8 g, Uint8 b, Uint8 a) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_SetRenderDrawColor(m_renderer, r, g, b, a);
+    SDL_RenderClear(m_renderer);
+}
+
+void RenderManager::renderTexture(SDL_Texture* texture, const SDL_FRect* src, const SDL_FRect* dst) {
+    if (!m_initialized || !m_renderer || !texture) {
+        return;
+    }
+
+    // Trace renderTexture usage
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::renderTexture entry tex=%llu src=%p dst=%p\n", (unsigned long long)(uintptr_t)texture, (void*)src, (void*)dst); fclose(f); }
+    }
+    SDL_RenderTexture(m_renderer, texture, src, dst);
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::renderTexture after SDL_RenderTexture tex=%llu\n", (unsigned long long)(uintptr_t)texture); fclose(f); }
+    }
+}
+
+void RenderManager::renderTexture(SDL_Texture* texture, float x, float y) {
+    if (!texture) {
+        return;
+    }
+
+    float w, h;
+    SDL_GetTextureSize(texture, &w, &h);
+    SDL_FRect dst = { x, y, w, h };
+    renderTexture(texture, nullptr, &dst);
+}
+
+void RenderManager::renderTexture(SDL_Texture* texture, float x, float y, float w, float h) {
+    if (!texture) {
+        return;
+    }
+
+    SDL_FRect dst = { x, y, w, h };
+    renderTexture(texture, nullptr, &dst);
+}
+
+void RenderManager::renderRect(const SDL_FRect& rect, Uint8 r, Uint8 g, Uint8 b, Uint8 a) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_SetRenderDrawColor(m_renderer, r, g, b, a);
+    SDL_RenderFillRect(m_renderer, &rect);
+}
+
+void RenderManager::renderLine(float x1, float y1, float x2, float y2, Uint8 r, Uint8 g, Uint8 b, Uint8 a) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_SetRenderDrawColor(m_renderer, r, g, b, a);
+    SDL_RenderLine(m_renderer, x1, y1, x2, y2);
+}
+
+void RenderManager::renderPoint(float x, float y, Uint8 r, Uint8 g, Uint8 b, Uint8 a) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_SetRenderDrawColor(m_renderer, r, g, b, a);
+    SDL_RenderPoint(m_renderer, x, y);
+}
+
+void RenderManager::handleWindowResize(int newWidth, int newHeight) {
+    if (!m_initialized) {
+        return;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "Window resized to %dx%d", newWidth, newHeight);
+    
+    m_windowWidth = newWidth;
+    m_windowHeight = newHeight;
+    updateLogicalScale();
+}
+
+void RenderManager::setFullscreen(bool fullscreen) {
+    if (!m_initialized || !m_window) {
+        return;
+    }
+
+    if (m_isFullscreen == fullscreen) {
+        return;
+    }
+
+    SDL_SetWindowFullscreen(m_window, fullscreen ? SDL_WINDOW_FULLSCREEN : 0);
+    m_isFullscreen = fullscreen;
+
+    // Update window size after fullscreen change
+    SDL_GetWindowSize(m_window, &m_windowWidth, &m_windowHeight);
+    updateLogicalScale();
+}
+
+void RenderManager::getWindowSize(int& width, int& height) const {
+    width = m_windowWidth;
+    height = m_windowHeight;
+}
+
+void RenderManager::getTextureSize(SDL_Texture* tex, int& w, int& h) const {
+    if (!tex) { w = 0; h = 0; return; }
+    // SDL3 provides SDL_GetTextureSize which accepts float or int pointers depending on overloads
+    float fw = 0.0f, fh = 0.0f;
+    SDL_GetTextureSize(tex, &fw, &fh);
+    w = int(fw + 0.5f);
+    h = int(fh + 0.5f);
+}
+
+void RenderManager::updateLogicalScale() {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    // Calculate scale to fit logical size into window
+    float scaleX = static_cast<float>(m_windowWidth) / static_cast<float>(m_logicalWidth);
+    float scaleY = static_cast<float>(m_windowHeight) / static_cast<float>(m_logicalHeight);
+    
+    // Use uniform scaling to maintain aspect ratio
+    float scale = std::min(scaleX, scaleY);
+    if (scale <= 0.0f) {
+        scale = 1.0f;
+    }
+
+    setScale(scale, scale);
+    // Compute centered logical viewport that preserves aspect ratio and is centered in window
+    int vpW = static_cast<int>(m_logicalWidth * scale);
+    int vpH = static_cast<int>(m_logicalHeight * scale);
+    int vpX = (m_windowWidth - vpW) / 2;
+    int vpY = (m_windowHeight - vpH) / 2;
+    SDL_Rect vp{ vpX, vpY, vpW, vpH };
+    SDL_SetRenderViewport(m_renderer, &vp);
+
+    // Cache logical viewport and scale for callers
+    m_logicalVP = vp;
+    m_logicalScale = scale;
+}
diff --git a/src/graphics/RenderManager.h b/src/graphics/RenderManager.h
new file mode 100644
index 0000000..a2c192e
--- /dev/null
+++ b/src/graphics/RenderManager.h
@@ -0,0 +1,92 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+#include <string>
+
+/**
+ * RenderManager - Abstracts SDL rendering functionality
+ * 
+ * Responsibilities:
+ * - Manage SDL_Window and SDL_Renderer lifecycle
+ * - Provide high-level rendering interface
+ * - Handle viewport and scaling logic
+ * - Abstract SDL-specific details from game code
+ */
+class RenderManager {
+public:
+    RenderManager();
+    ~RenderManager();
+
+    // Initialization and cleanup
+    bool initialize(int width, int height, const std::string& title);
+    void shutdown();
+
+    // Frame management
+    void beginFrame();
+    void endFrame();
+
+    // Viewport and scaling
+    void setLogicalSize(int width, int height);
+    void setViewport(int x, int y, int width, int height);
+    void setScale(float scaleX, float scaleY);
+    void resetViewport();
+
+    // Query the computed logical viewport and scale (useful for consistent input mapping)
+    SDL_Rect getLogicalViewport() const { return m_logicalVP; }
+    float getLogicalScale() const { return m_logicalScale; }
+
+    // Basic rendering operations
+    void clear(Uint8 r = 0, Uint8 g = 0, Uint8 b = 0, Uint8 a = 255);
+    
+    // Texture rendering
+    void renderTexture(SDL_Texture* texture, const SDL_FRect* src, const SDL_FRect* dst);
+    void renderTexture(SDL_Texture* texture, float x, float y);
+    void renderTexture(SDL_Texture* texture, float x, float y, float w, float h);
+
+    // Primitive rendering
+    void renderRect(const SDL_FRect& rect, Uint8 r, Uint8 g, Uint8 b, Uint8 a = 255);
+    void renderLine(float x1, float y1, float x2, float y2, Uint8 r, Uint8 g, Uint8 b, Uint8 a = 255);
+    void renderPoint(float x, float y, Uint8 r, Uint8 g, Uint8 b, Uint8 a = 255);
+
+    // Window management
+    void handleWindowResize(int newWidth, int newHeight);
+    void setFullscreen(bool fullscreen);
+    void getWindowSize(int& width, int& height) const;
+
+    // Direct access to SDL objects (temporary, will be removed later)
+    SDL_Renderer* getSDLRenderer() const { return m_renderer; }
+    SDL_Window* getSDLWindow() const { return m_window; }
+    // Texture queries
+    void getTextureSize(SDL_Texture* tex, int& w, int& h) const;
+
+    // State queries
+    bool isInitialized() const { return m_initialized; }
+    bool isFullscreen() const { return m_isFullscreen; }
+
+private:
+    // SDL objects
+    SDL_Window* m_window = nullptr;
+    SDL_Renderer* m_renderer = nullptr;
+
+    // Window properties
+    int m_windowWidth = 0;
+    int m_windowHeight = 0;
+    int m_logicalWidth = 0;
+    int m_logicalHeight = 0;
+    float m_scaleX = 1.0f;
+    float m_scaleY = 1.0f;
+    
+    // State
+    bool m_initialized = false;
+    bool m_isFullscreen = false;
+    // Cached logical viewport and scale (centered within window)
+    SDL_Rect m_logicalVP{0,0,0,0};
+    float m_logicalScale = 1.0f;
+    
+    // Helper methods
+    void updateLogicalScale();
+
+    // Query the computed logical viewport and scale (useful for consistent input mapping)
+    SDL_Rect getLogicalViewport() const { return m_logicalVP; }
+    float getLogicalScale() const { return m_logicalScale; }
+};
diff --git a/src/graphics/Starfield3D.cpp b/src/graphics/Starfield3D.cpp
index 3fe7740..fa038c4 100644
--- a/src/graphics/Starfield3D.cpp
+++ b/src/graphics/Starfield3D.cpp
@@ -137,16 +137,16 @@ void Starfield3D::update(float deltaTime) {
     }
 }
 
-void Starfield3D::drawStar(SDL_Renderer* renderer, float x, float y, int type) {
-    const SDL_Color& color = STAR_COLORS[type % COLOR_COUNT];
-    SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, color.a);
+void Starfield3D::drawStar(SDL_Renderer* renderer, float x, float y, SDL_Color color, float alphaScale) {
+    Uint8 alpha = static_cast<Uint8>(std::clamp(color.a * alphaScale, 0.0f, 255.0f));
+    SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, alpha);
     
     // Draw star as a small rectangle (1x1 pixel)
     SDL_FRect rect{x, y, 1.0f, 1.0f};
     SDL_RenderFillRect(renderer, &rect);
 }
 
-void Starfield3D::draw(SDL_Renderer* renderer) {
+void Starfield3D::draw(SDL_Renderer* renderer, float offsetX, float offsetY, float alphaScale, bool grayscale) {
     for (const Star3D& star : stars) {
         // Calculate perspective projection factor
         const float k = DEPTH_FACTOR / star.z;
@@ -158,7 +158,12 @@ void Starfield3D::draw(SDL_Renderer* renderer) {
         // Only draw stars that are within the viewport
         if (px >= 0.0f && px <= static_cast<float>(width) && 
             py >= 0.0f && py <= static_cast<float>(height)) {
-            drawStar(renderer, px, py, star.type);
+            SDL_Color baseColor = STAR_COLORS[star.type % COLOR_COUNT];
+            if (grayscale) {
+                Uint8 gray = static_cast<Uint8>(0.299f * baseColor.r + 0.587f * baseColor.g + 0.114f * baseColor.b);
+                baseColor.r = baseColor.g = baseColor.b = gray;
+            }
+            drawStar(renderer, px + offsetX, py + offsetY, baseColor, alphaScale);
         }
     }
 }
diff --git a/src/graphics/Starfield3D.h b/src/graphics/Starfield3D.h
index 7dfd5c9..3e03189 100644
--- a/src/graphics/Starfield3D.h
+++ b/src/graphics/Starfield3D.h
@@ -13,7 +13,7 @@ public:
 
     void init(int width, int height, int starCount = 160);
     void update(float deltaTime);
-    void draw(SDL_Renderer* renderer);
+    void draw(SDL_Renderer* renderer, float offsetX = 0.0f, float offsetY = 0.0f, float alphaScale = 1.0f, bool grayscale = false);
     void resize(int width, int height);
 
 private:
@@ -32,7 +32,7 @@ private:
     void setRandomDirection(Star3D& star);
     float randomFloat(float min, float max);
     int randomRange(int min, int max);
-    void drawStar(SDL_Renderer* renderer, float x, float y, int type);
+    void drawStar(SDL_Renderer* renderer, float x, float y, SDL_Color color, float alphaScale);
 
     std::vector<Star3D> stars;
     int width{0}, height{0};
diff --git a/src/graphics/effects/SpaceWarp.cpp b/src/graphics/effects/SpaceWarp.cpp
new file mode 100644
index 0000000..4ff5a0c
--- /dev/null
+++ b/src/graphics/effects/SpaceWarp.cpp
@@ -0,0 +1,418 @@
+#include "SpaceWarp.h"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+
+namespace {
+constexpr float MIN_ASPECT = 0.001f;
+}
+
+SpaceWarp::SpaceWarp() {
+    std::random_device rd;
+    rng.seed(rd());
+    setFlightMode(SpaceWarpFlightMode::Forward);
+}
+
+void SpaceWarp::init(int w, int h, int starCount) {
+    resize(w, h);
+    stars.resize(std::max(8, starCount));
+    for (auto& star : stars) {
+        respawn(star, true);
+    }
+    comets.clear();
+    cometSpawnTimer = randomRange(settings.cometSpawnIntervalMin, settings.cometSpawnIntervalMax);
+}
+
+void SpaceWarp::resize(int w, int h) {
+    width = std::max(1, w);
+    height = std::max(1, h);
+    centerX = width * 0.5f;
+    centerY = height * 0.5f;
+    warpFactor = std::max(width, height) * settings.warpFactorScale;
+}
+
+void SpaceWarp::setSettings(const SpaceWarpSettings& newSettings) {
+    settings = newSettings;
+    warpFactor = std::max(width, height) * settings.warpFactorScale;
+    cometSpawnTimer = std::clamp(cometSpawnTimer, settings.cometSpawnIntervalMin, settings.cometSpawnIntervalMax);
+}
+
+void SpaceWarp::setFlightMode(SpaceWarpFlightMode mode) {
+    flightMode = mode;
+    autoPilotEnabled = false;
+    switch (mode) {
+        case SpaceWarpFlightMode::Forward:
+            motion = {1.0f, 0.0f, 0.0f};
+            break;
+        case SpaceWarpFlightMode::BankLeft:
+            motion = {1.05f, -0.85f, 0.0f};
+            break;
+        case SpaceWarpFlightMode::BankRight:
+            motion = {1.05f, 0.85f, 0.0f};
+            break;
+        case SpaceWarpFlightMode::Reverse:
+            motion = {-0.6f, 0.0f, 0.0f};
+            break;
+        case SpaceWarpFlightMode::Custom:
+        default:
+            break;
+    }
+}
+
+void SpaceWarp::setFlightMotion(const SpaceWarpFlightMotion& newMotion) {
+    motion = newMotion;
+    flightMode = SpaceWarpFlightMode::Custom;
+    autoPilotEnabled = false;
+}
+
+void SpaceWarp::setAutoPilotEnabled(bool enabled) {
+    autoPilotEnabled = enabled;
+    if (enabled) {
+        flightMode = SpaceWarpFlightMode::Custom;
+        motionTarget = motion;
+        autoTimer = 0.0f;
+        scheduleNewAutoTarget();
+    }
+}
+
+void SpaceWarp::scheduleNewAutoTarget() {
+    // Autopilot behavior:
+    // - 90% of the time: gentle forward flight with small lateral/vertical drift
+    // - 10% of the time: short lateral "bank" burst (stronger lateral speed) for a while
+    float choice = randomRange(0.0f, 1.0f);
+    if (choice < 0.90f) {
+        // Normal forward flight
+        motionTarget.forwardScale = randomRange(0.95f, 1.12f);
+        motionTarget.lateralSpeed = randomRange(-0.18f, 0.18f);
+        motionTarget.verticalSpeed = randomRange(-0.12f, 0.12f);
+        // Longer interval between aggressive maneuvers
+        autoTimer = randomRange(autoMinInterval, autoMaxInterval);
+    } else {
+        // Occasional lateral bank burst
+        motionTarget.forwardScale = randomRange(0.90f, 1.10f);
+        // Pick left or right burst
+        float dir = (randomRange(0.0f, 1.0f) < 0.5f) ? -1.0f : 1.0f;
+        motionTarget.lateralSpeed = dir * randomRange(0.70f, 1.35f);
+        // Allow modest vertical bias during a bank
+        motionTarget.verticalSpeed = randomRange(-0.35f, 0.35f);
+        // Shorter duration for the burst so it feels like a brief maneuver
+        autoTimer = randomRange(1.0f, 3.0f);
+    }
+}
+
+void SpaceWarp::spawnComet() {
+    WarpComet comet;
+    float aspect = static_cast<float>(width) / static_cast<float>(std::max(1, height));
+    float normalizedAspect = std::max(aspect, MIN_ASPECT);
+    float xRange = settings.baseSpawnRange * 1.2f * (aspect >= 1.0f ? aspect : 1.0f);
+    float yRange = settings.baseSpawnRange * 1.2f * (aspect >= 1.0f ? 1.0f : (1.0f / normalizedAspect));
+    // Avoid spawning comets exactly on (or extremely near) the view axis,
+    // which can project to a nearly static bright dot.
+    const float axisMinFrac = 0.06f;
+    bool axisOk = false;
+    for (int attempt = 0; attempt < 10 && !axisOk; ++attempt) {
+        comet.x = randomRange(-xRange, xRange);
+        comet.y = randomRange(-yRange, yRange);
+        float nx = comet.x / std::max(xRange, 0.0001f);
+        float ny = comet.y / std::max(yRange, 0.0001f);
+        axisOk = (nx * nx + ny * ny) >= (axisMinFrac * axisMinFrac);
+    }
+    if (!axisOk) {
+        float ang = randomRange(0.0f, 6.28318530718f);
+        comet.x = std::cos(ang) * xRange * axisMinFrac;
+        comet.y = std::sin(ang) * yRange * axisMinFrac;
+    }
+    comet.z = randomRange(minDepth + 4.0f, maxDepth);
+    float baseSpeed = randomRange(settings.minSpeed, settings.maxSpeed);
+    float multiplier = randomRange(settings.cometSpeedMultiplierMin, settings.cometSpeedMultiplierMax);
+    comet.speed = baseSpeed * multiplier;
+    comet.size = randomRange(settings.cometMinSize, settings.cometMaxSize);
+    comet.trailLength = randomRange(settings.cometMinTrail, settings.cometMaxTrail);
+    comet.life = randomRange(1.8f, 3.4f);
+    comet.maxLife = comet.life;
+    float shade = randomRange(0.85f, 1.0f);
+    Uint8 c = static_cast<Uint8>(std::clamp(220.0f + shade * 35.0f, 0.0f, 255.0f));
+    comet.color = SDL_Color{c, Uint8(std::min(255.0f, c * 0.95f)), 255, 255};
+    // Initialize screen positions based on projection so the comet is not stuck at center
+    float sx = 0.0f, sy = 0.0f;
+    if (projectPoint(comet.x, comet.y, comet.z, sx, sy)) {
+        comet.screenX = sx;
+        comet.screenY = sy;
+        // Place prev slightly behind the head so the first frame shows motion/trail
+        float jitter = std::max(4.0f, comet.trailLength * 0.08f);
+        float ang = randomRange(0.0f, 6.28318530718f);
+        comet.prevScreenX = comet.screenX - std::cos(ang) * jitter;
+        comet.prevScreenY = comet.screenY - std::sin(ang) * jitter;
+    } else {
+        comet.prevScreenX = centerX;
+        comet.prevScreenY = centerY;
+        comet.screenX = centerX;
+        comet.screenY = centerY;
+    }
+    comets.push_back(comet);
+}
+
+float SpaceWarp::randomRange(float min, float max) {
+    std::uniform_real_distribution<float> dist(min, max);
+    return dist(rng);
+}
+
+static int randomIntInclusive(std::mt19937& rng, int min, int max) {
+    std::uniform_int_distribution<int> dist(min, max);
+    return dist(rng);
+}
+
+void SpaceWarp::respawn(WarpStar& star, bool randomDepth) {
+    float aspect = static_cast<float>(width) / static_cast<float>(std::max(1, height));
+    float normalizedAspect = std::max(aspect, MIN_ASPECT);
+    float xRange = settings.baseSpawnRange * (aspect >= 1.0f ? aspect : 1.0f);
+    float yRange = settings.baseSpawnRange * (aspect >= 1.0f ? 1.0f : (1.0f / normalizedAspect));
+    // Avoid axis-aligned stars (x≈0,y≈0) which can project to a static, bright center dot.
+    const float axisMinFrac = 0.06f;
+    bool axisOk = false;
+    for (int attempt = 0; attempt < 10 && !axisOk; ++attempt) {
+        star.x = randomRange(-xRange, xRange);
+        star.y = randomRange(-yRange, yRange);
+        float nx = star.x / std::max(xRange, 0.0001f);
+        float ny = star.y / std::max(yRange, 0.0001f);
+        axisOk = (nx * nx + ny * ny) >= (axisMinFrac * axisMinFrac);
+    }
+    if (!axisOk) {
+        float ang = randomRange(0.0f, 6.28318530718f);
+        star.x = std::cos(ang) * xRange * axisMinFrac;
+        star.y = std::sin(ang) * yRange * axisMinFrac;
+    }
+
+    // Keep z slightly above minDepth so projection never starts from the exact singular plane.
+    star.z = randomDepth ? randomRange(minDepth + 0.25f, maxDepth) : maxDepth;
+    star.speed = randomRange(settings.minSpeed, settings.maxSpeed);
+    star.shade = randomRange(settings.minShade, settings.maxShade);
+    static constexpr Uint8 GRAY_SHADES[] = {160, 180, 200, 220, 240};
+    int idx = randomIntInclusive(rng, 0, int(std::size(GRAY_SHADES)) - 1);
+    star.baseShade = GRAY_SHADES[idx];
+    // Compute initial projected screen position so newly spawned stars aren't frozen at center
+    float sx = 0.0f, sy = 0.0f;
+    if (projectPoint(star.x, star.y, star.z, sx, sy)) {
+        star.screenX = sx;
+        star.screenY = sy;
+        // give a small previous offset so trails and motion are visible immediately
+        float jitter = std::max(1.0f, settings.maxTrailLength * 0.06f);
+        float ang = randomRange(0.0f, 6.28318530718f);
+        star.prevScreenX = star.screenX - std::cos(ang) * jitter;
+        star.prevScreenY = star.screenY - std::sin(ang) * jitter;
+    } else {
+        star.prevScreenX = centerX;
+        star.prevScreenY = centerY;
+        star.screenX = centerX;
+        star.screenY = centerY;
+    }
+}
+
+bool SpaceWarp::project(const WarpStar& star, float& outX, float& outY) const {
+    return projectPoint(star.x, star.y, star.z, outX, outY);
+}
+
+bool SpaceWarp::projectPoint(float x, float y, float z, float& outX, float& outY) const {
+    if (z <= minDepth) {
+        return false;
+    }
+    float perspective = warpFactor / (z + 0.001f);
+    outX = centerX + x * perspective;
+    outY = centerY + y * perspective;
+    const float margin = settings.spawnMargin;
+    return outX >= -margin && outX <= width + margin && outY >= -margin && outY <= height + margin;
+}
+
+void SpaceWarp::update(float deltaSeconds) {
+    if (stars.empty()) {
+        return;
+    }
+
+    if (settings.cometSpawnIntervalMax > 0.0f) {
+        cometSpawnTimer -= deltaSeconds;
+        if (cometSpawnTimer <= 0.0f) {
+            spawnComet();
+            cometSpawnTimer = randomRange(settings.cometSpawnIntervalMin, settings.cometSpawnIntervalMax);
+        }
+    }
+
+    if (autoPilotEnabled) {
+        autoTimer -= deltaSeconds;
+        if (autoTimer <= 0.0f) {
+            scheduleNewAutoTarget();
+        }
+        auto follow = std::clamp(deltaSeconds * 0.45f, 0.0f, 1.0f);
+        motion.forwardScale = std::lerp(motion.forwardScale, motionTarget.forwardScale, follow);
+        motion.lateralSpeed = std::lerp(motion.lateralSpeed, motionTarget.lateralSpeed, follow);
+        motion.verticalSpeed = std::lerp(motion.verticalSpeed, motionTarget.verticalSpeed, follow);
+    }
+
+    const float forwardScale = (std::abs(motion.forwardScale) < 0.01f)
+        ? (motion.forwardScale >= 0.0f ? 0.01f : -0.01f)
+        : motion.forwardScale;
+    const bool movingBackward = forwardScale < 0.0f;
+    const float lateralSpeed = motion.lateralSpeed;
+    const float verticalSpeed = motion.verticalSpeed;
+
+    for (auto& star : stars) {
+        star.z -= star.speed * deltaSeconds * forwardScale;
+        if (!movingBackward) {
+            if (star.z <= minDepth) {
+                respawn(star, true);
+                continue;
+            }
+        } else {
+            if (star.z >= maxDepth) {
+                respawn(star, true);
+                star.z = minDepth + randomRange(0.25f, 24.0f);
+                continue;
+            }
+        }
+
+        float closeness = 1.0f - std::clamp(star.z / maxDepth, 0.0f, 1.0f);
+        float driftScale = (0.35f + closeness * 1.25f);
+        star.x += lateralSpeed * deltaSeconds * driftScale;
+        star.y += verticalSpeed * deltaSeconds * driftScale;
+
+        float sx = 0.0f;
+        float sy = 0.0f;
+        if (!project(star, sx, sy)) {
+            respawn(star, true);
+            continue;
+        }
+
+        // If a star projects to (near) the visual center, it can appear perfectly static
+        // during straight-line flight. Replace it to avoid the "big static star" artifact.
+        if (std::abs(sx - centerX) < 1.25f && std::abs(sy - centerY) < 1.25f) {
+            respawn(star, true);
+            continue;
+        }
+
+        star.prevScreenX = star.screenX;
+        star.prevScreenY = star.screenY;
+        star.screenX = sx;
+        star.screenY = sy;
+
+        float dx = star.screenX - star.prevScreenX;
+        float dy = star.screenY - star.prevScreenY;
+        float lenSq = dx * dx + dy * dy;
+        float maxStreak = std::max(settings.maxTrailLength, 0.0f);
+        if (maxStreak > 0.0f && lenSq > maxStreak * maxStreak) {
+            float len = std::sqrt(lenSq);
+            float scale = maxStreak / len;
+            star.prevScreenX = star.screenX - dx * scale;
+            star.prevScreenY = star.screenY - dy * scale;
+        }
+    }
+
+    for (auto it = comets.begin(); it != comets.end();) {
+        auto& comet = *it;
+        comet.life -= deltaSeconds;
+        comet.z -= comet.speed * deltaSeconds * forwardScale;
+        bool expired = comet.life <= 0.0f;
+        if (!movingBackward) {
+            if (comet.z <= minDepth * 0.35f) expired = true;
+        } else {
+            if (comet.z >= maxDepth + 40.0f) expired = true;
+        }
+
+        float closeness = 1.0f - std::clamp(comet.z / maxDepth, 0.0f, 1.0f);
+        float driftScale = (0.45f + closeness * 1.6f);
+        comet.x += lateralSpeed * deltaSeconds * driftScale;
+        comet.y += verticalSpeed * deltaSeconds * driftScale;
+
+        float sx = 0.0f;
+        float sy = 0.0f;
+        if (!projectPoint(comet.x, comet.y, comet.z, sx, sy)) {
+            expired = true;
+        } else {
+            comet.prevScreenX = comet.screenX;
+            comet.prevScreenY = comet.screenY;
+            comet.screenX = sx;
+            comet.screenY = sy;
+
+            float dx = comet.screenX - comet.prevScreenX;
+            float dy = comet.screenY - comet.prevScreenY;
+            float lenSq = dx * dx + dy * dy;
+            float maxTrail = std::max(comet.trailLength, 0.0f);
+            if (maxTrail > 0.0f && lenSq > maxTrail * maxTrail) {
+                float len = std::sqrt(lenSq);
+                float scale = maxTrail / len;
+                comet.prevScreenX = comet.screenX - dx * scale;
+                comet.prevScreenY = comet.screenY - dy * scale;
+            }
+        }
+
+        if (expired) {
+            it = comets.erase(it);
+        } else {
+            ++it;
+        }
+    }
+}
+
+void SpaceWarp::draw(SDL_Renderer* renderer, float alphaScale) {
+    if (stars.empty()) {
+        return;
+    }
+
+    // Add a small, smooth sub-pixel jitter to the visual center used for
+    // rendering so a single bright star/comet doesn't permanently sit exactly
+    // at the pixel-perfect center of the viewport.
+    const float jitterAmp = 1.6f; // maximum jitter in pixels
+    const uint32_t now = SDL_GetTicks();
+    const float tms = static_cast<float>(now) * 0.001f;
+    const float centerJitterX = std::sin(tms * 1.7f) * jitterAmp + std::cos(tms * 0.9f) * 0.4f;
+    const float centerJitterY = std::sin(tms * 1.1f + 3.7f) * (jitterAmp * 0.6f);
+
+    SDL_BlendMode previous = SDL_BLENDMODE_NONE;
+    SDL_GetRenderDrawBlendMode(renderer, &previous);
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_ADD);
+
+    for (const auto& star : stars) {
+        float depthFactor = 1.0f - std::clamp(star.z / maxDepth, 0.0f, 1.0f);
+        float alphaBase = std::clamp(settings.minAlpha + depthFactor * settings.alphaDepthBoost, 0.0f, 255.0f);
+        Uint8 alpha = static_cast<Uint8>(std::clamp(alphaBase * alphaScale, 0.0f, 255.0f));
+        float colorValue = std::clamp(
+            star.baseShade * (settings.baseShadeScale + depthFactor * settings.depthColorScale) * star.shade,
+            settings.minColor,
+            settings.maxColor);
+        Uint8 color = static_cast<Uint8>(colorValue);
+
+        if (settings.drawTrails) {
+            float trailAlphaFloat = alpha * settings.trailAlphaScale;
+            Uint8 trailAlpha = static_cast<Uint8>(std::clamp(trailAlphaFloat, 0.0f, 255.0f));
+            SDL_SetRenderDrawColor(renderer, color, color, color, trailAlpha);
+            SDL_RenderLine(renderer,
+                           star.prevScreenX + centerJitterX, star.prevScreenY + centerJitterY,
+                           star.screenX + centerJitterX, star.screenY + centerJitterY);
+        }
+
+        float dotSize = std::clamp(settings.minDotSize + depthFactor * (settings.maxDotSize - settings.minDotSize),
+                                   settings.minDotSize,
+                                   settings.maxDotSize);
+        SDL_FRect dot{star.screenX - dotSize * 0.5f + centerJitterX,
+                      star.screenY - dotSize * 0.5f + centerJitterY,
+                      dotSize, dotSize};
+        SDL_SetRenderDrawColor(renderer, color, color, color, alpha);
+        SDL_RenderFillRect(renderer, &dot);
+    }
+
+    for (const auto& comet : comets) {
+        float lifeNorm = std::clamp(comet.life / comet.maxLife, 0.0f, 1.0f);
+        Uint8 alpha = static_cast<Uint8>(std::clamp(220.0f * lifeNorm, 0.0f, 255.0f));
+        SDL_SetRenderDrawColor(renderer, comet.color.r, comet.color.g, comet.color.b, alpha);
+        SDL_RenderLine(renderer,
+                   comet.prevScreenX + centerJitterX, comet.prevScreenY + centerJitterY,
+                   comet.screenX + centerJitterX, comet.screenY + centerJitterY);
+
+        float size = comet.size * (0.8f + (1.0f - lifeNorm) * 0.6f);
+        SDL_FRect head{comet.screenX - size * 0.5f + centerJitterX,
+                       comet.screenY - size * 0.5f + centerJitterY,
+                       size, size};
+        SDL_RenderFillRect(renderer, &head);
+    }
+
+    SDL_SetRenderDrawBlendMode(renderer, previous);
+}
diff --git a/src/graphics/effects/SpaceWarp.h b/src/graphics/effects/SpaceWarp.h
new file mode 100644
index 0000000..525fdba
--- /dev/null
+++ b/src/graphics/effects/SpaceWarp.h
@@ -0,0 +1,126 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+#include <random>
+#include <vector>
+
+struct SpaceWarpSettings {
+    float baseSpawnRange = 1.45f;        // logical radius for initial star positions
+    float warpFactorScale = 122.85f;       // scales perspective factor so stars spread faster or slower
+    float spawnMargin = 60.0f;          // how far offscreen a star can travel before respawn
+    float minShade = 0.85f;              // lower bound for per-star brightness multiplier
+    float maxShade = 1.15f;              // upper bound for per-star brightness multiplier
+    float minSpeed = 120.0f;             // slowest warp velocity (higher feels faster motion)
+    float maxSpeed = 280.0f;             // fastest warp velocity
+    float minDotSize = 2.5f;             // smallest star size in pixels
+    float maxDotSize = 4.5f;             // largest star size in pixels
+    float minAlpha = 70.0f;             // base opacity even for distant stars
+    float alphaDepthBoost = 160.0f;      // extra opacity applied as stars approach the camera
+    float minColor = 180.0f;             // clamp for minimum grayscale value
+    float maxColor = 205.0f;             // clamp for maximum grayscale value
+    float baseShadeScale = 0.75f;        // baseline multiplier applied to the sampled grayscale shade
+    float depthColorScale = 0.55f;       // how much depth affects the grayscale brightness
+    bool drawTrails = true;             // when true, also render streak lines for hyper-speed look
+    float trailAlphaScale = 0.75f;       // relative opacity for streak lines vs dots
+    float maxTrailLength = 36.0f;        // clamp length of each streak in pixels
+    float cometSpawnIntervalMin = 2.8f;  // minimum seconds between comet spawns
+    float cometSpawnIntervalMax = 6.5f;  // maximum seconds between comet spawns
+    float cometSpeedMultiplierMin = 2.2f;// min multiplier for comet forward velocity
+    float cometSpeedMultiplierMax = 4.5f;// max multiplier for comet forward velocity
+    float cometMinTrail = 140.0f;        // minimum comet trail length in pixels
+    float cometMaxTrail = 280.0f;        // maximum comet trail length in pixels
+    float cometMinSize = 3.5f;           // minimum comet head size
+    float cometMaxSize = 6.5f;           // maximum comet head size
+};
+
+struct SpaceWarpFlightMotion {
+    float forwardScale = 1.0f;    // multiplier applied to each star's forward velocity (negative = backwards)
+    float lateralSpeed = 0.0f;    // normalized horizontal drift speed (left/right)
+    float verticalSpeed = 0.0f;   // normalized vertical drift speed (up/down)
+};
+
+enum class SpaceWarpFlightMode {
+    Forward = 0,
+    BankLeft,
+    BankRight,
+    Reverse,
+    Custom
+};
+
+class SpaceWarp {
+public:
+    SpaceWarp();
+    void init(int width, int height, int starCount = 320);
+    void resize(int width, int height);
+    void update(float deltaSeconds);
+    void draw(SDL_Renderer* renderer, float alphaScale = 1.0f);
+    void setSettings(const SpaceWarpSettings& newSettings);
+    const SpaceWarpSettings& getSettings() const { return settings; }
+    void setFlightMode(SpaceWarpFlightMode mode);
+    SpaceWarpFlightMode getFlightMode() const { return flightMode; }
+    void setFlightMotion(const SpaceWarpFlightMotion& motion); // overrides mode with Custom
+    const SpaceWarpFlightMotion& getFlightMotion() const { return motion; }
+    void setAutoPilotEnabled(bool enabled);
+    bool isAutoPilotEnabled() const { return autoPilotEnabled; }
+
+private:
+    struct WarpStar {
+        float x = 0.0f;
+        float y = 0.0f;
+        float z = 0.0f;
+        float speed = 0.0f;
+        float prevScreenX = 0.0f;
+        float prevScreenY = 0.0f;
+        float screenX = 0.0f;
+        float screenY = 0.0f;
+        float shade = 1.0f;
+        Uint8 baseShade = 220;
+    };
+
+    struct WarpComet {
+        float x = 0.0f;
+        float y = 0.0f;
+        float z = 0.0f;
+        float speed = 0.0f;
+        float life = 0.0f;
+        float maxLife = 0.0f;
+        float prevScreenX = 0.0f;
+        float prevScreenY = 0.0f;
+        float screenX = 0.0f;
+        float screenY = 0.0f;
+        float trailLength = 160.0f;
+        float size = 4.0f;
+        SDL_Color color{255, 255, 255, 255};
+    };
+
+    void respawn(WarpStar& star, bool randomDepth = true);
+    bool project(const WarpStar& star, float& outX, float& outY) const;
+    bool projectPoint(float x, float y, float z, float& outX, float& outY) const;
+    float randomRange(float min, float max);
+    void spawnComet();
+
+    std::vector<WarpStar> stars;
+    std::vector<WarpComet> comets;
+    std::mt19937 rng;
+
+    int width = 0;
+    int height = 0;
+    float centerX = 0.0f;
+    float centerY = 0.0f;
+    float warpFactor = 520.0f;
+
+    SpaceWarpSettings settings{};
+    SpaceWarpFlightMotion motion{};
+    SpaceWarpFlightMode flightMode = SpaceWarpFlightMode::Forward;
+    bool autoPilotEnabled = false;
+    float autoTimer = 0.0f;
+    float autoMinInterval = 3.5f;
+    float autoMaxInterval = 7.5f;
+    SpaceWarpFlightMotion motionTarget{};
+    float cometSpawnTimer = 0.0f;
+
+    float minDepth = 2.0f;
+    float maxDepth = 320.0f;
+
+    void scheduleNewAutoTarget();
+};
diff --git a/src/graphics/effects/Starfield.cpp b/src/graphics/effects/Starfield.cpp
new file mode 100644
index 0000000..e9a7518
--- /dev/null
+++ b/src/graphics/effects/Starfield.cpp
@@ -0,0 +1,41 @@
+// Starfield.cpp - implementation (copied into src/graphics)
+#include "graphics/Starfield.h"
+#include <SDL3/SDL.h>
+#include <random>
+
+void Starfield::init(int count, int w, int h)
+{
+    stars.clear();
+    stars.reserve(count);
+    std::mt19937 rng{std::random_device{}()};
+    std::uniform_real_distribution<float> dx(0.f, (float)w), dy(0.f, (float)h), dz(0.2f, 1.f);
+    for (int i = 0; i < count; ++i)
+        stars.push_back({dx(rng), dy(rng), dz(rng), 15.f + 35.f * dz(rng)});
+    lastW = w;
+    lastH = h;
+}
+
+void Starfield::update(float dt, int w, int h)
+{
+    if (w != lastW || h != lastH || stars.empty())
+        init((w * h) / 8000 + 120, w, h);
+    for (auto &s : stars)
+    {
+        s.y += s.speed * dt;
+        if (s.y > h)
+        {
+            s.y -= h;
+            s.x = (float)(rand() % w);
+        }
+    }
+}
+
+void Starfield::draw(SDL_Renderer *r) const
+{
+    SDL_SetRenderDrawColor(r, 255, 255, 255, 255);
+    for (auto &s : stars)
+    {
+        SDL_FRect fr{s.x, s.y, 1.f * s.z, 1.f * s.z};
+        SDL_RenderFillRect(r, &fr);
+    }
+}
diff --git a/src/graphics/effects/Starfield.h b/src/graphics/effects/Starfield.h
new file mode 100644
index 0000000..ae598d2
--- /dev/null
+++ b/src/graphics/effects/Starfield.h
@@ -0,0 +1,15 @@
+// Starfield.h - Procedural starfield background effect
+#pragma once
+#include <vector>
+struct SDL_Renderer; // fwd
+
+class Starfield {
+public:
+    void init(int count, int w, int h);
+    void update(float dt, int w, int h);
+    void draw(SDL_Renderer* r) const;
+private:
+    struct Star { float x,y,z,speed; };
+    std::vector<Star> stars;
+    int lastW{0}, lastH{0};
+};
diff --git a/src/graphics/effects/Starfield3D.cpp b/src/graphics/effects/Starfield3D.cpp
new file mode 100644
index 0000000..e9b65a1
--- /dev/null
+++ b/src/graphics/effects/Starfield3D.cpp
@@ -0,0 +1,228 @@
+// Starfield3D.cpp - 3D Parallax Starfield Implementation
+#include "Starfield3D.h"
+#include <cmath>
+#include <algorithm>
+
+Starfield3D::Starfield3D() : rng(std::random_device{}()), width(800), height(600), centerX(400), centerY(300) {
+}
+
+void Starfield3D::init(int w, int h, int starCount) {
+    width = w;
+    height = h;
+    centerX = width * 0.5f;
+    centerY = height * 0.5f;
+    
+    stars.resize(starCount);
+    createStarfield();
+}
+
+void Starfield3D::resize(int w, int h) {
+    width = w;
+    height = h;
+    centerX = width * 0.5f;
+    centerY = height * 0.5f;
+}
+
+void Starfield3D::setMagnetTarget(float localX, float localY, float strength) {
+    if (strength <= 0.0f) {
+        clearMagnetTarget();
+        return;
+    }
+    magnetActive = true;
+    magnetStrength = strength;
+    magnetX = std::clamp(localX, 0.0f, static_cast<float>(width));
+    magnetY = std::clamp(localY, 0.0f, static_cast<float>(height));
+}
+
+void Starfield3D::clearMagnetTarget() {
+    magnetActive = false;
+    magnetStrength = 0.0f;
+}
+
+float Starfield3D::randomFloat(float min, float max) {
+    std::uniform_real_distribution<float> dist(min, max);
+    return dist(rng);
+}
+
+int Starfield3D::randomRange(int min, int max) {
+    std::uniform_int_distribution<int> dist(min, max - 1);
+    return dist(rng);
+}
+
+void Starfield3D::setRandomDirection(Star3D& star) {
+    star.targetVx = randomFloat(-MAX_VELOCITY, MAX_VELOCITY);
+    star.targetVy = randomFloat(-MAX_VELOCITY, MAX_VELOCITY);
+    
+    // Allow stars to move both toward and away from viewer
+    if (randomFloat(0.0f, 1.0f) < REVERSE_PROBABILITY) {
+        // Move away from viewer (positive Z)
+        star.targetVz = STAR_SPEED * randomFloat(0.5f, 1.0f);
+    } else {
+        // Move toward viewer (negative Z)
+        star.targetVz = -STAR_SPEED * randomFloat(0.7f, 1.3f);
+    }
+    
+    star.changing = true;
+    star.changeTimer = randomFloat(30.0f, 120.0f); // Direction change lasts 30-120 frames
+}
+
+void Starfield3D::updateStar(int index) {
+    Star3D& star = stars[index];
+
+    // Avoid spawning stars on (or very near) the view axis. A star with x≈0 and y≈0
+    // projects to the exact center, and when it happens to be bright it looks like a
+    // static "big" star.
+    constexpr float SPAWN_RANGE = 25.0f;
+    constexpr float MIN_AXIS_RADIUS = 2.5f; // in star-space units
+    for (int attempt = 0; attempt < 8; ++attempt) {
+        star.x = randomFloat(-SPAWN_RANGE, SPAWN_RANGE);
+        star.y = randomFloat(-SPAWN_RANGE, SPAWN_RANGE);
+        if ((star.x * star.x + star.y * star.y) >= (MIN_AXIS_RADIUS * MIN_AXIS_RADIUS)) {
+            break;
+        }
+    }
+    // If we somehow still ended up too close, push it out deterministically.
+    if ((star.x * star.x + star.y * star.y) < (MIN_AXIS_RADIUS * MIN_AXIS_RADIUS)) {
+        star.x = (star.x < 0.0f ? -1.0f : 1.0f) * MIN_AXIS_RADIUS;
+        star.y = (star.y < 0.0f ? -1.0f : 1.0f) * MIN_AXIS_RADIUS;
+    }
+    star.z = randomFloat(1.0f, MAX_DEPTH);
+    
+    // Give stars initial velocities in all possible directions
+    if (randomFloat(0.0f, 1.0f) < 0.5f) {
+        // Half stars start moving toward viewer
+        star.vx = randomFloat(-0.1f, 0.1f);
+        star.vy = randomFloat(-0.1f, 0.1f);
+        star.vz = -STAR_SPEED * randomFloat(0.8f, 1.2f);
+    } else {
+        // Half stars start moving in random directions
+        star.vx = randomFloat(-0.2f, 0.2f);
+        star.vy = randomFloat(-0.2f, 0.2f);
+        
+        // 30% chance to start moving away
+        if (randomFloat(0.0f, 1.0f) < 0.3f) {
+            star.vz = STAR_SPEED * randomFloat(0.5f, 0.8f);
+        } else {
+            star.vz = -STAR_SPEED * randomFloat(0.8f, 1.2f);
+        }
+    }
+
+    // Ensure newly spawned stars have some lateral drift so they don't appear to
+    // "stick" near the center line.
+    if (std::abs(star.vx) < 0.02f && std::abs(star.vy) < 0.02f) {
+        const float sx = (star.x < 0.0f ? -1.0f : 1.0f);
+        const float sy = (star.y < 0.0f ? -1.0f : 1.0f);
+        star.vx = sx * randomFloat(0.04f, 0.14f);
+        star.vy = sy * randomFloat(0.04f, 0.14f);
+    }
+    
+    star.targetVx = star.vx;
+    star.targetVy = star.vy;
+    star.targetVz = star.vz;
+    star.changing = false;
+    star.changeTimer = 0.0f;
+    star.type = randomRange(0, COLOR_COUNT);
+    
+    // Give some stars initial direction variations
+    if (randomFloat(0.0f, 1.0f) < 0.4f) {
+        setRandomDirection(star);
+    }
+}
+
+void Starfield3D::createStarfield() {
+    for (size_t i = 0; i < stars.size(); ++i) {
+        updateStar(static_cast<int>(i));
+    }
+}
+
+void Starfield3D::update(float deltaTime) {
+    const float frameRate = 60.0f; // Target 60 FPS for consistency
+    const float frameMultiplier = deltaTime * frameRate;
+    
+    for (size_t i = 0; i < stars.size(); ++i) {
+        Star3D& star = stars[i];
+        
+        // Randomly change direction occasionally
+        if (!star.changing && randomFloat(0.0f, 1.0f) < DIRECTION_CHANGE_PROBABILITY * frameMultiplier) {
+            setRandomDirection(star);
+        }
+        
+        // Update velocities to approach target values
+        if (star.changing) {
+            // Smoothly transition to target velocities
+            const float change = VELOCITY_CHANGE * frameMultiplier;
+            star.vx += (star.targetVx - star.vx) * change;
+            star.vy += (star.targetVy - star.vy) * change;
+            star.vz += (star.targetVz - star.vz) * change;
+            
+            // Decrement change timer
+            star.changeTimer -= frameMultiplier;
+            if (star.changeTimer <= 0.0f) {
+                star.changing = false;
+            }
+        }
+        
+        // Update position using current velocity
+        star.x += star.vx * frameMultiplier;
+        star.y += star.vy * frameMultiplier;
+        star.z += star.vz * frameMultiplier;
+        
+        // Handle boundaries - reset star if it moves out of bounds, too close, or too far
+        if (star.z <= MIN_Z || 
+            star.z >= MAX_Z || 
+            std::abs(star.x) > 50.0f || 
+            std::abs(star.y) > 50.0f) {
+            updateStar(static_cast<int>(i));
+        }
+    }
+}
+
+void Starfield3D::drawStar(SDL_Renderer* renderer, float x, float y, SDL_Color color, float alphaScale) {
+    Uint8 alpha = static_cast<Uint8>(std::clamp(color.a * alphaScale, 0.0f, 255.0f));
+    SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, alpha);
+    
+    // Draw star as a small rectangle (1x1 pixel)
+    SDL_FRect rect{x, y, 1.0f, 1.0f};
+    SDL_RenderFillRect(renderer, &rect);
+}
+
+void Starfield3D::draw(SDL_Renderer* renderer, float offsetX, float offsetY, float alphaScale, bool grayscale) {
+    // Small visual jitter applied to the visual center so a single bright star
+    // doesn't remain perfectly fixed at the exact pixel center of the viewport.
+    const float jitterAmp = 1.6f; // max pixel offset
+    const uint32_t now = SDL_GetTicks();
+    const float tms = static_cast<float>(now) * 0.001f;
+    const float centerJitterX = std::sin(tms * 1.7f) * jitterAmp + std::cos(tms * 0.9f) * 0.4f;
+    const float centerJitterY = std::sin(tms * 1.1f + 3.7f) * (jitterAmp * 0.6f);
+
+    const bool useMagnet = magnetActive && magnetStrength > 0.0f;
+    for (const Star3D& star : stars) {
+        // Calculate perspective projection factor
+        const float k = DEPTH_FACTOR / star.z;
+        
+        // Calculate screen position with perspective
+        float px = star.x * k + centerX + centerJitterX;
+        float py = star.y * k + centerY + centerJitterY;
+
+        if (useMagnet) {
+            float dx = magnetX - px;
+            float dy = magnetY - py;
+            float dist = std::sqrt(dx * dx + dy * dy);
+            float pull = magnetStrength / (magnetStrength + dist + 1.0f);
+            pull = std::clamp(pull, 0.0f, 0.35f);
+            px += dx * pull;
+            py += dy * pull;
+        }
+        
+        // Only draw stars that are within the viewport
+        if (px >= 0.0f && px <= static_cast<float>(width) && 
+            py >= 0.0f && py <= static_cast<float>(height)) {
+            SDL_Color baseColor = STAR_COLORS[star.type % COLOR_COUNT];
+            if (grayscale) {
+                Uint8 gray = static_cast<Uint8>(0.299f * baseColor.r + 0.587f * baseColor.g + 0.114f * baseColor.b);
+                baseColor.r = baseColor.g = baseColor.b = gray;
+            }
+            drawStar(renderer, px + offsetX, py + offsetY, baseColor, alphaScale);
+        }
+    }
+}
diff --git a/src/graphics/effects/Starfield3D.h b/src/graphics/effects/Starfield3D.h
new file mode 100644
index 0000000..40c76dc
--- /dev/null
+++ b/src/graphics/effects/Starfield3D.h
@@ -0,0 +1,69 @@
+// Starfield3D.h - 3D Parallax Starfield Effect (canonical)
+#pragma once
+
+#include <SDL3/SDL.h>
+#include <vector>
+#include <random>
+#include <array>
+
+class Starfield3D {
+public:
+    Starfield3D();
+    ~Starfield3D() = default;
+
+    void init(int width, int height, int starCount = 160);
+    void update(float deltaTime);
+    void draw(SDL_Renderer* renderer, float offsetX = 0.0f, float offsetY = 0.0f, float alphaScale = 1.0f, bool grayscale = false);
+    void resize(int width, int height);
+    void setMagnetTarget(float localX, float localY, float strength);
+    void clearMagnetTarget();
+
+private:
+    struct Star3D {
+        float x, y, z;
+        float vx, vy, vz;
+        float targetVx, targetVy, targetVz;
+        float changeTimer;
+        bool changing;
+        int type;
+    };
+
+    // Helpers used by the implementation
+    void createStarfield();
+    void updateStar(int index);
+    void setRandomDirection(Star3D& star);
+    float randomFloat(float min, float max);
+    int randomRange(int min, int max);
+    void drawStar(SDL_Renderer* renderer, float x, float y, SDL_Color color, float alphaScale);
+
+    std::vector<Star3D> stars;
+    int width{0}, height{0};
+    float centerX{0}, centerY{0};
+    bool magnetActive{false};
+    float magnetX{0.0f};
+    float magnetY{0.0f};
+    float magnetStrength{0.0f};
+
+    // Random number generator
+    std::mt19937 rng;
+
+    // Visual / behavioral constants (tweakable)
+    inline static constexpr float MAX_VELOCITY = 0.5f;
+    inline static constexpr float REVERSE_PROBABILITY = 0.12f;
+    inline static constexpr float STAR_SPEED = 0.6f;
+    inline static constexpr float MAX_DEPTH = 120.0f;
+    inline static constexpr float DIRECTION_CHANGE_PROBABILITY = 0.002f;
+    inline static constexpr float VELOCITY_CHANGE = 0.02f;
+    inline static constexpr float MIN_Z = 0.1f;
+    inline static constexpr float MAX_Z = MAX_DEPTH;
+    inline static constexpr float DEPTH_FACTOR = 320.0f;
+
+    inline static constexpr int COLOR_COUNT = 5;
+    inline static const std::array<SDL_Color, COLOR_COUNT> STAR_COLORS = {
+        SDL_Color{255,255,255,255},
+        SDL_Color{200,200,255,255},
+        SDL_Color{255,220,180,255},
+        SDL_Color{180,220,255,255},
+        SDL_Color{255,180,200,255}
+    };
+};
diff --git a/src/graphics/renderers/GameRenderer.cpp b/src/graphics/renderers/GameRenderer.cpp
new file mode 100644
index 0000000..ddd4c94
--- /dev/null
+++ b/src/graphics/renderers/GameRenderer.cpp
@@ -0,0 +1,2973 @@
+#include "GameRenderer.h"
+
+#include "SyncLineRenderer.h"
+#include "../../gameplay/core/Game.h"
+#include "../../gameplay/coop/CoopGame.h"
+#include "../../app/Fireworks.h"
+#include "../ui/Font.h"
+#include "../../gameplay/effects/LineEffect.h"
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <sstream>
+#include <string>
+#include <limits>
+#include <random>
+#include <vector>
+#include "../../core/Settings.h"
+#include "../../graphics/effects/Starfield3D.h"
+
+namespace {
+struct ImpactSpark {
+    float x = 0.0f;
+    float y = 0.0f;
+    float vx = 0.0f;
+    float vy = 0.0f;
+    float lifeMs = 0.0f;
+    float maxLifeMs = 0.0f;
+    float size = 0.0f;
+    SDL_Color color{255, 255, 255, 255};
+};
+
+struct Sparkle {
+    float x = 0.0f;
+    float y = 0.0f;
+    float vx = 0.0f;
+    float vy = 0.0f;
+    float lifeMs = 0.0f;
+    float maxLifeMs = 0.0f;
+    float size = 0.0f;
+    SDL_Color color{255, 255, 255, 255};
+    float pulse = 0.0f;
+};
+
+struct ActivePieceSmoothState {
+    uint64_t sequence = 0;
+    float visualX = 0.0f;
+    bool initialized = false;
+};
+
+ActivePieceSmoothState s_activePieceSmooth;
+
+Starfield3D s_inGridStarfield;
+bool s_starfieldInitialized = false;
+std::vector<Sparkle> s_sparkles;
+float s_sparkleSpawnAcc = 0.0f;
+
+struct AsteroidBurst {
+    float x;
+    float y;
+    float lifeMs;
+    float maxLifeMs;
+    float baseRadius;
+    SDL_Color color;
+    float spin;
+};
+
+std::vector<AsteroidBurst> s_asteroidBursts;
+
+struct AsteroidShard {
+    float x;
+    float y;
+    float vx;
+    float vy;
+    float lifeMs;
+    float maxLifeMs;
+    float size;
+    SDL_Color color;
+};
+
+std::vector<AsteroidShard> s_asteroidShards;
+}
+
+struct TransportEffectState {
+    bool active = false;
+    Uint32 startTick = 0;
+    float durationMs = 600.0f;
+    Game::Piece piece;
+    float startX = 0.0f; // pixel origin of piece local (0,0)
+    float startY = 0.0f;
+    float targetX = 0.0f;
+    float targetY = 0.0f;
+    float tileSize = 24.0f;
+    // Next preview that should fade in after the transfer completes
+    Game::Piece nextPiece;
+    float nextPreviewX = 0.0f;
+    float nextPreviewY = 0.0f;
+};
+
+static TransportEffectState s_transport;
+
+static float smoothstep(float t) {
+    t = std::clamp(t, 0.0f, 1.0f);
+    return t * t * (3.0f - 2.0f * t);
+}
+
+void GameRenderer::startTransportEffect(const Game::Piece& piece, float startX, float startY, float targetX, float targetY, float tileSize, float durationSeconds) {
+    s_transport.active = true;
+    s_transport.startTick = SDL_GetTicks();
+    s_transport.durationMs = std::max(8.0f, durationSeconds * 1000.0f);
+    s_transport.piece = piece;
+    s_transport.startX = startX;
+    s_transport.startY = startY;
+    s_transport.targetX = targetX;
+    s_transport.targetY = targetY;
+    s_transport.tileSize = tileSize;
+}
+
+void GameRenderer::startTransportEffectForGame(Game* game, SDL_Texture* blocksTex, float logicalW, float logicalH, float logicalScale, float winW, float winH, float durationSeconds) {
+    if (!game) return;
+
+    // Recompute layout exactly like renderPlayingState so coordinates match
+    const float MIN_MARGIN = 40.0f;
+    const float TOP_MARGIN = 60.0f;
+    const float PANEL_WIDTH = 180.0f;
+    const float PANEL_SPACING = 30.0f;
+    const float NEXT_PIECE_HEIGHT = 120.0f;
+    const float BOTTOM_MARGIN = 60.0f;
+
+    float contentScale = logicalScale;
+    float contentW = logicalW * contentScale;
+    float contentH = logicalH * contentScale;
+    float contentOffsetX = (winW - contentW) * 0.5f / contentScale;
+    float contentOffsetY = (winH - contentH) * 0.5f / contentScale;
+
+    const float availableWidth = logicalW - (MIN_MARGIN * 2) - (PANEL_WIDTH * 2) - (PANEL_SPACING * 2);
+    const float availableHeight = logicalH - TOP_MARGIN - BOTTOM_MARGIN - NEXT_PIECE_HEIGHT;
+    const float maxBlockSizeW = availableWidth / Game::COLS;
+    const float maxBlockSizeH = availableHeight / Game::ROWS;
+    const float BLOCK_SIZE = std::min(maxBlockSizeW, maxBlockSizeH);
+    const float finalBlockSize = std::max(20.0f, std::min(BLOCK_SIZE, 40.0f));
+
+    const float GRID_W = Game::COLS * finalBlockSize;
+    const float GRID_H = Game::ROWS * finalBlockSize;
+    const float totalContentHeight = NEXT_PIECE_HEIGHT + GRID_H;
+    const float availableVerticalSpace = logicalH - TOP_MARGIN - BOTTOM_MARGIN;
+    const float verticalCenterOffset = (availableVerticalSpace - totalContentHeight) * 0.5f;
+    const float contentStartY = TOP_MARGIN + verticalCenterOffset;
+    const float totalLayoutWidth = PANEL_WIDTH + PANEL_SPACING + GRID_W + PANEL_SPACING + PANEL_WIDTH;
+    const float layoutStartX = (logicalW - totalLayoutWidth) * 0.5f;
+    const float gridX = layoutStartX + PANEL_WIDTH + PANEL_SPACING + contentOffsetX;
+    const float gridY = contentStartY + NEXT_PIECE_HEIGHT + contentOffsetY;
+
+    // Compute next panel placement (same as renderPlayingState)
+    const float NEXT_PANEL_WIDTH = GRID_W - finalBlockSize * 2.0f;
+    const float NEXT_PANEL_HEIGHT = finalBlockSize * 3.0f;
+    const float NEXT_PANEL_X = gridX + finalBlockSize;
+    // Move NEXT panel a bit higher so it visually separates from the grid
+    const float NEXT_PANEL_Y = gridY - NEXT_PANEL_HEIGHT - 12.0f;
+
+    // We'll animate the piece that is now current (the newly spawned piece)
+    const Game::Piece piece = game->current();
+
+    // Determine piece bounds in its 4x4 to center into preview area
+    int minCx = 4, maxCx = -1, minCy = 4, maxCy = -1;
+    for (int cy = 0; cy < 4; ++cy) for (int cx = 0; cx < 4; ++cx) if (Game::cellFilled(piece, cx, cy)) { minCx = std::min(minCx, cx); maxCx = std::max(maxCx, cx); minCy = std::min(minCy, cy); maxCy = std::max(maxCy, cy); }
+    if (maxCx < minCx) { minCx = 0; maxCx = 0; }
+    if (maxCy < minCy) { minCy = 0; maxCy = 0; }
+
+    const float labelReserve = finalBlockSize * 0.9f;
+    const float previewTop = NEXT_PANEL_Y + std::min(labelReserve, NEXT_PANEL_HEIGHT * 0.45f);
+    const float previewBottom = NEXT_PANEL_Y + NEXT_PANEL_HEIGHT - finalBlockSize * 0.25f;
+    const float previewCenterY = (previewTop + previewBottom) * 0.5f;
+    const float previewCenterX = std::round(NEXT_PANEL_X + NEXT_PANEL_WIDTH * 0.5f);
+
+    const float pieceWidth = static_cast<float>(maxCx - minCx + 1) * finalBlockSize;
+    const float pieceHeight = static_cast<float>(maxCy - minCy + 1) * finalBlockSize;
+    float startX = previewCenterX - pieceWidth * 0.5f - static_cast<float>(minCx) * finalBlockSize;
+    float startY = previewCenterY - pieceHeight * 0.5f - static_cast<float>(minCy) * finalBlockSize;
+    // Snap to grid columns
+    float gridOriginX = NEXT_PANEL_X - finalBlockSize;
+    float rel = startX - gridOriginX;
+    float nearestTile = std::round(rel / finalBlockSize);
+    startX = gridOriginX + nearestTile * finalBlockSize;
+    // Raise preview slightly to remove a thin line artifact under the panel
+    startY = std::round(startY) - 5.0f;
+
+    // Target is the current piece's grid position
+    float targetX = gridX + piece.x * finalBlockSize;
+    float targetY = gridY + piece.y * finalBlockSize;
+
+    // Also compute where the new NEXT preview (game->next()) will be drawn so we can fade it in later
+    const Game::Piece nextPiece = game->next();
+
+    // Compute next preview placement (center within NEXT panel)
+    int nMinCx = 4, nMaxCx = -1, nMinCy = 4, nMaxCy = -1;
+    for (int cy = 0; cy < 4; ++cy) for (int cx = 0; cx < 4; ++cx) if (Game::cellFilled(nextPiece, cx, cy)) { nMinCx = std::min(nMinCx, cx); nMaxCx = std::max(nMaxCx, cx); nMinCy = std::min(nMinCy, cy); nMaxCy = std::max(nMaxCy, cy); }
+    if (nMaxCx < nMinCx) { nMinCx = 0; nMaxCx = 0; }
+    if (nMaxCy < nMinCy) { nMinCy = 0; nMaxCy = 0; }
+
+    const float previewTop2 = NEXT_PANEL_Y + std::min(finalBlockSize * 0.9f, NEXT_PANEL_HEIGHT * 0.45f);
+    const float previewBottom2 = NEXT_PANEL_Y + NEXT_PANEL_HEIGHT - finalBlockSize * 0.25f;
+    const float previewCenterY2 = (previewTop2 + previewBottom2) * 0.5f;
+    const float previewCenterX2 = std::round(NEXT_PANEL_X + NEXT_PANEL_WIDTH * 0.5f);
+    const float pieceWidth2 = static_cast<float>(nMaxCx - nMinCx + 1) * finalBlockSize;
+    const float pieceHeight2 = static_cast<float>(nMaxCy - nMinCy + 1) * finalBlockSize;
+    float nextPreviewX = previewCenterX2 - pieceWidth2 * 0.5f - static_cast<float>(nMinCx) * finalBlockSize;
+    float nextPreviewY = previewCenterY2 - pieceHeight2 * 0.5f - static_cast<float>(nMinCy) * finalBlockSize;
+    // Snap to grid columns
+    float gridOriginX2 = NEXT_PANEL_X - finalBlockSize;
+    float rel2 = nextPreviewX - gridOriginX2;
+    float nearestTile2 = std::round(rel2 / finalBlockSize);
+    nextPreviewX = gridOriginX2 + nearestTile2 * finalBlockSize;
+    nextPreviewY = std::round(nextPreviewY) - 5.0f;
+
+    // Initialize transport state to perform fades: preview fade-out -> grid fade-in -> next preview fade-in
+    s_transport.active = true;
+    s_transport.startTick = SDL_GetTicks();
+    s_transport.durationMs = std::max(100.0f, durationSeconds * 1000.0f);
+    s_transport.piece = piece;
+    s_transport.startX = startX;
+    s_transport.startY = startY;
+    s_transport.targetX = targetX;
+    s_transport.targetY = targetY;
+    s_transport.tileSize = finalBlockSize;
+    // Store next preview piece and its pixel origin so we can fade it in later
+    s_transport.nextPiece = nextPiece;
+    s_transport.nextPreviewX = nextPreviewX;
+    s_transport.nextPreviewY = nextPreviewY;
+}
+
+bool GameRenderer::isTransportActive() {
+    return s_transport.active;
+}
+
+// Draw the ongoing transport effect; called every frame from renderPlayingState
+static void updateAndDrawTransport(SDL_Renderer* renderer, SDL_Texture* blocksTex) {
+    if (!s_transport.active) return;
+    Uint32 now = SDL_GetTicks();
+    float elapsed = static_cast<float>(now - s_transport.startTick);
+    float total = s_transport.durationMs;
+    if (total <= 0.0f) total = 1.0f;
+    // Simultaneous cross-fade: as the NEXT preview fades out, the piece fades into the grid
+    // and the new NEXT preview fades in — all driven by the same normalized t in [0,1].
+    float t = std::clamp(elapsed / total, 0.0f, 1.0f);
+    Uint8 previewAlpha = static_cast<Uint8>(std::lround(255.0f * (1.0f - t)));
+    Uint8 gridAlpha = static_cast<Uint8>(std::lround(255.0f * t));
+    Uint8 nextAlpha = gridAlpha; // fade new NEXT preview in at same rate as grid
+
+    // Draw preview fade-out
+    if (previewAlpha > 0) {
+        if (blocksTex) SDL_SetTextureAlphaMod(blocksTex, previewAlpha);
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!Game::cellFilled(s_transport.piece, cx, cy)) continue;
+                float px = s_transport.startX + static_cast<float>(cx) * s_transport.tileSize;
+                float py = s_transport.startY + static_cast<float>(cy) * s_transport.tileSize;
+                GameRenderer::drawBlockTexturePublic(renderer, blocksTex, px, py, s_transport.tileSize, s_transport.piece.type);
+            }
+        }
+        if (blocksTex) SDL_SetTextureAlphaMod(blocksTex, 255);
+    }
+
+    // Draw grid fade-in (same intensity as next preview fade-in)
+    if (gridAlpha > 0) {
+        if (blocksTex) SDL_SetTextureAlphaMod(blocksTex, gridAlpha);
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!Game::cellFilled(s_transport.piece, cx, cy)) continue;
+                float gx = s_transport.targetX + static_cast<float>(cx) * s_transport.tileSize;
+                float gy = s_transport.targetY + static_cast<float>(cy) * s_transport.tileSize;
+                GameRenderer::drawBlockTexturePublic(renderer, blocksTex, gx, gy, s_transport.tileSize, s_transport.piece.type);
+            }
+        }
+        if (blocksTex) SDL_SetTextureAlphaMod(blocksTex, 255);
+    }
+
+    // Draw new NEXT preview fade-in (simultaneous)
+    if (nextAlpha > 0) {
+        if (blocksTex) SDL_SetTextureAlphaMod(blocksTex, nextAlpha);
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!Game::cellFilled(s_transport.nextPiece, cx, cy)) continue;
+                float nx = s_transport.nextPreviewX + static_cast<float>(cx) * s_transport.tileSize;
+                float ny = s_transport.nextPreviewY + static_cast<float>(cy) * s_transport.tileSize;
+                GameRenderer::drawBlockTexturePublic(renderer, blocksTex, nx, ny, s_transport.tileSize, s_transport.nextPiece.type);
+            }
+        }
+        if (blocksTex) SDL_SetTextureAlphaMod(blocksTex, 255);
+    }
+
+    if (t >= 1.0f) {
+        s_transport.active = false;
+    }
+}
+
+// Color constants (copied from main.cpp)
+static const SDL_Color COLORS[] = {
+    {0, 0, 0, 255},        // 0: BLACK (empty)
+    {0, 255, 255, 255},    // 1: I-piece - cyan
+    {255, 255, 0, 255},    // 2: O-piece - yellow
+    {128, 0, 128, 255},    // 3: T-piece - purple
+    {0, 255, 0, 255},      // 4: S-piece - green
+    {255, 0, 0, 255},      // 5: Z-piece - red
+    {0, 0, 255, 255},      // 6: J-piece - blue
+    {255, 165, 0, 255}     // 7: L-piece - orange
+};
+
+void GameRenderer::drawRect(SDL_Renderer* renderer, float x, float y, float w, float h, SDL_Color c) {
+    SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, c.a);
+    SDL_FRect fr{x, y, w, h};
+    SDL_RenderFillRect(renderer, &fr);
+}
+
+static void drawAsteroid(SDL_Renderer* renderer, SDL_Texture* asteroidTex, float x, float y, float size, const AsteroidCell& cell) {
+    auto outlineGravity = [&](float inset, SDL_Color color) {
+        SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, color.a);
+        SDL_FRect glow{ x + inset, y + inset, size - inset * 2.0f, size - inset * 2.0f };
+        SDL_RenderRect(renderer, &glow);
+    };
+
+    if (asteroidTex) {
+        const float SPRITE_SIZE = 90.0f;
+        int col = 0;
+        switch (cell.type) {
+            case AsteroidType::Normal: col = 0; break;
+            case AsteroidType::Armored: col = 1; break;
+            case AsteroidType::Falling: col = 2; break;
+            case AsteroidType::Core: col = 3; break;
+        }
+        int row = std::clamp<int>(cell.visualState, 0, 2);
+        SDL_FRect src{ col * SPRITE_SIZE, row * SPRITE_SIZE, SPRITE_SIZE, SPRITE_SIZE };
+        SDL_FRect dst{ x, y, size, size };
+        SDL_RenderTexture(renderer, asteroidTex, &src, &dst);
+
+        if (cell.gravityEnabled) {
+            outlineGravity(2.0f, SDL_Color{255, 230, 120, 180});
+        }
+        return;
+    }
+
+    // Fallback: draw a colored quad (previous implementation)
+    SDL_Color base{};
+    switch (cell.type) {
+        case AsteroidType::Normal: base = SDL_Color{172, 138, 104, 255}; break;
+        case AsteroidType::Armored: base = SDL_Color{130, 150, 176, 255}; break;
+        case AsteroidType::Falling: base = SDL_Color{210, 120, 82, 255}; break;
+        case AsteroidType::Core: base = SDL_Color{198, 78, 200, 255}; break;
+    }
+    float hpScale = std::clamp(static_cast<float>(cell.hitsRemaining) / 3.0f, 0.25f, 1.0f);
+    SDL_Color fill{
+        static_cast<Uint8>(base.r * hpScale + 40 * (1.0f - hpScale)),
+        static_cast<Uint8>(base.g * hpScale + 40 * (1.0f - hpScale)),
+        static_cast<Uint8>(base.b * hpScale + 40 * (1.0f - hpScale)),
+        255
+    };
+    SDL_SetRenderDrawColor(renderer, fill.r, fill.g, fill.b, fill.a);
+    SDL_FRect body{x, y, size - 1.0f, size - 1.0f};
+    SDL_RenderFillRect(renderer, &body);
+
+    SDL_Color outline = base;
+    outline.a = 220;
+    SDL_FRect border{x + 1.0f, y + 1.0f, size - 2.0f, size - 2.0f};
+    SDL_SetRenderDrawColor(renderer, outline.r, outline.g, outline.b, outline.a);
+    SDL_RenderRect(renderer, &border);
+    if (cell.gravityEnabled) {
+        outlineGravity(2.0f, SDL_Color{255, 230, 120, 180});
+    }
+}
+
+void GameRenderer::drawBlockTexture(SDL_Renderer* renderer, SDL_Texture* blocksTex, float x, float y, float size, int blockType) {
+    if (!blocksTex || blockType < 0 || blockType >= PIECE_COUNT) {
+        // Fallback to colored rectangle if texture isn't available
+        SDL_Color color = (blockType >= 0 && blockType < PIECE_COUNT) ? COLORS[blockType + 1] : SDL_Color{128, 128, 128, 255};
+        drawRect(renderer, x, y, size-1, size-1, color);
+        return;
+    }
+    
+    // JavaScript uses: sx = type * spriteSize, sy = 0, with 2px padding
+    // Each sprite is 90px wide in the horizontal sprite sheet
+    const int SPRITE_SIZE = 90;
+    float srcX = blockType * SPRITE_SIZE + 2;  // Add 2px padding like JS
+    float srcY = 2;                            // Add 2px padding from top like JS
+    float srcW = SPRITE_SIZE - 4;              // Subtract 4px total padding like JS
+    float srcH = SPRITE_SIZE - 4;              // Subtract 4px total padding like JS
+    
+    SDL_FRect srcRect = {srcX, srcY, srcW, srcH};
+    SDL_FRect dstRect = {x, y, size, size};
+    SDL_RenderTexture(renderer, blocksTex, &srcRect, &dstRect);
+}
+
+void GameRenderer::drawPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, const Game::Piece& piece, float ox, float oy, float tileSize, bool isGhost, float pixelOffsetX, float pixelOffsetY) {
+    if (piece.type >= PIECE_COUNT) return;
+    
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (Game::cellFilled(piece, cx, cy)) {
+                float px = ox + (piece.x + cx) * tileSize + pixelOffsetX;
+                float py = oy + (piece.y + cy) * tileSize + pixelOffsetY;
+                
+                if (isGhost) {
+                    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+                    
+                    // Draw ghost piece as barely visible gray outline
+                    SDL_SetRenderDrawColor(renderer, 180, 180, 180, 20); // Very faint gray
+                    SDL_FRect rect = {px + 2, py + 2, tileSize - 4, tileSize - 4};
+                    SDL_RenderFillRect(renderer, &rect);
+                    
+                    // Draw thin gray border
+                    SDL_SetRenderDrawColor(renderer, 180, 180, 180, 30);
+                    SDL_FRect border = {px + 1, py + 1, tileSize - 2, tileSize - 2};
+                    SDL_RenderRect(renderer, &border);
+                } else {
+                    drawBlockTexture(renderer, blocksTex, px, py, tileSize, piece.type);
+                }
+            }
+        }
+    }
+}
+
+void GameRenderer::drawBlockTexturePublic(SDL_Renderer* renderer, SDL_Texture* blocksTex, float x, float y, float size, int blockType) {
+    // Forward to the private helper
+    drawBlockTexture(renderer, blocksTex, x, y, size, blockType);
+}
+
+void GameRenderer::drawSmallPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, PieceType pieceType, float x, float y, float tileSize) {
+    if (pieceType >= PIECE_COUNT) return;
+    
+    // Use the first rotation (index 0) for preview
+    Game::Piece previewPiece;
+    previewPiece.type = pieceType;
+    previewPiece.rot = 0;
+    previewPiece.x = 0;
+    previewPiece.y = 0;
+    
+    // Determine occupied bounds within 4x4 and center inside the 4x4 preview area
+    int minCx = 4, maxCx = -1, minCy = 4, maxCy = -1;
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (Game::cellFilled(previewPiece, cx, cy)) {
+                minCx = std::min(minCx, cx);
+                maxCx = std::max(maxCx, cx);
+                minCy = std::min(minCy, cy);
+                maxCy = std::max(maxCy, cy);
+            }
+        }
+    }
+    if (maxCx < minCx) { minCx = 0; maxCx = 0; }
+    if (maxCy < minCy) { minCy = 0; maxCy = 0; }
+
+    float areaW = 4.0f * tileSize;
+    float areaH = 4.0f * tileSize;
+    float pieceW = static_cast<float>(maxCx - minCx + 1) * tileSize;
+    float pieceH = static_cast<float>(maxCy - minCy + 1) * tileSize;
+    float offsetX = (areaW - pieceW) * 0.5f - static_cast<float>(minCx) * tileSize;
+    float offsetY = (areaH - pieceH) * 0.5f - static_cast<float>(minCy) * tileSize;
+    offsetX = std::round(offsetX);
+    offsetY = std::round(offsetY);
+    
+    // Use semi-transparent alpha for preview blocks
+    Uint8 previewAlpha = 180;
+    if (blocksTex) {
+        SDL_SetTextureAlphaMod(blocksTex, previewAlpha);
+    }
+    
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (Game::cellFilled(previewPiece, cx, cy)) {
+                float px = x + offsetX + cx * tileSize;
+                float py = y + offsetY + cy * tileSize;
+                GameRenderer::drawBlockTexturePublic(renderer, blocksTex, px, py, tileSize, pieceType);
+            }
+        }
+    }
+    
+    // Reset alpha
+    if (blocksTex) {
+        SDL_SetTextureAlphaMod(blocksTex, 255);
+    }
+}
+
+void GameRenderer::renderNextPanel(
+    SDL_Renderer* renderer,
+    FontAtlas* pixelFont,
+    SDL_Texture* blocksTex,
+    SDL_Texture* nextPanelTex,
+    const Game::Piece& nextPiece,
+    float panelX,
+    float panelY,
+    float panelW,
+    float panelH,
+    float tileSize
+) {
+    if (!renderer || !pixelFont) {
+        return;
+    }
+
+    const SDL_Color gridBorderColor{60, 80, 160, 255}; // matches main grid outline
+    const SDL_Color bayColor{8, 12, 24, 235};
+    const SDL_Color bayOutline{25, 62, 86, 220};
+    const SDL_Color labelColor{255, 220, 0, 255};
+
+    // If an external NEXT panel texture is provided, draw it scaled into
+    // the panel rectangle and skip the custom background/frame drawing.
+    if (nextPanelTex) {
+        SDL_FRect dst{panelX, panelY, panelW, panelH};
+        SDL_RenderTexture(renderer, nextPanelTex, nullptr, &dst);
+        // Draw the panel label over the texture — user requested visible label
+        const float labelPad = tileSize * 0.25f;
+        pixelFont->draw(renderer, panelX + labelPad, panelY + labelPad * 0.5f, "NEXT", 0.9f, labelColor);
+    } else {
+        SDL_FRect bayRect{panelX, panelY, panelW, panelH};
+        SDL_SetRenderDrawColor(renderer, bayColor.r, bayColor.g, bayColor.b, bayColor.a);
+        SDL_RenderFillRect(renderer, &bayRect);
+
+        SDL_FRect thinOutline{panelX - 1.0f, panelY - 1.0f, panelW + 2.0f, panelH + 2.0f};
+        auto drawOutlineNoBottom = [&](const SDL_FRect& rect, SDL_Color color) {
+            SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, color.a);
+            const float left = rect.x;
+            const float top = rect.y;
+            const float right = rect.x + rect.w;
+            const float bottom = rect.y + rect.h;
+            SDL_RenderLine(renderer, left, top, right, top);       // top edge
+            SDL_RenderLine(renderer, left, top, left, bottom);     // left edge
+            SDL_RenderLine(renderer, right, top, right, bottom);   // right edge
+        };
+
+        drawOutlineNoBottom(thinOutline, gridBorderColor);
+        drawOutlineNoBottom(bayRect, bayOutline);
+
+        const float labelPad = tileSize * 0.25f;
+        pixelFont->draw(renderer, panelX + labelPad, panelY + labelPad * 0.5f, "NEXT", 0.9f, labelColor);
+    }
+
+    if (nextPiece.type >= PIECE_COUNT) {
+        return;
+    }
+
+    // Determine the occupied bounds of the tetromino within its 4x4 local grid.
+    int minCx = 4;
+    int maxCx = -1;
+    int minCy = 4;
+    int maxCy = -1;
+    for (int cy = 0; cy < 4; ++cy) {
+        for (int cx = 0; cx < 4; ++cx) {
+            if (!Game::cellFilled(nextPiece, cx, cy)) {
+                continue;
+            }
+            minCx = std::min(minCx, cx);
+            maxCx = std::max(maxCx, cx);
+            minCy = std::min(minCy, cy);
+            maxCy = std::max(maxCy, cy);
+        }
+    }
+
+    if (maxCx < minCx || maxCy < minCy) {
+        return;
+    }
+
+    // Reserve a little headroom for the NEXT label, then center the piece in screen-space.
+    const float labelReserve = tileSize * 0.9f;
+    const float previewTop = panelY + std::min(labelReserve, panelH * 0.45f);
+    const float previewBottom = panelY + panelH - tileSize * 0.25f;
+    const float previewCenterY = (previewTop + previewBottom) * 0.5f;
+    const float previewCenterX = std::round(panelX + panelW * 0.5f);
+
+    const float pieceWidth = static_cast<float>(maxCx - minCx + 1) * tileSize;
+    const float pieceHeight = static_cast<float>(maxCy - minCy + 1) * tileSize;
+    // Center piece so its local cells fall exactly on grid-aligned pixel columns
+    float startX = previewCenterX - pieceWidth * 0.5f - static_cast<float>(minCx) * tileSize;
+    float startY = previewCenterY - pieceHeight * 0.5f - static_cast<float>(minCy) * tileSize;
+    // Snap horizontal position to the playfield's tile grid so preview cells align exactly
+    // with the main grid columns. `panelX` was computed as `gridX + tileSize` in caller,
+    // so derive grid origin as `panelX - tileSize`.
+    float gridOriginX = panelX - tileSize;
+    float rel = startX - gridOriginX;
+    float nearestTile = std::round(rel / tileSize);
+    startX = gridOriginX + nearestTile * tileSize;
+    // Round Y to pixel to avoid subpixel artifacts and nudge upward slightly
+    startY = std::round(startY) - 5.0f;
+
+    // If a transfer fade is active, the preview cells will be drawn by the
+    // transport effect (with fade). Skip drawing the normal preview in that case.
+    if (!s_transport.active) {
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!Game::cellFilled(nextPiece, cx, cy)) {
+                    continue;
+                }
+                const float px = startX + static_cast<float>(cx) * tileSize;
+                const float py = startY + static_cast<float>(cy) * tileSize;
+                GameRenderer::drawBlockTexturePublic(renderer, blocksTex, px, py, tileSize, nextPiece.type);
+            }
+        }
+    }
+}
+
+void GameRenderer::renderPlayingState(
+    SDL_Renderer* renderer,
+    Game* game,
+    FontAtlas* pixelFont,
+    LineEffect* lineEffect,
+    SDL_Texture* blocksTex,
+    SDL_Texture* asteroidsTex,
+    SDL_Texture* statisticsPanelTex,
+    SDL_Texture* scorePanelTex,
+    SDL_Texture* nextPanelTex,
+    SDL_Texture* holdPanelTex,
+    bool countdownActive,
+    float logicalW,
+    float logicalH,
+    float logicalScale,
+    float winW,
+    float winH,
+    bool challengeClearFxActive,
+    const std::vector<int>* challengeClearFxOrder,
+    double challengeClearFxElapsedMs,
+    double challengeClearFxDurationMs,
+    const std::string* challengeStoryText,
+    float challengeStoryAlpha
+) {
+    if (!game || !pixelFont) return;
+
+    static std::vector<ImpactSpark> s_impactSparks;
+    static uint32_t s_lastImpactFxId = 0;
+    static Uint32 s_lastImpactTick = SDL_GetTicks();
+    static std::mt19937 s_impactRng{ std::random_device{}() };
+
+    Uint32 nowTicks = SDL_GetTicks();
+    float sparkDeltaMs = static_cast<float>(nowTicks - s_lastImpactTick);
+    s_lastImpactTick = nowTicks;
+    if (sparkDeltaMs < 0.0f || sparkDeltaMs > 100.0f) {
+        sparkDeltaMs = 16.0f;
+    }
+    
+    // Calculate actual content area (centered within the window)
+    float contentScale = logicalScale;
+    float contentW = logicalW * contentScale;
+    float contentH = logicalH * contentScale;
+    float contentOffsetX = (winW - contentW) * 0.5f / contentScale;
+    float contentOffsetY = (winH - contentH) * 0.5f / contentScale;
+    
+    // Helper lambda for drawing rectangles with content offset
+    auto drawRectWithOffset = [&](float x, float y, float w, float h, SDL_Color c) {
+        SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, c.a);
+        SDL_FRect fr{x + contentOffsetX, y + contentOffsetY, w, h};
+        SDL_RenderFillRect(renderer, &fr);
+    };
+
+        // Responsive layout that scales with window size while maintaining margins
+        const float MIN_MARGIN = 40.0f;
+        const float TOP_MARGIN = 60.0f;
+        const float PANEL_WIDTH = 180.0f;
+        const float PANEL_SPACING = 30.0f;
+        const float NEXT_PIECE_HEIGHT = 120.0f;
+        const float BOTTOM_MARGIN = 60.0f;
+
+        // Calculate layout dimensions
+        const float availableWidth = logicalW - (MIN_MARGIN * 2) - (PANEL_WIDTH * 2) - (PANEL_SPACING * 2);
+        const float availableHeight = logicalH - TOP_MARGIN - BOTTOM_MARGIN - NEXT_PIECE_HEIGHT;
+
+        const float maxBlockSizeW = availableWidth / Game::COLS;
+        const float maxBlockSizeH = availableHeight / Game::ROWS;
+        const float BLOCK_SIZE = std::min(maxBlockSizeW, maxBlockSizeH);
+        const float finalBlockSize = std::max(20.0f, std::min(BLOCK_SIZE, 40.0f));
+
+        const float GRID_W = Game::COLS * finalBlockSize;
+        const float GRID_H = Game::ROWS * finalBlockSize;
+
+        // Calculate positions
+        const float totalContentHeight = NEXT_PIECE_HEIGHT + GRID_H;
+        const float availableVerticalSpace = logicalH - TOP_MARGIN - BOTTOM_MARGIN;
+        const float verticalCenterOffset = (availableVerticalSpace - totalContentHeight) * 0.5f;
+        const float contentStartY = TOP_MARGIN + verticalCenterOffset;
+
+        const float totalLayoutWidth = PANEL_WIDTH + PANEL_SPACING + GRID_W + PANEL_SPACING + PANEL_WIDTH;
+        const float layoutStartX = (logicalW - totalLayoutWidth) * 0.5f;
+
+        const float statsX = layoutStartX + contentOffsetX;
+        const float gridX = layoutStartX + PANEL_WIDTH + PANEL_SPACING + contentOffsetX;
+        const float gridY = contentStartY + NEXT_PIECE_HEIGHT + contentOffsetY;
+
+        const float statsY = gridY;
+        const float statsW = PANEL_WIDTH;
+        const float statsH = GRID_H;
+
+        // Next piece preview position
+        // Make NEXT panel span the inner area of the grid with a 1-cell margin on both sides
+        const float NEXT_PANEL_WIDTH = GRID_W - finalBlockSize * 2.0f; // leave 1 cell on left and right
+        const float NEXT_PANEL_HEIGHT = finalBlockSize * 3.0f;
+        const float NEXT_PANEL_X = gridX + finalBlockSize; // align panel so there's exactly one cell margin
+        // Move NEXT panel a bit higher so it visually separates from the grid
+        const float NEXT_PANEL_Y = gridY - NEXT_PANEL_HEIGHT - 12.0f; // nudge up ~12px
+    
+    // Handle line clearing effects
+    if (game->hasCompletedLines() && lineEffect && !lineEffect->isActive()) {
+        auto completedLines = game->getCompletedLines();
+        lineEffect->startLineClear(completedLines, static_cast<int>(gridX), static_cast<int>(gridY), static_cast<int>(finalBlockSize));
+        // Trigger fireworks visually for a 4-line clear (TETRIS)
+        if (completedLines.size() == 4) {
+            // spawn near center of grid
+            AppFireworks::spawn(gridX + GRID_W * 0.5f, gridY + GRID_H * 0.5f);
+        }
+    }
+    
+    // Draw game grid border
+    drawRectWithOffset(gridX - 3 - contentOffsetX, gridY - 3 - contentOffsetY, GRID_W + 6, GRID_H + 6, {100, 120, 200, 255});
+    // Draw a 1px blue border around grid but omit the top horizontal so the NEXT panel
+    // can visually join seamlessly. We'll draw left, right and bottom bands manually.
+    {
+        SDL_Color blue{60, 80, 160, 255};
+        // left vertical band (1px wide)
+        drawRectWithOffset(gridX - 1 - contentOffsetX, gridY - contentOffsetY, 1.0f, GRID_H, blue);
+        // right vertical band (1px wide)
+        drawRectWithOffset(gridX + GRID_W - contentOffsetX, gridY - contentOffsetY, 1.0f, GRID_H, blue);
+        // bottom horizontal band (1px high)
+        drawRectWithOffset(gridX - 1 - contentOffsetX, gridY + GRID_H - contentOffsetY, GRID_W + 2.0f, 1.0f, blue);
+    }
+    drawRectWithOffset(gridX - contentOffsetX, gridY - contentOffsetY, GRID_W, GRID_H, {20, 25, 35, 255});
+    
+    // Draw stats panel backdrop using the same art as the score panel
+    const float blocksPanelPadLeft = 34.0f;
+    const float blocksPanelPadRight = 10.0f;
+    const float blocksPanelPadY = 26.0f;
+    SDL_FRect blocksPanelBg{
+        statsX - blocksPanelPadLeft,
+        gridY - blocksPanelPadY,
+        statsW + blocksPanelPadLeft + blocksPanelPadRight,
+        GRID_H + blocksPanelPadY * 2.0f
+    };
+    if (statisticsPanelTex) {
+        // Use the dedicated statistics panel image; scale it to fit the panel while
+        // preserving aspect ratio (no crop) so very tall source images don't overflow.
+        float texWf = 0.0f, texHf = 0.0f;
+        if (SDL_GetTextureSize(statisticsPanelTex, &texWf, &texHf)) {
+            if (texWf > 0.0f && texHf > 0.0f) {
+            const float destW = blocksPanelBg.w;
+            const float destH = blocksPanelBg.h;
+            const float scale = std::min(destW / texWf, destH / texHf);
+            const float scaledW = texWf * scale;
+            const float scaledH = texHf * scale;
+            // Center the scaled texture inside the panel
+            SDL_FRect dstF{
+                blocksPanelBg.x + (destW - scaledW) * 0.5f,
+                blocksPanelBg.y + (destH - scaledH) * 0.5f,
+                scaledW,
+                scaledH
+            };
+            SDL_RenderTexture(renderer, statisticsPanelTex, nullptr, &dstF);
+            }
+        } else {
+            // Fallback: render entire texture stretched to panel
+            SDL_RenderTexture(renderer, statisticsPanelTex, nullptr, &blocksPanelBg);
+        }
+    } else if (scorePanelTex) {
+        SDL_RenderTexture(renderer, scorePanelTex, nullptr, &blocksPanelBg);
+    } else {
+        SDL_SetRenderDrawColor(renderer, 12, 18, 32, 205);
+        SDL_RenderFillRect(renderer, &blocksPanelBg);
+    }
+    
+    // Draw grid lines
+    SDL_SetRenderDrawColor(renderer, 40, 45, 60, 255);
+    for (int x = 1; x < Game::COLS; ++x) {
+        float lineX = gridX + x * finalBlockSize;
+        SDL_RenderLine(renderer, lineX, gridY, lineX, gridY + GRID_H);
+    }
+    for (int y = 1; y < Game::ROWS; ++y) {
+        float lineY = gridY + y * finalBlockSize;
+        SDL_RenderLine(renderer, gridX, lineY, gridX + GRID_W, lineY);
+    }
+
+    if (!s_starfieldInitialized) {
+        s_inGridStarfield.init(static_cast<int>(GRID_W), static_cast<int>(GRID_H), 180);
+        s_starfieldInitialized = true;
+    } else {
+        s_inGridStarfield.resize(static_cast<int>(GRID_W), static_cast<int>(GRID_H));
+    }
+
+    const float deltaSeconds = std::clamp(static_cast<float>(sparkDeltaMs) / 1000.0f, 0.0f, 0.033f);
+    s_inGridStarfield.update(deltaSeconds);
+
+    bool appliedMagnet = false;
+    if (game) {
+        const Game::Piece& activePiece = game->current();
+        const int pieceType = static_cast<int>(activePiece.type);
+        if (pieceType >= 0 && pieceType < PIECE_COUNT) {
+            float sumLocalX = 0.0f;
+            float sumLocalY = 0.0f;
+            int filledCells = 0;
+            for (int cy = 0; cy < 4; ++cy) {
+                for (int cx = 0; cx < 4; ++cx) {
+                    if (!Game::cellFilled(activePiece, cx, cy)) {
+                        continue;
+                    }
+                    sumLocalX += (activePiece.x + cx + 0.5f) * finalBlockSize;
+                    sumLocalY += (activePiece.y + cy + 0.5f) * finalBlockSize;
+                    ++filledCells;
+                }
+            }
+            if (filledCells > 0) {
+                float magnetLocalX = sumLocalX / static_cast<float>(filledCells);
+                float magnetLocalY = sumLocalY / static_cast<float>(filledCells);
+                magnetLocalX = std::clamp(magnetLocalX, 0.0f, GRID_W);
+                magnetLocalY = std::clamp(magnetLocalY, 0.0f, GRID_H);
+                const float magnetStrength = finalBlockSize * 2.2f;
+                s_inGridStarfield.setMagnetTarget(magnetLocalX, magnetLocalY, magnetStrength);
+                appliedMagnet = true;
+            }
+        }
+    }
+    if (!appliedMagnet) {
+        s_inGridStarfield.clearMagnetTarget();
+    }
+
+    SDL_BlendMode oldBlend = SDL_BLENDMODE_NONE;
+    SDL_GetRenderDrawBlendMode(renderer, &oldBlend);
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+    // Add a small, smooth sub-pixel jitter to the starfield origin so the
+    // brightest star doesn't permanently sit exactly at the visual center.
+    {
+        const float jitterAmp = 1.6f; // max pixels of jitter
+        const uint32_t now = SDL_GetTicks();
+        const float tms = static_cast<float>(now) * 0.001f;
+        const float jitterX = std::sin(tms * 1.7f) * jitterAmp + std::cos(tms * 0.9f) * 0.4f;
+        const float jitterY = std::sin(tms * 1.1f + 3.7f) * (jitterAmp * 0.6f);
+        s_inGridStarfield.draw(renderer, gridX + jitterX, gridY + jitterY, 0.22f, true);
+    }
+
+    // Update and spawn ambient sparkles inside/around the grid
+    // Use the same RNG and timing values used for impact sparks
+    if (!game->isPaused()) {
+        // Spawn rate: ~10 sparks/sec total (adjustable)
+        const float spawnInterval = 0.08f; // seconds
+        s_sparkleSpawnAcc += deltaSeconds;
+        while (s_sparkleSpawnAcc >= spawnInterval) {
+            s_sparkleSpawnAcc -= spawnInterval;
+
+            Sparkle s;
+            // Choose spawn area: near active piece magnet if present, otherwise along top/border
+            bool spawnNearPiece = appliedMagnet && (std::uniform_real_distribution<float>(0.0f,1.0f)(s_impactRng) > 0.35f);
+            float sx = 0.0f, sy = 0.0f;
+            if (spawnNearPiece) {
+                // Use starfield magnet target if set (approx center of active piece)
+                // Random jitter around magnet
+                float jitterX = std::uniform_real_distribution<float>(-finalBlockSize * 1.2f, finalBlockSize * 1.2f)(s_impactRng);
+                float jitterY = std::uniform_real_distribution<float>(-finalBlockSize * 1.2f, finalBlockSize * 1.2f)(s_impactRng);
+                // s_inGridStarfield stores magnet in local coords when used; approximate from magnet calculations above
+                // We'll center near grid center if magnet not available
+                sx = std::clamp(GRID_W * 0.5f + jitterX, -finalBlockSize * 2.0f, GRID_W + finalBlockSize * 2.0f);
+                sy = std::clamp(GRID_H * 0.4f + jitterY, -finalBlockSize * 2.0f, GRID_H + finalBlockSize * 2.0f);
+            } else {
+                // Spawn along border: choose side and position
+                float side = std::uniform_real_distribution<float>(0.0f, 1.0f)(s_impactRng);
+                // Border band width (how far outside the grid sparks can appear)
+                const float borderBand = std::max(12.0f, finalBlockSize * 1.0f);
+                if (side < 0.2f) { // left (outside)
+                    sx = std::uniform_real_distribution<float>(-borderBand, 0.0f)(s_impactRng);
+                    sy = std::uniform_real_distribution<float>(-borderBand, GRID_H + borderBand)(s_impactRng);
+                } else if (side < 0.4f) { // right (outside)
+                    sx = std::uniform_real_distribution<float>(GRID_W, GRID_W + borderBand)(s_impactRng);
+                    sy = std::uniform_real_distribution<float>(-borderBand, GRID_H + borderBand)(s_impactRng);
+                } else if (side < 0.6f) { // top (outside)
+                    sx = std::uniform_real_distribution<float>(-borderBand, GRID_W + borderBand)(s_impactRng);
+                    sy = std::uniform_real_distribution<float>(-borderBand, 0.0f)(s_impactRng);
+                } else if (side < 0.9f) { // top/inside border area
+                    sx = std::uniform_real_distribution<float>(0.0f, GRID_W)(s_impactRng);
+                    sy = std::uniform_real_distribution<float>(0.0f, finalBlockSize * 2.0f)(s_impactRng);
+                } else { // bottom (outside)
+                    sx = std::uniform_real_distribution<float>(-borderBand, GRID_W + borderBand)(s_impactRng);
+                    sy = std::uniform_real_distribution<float>(GRID_H, GRID_H + borderBand)(s_impactRng);
+                }
+            }
+
+            s.x = sx;
+            s.y = sy;
+            float speed = std::uniform_real_distribution<float>(10.0f, 60.0f)(s_impactRng);
+            float ang = std::uniform_real_distribution<float>(-3.14159f, 3.14159f)(s_impactRng);
+            s.vx = std::cos(ang) * speed;
+            s.vy = std::sin(ang) * speed * 0.25f; // slower vertical movement
+            s.maxLifeMs = std::uniform_real_distribution<float>(350.0f, 900.0f)(s_impactRng);
+            s.lifeMs = s.maxLifeMs;
+            s.size = std::uniform_real_distribution<float>(1.5f, 5.0f)(s_impactRng);
+            // Soft color range towards warm/cyan tints
+            if (std::uniform_real_distribution<float>(0.0f,1.0f)(s_impactRng) < 0.5f) {
+                s.color = SDL_Color{255, 230, 180, 255};
+            } else {
+                s.color = SDL_Color{180, 220, 255, 255};
+            }
+            s.pulse = std::uniform_real_distribution<float>(0.0f, 6.28f)(s_impactRng);
+
+            s_sparkles.push_back(s);
+        }
+    }
+
+    // Update and draw sparkles
+    if (!s_sparkles.empty()) {
+        auto it = s_sparkles.begin();
+        while (it != s_sparkles.end()) {
+            Sparkle &sp = *it;
+            sp.lifeMs -= sparkDeltaMs;
+            if (sp.lifeMs <= 0.0f) {
+                // On expiration, spawn a small burst of ImpactSparks (smaller boxes)
+                const int burstCount = std::uniform_int_distribution<int>(4, 8)(s_impactRng);
+                for (int bi = 0; bi < burstCount; ++bi) {
+                    ImpactSpark ps;
+                    // Position in absolute coords (same space as other impact sparks)
+                    ps.x = gridX + sp.x + std::uniform_real_distribution<float>(-2.0f, 2.0f)(s_impactRng);
+                    ps.y = gridY + sp.y + std::uniform_real_distribution<float>(-2.0f, 2.0f)(s_impactRng);
+                    float ang = std::uniform_real_distribution<float>(0.0f, 6.2831853f)(s_impactRng);
+                    float speed = std::uniform_real_distribution<float>(10.0f, 120.0f)(s_impactRng);
+                    ps.vx = std::cos(ang) * speed;
+                    ps.vy = std::sin(ang) * speed * 0.8f;
+                    ps.maxLifeMs = std::uniform_real_distribution<float>(220.0f, 500.0f)(s_impactRng);
+                    ps.lifeMs = ps.maxLifeMs;
+                    ps.size = std::max(1.0f, sp.size * 0.5f);
+                    ps.color = sp.color;
+                    s_impactSparks.push_back(ps);
+                }
+
+                it = s_sparkles.erase(it);
+                continue;
+            }
+            float lifeRatio = sp.lifeMs / sp.maxLifeMs;
+            // simple motion
+            sp.x += sp.vx * deltaSeconds;
+            sp.y += sp.vy * deltaSeconds;
+            sp.vy *= 0.995f; // slight damping
+            sp.pulse += deltaSeconds * 8.0f;
+
+            // Fade and pulse alpha
+            float pulse = 0.5f + 0.5f * std::sin(sp.pulse);
+            Uint8 alpha = static_cast<Uint8>(std::clamp(lifeRatio * pulse, 0.0f, 1.0f) * 255.0f);
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+            SDL_SetRenderDrawColor(renderer, sp.color.r, sp.color.g, sp.color.b, alpha);
+            float half = sp.size * 0.5f;
+            SDL_FRect fr{gridX + sp.x - half, gridY + sp.y - half, sp.size, sp.size};
+            SDL_RenderFillRect(renderer, &fr);
+
+            ++it;
+        }
+    }
+
+    SDL_SetRenderDrawBlendMode(renderer, oldBlend);
+
+    renderNextPanel(renderer, pixelFont, blocksTex, nextPanelTex, game->next(), NEXT_PANEL_X, NEXT_PANEL_Y, NEXT_PANEL_WIDTH, NEXT_PANEL_HEIGHT, finalBlockSize);
+
+    // Draw a small filled connector to visually merge NEXT panel and grid border
+    // If an external NEXT panel texture is used, skip the connector to avoid
+    // drawing a visible seam under the image/artwork.
+    if (!nextPanelTex) {
+        SDL_SetRenderDrawColor(renderer, 60, 80, 160, 255); // same as grid border
+        float connectorY = NEXT_PANEL_Y + NEXT_PANEL_HEIGHT; // bottom of next panel (near grid top)
+        SDL_FRect connRect{ NEXT_PANEL_X, connectorY - 1.0f, NEXT_PANEL_WIDTH, 2.0f };
+        SDL_RenderFillRect(renderer, &connRect);
+    }
+
+    // Draw transport effect if active (renders the moving piece and trail)
+    updateAndDrawTransport(renderer, blocksTex);
+    
+    // Precompute row drop offsets (line collapse effect)
+    std::array<float, Game::ROWS> rowDropOffsets{};
+    for (int y = 0; y < Game::ROWS; ++y) {
+        rowDropOffsets[y] = (lineEffect ? lineEffect->getRowDropOffset(y) : 0.0f);
+    }
+
+    // Spawn glamour bursts for freshly destroyed asteroids
+    if (game) {
+        const auto& bursts = game->getRecentAsteroidExplosions();
+        if (!bursts.empty()) {
+            std::uniform_real_distribution<float> lifeDist(280.0f, 420.0f);
+            std::uniform_real_distribution<float> radiusDist(finalBlockSize * 0.35f, finalBlockSize * 0.7f);
+            std::uniform_real_distribution<float> spinDist(-4.0f, 4.0f);
+            std::uniform_real_distribution<float> shardLife(240.0f, 520.0f);
+            std::uniform_real_distribution<float> shardVX(-0.16f, 0.16f);
+            std::uniform_real_distribution<float> shardVY(-0.22f, -0.06f);
+            std::uniform_real_distribution<float> shardSize(finalBlockSize * 0.06f, finalBlockSize * 0.12f);
+            for (const auto& p : bursts) {
+                if (p.x < 0 || p.x >= Game::COLS || p.y < 0 || p.y >= Game::ROWS) {
+                    continue;
+                }
+                float fx = gridX + (static_cast<float>(p.x) + 0.5f) * finalBlockSize;
+                float fy = gridY + (static_cast<float>(p.y) + 0.5f) * finalBlockSize + rowDropOffsets[p.y];
+
+                SDL_Color palette[3] = {
+                    SDL_Color{255, 230, 120, 255},
+                    SDL_Color{140, 220, 255, 255},
+                    SDL_Color{255, 160, 235, 255}
+                };
+                SDL_Color c = palette[s_impactRng() % 3];
+                AsteroidBurst burst{
+                    fx,
+                    fy,
+                    lifeDist(s_impactRng),
+                    0.0f,
+                    radiusDist(s_impactRng),
+                    c,
+                    spinDist(s_impactRng)
+                };
+                burst.maxLifeMs = burst.lifeMs;
+                s_asteroidBursts.push_back(burst);
+
+                // Spawn shards for extra sparkle
+                int shardCount = 10 + (s_impactRng() % 8);
+                for (int i = 0; i < shardCount; ++i) {
+                    AsteroidShard shard{
+                        fx,
+                        fy,
+                        shardVX(s_impactRng),
+                        shardVY(s_impactRng),
+                        shardLife(s_impactRng),
+                        0.0f,
+                        shardSize(s_impactRng),
+                        c
+                    };
+                    shard.maxLifeMs = shard.lifeMs;
+                    s_asteroidShards.push_back(shard);
+                }
+            }
+            game->clearRecentAsteroidExplosions();
+        }
+    }
+
+    // Draw the game board
+    const auto &board = game->boardRef();
+    const auto &asteroidCells = game->asteroidCells();
+    const bool challengeMode = game->getMode() == GameMode::Challenge;
+    float impactStrength = 0.0f;
+    float impactEased = 0.0f;
+    std::array<uint8_t, Game::COLS * Game::ROWS> impactMask{};
+    std::array<float, Game::COLS * Game::ROWS> impactWeight{};
+    if (game->hasHardDropShake()) {
+        impactStrength = static_cast<float>(game->hardDropShakeStrength());
+        impactStrength = std::clamp(impactStrength, 0.0f, 1.0f);
+        impactEased = impactStrength * impactStrength;
+        const auto& impactCells = game->getHardDropCells();
+        for (const auto& cell : impactCells) {
+            if (cell.x < 0 || cell.x >= Game::COLS || cell.y < 0 || cell.y >= Game::ROWS) {
+                continue;
+            }
+            int idx = cell.y * Game::COLS + cell.x;
+            impactMask[idx] = 1;
+            impactWeight[idx] = 1.0f;
+
+            int depth = 0;
+            for (int ny = cell.y + 1; ny < Game::ROWS && depth < 4; ++ny) {
+                if (board[ny * Game::COLS + cell.x] == 0) {
+                    break;
+                }
+                ++depth;
+                int nidx = ny * Game::COLS + cell.x;
+                impactMask[nidx] = 1;
+                float weight = std::max(0.15f, 1.0f - depth * 0.35f);
+                impactWeight[nidx] = std::max(impactWeight[nidx], weight);
+            }
+        }
+    }
+
+    bool shouldSpawnCrackles = game->hasHardDropShake() && !game->getHardDropCells().empty() && game->getHardDropFxId() != s_lastImpactFxId;
+    if (shouldSpawnCrackles) {
+        s_lastImpactFxId = game->getHardDropFxId();
+        std::uniform_real_distribution<float> jitter(-finalBlockSize * 0.2f, finalBlockSize * 0.2f);
+        std::uniform_real_distribution<float> velX(-0.04f, 0.04f);
+        std::uniform_real_distribution<float> velY(0.035f, 0.07f);
+        std::uniform_real_distribution<float> lifespan(210.0f, 320.0f);
+        std::uniform_real_distribution<float> sizeDist(finalBlockSize * 0.08f, finalBlockSize * 0.14f);
+
+        const auto& impactCells = game->getHardDropCells();
+        for (const auto& cell : impactCells) {
+            if (cell.x < 0 || cell.x >= Game::COLS || cell.y < 0 || cell.y >= Game::ROWS) {
+                continue;
+            }
+            int idx = cell.y * Game::COLS + cell.x;
+            int v = (cell.y >= 0) ? board[idx] : 0;
+            SDL_Color baseColor = (v > 0 && v < PIECE_COUNT + 1) ? COLORS[v] : SDL_Color{255, 220, 180, 255};
+            float cellX = gridX + (cell.x + 0.5f) * finalBlockSize;
+            float cellY = gridY + (cell.y + 0.85f) * finalBlockSize + rowDropOffsets[cell.y];
+            for (int i = 0; i < 4; ++i) {
+                ImpactSpark spark;
+                spark.x = cellX + jitter(s_impactRng);
+                spark.y = cellY + jitter(s_impactRng) * 0.25f;
+                spark.vx = velX(s_impactRng);
+                spark.vy = velY(s_impactRng);
+                spark.lifeMs = lifespan(s_impactRng);
+                spark.maxLifeMs = spark.lifeMs;
+                spark.size = sizeDist(s_impactRng);
+                spark.color = SDL_Color{
+                    static_cast<Uint8>(std::min(255, baseColor.r + 30)),
+                    static_cast<Uint8>(std::min(255, baseColor.g + 30)),
+                    static_cast<Uint8>(std::min(255, baseColor.b + 30)),
+                    255
+                };
+                s_impactSparks.push_back(spark);
+            }
+        }
+    }
+
+    std::array<float, Game::COLS * Game::ROWS> challengeClearMask{};
+    const bool challengeClearActive = challengeClearFxActive && challengeClearFxOrder && !challengeClearFxOrder->empty() && challengeClearFxDurationMs > 0.0;
+    if (challengeClearActive) {
+        const double totalDuration = std::max(50.0, challengeClearFxDurationMs);
+        const double perCell = totalDuration / static_cast<double>(challengeClearFxOrder->size());
+        for (size_t i = 0; i < challengeClearFxOrder->size(); ++i) {
+            int idx = (*challengeClearFxOrder)[i];
+            if (idx < 0 || idx >= static_cast<int>(challengeClearMask.size())) {
+                continue;
+            }
+            double startMs = perCell * static_cast<double>(i);
+            double local = (challengeClearFxElapsedMs - startMs) / perCell;
+            float progress = static_cast<float>(std::clamp(local, 0.0, 1.0));
+            if (progress > 0.0f) {
+                challengeClearMask[idx] = progress;
+            }
+        }
+    }
+
+    for (int y = 0; y < Game::ROWS; ++y) {
+        float dropOffset = rowDropOffsets[y];
+        for (int x = 0; x < Game::COLS; ++x) {
+            int v = board[y * Game::COLS + x];
+            if (v > 0) {
+                float bx = gridX + x * finalBlockSize;
+                float by = gridY + y * finalBlockSize + dropOffset;
+                const int cellIdx = y * Game::COLS + x;
+                float weight = impactWeight[cellIdx];
+                if (impactStrength > 0.0f && weight > 0.0f && impactMask[cellIdx]) {
+                    float cellSeed = static_cast<float>((x * 37 + y * 61) % 113);
+                    float t = static_cast<float>(nowTicks % 10000) * 0.018f + cellSeed;
+                    float amplitude = 6.0f * impactEased * weight;
+                    float freq = 2.0f + weight * 1.3f;
+                    bx += amplitude * std::sin(t * freq);
+                    by += amplitude * 0.75f * std::cos(t * (freq + 1.1f));
+                }
+
+                float clearProgress = challengeClearMask[cellIdx];
+                float clearAlpha = 1.0f;
+                float clearScale = 1.0f;
+                if (clearProgress > 0.0f) {
+                    float eased = smoothstep(clearProgress);
+                    clearAlpha = std::max(0.0f, 1.0f - eased);
+                    clearScale = 1.0f + 0.35f * eased;
+                    float offset = (finalBlockSize - finalBlockSize * clearScale) * 0.5f;
+                    bx += offset;
+                    by += offset;
+                    float jitter = eased * 2.0f;
+                    bx += std::sin(static_cast<float>(cellIdx) * 3.1f) * jitter;
+                    by += std::cos(static_cast<float>(cellIdx) * 2.3f) * jitter * 0.6f;
+                }
+
+                bool isAsteroid = challengeMode && asteroidCells[cellIdx].has_value();
+                if (isAsteroid) {
+                    const AsteroidCell& cell = *asteroidCells[cellIdx];
+                    float spawnScale = 1.0f;
+                    float spawnAlpha = 1.0f;
+                    if (countdownActive) {
+                        // Staggered pop-in while counting: start oversized, fade to 1.0 with ease
+                        const float t = static_cast<float>(SDL_GetTicks() & 2047) * 0.0015f; // ~0..3s loop
+                        float phase = std::fmod(t + (float(cellIdx % 11) * 0.12f), 1.6f);
+                        float pulse = std::clamp(phase / 1.2f, 0.0f, 1.0f);
+                        float eased = smoothstep(pulse);
+                        spawnScale = 1.35f - 0.35f * eased; // big -> normal
+                        spawnAlpha = 0.25f + 0.75f * eased; // fade in
+                    }
+
+                    if (asteroidsTex && spawnAlpha < 1.0f) {
+                        SDL_SetTextureAlphaMod(asteroidsTex, static_cast<Uint8>(std::clamp(spawnAlpha, 0.0f, 1.0f) * 255.0f));
+                    }
+
+                    float size = finalBlockSize * spawnScale * clearScale;
+                    float offset = (finalBlockSize - size) * 0.5f;
+                    if (asteroidsTex && clearAlpha < 1.0f) {
+                        Uint8 alpha = static_cast<Uint8>(std::clamp(spawnAlpha * clearAlpha, 0.0f, 1.0f) * 255.0f);
+                        SDL_SetTextureAlphaMod(asteroidsTex, alpha);
+                    }
+                    drawAsteroid(renderer, asteroidsTex, bx + offset, by + offset, size, cell);
+
+                    if (asteroidsTex && (spawnAlpha < 1.0f || clearAlpha < 1.0f)) {
+                        SDL_SetTextureAlphaMod(asteroidsTex, 255);
+                    }
+                } else {
+                    if (blocksTex && clearAlpha < 1.0f) {
+                        SDL_SetTextureAlphaMod(blocksTex, static_cast<Uint8>(std::clamp(clearAlpha, 0.0f, 1.0f) * 255.0f));
+                    }
+                    drawBlockTexture(renderer, blocksTex, bx, by, finalBlockSize * clearScale, v - 1);
+                    if (blocksTex && clearAlpha < 1.0f) {
+                        SDL_SetTextureAlphaMod(blocksTex, 255);
+                    }
+                }
+            }
+        }
+    }
+
+    // Update & draw asteroid glamour shards and bursts
+    if (!s_asteroidShards.empty() || !s_asteroidBursts.empty()) {
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_ADD);
+
+        // Shards
+        auto shardIt = s_asteroidShards.begin();
+        while (shardIt != s_asteroidShards.end()) {
+            AsteroidShard& s = *shardIt;
+            s.lifeMs -= sparkDeltaMs;
+            if (s.lifeMs <= 0.0f) {
+                shardIt = s_asteroidShards.erase(shardIt);
+                continue;
+            }
+            s.vy += 0.0007f * sparkDeltaMs;
+            s.x += s.vx * sparkDeltaMs;
+            s.y += s.vy * sparkDeltaMs;
+            float lifeRatio = std::clamp(static_cast<float>(s.lifeMs / s.maxLifeMs), 0.0f, 1.0f);
+            Uint8 alpha = static_cast<Uint8>(lifeRatio * 200.0f);
+            SDL_SetRenderDrawColor(renderer, s.color.r, s.color.g, s.color.b, alpha);
+            float size = s.size * (0.7f + (1.0f - lifeRatio) * 0.8f);
+            SDL_FRect shardRect{
+                s.x - size * 0.5f,
+                s.y - size * 0.5f,
+                size,
+                size * 1.4f
+            };
+            SDL_RenderFillRect(renderer, &shardRect);
+            ++shardIt;
+        }
+
+        // Bursts
+        auto it = s_asteroidBursts.begin();
+        while (it != s_asteroidBursts.end()) {
+            AsteroidBurst& b = *it;
+            b.lifeMs -= sparkDeltaMs;
+            if (b.lifeMs <= 0.0f) {
+                it = s_asteroidBursts.erase(it);
+                continue;
+            }
+            float t = 1.0f - static_cast<float>(b.lifeMs / b.maxLifeMs);
+            float alpha = std::clamp(1.0f - t, 0.0f, 1.0f);
+            float radius = b.baseRadius * (1.0f + t * 1.6f);
+            float thickness = std::max(2.0f, radius * 0.25f);
+            float jitter = std::sin(t * 12.0f + b.spin) * 2.0f;
+
+            SDL_Color c = b.color;
+            Uint8 a = static_cast<Uint8>(alpha * 220.0f);
+            SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, a);
+            SDL_FRect outer{
+                b.x - radius + jitter,
+                b.y - radius + jitter,
+                radius * 2.0f,
+                radius * 2.0f
+            };
+            SDL_RenderRect(renderer, &outer);
+
+            SDL_FRect inner{
+                b.x - (radius - thickness),
+                b.y - (radius - thickness),
+                (radius - thickness) * 2.0f,
+                (radius - thickness) * 2.0f
+            };
+            SDL_SetRenderDrawColor(renderer, 255, 255, 255, static_cast<Uint8>(a * 0.9f));
+            SDL_RenderRect(renderer, &inner);
+            ++it;
+        }
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+    }
+
+    if (!s_impactSparks.empty()) {
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+        auto it = s_impactSparks.begin();
+        while (it != s_impactSparks.end()) {
+            ImpactSpark& spark = *it;
+            spark.vy += 0.00045f * sparkDeltaMs;
+            spark.x += spark.vx * sparkDeltaMs;
+            spark.y += spark.vy * sparkDeltaMs;
+            spark.lifeMs -= sparkDeltaMs;
+            if (spark.lifeMs <= 0.0f) {
+                it = s_impactSparks.erase(it);
+                continue;
+            }
+            float lifeRatio = spark.lifeMs / spark.maxLifeMs;
+            Uint8 alpha = static_cast<Uint8>(std::clamp(lifeRatio, 0.0f, 1.0f) * 160.0f);
+            SDL_SetRenderDrawColor(renderer, spark.color.r, spark.color.g, spark.color.b, alpha);
+            SDL_FRect sparkRect{
+                spark.x - spark.size * 0.5f,
+                spark.y - spark.size * 0.5f,
+                spark.size,
+                spark.size * 1.4f
+            };
+            SDL_RenderFillRect(renderer, &sparkRect);
+            ++it;
+        }
+    }
+    
+    bool allowActivePieceRender = !GameRenderer::isTransportActive() && !challengeClearActive;
+    const bool smoothScrollEnabled = Settings::instance().isSmoothScrollEnabled();
+
+    float activePiecePixelOffsetX = 0.0f;
+    if (allowActivePieceRender) {
+        if (smoothScrollEnabled && !game->isPaused()) {
+            const uint64_t pieceSeq = game->getCurrentPieceSequence();
+            if (!s_activePieceSmooth.initialized || s_activePieceSmooth.sequence != pieceSeq) {
+                s_activePieceSmooth.sequence = pieceSeq;
+                s_activePieceSmooth.visualX = static_cast<float>(game->current().x);
+                s_activePieceSmooth.initialized = true;
+            }
+
+            const float targetX = static_cast<float>(game->current().x);
+            constexpr float HORIZONTAL_SMOOTH_MS = 55.0f;
+            const float lerpFactor = std::clamp(sparkDeltaMs / HORIZONTAL_SMOOTH_MS, 0.0f, 1.0f);
+            s_activePieceSmooth.visualX = std::lerp(s_activePieceSmooth.visualX, targetX, lerpFactor);
+            activePiecePixelOffsetX = (s_activePieceSmooth.visualX - targetX) * finalBlockSize;
+        } else {
+            s_activePieceSmooth.sequence = game->getCurrentPieceSequence();
+            s_activePieceSmooth.visualX = static_cast<float>(game->current().x);
+            s_activePieceSmooth.initialized = true;
+        }
+    }
+
+    auto computeFallOffset = [&]() -> float {
+        if (game->isPaused()) {
+            return 0.0f;
+        }
+        double gravityMs = game->getGravityMs();
+        if (gravityMs <= 0.0) {
+            return 0.0f;
+        }
+        double effectiveMs = game->isSoftDropping() ? std::max(5.0, gravityMs / 5.0) : gravityMs;
+        double accumulator = std::clamp(game->getFallAccumulator(), 0.0, effectiveMs);
+        if (effectiveMs <= 0.0) {
+            return 0.0f;
+        }
+        float progress = static_cast<float>(accumulator / effectiveMs);
+        progress = std::clamp(progress, 0.0f, 1.0f);
+        return progress * finalBlockSize;
+    };
+
+    float activePiecePixelOffsetY = (!game->isPaused() && smoothScrollEnabled) ? computeFallOffset() : 0.0f;
+    if (activePiecePixelOffsetY > 0.0f) {
+        const auto& boardRef = game->boardRef();
+        const Game::Piece& piece = game->current();
+        float maxAllowed = finalBlockSize;
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!Game::cellFilled(piece, cx, cy)) {
+                    continue;
+                }
+                int gx = piece.x + cx;
+                int gy = piece.y + cy;
+                if (gx < 0 || gx >= Game::COLS) {
+                    continue;
+                }
+                int testY = gy + 1;
+                int emptyRows = 0;
+                if (testY < 0) {
+                    emptyRows -= testY; // number of rows until we reach row 0
+                    testY = 0;
+                }
+                while (testY >= 0 && testY < Game::ROWS) {
+                    if (boardRef[testY * Game::COLS + gx] != 0) {
+                        break;
+                    }
+                    ++emptyRows;
+                    ++testY;
+                }
+                float cellLimit = (emptyRows > 0) ? finalBlockSize : 0.0f;
+                maxAllowed = std::min(maxAllowed, cellLimit);
+            }
+        }
+        activePiecePixelOffsetY = std::min(activePiecePixelOffsetY, maxAllowed);
+    }
+
+    // Debug: log single-player smoothing/fall values when enabled
+    if (Settings::instance().isDebugEnabled()) {
+        float sp_targetX = static_cast<float>(game->current().x);
+        double sp_gravityMs = game->getGravityMs();
+        double sp_fallAcc = game->getFallAccumulator();
+        int sp_soft = game->isSoftDropping() ? 1 : 0;
+        /*
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "SP OFFSETS: seq=%llu visX=%.3f targX=%.3f offX=%.2f offY=%.2f gravMs=%.2f fallAcc=%.2f soft=%d",
+            (unsigned long long)s_activePieceSmooth.sequence,
+            s_activePieceSmooth.visualX,
+            sp_targetX,
+            activePiecePixelOffsetX,
+            activePiecePixelOffsetY,
+            sp_gravityMs,
+            sp_fallAcc,
+            sp_soft
+        );
+        */
+    }
+
+    // Draw ghost piece (where current piece will land)
+    if (allowActivePieceRender) {
+        Game::Piece ghostPiece = game->current();
+        // Find landing position
+        while (true) {
+            Game::Piece testPiece = ghostPiece;
+            testPiece.y++;
+            bool collision = false;
+            
+            // Simple collision check
+            for (int cy = 0; cy < 4; ++cy) {
+                for (int cx = 0; cx < 4; ++cx) {
+                    if (Game::cellFilled(testPiece, cx, cy)) {
+                        int gx = testPiece.x + cx;
+                        int gy = testPiece.y + cy;
+                        if (gy >= Game::ROWS || gx < 0 || gx >= Game::COLS || 
+                            (gy >= 0 && board[gy * Game::COLS + gx] != 0)) {
+                            collision = true;
+                            break;
+                        }
+                    }
+                }
+                if (collision) break;
+            }
+            
+            if (collision) break;
+            ghostPiece = testPiece;
+        }
+        
+        // Draw ghost piece
+        drawPiece(renderer, blocksTex, ghostPiece, gridX, gridY, finalBlockSize, true);
+    }
+    
+    // Draw the falling piece
+    if (allowActivePieceRender) {
+        drawPiece(renderer, blocksTex, game->current(), gridX, gridY, finalBlockSize, false, activePiecePixelOffsetX, activePiecePixelOffsetY);
+    }
+    
+    // Draw line clearing effects
+    if (lineEffect && lineEffect->isActive()) {
+        lineEffect->render(renderer, blocksTex, static_cast<int>(gridX), static_cast<int>(gridY), static_cast<int>(finalBlockSize));
+    }
+    
+    // Draw block statistics (left panel) -> STATISTICS console
+    const auto& blockCounts = game->getBlockCounts();
+    int totalBlocks = 0;
+    for (int i = 0; i < PIECE_COUNT; ++i) totalBlocks += blockCounts[i];
+
+    // Header (slightly smaller)
+    const SDL_Color headerColor{255, 220, 0, 255};
+    const SDL_Color textColor{200, 220, 235, 200};
+    const SDL_Color mutedColor{150, 180, 200, 180};
+    // Small vertical shift to push text further into the statistics panel
+    // Increased from 20 to 80 to move text down by ~60px more (within 50-100px range)
+    const float statsTextShift = 80.0f;
+    pixelFont->draw(renderer, statsX + 12.0f, statsY + 8.0f + statsTextShift, "STATISTICS", 0.70f, headerColor);
+
+    // Tighter spacing and smaller icons/text for compact analytics console
+    float yCursor = statsY + 34.0f + statsTextShift;
+    const float leftPad = 2.0f;
+    const float rightPad = 14.0f;
+    // Horizontal shift to nudge the count/percent group closer to the right edge
+    const float statsNumbersShift = 20.0f;
+    // Horizontal shift to move the progress bar slightly left
+    const float statsBarShift = -10.0f;
+    // Increase row gap to avoid icon overlap on smaller scales (bumped up)
+    const float rowGap = 28.0f;
+    const float barHeight = 2.0f;
+
+    // Text scales for per-row numbers (slightly larger than before)
+    const float countScale = 0.60f;
+    const float percScale = 0.60f;
+
+    // Determine max percent to highlight top used piece
+    int maxPerc = 0;
+    for (int i = 0; i < PIECE_COUNT; ++i) {
+        int perc = (totalBlocks > 0) ? int(std::round(100.0 * double(blockCounts[i]) / double(totalBlocks))) : 0;
+        if (perc > maxPerc) maxPerc = perc;
+    }
+
+    // Row order groups: first 4, then last 3
+    std::vector<int> order = {0,1,2,3, 4,5,6};
+    // Precompute max widths for counts/perc so right-alignment is stable
+    int maxCountW = 0, maxCountH = 0;
+    int maxPercW = 0, maxPercH = 0;
+    for (int oi : order) {
+        char tmpCount[16]; snprintf(tmpCount, sizeof(tmpCount), "%dx", blockCounts[oi]);
+        char tmpPerc[16]; int tmpPercVal = (totalBlocks > 0) ? int(std::round(100.0 * double(blockCounts[oi]) / double(totalBlocks))) : 0; snprintf(tmpPerc, sizeof(tmpPerc), "%d%%", tmpPercVal);
+        pixelFont->measure(tmpCount, countScale, maxCountW, maxCountH);
+        int pw=0, ph=0; pixelFont->measure(tmpPerc, percScale, pw, ph);
+        maxPercW = std::max(maxPercW, pw);
+        maxPercH = std::max(maxPercH, ph);
+    }
+
+    for (size_t idx = 0; idx < order.size(); ++idx) {
+        int i = order[idx];
+
+        float rowLeft = statsX + leftPad;
+        float rowRight = statsX + statsW - rightPad;
+
+        // Icon aligned left, slightly higher to match reference spacing
+        float iconSize = finalBlockSize * 0.52f;
+        float iconBgPad = 6.0f;
+        float iconBgX = rowLeft - 18.0f;
+        float iconBgY = yCursor - 10.0f;
+
+        // Measure right-side text first so we can vertically align icon with text
+        int count = blockCounts[i];
+        char countStr[16]; snprintf(countStr, sizeof(countStr), "%dx", count);
+        int perc = (totalBlocks > 0) ? int(std::round(100.0 * double(count) / double(totalBlocks))) : 0;
+        char percStr[16]; snprintf(percStr, sizeof(percStr), "%d%%", perc);
+
+        int countW = maxCountW, countH = maxCountH;
+        int percW = maxPercW, percH = maxPercH;
+
+        float iconX = iconBgX + iconBgPad;
+        float iconY = yCursor - 6.0f + ((float)countH - iconSize) * 0.5f;
+        drawSmallPiece(renderer, blocksTex, static_cast<PieceType>(i), iconX, iconY, iconSize);
+
+        // Badge for counts/percent with no background, aligned to the right
+        const float numbersGap = 14.0f;
+        const float numbersPadX = 10.0f;
+        const float numbersPadY = 6.0f;
+        int maxTextH = std::max(countH, percH);
+        float numbersW = numbersPadX * 2.0f + countW + numbersGap + percW;
+        float numbersH = numbersPadY * 2.0f + static_cast<float>(maxTextH);
+        float numbersX = rowRight - numbersW + statsNumbersShift;
+        float numbersY = yCursor - (numbersH - static_cast<float>(maxTextH)) * 0.5f;
+
+        float textY = numbersY + (numbersH - static_cast<float>(maxTextH)) * 0.5f;
+        // Right-align the numbers block: perc anchored to the right, count right-aligned to the perc with gap
+        float percX = numbersX + numbersW - percW - numbersPadX;
+        float countX = percX - numbersGap - countW;
+        pixelFont->draw(renderer, countX, textY, countStr, countScale, textColor);
+        pixelFont->draw(renderer, percX, textY, percStr, percScale, mutedColor);
+
+        // Progress bar anchored to the numbers width
+        float barX = numbersX + statsBarShift;
+        float barW = numbersW;
+        float barY = numbersY + numbersH + 8.0f;
+
+        SDL_SetRenderDrawColor(renderer, 24, 80, 120, 220);
+        SDL_FRect track{barX, barY, barW, barHeight};
+        SDL_RenderFillRect(renderer, &track);
+
+        // Fill color brightness based on usage and highlight for top piece
+        float strength = (totalBlocks > 0) ? (float(blockCounts[i]) / float(totalBlocks)) : 0.0f;
+        SDL_Color baseC = {60, 200, 255, 255};
+        SDL_Color dimC = {40, 120, 160, 255};
+        SDL_Color fillC = (perc == maxPerc) ? SDL_Color{100, 230, 255, 255} : SDL_Color{
+            static_cast<Uint8>(std::lerp((float)dimC.r, (float)baseC.r, strength)),
+            static_cast<Uint8>(std::lerp((float)dimC.g, (float)baseC.g, strength)),
+            static_cast<Uint8>(std::lerp((float)dimC.b, (float)baseC.b, strength)),
+            255
+        };
+
+        float fillW = barW * std::clamp(strength, 0.0f, 1.0f);
+        SDL_SetRenderDrawColor(renderer, fillC.r, fillC.g, fillC.b, fillC.a);
+        SDL_FRect fill{barX, barY, fillW, barHeight};
+        SDL_RenderFillRect(renderer, &fill);
+
+        // Advance cursor to next row: after bar + gap (leave more space between blocks)
+        yCursor = barY + barHeight + rowGap + 6.0f;
+    }
+
+    // Bottom summary stats: prefer to place summary right after last row
+    // but clamp it so it never goes below the reserved bottom area.
+    float preferredSummaryY = yCursor + 24.0f; // space below last row
+    float maxSummaryY = statsY + statsH - 90.0f; // original lower bound
+    float summaryY = std::min(preferredSummaryY, maxSummaryY);
+    const SDL_Color summaryValueColor{220, 235, 250, 255};
+    const SDL_Color labelMuted{160, 180, 200, 200};
+
+    char totalStr[32]; snprintf(totalStr, sizeof(totalStr), "%d", totalBlocks);
+    char tetrisesStr[32]; snprintf(tetrisesStr, sizeof(tetrisesStr), "%d", game->tetrisesMade());
+    char maxComboStr[32]; snprintf(maxComboStr, sizeof(maxComboStr), "%d", game->comboCount());
+
+    // Use slightly smaller labels/values to match the compact look
+    const float labelX = statsX + 8.0f; // move labels more left
+    const float valueRightPad = 12.0f; // pad from right edge
+
+    int valW=0, valH=0;
+    pixelFont->measure(totalStr, 0.55f, valW, valH);
+    float totalX = statsX + statsW - valueRightPad - (float)valW;
+    pixelFont->draw(renderer, labelX, summaryY + 0.0f, "TOTAL PIECES", 0.46f, labelMuted);
+    pixelFont->draw(renderer, totalX, summaryY + 0.0f, totalStr, 0.55f, summaryValueColor);
+
+    pixelFont->measure(tetrisesStr, 0.55f, valW, valH);
+    float tetrisesX = statsX + statsW - valueRightPad - (float)valW;
+    pixelFont->draw(renderer, labelX, summaryY + 22.0f, "TETRISES MADE", 0.46f, labelMuted);
+    pixelFont->draw(renderer, tetrisesX, summaryY + 22.0f, tetrisesStr, 0.55f, summaryValueColor);
+
+    pixelFont->measure(maxComboStr, 0.55f, valW, valH);
+    float comboX = statsX + statsW - valueRightPad - (float)valW;
+    pixelFont->draw(renderer, labelX, summaryY + 44.0f, "COMBOS", 0.46f, labelMuted);
+    pixelFont->draw(renderer, comboX, summaryY + 44.0f, maxComboStr, 0.55f, summaryValueColor);
+    
+    // Draw score panel (right side)
+    const float contentTopOffset = 0.0f;
+    const float contentBottomOffset = 290.0f;
+    const float contentPad = 36.0f;
+    float scoreContentH = (contentBottomOffset - contentTopOffset) + contentPad;
+    float baseY = gridY + (GRID_H - scoreContentH) * 0.5f;
+
+    const float statsPanelGap = 12.0f;
+    const float statsPanelLeft = gridX + GRID_W + statsPanelGap;
+    const float statsPanelPadLeft = 40.0f;
+    const float statsPanelPadRight = 34.0f;
+    const float statsPanelPadY = 28.0f;
+    const float statsTextX = statsPanelLeft + statsPanelPadLeft;
+
+    const SDL_Color labelColor{255, 220, 0, 255};
+    const SDL_Color valueColor{255, 255, 255, 255};
+    const SDL_Color nextColor{80, 255, 120, 255};
+
+    char scoreStr[32];
+    snprintf(scoreStr, sizeof(scoreStr), "%d", game->score());
+
+    char linesStr[16];
+    snprintf(linesStr, sizeof(linesStr), "%03d", game->lines());
+
+    char levelStr[16];
+    snprintf(levelStr, sizeof(levelStr), "%02d", game->level());
+    char challengeLevelStr[16];
+    snprintf(challengeLevelStr, sizeof(challengeLevelStr), "%02d/100", game->challengeLevel());
+    char asteroidStr[32];
+    snprintf(asteroidStr, sizeof(asteroidStr), "%d LEFT", game->asteroidsRemaining());
+
+    // Next level progress (endless only)
+    int startLv = game->startLevelBase();
+    int firstThreshold = (startLv + 1) * 10;
+    int linesDone = game->lines();
+    int nextThreshold = 0;
+    if (linesDone < firstThreshold) {
+        nextThreshold = firstThreshold;
+    } else {
+        int blocksPast = linesDone - firstThreshold;
+        nextThreshold = firstThreshold + ((blocksPast / 10) + 1) * 10;
+    }
+    int linesForNext = std::max(0, nextThreshold - linesDone);
+    char nextStr[32];
+    snprintf(nextStr, sizeof(nextStr), "%d  LINES", linesForNext);
+
+    // Time display
+    int totalSecs = static_cast<int>(game->elapsed());
+    int mins = totalSecs / 60;
+    int secs = totalSecs % 60;
+    char timeStr[16];
+    snprintf(timeStr, sizeof(timeStr), "%02d:%02d", mins, secs);
+
+    const bool debugEnabled = Settings::instance().isDebugEnabled();
+    char gravityStr[32] = "";
+    char dropStr[32] = "";
+    char gravityHud[64] = "";
+    SDL_Color dropColor{100, 255, 100, 255};
+    if (debugEnabled) {
+        double gravityMs = game->getGravityMs();
+        double fallAcc = game->getFallAccumulator();
+        bool isSoftDrop = game->isSoftDropping();
+        double effectiveGravityMs = isSoftDrop ? (gravityMs / 2.0) : gravityMs;
+        double timeUntilDrop = std::max(0.0, effectiveGravityMs - fallAcc);
+
+        snprintf(gravityStr, sizeof(gravityStr), "%.0f ms%s", gravityMs, isSoftDrop ? " (SD)" : "");
+        snprintf(dropStr, sizeof(dropStr), "Drop: %.0f", timeUntilDrop);
+        dropColor = isSoftDrop ? SDL_Color{255, 200, 100, 255} : SDL_Color{100, 255, 100, 255};
+
+        double gfps = gravityMs > 0.0 ? (1000.0 / gravityMs) : 0.0;
+        snprintf(gravityHud, sizeof(gravityHud), "GRAV: %.0f ms (%.2f fps)", gravityMs, gfps);
+    }
+
+    struct StatLine {
+        const char* text;
+        float offsetY;
+        float scale;
+        SDL_Color color;
+    };
+
+    std::vector<StatLine> statLines;
+    statLines.reserve(debugEnabled ? 13 : 10);
+    statLines.push_back({"SCORE", 0.0f, 1.0f, labelColor});
+    statLines.push_back({scoreStr, 25.0f, 0.9f, valueColor});
+    statLines.push_back({"LINES", 70.0f, 1.0f, labelColor});
+    statLines.push_back({linesStr, 95.0f, 0.9f, valueColor});
+
+    if (game->getMode() == GameMode::Challenge) {
+        statLines.push_back({"LEVEL", 140.0f, 1.0f, labelColor});
+        statLines.push_back({challengeLevelStr, 165.0f, 0.9f, valueColor});
+        statLines.push_back({"ASTEROIDS", 200.0f, 1.0f, labelColor});
+        statLines.push_back({asteroidStr, 225.0f, 0.9f, nextColor});
+        statLines.push_back({"TIME", 265.0f, 1.0f, labelColor});
+        statLines.push_back({timeStr, 290.0f, 0.9f, valueColor});
+    } else {
+        statLines.push_back({"LEVEL", 140.0f, 1.0f, labelColor});
+        statLines.push_back({levelStr, 165.0f, 0.9f, valueColor});
+        statLines.push_back({"NEXT LVL", 200.0f, 1.0f, labelColor});
+        statLines.push_back({nextStr, 225.0f, 0.9f, nextColor});
+        statLines.push_back({"TIME", 265.0f, 1.0f, labelColor});
+        statLines.push_back({timeStr, 290.0f, 0.9f, valueColor});
+    }
+
+    if (debugEnabled) {
+        SDL_Color debugLabelColor{150, 150, 150, 255};
+        SDL_Color debugValueColor{180, 180, 180, 255};
+        statLines.push_back({"GRAVITY", 330.0f, 0.8f, debugLabelColor});
+        statLines.push_back({gravityStr, 350.0f, 0.7f, debugValueColor});
+        statLines.push_back({dropStr, 370.0f, 0.7f, dropColor});
+    }
+
+    bool scorePanelMetricsValid = false;
+    float scorePanelTop = 0.0f;
+    float scorePanelLeftX = 0.0f;
+    float scorePanelWidth = 0.0f;
+
+    if (!statLines.empty()) {
+        float statsContentTop = std::numeric_limits<float>::max();
+        float statsContentBottom = std::numeric_limits<float>::lowest();
+        float statsContentMaxWidth = 0.0f;
+
+        for (const auto& line : statLines) {
+            int textW = 0;
+            int textH = 0;
+            pixelFont->measure(line.text, line.scale, textW, textH);
+            float y = baseY + line.offsetY;
+            statsContentTop = std::min(statsContentTop, y);
+            statsContentBottom = std::max(statsContentBottom, y + textH);
+            statsContentMaxWidth = std::max(statsContentMaxWidth, static_cast<float>(textW));
+        }
+
+        float statsPanelWidth = statsPanelPadLeft + statsContentMaxWidth + statsPanelPadRight;
+        float statsPanelHeight = (statsContentBottom - statsContentTop) + statsPanelPadY * 2.0f;
+        float statsPanelTop = statsContentTop - statsPanelPadY;
+
+        SDL_FRect statsBg{statsPanelLeft, statsPanelTop, statsPanelWidth, statsPanelHeight};
+        if (scorePanelTex) {
+            SDL_RenderTexture(renderer, scorePanelTex, nullptr, &statsBg);
+        } else {
+            SDL_SetRenderDrawColor(renderer, 12, 18, 32, 205);
+            SDL_RenderFillRect(renderer, &statsBg);
+        }
+
+        scorePanelMetricsValid = true;
+        scorePanelTop = statsPanelTop;
+        scorePanelLeftX = statsPanelLeft;
+        scorePanelWidth = statsPanelWidth;
+    }
+
+    for (const auto& line : statLines) {
+        pixelFont->draw(renderer, statsTextX, baseY + line.offsetY, line.text, line.scale, line.color);
+    }
+
+    // Challenge story / briefing line near level indicator
+    if (challengeStoryText && !challengeStoryText->empty() && challengeStoryAlpha > 0.0f && game->getMode() == GameMode::Challenge) {
+        float alpha = std::clamp(challengeStoryAlpha, 0.0f, 1.0f);
+        SDL_Color storyColor{160, 220, 255, static_cast<Uint8>(std::lround(210.0f * alpha))};
+        SDL_Color shadowColor{0, 0, 0, static_cast<Uint8>(std::lround(120.0f * alpha))};
+
+        auto drawWrapped = [&](const std::string& text, float x, float y, float maxW, float scale, SDL_Color color) {
+            std::istringstream iss(text);
+            std::string word;
+            std::string line;
+            float cursorY = y;
+            int lastH = 0;
+            while (iss >> word) {
+                std::string candidate = line.empty() ? word : (line + " " + word);
+                int w = 0, h = 0;
+                pixelFont->measure(candidate, scale, w, h);
+                if (w > maxW && !line.empty()) {
+                    pixelFont->draw(renderer, x + 1.0f, cursorY + 1.0f, line, scale, shadowColor);
+                    pixelFont->draw(renderer, x, cursorY, line, scale, color);
+                    cursorY += h + 4.0f;
+                    line = word;
+                    lastH = h;
+                } else {
+                    line = candidate;
+                    lastH = h;
+                }
+            }
+            if (!line.empty()) {
+                pixelFont->draw(renderer, x + 1.0f, cursorY + 1.0f, line, scale, shadowColor);
+                pixelFont->draw(renderer, x, cursorY, line, scale, color);
+                cursorY += lastH + 4.0f;
+            }
+        };
+
+        float storyX = statsTextX;
+        float storyY = baseY + 112.0f;
+        float maxW = 230.0f;
+        if (scorePanelMetricsValid && scorePanelWidth > 40.0f) {
+            storyX = scorePanelLeftX + 14.0f;
+            maxW = std::max(160.0f, scorePanelWidth - 28.0f);
+        }
+
+        drawWrapped(*challengeStoryText, storyX, storyY, maxW, 0.7f, storyColor);
+    }
+
+    if (debugEnabled) {
+        pixelFont->draw(renderer, logicalW - 260, 10, gravityHud, 0.9f, {200, 200, 220, 255});
+    }
+    
+    // Hold panel background & label (always visible). Small preview renders only if a piece is held.
+    {
+        float holdLabelX = statsTextX;
+        float holdY = statsY + statsH - 80.0f;
+        float holdBlockH = (finalBlockSize * 0.6f) * 6.0f;
+        const float holdGap = 18.0f;
+        float panelW = 120.0f;
+        float panelH = holdBlockH + 12.0f;
+        float panelX = holdLabelX + 40.0f;
+        float panelY = holdY - 6.0f;
+
+        if (scorePanelMetricsValid) {
+            // align panel to score panel width and position it above it
+            panelW = scorePanelWidth;
+            panelX = scorePanelLeftX;
+            panelY = scorePanelTop - panelH - holdGap;
+            // choose label X (left edge + padding)
+            holdLabelX = panelX + 10.0f;
+            // label Y inside panel
+            holdY = panelY + 8.0f;
+        }
+
+        if (holdPanelTex) {
+            SDL_FRect panelDst{panelX, panelY, panelW, panelH};
+            SDL_SetTextureBlendMode(holdPanelTex, SDL_BLENDMODE_BLEND);
+            SDL_SetTextureScaleMode(holdPanelTex, SDL_SCALEMODE_LINEAR);
+            SDL_RenderTexture(renderer, holdPanelTex, nullptr, &panelDst);
+        } else {
+            // fallback: draw a dark panel rect so UI is visible even without texture
+            SDL_SetRenderDrawColor(renderer, 12, 18, 32, 220);
+            SDL_FRect panelDst{panelX, panelY, panelW, panelH};
+            SDL_RenderFillRect(renderer, &panelDst);
+        }
+
+        // Display "HOLD" label on right side
+        pixelFont->draw(renderer, holdLabelX + 56.0f, holdY + 4.0f, "HOLD", 1.0f, {255, 220, 0, 255});
+
+        if (game->held().type < PIECE_COUNT) {
+            // Draw small held preview inside the panel (centered)
+            float previewX = panelX + (panelW - (finalBlockSize * 0.6f * 4.0f)) * 0.5f;
+            float previewY = panelY + (panelH - holdBlockH) * 2.5f;
+            drawSmallPiece(renderer, blocksTex, static_cast<PieceType>(game->held().type), previewX, previewY, finalBlockSize * 0.6f);
+        }
+    }
+    
+    // Pause overlay logic moved to renderPauseOverlay
+
+    
+    // Exit popup logic moved to renderExitPopup
+}
+
+void GameRenderer::renderCoopPlayingState(
+    SDL_Renderer* renderer,
+    CoopGame* game,
+    FontAtlas* pixelFont,
+    LineEffect* lineEffect,
+    SDL_Texture* blocksTex,
+    SDL_Texture* statisticsPanelTex,
+    SDL_Texture* scorePanelTex,
+    SDL_Texture* nextPanelTex,
+    SDL_Texture* holdPanelTex,
+    bool paused,
+    float logicalW,
+    float logicalH,
+    float logicalScale,
+    float winW,
+    float winH
+) {
+    if (!renderer || !game || !pixelFont) return;
+
+    static SyncLineRenderer s_syncLine;
+    static bool s_lastHadCompletedLines = false;
+
+    static Uint32 s_lastCoopTick = SDL_GetTicks();
+    Uint32 nowTicks = SDL_GetTicks();
+    float deltaMs = static_cast<float>(nowTicks - s_lastCoopTick);
+    s_lastCoopTick = nowTicks;
+    if (deltaMs < 0.0f || deltaMs > 100.0f) {
+        deltaMs = 16.0f;
+    }
+
+    const float deltaSeconds = std::clamp(deltaMs / 1000.0f, 0.0f, 0.033f);
+    s_syncLine.Update(deltaSeconds);
+
+    const bool smoothScrollEnabled = Settings::instance().isSmoothScrollEnabled();
+    struct SmoothState { bool initialized{false}; uint64_t seq{0}; float visualX{0.0f}; float visualY{0.0f}; };
+    static SmoothState s_leftSmooth{};
+    static SmoothState s_rightSmooth{};
+    struct SpawnFadeState { bool active{false}; uint64_t seq{0}; Uint32 startTick{0}; float durationMs{200.0f}; CoopGame::Piece piece; int spawnY{0}; float targetX{0.0f}; float targetY{0.0f}; float tileSize{0.0f}; };
+    static SpawnFadeState s_leftSpawnFade{};
+    static SpawnFadeState s_rightSpawnFade{};
+
+    // Layout constants (reuse single-player feel but sized for 20 cols)
+    const float MIN_MARGIN = 40.0f;
+    const float TOP_MARGIN = 60.0f;
+    const float PANEL_WIDTH = 180.0f;
+    const float PANEL_SPACING = 30.0f;
+    const float NEXT_PANEL_HEIGHT = 120.0f;
+    const float BOTTOM_MARGIN = 60.0f;
+
+    // Content offset (centered logical viewport inside window)
+    float contentScale = logicalScale;
+    float contentW = logicalW * contentScale;
+    float contentH = logicalH * contentScale;
+    float contentOffsetX = (winW - contentW) * 0.5f / contentScale;
+    float contentOffsetY = (winH - contentH) * 0.5f / contentScale;
+
+    auto drawRectWithOffset = [&](float x, float y, float w, float h, SDL_Color c) {
+        SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, c.a);
+        SDL_FRect fr{x + contentOffsetX, y + contentOffsetY, w, h};
+        SDL_RenderFillRect(renderer, &fr);
+    };
+
+    static constexpr float COOP_GAP_PX = 20.0f;
+
+    const float availableWidth = logicalW - (MIN_MARGIN * 2) - (PANEL_WIDTH * 2) - (PANEL_SPACING * 2);
+    const float availableHeight = logicalH - TOP_MARGIN - BOTTOM_MARGIN - NEXT_PANEL_HEIGHT;
+
+    const float usableGridWidth = std::max(0.0f, availableWidth - COOP_GAP_PX);
+    const float maxBlockSizeW = usableGridWidth / CoopGame::COLS;
+    const float maxBlockSizeH = availableHeight / CoopGame::ROWS;
+    const float BLOCK_SIZE = std::min(maxBlockSizeW, maxBlockSizeH);
+    const float finalBlockSize = std::max(16.0f, std::min(BLOCK_SIZE, 36.0f));
+
+    const float HALF_W = 10.0f * finalBlockSize;
+    const float GRID_W = CoopGame::COLS * finalBlockSize + COOP_GAP_PX;
+    const float GRID_H = CoopGame::ROWS * finalBlockSize;
+
+    const float totalContentHeight = NEXT_PANEL_HEIGHT + GRID_H;
+    const float availableVerticalSpace = logicalH - TOP_MARGIN - BOTTOM_MARGIN;
+    const float verticalCenterOffset = (availableVerticalSpace - totalContentHeight) * 0.5f;
+    const float contentStartY = TOP_MARGIN + verticalCenterOffset;
+
+    const float totalLayoutWidth = PANEL_WIDTH + PANEL_SPACING + GRID_W + PANEL_SPACING + PANEL_WIDTH;
+    const float layoutStartX = (logicalW - totalLayoutWidth) * 0.5f;
+
+    const float statsX = layoutStartX + contentOffsetX;
+    const float gridX = layoutStartX + PANEL_WIDTH + PANEL_SPACING + contentOffsetX;
+    const float gridY = contentStartY + NEXT_PANEL_HEIGHT + contentOffsetY;
+
+    const float rightPanelX = gridX + GRID_W + PANEL_SPACING;
+
+    const float statsY = gridY;
+    const float statsW = PANEL_WIDTH;
+    const float statsH = GRID_H;
+
+    // (Score panels are drawn per-player below using scorePanelTex and classic sizing.)
+
+    // Handle line clearing effects (defer to LineEffect like single-player)
+    if (game->hasCompletedLines() && lineEffect && !lineEffect->isActive()) {
+        auto completedLines = game->getCompletedLines();
+        lineEffect->startLineClear(completedLines, static_cast<int>(gridX), static_cast<int>(gridY), static_cast<int>(finalBlockSize), CoopGame::COLS, static_cast<int>(COOP_GAP_PX), 10);
+        if (completedLines.size() == 4) {
+            AppFireworks::spawn(gridX + GRID_W * 0.5f, gridY + GRID_H * 0.5f);
+        }
+    }
+
+    // Precompute row drop offsets (line collapse effect)
+    std::array<float, CoopGame::ROWS> rowDropOffsets{};
+    for (int y = 0; y < CoopGame::ROWS; ++y) {
+        rowDropOffsets[y] = (lineEffect ? lineEffect->getRowDropOffset(y) : 0.0f);
+    }
+
+    // Grid backdrop and border (one border around both halves)
+    drawRectWithOffset(gridX - 3 - contentOffsetX, gridY - 3 - contentOffsetY, GRID_W + 6, GRID_H + 6, {100, 120, 200, 255});
+    // Background for left+right halves
+    drawRectWithOffset(gridX - contentOffsetX, gridY - contentOffsetY, GRID_W, GRID_H, {20, 25, 35, 255});
+    // Gap background (slightly darker so the 10px separation reads clearly)
+    drawRectWithOffset(gridX + HALF_W - contentOffsetX, gridY - contentOffsetY, COOP_GAP_PX, GRID_H, {12, 14, 18, 255});
+
+    // Sync divider line centered in the gap between halves.
+    const float dividerCenterX = gridX + HALF_W + (COOP_GAP_PX * 0.5f);
+    s_syncLine.SetRect(SDL_FRect{ dividerCenterX - 2.0f, gridY, 4.0f, GRID_H });
+
+    auto cellX = [&](int col) -> float {
+        float x = gridX + col * finalBlockSize;
+        if (col >= 10) {
+            x += COOP_GAP_PX;
+        }
+        return x;
+    };
+
+    // Grid lines (draw per-half so the gap is clean)
+    SDL_SetRenderDrawColor(renderer, 40, 45, 60, 255);
+    for (int x = 1; x < 10; ++x) {
+        float lineX = gridX + x * finalBlockSize;
+        SDL_RenderLine(renderer, lineX, gridY, lineX, gridY + GRID_H);
+    }
+    for (int x = 1; x < 10; ++x) {
+        float lineX = gridX + HALF_W + COOP_GAP_PX + x * finalBlockSize;
+        SDL_RenderLine(renderer, lineX, gridY, lineX, gridY + GRID_H);
+    }
+    for (int y = 1; y < CoopGame::ROWS; ++y) {
+        float lineY = gridY + y * finalBlockSize;
+        SDL_RenderLine(renderer, gridX, lineY, gridX + HALF_W, lineY);
+        SDL_RenderLine(renderer, gridX + HALF_W + COOP_GAP_PX, lineY, gridX + HALF_W + COOP_GAP_PX + HALF_W, lineY);
+    }
+
+    // In-grid 3D starfield + ambient sparkles (match classic feel, per-half)
+    {
+        static Uint32 s_lastCoopSparkTick = SDL_GetTicks();
+        static std::mt19937 s_coopSparkRng{ std::random_device{}() };
+        static std::vector<Sparkle> s_leftSparkles;
+        static std::vector<Sparkle> s_rightSparkles;
+        static std::vector<ImpactSpark> s_leftImpactSparks;
+        static std::vector<ImpactSpark> s_rightImpactSparks;
+        static float s_leftSparkleSpawnAcc = 0.0f;
+        static float s_rightSparkleSpawnAcc = 0.0f;
+
+        float halfW = HALF_W;
+        const float leftGridX = gridX;
+        const float rightGridX = gridX + HALF_W + COOP_GAP_PX;
+
+        Uint32 sparkNow = nowTicks;
+        float sparkDeltaMs = static_cast<float>(sparkNow - s_lastCoopSparkTick);
+        s_lastCoopSparkTick = sparkNow;
+        if (sparkDeltaMs < 0.0f || sparkDeltaMs > 100.0f) {
+            sparkDeltaMs = 16.0f;
+        }
+
+        if (!s_starfieldInitialized) {
+            s_inGridStarfield.init(static_cast<int>(halfW), static_cast<int>(GRID_H), 180);
+            s_starfieldInitialized = true;
+        } else {
+            s_inGridStarfield.resize(static_cast<int>(halfW), static_cast<int>(GRID_H));
+        }
+
+        const float deltaSeconds = std::clamp(sparkDeltaMs / 1000.0f, 0.0f, 0.033f);
+        s_inGridStarfield.update(deltaSeconds);
+
+        struct MagnetInfo { bool active{false}; float x{0.0f}; float y{0.0f}; };
+        auto computeMagnet = [&](CoopGame::PlayerSide side) -> MagnetInfo {
+            MagnetInfo info{};
+            const CoopGame::Piece& activePiece = game->current(side);
+            const int pieceType = static_cast<int>(activePiece.type);
+            if (pieceType < 0 || pieceType >= PIECE_COUNT) {
+                return info;
+            }
+
+            float sumLocalX = 0.0f;
+            float sumLocalY = 0.0f;
+            int filledCells = 0;
+            const int localXOffsetCols = (side == CoopGame::PlayerSide::Right) ? 10 : 0;
+            for (int cy = 0; cy < 4; ++cy) {
+                for (int cx = 0; cx < 4; ++cx) {
+                    if (!CoopGame::cellFilled(activePiece, cx, cy)) continue;
+                    sumLocalX += ((activePiece.x - localXOffsetCols) + cx + 0.5f) * finalBlockSize;
+                    sumLocalY += (activePiece.y + cy + 0.5f) * finalBlockSize;
+                    ++filledCells;
+                }
+            }
+            if (filledCells <= 0) {
+                return info;
+            }
+
+            info.active = true;
+            info.x = std::clamp(sumLocalX / static_cast<float>(filledCells), 0.0f, halfW);
+            info.y = std::clamp(sumLocalY / static_cast<float>(filledCells), 0.0f, GRID_H);
+            return info;
+        };
+
+        const MagnetInfo leftMagnet = computeMagnet(CoopGame::PlayerSide::Left);
+        const MagnetInfo rightMagnet = computeMagnet(CoopGame::PlayerSide::Right);
+
+        SDL_BlendMode oldBlend = SDL_BLENDMODE_NONE;
+        SDL_GetRenderDrawBlendMode(renderer, &oldBlend);
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+
+        auto drawStarfieldHalf = [&](float originX, const MagnetInfo& magnet) {
+            if (magnet.active) {
+                const float magnetStrength = finalBlockSize * 2.2f;
+                s_inGridStarfield.setMagnetTarget(magnet.x, magnet.y, magnetStrength);
+            } else {
+                s_inGridStarfield.clearMagnetTarget();
+            }
+
+            const float jitterAmp = 1.6f;
+            const float tms = static_cast<float>(sparkNow) * 0.001f;
+            const float jitterX = std::sin(tms * 1.7f) * jitterAmp + std::cos(tms * 0.9f) * 0.4f;
+            const float jitterY = std::sin(tms * 1.1f + 3.7f) * (jitterAmp * 0.6f);
+            s_inGridStarfield.draw(renderer, originX + jitterX, gridY + jitterY, 0.22f, true);
+        };
+
+        drawStarfieldHalf(leftGridX, leftMagnet);
+        drawStarfieldHalf(rightGridX, rightMagnet);
+
+        auto updateAndDrawSparkleLayer = [&](std::vector<Sparkle>& sparkles,
+                                             std::vector<ImpactSpark>& impactSparks,
+                                             float& spawnAcc,
+                                             const MagnetInfo& magnet,
+                                             float originX) {
+            if (!paused) {
+                const float spawnInterval = 0.08f;
+                spawnAcc += deltaSeconds;
+                while (spawnAcc >= spawnInterval) {
+                    spawnAcc -= spawnInterval;
+
+                    Sparkle s;
+                    bool spawnNearPiece = magnet.active && (std::uniform_real_distribution<float>(0.0f, 1.0f)(s_coopSparkRng) > 0.35f);
+
+                    float sx = 0.0f;
+                    float sy = 0.0f;
+                    if (spawnNearPiece) {
+                        float jitterX = std::uniform_real_distribution<float>(-finalBlockSize * 1.2f, finalBlockSize * 1.2f)(s_coopSparkRng);
+                        float jitterY = std::uniform_real_distribution<float>(-finalBlockSize * 1.2f, finalBlockSize * 1.2f)(s_coopSparkRng);
+                        sx = std::clamp(magnet.x + jitterX, -finalBlockSize * 2.0f, halfW + finalBlockSize * 2.0f);
+                        sy = std::clamp(magnet.y + jitterY, -finalBlockSize * 2.0f, GRID_H + finalBlockSize * 2.0f);
+                    } else {
+                        float side = std::uniform_real_distribution<float>(0.0f, 1.0f)(s_coopSparkRng);
+                        const float borderBand = std::max(12.0f, finalBlockSize * 1.0f);
+                        if (side < 0.2f) {
+                            sx = std::uniform_real_distribution<float>(-borderBand, 0.0f)(s_coopSparkRng);
+                            sy = std::uniform_real_distribution<float>(-borderBand, GRID_H + borderBand)(s_coopSparkRng);
+                        } else if (side < 0.4f) {
+                            sx = std::uniform_real_distribution<float>(halfW, halfW + borderBand)(s_coopSparkRng);
+                            sy = std::uniform_real_distribution<float>(-borderBand, GRID_H + borderBand)(s_coopSparkRng);
+                        } else if (side < 0.6f) {
+                            sx = std::uniform_real_distribution<float>(-borderBand, halfW + borderBand)(s_coopSparkRng);
+                            sy = std::uniform_real_distribution<float>(-borderBand, 0.0f)(s_coopSparkRng);
+                        } else if (side < 0.9f) {
+                            sx = std::uniform_real_distribution<float>(0.0f, halfW)(s_coopSparkRng);
+                            sy = std::uniform_real_distribution<float>(0.0f, finalBlockSize * 2.0f)(s_coopSparkRng);
+                        } else {
+                            sx = std::uniform_real_distribution<float>(-borderBand, halfW + borderBand)(s_coopSparkRng);
+                            sy = std::uniform_real_distribution<float>(GRID_H, GRID_H + borderBand)(s_coopSparkRng);
+                        }
+                    }
+
+                    s.x = sx;
+                    s.y = sy;
+                    float speed = std::uniform_real_distribution<float>(10.0f, 60.0f)(s_coopSparkRng);
+                    float ang = std::uniform_real_distribution<float>(-3.14159f, 3.14159f)(s_coopSparkRng);
+                    s.vx = std::cos(ang) * speed;
+                    s.vy = std::sin(ang) * speed * 0.25f;
+                    s.maxLifeMs = std::uniform_real_distribution<float>(350.0f, 900.0f)(s_coopSparkRng);
+                    s.lifeMs = s.maxLifeMs;
+                    s.size = std::uniform_real_distribution<float>(1.5f, 5.0f)(s_coopSparkRng);
+                    if (std::uniform_real_distribution<float>(0.0f, 1.0f)(s_coopSparkRng) < 0.5f) {
+                        s.color = SDL_Color{255, 230, 180, 255};
+                    } else {
+                        s.color = SDL_Color{180, 220, 255, 255};
+                    }
+                    s.pulse = std::uniform_real_distribution<float>(0.0f, 6.28f)(s_coopSparkRng);
+                    sparkles.push_back(s);
+                }
+            }
+
+            if (!sparkles.empty()) {
+                auto it = sparkles.begin();
+                while (it != sparkles.end()) {
+                    Sparkle& sp = *it;
+                    sp.lifeMs -= sparkDeltaMs;
+                    if (sp.lifeMs <= 0.0f) {
+                        const int burstCount = std::uniform_int_distribution<int>(4, 8)(s_coopSparkRng);
+                        for (int bi = 0; bi < burstCount; ++bi) {
+                            ImpactSpark ps;
+                            ps.x = originX + sp.x + std::uniform_real_distribution<float>(-2.0f, 2.0f)(s_coopSparkRng);
+                            ps.y = gridY + sp.y + std::uniform_real_distribution<float>(-2.0f, 2.0f)(s_coopSparkRng);
+                            float ang = std::uniform_real_distribution<float>(0.0f, 6.2831853f)(s_coopSparkRng);
+                            float speed = std::uniform_real_distribution<float>(10.0f, 120.0f)(s_coopSparkRng);
+                            ps.vx = std::cos(ang) * speed;
+                            ps.vy = std::sin(ang) * speed * 0.8f;
+                            ps.maxLifeMs = std::uniform_real_distribution<float>(220.0f, 500.0f)(s_coopSparkRng);
+                            ps.lifeMs = ps.maxLifeMs;
+                            ps.size = std::max(1.0f, sp.size * 0.5f);
+                            ps.color = sp.color;
+                            impactSparks.push_back(ps);
+                        }
+                        it = sparkles.erase(it);
+                        continue;
+                    }
+
+                    float lifeRatio = sp.lifeMs / sp.maxLifeMs;
+                    sp.x += sp.vx * deltaSeconds;
+                    sp.y += sp.vy * deltaSeconds;
+                    sp.vy *= 0.995f;
+                    sp.pulse += deltaSeconds * 8.0f;
+
+                    float pulse = 0.5f + 0.5f * std::sin(sp.pulse);
+                    Uint8 alpha = static_cast<Uint8>(std::clamp(lifeRatio * pulse, 0.0f, 1.0f) * 255.0f);
+                    SDL_SetRenderDrawColor(renderer, sp.color.r, sp.color.g, sp.color.b, alpha);
+                    float half = sp.size * 0.5f;
+                    SDL_FRect fr{ originX + sp.x - half, gridY + sp.y - half, sp.size, sp.size };
+                    SDL_RenderFillRect(renderer, &fr);
+                    ++it;
+                }
+            }
+
+            if (!impactSparks.empty()) {
+                auto it = impactSparks.begin();
+                while (it != impactSparks.end()) {
+                    ImpactSpark& spark = *it;
+                    spark.vy += 0.00045f * sparkDeltaMs;
+                    spark.x += spark.vx * sparkDeltaMs;
+                    spark.y += spark.vy * sparkDeltaMs;
+                    spark.lifeMs -= sparkDeltaMs;
+                    if (spark.lifeMs <= 0.0f) {
+                        it = impactSparks.erase(it);
+                        continue;
+                    }
+                    float lifeRatio = spark.lifeMs / spark.maxLifeMs;
+                    Uint8 alpha = static_cast<Uint8>(std::clamp(lifeRatio, 0.0f, 1.0f) * 160.0f);
+                    SDL_SetRenderDrawColor(renderer, spark.color.r, spark.color.g, spark.color.b, alpha);
+                    SDL_FRect sparkRect{
+                        spark.x - spark.size * 0.5f,
+                        spark.y - spark.size * 0.5f,
+                        spark.size,
+                        spark.size * 1.4f
+                    };
+                    SDL_RenderFillRect(renderer, &sparkRect);
+                    ++it;
+                }
+            }
+        };
+
+        updateAndDrawSparkleLayer(s_leftSparkles, s_leftImpactSparks, s_leftSparkleSpawnAcc, leftMagnet, leftGridX);
+        updateAndDrawSparkleLayer(s_rightSparkles, s_rightImpactSparks, s_rightSparkleSpawnAcc, rightMagnet, rightGridX);
+
+        SDL_SetRenderDrawBlendMode(renderer, oldBlend);
+    }
+
+    // Half-row feedback: lightly tint rows where one side is filled, brighter where both are pending clear
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+    const auto& rowStates = game->rowHalfStates();
+
+    bool leftReady = false;
+    bool rightReady = false;
+    bool synced = false;
+
+    for (int y = 0; y < CoopGame::ROWS; ++y) {
+        const auto& rs = rowStates[y];
+        float rowY = gridY + y * finalBlockSize;
+
+        if (rs.leftFull && rs.rightFull) {
+            synced = true;
+        } else {
+            leftReady = leftReady || (rs.leftFull && !rs.rightFull);
+            rightReady = rightReady || (rs.rightFull && !rs.leftFull);
+        }
+
+        if (rs.leftFull && rs.rightFull) {
+            SDL_SetRenderDrawColor(renderer, 140, 210, 255, 45);
+            SDL_FRect frL{gridX, rowY, HALF_W, finalBlockSize};
+            SDL_RenderFillRect(renderer, &frL);
+            SDL_FRect frR{gridX + HALF_W + COOP_GAP_PX, rowY, HALF_W, finalBlockSize};
+            SDL_RenderFillRect(renderer, &frR);
+        } else if (rs.leftFull ^ rs.rightFull) {
+            SDL_SetRenderDrawColor(renderer, 90, 140, 220, 35);
+            float w = HALF_W;
+            float x = rs.leftFull ? gridX : (gridX + HALF_W + COOP_GAP_PX);
+            SDL_FRect fr{x, rowY, w, finalBlockSize};
+            SDL_RenderFillRect(renderer, &fr);
+        }
+    }
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+
+    // Trigger a brief flash exactly when cooperative lines are actually cleared:
+    // `completedLines` remains populated during the LineEffect, then becomes empty
+    // immediately after `CoopGame::clearCompletedLines()` is invoked.
+    const bool hasCompletedLines = game->hasCompletedLines();
+    if (s_lastHadCompletedLines && !hasCompletedLines) {
+        s_syncLine.TriggerClearFlash();
+    }
+    s_lastHadCompletedLines = hasCompletedLines;
+
+    if (synced) {
+        s_syncLine.SetState(SyncState::Synced);
+    } else if (leftReady) {
+        s_syncLine.SetState(SyncState::LeftReady);
+    } else if (rightReady) {
+        s_syncLine.SetState(SyncState::RightReady);
+    } else {
+        s_syncLine.SetState(SyncState::Idle);
+    }
+
+    // Hard-drop impact shake (match classic feel)
+    float impactStrength = 0.0f;
+    float impactEased = 0.0f;
+    std::array<uint8_t, CoopGame::COLS * CoopGame::ROWS> impactMask{};
+    std::array<float, CoopGame::COLS * CoopGame::ROWS> impactWeight{};
+    if (game->hasHardDropShake()) {
+        impactStrength = static_cast<float>(game->hardDropShakeStrength());
+        impactStrength = std::clamp(impactStrength, 0.0f, 1.0f);
+        impactEased = impactStrength * impactStrength;
+        const auto& impactCells = game->getHardDropCells();
+        const auto& boardRef = game->boardRef();
+        for (const auto& cell : impactCells) {
+            if (cell.x < 0 || cell.x >= CoopGame::COLS || cell.y < 0 || cell.y >= CoopGame::ROWS) {
+                continue;
+            }
+            int idx = cell.y * CoopGame::COLS + cell.x;
+            impactMask[idx] = 1;
+            impactWeight[idx] = 1.0f;
+
+            int depth = 0;
+            for (int ny = cell.y + 1; ny < CoopGame::ROWS && depth < 4; ++ny) {
+                if (!boardRef[ny * CoopGame::COLS + cell.x].occupied) {
+                    break;
+                }
+                ++depth;
+                int nidx = ny * CoopGame::COLS + cell.x;
+                impactMask[nidx] = 1;
+                float weight = std::max(0.15f, 1.0f - depth * 0.35f);
+                impactWeight[nidx] = std::max(impactWeight[nidx], weight);
+            }
+        }
+    }
+
+    // Draw settled blocks
+    const auto& board = game->boardRef();
+    for (int y = 0; y < CoopGame::ROWS; ++y) {
+        float dropOffset = rowDropOffsets[y];
+        for (int x = 0; x < CoopGame::COLS; ++x) {
+            const auto& cell = board[y * CoopGame::COLS + x];
+            if (!cell.occupied || cell.value <= 0) continue;
+            float px = cellX(x);
+            float py = gridY + y * finalBlockSize + dropOffset;
+
+            const int cellIdx = y * CoopGame::COLS + x;
+            float weight = impactWeight[cellIdx];
+            if (impactStrength > 0.0f && weight > 0.0f && impactMask[cellIdx]) {
+                float cellSeed = static_cast<float>((x * 37 + y * 61) % 113);
+                float t = static_cast<float>(nowTicks % 10000) * 0.018f + cellSeed;
+                float amplitude = 6.0f * impactEased * weight;
+                float freq = 2.0f + weight * 1.3f;
+                px += amplitude * std::sin(t * freq);
+                py += amplitude * 0.75f * std::cos(t * (freq + 1.1f));
+            }
+
+            drawBlockTexturePublic(renderer, blocksTex, px, py, finalBlockSize, cell.value - 1);
+        }
+    }
+
+    // Active pieces (per-side smoothing)
+    auto computeOffsets = [&](CoopGame::PlayerSide side, SmoothState& ss) {
+        float offsetX = 0.0f;
+        float offsetY = 0.0f;
+
+        if (smoothScrollEnabled) {
+            const uint64_t seq = game->currentPieceSequence(side);
+            const float targetX = static_cast<float>(game->current(side).x);
+            if (!ss.initialized || ss.seq != seq) {
+                ss.initialized = true;
+                ss.seq = seq;
+                ss.visualX = targetX;
+                // Trigger a short spawn fade so the newly spawned piece visually
+                // fades into the first visible row (like classic mode).
+                SpawnFadeState &sf = (side == CoopGame::PlayerSide::Left) ? s_leftSpawnFade : s_rightSpawnFade;
+                sf.active = true;
+                sf.startTick = nowTicks;
+                sf.durationMs = 200.0f;
+                sf.seq = seq;
+                sf.piece = game->current(side);
+                sf.spawnY = sf.piece.y;
+                sf.tileSize = finalBlockSize;
+                // Note: during the spawn fade we draw the live piece each frame.
+                // If the piece is still above the visible grid, we temporarily pin
+                // it so the topmost filled cell appears at row 0 (no spawn delay),
+                // while still applying smoothing offsets so it starts moving
+                // immediately.
+                sf.targetX = 0.0f;
+                sf.targetY = 0.0f;
+            } else {
+                // Reuse exact horizontal smoothing from single-player
+                constexpr float HORIZONTAL_SMOOTH_MS = 55.0f;
+                const float lerpFactor = std::clamp(deltaMs / HORIZONTAL_SMOOTH_MS, 0.0f, 1.0f);
+                ss.visualX = std::lerp(ss.visualX, targetX, lerpFactor);
+            }
+            offsetX = (ss.visualX - targetX) * finalBlockSize;
+
+            // Reuse exact single-player fall offset computation (per-side getters)
+            double gravityMs = game->getGravityMs();
+            if (gravityMs > 0.0) {
+                double effectiveMs = game->isSoftDropping(side) ? std::max(5.0, gravityMs / 5.0) : gravityMs;
+                double accumulator = std::clamp(game->getFallAccumulator(side), 0.0, effectiveMs);
+                float progress = static_cast<float>(accumulator / effectiveMs);
+                progress = std::clamp(progress, 0.0f, 1.0f);
+                offsetY = progress * finalBlockSize;
+
+                // Clamp vertical offset to avoid overlapping settled blocks (same logic as single-player)
+                const auto& boardRef = game->boardRef();
+                const CoopGame::Piece& piece = game->current(side);
+                float maxAllowed = finalBlockSize;
+                for (int cy = 0; cy < 4; ++cy) {
+                    for (int cx = 0; cx < 4; ++cx) {
+                        if (!CoopGame::cellFilled(piece, cx, cy)) continue;
+                        int gx = piece.x + cx;
+                        int gy = piece.y + cy;
+                        if (gx < 0 || gx >= CoopGame::COLS) continue;
+                        int testY = gy + 1;
+                        int emptyRows = 0;
+                        if (testY < 0) {
+                            emptyRows -= testY;
+                            testY = 0;
+                        }
+                        while (testY >= 0 && testY < CoopGame::ROWS) {
+                            if (boardRef[testY * CoopGame::COLS + gx].occupied) break;
+                            ++emptyRows;
+                            ++testY;
+                        }
+                        float cellLimit = (emptyRows > 0) ? finalBlockSize : 0.0f;
+                        maxAllowed = std::min(maxAllowed, cellLimit);
+                    }
+                }
+                offsetY = std::min(offsetY, maxAllowed);
+            }
+        } else {
+            ss.initialized = true;
+            ss.seq = game->currentPieceSequence(side);
+            ss.visualX = static_cast<float>(game->current(side).x);
+        }
+
+        if (Settings::instance().isDebugEnabled()) {
+            float dbg_targetX = static_cast<float>(game->current(side).x);
+            double gMsDbg = game->getGravityMs();
+            double accDbg = game->getFallAccumulator(side);
+            int softDbg = game->isSoftDropping(side) ? 1 : 0;
+            /*
+            SDL_LogDebug(SDL_LOG_CATEGORY_APPLICATION, "COOP %s OFFSETS: seq=%llu visX=%.3f targX=%.3f offX=%.2f offY=%.2f gravMs=%.2f fallAcc=%.2f soft=%d",
+                (side == CoopGame::PlayerSide::Left) ? "L" : "R",
+                (unsigned long long)ss.seq,
+                ss.visualX,
+                dbg_targetX,
+                offsetX,
+                offsetY,
+                gMsDbg,
+                accDbg,
+                softDbg
+            );
+            */
+        }
+        return std::pair<float, float>{ offsetX, offsetY };
+    };
+
+    auto drawSpawnFadeIfActive = [&](SpawnFadeState &sf, CoopGame::PlayerSide side, const std::pair<float, float>& offsets) {
+        if (!sf.active) return;
+
+        // If the piece has already changed, stop the fade.
+        const uint64_t currentSeq = game->currentPieceSequence(side);
+        if (sf.seq != currentSeq) {
+            sf.active = false;
+            return;
+        }
+
+        const CoopGame::Piece& livePiece = game->current(side);
+        float elapsed = static_cast<float>(nowTicks - sf.startTick);
+        float t = sf.durationMs <= 0.0f ? 1.0f : std::clamp(elapsed / sf.durationMs, 0.0f, 1.0f);
+        Uint8 alpha = static_cast<Uint8>(std::lround(255.0f * t));
+        if (blocksTex) SDL_SetTextureAlphaMod(blocksTex, alpha);
+
+        int minCy = 4;
+        int maxCy = -1;
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!CoopGame::cellFilled(livePiece, cx, cy)) continue;
+                minCy = std::min(minCy, cy);
+                maxCy = std::max(maxCy, cy);
+            }
+        }
+        if (minCy == 4) {
+            minCy = 0;
+        }
+        if (maxCy < 0) {
+            maxCy = 0;
+        }
+
+        // Pin only when *no* filled cell is visible yet. Using maxCy avoids pinning
+        // cases like vertical I where some blocks are already visible at spawn.
+        const bool pinToFirstVisibleRow = (livePiece.y + maxCy) < 0;
+
+        const float baseX = cellX(livePiece.x) + offsets.first;
+        float baseY = 0.0f;
+        if (pinToFirstVisibleRow) {
+            // Keep the piece visible (topmost filled cell at row 0), but also
+            // incorporate real y-step progression so the fall accumulator wrapping
+            // doesn't produce a one-row snap.
+            const int dySteps = livePiece.y - sf.spawnY;
+            baseY = (gridY - static_cast<float>(minCy) * sf.tileSize)
+                + static_cast<float>(dySteps) * sf.tileSize
+                + offsets.second;
+        } else {
+            baseY = gridY + static_cast<float>(livePiece.y) * sf.tileSize + offsets.second;
+        }
+
+        // Draw the live piece (either pinned-to-row0 or at its real position).
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!CoopGame::cellFilled(livePiece, cx, cy)) continue;
+                int pyIdx = livePiece.y + cy;
+                if (!pinToFirstVisibleRow && pyIdx < 0) continue;
+                float px = baseX + static_cast<float>(cx) * sf.tileSize;
+                float py = baseY + static_cast<float>(cy) * sf.tileSize;
+                drawBlockTexturePublic(renderer, blocksTex, px, py, sf.tileSize, livePiece.type);
+            }
+        }
+        if (blocksTex) SDL_SetTextureAlphaMod(blocksTex, 255);
+
+        // End fade after duration, but never stop while we are pinning (otherwise
+        // I can briefly disappear until it becomes visible in the real grid).
+        if (t >= 1.0f && !pinToFirstVisibleRow) {
+            sf.active = false;
+        }
+    };
+
+    auto drawPiece = [&](const CoopGame::Piece& p, const std::pair<float, float>& offsets, bool isGhost) {
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!CoopGame::cellFilled(p, cx, cy)) continue;
+                int pxIdx = p.x + cx;
+                int pyIdx = p.y + cy;
+                if (pyIdx < 0) continue; // don't draw parts above the visible grid
+                float px = cellX(pxIdx) + offsets.first;
+                float py = gridY + (float)pyIdx * finalBlockSize + offsets.second;
+                if (isGhost) {
+                    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+                    SDL_SetRenderDrawColor(renderer, 180, 180, 180, 20);
+                    SDL_FRect rect = {px + 2.0f, py + 2.0f, finalBlockSize - 4.0f, finalBlockSize - 4.0f};
+                    SDL_RenderFillRect(renderer, &rect);
+                    SDL_SetRenderDrawColor(renderer, 180, 180, 180, 30);
+                    SDL_FRect border = {px + 1.0f, py + 1.0f, finalBlockSize - 2.0f, finalBlockSize - 2.0f};
+                    SDL_RenderRect(renderer, &border);
+                } else {
+                    drawBlockTexturePublic(renderer, blocksTex, px, py, finalBlockSize, p.type);
+                }
+            }
+        }
+    };
+    const auto leftOffsets = computeOffsets(CoopGame::PlayerSide::Left, s_leftSmooth);
+    const auto rightOffsets = computeOffsets(CoopGame::PlayerSide::Right, s_rightSmooth);
+    // Draw transient spawn fades (if active)
+    drawSpawnFadeIfActive(s_leftSpawnFade, CoopGame::PlayerSide::Left, leftOffsets);
+    drawSpawnFadeIfActive(s_rightSpawnFade, CoopGame::PlayerSide::Right, rightOffsets);
+
+    // Draw classic-style ghost pieces (landing position), grid-aligned.
+    // This intentionally does NOT use smoothing offsets.
+    auto computeGhostPiece = [&](CoopGame::PlayerSide side) {
+        CoopGame::Piece ghostPiece = game->current(side);
+        const auto& boardRef = game->boardRef();
+        while (true) {
+            CoopGame::Piece testPiece = ghostPiece;
+            testPiece.y++;
+            bool collision = false;
+            for (int cy = 0; cy < 4; ++cy) {
+                for (int cx = 0; cx < 4; ++cx) {
+                    if (!CoopGame::cellFilled(testPiece, cx, cy)) continue;
+                    int gx = testPiece.x + cx;
+                    int gy = testPiece.y + cy;
+                    if (gy >= CoopGame::ROWS || gx < 0 || gx >= CoopGame::COLS ||
+                        (gy >= 0 && boardRef[gy * CoopGame::COLS + gx].occupied)) {
+                        collision = true;
+                        break;
+                    }
+                }
+                if (collision) break;
+            }
+            if (collision) break;
+            ghostPiece = testPiece;
+        }
+        return ghostPiece;
+    };
+
+    const std::pair<float, float> ghostOffsets{0.0f, 0.0f};
+    drawPiece(computeGhostPiece(CoopGame::PlayerSide::Left), ghostOffsets, true);
+    drawPiece(computeGhostPiece(CoopGame::PlayerSide::Right), ghostOffsets, true);
+
+    // If a spawn fade is active for a side and matches the current piece
+    // sequence, only draw the fade visual and skip the regular piece draw
+    // to avoid a double-draw that appears as a jump when falling starts.
+    if (!(s_leftSpawnFade.active && s_leftSpawnFade.seq == game->currentPieceSequence(CoopGame::PlayerSide::Left))) {
+        drawPiece(game->current(CoopGame::PlayerSide::Left), leftOffsets, false);
+    }
+    if (!(s_rightSpawnFade.active && s_rightSpawnFade.seq == game->currentPieceSequence(CoopGame::PlayerSide::Right))) {
+        drawPiece(game->current(CoopGame::PlayerSide::Right), rightOffsets, false);
+    }
+
+    // Draw line clearing effects above pieces (matches single-player)
+    if (lineEffect && lineEffect->isActive()) {
+        lineEffect->render(renderer, blocksTex, static_cast<int>(gridX), static_cast<int>(gridY), static_cast<int>(finalBlockSize), static_cast<int>(COOP_GAP_PX), 10);
+    }
+
+    // Render the SYNC divider last so it stays visible above effects/blocks.
+    s_syncLine.Render(renderer);
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+
+    // Next panels (two)
+    const float nextPanelPad = 12.0f;
+    const float nextPanelW = (HALF_W) - finalBlockSize * 1.5f;
+    const float nextPanelH = NEXT_PANEL_HEIGHT - nextPanelPad * 2.0f;
+    float nextLeftX = gridX + finalBlockSize;
+    float nextRightX = gridX + HALF_W + COOP_GAP_PX + (HALF_W - finalBlockSize - nextPanelW);
+    float nextY = contentStartY + contentOffsetY;
+
+    auto drawNextPanel = [&](float panelX, float panelY, const CoopGame::Piece& piece) {
+        SDL_FRect panel{ panelX, panelY, nextPanelW, nextPanelH };
+        if (nextPanelTex) {
+            SDL_RenderTexture(renderer, nextPanelTex, nullptr, &panel);
+        } else {
+            drawRectWithOffset(panel.x - contentOffsetX, panel.y - contentOffsetY, panel.w, panel.h, SDL_Color{18,22,30,200});
+        }
+        // Center piece inside panel
+        int minCx = 4, minCy = 4, maxCx = -1, maxCy = -1;
+        for (int cy = 0; cy < 4; ++cy) {
+            for (int cx = 0; cx < 4; ++cx) {
+                if (!CoopGame::cellFilled(piece, cx, cy)) continue;
+                minCx = std::min(minCx, cx);
+                minCy = std::min(minCy, cy);
+                maxCx = std::max(maxCx, cx);
+                maxCy = std::max(maxCy, cy);
+            }
+        }
+        if (maxCx >= minCx && maxCy >= minCy) {
+            float tile = finalBlockSize * 0.8f;
+            float pieceW = (maxCx - minCx + 1) * tile;
+            float pieceH = (maxCy - minCy + 1) * tile;
+            float startX = panel.x + (panel.w - pieceW) * 0.5f - minCx * tile;
+            float startY = panel.y + (panel.h - pieceH) * 0.5f - minCy * tile;
+            for (int cy = 0; cy < 4; ++cy) {
+                for (int cx = 0; cx < 4; ++cx) {
+                    if (!CoopGame::cellFilled(piece, cx, cy)) continue;
+                    float px = startX + cx * tile;
+                    float py = startY + cy * tile;
+                    drawBlockTexturePublic(renderer, blocksTex, px, py, tile, piece.type);
+                }
+            }
+        }
+    };
+
+    drawNextPanel(nextLeftX, nextY, game->next(CoopGame::PlayerSide::Left));
+    drawNextPanel(nextRightX, nextY, game->next(CoopGame::PlayerSide::Right));
+
+    // Per-player scoreboards (left and right)
+    auto drawPlayerScoreboard = [&](CoopGame::PlayerSide side, float columnLeftX, float columnRightX, const char* title) {
+        const SDL_Color labelColor{255, 220, 0, 255};
+        const SDL_Color valueColor{255, 255, 255, 255};
+        const SDL_Color nextColor{80, 255, 120, 255};
+
+        // Match classic vertical placement feel
+        const float contentTopOffset = 0.0f;
+        const float contentBottomOffset = 290.0f;
+        const float contentPad = 36.0f;
+        float scoreContentH = (contentBottomOffset - contentTopOffset) + contentPad;
+        float baseY = gridY + (GRID_H - scoreContentH) * 0.5f;
+
+        const float statsPanelPadLeft = 40.0f;
+        const float statsPanelPadRight = 34.0f;
+        const float statsPanelPadY = 28.0f;
+
+        const float textX = columnLeftX + statsPanelPadLeft;
+
+        char scoreStr[32];
+        std::snprintf(scoreStr, sizeof(scoreStr), "%d", game->score(side));
+
+        char linesStr[16];
+        std::snprintf(linesStr, sizeof(linesStr), "%03d", game->lines(side));
+
+        char levelStr[16];
+        std::snprintf(levelStr, sizeof(levelStr), "%02d", game->level(side));
+
+        // Next level progression (per-player lines)
+        int startLv = game->startLevelBase();
+        int linesDone = game->lines(side);
+        int firstThreshold = (startLv + 1) * 10;
+        int nextThreshold = 0;
+        if (linesDone < firstThreshold) {
+            nextThreshold = firstThreshold;
+        } else {
+            int blocksPast = linesDone - firstThreshold;
+            nextThreshold = firstThreshold + ((blocksPast / 10) + 1) * 10;
+        }
+        int linesForNext = std::max(0, nextThreshold - linesDone);
+        char nextStr[32];
+        std::snprintf(nextStr, sizeof(nextStr), "%d  LINES", linesForNext);
+
+        // Time display (shared session time)
+        int totalSecs = game->elapsed(side);
+        int mins = totalSecs / 60;
+        int secs = totalSecs % 60;
+        char timeStr[16];
+        std::snprintf(timeStr, sizeof(timeStr), "%02d:%02d", mins, secs);
+
+        struct StatLine {
+            const char* text;
+            float offsetY;
+            float scale;
+            SDL_Color color;
+        };
+
+        // Keep offsets aligned with classic spacing
+        std::vector<StatLine> statLines;
+        statLines.reserve(12);
+        statLines.push_back({title, 0.0f, 0.95f, SDL_Color{200, 220, 235, 220}});
+        statLines.push_back({"SCORE", 30.0f, 1.0f, labelColor});
+        statLines.push_back({scoreStr, 55.0f, 0.9f, valueColor});
+        statLines.push_back({"LINES", 100.0f, 1.0f, labelColor});
+        statLines.push_back({linesStr, 125.0f, 0.9f, valueColor});
+        statLines.push_back({"LEVEL", 170.0f, 1.0f, labelColor});
+        statLines.push_back({levelStr, 195.0f, 0.9f, valueColor});
+        statLines.push_back({"NEXT LVL", 230.0f, 1.0f, labelColor});
+        statLines.push_back({nextStr, 255.0f, 0.9f, nextColor});
+        statLines.push_back({"TIME", 295.0f, 1.0f, labelColor});
+        statLines.push_back({timeStr, 320.0f, 0.9f, valueColor});
+
+        // Size the panel like classic: measure the text block and fit the background.
+        float statsContentTop = std::numeric_limits<float>::max();
+        float statsContentBottom = std::numeric_limits<float>::lowest();
+        float statsContentMaxWidth = 0.0f;
+        for (const auto& line : statLines) {
+            int textW = 0;
+            int textH = 0;
+            pixelFont->measure(line.text, line.scale, textW, textH);
+            float y = baseY + line.offsetY;
+            statsContentTop = std::min(statsContentTop, y);
+            statsContentBottom = std::max(statsContentBottom, y + static_cast<float>(textH));
+            statsContentMaxWidth = std::max(statsContentMaxWidth, static_cast<float>(textW));
+        }
+
+        float panelW = statsPanelPadLeft + statsContentMaxWidth + statsPanelPadRight;
+        float panelH = (statsContentBottom - statsContentTop) + statsPanelPadY * 2.0f;
+        float panelY = statsContentTop - statsPanelPadY;
+        // Left player is left-aligned in its column; right player is right-aligned.
+        float panelX = (side == CoopGame::PlayerSide::Right) ? (columnRightX - panelW) : columnLeftX;
+        SDL_FRect panelBg{ panelX, panelY, panelW, panelH };
+        if (scorePanelTex) {
+            SDL_RenderTexture(renderer, scorePanelTex, nullptr, &panelBg);
+        } else {
+            SDL_SetRenderDrawColor(renderer, 12, 18, 32, 205);
+            SDL_RenderFillRect(renderer, &panelBg);
+        }
+
+        float textDrawX = panelX + statsPanelPadLeft;
+        for (const auto& line : statLines) {
+            pixelFont->draw(renderer, textDrawX, baseY + line.offsetY, line.text, line.scale, line.color);
+        }
+    };
+
+    // Nudge panels toward the window edges for tighter symmetry.
+    const float scorePanelEdgeNudge = 20.0f;
+    const float leftColumnLeftX = statsX - scorePanelEdgeNudge;
+    const float leftColumnRightX = leftColumnLeftX + statsW;
+    const float rightColumnLeftX = rightPanelX;
+    const float rightColumnRightX = rightColumnLeftX + statsW + scorePanelEdgeNudge;
+
+    drawPlayerScoreboard(CoopGame::PlayerSide::Left, leftColumnLeftX, leftColumnRightX, "PLAYER 1");
+    drawPlayerScoreboard(CoopGame::PlayerSide::Right, rightColumnLeftX, rightColumnRightX, "PLAYER 2");
+
+    // Combined score summary centered under the grid
+    {
+        int leftScore = game->score(CoopGame::PlayerSide::Left);
+        int rightScore = game->score(CoopGame::PlayerSide::Right);
+        int sumScore = leftScore + rightScore;
+        char sumLabel[64];
+        char sumValue[64];
+        std::snprintf(sumLabel, sizeof(sumLabel), "SCORE %d + SCORE %d =", leftScore, rightScore);
+        std::snprintf(sumValue, sizeof(sumValue), "%d", sumScore);
+
+        // Draw label smaller and value larger
+        float labelScale = 0.9f;
+        float valueScale = 1.6f;
+        SDL_Color labelColor = {200, 220, 235, 220};
+        SDL_Color valueColor = {255, 230, 130, 255};
+
+        // Position: centered beneath the grid
+        float centerX = gridX + GRID_W * 0.5f;
+        int lw=0, lh=0; pixelFont->measure(sumLabel, labelScale, lw, lh);
+        int vw=0, vh=0; pixelFont->measure(sumValue, valueScale, vw, vh);
+        float labelX = centerX - static_cast<float>(lw) * 0.5f;
+        float valueX = centerX - static_cast<float>(vw) * 0.5f;
+        float belowY = gridY + GRID_H + 14.0f; // small gap below grid
+
+        pixelFont->draw(renderer, labelX, belowY, sumLabel, labelScale, labelColor);
+        pixelFont->draw(renderer, valueX, belowY + 22.0f, sumValue, valueScale, valueColor);
+    }
+}
+
+void GameRenderer::renderExitPopup(
+    SDL_Renderer* renderer,
+    FontAtlas* pixelFont,
+    float winW,
+    float winH,
+    float logicalScale,
+    int selectedButton
+) {
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+
+    SDL_Rect oldViewport;
+    SDL_GetRenderViewport(renderer, &oldViewport);
+    float oldScaleX = 1.0f;
+    float oldScaleY = 1.0f;
+    SDL_GetRenderScale(renderer, &oldScaleX, &oldScaleY);
+
+    SDL_SetRenderViewport(renderer, nullptr);
+    SDL_SetRenderScale(renderer, 1.0f, 1.0f);
+
+    SDL_SetRenderDrawColor(renderer, 2, 4, 12, 210);
+    SDL_FRect fullWin{0.0f, 0.0f, winW, winH};
+    SDL_RenderFillRect(renderer, &fullWin);
+
+    const float scale = std::max(0.8f, logicalScale);
+    const float panelW = 740.0f * scale;
+    const float panelH = 380.0f * scale;
+    SDL_FRect panel{
+        (winW - panelW) * 0.5f,
+        (winH - panelH) * 0.5f,
+        panelW,
+        panelH
+    };
+
+    SDL_FRect shadow{
+        panel.x + 14.0f * scale,
+        panel.y + 16.0f * scale,
+        panel.w + 4.0f * scale,
+        panel.h + 4.0f * scale
+    };
+    SDL_SetRenderDrawColor(renderer, 0, 0, 0, 140);
+    SDL_RenderFillRect(renderer, &shadow);
+
+    const std::array<SDL_Color, 3> panelLayers{
+        SDL_Color{7, 10, 22, 255},
+        SDL_Color{12, 22, 40, 255},
+        SDL_Color{18, 32, 56, 255}
+    };
+    for (size_t i = 0; i < panelLayers.size(); ++i) {
+        float inset = static_cast<float>(i) * 6.0f * scale;
+        SDL_FRect layer{
+            panel.x + inset,
+            panel.y + inset,
+            panel.w - inset * 2.0f,
+            panel.h - inset * 2.0f
+        };
+        SDL_Color c = panelLayers[i];
+        SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, c.a);
+        SDL_RenderFillRect(renderer, &layer);
+    }
+
+    SDL_SetRenderDrawColor(renderer, 60, 90, 150, 255);
+    SDL_RenderRect(renderer, &panel);
+
+    SDL_FRect insetFrame{
+        panel.x + 10.0f * scale,
+        panel.y + 10.0f * scale,
+        panel.w - 20.0f * scale,
+        panel.h - 20.0f * scale
+    };
+    SDL_SetRenderDrawColor(renderer, 24, 45, 84, 255);
+    SDL_RenderRect(renderer, &insetFrame);
+
+    const float contentPad = 44.0f * scale;
+    float textX = panel.x + contentPad;
+    float contentWidth = panel.w - contentPad * 2.0f;
+    float cursorY = panel.y + contentPad * 0.6f;
+
+    const char* title = "EXIT GAME?";
+    const float titleScale = 2.0f * scale;
+    int titleW = 0, titleH = 0;
+    pixelFont->measure(title, titleScale, titleW, titleH);
+    pixelFont->draw(renderer, textX, cursorY, title, titleScale, SDL_Color{255, 224, 130, 255});
+    cursorY += titleH + 18.0f * scale;
+
+    SDL_SetRenderDrawColor(renderer, 32, 64, 110, 210);
+    SDL_FRect divider{textX, cursorY, contentWidth, 2.0f * scale};
+    SDL_RenderFillRect(renderer, &divider);
+    cursorY += 26.0f * scale;
+
+    const std::array<const char*, 2> lines{
+        "Are you sure you want to quit?",
+        "Current progress will be lost."
+    };
+    const float bodyScale = 1.05f * scale;
+    for (const char* line : lines) {
+        int lineW = 0, lineH = 0;
+        pixelFont->measure(line, bodyScale, lineW, lineH);
+        pixelFont->draw(renderer, textX, cursorY, line, bodyScale, SDL_Color{210, 226, 245, 255});
+        cursorY += lineH + 10.0f * scale;
+    }
+
+    const char* tip = "Enter confirms • Esc returns";
+    const float tipScale = 0.9f * scale;
+    int tipW = 0, tipH = 0;
+    pixelFont->measure(tip, tipScale, tipW, tipH);
+
+    const float buttonGap = 32.0f * scale;
+    const float buttonH = 78.0f * scale;
+    const float buttonW = (contentWidth - buttonGap) * 0.5f;
+    float buttonY = panel.y + panel.h - contentPad - buttonH;
+
+    float tipX = panel.x + (panel.w - tipW) * 0.5f;
+    float tipY = buttonY - tipH - 14.0f * scale;
+    pixelFont->draw(renderer, tipX, tipY, tip, tipScale, SDL_Color{150, 170, 205, 255});
+
+    auto drawButton = [&](int idx, float btnX, SDL_Color baseColor, const char* label) {
+        bool selected = (selectedButton == idx);
+        SDL_FRect btn{btnX, buttonY, buttonW, buttonH};
+        SDL_Color body = baseColor;
+        if (selected) {
+            body.r = Uint8(std::min(255, body.r + 35));
+            body.g = Uint8(std::min(255, body.g + 35));
+            body.b = Uint8(std::min(255, body.b + 35));
+        }
+        SDL_Color border = selected ? SDL_Color{255, 225, 150, 255} : SDL_Color{90, 120, 170, 255};
+        SDL_Color topEdge = SDL_Color{Uint8(std::min(255, body.r + 20)), Uint8(std::min(255, body.g + 20)), Uint8(std::min(255, body.b + 20)), 255};
+
+        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 110);
+        SDL_FRect btnShadow{btn.x + 6.0f * scale, btn.y + 8.0f * scale, btn.w, btn.h};
+        SDL_RenderFillRect(renderer, &btnShadow);
+
+        SDL_SetRenderDrawColor(renderer, body.r, body.g, body.b, body.a);
+        SDL_RenderFillRect(renderer, &btn);
+
+        SDL_FRect topStrip{btn.x, btn.y, btn.w, 6.0f * scale};
+        SDL_SetRenderDrawColor(renderer, topEdge.r, topEdge.g, topEdge.b, topEdge.a);
+        SDL_RenderFillRect(renderer, &topStrip);
+
+        SDL_SetRenderDrawColor(renderer, border.r, border.g, border.b, border.a);
+        SDL_RenderRect(renderer, &btn);
+
+        if (selected) {
+            SDL_SetRenderDrawColor(renderer, 255, 230, 160, 90);
+            SDL_FRect glow{
+                btn.x - 6.0f * scale,
+                btn.y - 6.0f * scale,
+                btn.w + 12.0f * scale,
+                btn.h + 12.0f * scale
+            };
+            SDL_RenderRect(renderer, &glow);
+        }
+
+        const float labelScale = 1.35f * scale;
+        int labelW = 0, labelH = 0;
+        pixelFont->measure(label, labelScale, labelW, labelH);
+        float textX = btn.x + (btn.w - labelW) * 0.5f;
+        float textY = btn.y + (btn.h - labelH) * 0.5f;
+        SDL_Color textColor = selected ? SDL_Color{255, 255, 255, 255} : SDL_Color{235, 238, 250, 255};
+        pixelFont->draw(renderer, textX, textY, label, labelScale, textColor);
+    };
+
+    float yesX = textX;
+    float noX = yesX + buttonW + buttonGap;
+    drawButton(0, yesX, SDL_Color{190, 70, 70, 255}, "YES");
+    drawButton(1, noX, SDL_Color{70, 115, 190, 255}, "NO");
+
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+    SDL_SetRenderViewport(renderer, &oldViewport);
+    SDL_SetRenderScale(renderer, oldScaleX, oldScaleY);
+}
+
+void GameRenderer::renderPauseOverlay(
+    SDL_Renderer* renderer,
+    FontAtlas* pixelFont,
+    float winW,
+    float winH,
+    float logicalScale
+) {
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+
+    // Switch to window coordinates for the full-screen overlay and text
+    SDL_Rect oldViewport;
+    SDL_GetRenderViewport(renderer, &oldViewport);
+    float oldScaleX, oldScaleY;
+    SDL_GetRenderScale(renderer, &oldScaleX, &oldScaleY);
+
+    SDL_SetRenderViewport(renderer, nullptr);
+    SDL_SetRenderScale(renderer, 1.0f, 1.0f);
+
+    // Draw full screen overlay (darken)
+    SDL_SetRenderDrawColor(renderer, 0, 0, 0, 180);
+    SDL_FRect pauseOverlay{0, 0, winW, winH};
+    SDL_RenderFillRect(renderer, &pauseOverlay);
+    
+    // Draw centered text
+    const char* pausedText = "PAUSED";
+    float pausedScale = 2.0f * logicalScale;
+    int pW = 0, pH = 0;
+    pixelFont->measure(pausedText, pausedScale, pW, pH);
+    pixelFont->draw(renderer, (winW - pW) * 0.5f, (winH - pH) * 0.5f - (20 * logicalScale), pausedText, pausedScale, {255, 255, 255, 255});
+    
+    const char* resumeText = "Press P to resume";
+    float resumeScale = 0.8f * logicalScale;
+    int rW = 0, rH = 0;
+    pixelFont->measure(resumeText, resumeScale, rW, rH);
+    pixelFont->draw(renderer, (winW - rW) * 0.5f, (winH - pH) * 0.5f + (40 * logicalScale), resumeText, resumeScale, {200, 200, 220, 255});
+
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_NONE);
+
+    // Restore previous render state
+    SDL_SetRenderViewport(renderer, &oldViewport);
+    SDL_SetRenderScale(renderer, oldScaleX, oldScaleY);
+}
diff --git a/src/graphics/renderers/GameRenderer.h b/src/graphics/renderers/GameRenderer.h
new file mode 100644
index 0000000..04a69b2
--- /dev/null
+++ b/src/graphics/renderers/GameRenderer.h
@@ -0,0 +1,107 @@
+#pragma once
+#include <SDL3/SDL.h>
+#include <vector>
+#include <string>
+#include "../../gameplay/core/Game.h"
+#include "../../gameplay/coop/CoopGame.h"
+
+// Forward declarations
+class FontAtlas;
+class LineEffect;
+
+/**
+ * GameRenderer - Utility class for rendering the Tetris game board and HUD.
+ * 
+ * This class encapsulates all the game-specific rendering logic that was
+ * previously in main.cpp, making it reusable across different contexts.
+ */
+class GameRenderer {
+public:
+    // Render the complete playing state including game board, HUD, and effects
+    static void renderPlayingState(
+        SDL_Renderer* renderer,
+        Game* game,
+        FontAtlas* pixelFont,
+        LineEffect* lineEffect,
+        SDL_Texture* blocksTex,
+        SDL_Texture* asteroidsTex,
+        SDL_Texture* statisticsPanelTex,
+        SDL_Texture* scorePanelTex,
+        SDL_Texture* nextPanelTex,
+        SDL_Texture* holdPanelTex,
+        bool countdownActive,
+        float logicalW,
+        float logicalH,
+        float logicalScale,
+        float winW,
+        float winH,
+        bool challengeClearFxActive = false,
+        const std::vector<int>* challengeClearFxOrder = nullptr,
+        double challengeClearFxElapsedMs = 0.0,
+        double challengeClearFxDurationMs = 0.0,
+        const std::string* challengeStoryText = nullptr,
+        float challengeStoryAlpha = 0.0f
+    );
+
+    // Render the pause overlay (full screen)
+    static void renderPauseOverlay(
+        SDL_Renderer* renderer,
+        FontAtlas* pixelFont,
+        float winW,
+        float winH,
+        float logicalScale
+    );
+
+    // Render the exit confirmation popup
+    static void renderExitPopup(
+        SDL_Renderer* renderer,
+        FontAtlas* pixelFont,
+        float winW,
+        float winH,
+        float logicalScale,
+        int selectedButton
+    );
+
+    static void renderCoopPlayingState(
+        SDL_Renderer* renderer,
+        CoopGame* game,
+        FontAtlas* pixelFont,
+        LineEffect* lineEffect,
+        SDL_Texture* blocksTex,
+        SDL_Texture* statisticsPanelTex,
+        SDL_Texture* scorePanelTex,
+        SDL_Texture* nextPanelTex,
+        SDL_Texture* holdPanelTex,
+        bool paused,
+        float logicalW,
+        float logicalH,
+        float logicalScale,
+        float winW,
+        float winH
+    );
+
+    // Public wrapper that forwards to the private tile-drawing helper. Use this if
+    // calling from non-member helper functions (e.g. visual effects) that cannot
+    // access private class members.
+    static void drawBlockTexturePublic(SDL_Renderer* renderer, SDL_Texture* blocksTex, float x, float y, float size, int blockType);
+    // Transport/teleport visual effect API (public): start a sci-fi "transport" animation
+    // moving a visual copy of `piece` from screen pixel origin (startX,startY) to
+    // target pixel origin (targetX,targetY). `tileSize` should be the same cell size
+    // used for the grid. Duration is seconds.
+    static void startTransportEffect(const Game::Piece& piece, float startX, float startY, float targetX, float targetY, float tileSize, float durationSeconds = 0.6f);
+    // Convenience: compute the preview & grid positions using the same layout math
+    // used by `renderPlayingState` and start the transport effect for the current
+    // `game` using renderer layout parameters.
+    static void startTransportEffectForGame(Game* game, SDL_Texture* blocksTex, float logicalW, float logicalH, float logicalScale, float winW, float winH, float durationSeconds = 0.6f);
+    static bool isTransportActive();
+
+private:
+    // Helper functions for drawing game elements
+    static void drawBlockTexture(SDL_Renderer* renderer, SDL_Texture* blocksTex, float x, float y, float size, int blockType);
+    static void drawPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, const Game::Piece& piece, float ox, float oy, float tileSize, bool isGhost = false, float pixelOffsetX = 0.0f, float pixelOffsetY = 0.0f);
+    static void drawSmallPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, PieceType pieceType, float x, float y, float tileSize);
+    static void renderNextPanel(SDL_Renderer* renderer, FontAtlas* pixelFont, SDL_Texture* blocksTex, SDL_Texture* nextPanelTex, const Game::Piece& nextPiece, float panelX, float panelY, float panelW, float panelH, float tileSize);
+    
+    // Helper function for drawing rectangles
+    static void drawRect(SDL_Renderer* renderer, float x, float y, float w, float h, SDL_Color c);
+};
diff --git a/src/graphics/renderers/RenderManager.cpp b/src/graphics/renderers/RenderManager.cpp
new file mode 100644
index 0000000..396538b
--- /dev/null
+++ b/src/graphics/renderers/RenderManager.cpp
@@ -0,0 +1,328 @@
+#include "RenderManager.h"
+#include <SDL3/SDL.h>
+#include <algorithm>
+
+RenderManager::RenderManager() = default;
+
+RenderManager::~RenderManager() {
+    if (m_initialized) {
+        shutdown();
+    }
+}
+
+bool RenderManager::initialize(int width, int height, const std::string& title) {
+    if (m_initialized) {
+        SDL_LogWarn(SDL_LOG_CATEGORY_RENDER, "RenderManager already initialized");
+        return true;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "Initializing RenderManager (%dx%d)", width, height);
+
+    // Create window
+    m_window = SDL_CreateWindow(
+        title.c_str(),
+        width, height,
+        SDL_WINDOW_RESIZABLE
+    );
+
+    if (!m_window) {
+        SDL_LogError(SDL_LOG_CATEGORY_RENDER, "Failed to create window: %s", SDL_GetError());
+        return false;
+    }
+
+    // Create renderer
+    m_renderer = SDL_CreateRenderer(m_window, nullptr);
+    if (!m_renderer) {
+        SDL_LogError(SDL_LOG_CATEGORY_RENDER, "Failed to create renderer: %s", SDL_GetError());
+        SDL_DestroyWindow(m_window);
+        m_window = nullptr;
+        return false;
+    }
+
+    // Enable VSync
+    SDL_SetRenderVSync(m_renderer, 1);
+
+    // Store window dimensions
+    m_windowWidth = width;
+    m_windowHeight = height;
+    m_logicalWidth = width;
+    m_logicalHeight = height;
+
+    // Set initial logical size
+    setLogicalSize(width, height);
+
+    m_initialized = true;
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "RenderManager initialized successfully");
+    return true;
+}
+
+void RenderManager::shutdown() {
+    if (!m_initialized) {
+        return;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "Shutting down RenderManager");
+
+    if (m_renderer) {
+        SDL_DestroyRenderer(m_renderer);
+        m_renderer = nullptr;
+    }
+
+    if (m_window) {
+        SDL_DestroyWindow(m_window);
+        m_window = nullptr;
+    }
+
+    m_initialized = false;
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "RenderManager shutdown complete");
+}
+
+void RenderManager::beginFrame() {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    // Trace beginFrame entry
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::beginFrame entry\n"); fclose(f); }
+    }
+
+    // Clear the screen (wrapped with trace)
+    clear(12, 12, 16, 255); // Dark background similar to original
+
+    // Trace after clear
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::beginFrame after clear\n"); fclose(f); }
+    }
+}
+
+void RenderManager::endFrame() {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+    // Trace before present
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::endFrame before present\n"); fclose(f); }
+    }
+
+    SDL_RenderPresent(m_renderer);
+
+    // Trace after present
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::endFrame after present\n"); fclose(f); }
+    }
+}
+
+void RenderManager::setLogicalSize(int width, int height) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    m_logicalWidth = width;
+    m_logicalHeight = height;
+    updateLogicalScale();
+}
+
+void RenderManager::setViewport(int x, int y, int width, int height) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_Rect viewport = { x, y, width, height };
+    SDL_SetRenderViewport(m_renderer, &viewport);
+    // Keep cached logical viewport in sync if this matches our computed logical scale
+    m_logicalVP = viewport;
+}
+
+void RenderManager::setScale(float scaleX, float scaleY) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    m_scaleX = scaleX;
+    m_scaleY = scaleY;
+    SDL_SetRenderScale(m_renderer, scaleX, scaleY);
+}
+
+void RenderManager::resetViewport() {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    // Reset to full window viewport and recompute logical scale/viewport
+    SDL_SetRenderViewport(m_renderer, nullptr);
+    updateLogicalScale();
+}
+
+// IRenderer interface implementation
+void RenderManager::clearScreen(uint8_t r, uint8_t g, uint8_t b, uint8_t a) {
+    clear(static_cast<Uint8>(r), static_cast<Uint8>(g), static_cast<Uint8>(b), static_cast<Uint8>(a));
+}
+
+void RenderManager::present() {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+    
+    SDL_RenderPresent(m_renderer);
+}
+
+SDL_Renderer* RenderManager::getSDLRenderer() {
+    return m_renderer;
+}
+
+void RenderManager::getWindowDimensions(int& width, int& height) const {
+    getWindowSize(width, height);
+}
+
+void RenderManager::setViewport(const SDL_Rect* viewport) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+    
+    SDL_SetRenderViewport(m_renderer, viewport);
+}
+
+// Legacy clear method
+void RenderManager::clear(Uint8 r, Uint8 g, Uint8 b, Uint8 a) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_SetRenderDrawColor(m_renderer, r, g, b, a);
+    SDL_RenderClear(m_renderer);
+}
+
+void RenderManager::renderTexture(SDL_Texture* texture, const SDL_FRect* src, const SDL_FRect* dst) {
+    if (!m_initialized || !m_renderer || !texture) {
+        return;
+    }
+
+    // Trace renderTexture usage
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::renderTexture entry tex=%llu src=%p dst=%p\n", (unsigned long long)(uintptr_t)texture, (void*)src, (void*)dst); fclose(f); }
+    }
+    SDL_RenderTexture(m_renderer, texture, src, dst);
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "RenderManager::renderTexture after SDL_RenderTexture tex=%llu\n", (unsigned long long)(uintptr_t)texture); fclose(f); }
+    }
+}
+
+void RenderManager::renderTexture(SDL_Texture* texture, float x, float y) {
+    if (!texture) {
+        return;
+    }
+
+    float w, h;
+    SDL_GetTextureSize(texture, &w, &h);
+    SDL_FRect dst = { x, y, w, h };
+    renderTexture(texture, nullptr, &dst);
+}
+
+void RenderManager::renderTexture(SDL_Texture* texture, float x, float y, float w, float h) {
+    if (!texture) {
+        return;
+    }
+
+    SDL_FRect dst = { x, y, w, h };
+    renderTexture(texture, nullptr, &dst);
+}
+
+void RenderManager::renderRect(const SDL_FRect& rect, Uint8 r, Uint8 g, Uint8 b, Uint8 a) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_SetRenderDrawColor(m_renderer, r, g, b, a);
+    SDL_RenderFillRect(m_renderer, &rect);
+}
+
+void RenderManager::renderLine(float x1, float y1, float x2, float y2, Uint8 r, Uint8 g, Uint8 b, Uint8 a) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_SetRenderDrawColor(m_renderer, r, g, b, a);
+    SDL_RenderLine(m_renderer, x1, y1, x2, y2);
+}
+
+void RenderManager::renderPoint(float x, float y, Uint8 r, Uint8 g, Uint8 b, Uint8 a) {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    SDL_SetRenderDrawColor(m_renderer, r, g, b, a);
+    SDL_RenderPoint(m_renderer, x, y);
+}
+
+void RenderManager::handleWindowResize(int newWidth, int newHeight) {
+    if (!m_initialized) {
+        return;
+    }
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_RENDER, "Window resized to %dx%d", newWidth, newHeight);
+    
+    m_windowWidth = newWidth;
+    m_windowHeight = newHeight;
+    updateLogicalScale();
+}
+
+void RenderManager::setFullscreen(bool fullscreen) {
+    if (!m_initialized || !m_window) {
+        return;
+    }
+
+    if (m_isFullscreen == fullscreen) {
+        return;
+    }
+
+    SDL_SetWindowFullscreen(m_window, fullscreen ? SDL_WINDOW_FULLSCREEN : 0);
+    m_isFullscreen = fullscreen;
+
+    // Update window size after fullscreen change
+    SDL_GetWindowSize(m_window, &m_windowWidth, &m_windowHeight);
+    updateLogicalScale();
+}
+
+void RenderManager::getWindowSize(int& width, int& height) const {
+    width = m_windowWidth;
+    height = m_windowHeight;
+}
+
+void RenderManager::getTextureSize(SDL_Texture* tex, int& w, int& h) const {
+    if (!tex) { w = 0; h = 0; return; }
+    // SDL3 provides SDL_GetTextureSize which accepts float or int pointers depending on overloads
+    float fw = 0.0f, fh = 0.0f;
+    SDL_GetTextureSize(tex, &fw, &fh);
+    w = int(fw + 0.5f);
+    h = int(fh + 0.5f);
+}
+
+void RenderManager::updateLogicalScale() {
+    if (!m_initialized || !m_renderer) {
+        return;
+    }
+
+    // Calculate scale to fit logical size into window
+    float scaleX = static_cast<float>(m_windowWidth) / static_cast<float>(m_logicalWidth);
+    float scaleY = static_cast<float>(m_windowHeight) / static_cast<float>(m_logicalHeight);
+    
+    // Use uniform scaling to maintain aspect ratio
+    float scale = std::min(scaleX, scaleY);
+    if (scale <= 0.0f) {
+        scale = 1.0f;
+    }
+
+    setScale(scale, scale);
+    // Compute centered logical viewport that preserves aspect ratio and is centered in window
+    int vpW = static_cast<int>(m_logicalWidth * scale);
+    int vpH = static_cast<int>(m_logicalHeight * scale);
+    int vpX = (m_windowWidth - vpW) / 2;
+    int vpY = (m_windowHeight - vpH) / 2;
+    SDL_Rect vp{ vpX, vpY, vpW, vpH };
+    SDL_SetRenderViewport(m_renderer, &vp);
+
+    // Cache logical viewport and scale for callers
+    m_logicalVP = vp;
+    m_logicalScale = scale;
+}
diff --git a/src/graphics/renderers/RenderManager.h b/src/graphics/renderers/RenderManager.h
new file mode 100644
index 0000000..5ae67e8
--- /dev/null
+++ b/src/graphics/renderers/RenderManager.h
@@ -0,0 +1,95 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+#include <string>
+#include "../../core/interfaces/IRenderer.h"
+
+/**
+ * RenderManager - Abstracts SDL rendering functionality
+ * 
+ * Responsibilities:
+ * - Manage SDL_Window and SDL_Renderer lifecycle
+ * - Provide high-level rendering interface
+ * - Handle viewport and scaling logic
+ * - Abstract SDL-specific details from game code
+ */
+class RenderManager : public IRenderer {
+public:
+    RenderManager();
+    ~RenderManager();
+
+    // Initialization and cleanup
+    bool initialize(int width, int height, const std::string& title);
+    void shutdown();
+
+    // Frame management
+    void beginFrame();
+    void endFrame();
+
+    // IRenderer interface implementation
+    void clearScreen(uint8_t r, uint8_t g, uint8_t b, uint8_t a) override;
+    void present() override;
+    SDL_Renderer* getSDLRenderer() override;
+    void getWindowDimensions(int& width, int& height) const override;
+    void setViewport(const SDL_Rect* viewport) override;
+    void setScale(float scaleX, float scaleY) override;
+
+    // Additional RenderManager-specific methods
+    void setLogicalSize(int width, int height);
+    void setViewport(int x, int y, int width, int height);
+    void resetViewport();
+
+    // Query the computed logical viewport and scale (useful for consistent input mapping)
+    SDL_Rect getLogicalViewport() const { return m_logicalVP; }
+    float getLogicalScale() const { return m_logicalScale; }
+
+    // Basic rendering operations (legacy method signature)
+    void clear(Uint8 r = 0, Uint8 g = 0, Uint8 b = 0, Uint8 a = 255);
+    
+    // Texture rendering
+    void renderTexture(SDL_Texture* texture, const SDL_FRect* src, const SDL_FRect* dst);
+    void renderTexture(SDL_Texture* texture, float x, float y);
+    void renderTexture(SDL_Texture* texture, float x, float y, float w, float h);
+
+    // Primitive rendering
+    void renderRect(const SDL_FRect& rect, Uint8 r, Uint8 g, Uint8 b, Uint8 a = 255);
+    void renderLine(float x1, float y1, float x2, float y2, Uint8 r, Uint8 g, Uint8 b, Uint8 a = 255);
+    void renderPoint(float x, float y, Uint8 r, Uint8 g, Uint8 b, Uint8 a = 255);
+
+    // Window management
+    void handleWindowResize(int newWidth, int newHeight);
+    void setFullscreen(bool fullscreen);
+    void getWindowSize(int& width, int& height) const;
+
+    // Direct access to SDL objects (temporary, will be removed later)
+    SDL_Window* getSDLWindow() const { return m_window; }
+    // Texture queries
+    void getTextureSize(SDL_Texture* tex, int& w, int& h) const;
+
+    // State queries
+    bool isInitialized() const { return m_initialized; }
+    bool isFullscreen() const { return m_isFullscreen; }
+
+private:
+    // SDL objects
+    SDL_Window* m_window = nullptr;
+    SDL_Renderer* m_renderer = nullptr;
+
+    // Window properties
+    int m_windowWidth = 0;
+    int m_windowHeight = 0;
+    int m_logicalWidth = 0;
+    int m_logicalHeight = 0;
+    float m_scaleX = 1.0f;
+    float m_scaleY = 1.0f;
+    
+    // State
+    bool m_initialized = false;
+    bool m_isFullscreen = false;
+    // Cached logical viewport and scale (centered within window)
+    SDL_Rect m_logicalVP{0,0,0,0};
+    float m_logicalScale = 1.0f;
+    
+    // Helper methods
+    void updateLogicalScale();
+};
diff --git a/src/graphics/renderers/RenderPrimitives.h b/src/graphics/renderers/RenderPrimitives.h
new file mode 100644
index 0000000..5836ce2
--- /dev/null
+++ b/src/graphics/renderers/RenderPrimitives.h
@@ -0,0 +1,16 @@
+#pragma once
+
+#include <SDL3/SDL.h>
+
+namespace RenderPrimitives {
+
+inline void fillRect(SDL_Renderer* renderer, float x, float y, float w, float h, SDL_Color color) {
+    if (!renderer) {
+        return;
+    }
+    SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, color.a);
+    SDL_FRect rect{x, y, w, h};
+    SDL_RenderFillRect(renderer, &rect);
+}
+
+} // namespace RenderPrimitives
diff --git a/src/graphics/renderers/SyncLineRenderer.cpp b/src/graphics/renderers/SyncLineRenderer.cpp
new file mode 100644
index 0000000..bf15bd6
--- /dev/null
+++ b/src/graphics/renderers/SyncLineRenderer.cpp
@@ -0,0 +1,358 @@
+#include "SyncLineRenderer.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdlib>
+
+SyncLineRenderer::SyncLineRenderer()
+    : m_state(SyncState::Idle),
+      m_flashTimer(0.0f),
+            m_time(0.0f) {
+        m_particles.reserve(MAX_PARTICLES);
+}
+
+static float syncWobbleX(float t) {
+    // Small, smooth horizontal motion to make the conduit feel fluid.
+    // Kept subtle so it doesn't distract from gameplay.
+    return std::sinf(t * 2.1f) * 1.25f + std::sinf(t * 5.2f + 1.3f) * 0.55f;
+}
+
+void SyncLineRenderer::SpawnParticle() {
+    if (m_particles.size() >= MAX_PARTICLES) {
+        return;
+    }
+
+    SyncParticle p;
+    const float centerX = (m_rect.x + (m_rect.w * 0.5f)) + syncWobbleX(m_time);
+    // Spawn around the beam center so it reads like a conduit.
+    const float jitter = -8.0f + static_cast<float>(std::rand() % 17);
+
+    p.x = centerX + jitter;
+    p.y = m_rect.y + m_rect.h + static_cast<float>(std::rand() % 10);
+
+    // Two styles: tiny sparkle dots + short streaks.
+    const bool dot = (std::rand() % 100) < 35;
+    if (dot) {
+        p.vx = (-18.0f + static_cast<float>(std::rand() % 37));
+        p.vy = 180.0f + static_cast<float>(std::rand() % 180);
+        p.w = 1.0f + static_cast<float>(std::rand() % 2);
+        p.h = 1.0f + static_cast<float>(std::rand() % 2);
+        p.alpha = 240.0f;
+    } else {
+        p.vx = (-14.0f + static_cast<float>(std::rand() % 29));
+        p.vy = 160.0f + static_cast<float>(std::rand() % 200);
+        p.w = 1.0f + static_cast<float>(std::rand() % 3);
+        p.h = 3.0f + static_cast<float>(std::rand() % 10);
+        p.alpha = 220.0f;
+    }
+
+    // Slight color variance (cyan/green/white) to keep it energetic.
+    const int roll = std::rand() % 100;
+    if (roll < 55) {
+        p.color = SDL_Color{110, 255, 210, 255};
+    } else if (roll < 90) {
+        p.color = SDL_Color{120, 210, 255, 255};
+    } else {
+        p.color = SDL_Color{255, 255, 255, 255};
+    }
+
+    m_particles.push_back(p);
+}
+
+void SyncLineRenderer::SpawnBurst(int count) {
+    for (int i = 0; i < count; ++i) {
+        SpawnParticle();
+    }
+}
+
+void SyncLineRenderer::SetRect(const SDL_FRect& rect) {
+    m_rect = rect;
+}
+
+void SyncLineRenderer::SetState(SyncState state) {
+    if (state != SyncState::ClearFlash) {
+        m_state = state;
+    }
+}
+
+void SyncLineRenderer::TriggerClearFlash() {
+    m_state = SyncState::ClearFlash;
+    m_flashTimer = FLASH_DURATION;
+
+    // Reward burst: strong visual feedback on cooperative clear.
+    SpawnBurst(56);
+}
+
+void SyncLineRenderer::Update(float deltaTime) {
+    m_time += deltaTime;
+    m_pulseTime += deltaTime;
+
+    // State-driven particle spawning
+    float spawnRatePerSec = 0.0f;
+    int particlesPerSpawn = 1;
+    switch (m_state) {
+        case SyncState::LeftReady:
+        case SyncState::RightReady:
+            spawnRatePerSec = 24.0f;  // steady
+            break;
+        case SyncState::Synced:
+            spawnRatePerSec = 78.0f;  // very heavy stream
+            particlesPerSpawn = 2;
+            break;
+        default:
+            spawnRatePerSec = 18.0f;  // always-on sparkle stream
+            break;
+    }
+
+    if (spawnRatePerSec <= 0.0f) {
+        m_spawnAcc = 0.0f;
+    } else {
+        m_spawnAcc += deltaTime * spawnRatePerSec;
+        while (m_spawnAcc >= 1.0f) {
+            m_spawnAcc -= 1.0f;
+            for (int i = 0; i < particlesPerSpawn; ++i) {
+                SpawnParticle();
+            }
+        }
+    }
+
+    // Update particles
+    for (auto& p : m_particles) {
+        p.x += p.vx * deltaTime;
+        p.y -= p.vy * deltaTime;
+        // Slow drift & fade.
+        p.vx *= (1.0f - 0.35f * deltaTime);
+        p.alpha -= 115.0f * deltaTime;
+    }
+    std::erase_if(m_particles, [&](const SyncParticle& p) {
+        // Cull when out of view or too far from the beam.
+        const float centerX = (m_rect.x + (m_rect.w * 0.5f)) + syncWobbleX(m_time);
+        const float maxDx = 18.0f;
+        return (p.y < (m_rect.y - 16.0f)) || p.alpha <= 0.0f || std::fabs(p.x - centerX) > maxDx;
+    });
+
+    if (m_state == SyncState::ClearFlash) {
+        m_flashTimer -= deltaTime;
+        if (m_flashTimer <= 0.0f) {
+            m_state = SyncState::Idle;
+            m_flashTimer = 0.0f;
+        }
+    }
+}
+
+SDL_Color SyncLineRenderer::GetBaseColor() const {
+    switch (m_state) {
+        case SyncState::LeftReady:
+        case SyncState::RightReady:
+            return SDL_Color{255, 220, 100, 235};
+
+        case SyncState::Synced:
+            return SDL_Color{100, 255, 120, 240};
+
+        case SyncState::ClearFlash:
+            return SDL_Color{255, 255, 255, 255};
+
+        default:
+            return SDL_Color{80, 180, 255, 235};
+    }
+}
+
+void SyncLineRenderer::Render(SDL_Renderer* renderer) {
+    if (!renderer) {
+        return;
+    }
+
+    // We render the conduit with lots of translucent layers. Using additive blending
+    // for glow/pulse makes it read like a blurred beam without shaders.
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+
+    const float wobbleX = syncWobbleX(m_time);
+    const float centerX = (m_rect.x + (m_rect.w * 0.5f)) + wobbleX;
+    const float h = m_rect.h;
+    const float hotspotH = std::clamp(h * 0.12f, 18.0f, 44.0f);
+
+    // Flash factor (0..1)
+    const float flashT = (m_state == SyncState::ClearFlash && FLASH_DURATION > 0.0f)
+                             ? std::clamp(m_flashTimer / FLASH_DURATION, 0.0f, 1.0f)
+                             : 0.0f;
+
+    SDL_Color color = GetBaseColor();
+
+    // Synced pulse drives aura + core intensity.
+    float pulse01 = 0.0f;
+    if (m_state == SyncState::Synced) {
+        pulse01 = 0.5f + 0.5f * std::sinf(m_time * 6.0f);
+    }
+
+    // 1) Outer aura layers (bloom-like using rectangles)
+    auto drawGlow = [&](float extraW, Uint8 a, SDL_Color c) {
+        SDL_FRect fr{
+            centerX - (m_rect.w + extraW) * 0.5f,
+            m_rect.y,
+            m_rect.w + extraW,
+            m_rect.h
+        };
+        SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, a);
+        SDL_RenderFillRect(renderer, &fr);
+    };
+
+    SDL_Color aura = color;
+    // Slightly bias aura towards cyan so it reads “energy conduit”.
+    aura.r = static_cast<Uint8>(std::min(255, static_cast<int>(aura.r) + 10));
+    aura.g = static_cast<Uint8>(std::min(255, static_cast<int>(aura.g) + 10));
+    aura.b = static_cast<Uint8>(std::min(255, static_cast<int>(aura.b) + 35));
+
+    const float auraBoost = (m_state == SyncState::Synced) ? (0.70f + 0.80f * pulse01) : 0.70f;
+    const float flashBoost = 1.0f + flashT * 1.45f;
+
+    SDL_BlendMode oldBlend = SDL_BLENDMODE_BLEND;
+    SDL_GetRenderDrawBlendMode(renderer, &oldBlend);
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_ADD);
+
+    SDL_Color auraOuter = aura;
+    auraOuter.r = static_cast<Uint8>(std::min(255, static_cast<int>(auraOuter.r) + 10));
+    auraOuter.g = static_cast<Uint8>(std::min(255, static_cast<int>(auraOuter.g) + 5));
+    auraOuter.b = static_cast<Uint8>(std::min(255, static_cast<int>(auraOuter.b) + 55));
+
+    SDL_Color auraInner = aura;
+    auraInner.r = static_cast<Uint8>(std::min(255, static_cast<int>(auraInner.r) + 40));
+    auraInner.g = static_cast<Uint8>(std::min(255, static_cast<int>(auraInner.g) + 40));
+    auraInner.b = static_cast<Uint8>(std::min(255, static_cast<int>(auraInner.b) + 70));
+
+    // Wider + softer outer halo, then tighter inner glow.
+    drawGlow(62.0f, static_cast<Uint8>(std::clamp(12.0f * auraBoost * flashBoost, 0.0f, 255.0f)), auraOuter);
+    drawGlow(44.0f, static_cast<Uint8>(std::clamp(20.0f * auraBoost * flashBoost, 0.0f, 255.0f)), auraOuter);
+    drawGlow(30.0f, static_cast<Uint8>(std::clamp(34.0f * auraBoost * flashBoost, 0.0f, 255.0f)), auraOuter);
+    drawGlow(18.0f, static_cast<Uint8>(std::clamp(54.0f * auraBoost * flashBoost, 0.0f, 255.0f)), auraInner);
+    drawGlow(10.0f, static_cast<Uint8>(std::clamp(78.0f * auraBoost * flashBoost, 0.0f, 255.0f)), auraInner);
+
+    // 2) Hotspots near top/bottom (adds that “powered endpoints” vibe)
+    SDL_Color hot = auraInner;
+    hot.r = static_cast<Uint8>(std::min(255, static_cast<int>(hot.r) + 35));
+    hot.g = static_cast<Uint8>(std::min(255, static_cast<int>(hot.g) + 35));
+    hot.b = static_cast<Uint8>(std::min(255, static_cast<int>(hot.b) + 35));
+    {
+        const float hotW1 = 34.0f;
+        const float hotW2 = 18.0f;
+        SDL_FRect topHot1{ centerX - (m_rect.w + hotW1) * 0.5f, m_rect.y, m_rect.w + hotW1, hotspotH };
+        SDL_FRect botHot1{ centerX - (m_rect.w + hotW1) * 0.5f, m_rect.y + m_rect.h - hotspotH, m_rect.w + hotW1, hotspotH };
+        SDL_FRect topHot2{ centerX - (m_rect.w + hotW2) * 0.5f, m_rect.y + hotspotH * 0.12f, m_rect.w + hotW2, hotspotH * 0.78f };
+        SDL_FRect botHot2{ centerX - (m_rect.w + hotW2) * 0.5f, m_rect.y + m_rect.h - hotspotH * 0.90f, m_rect.w + hotW2, hotspotH * 0.78f };
+
+        Uint8 ha1 = static_cast<Uint8>(std::clamp((m_state == SyncState::Synced ? 85.0f : 55.0f) * flashBoost, 0.0f, 255.0f));
+        Uint8 ha2 = static_cast<Uint8>(std::clamp((m_state == SyncState::Synced ? 130.0f : 90.0f) * flashBoost, 0.0f, 255.0f));
+        SDL_SetRenderDrawColor(renderer, hot.r, hot.g, hot.b, ha1);
+        SDL_RenderFillRect(renderer, &topHot1);
+        SDL_RenderFillRect(renderer, &botHot1);
+        SDL_SetRenderDrawColor(renderer, 255, 255, 255, ha2);
+        SDL_RenderFillRect(renderer, &topHot2);
+        SDL_RenderFillRect(renderer, &botHot2);
+    }
+
+    // 3) Synced pulse wave (a travelling “breath” around the beam)
+    if (m_state == SyncState::Synced) {
+        float wave = std::fmod(m_pulseTime * 2.4f, 1.0f);
+        float width = 10.0f + wave * 26.0f;
+        Uint8 alpha = static_cast<Uint8>(std::clamp(150.0f * (1.0f - wave) * flashBoost, 0.0f, 255.0f));
+
+        SDL_FRect waveRect{
+            centerX - (m_rect.w + width) * 0.5f,
+            m_rect.y,
+            m_rect.w + width,
+            m_rect.h
+        };
+
+        SDL_SetRenderDrawColor(renderer, 140, 255, 220, alpha);
+        SDL_RenderFillRect(renderer, &waveRect);
+    }
+
+    // 4) Shimmer bands (stylish motion inside the conduit)
+    {
+        const int bands = 7;
+        const float speed = (m_state == SyncState::Synced) ? 160.0f : 95.0f;
+        const float bandW = m_rect.w + 12.0f;
+        for (int i = 0; i < bands; ++i) {
+            const float phase = (static_cast<float>(i) / static_cast<float>(bands));
+            const float y = m_rect.y + std::fmod(m_time * speed + phase * h, h);
+            const float fade = 0.35f + 0.65f * std::sinf((m_time * 2.1f) + phase * 6.28318f);
+            const float bandH = 2.0f + (phase * 2.0f);
+            Uint8 a = static_cast<Uint8>(std::clamp((26.0f + 36.0f * pulse01) * std::fabs(fade) * flashBoost, 0.0f, 255.0f));
+            SDL_FRect fr{ centerX - bandW * 0.5f, y, bandW, bandH };
+            SDL_SetRenderDrawColor(renderer, 200, 255, 255, a);
+            SDL_RenderFillRect(renderer, &fr);
+        }
+    }
+
+    // 5) Core beam (thin bright core + thicker body with horizontal gradient)
+    Uint8 bodyA = color.a;
+    if (m_state == SyncState::Synced) {
+        bodyA = static_cast<Uint8>(std::clamp(175.0f + pulse01 * 75.0f, 0.0f, 255.0f));
+    }
+    // Keep the center more translucent; let glow carry intensity.
+    bodyA = static_cast<Uint8>(std::clamp(bodyA * (0.72f + flashT * 0.35f), 0.0f, 255.0f));
+
+    // Render a smooth-looking body by stacking a few vertical strips.
+    // This approximates a gradient (bright center -> soft edges) without shaders.
+    {
+        // Allow thinner beam while keeping gradient readable.
+        const float bodyW = std::max(4.0f, m_rect.w);
+        const float x0 = centerX - bodyW * 0.5f;
+
+        SDL_FRect left{ x0, m_rect.y, bodyW * 0.34f, m_rect.h };
+        SDL_FRect mid{ x0 + bodyW * 0.34f, m_rect.y, bodyW * 0.32f, m_rect.h };
+        SDL_FRect right{ x0 + bodyW * 0.66f, m_rect.y, bodyW * 0.34f, m_rect.h };
+
+        SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, static_cast<Uint8>(std::clamp(bodyA * 0.60f, 0.0f, 255.0f)));
+        SDL_RenderFillRect(renderer, &left);
+        SDL_RenderFillRect(renderer, &right);
+
+        SDL_SetRenderDrawColor(renderer,
+                               static_cast<Uint8>(std::min(255, static_cast<int>(color.r) + 35)),
+                               static_cast<Uint8>(std::min(255, static_cast<int>(color.g) + 35)),
+                               static_cast<Uint8>(std::min(255, static_cast<int>(color.b) + 55)),
+                               static_cast<Uint8>(std::clamp(bodyA * 0.88f, 0.0f, 255.0f)));
+        SDL_RenderFillRect(renderer, &mid);
+    }
+
+    SDL_FRect coreRect{ centerX - 1.1f, m_rect.y, 2.2f, m_rect.h };
+    Uint8 coreA = static_cast<Uint8>(std::clamp(210.0f + pulse01 * 70.0f + flashT * 95.0f, 0.0f, 255.0f));
+    SDL_SetRenderDrawColor(renderer, 255, 255, 255, coreA);
+    SDL_RenderFillRect(renderer, &coreRect);
+
+    // Switch back to normal alpha blend for particles so they stay readable.
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+
+    // 6) Energy particles (sparks/streaks traveling upward)
+    for (const auto& p : m_particles) {
+        Uint8 a = static_cast<Uint8>(std::clamp(p.alpha, 0.0f, 255.0f));
+
+        // Add a tiny sinusoidal sway so the stream feels alive.
+        const float sway = std::sinf((p.y * 0.045f) + (m_time * 6.2f)) * 0.9f;
+        SDL_FRect spark{ (p.x + sway) - (p.w * 0.5f), p.y, p.w, p.h };
+        SDL_SetRenderDrawColor(renderer, p.color.r, p.color.g, p.color.b, a);
+        SDL_RenderFillRect(renderer, &spark);
+
+        // A little aura around each spark helps it read at speed.
+        if (a > 40) {
+            SDL_FRect sparkGlow{ spark.x - 1.0f, spark.y - 1.0f, spark.w + 2.0f, spark.h + 2.0f };
+            SDL_SetRenderDrawColor(renderer, p.color.r, p.color.g, p.color.b, static_cast<Uint8>(a * 0.35f));
+            SDL_RenderFillRect(renderer, &sparkGlow);
+        }
+    }
+
+    // 7) Flash/glow overlay (adds “clear burst” punch)
+    if (m_state == SyncState::ClearFlash) {
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_ADD);
+
+        const float extra = 74.0f;
+        SDL_FRect glow{ centerX - (m_rect.w + extra) * 0.5f, m_rect.y, m_rect.w + extra, m_rect.h };
+        Uint8 ga = static_cast<Uint8>(std::clamp(90.0f + 140.0f * flashT, 0.0f, 255.0f));
+        SDL_SetRenderDrawColor(renderer, 255, 255, 255, ga);
+        SDL_RenderFillRect(renderer, &glow);
+
+        SDL_SetRenderDrawBlendMode(renderer, oldBlend);
+    }
+
+    // Restore whatever blend mode the caller had.
+    SDL_SetRenderDrawBlendMode(renderer, oldBlend);
+}
diff --git a/src/graphics/renderers/SyncLineRenderer.h b/src/graphics/renderers/SyncLineRenderer.h
new file mode 100644
index 0000000..2a256fb
--- /dev/null
+++ b/src/graphics/renderers/SyncLineRenderer.h
@@ -0,0 +1,54 @@
+#pragma once
+#include <SDL3/SDL.h>
+
+#include <vector>
+
+enum class SyncState {
+    Idle,
+    LeftReady,
+    RightReady,
+    Synced,
+    ClearFlash
+};
+
+class SyncLineRenderer {
+public:
+    SyncLineRenderer();
+
+    void SetRect(const SDL_FRect& rect);
+    void SetState(SyncState state);
+    void TriggerClearFlash();
+
+    void Update(float deltaTime);
+    void Render(SDL_Renderer* renderer);
+
+private:
+    struct SyncParticle {
+        float x;
+        float y;
+        float vx;
+        float vy;
+        float w;
+        float h;
+        float alpha;
+        SDL_Color color;
+    };
+
+    SDL_FRect m_rect{};
+    SyncState m_state;
+
+    float m_flashTimer;
+    float m_time;
+
+    float m_pulseTime{0.0f};
+    float m_spawnAcc{0.0f};
+    std::vector<SyncParticle> m_particles;
+
+    static constexpr float FLASH_DURATION = 0.15f;
+    static constexpr size_t MAX_PARTICLES = 240;
+
+    void SpawnParticle();
+    void SpawnBurst(int count);
+
+    SDL_Color GetBaseColor() const;
+};
diff --git a/src/graphics/renderers/UIRenderer.cpp b/src/graphics/renderers/UIRenderer.cpp
new file mode 100644
index 0000000..f6e976b
--- /dev/null
+++ b/src/graphics/renderers/UIRenderer.cpp
@@ -0,0 +1,237 @@
+#include "UIRenderer.h"
+#include "../ui/Font.h"
+#include <algorithm>
+#include <cmath>
+
+void UIRenderer::drawSciFiPanel(SDL_Renderer* renderer, const SDL_FRect& rect, float alpha) {
+    if (!renderer) return;
+
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+    Uint8 alphaUint = static_cast<Uint8>(std::clamp(alpha * 255.0f, 0.0f, 255.0f));
+
+    // Drop shadow
+    SDL_FRect shadow{rect.x + 6.0f, rect.y + 10.0f, rect.w, rect.h};
+    SDL_SetRenderDrawColor(renderer, 0, 0, 0, static_cast<Uint8>(120.0f * alpha));
+    SDL_RenderFillRect(renderer, &shadow);
+
+    // Glow aura
+    for (int i = 0; i < 5; ++i) {
+        SDL_FRect glow{rect.x - float(i * 2), rect.y - float(i * 2), rect.w + float(i * 4), rect.h + float(i * 4)};
+        Uint8 glowAlpha = static_cast<Uint8>((42 - i * 8) * alpha);
+        SDL_SetRenderDrawColor(renderer, 0, 180, 255, glowAlpha);
+        SDL_RenderRect(renderer, &glow);
+    }
+
+    // Body
+    SDL_SetRenderDrawColor(renderer, 18, 30, 52, alphaUint);
+    SDL_RenderFillRect(renderer, &rect);
+
+    // Border
+    SDL_SetRenderDrawColor(renderer, 70, 120, 210, alphaUint);
+    SDL_RenderRect(renderer, &rect);
+}
+
+void UIRenderer::drawButton(SDL_Renderer* renderer, FontAtlas* font, float cx, float cy, float w, float h, 
+                           const std::string& label, bool isHovered, bool isSelected, 
+                           SDL_Color bgColor, SDL_Color borderColor, bool textOnly, SDL_Texture* icon) {
+    if (!renderer) return;
+
+    float x = cx - w * 0.5f;
+    float y = cy - h * 0.5f;
+
+    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+
+    // In "textOnly" mode we don't draw a full button body (the art may be in the background image),
+    // but we still add a subtle highlight so hover/selection feels intentional.
+    if (textOnly && (isHovered || isSelected)) {
+        Uint8 outlineA = isSelected ? 170 : 110;
+        Uint8 fillA = isSelected ? 60 : 32;
+
+        SDL_Color hl = borderColor;
+        hl.a = outlineA;
+        SDL_SetRenderDrawColor(renderer, hl.r, hl.g, hl.b, hl.a);
+        SDL_FRect o1{x - 3.0f, y - 3.0f, w + 6.0f, h + 6.0f};
+        SDL_RenderRect(renderer, &o1);
+        SDL_FRect o2{x - 6.0f, y - 6.0f, w + 12.0f, h + 12.0f};
+        SDL_SetRenderDrawColor(renderer, hl.r, hl.g, hl.b, static_cast<Uint8>(std::max(0, (int)hl.a - 60)));
+        SDL_RenderRect(renderer, &o2);
+
+        SDL_Color fill = bgColor;
+        fill.a = fillA;
+        SDL_SetRenderDrawColor(renderer, fill.r, fill.g, fill.b, fill.a);
+        SDL_FRect f{x, y, w, h};
+        SDL_RenderFillRect(renderer, &f);
+    }
+
+    if (!textOnly) {
+        // Adjust colors based on state
+        if (isSelected) {
+            // Keep caller-provided colors; just add a stronger glow.
+            SDL_SetRenderDrawColor(renderer, 255, 220, 0, 110);
+            SDL_FRect glow{x - 10, y - 10, w + 20, h + 20};
+            SDL_RenderFillRect(renderer, &glow);
+        } else if (isHovered) {
+            bgColor = {static_cast<Uint8>(std::min(255, bgColor.r + 40)), 
+                       static_cast<Uint8>(std::min(255, bgColor.g + 40)), 
+                       static_cast<Uint8>(std::min(255, bgColor.b + 40)), 
+                       bgColor.a};
+        }
+
+        // Neon glow aura around the button to increase visibility (subtle)
+        for (int gi = 0; gi < 3; ++gi) {
+            float grow = 6.0f + gi * 3.0f;
+            Uint8 glowA = static_cast<Uint8>(std::max(0, (int)borderColor.a / (3 - gi)));
+            SDL_SetRenderDrawColor(renderer, borderColor.r, borderColor.g, borderColor.b, glowA);
+            SDL_FRect glowRect{x - grow, y - grow, w + grow * 2.0f, h + grow * 2.0f};
+            SDL_RenderRect(renderer, &glowRect);
+        }
+
+        // Draw button background with border
+        SDL_SetRenderDrawColor(renderer, borderColor.r, borderColor.g, borderColor.b, borderColor.a);
+        SDL_FRect borderRect{x - 2, y - 2, w + 4, h + 4};
+        SDL_RenderFillRect(renderer, &borderRect);
+
+        SDL_SetRenderDrawColor(renderer, bgColor.r, bgColor.g, bgColor.b, bgColor.a);
+        SDL_FRect bgRect{x, y, w, h};
+        SDL_RenderFillRect(renderer, &bgRect);
+    }
+
+    // Draw icon if provided, otherwise draw text
+    if (icon) {
+        // Get icon dimensions
+        float iconW = 0.0f, iconH = 0.0f;
+        SDL_GetTextureSize(icon, &iconW, &iconH);
+        
+        // Scale icon to fit nicely in button (60% of button height)
+        float maxIconH = h * 0.6f;
+        float scale = maxIconH / iconH;
+        float scaledW = iconW * scale;
+        float scaledH = iconH * scale;
+        
+        // Center icon in button
+        float iconX = cx - scaledW * 0.5f;
+        float iconY = cy - scaledH * 0.5f;
+        
+        SDL_FRect iconRect{iconX, iconY, scaledW, scaledH};
+
+        // Soft icon shadow for readability over busy backgrounds
+        SDL_SetTextureBlendMode(icon, SDL_BLENDMODE_BLEND);
+        SDL_SetTextureColorMod(icon, 0, 0, 0);
+        SDL_SetTextureAlphaMod(icon, 150);
+        SDL_FRect shadowRect{iconX + 2.0f, iconY + 2.0f, scaledW, scaledH};
+        SDL_RenderTexture(renderer, icon, nullptr, &shadowRect);
+
+        // Main icon (yellow tint when selected)
+        if (isSelected) {
+            SDL_SetTextureColorMod(icon, 255, 220, 0);
+        } else {
+            SDL_SetTextureColorMod(icon, 255, 255, 255);
+        }
+        SDL_SetTextureAlphaMod(icon, 255);
+        SDL_RenderTexture(renderer, icon, nullptr, &iconRect);
+
+        // Reset
+        SDL_SetTextureColorMod(icon, 255, 255, 255);
+        SDL_SetTextureAlphaMod(icon, 255);
+    } else if (font) {
+        // Draw text with scale based on button height.
+        float textScale = 1.2f;
+        if (h <= 40.0f) {
+            textScale = 0.90f;
+        } else if (h <= 54.0f) {
+            textScale = 1.00f;
+        } else if (h <= 70.0f) {
+            textScale = 1.10f;
+        }
+        int textW = 0, textH = 0;
+        font->measure(label, textScale, textW, textH);
+        float tx = x + (w - static_cast<float>(textW)) * 0.5f;
+        // Vertically center text within the button.
+        float ty = y + (h - static_cast<float>(textH)) * 0.5f;
+        
+        // Choose text color based on selection state
+        SDL_Color textColor = {255, 255, 255, 255}; // Default white
+        if (isSelected) {
+            textColor = {255, 220, 0, 255}; // Yellow when selected
+        }
+        
+        // Text shadow
+        font->draw(renderer, tx + 2.0f, ty + 2.0f, label, textScale, {0, 0, 0, 200});
+        // Text
+        font->draw(renderer, tx, ty, label, textScale, textColor);
+    }
+}
+
+void UIRenderer::computeContentOffsets(float winW, float winH, float logicalW, float logicalH, float logicalScale, float& outOffsetX, float& outOffsetY) {
+    float contentW = logicalW * logicalScale;
+    float contentH = logicalH * logicalScale;
+    outOffsetX = (winW - contentW) * 0.5f / logicalScale;
+    outOffsetY = (winH - contentH) * 0.5f / logicalScale;
+}
+
+void UIRenderer::drawLogo(SDL_Renderer* renderer, SDL_Texture* logoTex, float logicalW, float logicalH, float contentOffsetX, float contentOffsetY, int texW, int texH) {
+    if (!renderer || !logoTex) return;
+
+    float w = 0.0f;
+    float h = 0.0f;
+
+    if (texW > 0 && texH > 0) {
+        w = static_cast<float>(texW);
+        h = static_cast<float>(texH);
+    } else {
+        SDL_GetTextureSize(logoTex, &w, &h);
+    }
+
+    if (w > 0.0f && h > 0.0f) {
+        float maxWidth = logicalW * 0.6f;
+        float scale = std::min(1.0f, maxWidth / w);
+        float dw = w * scale;
+        float dh = h * scale;
+        float logoX = (logicalW - dw) * 0.5f + contentOffsetX;
+        float logoY = logicalH * 0.05f + contentOffsetY;
+        SDL_FRect dst{logoX, logoY, dw, dh};
+        SDL_RenderTexture(renderer, logoTex, nullptr, &dst);
+    }
+}
+
+void UIRenderer::drawSettingsPopup(SDL_Renderer* renderer, FontAtlas* font, float logicalW, float logicalH, bool musicEnabled, bool soundEnabled) {
+    if (!renderer || !font) return;
+
+    float popupW = 350, popupH = 260;
+    float popupX = (logicalW - popupW) / 2;
+    float popupY = (logicalH - popupH) / 2;
+    
+    // Semi-transparent overlay
+    SDL_SetRenderDrawColor(renderer, 0, 0, 0, 128);
+    SDL_FRect overlay{0, 0, logicalW, logicalH};
+    SDL_RenderFillRect(renderer, &overlay);
+    
+    // Popup background
+    SDL_SetRenderDrawColor(renderer, 100, 120, 160, 255);
+    SDL_FRect bord{popupX-4, popupY-4, popupW+8, popupH+8};
+    SDL_RenderFillRect(renderer, &bord);
+    
+    SDL_SetRenderDrawColor(renderer, 40, 50, 70, 255);
+    SDL_FRect body{popupX, popupY, popupW, popupH};
+    SDL_RenderFillRect(renderer, &body);
+    
+    // Title
+    font->draw(renderer, popupX + 20, popupY + 20, "SETTINGS", 2.0f, {255, 220, 0, 255});
+    
+    // Music toggle
+    font->draw(renderer, popupX + 20, popupY + 70, "MUSIC:", 1.5f, {255, 255, 255, 255});
+    const char* musicStatus = musicEnabled ? "ON" : "OFF";
+    SDL_Color musicColor = musicEnabled ? SDL_Color{0, 255, 0, 255} : SDL_Color{255, 0, 0, 255};
+    font->draw(renderer, popupX + 120, popupY + 70, musicStatus, 1.5f, musicColor);
+    
+    // Sound effects toggle
+    font->draw(renderer, popupX + 20, popupY + 100, "SOUND FX:", 1.5f, {255, 255, 255, 255});
+    const char* soundStatus = soundEnabled ? "ON" : "OFF";
+    SDL_Color soundColor = soundEnabled ? SDL_Color{0, 255, 0, 255} : SDL_Color{255, 0, 0, 255};
+    font->draw(renderer, popupX + 140, popupY + 100, soundStatus, 1.5f, soundColor);
+    
+    // Instructions
+    font->draw(renderer, popupX + 20, popupY + 150, "M = TOGGLE MUSIC", 1.0f, {200, 200, 220, 255});
+    font->draw(renderer, popupX + 20, popupY + 170, "K = TOGGLE SOUND FX", 1.0f, {200, 200, 220, 255});
+    font->draw(renderer, popupX + 20, popupY + 190, "ESC = CLOSE", 1.0f, {200, 200, 220, 255});
+}
diff --git a/src/graphics/renderers/UIRenderer.h b/src/graphics/renderers/UIRenderer.h
new file mode 100644
index 0000000..3fff420
--- /dev/null
+++ b/src/graphics/renderers/UIRenderer.h
@@ -0,0 +1,28 @@
+#pragma once
+#include <SDL3/SDL.h>
+#include <string>
+
+class FontAtlas;
+
+class UIRenderer {
+public:
+    // Draw a sci-fi style panel with glow, shadow, and border
+    static void drawSciFiPanel(SDL_Renderer* renderer, const SDL_FRect& rect, float alpha = 1.0f);
+
+    // Draw a generic button with hover/select states
+    static void drawButton(SDL_Renderer* renderer, FontAtlas* font, float cx, float cy, float w, float h, 
+                          const std::string& label, bool isHovered, bool isSelected, 
+                          SDL_Color bgColor = {80, 110, 200, 255}, 
+                          SDL_Color borderColor = {60, 80, 140, 255},
+                          bool textOnly = false,
+                          SDL_Texture* icon = nullptr);
+
+    // Helper to calculate content offsets for centering
+    static void computeContentOffsets(float winW, float winH, float logicalW, float logicalH, float logicalScale, float& outOffsetX, float& outOffsetY);
+
+    // Draw the game logo centered at the top
+    static void drawLogo(SDL_Renderer* renderer, SDL_Texture* logoTex, float logicalW, float logicalH, float contentOffsetX, float contentOffsetY, int texW = 0, int texH = 0);
+
+    // Draw the settings popup
+    static void drawSettingsPopup(SDL_Renderer* renderer, FontAtlas* font, float logicalW, float logicalH, bool musicEnabled, bool soundEnabled);
+};
diff --git a/src/graphics/ui/Font.cpp b/src/graphics/ui/Font.cpp
new file mode 100644
index 0000000..6520720
--- /dev/null
+++ b/src/graphics/ui/Font.cpp
@@ -0,0 +1,36 @@
+// Font.cpp - implementation of FontAtlas (copied into src/graphics)
+#include "graphics/Font.h"
+#include <SDL3/SDL.h>
+
+bool FontAtlas::init(const std::string& path, int basePt) { fontPath = path; baseSize = basePt; return true; }
+
+void FontAtlas::shutdown() { for (auto &kv : cache) if (kv.second) TTF_CloseFont(kv.second); cache.clear(); }
+
+TTF_Font* FontAtlas::getSized(int ptSize) {
+    auto it = cache.find(ptSize); if (it!=cache.end()) return it->second;
+    TTF_Font* f = TTF_OpenFont(fontPath.c_str(), ptSize);
+    if (!f) return nullptr; cache[ptSize] = f; return f;
+}
+
+void FontAtlas::draw(SDL_Renderer* r, float x, float y, const std::string& text, float scale, SDL_Color color) {
+    if (scale <= 0) return; int pt = int(baseSize * scale); if (pt < 8) pt = 8; TTF_Font* f = getSized(pt); if (!f) return;
+    SDL_Surface* surf = TTF_RenderText_Blended(f, text.c_str(), text.length(), color); if (!surf) return;
+    SDL_Texture* tex = SDL_CreateTextureFromSurface(r, surf);
+    if (tex) { SDL_FRect dst{ x, y, (float)surf->w, (float)surf->h }; SDL_RenderTexture(r, tex, nullptr, &dst); SDL_DestroyTexture(tex); }
+    SDL_DestroySurface(surf);
+}
+
+void FontAtlas::measure(const std::string& text, float scale, int& outW, int& outH) {
+    outW = 0; outH = 0;
+    if (scale <= 0) return;
+    int pt = int(baseSize * scale);
+    if (pt < 1) pt = 1;
+    TTF_Font* f = getSized(pt);
+    if (!f) return;
+    // Use render-to-surface measurement to avoid dependency on specific TTF_* measurement API variants
+    SDL_Color dummy = {255,255,255,255};
+    SDL_Surface* surf = TTF_RenderText_Blended(f, text.c_str(), text.length(), dummy);
+    if (!surf) return;
+    outW = surf->w; outH = surf->h;
+    SDL_DestroySurface(surf);
+}
diff --git a/src/graphics/ui/Font.h b/src/graphics/ui/Font.h
new file mode 100644
index 0000000..3ff2846
--- /dev/null
+++ b/src/graphics/ui/Font.h
@@ -0,0 +1,20 @@
+// Font.h - Font rendering abstraction with simple size cache
+#pragma once
+#include <SDL3_ttf/SDL_ttf.h>
+#include <string>
+#include <unordered_map>
+struct SDL_Renderer;
+
+class FontAtlas {
+public:
+    bool init(const std::string& path, int basePt);
+    void shutdown();
+    void draw(SDL_Renderer* r, float x, float y, const std::string& text, float scale, SDL_Color color);
+    // Measure rendered text size in pixels for a given scale
+    void measure(const std::string& text, float scale, int& outW, int& outH);
+private:
+    std::string fontPath;
+    int baseSize{24};
+    std::unordered_map<int, TTF_Font*> cache; // point size -> font*
+    TTF_Font* getSized(int ptSize);
+};
diff --git a/src/graphics/ui/HelpOverlay.cpp b/src/graphics/ui/HelpOverlay.cpp
new file mode 100644
index 0000000..fbe2059
--- /dev/null
+++ b/src/graphics/ui/HelpOverlay.cpp
@@ -0,0 +1,147 @@
+#include "HelpOverlay.h"
+#include "Font.h"
+#include <array>
+#include <algorithm>
+
+namespace {
+struct ShortcutEntry {
+    const char* combo;
+    const char* description;
+};
+
+void drawRect(SDL_Renderer* renderer, float x, float y, float w, float h, SDL_Color color) {
+    SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, color.a);
+    SDL_FRect rect{x, y, w, h};
+    SDL_RenderFillRect(renderer, &rect);
+}
+
+float fitScale(FontAtlas& font, const char* text, float initialScale, float maxWidth) {
+    int textW = 0, textH = 0;
+    float scale = initialScale;
+    font.measure(text, scale, textW, textH);
+    if (textW > maxWidth && textW > 0) {
+        float factor = maxWidth / static_cast<float>(textW);
+        scale = std::max(0.65f, scale * factor);
+    }
+    return scale;
+}
+
+} // anonymous namespace
+
+namespace HelpOverlay {
+
+void Render(SDL_Renderer* renderer, FontAtlas& font, float logicalWidth, float logicalHeight, float offsetX, float offsetY) {
+    if (!renderer) return;
+
+    const std::array<ShortcutEntry, 5> generalShortcuts{{
+        {"F1", "Toggle this help overlay"},
+        {"ESC", "Back / cancel current popup"},
+        {"F11 or ALT+ENTER", "Toggle fullscreen"},
+        {"M", "Mute or unmute music"},
+        {"K", "Toggle sound effects"}
+    }};
+
+    const std::array<ShortcutEntry, 2> menuShortcuts{{
+        {"ARROW KEYS", "Navigate menu buttons"},
+        {"ENTER / SPACE", "Activate highlighted action"}
+    }};
+
+    const std::array<ShortcutEntry, 8> gameplayShortcuts{{
+        {"LEFT / RIGHT", "Move active piece"},
+        {"DOWN", "Soft drop (faster fall)"},
+        {"SPACE", "Hard drop / instant lock"},
+        {"UP", "Rotate clockwise"},
+        {"H", "Hold / swap current piece"},
+        {"X", "Toggle rotation direction used by UP"},
+        {"P", "Pause or resume"},
+        {"ESC", "Open exit confirmation"}
+    }};
+
+    const float boxW = logicalWidth * 0.7f;
+    const float boxH = logicalHeight * 0.55f;
+    const float boxX = offsetX + (logicalWidth - boxW) * 0.5f;
+    const float boxY = offsetY + (logicalHeight - boxH) * 0.5f;
+
+    drawRect(renderer, boxX - 6.0f, boxY - 6.0f, boxW + 12.0f, boxH + 12.0f, {70, 90, 150, 255});
+    drawRect(renderer, boxX - 2.0f, boxY - 2.0f, boxW + 4.0f, boxH + 4.0f, {10, 12, 20, 255});
+    drawRect(renderer, boxX, boxY, boxW, boxH, {18, 22, 35, 240});
+
+    // Slightly smaller overall title to fit tighter layouts
+    const float titleScale = 1.45f;
+    font.draw(renderer, boxX + 28.0f, boxY + 24.0f, "HELP & SHORTCUTS", titleScale, {255, 220, 0, 255});
+
+    const float contentPadding = 32.0f;
+    const float columnGap = 30.0f;
+    const float columnWidth = (boxW - contentPadding * 2.0f - columnGap) * 0.5f;
+    const float leftColumnX = boxX + contentPadding;
+    const float rightColumnX = leftColumnX + columnWidth + columnGap;
+    const float footerHeight = 46.0f;
+    const float footerPadding = 18.0f;
+
+    // Slightly reduced scales for a more compact popup
+    const float sectionTitleScale = 1.0f;
+    const float comboScale = 0.82f;
+    const float descBaseScale = 0.72f;
+    // Increase vertical spacing between combo label and description for readability
+    const float comboSpacing = 28.0f;
+    // Increase spacing between sections and after titles
+    const float sectionSpacing = 22.0f;
+
+    // Helper to draw text with extra letter-spacing (tracking) for section titles
+    auto drawSpaced = [&](float sx, float sy, const char* text, float scale, SDL_Color color, float extraPx) {
+        std::string stext(text);
+        float x = sx;
+        for (size_t i = 0; i < stext.size(); ++i) {
+            std::string ch(1, stext[i]);
+            font.draw(renderer, x, sy, ch.c_str(), scale, color);
+            int cw = 0, chh = 0;
+            font.measure(ch.c_str(), scale, cw, chh);
+            x += static_cast<float>(cw) + extraPx;
+        }
+    };
+
+    auto drawSection = [&](float startX, float& cursorY, const char* title, const auto& entries) {
+        drawSpaced(startX, cursorY, title, sectionTitleScale, {180, 200, 255, 255}, 4.0f);
+        // extra gap after section title
+        cursorY += 34.0f;
+        for (const auto& entry : entries) {
+            font.draw(renderer, startX, cursorY, entry.combo, comboScale, {255, 255, 255, 255});
+            // larger spacing between combo label and description
+            cursorY += comboSpacing;
+
+            float descScale = fitScale(font, entry.description, descBaseScale, columnWidth - 10.0f);
+            font.draw(renderer, startX, cursorY, entry.description, descScale, {200, 210, 230, 255});
+            int descW = 0, descH = 0;
+            font.measure(entry.description, descScale, descW, descH);
+            // a bit more space after description row
+            cursorY += static_cast<float>(descH) + 14.0f;
+        }
+        cursorY += sectionSpacing;
+    };
+
+    float leftCursorY = boxY + 80.0f;
+    float rightCursorY = boxY + 80.0f;
+    drawSection(leftColumnX, leftCursorY, "GENERAL", generalShortcuts);
+    drawSection(leftColumnX, leftCursorY, "MENUS", menuShortcuts);
+    drawSection(rightColumnX, rightCursorY, "GAMEPLAY", gameplayShortcuts);
+
+    SDL_FRect footerRect{
+        boxX + contentPadding,
+        boxY + boxH - contentPadding - footerHeight,
+        boxW - contentPadding * 2.0f,
+        footerHeight
+    };
+    drawRect(renderer, footerRect.x, footerRect.y, footerRect.w, footerRect.h, {24, 30, 50, 255});
+    SDL_SetRenderDrawColor(renderer, 90, 110, 170, 255);
+    SDL_RenderRect(renderer, &footerRect);
+
+    const char* closeLabel = "PRESS F1 OR ESC TO CLOSE";
+    float closeScale = fitScale(font, closeLabel, 1.0f, footerRect.w - footerPadding * 2.0f);
+    int closeW = 0, closeH = 0;
+    font.measure(closeLabel, closeScale, closeW, closeH);
+    float closeX = footerRect.x + (footerRect.w - static_cast<float>(closeW)) * 0.5f;
+    float closeY = footerRect.y + (footerRect.h - static_cast<float>(closeH)) * 0.5f;
+    font.draw(renderer, closeX, closeY, closeLabel, closeScale, {215, 220, 240, 255});
+}
+
+} // namespace HelpOverlay
diff --git a/src/graphics/ui/HelpOverlay.h b/src/graphics/ui/HelpOverlay.h
new file mode 100644
index 0000000..1de9b68
--- /dev/null
+++ b/src/graphics/ui/HelpOverlay.h
@@ -0,0 +1,16 @@
+#pragma once
+#include <SDL3/SDL.h>
+
+class FontAtlas;
+
+namespace HelpOverlay {
+    // Draws the help popup contents inside the logical coordinate space.
+    // Optional offsets allow aligning the box when the logical canvas is letterboxed.
+    void Render(
+        SDL_Renderer* renderer,
+        FontAtlas& font,
+        float logicalWidth,
+        float logicalHeight,
+        float offsetX = 0.0f,
+        float offsetY = 0.0f);
+}
diff --git a/src/main.cpp b/src/main.cpp
index 25989c2..e88774b 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -1,1658 +1,15 @@
-// main.cpp - Application orchestration (initialization, loop, UI states)
-// High-level only: delegates Tetris logic, scores, background, font rendering.
+// main.cpp - Thin entrypoint.
+//
+// The full SDL initialization, loading screen, state machine, game loop, and shutdown
+// are intentionally kept out of this file (see `TetrisApp`) to keep the entrypoint
+// small and keep orchestration separate from gameplay/state code.
 
-#include <SDL3/SDL.h>
 #include <SDL3/SDL_main.h>
-#include <SDL3_ttf/SDL_ttf.h>
-#include <string>
-#include <cstdio>
-#include <algorithm>
-#include <array>
-#include <vector>
-#include <random>
-#include <cmath>
-#include <cstdlib>
-#include <memory>
 
-#include "audio/Audio.h"
-#include "audio/SoundEffect.h"
-
-#include "gameplay/Game.h"
-#include "persistence/Scores.h"
-#include "graphics/Starfield.h"
-#include "Starfield3D.h"
-#include "graphics/Font.h"
-#include "gameplay/LineEffect.h"
-#include "states/State.h"
-#include "states/LoadingState.h"
-#include "states/MenuState.h"
-#include "states/PlayingState.h"
-#include "audio/MenuWrappers.h"
-
-// Debug logging removed: no-op in this build (previously LOG_DEBUG)
-
-// Font rendering now handled by FontAtlas
-
-// ---------- Game config ----------
-static constexpr int LOGICAL_W = 1200;
-static constexpr int LOGICAL_H = 1000;
-static constexpr int WELL_W = Game::COLS * Game::TILE;
-static constexpr int WELL_H = Game::ROWS * Game::TILE;
-
-// Piece types now declared in Game.h
-
-// Scores now managed by ScoreManager
-
-// 4x4 shapes encoded as 16-bit bitmasks per rotation (row-major 4x4).
-// Bit 0 = (x=0,y=0), Bit 1 = (1,0) ... Bit 15 = (3,3)
-// Shapes & game logic now in Game.cpp
-
-// (removed inline shapes)
-
-// Piece struct now in Game.h
-
-// Game struct replaced by Game class
-
-static const std::array<SDL_Color, PIECE_COUNT + 1> COLORS = {{
-    SDL_Color{20, 20, 26, 255},  // 0 empty
-    SDL_Color{0, 255, 255, 255}, // I
-    SDL_Color{255, 255, 0, 255}, // O
-    SDL_Color{160, 0, 255, 255}, // T
-    SDL_Color{0, 255, 0, 255},   // S
-    SDL_Color{255, 0, 0, 255},   // Z
-    SDL_Color{0, 0, 255, 255},   // J
-    SDL_Color{255, 160, 0, 255}, // L
-}};
-
-static void drawRect(SDL_Renderer *r, float x, float y, float w, float h, SDL_Color c)
-{
-    SDL_SetRenderDrawColor(r, c.r, c.g, c.b, c.a);
-    SDL_FRect fr{x, y, w, h};
-    SDL_RenderFillRect(r, &fr);
-}
-
-// -----------------------------------------------------------------------------
-// Enhanced Button Drawing
-// -----------------------------------------------------------------------------
-static void drawEnhancedButton(SDL_Renderer* renderer, FontAtlas& font, float cx, float cy, float w, float h, 
-                               const std::string& label, bool isHovered, bool isSelected = false) {
-    SDL_Color bgColor = isHovered ? SDL_Color{120, 150, 240, 255} : SDL_Color{80, 110, 200, 255};
-    if (isSelected) bgColor = {160, 190, 255, 255};
-    
-    float x = cx - w/2;
-    float y = cy - h/2;
-    
-    // Draw button background with border
-    drawRect(renderer, x-2, y-2, w+4, h+4, {60, 80, 140, 255}); // Border
-    drawRect(renderer, x, y, w, h, bgColor); // Background
-    
-    // Draw button text centered
-    float textScale = 1.5f;
-    float textX = x + (w - label.length() * 12 * textScale) / 2;
-    float textY = y + (h - 20 * textScale) / 2;
-    font.draw(renderer, textX, textY, label, textScale, {255, 255, 255, 255});
-}
-
-// External wrapper for enhanced button so other translation units can call it.
-void menu_drawEnhancedButton(SDL_Renderer* renderer, FontAtlas& font, float cx, float cy, float w, float h,
-                             const std::string& label, bool isHovered, bool isSelected) {
-    drawEnhancedButton(renderer, font, cx, cy, w, h, label, isHovered, isSelected);
-}
-
-// Popup wrappers
-// Forward declarations for popup functions defined later in this file
-static void drawLevelSelectionPopup(SDL_Renderer* renderer, FontAtlas& font, SDL_Texture* bgTex, int selectedLevel);
-static void drawSettingsPopup(SDL_Renderer* renderer, FontAtlas& font, bool musicEnabled);
-
-void menu_drawLevelSelectionPopup(SDL_Renderer* renderer, FontAtlas& font, SDL_Texture* bgTex, int selectedLevel) {
-    drawLevelSelectionPopup(renderer, font, bgTex, selectedLevel);
-}
-
-void menu_drawSettingsPopup(SDL_Renderer* renderer, FontAtlas& font, bool musicEnabled) {
-    drawSettingsPopup(renderer, font, musicEnabled);
-}
-
-// Simple rounded menu button drawer used by MenuState (keeps visual parity with JS)
-void menu_drawMenuButton(SDL_Renderer* renderer, FontAtlas& font, float cx, float cy, float w, float h,
-                         const std::string& label, SDL_Color bgColor, SDL_Color borderColor) {
-    float x = cx - w/2;
-    float y = cy - h/2;
-    drawRect(renderer, x-6, y-6, w+12, h+12, borderColor);
-    drawRect(renderer, x-4, y-4, w+8, h+8, {255,255,255,255});
-    drawRect(renderer, x, y, w, h, bgColor);
-
-    float textScale = 1.6f;
-    float approxCharW = 12.0f * textScale;
-    float textW = label.length() * approxCharW;
-    float tx = x + (w - textW) / 2.0f;
-    float ty = y + (h - 20.0f * textScale) / 2.0f;
-    font.draw(renderer, tx+2, ty+2, label, textScale, {0,0,0,180});
-    font.draw(renderer, tx, ty, label, textScale, {255,255,255,255});
-}
-
-// -----------------------------------------------------------------------------
-// Block Drawing Functions
-// -----------------------------------------------------------------------------
-static void drawBlockTexture(SDL_Renderer* renderer, SDL_Texture* blocksTex, float x, float y, float size, int blockType) {
-    if (!blocksTex || blockType < 0 || blockType >= PIECE_COUNT) {
-        // Debug: print why we're falling back
-        if (!blocksTex) {
-            static bool printed = false;
-            if (!printed) {
-                (void)0;
-                printed = true;
-            }
-        }
-        // Fallback to colored rectangle if texture isn't available
-        SDL_Color color = (blockType >= 0 && blockType < PIECE_COUNT) ? COLORS[blockType + 1] : SDL_Color{128, 128, 128, 255};
-        drawRect(renderer, x, y, size-1, size-1, color);
-        return;
-    }
-    
-    // JavaScript uses: sx = type * spriteSize, sy = 0, with 2px padding
-    // Each sprite is 90px wide in the horizontal sprite sheet
-    const int SPRITE_SIZE = 90;
-    float srcX = blockType * SPRITE_SIZE + 2;  // Add 2px padding like JS
-    float srcY = 2;                            // Add 2px padding from top like JS
-    float srcW = SPRITE_SIZE - 4;              // Subtract 4px total padding like JS
-    float srcH = SPRITE_SIZE - 4;              // Subtract 4px total padding like JS
-    
-    SDL_FRect srcRect = {srcX, srcY, srcW, srcH};
-    SDL_FRect dstRect = {x, y, size, size};
-    SDL_RenderTexture(renderer, blocksTex, &srcRect, &dstRect);
-}
-
-static void drawPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, const Game::Piece& piece, float ox, float oy, float tileSize, bool isGhost = false) {
-    if (piece.type >= PIECE_COUNT) return;
-    
-    for (int cy = 0; cy < 4; ++cy) {
-        for (int cx = 0; cx < 4; ++cx) {
-            if (Game::cellFilled(piece, cx, cy)) {
-                float px = ox + (piece.x + cx) * tileSize;
-                float py = oy + (piece.y + cy) * tileSize;
-                
-                if (isGhost) {
-
-                    SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
-
-                    // Draw ghost piece as barely visible gray outline
-                    SDL_SetRenderDrawColor(renderer, 180, 180, 180, 20); // Very faint gray
-                    SDL_FRect rect = {px + 2, py + 2, tileSize - 4, tileSize - 4};
-                    SDL_RenderFillRect(renderer, &rect);
-                    
-                    // Draw thin gray border
-                    SDL_SetRenderDrawColor(renderer, 180, 180, 180, 30);
-                    SDL_FRect border = {px + 1, py + 1, tileSize - 2, tileSize - 2};
-                    SDL_RenderRect(renderer, &border);
-                } else {
-                    drawBlockTexture(renderer, blocksTex, px, py, tileSize, piece.type);
-                }
-            }
-        }
-    }
-}
-
-static void drawSmallPiece(SDL_Renderer* renderer, SDL_Texture* blocksTex, PieceType pieceType, float x, float y, float tileSize) {
-    if (pieceType >= PIECE_COUNT) return;
-    
-    // Use the first rotation (index 0) for preview
-    Game::Piece previewPiece;
-    previewPiece.type = pieceType;
-    previewPiece.rot = 0;
-    previewPiece.x = 0;
-    previewPiece.y = 0;
-    
-    // Center the piece in the preview area
-    float offsetX = 0, offsetY = 0;
-    if (pieceType == I) { offsetX = tileSize * 0.5f; } // I-piece centering
-    else if (pieceType == O) { offsetX = tileSize * 0.5f; } // O-piece centering
-    
-    // Use semi-transparent alpha for preview blocks
-    Uint8 previewAlpha = 180; // Change this value for more/less transparency
-    SDL_SetTextureAlphaMod(blocksTex, previewAlpha);
-    for (int cy = 0; cy < 4; ++cy) {
-        for (int cx = 0; cx < 4; ++cx) {
-            if (Game::cellFilled(previewPiece, cx, cy)) {
-                float px = x + offsetX + cx * tileSize;
-                float py = y + offsetY + cy * tileSize;
-                drawBlockTexture(renderer, blocksTex, px, py, tileSize, pieceType);
-            }
-        }
-    }
-    SDL_SetTextureAlphaMod(blocksTex, 255); // Reset alpha after drawing
-}
-
-// -----------------------------------------------------------------------------
-// Popup Drawing Functions
-// -----------------------------------------------------------------------------
-static void drawLevelSelectionPopup(SDL_Renderer* renderer, FontAtlas& font, SDL_Texture* bgTex, int selectedLevel) {
-    // Popup dims scale with logical size for responsiveness
-    float popupW = std::min(760.0f, LOGICAL_W * 0.75f);
-    float popupH = std::min(520.0f, LOGICAL_H * 0.7f);
-    float popupX = (LOGICAL_W - popupW) / 2.0f;
-    float popupY = (LOGICAL_H - popupH) / 2.0f;
-
-    // Draw the background picture stretched to full logical viewport if available
-    if (bgTex) {
-        // Dim the background by rendering it then overlaying a semi-transparent black rect
-        SDL_FRect dst{0, 0, (float)LOGICAL_W, (float)LOGICAL_H};
-        SDL_RenderTexture(renderer, bgTex, nullptr, &dst);
-        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 160);
-        SDL_FRect dim{0,0,(float)LOGICAL_W,(float)LOGICAL_H};
-        SDL_RenderFillRect(renderer, &dim);
-    } else {
-        // Fallback to semi-transparent overlay
-        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 180);
-        SDL_FRect overlay{0, 0, (float)LOGICAL_W, (float)LOGICAL_H};
-        SDL_RenderFillRect(renderer, &overlay);
-    }
-
-    // Popup panel with border and subtle background
-    drawRect(renderer, popupX-6, popupY-6, popupW+12, popupH+12, {90, 110, 140, 200}); // outer border
-    drawRect(renderer, popupX-3, popupY-3, popupW+6, popupH+6, {30, 38, 60, 220}); // inner border
-    drawRect(renderer, popupX, popupY, popupW, popupH, {18, 22, 34, 235}); // panel
-
-    // Title (use retro pixel font)
-    font.draw(renderer, popupX + 28, popupY + 18, "SELECT STARTING LEVEL", 2.4f, {255, 220, 0, 255});
-
-    // Grid layout for levels: 4 columns x 5 rows
-    int cols = 4, rows = 5;
-    float padding = 24.0f;
-    float gridW = popupW - padding * 2;
-    float gridH = popupH - 120.0f; // leave space for title and instructions
-    float cellW = gridW / cols;
-    float cellH = std::min(80.0f, gridH / rows - 12.0f);
-
-    float gridStartX = popupX + padding;
-    float gridStartY = popupY + 70;
-
-    for (int level = 0; level < 20; ++level) {
-        int row = level / cols;
-        int col = level % cols;
-        float cx = gridStartX + col * cellW;
-        float cy = gridStartY + row * (cellH + 12.0f);
-
-        bool isSelected = (level == selectedLevel);
-        SDL_Color bg = isSelected ? SDL_Color{255, 220, 0, 255} : SDL_Color{70, 85, 120, 240};
-        SDL_Color fg = isSelected ? SDL_Color{0, 0, 0, 255} : SDL_Color{240, 240, 245, 255};
-
-        // Button background
-        drawRect(renderer, cx + 8, cy, cellW - 16, cellH, bg);
-
-        // Level label centered
-        char levelStr[8]; snprintf(levelStr, sizeof(levelStr), "%d", level);
-        float tx = cx + (cellW / 2.0f) - (6.0f * 1.8f); // rough centering
-        float ty = cy + (cellH / 2.0f) - 10.0f;
-        font.draw(renderer, tx, ty, levelStr, 1.8f, fg);
-    }
-
-    // Instructions under grid
-    font.draw(renderer, popupX + 28, popupY + popupH - 40, "CLICK A LEVEL TO SELECT  •  ESC = CANCEL", 1.0f, {200,200,220,255});
-}
-
-static void drawSettingsPopup(SDL_Renderer* renderer, FontAtlas& font, bool musicEnabled) {
-    float popupW = 350, popupH = 260;
-    float popupX = (LOGICAL_W - popupW) / 2;
-    float popupY = (LOGICAL_H - popupH) / 2;
-    
-    // Semi-transparent overlay
-    SDL_SetRenderDrawColor(renderer, 0, 0, 0, 128);
-    SDL_FRect overlay{0, 0, LOGICAL_W, LOGICAL_H};
-    SDL_RenderFillRect(renderer, &overlay);
-    
-    // Popup background
-    drawRect(renderer, popupX-4, popupY-4, popupW+8, popupH+8, {100, 120, 160, 255}); // Border
-    drawRect(renderer, popupX, popupY, popupW, popupH, {40, 50, 70, 255}); // Background
-    
-    // Title
-    font.draw(renderer, popupX + 20, popupY + 20, "SETTINGS", 2.0f, {255, 220, 0, 255});
-    
-    // Music toggle
-    font.draw(renderer, popupX + 20, popupY + 70, "MUSIC:", 1.5f, {255, 255, 255, 255});
-    const char* musicStatus = musicEnabled ? "ON" : "OFF";
-    SDL_Color musicColor = musicEnabled ? SDL_Color{0, 255, 0, 255} : SDL_Color{255, 0, 0, 255};
-    font.draw(renderer, popupX + 120, popupY + 70, musicStatus, 1.5f, musicColor);
-    
-    // Sound effects toggle
-    font.draw(renderer, popupX + 20, popupY + 100, "SOUND FX:", 1.5f, {255, 255, 255, 255});
-    const char* soundStatus = SoundEffectManager::instance().isEnabled() ? "ON" : "OFF";
-    SDL_Color soundColor = SoundEffectManager::instance().isEnabled() ? SDL_Color{0, 255, 0, 255} : SDL_Color{255, 0, 0, 255};
-    font.draw(renderer, popupX + 140, popupY + 100, soundStatus, 1.5f, soundColor);
-    
-    // Instructions
-    font.draw(renderer, popupX + 20, popupY + 150, "M = TOGGLE MUSIC", 1.0f, {200, 200, 220, 255});
-    font.draw(renderer, popupX + 20, popupY + 170, "S = TOGGLE SOUND FX", 1.0f, {200, 200, 220, 255});
-    font.draw(renderer, popupX + 20, popupY + 190, "N = PLAY LETS_GO", 1.0f, {200, 200, 220, 255});
-    font.draw(renderer, popupX + 20, popupY + 210, "ESC = CLOSE", 1.0f, {200, 200, 220, 255});
-}
-
-// -----------------------------------------------------------------------------
-// Starfield effect for background
-// -----------------------------------------------------------------------------
-// Starfield now managed by Starfield class
-
-// State manager integration (scaffolded in StateManager.h)
-#include "core/StateManager.h"
-
-// -----------------------------------------------------------------------------
-// Intro/Menu state variables
-// -----------------------------------------------------------------------------
-static double logoAnimCounter = 0.0;
-static bool showLevelPopup = false;
-static bool showSettingsPopup = false;
-static bool musicEnabled = true;
-static int hoveredButton = -1; // -1 = none, 0 = play, 1 = level, 2 = settings
-
-// -----------------------------------------------------------------------------
-// Tetris Block Fireworks for intro animation (block particles)
-// Forward declare block render helper used by particles
-static void drawBlockTexture(SDL_Renderer* renderer, SDL_Texture* blocksTex, float x, float y, float size, int blockType);
-// -----------------------------------------------------------------------------
-struct BlockParticle {
-    float x, y, vx, vy, size, alpha, decay;
-    int blockType; // 0..6
-    BlockParticle(float sx, float sy)
-        : x(sx), y(sy) {
-        float angle = (rand() % 628) / 100.0f; // 0..2pi
-        float speed = 1.5f + (rand() % 350) / 100.0f; // ~1.5..5.0
-        vx = std::cos(angle) * speed;
-        vy = std::sin(angle) * speed;
-        size = 6.0f + (rand() % 50) / 10.0f; // 6..11 px
-        alpha = 1.0f;
-        decay = 0.012f + (rand() % 200) / 10000.0f; // 0.012..0.032
-        blockType = rand() % 7; // choose a tetris color
-    }
-    bool update() {
-        vx *= 0.985f; // friction
-        vy = vy * 0.985f + 0.07f; // gravity
-        x += vx;
-        y += vy;
-        alpha -= decay;
-        size = std::max(2.0f, size - 0.04f);
-        return alpha > 0.02f;
-    }
-};
-
-struct TetrisFirework {
-    std::vector<BlockParticle> particles;
-    int mode = 0; // 0=random,1=red,2=green,3=palette
-    TetrisFirework(float x, float y) {
-        mode = rand() % 4;
-        int particleCount = 30 + rand() % 25; // 30-55 particles
-        particles.reserve(particleCount);
-        for (int i = 0; i < particleCount; ++i) particles.emplace_back(x, y);
-    }
-    bool update() {
-        for (auto it = particles.begin(); it != particles.end();) {
-            if (!it->update()) it = particles.erase(it); else ++it;
-        }
-        return !particles.empty();
-    }
-    // Drawing is handled by drawFireworks_impl which accepts the texture to use.
-};
-
-static std::vector<TetrisFirework> fireworks;
-static Uint64 lastFireworkTime = 0;
-
-// -----------------------------------------------------------------------------
-// Fireworks Management
-// -----------------------------------------------------------------------------
-static void updateFireworks(double frameMs) {
-    Uint64 now = SDL_GetTicks();
-    // Randomly spawn new block fireworks (2% chance per frame), bias to lower-right
-    if (fireworks.size() < 5 && (rand() % 100) < 2) {
-        float x = LOGICAL_W * 0.55f + float(rand() % int(LOGICAL_W * 0.35f));
-        float y = LOGICAL_H * 0.80f + float(rand() % int(LOGICAL_H * 0.15f));
-        fireworks.emplace_back(x, y);
-        lastFireworkTime = now;
-    }
-    
-    // Update existing fireworks
-    for (auto it = fireworks.begin(); it != fireworks.end();) {
-        if (!it->update()) {
-            it = fireworks.erase(it);
-        } else {
-            ++it;
-        }
-    }
-}
-
-// Primary implementation that accepts a texture pointer
-static void drawFireworks_impl(SDL_Renderer* renderer, SDL_Texture* blocksTexture) {
-    for (auto& f : fireworks) {
-        // Particle draw uses the texture pointer passed into drawBlockTexture calls from f.draw
-        // We'll set a thread-local-ish variable by passing the texture as an argument to draw
-        // routines or using the provided texture in the particle's draw path.
-        // For simplicity, the particle draw function below will reference a global symbol
-        // via an argument — we adapt by providing the texture when calling drawBlockTexture.
-        // Implementation: call a small lambda that temporarily binds the texture for drawBlockTexture.
-        struct Drawer { SDL_Renderer* r; SDL_Texture* tex; void drawParticle(struct BlockParticle& p) {
-                if (tex) {
-                    Uint8 prevA = 255;
-                    SDL_GetTextureAlphaMod(tex, &prevA);
-                    Uint8 setA = Uint8(std::max(0.0f, std::min(1.0f, p.alpha)) * 255.0f);
-                    SDL_SetTextureAlphaMod(tex, setA);
-                    // Note: color modulation will be applied by callers of drawBlockTexture where needed
-                    // but we mimic behavior from previous implementation by leaving color mod as default.
-                    drawBlockTexture(r, tex, p.x - p.size * 0.5f, p.y - p.size * 0.5f, p.size, p.blockType);
-                    SDL_SetTextureAlphaMod(tex, prevA);
-                    SDL_SetTextureColorMod(tex, 255, 255, 255);
-                } else {
-                    SDL_SetRenderDrawColor(r, 255, 255, 255, Uint8(p.alpha * 255));
-                    SDL_FRect rect{p.x - p.size/2, p.y - p.size/2, p.size, p.size};
-                    SDL_RenderFillRect(r, &rect);
-                }
-            }
-    } drawer{renderer, blocksTexture};
-        for (auto &p : f.particles) {
-            drawer.drawParticle(p);
-        }
-    }
-}
-// External wrappers for use by other translation units (MenuState)
-// Expect callers to pass the blocks texture via StateContext so we avoid globals.
-void menu_drawFireworks(SDL_Renderer* renderer, SDL_Texture* blocksTex) { drawFireworks_impl(renderer, blocksTex); }
-void menu_updateFireworks(double frameMs) { updateFireworks(frameMs); }
-double menu_getLogoAnimCounter() { return logoAnimCounter; }
-int menu_getHoveredButton() { return hoveredButton; }
+#include "app/TetrisApp.h"
 
 int main(int, char **)
 {
-    // Initialize random seed for fireworks
-    srand(static_cast<unsigned int>(SDL_GetTicks()));
-    
-    int sdlInitRes = SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO);
-    if (sdlInitRes < 0)
-    {
-        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_Init failed: %s", SDL_GetError());
-        return 1;
-    }
-    int ttfInitRes = TTF_Init();
-    if (ttfInitRes < 0)
-    {
-        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "TTF_Init failed");
-        SDL_Quit();
-        return 1;
-    }
-    SDL_Window *window = SDL_CreateWindow("Tetris (SDL3)", LOGICAL_W, LOGICAL_H, SDL_WINDOW_RESIZABLE);
-    if (!window)
-    {
-        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_CreateWindow failed: %s", SDL_GetError());
-        TTF_Quit();
-        SDL_Quit();
-        return 1;
-    }
-    SDL_Renderer *renderer = SDL_CreateRenderer(window, nullptr);
-    if (!renderer)
-    {
-        SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "SDL_CreateRenderer failed: %s", SDL_GetError());
-        SDL_DestroyWindow(window);
-        TTF_Quit();
-        SDL_Quit();
-        return 1;
-    }
-    SDL_SetRenderVSync(renderer, 1);
-
-    FontAtlas font;
-    font.init("FreeSans.ttf", 24);
-    
-    // Load PressStart2P font for loading screen and retro UI elements
-    FontAtlas pixelFont;
-    pixelFont.init("assets/fonts/PressStart2P-Regular.ttf", 16);
-    
-    ScoreManager scores;
-    scores.load();
-    Starfield starfield;
-    starfield.init(200, LOGICAL_W, LOGICAL_H);
-    Starfield3D starfield3D;
-    starfield3D.init(LOGICAL_W, LOGICAL_H, 200);
-    
-    // Initialize line clearing effects
-    LineEffect lineEffect;
-    lineEffect.init(renderer);
-    
-    // Load logo using native SDL BMP loading
-    SDL_Texture *logoTex = nullptr;
-    SDL_Surface* logoSurface = SDL_LoadBMP("assets/images/logo.bmp");
-    if (logoSurface) {
-    (void)0;
-        logoTex = SDL_CreateTextureFromSurface(renderer, logoSurface);
-        SDL_DestroySurface(logoSurface);
-    } else {
-    (void)0;
-    }
-    // Load small logo (used by Menu to show whole logo)
-    SDL_Texture *logoSmallTex = nullptr;
-    SDL_Surface* logoSmallSurface = SDL_LoadBMP("assets/images/logo_small.bmp");
-    int logoSmallW = 0, logoSmallH = 0;
-    if (logoSmallSurface) {
-        // capture surface size before creating the texture (avoids SDL_QueryTexture)
-        logoSmallW = logoSmallSurface->w;
-        logoSmallH = logoSmallSurface->h;
-        logoSmallTex = SDL_CreateTextureFromSurface(renderer, logoSmallSurface);
-        SDL_DestroySurface(logoSmallSurface);
-    } else {
-        // fallback: leave logoSmallTex null so MenuState will use large logo
-        (void)0;
-    }
-    
-    // Load background using native SDL BMP loading
-    SDL_Texture *backgroundTex = nullptr;
-    SDL_Surface* backgroundSurface = SDL_LoadBMP("assets/images/main_background.bmp");
-    if (backgroundSurface) {
-    (void)0;
-        backgroundTex = SDL_CreateTextureFromSurface(renderer, backgroundSurface);
-        SDL_DestroySurface(backgroundSurface);
-    } else {
-    (void)0;
-    }
-
-    // Note: `backgroundTex` is owned by main and passed into `StateContext::backgroundTex` below.
-    // States should render using `ctx.backgroundTex` rather than accessing globals.
-    
-    // Level background caching system
-    SDL_Texture *levelBackgroundTex = nullptr;
-    SDL_Texture *nextLevelBackgroundTex = nullptr; // used during fade transitions
-    int cachedLevel = -1; // Track which level background is currently cached
-    float levelFadeAlpha = 0.0f; // 0..1 blend factor where 1 means next fully visible
-    const float LEVEL_FADE_DURATION = 3500.0f; // ms for fade transition (3.5s)
-    float levelFadeElapsed = 0.0f;
-    
-    // Load blocks texture using native SDL BMP loading
-    SDL_Texture *blocksTex = nullptr;
-    SDL_Surface* blocksSurface = SDL_LoadBMP("assets/images/blocks90px_001.bmp");
-    if (blocksSurface) {
-    (void)0;
-        blocksTex = SDL_CreateTextureFromSurface(renderer, blocksSurface);
-        SDL_DestroySurface(blocksSurface);
-    } else {
-    (void)0;
-    }
-    // No global exposure of blocksTex; states receive textures via StateContext.
-    
-    if (!blocksTex) {
-    (void)0;
-        
-        // Create a 630x90 texture (7 blocks * 90px each)
-        blocksTex = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_RGBA8888, SDL_TEXTUREACCESS_TARGET, 630, 90);
-        if (blocksTex) {
-            // Set texture as render target and draw colored blocks
-            SDL_SetRenderTarget(renderer, blocksTex);
-            SDL_SetRenderDrawColor(renderer, 0, 0, 0, 0);
-            SDL_RenderClear(renderer);
-            
-            // Draw each block type with its color
-            for (int i = 0; i < PIECE_COUNT; ++i) {
-                SDL_Color color = COLORS[i + 1];
-                SDL_SetRenderDrawColor(renderer, color.r, color.g, color.b, 255);
-                SDL_FRect rect = {float(i * 90 + 4), 4, 82, 82}; // 4px padding, 82x82 block
-                SDL_RenderFillRect(renderer, &rect);
-                
-                // Add a highlight effect
-                SDL_SetRenderDrawColor(renderer, 
-                    (Uint8)std::min(255, color.r + 30),
-                    (Uint8)std::min(255, color.g + 30),
-                    (Uint8)std::min(255, color.b + 30), 255);
-                SDL_FRect highlight = {float(i * 90 + 4), 4, 82, 20};
-                SDL_RenderFillRect(renderer, &highlight);
-            }
-            
-            // Reset render target
-            SDL_SetRenderTarget(renderer, nullptr);
-            (void)0;
-        } else {
-            std::fprintf(stderr, "Failed to create programmatic texture: %s\n", SDL_GetError());
-        }
-    } else {
-    (void)0;
-    }
-
-    // Provide the blocks sheet to the fireworks system through StateContext (no globals).
-
-    // Default start level selection: 0
-    int startLevelSelection = 0;
-    Game game(startLevelSelection);
-    
-    // Initialize sound effects system
-    SoundEffectManager::instance().init();
-    
-    // Load sound effects
-    SoundEffectManager::instance().loadSound("clear_line", "assets/music/clear_line.wav");
-    
-    // Load voice lines for line clears using WAV files (with MP3 fallback)
-    std::vector<std::string> doubleSounds = {"nice_combo", "you_fire", "well_played", "keep_that_ryhtm"};
-    std::vector<std::string> tripleSounds = {"great_move", "smooth_clear", "impressive", "triple_strike"};
-    std::vector<std::string> tetrisSounds = {"amazing", "you_re_unstoppable", "boom_tetris", "wonderful"};
-    
-    // Helper function to load sound with WAV/MP3 fallback and file existence check
-    auto loadSoundWithFallback = [&](const std::string& id, const std::string& baseName) {
-        std::string wavPath = "assets/music/" + baseName + ".wav";
-        std::string mp3Path = "assets/music/" + baseName + ".mp3";
-        
-        // Check if WAV file exists first
-        SDL_IOStream* wavFile = SDL_IOFromFile(wavPath.c_str(), "rb");
-        if (wavFile) {
-            SDL_CloseIO(wavFile);
-            if (SoundEffectManager::instance().loadSound(id, wavPath)) {
-                (void)0;
-                return;
-            }
-        }
-        
-        // Fallback to MP3 if WAV doesn't exist or fails to load
-        SDL_IOStream* mp3File = SDL_IOFromFile(mp3Path.c_str(), "rb");
-        if (mp3File) {
-            SDL_CloseIO(mp3File);
-            if (SoundEffectManager::instance().loadSound(id, mp3Path)) {
-                (void)0;
-                return;
-            }
-        }
-        
-    SDL_LogError(SDL_LOG_CATEGORY_APPLICATION, "Failed to load sound: %s (tried both WAV and MP3)", id.c_str());
-    };
-    
-    loadSoundWithFallback("nice_combo", "nice_combo");
-    loadSoundWithFallback("you_fire", "you_fire");
-    loadSoundWithFallback("well_played", "well_played");
-    loadSoundWithFallback("keep_that_ryhtm", "keep_that_ryhtm");
-    loadSoundWithFallback("great_move", "great_move");
-    loadSoundWithFallback("smooth_clear", "smooth_clear");
-    loadSoundWithFallback("impressive", "impressive");
-    loadSoundWithFallback("triple_strike", "triple_strike");
-    loadSoundWithFallback("amazing", "amazing");
-    loadSoundWithFallback("you_re_unstoppable", "you_re_unstoppable");
-    loadSoundWithFallback("boom_tetris", "boom_tetris");
-    loadSoundWithFallback("wonderful", "wonderful");
-    loadSoundWithFallback("lets_go", "lets_go"); // For level up
-    
-    // Set up sound effect callbacks
-    game.setSoundCallback([&](int linesCleared) {
-        // Play basic line clear sound first
-        SoundEffectManager::instance().playSound("clear_line", 1.0f); // Increased volume
-        
-        // Then play voice line based on number of lines cleared
-        if (linesCleared == 2) {
-            SoundEffectManager::instance().playRandomSound(doubleSounds, 1.0f); // Increased volume
-        } else if (linesCleared == 3) {
-            SoundEffectManager::instance().playRandomSound(tripleSounds, 1.0f); // Increased volume
-        } else if (linesCleared == 4) {
-            SoundEffectManager::instance().playRandomSound(tetrisSounds, 1.0f); // Increased volume
-        }
-        // Single line clears just play the basic clear sound (no voice in JS version)
-    });
-    
-    game.setLevelUpCallback([&](int newLevel) {
-        // Play level up sound
-        SoundEffectManager::instance().playSound("lets_go", 1.0f); // Increased volume
-    });
-    
-    AppState state = AppState::Loading;
-    double loadingProgress = 0.0;
-    Uint64 loadStart = SDL_GetTicks();
-    bool running = true, isFullscreen = false;
-    bool leftHeld = false, rightHeld = false;
-    double moveTimerMs = 0;
-    const double DAS = 170.0, ARR = 40.0;
-    SDL_Rect logicalVP{0, 0, LOGICAL_W, LOGICAL_H};
-    float logicalScale = 1.f;
-    Uint64 lastMs = SDL_GetTicks();
-    bool musicStarted = false;
-    bool musicLoaded = false;
-    int currentTrackLoading = 0;
-    int totalTracks = 0; // Will be set dynamically based on actual files
-    
-    // Instantiate state manager
-    StateManager stateMgr(state);
-
-    // Prepare shared context for states
-    StateContext ctx{};
-    ctx.game = &game;
-    ctx.scores = &scores;
-    ctx.starfield = &starfield;
-    ctx.starfield3D = &starfield3D;
-    ctx.font = &font;
-    ctx.pixelFont = &pixelFont;
-    ctx.lineEffect = &lineEffect;
-    ctx.logoTex = logoTex;
-    ctx.logoSmallTex = logoSmallTex;
-    ctx.logoSmallW = logoSmallW;
-    ctx.logoSmallH = logoSmallH;
-    ctx.backgroundTex = backgroundTex;
-    ctx.blocksTex = blocksTex;
-    ctx.musicEnabled = &musicEnabled;
-    ctx.startLevelSelection = &startLevelSelection;
-    ctx.hoveredButton = &hoveredButton;
-    ctx.showLevelPopup = &showLevelPopup;
-    ctx.showSettingsPopup = &showSettingsPopup;
-
-    // Instantiate state objects
-    auto loadingState = std::make_unique<LoadingState>(ctx);
-    auto menuState = std::make_unique<MenuState>(ctx);
-    auto playingState = std::make_unique<PlayingState>(ctx);
-
-    // Register handlers and lifecycle hooks
-    stateMgr.registerHandler(AppState::Loading, [&](const SDL_Event& e){ loadingState->handleEvent(e); });
-    stateMgr.registerOnEnter(AppState::Loading, [&](){ loadingState->onEnter(); });
-    stateMgr.registerOnExit(AppState::Loading, [&](){ loadingState->onExit(); });
-
-    stateMgr.registerHandler(AppState::Menu, [&](const SDL_Event& e){ menuState->handleEvent(e); });
-    stateMgr.registerOnEnter(AppState::Menu, [&](){ menuState->onEnter(); });
-    stateMgr.registerOnExit(AppState::Menu, [&](){ menuState->onExit(); });
-
-    // Combined Playing state handler: run playingState handler and inline gameplay mapping
-    stateMgr.registerHandler(AppState::Playing, [&](const SDL_Event& e){
-        // First give the PlayingState a chance to handle the event
-        playingState->handleEvent(e);
-
-        // Then perform inline gameplay mappings (gravity/rotation/hard-drop/hold)
-        if (e.type == SDL_EVENT_KEY_DOWN && !e.key.repeat) {
-            if (!game.isPaused()) {
-                if (e.key.scancode == SDL_SCANCODE_SPACE) {
-                    game.hardDrop();
-                }
-                else if (e.key.scancode == SDL_SCANCODE_UP) {
-                    game.rotate(+1);
-                }
-                else if (e.key.scancode == SDL_SCANCODE_Z || (e.key.mod & SDL_KMOD_SHIFT)) {
-                    game.rotate(-1);
-                }
-                else if (e.key.scancode == SDL_SCANCODE_C || (e.key.mod & SDL_KMOD_CTRL)) {
-                    game.holdCurrent();
-                }
-            }
-        }
-    });
-    stateMgr.registerOnEnter(AppState::Playing, [&](){ playingState->onEnter(); });
-    stateMgr.registerOnExit(AppState::Playing, [&](){ playingState->onExit(); });
-
-    // Playing, LevelSelect and GameOver currently use inline logic in main; we'll migrate later
-    while (running)
-    {
-        int winW = 0, winH = 0;
-        SDL_GetWindowSize(window, &winW, &winH);
-        
-        // Use the full window for the viewport, scale to fit content
-        logicalScale = std::min(winW / (float)LOGICAL_W, winH / (float)LOGICAL_H);
-        if (logicalScale <= 0)
-            logicalScale = 1.f;
-        
-        // Fill the entire window with our viewport
-        logicalVP.w = winW;
-        logicalVP.h = winH;
-        logicalVP.x = 0;
-        logicalVP.y = 0;
-        // --- Events ---
-        SDL_Event e;
-        while (SDL_PollEvent(&e))
-        {
-            if (e.type == SDL_EVENT_QUIT)
-                running = false;
-            else {
-                // Route event to state manager handlers for per-state logic
-                stateMgr.handleEvent(e);
-
-                // Global key toggles (applies regardless of state)
-                if (e.type == SDL_EVENT_KEY_DOWN && !e.key.repeat) {
-                    if (e.key.scancode == SDL_SCANCODE_M)
-                    {
-                        Audio::instance().toggleMute();
-                        musicEnabled = !musicEnabled;
-                    }
-                    if (e.key.scancode == SDL_SCANCODE_S)
-                    {
-                        // Toggle sound effects
-                        SoundEffectManager::instance().setEnabled(!SoundEffectManager::instance().isEnabled());
-                    }
-                    if (e.key.scancode == SDL_SCANCODE_N)
-                    {
-                        // Test sound effects - play lets_go.wav specifically
-                        SoundEffectManager::instance().playSound("lets_go", 1.0f);
-                    }
-                    if (e.key.key == SDLK_F11 || (e.key.key == SDLK_RETURN && (e.key.mod & SDL_KMOD_ALT)))
-                    {
-                        isFullscreen = !isFullscreen;
-                        SDL_SetWindowFullscreen(window, isFullscreen ? SDL_WINDOW_FULLSCREEN : 0);
-                    }
-                }
-
-                // Mouse handling remains in main loop for UI interactions
-                if (e.type == SDL_EVENT_MOUSE_BUTTON_DOWN)
-                {
-                    float mx = (float)e.button.x, my = (float)e.button.y;
-                    if (mx >= logicalVP.x && my >= logicalVP.y && mx <= logicalVP.x + logicalVP.w && my <= logicalVP.y + logicalVP.h)
-                    {
-                        float lx = (mx - logicalVP.x) / logicalScale, ly = (my - logicalVP.y) / logicalScale;
-                        if (state == AppState::Menu)
-                        {
-                            // Compute content offsets (match MenuState centering)
-                            float contentW = LOGICAL_W * logicalScale;
-                            float contentH = LOGICAL_H * logicalScale;
-                            float contentOffsetX = (winW - contentW) * 0.5f / logicalScale;
-                            float contentOffsetY = (winH - contentH) * 0.5f / logicalScale;
-
-                            if (showLevelPopup) {
-                                // Handle level selection popup clicks
-                                float popupW = 400, popupH = 300;
-                                float popupX = (LOGICAL_W - popupW) / 2;
-                                float popupY = (LOGICAL_H - popupH) / 2;
-                                
-                                if (lx >= popupX && lx <= popupX + popupW && ly >= popupY && ly <= popupY + popupH) {
-                                    // Click inside popup - check level grid
-                                    float gridStartX = popupX + 50;
-                                    float gridStartY = popupY + 70;
-                                    float cellW = 70, cellH = 35;
-                                    
-                                    if (lx >= gridStartX && ly >= gridStartY) {
-                                        int col = int((lx - gridStartX) / cellW);
-                                        int row = int((ly - gridStartY) / cellH);
-                                        if (col >= 0 && col < 4 && row >= 0 && row < 5) {
-                                            int selectedLevel = row * 4 + col;
-                                            if (selectedLevel < 20) {
-                                                startLevelSelection = selectedLevel;
-                                                showLevelPopup = false;
-                                            }
-                                        }
-                                    }
-                                } else {
-                                    // Click outside popup - close it
-                                    showLevelPopup = false;
-                                }
-                            } else if (showSettingsPopup) {
-                                // Click anywhere closes settings popup
-                                showSettingsPopup = false;
-                            } else {
-                                // Responsive Main menu buttons (match MenuState layout)
-                                bool isSmall = ((LOGICAL_W * logicalScale) < 700.0f);
-                                float btnW = isSmall ? (LOGICAL_W * 0.4f) : 300.0f;
-                                float btnH = isSmall ? 60.0f : 70.0f;
-                                float btnCX = LOGICAL_W * 0.5f + contentOffsetX;
-                                const float btnYOffset = 40.0f; // must match MenuState offset
-                                float btnCY = LOGICAL_H * 0.86f + contentOffsetY + btnYOffset;
-                                SDL_FRect playBtn{btnCX - btnW * 0.6f - btnW/2.0f, btnCY - btnH/2.0f, btnW, btnH};
-                                SDL_FRect levelBtn{btnCX + btnW * 0.6f - btnW/2.0f, btnCY - btnH/2.0f, btnW, btnH};
-
-                                if (lx >= playBtn.x && lx <= playBtn.x + playBtn.w && ly >= playBtn.y && ly <= playBtn.y + playBtn.h)
-                                {
-                                    // Reset the game first with the chosen start level so HUD and
-                                    // Playing state see the correct 0-based level immediately.
-                                    game.reset(startLevelSelection);
-                                    state = AppState::Playing;
-                                    stateMgr.setState(state);
-                                }
-                                else if (lx >= levelBtn.x && lx <= levelBtn.x + levelBtn.w && ly >= levelBtn.y && ly <= levelBtn.y + levelBtn.h)
-                                {
-                                    showLevelPopup = true;
-                                }
-                                
-                                // Settings button (gear icon area - top right)
-                                SDL_FRect settingsBtn{LOGICAL_W - 60, 10, 50, 30};
-                                if (lx >= settingsBtn.x && lx <= settingsBtn.x + settingsBtn.w && ly >= settingsBtn.y && ly <= settingsBtn.y + settingsBtn.h)
-                                {
-                                    showSettingsPopup = true;
-                                }
-                            }
-                        }
-                        else if (state == AppState::LevelSelect)
-                            startLevelSelection = (startLevelSelection + 1) % 20;
-                        else if (state == AppState::GameOver) {
-                            state = AppState::Menu;
-                            stateMgr.setState(state);
-                        }
-                    }
-                }
-                else if (e.type == SDL_EVENT_MOUSE_MOTION)
-                {
-                    float mx = (float)e.motion.x, my = (float)e.motion.y;
-                    if (mx >= logicalVP.x && my >= logicalVP.y && mx <= logicalVP.x + logicalVP.w && my <= logicalVP.y + logicalVP.h)
-                    {
-                        float lx = (mx - logicalVP.x) / logicalScale, ly = (my - logicalVP.y) / logicalScale;
-                        if (state == AppState::Menu && !showLevelPopup && !showSettingsPopup)
-                        {
-                            // Compute content offsets and responsive buttons (match MenuState)
-                            float contentW = LOGICAL_W * logicalScale;
-                            float contentH = LOGICAL_H * logicalScale;
-                            float contentOffsetX = (winW - contentW) * 0.5f / logicalScale;
-                            float contentOffsetY = (winH - contentH) * 0.5f / logicalScale;
-                            bool isSmall = ((LOGICAL_W * logicalScale) < 700.0f);
-                            float btnW = isSmall ? (LOGICAL_W * 0.4f) : 300.0f;
-                            float btnH = isSmall ? 60.0f : 70.0f;
-                            float btnCX = LOGICAL_W * 0.5f + contentOffsetX;
-                            const float btnYOffset = 40.0f; // must match MenuState offset
-                            float btnCY = LOGICAL_H * 0.86f + contentOffsetY + btnYOffset;
-                            SDL_FRect playBtn{btnCX - btnW * 0.6f - btnW/2.0f, btnCY - btnH/2.0f, btnW, btnH};
-                            SDL_FRect levelBtn{btnCX + btnW * 0.6f - btnW/2.0f, btnCY - btnH/2.0f, btnW, btnH};
-                            
-                            hoveredButton = -1;
-                            if (lx >= playBtn.x && lx <= playBtn.x + playBtn.w && ly >= playBtn.y && ly <= playBtn.y + playBtn.h)
-                                hoveredButton = 0;
-                            else if (lx >= levelBtn.x && lx <= levelBtn.x + levelBtn.w && ly >= levelBtn.y && ly <= levelBtn.y + levelBtn.h)
-                                hoveredButton = 1;
-                        }
-                    }
-                }
-            }
-        }
-
-        // --- Timing ---
-        Uint64 now = SDL_GetTicks();
-        double frameMs = double(now - lastMs);
-        lastMs = now;
-        const bool *ks = SDL_GetKeyboardState(nullptr);
-        bool left = state == AppState::Playing && ks[SDL_SCANCODE_LEFT];
-        bool right = state == AppState::Playing && ks[SDL_SCANCODE_RIGHT];
-        bool down = state == AppState::Playing && ks[SDL_SCANCODE_DOWN];
-
-        // Inform game about soft-drop state for scoring parity (1 point per cell when holding Down)
-        if (state == AppState::Playing)
-            game.setSoftDropping(down && !game.isPaused());
-        else
-            game.setSoftDropping(false);
-
-        // Handle DAS/ARR
-        int moveDir = 0;
-        if (left && !right)
-            moveDir = -1;
-        else if (right && !left)
-            moveDir = +1;
-
-        if (moveDir != 0 && !game.isPaused())
-        {
-            if ((moveDir == -1 && leftHeld == false) || (moveDir == +1 && rightHeld == false))
-            {
-                game.move(moveDir);
-                moveTimerMs = DAS;
-            }
-            else
-            {
-                moveTimerMs -= frameMs;
-                if (moveTimerMs <= 0)
-                {
-                    game.move(moveDir);
-                    moveTimerMs += ARR;
-                }
-            }
-        }
-        else
-            moveTimerMs = 0;
-        leftHeld = left;
-        rightHeld = right;
-        if (down && !game.isPaused())
-            game.softDropBoost(frameMs);
-        if (state == AppState::Playing)
-        {
-            if (!game.isPaused()) {
-                game.tickGravity(frameMs);
-                game.addElapsed(frameMs);
-                
-                // Update line effect and clear lines when animation completes
-                if (lineEffect.isActive()) {
-                    if (lineEffect.update(frameMs / 1000.0f)) {
-                        // Effect is complete, now actually clear the lines
-                        game.clearCompletedLines();
-                    }
-                }
-            }
-            if (game.isGameOver())
-            {
-                scores.submit(game.score(), game.lines(), game.level(), game.elapsed());
-                state = AppState::GameOver;
-                stateMgr.setState(state);
-            }
-        }
-        else if (state == AppState::Loading)
-        {
-            // Initialize audio system and start background loading on first frame
-            if (!musicLoaded && currentTrackLoading == 0) {
-                Audio::instance().init();
-                
-                // Count actual music files first
-                totalTracks = 0;
-                for (int i = 1; i <= 100; ++i) { // Check up to 100 files
-                    char buf[64];
-                    std::snprintf(buf, sizeof(buf), "assets/music/music%03d.mp3", i);
-                    
-                    // Check if file exists
-                    SDL_IOStream* file = SDL_IOFromFile(buf, "rb");
-                    if (file) {
-                        SDL_CloseIO(file);
-                        totalTracks++;
-                    } else {
-                        break; // No more consecutive files
-                    }
-                }
-                
-                // Add all found tracks to the background loading queue
-                for (int i = 1; i <= totalTracks; ++i) {
-                    char buf[64];
-                    std::snprintf(buf, sizeof(buf), "assets/music/music%03d.mp3", i);
-                    Audio::instance().addTrackAsync(buf);
-                }
-                
-                // Start background loading thread
-                Audio::instance().startBackgroundLoading();
-                currentTrackLoading = 1; // Mark as started
-            }
-            
-            // Update progress based on background loading
-            if (currentTrackLoading > 0 && !musicLoaded) {
-                currentTrackLoading = Audio::instance().getLoadedTrackCount();
-                if (Audio::instance().isLoadingComplete()) {
-                    Audio::instance().shuffle(); // Shuffle once all tracks are loaded
-                    musicLoaded = true;
-                }
-            }
-            
-            // Calculate comprehensive loading progress
-            // Phase 1: Initial assets (textures, fonts) - 20%
-            double assetProgress = 0.2; // Assets are loaded at startup
-            
-            // Phase 2: Music loading - 70% 
-            double musicProgress = 0.0;
-            if (totalTracks > 0) {
-                musicProgress = musicLoaded ? 0.7 : std::min(0.7, (double)currentTrackLoading / totalTracks * 0.7);
-            }
-            
-            // Phase 3: Final initialization - 10%
-            double timeProgress = std::min(0.1, (now - loadStart) / 500.0); // Faster final phase
-            
-            loadingProgress = assetProgress + musicProgress + timeProgress;
-            
-            // Ensure we never exceed 100% and reach exactly 100% when everything is loaded
-            loadingProgress = std::min(1.0, loadingProgress);
-            if (musicLoaded && timeProgress >= 0.1) {
-                loadingProgress = 1.0;
-            }
-            
-            if (loadingProgress >= 1.0 && musicLoaded) {
-                state = AppState::Menu;
-                stateMgr.setState(state);
-            }
-        }
-        if (state == AppState::Menu || state == AppState::Playing)
-        {
-            if (!musicStarted && musicLoaded)
-            {
-                // Music tracks are already loaded during loading screen, just start playback
-                Audio::instance().start();
-                musicStarted = true;
-            }
-        }
-        
-        // Update starfields based on current state
-        if (state == AppState::Loading) {
-            starfield3D.update(float(frameMs / 1000.0f));
-            starfield3D.resize(logicalVP.w, logicalVP.h); // Update for window resize
-        } else {
-            starfield.update(float(frameMs / 1000.0f), logicalVP.x * 2 + logicalVP.w, logicalVP.y * 2 + logicalVP.h);
-        }
-
-        // Advance level background fade if a next texture is queued
-        if (nextLevelBackgroundTex) {
-            levelFadeElapsed += float(frameMs);
-            levelFadeAlpha = std::min(1.0f, levelFadeElapsed / LEVEL_FADE_DURATION);
-        }
-        
-        // Update intro animations
-        if (state == AppState::Menu) {
-            logoAnimCounter += frameMs * 0.0008; // Animation speed
-            updateFireworks(frameMs);
-        }
-
-        // --- Per-state update hooks (allow states to manage logic incrementally)
-        switch (stateMgr.getState()) {
-            case AppState::Loading:
-                loadingState->update(frameMs);
-                break;
-            case AppState::Menu:
-                menuState->update(frameMs);
-                break;
-            case AppState::Playing:
-                playingState->update(frameMs);
-                break;
-            default:
-                break;
-        }
-
-        // --- Render ---
-        SDL_SetRenderViewport(renderer, nullptr);
-        SDL_SetRenderDrawColor(renderer, 12, 12, 16, 255);
-        SDL_RenderClear(renderer);
-        
-    // Draw level-based background for gameplay, starfield for other states
-    if (state == AppState::Playing) {
-        // Use level-based background for gameplay with caching
-        int currentLevel = game.level();
-        int bgLevel = (currentLevel > 32) ? 32 : currentLevel; // Cap at level 32
-        
-        // Only load new background if level changed
-        if (cachedLevel != bgLevel) {
-            // Load new level background into nextLevelBackgroundTex
-            if (nextLevelBackgroundTex) { SDL_DestroyTexture(nextLevelBackgroundTex); nextLevelBackgroundTex = nullptr; }
-            char bgPath[256];
-            snprintf(bgPath, sizeof(bgPath), "assets/images/tetris_main_back_level%d.bmp", bgLevel);
-            SDL_Surface* levelBgSurface = SDL_LoadBMP(bgPath);
-            if (levelBgSurface) {
-                nextLevelBackgroundTex = SDL_CreateTextureFromSurface(renderer, levelBgSurface);
-                SDL_DestroySurface(levelBgSurface);
-                // start fade transition
-                levelFadeAlpha = 0.0f;
-                levelFadeElapsed = 0.0f;
-                cachedLevel = bgLevel;
-            } else {
-                // don't change textures if file missing
-                cachedLevel = -1;
-            }
-        }
-
-        // Draw blended backgrounds if needed
-        if (levelBackgroundTex || nextLevelBackgroundTex) {
-            SDL_FRect fullRect = { 0, 0, (float)logicalVP.w, (float)logicalVP.h };
-            // if fade in progress
-            if (nextLevelBackgroundTex && levelFadeAlpha < 1.0f && levelBackgroundTex) {
-                // draw current with inverse alpha
-                SDL_SetTextureAlphaMod(levelBackgroundTex, Uint8((1.0f - levelFadeAlpha) * 255));
-                SDL_RenderTexture(renderer, levelBackgroundTex, nullptr, &fullRect);
-                SDL_SetTextureAlphaMod(nextLevelBackgroundTex, Uint8(levelFadeAlpha * 255));
-                SDL_RenderTexture(renderer, nextLevelBackgroundTex, nullptr, &fullRect);
-                // reset mods
-                SDL_SetTextureAlphaMod(levelBackgroundTex, 255);
-                SDL_SetTextureAlphaMod(nextLevelBackgroundTex, 255);
-            }
-            else if (nextLevelBackgroundTex && (!levelBackgroundTex || levelFadeAlpha >= 1.0f)) {
-                // finalise swap
-                if (levelBackgroundTex) { SDL_DestroyTexture(levelBackgroundTex); }
-                levelBackgroundTex = nextLevelBackgroundTex;
-                nextLevelBackgroundTex = nullptr;
-                levelFadeAlpha = 0.0f;
-                SDL_RenderTexture(renderer, levelBackgroundTex, nullptr, &fullRect);
-            }
-            else if (levelBackgroundTex) {
-                SDL_RenderTexture(renderer, levelBackgroundTex, nullptr, &fullRect);
-            }
-        }
-    } else if (state == AppState::Loading) {
-        // Use 3D starfield for loading screen (full screen)
-        starfield3D.draw(renderer);
-    } else if (state == AppState::Menu) {
-        // Use static background for menu, stretched to window; no starfield on sides
-        if (backgroundTex) {
-            SDL_FRect fullRect = { 0, 0, (float)logicalVP.w, (float)logicalVP.h };
-            SDL_RenderTexture(renderer, backgroundTex, nullptr, &fullRect);
-        }
-    } else {
-        // Use regular starfield for other states (not gameplay)
-        starfield.draw(renderer);
-    }
-        SDL_SetRenderViewport(renderer, &logicalVP);
-        SDL_SetRenderScale(renderer, logicalScale, logicalScale);
-
-        switch (state)
-        {
-        case AppState::Loading:
-        {
-            // Calculate actual content area (centered within the window)
-            float contentScale = logicalScale;
-            float contentW = LOGICAL_W * contentScale;
-            float contentH = LOGICAL_H * contentScale;
-            float contentOffsetX = (winW - contentW) * 0.5f / contentScale;
-            float contentOffsetY = (winH - contentH) * 0.5f / contentScale;
-            
-            auto drawRect = [&](float x, float y, float w, float h, SDL_Color c)
-            { SDL_SetRenderDrawColor(renderer,c.r,c.g,c.b,c.a); SDL_FRect fr{x + contentOffsetX, y + contentOffsetY, w, h}; SDL_RenderFillRect(renderer,&fr); };
-            
-            // Calculate dimensions for perfect centering (like JavaScript version)
-            const bool isLimitedHeight = LOGICAL_H < 450;
-            const float logoHeight = logoTex ? (isLimitedHeight ? LOGICAL_H * 0.25f : LOGICAL_H * 0.4f) : 0;
-            const float loadingTextHeight = 20; // Height of "LOADING" text (match JS)
-            const float barHeight = 20; // Loading bar height (match JS)
-            const float barPaddingVertical = isLimitedHeight ? 15 : 35;
-            const float percentTextHeight = 24; // Height of percentage text
-            const float spacingBetweenElements = isLimitedHeight ? 5 : 15;
-            
-            // Total content height
-            const float totalContentHeight = logoHeight + 
-                                           (logoHeight > 0 ? spacingBetweenElements : 0) +
-                                           loadingTextHeight + 
-                                           barPaddingVertical + 
-                                           barHeight + 
-                                           spacingBetweenElements + 
-                                           percentTextHeight;
-            
-            // Start Y position for perfect vertical centering
-            float currentY = (LOGICAL_H - totalContentHeight) / 2.0f;
-            
-            // Draw logo (centered, static like JavaScript version)
-            if (logoTex)
-            {
-                // Use the same original large logo dimensions as JS (we used a half-size BMP previously)
-                const int lw = 872, lh = 273;
-
-                // Cap logo width similar to JS UI.MAX_LOGO_WIDTH (600) and available screen space
-                const float maxLogoWidth = std::min(LOGICAL_W * 0.9f, 600.0f);
-                const float availableHeight = isLimitedHeight ? LOGICAL_H * 0.25f : LOGICAL_H * 0.4f;
-                const float availableWidth = maxLogoWidth;
-
-                const float scaleFactorWidth = availableWidth / static_cast<float>(lw);
-                const float scaleFactorHeight = availableHeight / static_cast<float>(lh);
-                const float scaleFactor = std::min(scaleFactorWidth, scaleFactorHeight);
-
-                const float displayWidth = lw * scaleFactor;
-                const float displayHeight = lh * scaleFactor;
-                const float logoX = (LOGICAL_W - displayWidth) / 2.0f;
-                
-                SDL_FRect dst{logoX + contentOffsetX, currentY + contentOffsetY, displayWidth, displayHeight};
-                SDL_RenderTexture(renderer, logoTex, nullptr, &dst);
-                
-                currentY += displayHeight + spacingBetweenElements;
-            }
-            
-            // Draw "LOADING" text (centered, using pixel font)
-            const char* loadingText = "LOADING";
-            float textWidth = strlen(loadingText) * 12.0f; // Approximate width for pixel font
-            float textX = (LOGICAL_W - textWidth) / 2.0f;
-            pixelFont.draw(renderer, textX + contentOffsetX, currentY + contentOffsetY, loadingText, 1.0f, {255, 204, 0, 255});
-            
-            currentY += loadingTextHeight + barPaddingVertical;
-            
-            // Draw loading bar (like JavaScript version)
-            const int barW = 400, barH = 20;
-            const int bx = (LOGICAL_W - barW) / 2;
-            
-            // Bar border (dark gray) - using drawRect which adds content offset
-            drawRect(bx - 3, currentY - 3, barW + 6, barH + 6, {68, 68, 80, 255});
-            
-            // Bar background (darker gray)
-            drawRect(bx, currentY, barW, barH, {34, 34, 34, 255});
-            
-            // Progress bar (gold color)
-            drawRect(bx, currentY, int(barW * loadingProgress), barH, {255, 204, 0, 255});
-            
-            currentY += barH + spacingBetweenElements;
-            
-            // Draw percentage text (centered, using pixel font)
-            int percentage = int(loadingProgress * 100);
-            char percentText[16];
-            std::snprintf(percentText, sizeof(percentText), "%d%%", percentage);
-            
-            float percentWidth = strlen(percentText) * 12.0f; // Approximate width for pixel font
-            float percentX = (LOGICAL_W - percentWidth) / 2.0f;
-            pixelFont.draw(renderer, percentX + contentOffsetX, currentY + contentOffsetY, percentText, 1.5f, {255, 204, 0, 255});
-        }
-        break;
-        case AppState::Menu:
-            // Delegate full menu rendering to MenuState object now
-            menuState->render(renderer, logicalScale, logicalVP);
-            break;
-        case AppState::LevelSelect:
-            font.draw(renderer, LOGICAL_W * 0.5f - 120, 80, "SELECT LEVEL", 2.5f, SDL_Color{255, 220, 0, 255});
-            {
-                char buf[64];
-                std::snprintf(buf, sizeof(buf), "LEVEL: %d", startLevelSelection);
-                font.draw(renderer, LOGICAL_W * 0.5f - 80, 180, buf, 2.0f, SDL_Color{200, 240, 255, 255});
-            }
-            font.draw(renderer, LOGICAL_W * 0.5f - 180, 260, "ARROWS CHANGE  ENTER=OK  ESC=BACK", 1.2f, SDL_Color{200, 200, 220, 255});
-            break;
-        case AppState::Playing:
-        {
-            // Calculate actual content area (centered within the window)
-            float contentScale = logicalScale;
-            float contentW = LOGICAL_W * contentScale;
-            float contentH = LOGICAL_H * contentScale;
-            float contentOffsetX = (winW - contentW) * 0.5f / contentScale;
-            float contentOffsetY = (winH - contentH) * 0.5f / contentScale;
-            
-            // Draw the game with layout matching the JavaScript version
-            auto drawRect = [&](float x, float y, float w, float h, SDL_Color c)
-            {
-                SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, c.a);
-                SDL_FRect fr{x + contentOffsetX, y + contentOffsetY, w, h};
-                SDL_RenderFillRect(renderer, &fr);
-            };
-
-            // Responsive layout that scales with window size while maintaining margins
-            // Calculate available space considering UI panels and margins
-            const float MIN_MARGIN = 40.0f;  // Minimum margin from edges
-            const float TOP_MARGIN = 60.0f;  // Extra top margin for better spacing
-            const float PANEL_WIDTH = 180.0f;  // Width of side panels
-            const float PANEL_SPACING = 30.0f;  // Space between grid and panels
-            const float NEXT_PIECE_HEIGHT = 120.0f; // Space reserved for next piece preview (increased)
-            const float BOTTOM_MARGIN = 60.0f; // Space for controls text at bottom
-            
-            // Available width = Total width - margins - left panel - right panel - spacing
-            const float availableWidth = LOGICAL_W - (MIN_MARGIN * 2) - (PANEL_WIDTH * 2) - (PANEL_SPACING * 2);
-            const float availableHeight = LOGICAL_H - TOP_MARGIN - BOTTOM_MARGIN - NEXT_PIECE_HEIGHT;
-            
-            // Calculate block size based on available space (maintain 10:20 aspect ratio)
-            const float maxBlockSizeW = availableWidth / Game::COLS;
-            const float maxBlockSizeH = availableHeight / Game::ROWS;
-            const float BLOCK_SIZE = std::min(maxBlockSizeW, maxBlockSizeH);
-            
-            // Ensure minimum and maximum block sizes
-            const float finalBlockSize = std::max(20.0f, std::min(BLOCK_SIZE, 40.0f));
-            
-            const float GRID_W = Game::COLS * finalBlockSize;
-            const float GRID_H = Game::ROWS * finalBlockSize;
-            
-            // Calculate vertical position with proper top margin
-            const float totalContentHeight = NEXT_PIECE_HEIGHT + GRID_H;
-            const float availableVerticalSpace = LOGICAL_H - TOP_MARGIN - BOTTOM_MARGIN;
-            const float verticalCenterOffset = (availableVerticalSpace - totalContentHeight) * 0.5f;
-            const float contentStartY = TOP_MARGIN + verticalCenterOffset;
-            
-            // Perfect horizontal centering - center the entire layout (grid + panels) in the window
-            const float totalLayoutWidth = PANEL_WIDTH + PANEL_SPACING + GRID_W + PANEL_SPACING + PANEL_WIDTH;
-            const float layoutStartX = (LOGICAL_W - totalLayoutWidth) * 0.5f;
-            
-            // Calculate panel and grid positions from the centered layout
-            const float statsX = layoutStartX + contentOffsetX;
-            const float gridX = layoutStartX + PANEL_WIDTH + PANEL_SPACING + contentOffsetX;
-            const float scoreX = layoutStartX + PANEL_WIDTH + PANEL_SPACING + GRID_W + PANEL_SPACING + contentOffsetX;
-            
-            // Position grid with proper top spacing
-            const float gridY = contentStartY + NEXT_PIECE_HEIGHT + contentOffsetY;
-            
-            // Panel dimensions and positions
-            const float statsY = gridY;
-            const float statsW = PANEL_WIDTH;
-            const float statsH = GRID_H;
-            
-            const float scoreY = gridY;
-            const float scoreW = PANEL_WIDTH;
-            
-            // Next piece preview (above grid, centered)
-            const float nextW = finalBlockSize * 4 + 20;
-            const float nextH = finalBlockSize * 2 + 20;
-            const float nextX = gridX + (GRID_W - nextW) * 0.5f;
-            const float nextY = contentStartY + contentOffsetY;
-            
-            // Handle line clearing effects (now that we have grid coordinates)
-            if (game.hasCompletedLines() && !lineEffect.isActive()) {
-                auto completedLines = game.getCompletedLines();
-                lineEffect.startLineClear(completedLines, static_cast<int>(gridX), static_cast<int>(gridY), static_cast<int>(finalBlockSize));
-            }
-            
-            // Draw panels with borders (like JS version)
-            
-            // Game grid border
-            drawRect(gridX - 3 - contentOffsetX, gridY - 3 - contentOffsetY, GRID_W + 6, GRID_H + 6, {100, 120, 200, 255}); // Outer border
-            drawRect(gridX - 1 - contentOffsetX, gridY - 1 - contentOffsetY, GRID_W + 2, GRID_H + 2, {60, 80, 160, 255});   // Inner border
-            drawRect(gridX - contentOffsetX, gridY - contentOffsetY, GRID_W, GRID_H, {20, 25, 35, 255}); // Background
-            
-            // Left panel background (BLOCKS panel) - translucent, slightly shorter height
-            {
-                SDL_SetRenderDrawColor(renderer, 10, 15, 25, 160);
-                SDL_FRect lbg{statsX - 16, gridY - 10, statsW + 32, GRID_H + 20};
-                SDL_RenderFillRect(renderer, &lbg);
-            }
-            // Right panel background (SCORE/LINES/LEVEL etc) - translucent
-            {
-                SDL_SetRenderDrawColor(renderer, 10, 15, 25, 160);
-                SDL_FRect rbg{scoreX - 16, gridY - 16, scoreW + 32, GRID_H + 32};
-                SDL_RenderFillRect(renderer, &rbg);
-            }
-
-            // Draw grid lines (subtle lines to show cell boundaries)
-            SDL_SetRenderDrawColor(renderer, 40, 45, 60, 255); // Slightly lighter than background
-            
-            // Vertical grid lines
-            for (int x = 1; x < Game::COLS; ++x) {
-                float lineX = gridX + x * finalBlockSize; // Remove duplicate contentOffsetX
-                SDL_RenderLine(renderer, lineX, gridY, lineX, gridY + GRID_H);
-            }
-            
-            // Horizontal grid lines
-            for (int y = 1; y < Game::ROWS; ++y) {
-                float lineY = gridY + y * finalBlockSize; // Remove duplicate contentOffsetY
-                SDL_RenderLine(renderer, gridX, lineY, gridX + GRID_W, lineY);
-            }
-            
-            // Block statistics panel
-            drawRect(statsX - 3 - contentOffsetX, statsY - 3 - contentOffsetY, statsW + 6, statsH + 6, {100, 120, 200, 255});
-            drawRect(statsX - contentOffsetX, statsY - contentOffsetY, statsW, statsH, {30, 35, 50, 255});
-            
-            // Next piece preview panel
-            drawRect(nextX - 3 - contentOffsetX, nextY - 3 - contentOffsetY, nextW + 6, nextH + 6, {100, 120, 200, 255});
-            drawRect(nextX - contentOffsetX, nextY - contentOffsetY, nextW, nextH, {30, 35, 50, 255});
-            
-            // Draw the game board
-            const auto &board = game.boardRef();
-            for (int y = 0; y < Game::ROWS; ++y)
-            {
-                for (int x = 0; x < Game::COLS; ++x)
-                {
-                    int v = board[y * Game::COLS + x];
-                    if (v > 0) {
-                        float bx = gridX + x * finalBlockSize;
-                        float by = gridY + y * finalBlockSize;
-                        drawBlockTexture(renderer, blocksTex, bx, by, finalBlockSize, v - 1);
-                    }
-                }
-            }
-
-            // Draw ghost piece (where current piece will land)
-            if (!game.isPaused()) {
-                Game::Piece ghostPiece = game.current();
-                // Find landing position
-                while (true) {
-                    Game::Piece testPiece = ghostPiece;
-                    testPiece.y++;
-                    bool collision = false;
-                    
-                    // Simple collision check
-                    for (int cy = 0; cy < 4; ++cy) {
-                        for (int cx = 0; cx < 4; ++cx) {
-                            if (Game::cellFilled(testPiece, cx, cy)) {
-                                int gx = testPiece.x + cx;
-                                int gy = testPiece.y + cy;
-                                if (gy >= Game::ROWS || gx < 0 || gx >= Game::COLS || 
-                                    (gy >= 0 && board[gy * Game::COLS + gx] != 0)) {
-                                    collision = true;
-                                    break;
-                                }
-                            }
-                        }
-                        if (collision) break;
-                    }
-                    
-                    if (collision) break;
-                    ghostPiece = testPiece;
-                }
-                
-                // Draw ghost piece
-                drawPiece(renderer, blocksTex, ghostPiece, gridX, gridY, finalBlockSize, true);
-            }
-
-            // Draw the falling piece
-            if (!game.isPaused()) {
-                drawPiece(renderer, blocksTex, game.current(), gridX, gridY, finalBlockSize, false);
-            }
-            
-            // Draw line clearing effects
-            if (lineEffect.isActive()) {
-                lineEffect.render(renderer, static_cast<int>(gridX), static_cast<int>(gridY), static_cast<int>(finalBlockSize));
-            }
-
-            // Draw next piece preview
-            pixelFont.draw(renderer, nextX + 10, nextY - 20, "NEXT", 1.0f, {255, 220, 0, 255});
-            if (game.next().type < PIECE_COUNT) {
-                drawSmallPiece(renderer, blocksTex, game.next().type, nextX + 10, nextY + 10, finalBlockSize * 0.6f);
-            }
-
-            // Draw block statistics (left panel)
-            pixelFont.draw(renderer, statsX + 10, statsY + 10, "BLOCKS", 1.0f, {255, 220, 0, 255});
-            
-            const auto& blockCounts = game.getBlockCounts();
-            int totalBlocks = 0; for (int i = 0; i < PIECE_COUNT; ++i) totalBlocks += blockCounts[i];
-            const char* pieceNames[] = {"I", "O", "T", "S", "Z", "J", "L"};
-            // Dynamic vertical cursor so bars sit below blocks cleanly
-            float yCursor = statsY + 52;
-            for (int i = 0; i < PIECE_COUNT; ++i) {
-                // Baseline for this entry
-                float py = yCursor;
-
-                // Draw small piece icon (top of entry)
-                float previewSize = finalBlockSize * 0.55f;
-                drawSmallPiece(renderer, blocksTex, static_cast<PieceType>(i), statsX + 18, py, previewSize);
-
-                // Compute preview height in tiles (rotation 0)
-                int maxCy = -1;
-                {
-                    Game::Piece prev; prev.type = static_cast<PieceType>(i); prev.rot = 0; prev.x = 0; prev.y = 0;
-                    for (int cy = 0; cy < 4; ++cy) {
-                        for (int cx = 0; cx < 4; ++cx) {
-                            if (Game::cellFilled(prev, cx, cy)) maxCy = std::max(maxCy, cy);
-                        }
-                    }
-                }
-                int tilesHigh = (maxCy >= 0 ? maxCy + 1 : 1);
-                float previewHeight = tilesHigh * previewSize;
-
-                // Count on the right, near the top (aligned with blocks)
-                int count = blockCounts[i];
-                char countStr[16];
-                snprintf(countStr, sizeof(countStr), "%d", count);
-                pixelFont.draw(renderer, statsX + statsW - 20, py + 6, countStr, 1.1f, {240, 240, 245, 255});
-
-                // Percentage and bar BELOW the blocks
-                int perc = (totalBlocks > 0) ? int(std::round(100.0 * double(count) / double(totalBlocks))) : 0;
-                char percStr[16];
-                snprintf(percStr, sizeof(percStr), "%d%%", perc);
-
-                float barX = statsX + 12;
-                float barY = py + previewHeight + 18.0f;
-                float barW = statsW - 24;
-                float barH = 6;
-
-                // Percent text just above the bar (left)
-                pixelFont.draw(renderer, barX, barY - 16, percStr, 0.8f, {230, 230, 235, 255});
-
-                // Track
-                SDL_SetRenderDrawColor(renderer, 170, 170, 175, 200);
-                SDL_FRect track{barX, barY, barW, barH};
-                SDL_RenderFillRect(renderer, &track);
-                // Fill (piece color)
-                SDL_Color pc = COLORS[i + 1];
-                SDL_SetRenderDrawColor(renderer, pc.r, pc.g, pc.b, 230);
-                float fillW = barW * (perc / 100.0f);
-                if (fillW < 0) fillW = 0; if (fillW > barW) fillW = barW;
-                SDL_FRect fill{barX, barY, fillW, barH};
-                SDL_RenderFillRect(renderer, &fill);
-
-                // Advance cursor: bar bottom + spacing
-                yCursor = barY + barH + 18.0f;
-            }
-
-            // Draw score panel (right side), centered vertically in grid
-            // Compute content vertical centering based on known offsets
-            const float contentTopOffset = 0.0f;
-            const float contentBottomOffset = 290.0f; // last line (time value)
-            const float contentPad = 36.0f;
-            float scoreContentH = (contentBottomOffset - contentTopOffset) + contentPad;
-            float baseY = gridY + (GRID_H - scoreContentH) * 0.5f;
-
-            pixelFont.draw(renderer, scoreX, baseY + 0, "SCORE", 1.0f, {255, 220, 0, 255});
-            char scoreStr[32];
-            snprintf(scoreStr, sizeof(scoreStr), "%d", game.score());
-            pixelFont.draw(renderer, scoreX, baseY + 25, scoreStr, 0.9f, {255, 255, 255, 255});
-
-            pixelFont.draw(renderer, scoreX, baseY + 70, "LINES", 1.0f, {255, 220, 0, 255});
-            char linesStr[16];
-            snprintf(linesStr, sizeof(linesStr), "%03d", game.lines());
-            pixelFont.draw(renderer, scoreX, baseY + 95, linesStr, 0.9f, {255, 255, 255, 255});
-
-            pixelFont.draw(renderer, scoreX, baseY + 140, "LEVEL", 1.0f, {255, 220, 0, 255});
-            char levelStr[16];
-            snprintf(levelStr, sizeof(levelStr), "%02d", game.level());
-            pixelFont.draw(renderer, scoreX, baseY + 165, levelStr, 0.9f, {255, 255, 255, 255});
-
-            // Next level progress
-            // JS rules: first threshold = (startLevel+1)*10; afterwards every +10
-            int startLv = game.startLevelBase(); // 0-based
-            int firstThreshold = (startLv + 1) * 10;
-            int linesDone = game.lines();
-            int nextThreshold = 0;
-            if (linesDone < firstThreshold) {
-                nextThreshold = firstThreshold;
-            } else {
-                int blocksPast = linesDone - firstThreshold;
-                nextThreshold = firstThreshold + ((blocksPast / 10) + 1) * 10;
-            }
-            int linesForNext = std::max(0, nextThreshold - linesDone);
-            pixelFont.draw(renderer, scoreX, baseY + 200, "NEXT LVL", 1.0f, {255, 220, 0, 255});
-            char nextStr[32];
-            snprintf(nextStr, sizeof(nextStr), "%d  LINES", linesForNext);
-            pixelFont.draw(renderer, scoreX, baseY + 225, nextStr, 0.9f, {80, 255, 120, 255});
-
-            // Time
-            pixelFont.draw(renderer, scoreX, baseY + 265, "TIME", 1.0f, {255, 220, 0, 255});
-            int totalSecs = static_cast<int>(game.elapsed());
-            int mins = totalSecs / 60;
-            int secs = totalSecs % 60;
-            char timeStr[16];
-            snprintf(timeStr, sizeof(timeStr), "%02d:%02d", mins, secs);
-            pixelFont.draw(renderer, scoreX, baseY + 290, timeStr, 0.9f, {255, 255, 255, 255});
-
-            // --- Gravity HUD: show current gravity in ms and equivalent fps (top-right) ---
-            {
-                char gms[64];
-                double gms_val = game.getGravityMs();
-                double gfps = gms_val > 0.0 ? (1000.0 / gms_val) : 0.0;
-                snprintf(gms, sizeof(gms), "GRAV: %.0f ms (%.2f fps)", gms_val, gfps);
-                pixelFont.draw(renderer, LOGICAL_W - 260, 10, gms, 0.9f, {200, 200, 220, 255});
-            }
-
-            // Hold piece (if implemented)
-            if (game.held().type < PIECE_COUNT) {
-                pixelFont.draw(renderer, statsX + 10, statsY + statsH - 80, "HOLD", 1.0f, {255, 220, 0, 255});
-                drawSmallPiece(renderer, blocksTex, game.held().type, statsX + 60, statsY + statsH - 80, finalBlockSize * 0.6f);
-            }
-
-            // Pause overlay
-            if (game.isPaused()) {
-                // Semi-transparent overlay
-                SDL_SetRenderDrawColor(renderer, 0, 0, 0, 180);
-                SDL_FRect pauseOverlay{0, 0, LOGICAL_W, LOGICAL_H};
-                SDL_RenderFillRect(renderer, &pauseOverlay);
-                
-                // Pause text
-                pixelFont.draw(renderer, LOGICAL_W * 0.5f - 80, LOGICAL_H * 0.5f - 20, "PAUSED", 2.0f, {255, 255, 255, 255});
-                pixelFont.draw(renderer, LOGICAL_W * 0.5f - 120, LOGICAL_H * 0.5f + 30, "Press P to resume", 0.8f, {200, 200, 220, 255});
-            }
-
-            // Controls hint at bottom
-            font.draw(renderer, 20, LOGICAL_H - 30, "ARROWS=Move  Z/X=Rotate  C=Hold  SPACE=Drop  P=Pause  ESC=Menu", 1.0f, {150, 150, 170, 255});
-        }
-        break;
-        case AppState::GameOver:
-            font.draw(renderer, LOGICAL_W * 0.5f - 120, 140, "GAME OVER", 3.0f, SDL_Color{255, 80, 60, 255});
-            {
-                char buf[128];
-                std::snprintf(buf, sizeof(buf), "SCORE %d  LINES %d  LEVEL %d", game.score(), game.lines(), game.level());
-                font.draw(renderer, LOGICAL_W * 0.5f - 120, 220, buf, 1.2f, SDL_Color{220, 220, 230, 255});
-            }
-            font.draw(renderer, LOGICAL_W * 0.5f - 120, 270, "PRESS ENTER / SPACE", 1.2f, SDL_Color{200, 200, 220, 255});
-            break;
-        }
-
-        SDL_RenderPresent(renderer);
-        SDL_SetRenderScale(renderer, 1.f, 1.f);
-    }
-    if (logoTex)
-        SDL_DestroyTexture(logoTex);
-    if (backgroundTex)
-        SDL_DestroyTexture(backgroundTex);
-    if (levelBackgroundTex)
-        SDL_DestroyTexture(levelBackgroundTex);
-    if (blocksTex)
-        SDL_DestroyTexture(blocksTex);
-    lineEffect.shutdown();
-    Audio::instance().shutdown();
-    SoundEffectManager::instance().shutdown();
-    font.shutdown();
-    TTF_Quit();
-    SDL_DestroyRenderer(renderer);
-    SDL_DestroyWindow(window);
-    SDL_Quit();
-    return 0;
+    TetrisApp app;
+    return app.run();
 }
diff --git a/src/network/CoopNetButtons.h b/src/network/CoopNetButtons.h
new file mode 100644
index 0000000..68d6ec5
--- /dev/null
+++ b/src/network/CoopNetButtons.h
@@ -0,0 +1,21 @@
+#pragma once
+
+#include <cstdint>
+
+namespace coopnet {
+// 8-bit input mask carried in NetSession::InputFrame.
+// Keep in sync across capture/apply on both peers.
+enum Buttons : uint8_t {
+    MoveLeft  = 1u << 0,
+    MoveRight = 1u << 1,
+    SoftDrop  = 1u << 2,
+    RotCW     = 1u << 3,
+    RotCCW    = 1u << 4,
+    HardDrop  = 1u << 5,
+    Hold      = 1u << 6,
+};
+
+inline bool has(uint8_t mask, Buttons b) {
+    return (mask & static_cast<uint8_t>(b)) != 0;
+}
+}
diff --git a/src/network/NetSession.cpp b/src/network/NetSession.cpp
new file mode 100644
index 0000000..026fc67
--- /dev/null
+++ b/src/network/NetSession.cpp
@@ -0,0 +1,324 @@
+#include "NetSession.h"
+
+#include <enet/enet.h>
+
+#include <SDL3/SDL.h>
+
+#include <cstring>
+
+namespace {
+constexpr uint8_t kChannelReliable = 0;
+
+static bool netLogVerboseEnabled() {
+    // Set environment variable / hint: SPACETRIS_NET_LOG=1
+    const char* v = SDL_GetHint("SPACETRIS_NET_LOG");
+    return v && v[0] == '1';
+}
+
+template <typename T>
+static void append(std::vector<uint8_t>& out, const T& value) {
+    const uint8_t* p = reinterpret_cast<const uint8_t*>(&value);
+    out.insert(out.end(), p, p + sizeof(T));
+}
+
+template <typename T>
+static bool read(const uint8_t* data, size_t size, size_t& off, T& out) {
+    if (off + sizeof(T) > size) return false;
+    std::memcpy(&out, data + off, sizeof(T));
+    off += sizeof(T);
+    return true;
+}
+}
+
+NetSession::NetSession() = default;
+
+NetSession::~NetSession() {
+    shutdown();
+}
+
+bool NetSession::ensureEnetInitialized() {
+    static bool s_inited = false;
+    if (s_inited) return true;
+    if (enet_initialize() != 0) {
+        setError("enet_initialize failed");
+        m_state = ConnState::Error;
+        return false;
+    }
+    s_inited = true;
+    return true;
+}
+
+void NetSession::setError(const std::string& msg) {
+    m_lastError = msg;
+}
+
+bool NetSession::host(const std::string& bindHost, uint16_t port) {
+    shutdown();
+    if (!ensureEnetInitialized()) return false;
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] host(bind='%s', port=%u)", bindHost.c_str(), (unsigned)port);
+
+    ENetAddress address{};
+    address.host = ENET_HOST_ANY;
+    address.port = port;
+
+    if (!bindHost.empty() && bindHost != "0.0.0.0") {
+        if (enet_address_set_host(&address, bindHost.c_str()) != 0) {
+            setError("enet_address_set_host (bind) failed");
+            m_state = ConnState::Error;
+            return false;
+        }
+    }
+
+    // 1 peer, 2 channels (reserve extra)
+    m_host = enet_host_create(&address, 1, 2, 0, 0);
+    if (!m_host) {
+        setError("enet_host_create (host) failed");
+        m_state = ConnState::Error;
+        return false;
+    }
+
+    m_mode = Mode::Host;
+    m_state = ConnState::Connecting;
+    return true;
+}
+
+bool NetSession::join(const std::string& hostNameOrIp, uint16_t port) {
+    shutdown();
+    if (!ensureEnetInitialized()) return false;
+
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] join(remote='%s', port=%u)", hostNameOrIp.c_str(), (unsigned)port);
+
+    m_host = enet_host_create(nullptr, 1, 2, 0, 0);
+    if (!m_host) {
+        setError("enet_host_create (client) failed");
+        m_state = ConnState::Error;
+        return false;
+    }
+
+    ENetAddress address{};
+    if (enet_address_set_host(&address, hostNameOrIp.c_str()) != 0) {
+        setError("enet_address_set_host failed");
+        m_state = ConnState::Error;
+        return false;
+    }
+    address.port = port;
+
+    m_peer = enet_host_connect(m_host, &address, 2, 0);
+    if (!m_peer) {
+        setError("enet_host_connect failed");
+        m_state = ConnState::Error;
+        return false;
+    }
+
+    m_mode = Mode::Client;
+    m_state = ConnState::Connecting;
+    return true;
+}
+
+void NetSession::shutdown() {
+    if (m_host || m_peer) {
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] shutdown(mode=%d state=%d)", (int)m_mode, (int)m_state);
+    }
+
+    m_remoteInputs.clear();
+    m_remoteHashes.clear();
+    m_receivedHandshake.reset();
+
+    m_inputsSent = 0;
+    m_inputsReceived = 0;
+    m_hashesSent = 0;
+    m_hashesReceived = 0;
+    m_handshakesSent = 0;
+    m_handshakesReceived = 0;
+    m_lastRecvInputTick = 0xFFFFFFFFu;
+    m_lastRecvHashTick = 0xFFFFFFFFu;
+    m_lastStatsLogMs = 0;
+
+    if (m_peer) {
+        enet_peer_disconnect(m_peer, 0);
+        m_peer = nullptr;
+    }
+
+    if (m_host) {
+        enet_host_destroy(m_host);
+        m_host = nullptr;
+    }
+
+    m_mode = Mode::None;
+    m_state = ConnState::Disconnected;
+    m_lastError.clear();
+}
+
+void NetSession::poll(uint32_t timeoutMs) {
+    if (!m_host) return;
+
+    ENetEvent event{};
+    while (enet_host_service(m_host, &event, static_cast<enet_uint32>(timeoutMs)) > 0) {
+        switch (event.type) {
+            case ENET_EVENT_TYPE_CONNECT:
+                m_peer = event.peer;
+                m_state = ConnState::Connected;
+                SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] connected (mode=%d)", (int)m_mode);
+                break;
+            case ENET_EVENT_TYPE_RECEIVE:
+                if (event.packet) {
+                    handlePacket(event.packet->data, event.packet->dataLength);
+                    enet_packet_destroy(event.packet);
+                }
+                break;
+            case ENET_EVENT_TYPE_DISCONNECT:
+                m_peer = nullptr;
+                m_state = ConnState::Disconnected;
+                SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "[NET] disconnected");
+                break;
+            case ENET_EVENT_TYPE_NONE:
+            default:
+                break;
+        }
+
+        // After first event, do non-blocking passes.
+        timeoutMs = 0;
+    }
+
+    // Rate-limited stats log (opt-in)
+    if (netLogVerboseEnabled()) {
+        const uint32_t nowMs = SDL_GetTicks();
+        if (m_lastStatsLogMs == 0) m_lastStatsLogMs = nowMs;
+        if (nowMs - m_lastStatsLogMs >= 1000u) {
+            m_lastStatsLogMs = nowMs;
+            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION,
+                        "[NET] stats: sent(in=%u hash=%u hs=%u) recv(in=%u hash=%u hs=%u) lastRecv(inTick=%u hashTick=%u) state=%d",
+                        m_inputsSent,
+                        m_hashesSent,
+                        m_handshakesSent,
+                        m_inputsReceived,
+                        m_hashesReceived,
+                        m_handshakesReceived,
+                        m_lastRecvInputTick,
+                        m_lastRecvHashTick,
+                        (int)m_state);
+        }
+    }
+}
+
+bool NetSession::sendBytesReliable(const void* data, size_t size) {
+    if (!m_peer) return false;
+    ENetPacket* packet = enet_packet_create(data, size, ENET_PACKET_FLAG_RELIABLE);
+    if (!packet) return false;
+    if (enet_peer_send(m_peer, kChannelReliable, packet) != 0) {
+        enet_packet_destroy(packet);
+        return false;
+    }
+    // Let the caller decide flush cadence; but for tiny control packets, flushing is cheap.
+    enet_host_flush(m_host);
+    return true;
+}
+
+bool NetSession::sendHandshake(const Handshake& hs) {
+    if (m_mode != Mode::Host) return false;
+    m_handshakesSent++;
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] sendHandshake(seed=%u startTick=%u startLevel=%u)", hs.rngSeed, hs.startTick, (unsigned)hs.startLevel);
+    std::vector<uint8_t> buf;
+    buf.reserve(1 + sizeof(uint32_t) * 2 + sizeof(uint8_t));
+    buf.push_back(static_cast<uint8_t>(MsgType::Handshake));
+    append(buf, hs.rngSeed);
+    append(buf, hs.startTick);
+    append(buf, hs.startLevel);
+    return sendBytesReliable(buf.data(), buf.size());
+}
+
+std::optional<NetSession::Handshake> NetSession::takeReceivedHandshake() {
+    auto out = m_receivedHandshake;
+    m_receivedHandshake.reset();
+    return out;
+}
+
+bool NetSession::sendLocalInput(uint32_t tick, uint8_t buttons) {
+    m_inputsSent++;
+    if (netLogVerboseEnabled() && (tick % 60u) == 0u) {
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] sendInput(tick=%u buttons=0x%02X)", tick, (unsigned)buttons);
+    }
+    std::vector<uint8_t> buf;
+    buf.reserve(1 + sizeof(uint32_t) + sizeof(uint8_t));
+    buf.push_back(static_cast<uint8_t>(MsgType::Input));
+    append(buf, tick);
+    append(buf, buttons);
+    return sendBytesReliable(buf.data(), buf.size());
+}
+
+std::optional<uint8_t> NetSession::getRemoteButtons(uint32_t tick) const {
+    auto it = m_remoteInputs.find(tick);
+    if (it == m_remoteInputs.end()) return std::nullopt;
+    return it->second;
+}
+
+bool NetSession::sendStateHash(uint32_t tick, uint64_t hash) {
+    m_hashesSent++;
+    if (netLogVerboseEnabled()) {
+        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] sendHash(tick=%u hash=%llu)", tick, (unsigned long long)hash);
+    }
+    std::vector<uint8_t> buf;
+    buf.reserve(1 + sizeof(uint32_t) + sizeof(uint64_t));
+    buf.push_back(static_cast<uint8_t>(MsgType::Hash));
+    append(buf, tick);
+    append(buf, hash);
+    return sendBytesReliable(buf.data(), buf.size());
+}
+
+std::optional<uint64_t> NetSession::takeRemoteHash(uint32_t tick) {
+    auto it = m_remoteHashes.find(tick);
+    if (it == m_remoteHashes.end()) return std::nullopt;
+    uint64_t v = it->second;
+    m_remoteHashes.erase(it);
+    return v;
+}
+
+void NetSession::handlePacket(const uint8_t* data, size_t size) {
+    if (!data || size < 1) return;
+    size_t off = 0;
+    uint8_t typeByte = 0;
+    if (!read(data, size, off, typeByte)) return;
+
+    MsgType t = static_cast<MsgType>(typeByte);
+    switch (t) {
+        case MsgType::Handshake: {
+            Handshake hs{};
+            if (!read(data, size, off, hs.rngSeed)) return;
+            if (!read(data, size, off, hs.startTick)) return;
+            if (!read(data, size, off, hs.startLevel)) return;
+            m_receivedHandshake = hs;
+            m_handshakesReceived++;
+            SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] recvHandshake(seed=%u startTick=%u startLevel=%u)", hs.rngSeed, hs.startTick, (unsigned)hs.startLevel);
+            break;
+        }
+        case MsgType::Input: {
+            uint32_t tick = 0;
+            uint8_t buttons = 0;
+            if (!read(data, size, off, tick)) return;
+            if (!read(data, size, off, buttons)) return;
+            m_remoteInputs[tick] = buttons;
+            m_inputsReceived++;
+            m_lastRecvInputTick = tick;
+            if (netLogVerboseEnabled() && (tick % 60u) == 0u) {
+                SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] recvInput(tick=%u buttons=0x%02X)", tick, (unsigned)buttons);
+            }
+            break;
+        }
+        case MsgType::Hash: {
+            uint32_t tick = 0;
+            uint64_t hash = 0;
+            if (!read(data, size, off, tick)) return;
+            if (!read(data, size, off, hash)) return;
+            m_remoteHashes[tick] = hash;
+            m_hashesReceived++;
+            m_lastRecvHashTick = tick;
+            if (netLogVerboseEnabled()) {
+                SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET] recvHash(tick=%u hash=%llu)", tick, (unsigned long long)hash);
+            }
+            break;
+        }
+        default:
+            break;
+    }
+}
diff --git a/src/network/NetSession.h b/src/network/NetSession.h
new file mode 100644
index 0000000..d02da9f
--- /dev/null
+++ b/src/network/NetSession.h
@@ -0,0 +1,118 @@
+#pragma once
+
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+struct _ENetHost;
+struct _ENetPeer;
+
+// Lockstep networking session for COOPERATE (network) mode.
+//
+// Design goals:
+// - Non-blocking polling (caller drives poll from the main loop)
+// - Reliable, ordered delivery for inputs and control messages
+// - Host provides seed + start tick (handshake)
+// - Only inputs/state hashes are exchanged (no board sync)
+class NetSession {
+public:
+    enum class Mode {
+        None,
+        Host,
+        Client,
+    };
+
+    enum class ConnState {
+        Disconnected,
+        Connecting,
+        Connected,
+        Error,
+    };
+
+    struct Handshake {
+        uint32_t rngSeed = 0;
+        uint32_t startTick = 0;
+        uint8_t startLevel = 0;
+    };
+
+    struct InputFrame {
+        uint32_t tick = 0;
+        uint8_t buttons = 0;
+    };
+
+    NetSession();
+    ~NetSession();
+
+    NetSession(const NetSession&) = delete;
+    NetSession& operator=(const NetSession&) = delete;
+
+    // If bindHost is empty or "0.0.0.0", binds to ENET_HOST_ANY.
+    bool host(const std::string& bindHost, uint16_t port);
+    bool join(const std::string& hostNameOrIp, uint16_t port);
+    void shutdown();
+
+    void poll(uint32_t timeoutMs = 0);
+
+    Mode mode() const { return m_mode; }
+    ConnState state() const { return m_state; }
+    bool isConnected() const { return m_state == ConnState::Connected; }
+
+    // Host-only: send handshake once the peer connects.
+    bool sendHandshake(const Handshake& hs);
+
+    // Client-only: becomes available once received from host.
+    std::optional<Handshake> takeReceivedHandshake();
+
+    // Input exchange --------------------------------------------------------
+    // Send local input for a given simulation tick.
+    bool sendLocalInput(uint32_t tick, uint8_t buttons);
+
+    // Returns the last received remote input for a tick (if any).
+    std::optional<uint8_t> getRemoteButtons(uint32_t tick) const;
+
+    // Hash exchange (for desync detection) ---------------------------------
+    bool sendStateHash(uint32_t tick, uint64_t hash);
+    std::optional<uint64_t> takeRemoteHash(uint32_t tick);
+
+    // Diagnostics
+    std::string lastError() const { return m_lastError; }
+
+private:
+    enum class MsgType : uint8_t {
+        Handshake = 1,
+        Input = 2,
+        Hash = 3,
+    };
+
+    bool ensureEnetInitialized();
+    void setError(const std::string& msg);
+
+    bool sendBytesReliable(const void* data, size_t size);
+    void handlePacket(const uint8_t* data, size_t size);
+
+    Mode m_mode = Mode::None;
+    ConnState m_state = ConnState::Disconnected;
+
+    _ENetHost* m_host = nullptr;
+    _ENetPeer* m_peer = nullptr;
+
+    std::string m_lastError;
+
+    std::optional<Handshake> m_receivedHandshake;
+
+    std::unordered_map<uint32_t, uint8_t> m_remoteInputs;
+    std::unordered_map<uint32_t, uint64_t> m_remoteHashes;
+
+    // Debug logging (rate-limited)
+    uint32_t m_inputsSent = 0;
+    uint32_t m_inputsReceived = 0;
+    uint32_t m_hashesSent = 0;
+    uint32_t m_hashesReceived = 0;
+    uint32_t m_handshakesSent = 0;
+    uint32_t m_handshakesReceived = 0;
+    uint32_t m_lastRecvInputTick = 0xFFFFFFFFu;
+    uint32_t m_lastRecvHashTick = 0xFFFFFFFFu;
+    uint32_t m_lastStatsLogMs = 0;
+};
diff --git a/src/network/supabase_client.cpp b/src/network/supabase_client.cpp
new file mode 100644
index 0000000..51e8bbe
--- /dev/null
+++ b/src/network/supabase_client.cpp
@@ -0,0 +1,182 @@
+#include "supabase_client.h"
+#include <curl/curl.h>
+#include <nlohmann/json.hpp>
+#include <thread>
+#include <iostream>
+#include <algorithm>
+#include <cmath>
+
+using json = nlohmann::json;
+
+namespace {
+// Supabase constants (publishable anon key)
+const std::string SUPABASE_URL = "https://xzxpmvyamjvtxpwnjpad.supabase.co";
+const std::string SUPABASE_ANON_KEY = "sb_publishable_GqQx844xYDizO9-ytlBXfA_MVT6N7yA";
+
+std::string buildUrl(const std::string &path) {
+    std::string url = SUPABASE_URL;
+    if (!url.empty() && url.back() == '/') url.pop_back();
+    url += "/rest/v1/" + path;
+    return url;
+}
+
+size_t curlWriteCallback(void* contents, size_t size, size_t nmemb, void* userp) {
+    size_t realSize = size * nmemb;
+    std::string *s = reinterpret_cast<std::string*>(userp);
+    s->append(reinterpret_cast<char*>(contents), realSize);
+    return realSize;
+}
+
+struct CurlInit {
+    CurlInit() { curl_global_init(CURL_GLOBAL_DEFAULT); }
+    ~CurlInit() { curl_global_cleanup(); }
+};
+static CurlInit g_curl_init;
+}
+
+namespace supabase {
+
+static bool g_verbose = false;
+
+void SetVerbose(bool enabled) {
+    g_verbose = enabled;
+}
+
+
+void SubmitHighscoreAsync(const ScoreEntry &entry) {
+    std::thread([entry]() {
+        try {
+            CURL* curl = curl_easy_init();
+            if (!curl) return;
+
+            std::string url = buildUrl("highscores");
+
+            json j;
+            j["score"] = entry.score;
+            j["lines"] = entry.lines;
+            j["level"] = entry.level;
+            j["time_sec"] = static_cast<int>(std::lround(entry.timeSec));
+            j["name"] = entry.name;
+            j["game_type"] = entry.gameType;
+            j["timestamp"] = static_cast<int>(std::time(nullptr));
+
+            std::string body = j.dump();
+            struct curl_slist *headers = nullptr;
+            std::string h1 = std::string("apikey: ") + SUPABASE_ANON_KEY;
+            std::string h2 = std::string("Authorization: Bearer ") + SUPABASE_ANON_KEY;
+            headers = curl_slist_append(headers, h1.c_str());
+            headers = curl_slist_append(headers, h2.c_str());
+            headers = curl_slist_append(headers, "Content-Type: application/json");
+
+            std::string resp;
+            curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
+            curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
+            curl_easy_setopt(curl, CURLOPT_POSTFIELDS, body.c_str());
+            curl_easy_setopt(curl, CURLOPT_TIMEOUT, 5L);
+            curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, curlWriteCallback);
+            curl_easy_setopt(curl, CURLOPT_WRITEDATA, &resp);
+
+            if (g_verbose) {
+                std::cerr << "[Supabase] POST " << url << "\n";
+                std::cerr << "[Supabase] Body: " << body << "\n";
+            }
+
+            CURLcode res = curl_easy_perform(curl);
+            if (res != CURLE_OK) {
+                if (g_verbose) std::cerr << "[Supabase] POST error: " << curl_easy_strerror(res) << "\n";
+            } else {
+                long http_code = 0;
+                curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &http_code);
+                if (g_verbose) {
+                    std::cerr << "[Supabase] POST response code: " << http_code << " body_len=" << resp.size() << "\n";
+                    if (!resp.empty()) std::cerr << "[Supabase] POST response: " << resp << "\n";
+                }
+            }
+
+            curl_slist_free_all(headers);
+            curl_easy_cleanup(curl);
+        } catch (...) {
+            // swallow errors
+        }
+    }).detach();
+}
+
+std::vector<ScoreEntry> FetchHighscores(const std::string &gameType, int limit) {
+    std::vector<ScoreEntry> out;
+    try {
+        CURL* curl = curl_easy_init();
+        if (!curl) return out;
+
+        std::string path = "highscores";
+        // Clamp limit to max 10 to keep payloads small
+        int l = std::clamp(limit, 1, 10);
+        std::string query;
+        if (!gameType.empty()) {
+            if (gameType == "challenge") {
+                query = "?game_type=eq." + gameType + "&order=level.desc,time_sec.asc&limit=" + std::to_string(l);
+            } else {
+                query = "?game_type=eq." + gameType + "&order=score.desc&limit=" + std::to_string(l);
+            }
+        } else {
+            query = "?order=score.desc&limit=" + std::to_string(l);
+        }
+
+        std::string url = buildUrl(path) + query;
+
+        struct curl_slist *headers = nullptr;
+        headers = curl_slist_append(headers, ("apikey: " + SUPABASE_ANON_KEY).c_str());
+        headers = curl_slist_append(headers, ("Authorization: Bearer " + SUPABASE_ANON_KEY).c_str());
+        headers = curl_slist_append(headers, "Content-Type: application/json");
+
+
+        std::string resp;
+        curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
+        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
+        curl_easy_setopt(curl, CURLOPT_TIMEOUT, 5L);
+        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, curlWriteCallback);
+        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &resp);
+
+        if (g_verbose) std::cerr << "[Supabase] GET " << url << "\n";
+
+        CURLcode res = curl_easy_perform(curl);
+        if (res == CURLE_OK) {
+            long http_code = 0;
+            curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &http_code);
+            if (g_verbose) {
+                std::cerr << "[Supabase] GET response code: " << http_code << " body_len=" << resp.size() << "\n";
+                if (!resp.empty()) std::cerr << "[Supabase] GET response: " << resp << "\n";
+            }
+            try {
+                auto j = json::parse(resp);
+                if (j.is_array()) {
+                    for (auto &v : j) {
+                        ScoreEntry e{};
+                        if (v.contains("score")) e.score = v["score"].get<int>();
+                        if (v.contains("lines")) e.lines = v["lines"].get<int>();
+                        if (v.contains("level")) e.level = v["level"].get<int>();
+                        if (v.contains("time_sec")) {
+                            try { e.timeSec = v["time_sec"].get<double>(); } catch(...) { e.timeSec = v["time_sec"].get<int>(); }
+                        } else if (v.contains("timestamp")) {
+                            e.timeSec = v["timestamp"].get<int>();
+                        }
+                        if (v.contains("name")) e.name = v["name"].get<std::string>();
+                        if (v.contains("game_type")) e.gameType = v["game_type"].get<std::string>();
+                        out.push_back(e);
+                    }
+                }
+            } catch (...) {
+                if (g_verbose) std::cerr << "[Supabase] GET parse error" << std::endl;
+            }
+        } else {
+            if (g_verbose) std::cerr << "[Supabase] GET error: " << curl_easy_strerror(res) << "\n";
+        }
+
+        curl_slist_free_all(headers);
+        curl_easy_cleanup(curl);
+    } catch (...) {
+        // swallow
+    }
+    return out;
+}
+
+} // namespace supabase
diff --git a/src/network/supabase_client.h b/src/network/supabase_client.h
new file mode 100644
index 0000000..93b5b22
--- /dev/null
+++ b/src/network/supabase_client.h
@@ -0,0 +1,17 @@
+#pragma once
+#include <string>
+#include <vector>
+#include "../persistence/Scores.h"
+
+namespace supabase {
+
+// Submit a highscore asynchronously (detached thread)
+void SubmitHighscoreAsync(const ScoreEntry &entry);
+
+// Fetch highscores for a game type. If gameType is empty, fetch all (limited).
+std::vector<ScoreEntry> FetchHighscores(const std::string &gameType, int limit);
+
+// Enable or disable verbose logging to stderr. Disabled by default.
+void SetVerbose(bool enabled);
+
+} // namespace supabase
diff --git a/src/persistence/Scores.cpp b/src/persistence/Scores.cpp
index fafd4ca..5aa8229 100644
--- a/src/persistence/Scores.cpp
+++ b/src/persistence/Scores.cpp
@@ -1,21 +1,46 @@
-// Scores.cpp - Implementation of ScoreManager (copied into src/persistence)
+// Scores.cpp - Implementation of ScoreManager
 #include "Scores.h"
 #include <SDL3/SDL.h>
 #include <fstream>
 #include <sstream>
 #include <algorithm>
+#include "../network/supabase_client.h"
+#include <nlohmann/json.hpp>
+#include <iostream>
+#include <thread>
+#include <ctime>
+#include <filesystem>
+
+using json = nlohmann::json;
 
 ScoreManager::ScoreManager(size_t maxScores) : maxEntries(maxScores) {}
 
 std::string ScoreManager::filePath() const {
     static std::string path; if (!path.empty()) return path;
-    char* base = SDL_GetPrefPath("example","tetris_sdl3");
+    char* base = SDL_GetPrefPath("example","spacetris_sdl3");
     if (base) { path = std::string(base)+"highscores.txt"; SDL_free(base);} else path="highscores.txt";
     return path;
 }
 
 void ScoreManager::load() {
     scores.clear();
+    
+    // Try to load from Supabase first
+    try {
+        // Request only 10 records from Supabase to keep payload small
+        auto fetched = supabase::FetchHighscores("", 10);
+        if (!fetched.empty()) {
+            scores = fetched;
+            std::sort(scores.begin(), scores.end(), [](auto&a,auto&b){return a.score>b.score;});
+            if (scores.size() > maxEntries) scores.resize(maxEntries);
+            save();
+            return;
+        }
+    } catch (...) {
+        std::cerr << "Failed to load from Supabase, falling back to local file." << std::endl;
+    }
+
+    // Fallback to local file
     std::ifstream f(filePath()); 
     if (!f) {
         // Create sample high scores if file doesn't exist
@@ -30,11 +55,32 @@ void ScoreManager::load() {
         ScoreEntry e; 
         iss >> e.score >> e.lines >> e.level >> e.timeSec;
         if (iss) {
-            // Try to read name (rest of line after timeSec)
+            // Try to read name (rest of line after timeSec). We may also have a trailing gameType token.
             std::string remaining;
             std::getline(iss, remaining);
-            if (!remaining.empty() && remaining[0] == ' ') {
-                e.name = remaining.substr(1); // Remove leading space
+            if (!remaining.empty() && remaining[0] == ' ') remaining = remaining.substr(1);
+            if (!remaining.empty()) {
+                static const std::vector<std::string> known = {"classic","cooperate","challenge","versus"};
+                while (!remaining.empty() && (remaining.back() == '\n' || remaining.back() == '\r' || remaining.back() == ' ')) remaining.pop_back();
+                size_t lastSpace = remaining.find_last_of(' ');
+                std::string lastToken = (lastSpace == std::string::npos) ? remaining : remaining.substr(lastSpace + 1);
+                bool matched = false;
+                for (const auto &k : known) {
+                    if (lastToken == k) {
+                        matched = true;
+                        e.gameType = k;
+                        if (lastSpace == std::string::npos) e.name = "PLAYER";
+                        else e.name = remaining.substr(0, lastSpace);
+                        break;
+                    }
+                }
+                if (!matched) {
+                    e.name = remaining;
+                    e.gameType = "classic";
+                }
+            } else {
+                e.name = "PLAYER";
+                e.gameType = "classic";
             }
             scores.push_back(e);
         }
@@ -52,30 +98,57 @@ void ScoreManager::load() {
 void ScoreManager::save() const {
     std::ofstream f(filePath(), std::ios::trunc);
     for (auto &e : scores) {
-        f << e.score << ' ' << e.lines << ' ' << e.level << ' ' << e.timeSec << ' ' << e.name << '\n';
+        // Save gameType as trailing token so future loads can preserve it
+        f << e.score << ' ' << e.lines << ' ' << e.level << ' ' << e.timeSec << ' ' << e.name << ' ' << e.gameType << '\n';
     }
 }
 
-void ScoreManager::submit(int score, int lines, int level, double timeSec) {
-    scores.push_back(ScoreEntry{score,lines,level,timeSec});
+void ScoreManager::submit(int score, int lines, int level, double timeSec, const std::string& name, const std::string& gameType) {
+    // Add to local list
+    ScoreEntry newEntry{};
+    newEntry.score = score;
+    newEntry.lines = lines;
+    newEntry.level = level;
+    newEntry.timeSec = timeSec;
+    newEntry.name = name;
+    // preserve the game type locally so menu filtering works immediately
+    newEntry.gameType = gameType;
+    scores.push_back(newEntry);
     std::sort(scores.begin(), scores.end(), [](auto&a,auto&b){return a.score>b.score;});
     if (scores.size()>maxEntries) scores.resize(maxEntries);
     save();
+    // Submit to Supabase asynchronously
+    ScoreEntry se{score, lines, level, timeSec, name, gameType};
+    supabase::SubmitHighscoreAsync(se);
+}
+
+bool ScoreManager::isHighScore(int score) const {
+    if (scores.size() < maxEntries) return true;
+    return score > scores.back().score;
+}
+
+void ScoreManager::replaceAll(const std::vector<ScoreEntry>& newScores) {
+    scores = newScores;
+    // Ensure ordering and trimming to our configured maxEntries
+    std::sort(scores.begin(), scores.end(), [](auto&a,auto&b){return a.score>b.score;});
+    if (scores.size() > maxEntries) scores.resize(maxEntries);
+    // Persist new set to local file for next launch
+    try { save(); } catch (...) { /* swallow */ }
 }
 
 void ScoreManager::createSampleScores() {
     scores = {
-        {159840, 189, 14, 972, "GREGOR"},
-        {156340, 132, 12, 714, "GREGOR"}, 
-        {155219, 125, 12, 696, "GREGOR"},
-        {141823, 123, 10, 710, "GREGOR"},
-        {140079, 71, 11, 410, "GREGOR"},
-        {116012, 121, 10, 619, "GREGOR"},
-        {112643, 137, 13, 689, "GREGOR"},
-        {99190, 61, 10, 378, "GREGOR"},
-        {93648, 107, 10, 629, "GREGOR"},
-        {89041, 115, 10, 618, "GREGOR"},
-        {88600, 55, 9, 354, "GREGOR"},
-        {86346, 141, 13, 723, "GREGOR"}
+        {159840, 189, 14, 972.0, "GREGOR"},
+        {156340, 132, 12, 714.0, "GREGOR"}, 
+        {155219, 125, 12, 696.0, "GREGOR"},
+        {141823, 123, 10, 710.0, "GREGOR"},
+        {140079, 71, 11, 410.0, "GREGOR"},
+        {116012, 121, 10, 619.0, "GREGOR"},
+        {112643, 137, 13, 689.0, "GREGOR"},
+        {99190, 61, 10, 378.0, "GREGOR"},
+        {93648, 107, 10, 629.0, "GREGOR"},
+        {89041, 115, 10, 618.0, "GREGOR"},
+        {88600, 55, 9, 354.0, "GREGOR"},
+        {86346, 141, 13, 723.0, "GREGOR"}
     };
 }
diff --git a/src/persistence/Scores.h b/src/persistence/Scores.h
index 2f69da9..1f11e0b 100644
--- a/src/persistence/Scores.h
+++ b/src/persistence/Scores.h
@@ -3,14 +3,19 @@
 #include <vector>
 #include <string>
 
-struct ScoreEntry { int score{}; int lines{}; int level{}; double timeSec{}; std::string name{"PLAYER"}; };
+struct ScoreEntry { int score{}; int lines{}; int level{}; double timeSec{}; std::string name{"PLAYER"}; std::string gameType{"classic"}; };
 
 class ScoreManager {
 public:
     explicit ScoreManager(size_t maxScores = 12);
     void load();
     void save() const;
-    void submit(int score, int lines, int level, double timeSec);
+    // Replace the in-memory scores (thread-safe caller should ensure non-blocking)
+    void replaceAll(const std::vector<ScoreEntry>& newScores);
+    // New optional `gameType` parameter will be sent as `game_type`.
+    // Allowed values: "classic", "versus", "cooperate", "challenge".
+    void submit(int score, int lines, int level, double timeSec, const std::string& name = "PLAYER", const std::string& gameType = "classic");
+    bool isHighScore(int score) const;
     const std::vector<ScoreEntry>& all() const { return scores; }
 private:
     std::vector<ScoreEntry> scores;
diff --git a/src/resources/AssetPaths.h b/src/resources/AssetPaths.h
new file mode 100644
index 0000000..d050ac7
--- /dev/null
+++ b/src/resources/AssetPaths.h
@@ -0,0 +1,18 @@
+// Centralized asset path constants
+#pragma once
+
+namespace Assets {
+    inline constexpr const char* FONT_ORBITRON = "assets/fonts/Orbitron.ttf";
+    inline constexpr const char* FONT_EXO2 = "assets/fonts/Exo2.ttf";
+
+    inline constexpr const char* LOGO = "assets/images/spacetris.png";
+    inline constexpr const char* MAIN_SCREEN = "assets/images/main_screen.png";
+    inline constexpr const char* BLOCKS_SPRITE = "assets/images/blocks90px_003.png";
+    inline constexpr const char* ASTEROID_SPRITE = "assets/images/asteroids_001.png";
+    inline constexpr const char* PANEL_SCORE = "assets/images/panel_score.png";
+    inline constexpr const char* PANEL_STATS = "assets/images/statistics_panel.png";
+    inline constexpr const char* NEXT_PANEL = "assets/images/next_panel.png";
+    inline constexpr const char* HOLD_PANEL = "assets/images/hold_panel.png";
+
+    inline constexpr const char* MUSIC_DIR = "assets/music/";
+}
diff --git a/src/states/LevelSelectorState.cpp b/src/states/LevelSelectorState.cpp
new file mode 100644
index 0000000..861240b
--- /dev/null
+++ b/src/states/LevelSelectorState.cpp
@@ -0,0 +1,362 @@
+// LevelSelectorState.cpp - Level selection popup state implementation
+#include "LevelSelectorState.h"
+#include "State.h"
+#include "../core/state/StateManager.h"
+#include "../core/GlobalState.h"
+#include "../graphics/ui/Font.h"
+#include <SDL3/SDL.h>
+#include <algorithm>
+#include <cstdio>
+#include <string>
+#include "../graphics/renderers/UIRenderer.h"
+
+// Use dynamic logical dimensions from GlobalState instead of hardcoded values
+
+// --- Minimal draw helpers and look-and-feel adapted from the sample ---
+static inline SDL_Color RGBA(Uint8 r, Uint8 g, Uint8 b, Uint8 a = 255) { return SDL_Color{r, g, b, a}; }
+
+// Palette
+static const SDL_Color COL_BG       = {11, 15, 20, 255};
+static const SDL_Color COL_PANEL    = {20, 40, 60, 255};
+static const SDL_Color COL_PANEL_IN = {26, 46, 66, 255};
+static const SDL_Color COL_CYAN     = {0, 255, 255, 200};
+static const SDL_Color COL_CYAN_SO  = {0, 255, 255, 32};
+static const SDL_Color COL_TILE     = {30, 40, 60, 255};
+static const SDL_Color COL_TILE_H   = {60, 80, 100, 255};
+static const SDL_Color COL_TILE_B   = {74, 94, 118, 220};
+static const SDL_Color COL_NUM      = {233, 241, 255, 255};
+static const SDL_Color COL_ACCENT   = {255, 140, 40, 255};
+static const SDL_Color COL_TITLE    = {255, 200, 50, 255};
+static const SDL_Color COL_FOOTER   = {154, 167, 178, 255};
+
+static void FillRect(SDL_Renderer* r, SDL_FRect rc, SDL_Color c) {
+    SDL_SetRenderDrawBlendMode(r, SDL_BLENDMODE_BLEND);
+    SDL_SetRenderDrawColor(r, c.r, c.g, c.b, c.a);
+    SDL_RenderFillRect(r, &rc);
+}
+static void StrokeRect(SDL_Renderer* r, SDL_FRect rc, SDL_Color c) {
+    SDL_SetRenderDrawBlendMode(r, SDL_BLENDMODE_BLEND);
+    SDL_SetRenderDrawColor(r, c.r, c.g, c.b, c.a);
+    SDL_RenderRect(r, &rc);
+}
+static void Line(SDL_Renderer* r, float x1, float y1, float x2, float y2, SDL_Color c) {
+    SDL_SetRenderDrawBlendMode(r, SDL_BLENDMODE_BLEND);
+    SDL_SetRenderDrawColor(r, c.r, c.g, c.b, c.a);
+    SDL_RenderLine(r, x1, y1, x2, y2);
+}
+
+// Bitmap-like digits for cell numbers (keeps consistent look without relying on font inside cells)
+static void DrawDigit(SDL_Renderer* r, int num, float cx, float cy) {
+    SDL_SetRenderDrawColor(r, COL_NUM.r, COL_NUM.g, COL_NUM.b, COL_NUM.a);
+    auto glyph = [&](int d, float ox) {
+        static const int map[10][15] = {
+            {1,1,1, 1,0,1, 1,0,1, 1,0,1, 1,1,1},
+            {0,1,0, 1,1,0, 0,1,0, 0,1,0, 1,1,1},
+            {1,1,1, 0,0,1, 1,1,1, 1,0,0, 1,1,1},
+            {1,1,1, 0,0,1, 0,1,1, 0,0,1, 1,1,1},
+            {1,0,1, 1,0,1, 1,1,1, 0,0,1, 0,0,1},
+            {1,1,1, 1,0,0, 1,1,1, 0,0,1, 1,1,1},
+            {1,1,1, 1,0,0, 1,1,1, 1,0,1, 1,1,1},
+            {1,1,1, 0,0,1, 0,1,0, 0,1,0, 0,1,0},
+            {1,1,1, 1,0,1, 1,1,1, 1,0,1, 1,1,1},
+            {1,1,1, 1,0,1, 1,1,1, 0,0,1, 1,1,1}
+        };
+        float s = 5.f; float gx = cx + ox - 6.f, gy = cy - 12.f;
+        for (int y = 0; y < 5; y++) for (int x = 0; x < 3; x++)
+            if (map[d][y * 3 + x]) {
+                SDL_FRect p{gx + x * s, gy + y * s, s - 1.f, s - 1.f};
+                SDL_RenderFillRect(r, &p);
+            }
+    };
+    if (num < 10) glyph(num, 0);
+    else { glyph(num / 10, -8); glyph(num % 10, 8); }
+}
+
+// Centered text using project Font, with optional shadow
+static void DrawText(SDL_Renderer* r, FontAtlas* font, const std::string& s,
+                     float x, float y, float scale, SDL_Color col,
+                     bool center = true, bool shadow = true) {
+    if (!font) return;
+    int w = 0, h = 0; font->measure(s, scale, w, h);
+    float tx = x, ty = y;
+    if (center) tx -= (float)w / 2.0f;
+    if (shadow) {
+        font->draw(r, tx + 2.0f, ty + 2.0f, s, scale, {0, 0, 0, 200});
+    }
+    font->draw(r, tx, ty, s, scale, col);
+}
+
+static void Vignette(SDL_Renderer* r, int w, int h) {
+    int pad = w / 10;
+    FillRect(r, SDL_FRect{0, 0, (float)w, (float)pad}, SDL_Color{0, 0, 0, 140});
+    FillRect(r, SDL_FRect{0, (float)h - pad, (float)w, (float)pad}, SDL_Color{0, 0, 0, 140});
+    FillRect(r, SDL_FRect{0, 0, (float)pad, (float)h}, SDL_Color{0, 0, 0, 140});
+    FillRect(r, SDL_FRect{(float)w - pad, 0, (float)pad, (float)h}, SDL_Color{0, 0, 0, 140});
+}
+
+// DrawPanel removed, replaced by UIRenderer::drawSciFiPanel
+
+struct Grid {
+    int cols = 4, rows = 5;
+    float cellW = 0.f, cellH = 0.f, gapX = 12.f, gapY = 12.f;
+    SDL_FRect area{0, 0, 0, 0};
+    SDL_FRect cell(int i) const {
+        int r = i / cols, c = i % cols;
+        return SDL_FRect{ area.x + c * (cellW + gapX), area.y + r * (cellH + gapY), cellW, cellH };
+    }
+};
+
+static Grid MakeGrid(const SDL_FRect& panel) {
+    Grid g;
+    float marginX = 34, marginY = 76;
+    g.area = SDL_FRect{ panel.x + marginX, panel.y + marginY, panel.w - 2 * marginX, panel.h - marginY - 28 };
+    g.cellW = (g.area.w - (g.cols - 1) * g.gapX) / g.cols;
+    g.cellH = (g.area.h - (g.rows - 1) * g.gapY) / g.rows;
+    return g;
+}
+
+static void DrawCell(SDL_Renderer* r, SDL_FRect rc, int idx, bool hovered, bool selected) {
+    FillRect(r, rc, selected ? COL_ACCENT : (hovered ? COL_TILE_H : COL_TILE));
+    StrokeRect(r, rc, COL_TILE_B);
+    Line(r, rc.x + 2, rc.y + 2, rc.x + rc.w - 2, rc.y + 2, SDL_Color{255, 255, 255, 18});
+    Line(r, rc.x + 2, rc.y + rc.h - 2, rc.x + rc.w - 2, rc.y + rc.h - 2, SDL_Color{0, 0, 0, 40});
+    DrawDigit(r, idx, rc.x + rc.w / 2.f, rc.y + rc.h / 2.f);
+}
+
+static int HitTest(const Grid& g, int mx, int my) {
+    for (int i = 0; i < 20; i++) {
+        SDL_FRect rc = g.cell(i);
+        if (mx >= rc.x && mx < rc.x + rc.w && my >= rc.y && my < rc.y + rc.h) return i;
+    }
+    return -1;
+}
+
+LevelSelectorState::LevelSelectorState(StateContext& ctx) : State(ctx) {
+}
+
+void LevelSelectorState::onEnter() {
+    hoveredLevel = ctx.startLevelSelection ? *ctx.startLevelSelection : 0;
+}
+
+void LevelSelectorState::onExit() {
+    hoveredLevel = -1;
+}
+
+void LevelSelectorState::handleEvent(const SDL_Event& e) {
+    if (e.type == SDL_EVENT_KEY_DOWN && !e.key.repeat) {
+        // Arrow key navigation (clamped within grid like the sample)
+        int c = hoveredLevel < 0 ? 0 : hoveredLevel;
+        switch (e.key.scancode) {
+            case SDL_SCANCODE_LEFT:  if (c % 4 > 0) c--; break;
+            case SDL_SCANCODE_RIGHT: if (c % 4 < 3) c++; break;
+            case SDL_SCANCODE_UP:    if (c / 4 > 0) c -= 4; break;
+            case SDL_SCANCODE_DOWN:  if (c / 4 < 4) c += 4; break;
+            case SDL_SCANCODE_RETURN:
+            case SDL_SCANCODE_KP_ENTER:
+                selectLevel(hoveredLevel < 0 ? 0 : hoveredLevel);
+                return;
+            case SDL_SCANCODE_ESCAPE:
+                closePopup();
+                return;
+            default: break;
+        }
+        hoveredLevel = c;
+        if (ctx.startLevelSelection) *ctx.startLevelSelection = hoveredLevel;
+    } else if (e.type == SDL_EVENT_MOUSE_BUTTON_DOWN) {
+        if (e.button.button == SDL_BUTTON_LEFT) {
+            // Get dynamic logical dimensions
+            const int LOGICAL_W = GlobalState::instance().getLogicalWidth();
+            const int LOGICAL_H = GlobalState::instance().getLogicalHeight();
+            
+            // convert mouse to logical coords (viewport is already centered)
+            float lx = (float(e.button.x) - float(lastLogicalVP.x)) / (lastLogicalScale > 0.f ? lastLogicalScale : 1.f);
+            float ly = (float(e.button.y) - float(lastLogicalVP.y)) / (lastLogicalScale > 0.f ? lastLogicalScale : 1.f);
+            
+            // Use same panel calculation as render (centered)
+            const float LOGICAL_W_F = 1200.f;
+            const float LOGICAL_H_F = 1000.f;
+            float winW = (float)lastLogicalVP.w;
+            float winH = (float)lastLogicalVP.h;
+            float contentOffsetX = 0.0f;
+            float contentOffsetY = 0.0f;
+            UIRenderer::computeContentOffsets(winW, winH, LOGICAL_W_F, LOGICAL_H_F, lastLogicalScale, contentOffsetX, contentOffsetY);
+
+            float PW = std::min(520.f, LOGICAL_W_F * 0.65f);
+            float PH = std::min(360.f, LOGICAL_H_F * 0.7f);
+            SDL_FRect panel{ (LOGICAL_W_F - PW) / 2.f + contentOffsetX, (LOGICAL_H_F - PH) / 2.f - 40.f + contentOffsetY, PW, PH };
+            Grid g = MakeGrid(panel);
+            int hit = HitTest(g, int(lx), int(ly));
+            if (hit != -1) {
+                selectLevel(hit);
+            } else {
+                closePopup();
+            }
+        }
+    } else if (e.type == SDL_EVENT_MOUSE_MOTION) {
+    // Get dynamic logical dimensions
+    const int LOGICAL_W = GlobalState::instance().getLogicalWidth();
+    const int LOGICAL_H = GlobalState::instance().getLogicalHeight();
+    
+    // convert mouse to logical coords (viewport is already centered)
+    float lx = (float(e.motion.x) - float(lastLogicalVP.x)) / (lastLogicalScale > 0.f ? lastLogicalScale : 1.f);
+    float ly = (float(e.motion.y) - float(lastLogicalVP.y)) / (lastLogicalScale > 0.f ? lastLogicalScale : 1.f);
+    
+    // Use same panel calculation as render (centered)
+    const float LOGICAL_W_F = 1200.f;
+    const float LOGICAL_H_F = 1000.f;
+    float winW = (float)lastLogicalVP.w;
+    float winH = (float)lastLogicalVP.h;
+    float contentOffsetX = 0.0f;
+    float contentOffsetY = 0.0f;
+    UIRenderer::computeContentOffsets(winW, winH, LOGICAL_W_F, LOGICAL_H_F, lastLogicalScale, contentOffsetX, contentOffsetY);
+
+    float PW = std::min(520.f, LOGICAL_W_F * 0.65f);
+    float PH = std::min(360.f, LOGICAL_H_F * 0.7f);
+    SDL_FRect panel{ (LOGICAL_W_F - PW) / 2.f + contentOffsetX, (LOGICAL_H_F - PH) / 2.f - 40.f + contentOffsetY, PW, PH };
+    Grid g = MakeGrid(panel);
+    hoveredLevel = HitTest(g, int(lx), int(ly));
+    }
+}
+
+void LevelSelectorState::update(double frameMs) {
+    // No continuous updates needed for level selector
+    (void)frameMs;
+}
+
+void LevelSelectorState::render(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) {
+    // Cache for input conversion
+    lastLogicalScale = logicalScale;
+    lastLogicalVP = logicalVP;
+    drawLevelSelectionPopup(renderer, logicalScale, logicalVP);
+}
+
+void LevelSelectorState::drawLevelSelectionPopup(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) {
+    if (!renderer) return;
+
+    // Use fixed logical dimensions to match main.cpp and ensure consistent layout
+    const float LOGICAL_W = 1200.f;
+    const float LOGICAL_H = 1000.f;
+    
+    // Compute content offsets (same approach as MenuState for proper centering)
+    float winW = (float)logicalVP.w;
+    float winH = (float)logicalVP.h;
+    float contentOffsetX = 0.0f;
+    float contentOffsetY = 0.0f;
+    UIRenderer::computeContentOffsets(winW, winH, LOGICAL_W, LOGICAL_H, logicalScale, contentOffsetX, contentOffsetY);
+
+    // Draw the logo at the top (same as MenuState)
+    SDL_Texture* logoToUse = ctx.logoSmallTex ? ctx.logoSmallTex : ctx.logoTex;
+    int logoW = 0, logoH = 0;
+    if (logoToUse == ctx.logoSmallTex && ctx.logoSmallW > 0) {
+        logoW = ctx.logoSmallW;
+        logoH = ctx.logoSmallH;
+    }
+    UIRenderer::drawLogo(renderer, logoToUse, LOGICAL_W, LOGICAL_H, contentOffsetX, contentOffsetY, logoW, logoH);
+
+    // Panel and title strip (in logical space) - centered properly with offsets
+    float PW = std::min(520.f, LOGICAL_W * 0.65f);
+    float PH = std::min(360.f, LOGICAL_H * 0.7f);
+    SDL_FRect panel{ (LOGICAL_W - PW) / 2.f + contentOffsetX, (LOGICAL_H - PH) / 2.f - 40.f + contentOffsetY, PW, PH };
+
+    UIRenderer::drawSciFiPanel(renderer, panel);
+    
+    // Inner face (LevelSelector specific)
+    SDL_FRect inner{panel.x + 12, panel.y + 56, panel.w - 24, panel.h - 68};
+    FillRect(renderer, inner, COL_PANEL_IN);
+    StrokeRect(renderer, inner, SDL_Color{24, 31, 41, 180});
+
+    // Title text - prefer pixelFont for a blocky title if available, fallback to regular font
+    FontAtlas* titleFont = ctx.pixelFont ? ctx.pixelFont : ctx.font;
+    DrawText(renderer, titleFont, "SELECT  STARTING  LEVEL", LOGICAL_W / 2.f + contentOffsetX, panel.y + 20.f, 1.2f, COL_TITLE, true, true);
+
+    // Grid of levels
+    Grid g = MakeGrid(panel);
+    int selectedLevel = ctx.startLevelSelection ? *ctx.startLevelSelection : 0;
+    for (int i = 0; i < 20; i++) {
+        SDL_FRect rc = g.cell(i);
+        DrawCell(renderer, rc, i, hoveredLevel == i, selectedLevel == i);
+    }
+
+    // Footer/instructions - use regular TTF font for readability, centered and lower
+    FontAtlas* footerFont = ctx.pixelFont ? ctx.pixelFont : ctx.font;
+    DrawText(renderer, footerFont, "CLICK A LEVEL TO SELECT   •   ESC = CANCEL",
+             LOGICAL_W / 2.f + contentOffsetX, panel.y + panel.h + 60.f, 1.0f, COL_FOOTER, true, true);
+}
+
+bool LevelSelectorState::isMouseInPopup(float mouseX, float mouseY, float& popupX, float& popupY, float& popupW, float& popupH) {
+    // Get dynamic logical dimensions
+    const int LOGICAL_W = GlobalState::instance().getLogicalWidth();
+    const int LOGICAL_H = GlobalState::instance().getLogicalHeight();
+    
+    // Simplified: viewport is already centered, just convert mouse to logical coords
+    (void)mouseX; (void)mouseY;
+    float lx = 0.f, ly = 0.f;
+    if (lastLogicalScale > 0.0f) {
+        lx = (float(mouseX) - float(lastLogicalVP.x)) / lastLogicalScale;
+        ly = (float(mouseY) - float(lastLogicalVP.y)) / lastLogicalScale;
+    }
+    const float LOGICAL_W_F = 1200.f;
+    const float LOGICAL_H_F = 1000.f;
+    float winW = (float)lastLogicalVP.w;
+    float winH = (float)lastLogicalVP.h;
+    float contentOffsetX = 0.0f;
+    float contentOffsetY = 0.0f;
+    UIRenderer::computeContentOffsets(winW, winH, LOGICAL_W_F, LOGICAL_H_F, lastLogicalScale, contentOffsetX, contentOffsetY);
+
+    float PW = std::min(520.f, LOGICAL_W_F * 0.65f);
+    float PH = std::min(360.f, LOGICAL_H_F * 0.7f);
+    SDL_FRect p{ (LOGICAL_W_F - PW) / 2.f + contentOffsetX, (LOGICAL_H_F - PH) / 2.f - 40.f + contentOffsetY, PW, PH };
+    popupX = p.x; popupY = p.y; popupW = p.w; popupH = p.h;
+    return lx >= popupX && lx <= popupX + popupW && ly >= popupY && ly <= popupY + popupH;
+}
+
+int LevelSelectorState::getLevelFromMouse(float mouseX, float mouseY, float popupX, float popupY, float popupW, float popupH) {
+    // Get dynamic logical dimensions
+    const int LOGICAL_W = GlobalState::instance().getLogicalWidth();
+    const int LOGICAL_H = GlobalState::instance().getLogicalHeight();
+    
+    (void)popupX; (void)popupY; (void)popupW; (void)popupH;
+    float lx = 0.f, ly = 0.f;
+    if (lastLogicalScale > 0.0f) {
+        lx = (float(mouseX) - float(lastLogicalVP.x)) / lastLogicalScale;
+        ly = (float(mouseY) - float(lastLogicalVP.y)) / lastLogicalScale;
+    }
+    const float LOGICAL_W_F = 1200.f;
+    const float LOGICAL_H_F = 1000.f;
+    float winW = (float)lastLogicalVP.w;
+    float winH = (float)lastLogicalVP.h;
+    float contentOffsetX = 0.0f;
+    float contentOffsetY = 0.0f;
+    UIRenderer::computeContentOffsets(winW, winH, LOGICAL_W_F, LOGICAL_H_F, lastLogicalScale, contentOffsetX, contentOffsetY);
+
+    float PW = std::min(520.f, LOGICAL_W_F * 0.65f);
+    float PH = std::min(360.f, LOGICAL_H_F * 0.7f);
+    SDL_FRect p{ (LOGICAL_W_F - PW) / 2.f + contentOffsetX, (LOGICAL_H_F - PH) / 2.f - 40.f + contentOffsetY, PW, PH };
+    Grid g = MakeGrid(p);
+    return HitTest(g, (int)lx, (int)ly);
+}
+
+void LevelSelectorState::updateHoverFromMouse(float mouseX, float mouseY) {
+    hoveredLevel = getLevelFromMouse(mouseX, mouseY, 0, 0, 0, 0);
+}
+
+void LevelSelectorState::selectLevel(int level) {
+    if (ctx.startLevelSelection) {
+        *ctx.startLevelSelection = level;
+    }
+    // Transition back to menu
+    if (ctx.requestFadeTransition) {
+        ctx.requestFadeTransition(AppState::Menu);
+    } else if (ctx.stateManager) {
+        ctx.stateManager->setState(AppState::Menu);
+    }
+}
+
+void LevelSelectorState::closePopup() {
+    // Transition back to menu without changing level
+    if (ctx.requestFadeTransition) {
+        ctx.requestFadeTransition(AppState::Menu);
+    } else if (ctx.stateManager) {
+        ctx.stateManager->setState(AppState::Menu);
+    }
+}
diff --git a/src/states/LevelSelectorState.h b/src/states/LevelSelectorState.h
new file mode 100644
index 0000000..e35d5d0
--- /dev/null
+++ b/src/states/LevelSelectorState.h
@@ -0,0 +1,28 @@
+// LevelSelectorState.h - Level selection popup state
+#pragma once
+#include "State.h"
+
+class LevelSelectorState : public State {
+public:
+    explicit LevelSelectorState(StateContext& ctx);
+    
+    void onEnter() override;
+    void onExit() override;
+    void handleEvent(const SDL_Event& e) override;
+    void update(double frameMs) override;
+    void render(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) override;
+
+private:
+    int hoveredLevel = -1; // -1 = none, 0..19 = hovered level
+    // Cache the latest logical scale/viewport from render() for input conversion
+    float lastLogicalScale = 1.0f;
+    SDL_Rect lastLogicalVP{0,0,0,0};
+    
+    // Helper functions
+    void drawLevelSelectionPopup(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP);
+    bool isMouseInPopup(float mouseX, float mouseY, float& popupX, float& popupY, float& popupW, float& popupH);
+    int getLevelFromMouse(float mouseX, float mouseY, float popupX, float popupY, float popupW, float popupH);
+    void updateHoverFromMouse(float mouseX, float mouseY);
+    void selectLevel(int level);
+    void closePopup();
+};
diff --git a/src/states/LoadingManager.cpp b/src/states/LoadingManager.cpp
new file mode 100644
index 0000000..d87f9ce
--- /dev/null
+++ b/src/states/LoadingManager.cpp
@@ -0,0 +1,39 @@
+#include "states/LoadingManager.h"
+#include "app/AssetLoader.h"
+
+LoadingManager::LoadingManager(AssetLoader* loader)
+    : m_loader(loader)
+{
+}
+
+void LoadingManager::queueTexture(const std::string& path) {
+    if (!m_loader) return;
+    m_loader->queueTexture(path);
+}
+
+void LoadingManager::start() {
+    m_started = true;
+}
+
+bool LoadingManager::update() {
+    if (!m_loader) return true;
+    // perform a single step on the loader; AssetLoader::performStep returns true when
+    // there are no more queued tasks.
+    bool done = m_loader->performStep();
+    return done;
+}
+
+float LoadingManager::getProgress() const {
+    if (!m_loader) return 1.0f;
+    return m_loader->getProgress();
+}
+
+std::vector<std::string> LoadingManager::getAndClearErrors() {
+    if (!m_loader) return {};
+    return m_loader->getAndClearErrors();
+}
+
+std::string LoadingManager::getCurrentLoading() const {
+    if (!m_loader) return {};
+    return m_loader->getCurrentLoading();
+}
diff --git a/src/states/LoadingManager.h b/src/states/LoadingManager.h
new file mode 100644
index 0000000..94eb0bf
--- /dev/null
+++ b/src/states/LoadingManager.h
@@ -0,0 +1,36 @@
+#pragma once
+
+#include <string>
+#include <vector>
+#include <memory>
+
+class AssetLoader;
+
+// LoadingManager: thin facade over AssetLoader for incremental loading.
+// Main thread only. Call update() once per frame to perform a single step.
+class LoadingManager {
+public:
+    explicit LoadingManager(AssetLoader* loader);
+
+    // Queue a texture path (relative to base path) for loading.
+    void queueTexture(const std::string& path);
+
+    // Start loading (idempotent).
+    void start();
+
+    // Perform a single loading step. Returns true when loading complete.
+    bool update();
+
+    // Progress in [0,1]
+    float getProgress() const;
+
+    // Return and clear any accumulated loading errors.
+    std::vector<std::string> getAndClearErrors();
+
+    // Current path being loaded (or empty)
+    std::string getCurrentLoading() const;
+
+private:
+    AssetLoader* m_loader = nullptr;
+    bool m_started = false;
+};
diff --git a/src/states/LoadingState.cpp b/src/states/LoadingState.cpp
index 1b8874a..c62bede 100644
--- a/src/states/LoadingState.cpp
+++ b/src/states/LoadingState.cpp
@@ -1,6 +1,6 @@
 // LoadingState.cpp
 #include "LoadingState.h"
-#include "gameplay/Game.h"
+#include "../gameplay/core/Game.h"
 #include <SDL3/SDL.h>
 #include <cstdio>
 
diff --git a/src/states/MenuState.cpp b/src/states/MenuState.cpp
index b50928a..3b9bcb1 100644
--- a/src/states/MenuState.cpp
+++ b/src/states/MenuState.cpp
@@ -1,151 +1,2265 @@
-// MenuState.cpp
 #include "MenuState.h"
 #include "persistence/Scores.h"
+#include "../network/supabase_client.h"
+#include "../network/NetSession.h"
 #include "graphics/Font.h"
+#include "../graphics/ui/HelpOverlay.h"
+#include "../core/GlobalState.h"
+#include "../core/Settings.h"
+#include "../core/state/StateManager.h"
+#include "../audio/Audio.h"
+#include "../audio/SoundEffect.h"
 #include <SDL3/SDL.h>
+#include <SDL3/SDL_render.h>
+#include <SDL3/SDL_surface.h>
 #include <cstdio>
 #include <algorithm>
+#include <array>
 #include <cmath>
+#include <vector>
+#include <random>
 
-// Local logical canvas size (matches main.cpp). Kept local to avoid changing many files.
-static constexpr int LOGICAL_W = 1200;
-static constexpr int LOGICAL_H = 1000;
+// Use dynamic logical dimensions from GlobalState instead of hardcoded values
+// This allows the UI to adapt when the window is resized or goes fullscreen
 
 // Shared flags and resources are provided via StateContext `ctx`.
 // Removed fragile extern declarations and use `ctx.showLevelPopup`, `ctx.showSettingsPopup`,
 // `ctx.musicEnabled` and `ctx.hoveredButton` instead to avoid globals.
 // Menu helper wrappers are declared in a shared header implemented in main.cpp
 #include "../audio/MenuWrappers.h"
+#include "../utils/ImagePathResolver.h"
+#include "../graphics/renderers/UIRenderer.h"
+#include "../graphics/renderers/GameRenderer.h"
+#include "../ui/MenuLayout.h"
+#include "../ui/BottomMenu.h"
+#include <SDL3_image/SDL_image.h>
+
+// Frosted tint helper: draw a safe, inexpensive frosted overlay for the panel area.
+// This avoids renderer readback / surface APIs which aren't portable across SDL3 builds.
+static void renderBackdropBlur(SDL_Renderer* renderer, const SDL_Rect& logicalVP, float logicalScale, float panelTop, float panelH, SDL_Texture* sceneTex, int sceneW, int sceneH) {
+    if (!renderer) return;
+    // Preserve previous draw blend mode so callers don't get surprised when
+    // the helper early-returns or changes blend state.
+    SDL_BlendMode prevBlendMode = SDL_BLENDMODE_NONE;
+    SDL_GetRenderDrawBlendMode(renderer, &prevBlendMode);
+    // If we don't have a captured scene texture, fall back to the frosted tint.
+    if (!sceneTex || sceneW <= 0 || sceneH <= 0) {
+        float viewportLogicalW = (float)logicalVP.w / logicalScale;
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+        SDL_SetRenderDrawColor(renderer, 200, 210, 220, 48);
+        SDL_FRect base{ 0.0f, panelTop, viewportLogicalW, panelH };
+        SDL_RenderFillRect(renderer, &base);
+        SDL_SetRenderDrawColor(renderer, 255, 255, 255, 24);
+        SDL_FRect highlight{ 0.0f, panelTop, viewportLogicalW, std::max(2.0f, panelH * 0.06f) };
+        SDL_RenderFillRect(renderer, &highlight);
+        SDL_SetRenderDrawColor(renderer, 16, 24, 32, 12);
+        SDL_FRect shadow{ 0.0f, panelTop + panelH - std::max(2.0f, panelH * 0.06f), viewportLogicalW, std::max(2.0f, panelH * 0.06f) };
+        SDL_RenderFillRect(renderer, &shadow);
+        // Restore previous blend mode
+        SDL_SetRenderDrawBlendMode(renderer, prevBlendMode);
+        return;
+    }
+
+    // Compute source rect in scene texture pixels for the panel area
+    int panelWinX = 0;
+    int panelWinY = static_cast<int>(std::floor(panelTop * logicalScale + logicalVP.y));
+    int panelWinW = sceneW; // full width of captured scene
+    int panelWinH = static_cast<int>(std::ceil(panelH * logicalScale));
+    if (panelWinW <= 0 || panelWinH <= 0) return;
+
+    // Downsample size (cheap Gaussian-ish blur via scale).
+    int blurW = std::max(8, panelWinW / 6);
+    int blurH = std::max(4, panelWinH / 6);
+
+    // Create a small render target to draw the downsampled region into
+    SDL_Texture* small = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_RGBA8888, SDL_TEXTUREACCESS_TARGET, blurW, blurH);
+    if (!small) {
+        // Fall back to tint if we can't allocate
+        float viewportLogicalW = (float)logicalVP.w / logicalScale;
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+        SDL_SetRenderDrawColor(renderer, 200, 210, 220, 48);
+        SDL_FRect base{ 0.0f, panelTop, viewportLogicalW, panelH };
+        SDL_RenderFillRect(renderer, &base);
+        SDL_SetRenderDrawBlendMode(renderer, prevBlendMode);
+        return;
+    }
+
+    // Source rectangle in the scene texture (pixel coords) as floats
+    SDL_FRect srcRectF{ (float)panelWinX, (float)panelWinY, (float)panelWinW, (float)panelWinH };
+
+    // Render the sub-region of the scene into the small texture
+    SDL_SetRenderTarget(renderer, small);
+    SDL_SetRenderDrawColor(renderer, 0, 0, 0, 0);
+    SDL_RenderClear(renderer);
+
+    SDL_FRect smallDst{ 0.0f, 0.0f, (float)blurW, (float)blurH };
+    SDL_RenderTexture(renderer, sceneTex, &srcRectF, &smallDst);
+
+    // Reset target
+    SDL_SetRenderTarget(renderer, nullptr);
+
+    // Render the small texture scaled up to the panel area with linear filtering
+    SDL_SetTextureBlendMode(small, SDL_BLENDMODE_BLEND);
+    SDL_SetTextureScaleMode(small, SDL_SCALEMODE_LINEAR);
+
+    float viewportLogicalW = (float)logicalVP.w / logicalScale;
+    SDL_FRect dst{ 0.0f, panelTop, viewportLogicalW, panelH };
+    SDL_RenderTexture(renderer, small, nullptr, &dst);
+
+    // Cleanup
+    SDL_DestroyTexture(small);
+    // Restore previous blend mode so caller drawing is unaffected
+    SDL_SetRenderDrawBlendMode(renderer, prevBlendMode);
+}
 
 MenuState::MenuState(StateContext& ctx) : State(ctx) {}
 
+void MenuState::showCoopSetupPanel(bool show, bool resumeMusic) {
+    if (show) {
+        if (!coopSetupVisible && !coopSetupAnimating) {
+            // Avoid overlapping panels
+            if (aboutPanelVisible && !aboutPanelAnimating) {
+                aboutPanelAnimating = true;
+                aboutDirection = -1;
+            }
+            if (helpPanelVisible && !helpPanelAnimating) {
+                helpPanelAnimating = true;
+                helpDirection = -1;
+            }
+            if (optionsVisible && !optionsAnimating) {
+                optionsAnimating = true;
+                optionsDirection = -1;
+            }
+            if (levelPanelVisible && !levelPanelAnimating) {
+                levelPanelAnimating = true;
+                levelDirection = -1;
+            }
+            if (exitPanelVisible && !exitPanelAnimating) {
+                exitPanelAnimating = true;
+                exitDirection = -1;
+                if (ctx.showExitConfirmPopup) *ctx.showExitConfirmPopup = false;
+            }
+
+            coopSetupAnimating = true;
+            coopSetupDirection = 1;
+            coopSetupSelected = (ctx.coopVsAI && *ctx.coopVsAI) ? 1 : 0;
+            coopSetupStep = CoopSetupStep::ChoosePartner;
+            coopNetworkRoleSelected = 0;
+            coopNetworkHandshakeSent = false;
+            coopNetworkStatusText.clear();
+            if (SDL_Window* focusWin = SDL_GetKeyboardFocus()) {
+                SDL_StopTextInput(focusWin);
+            }
+            if (coopNetworkSession) {
+                coopNetworkSession->shutdown();
+                coopNetworkSession.reset();
+            }
+            coopSetupRectsValid = false;
+            selectedButton = static_cast<int>(ui::BottomMenuItem::Cooperate);
+            // Ensure the transition value is non-zero so render code can show
+            // the inline choice buttons immediately on the same frame.
+            if (coopSetupTransition <= 0.0) coopSetupTransition = 0.001;
+        }
+    } else {
+        if (coopSetupVisible && !coopSetupAnimating) {
+            coopSetupAnimating = true;
+            coopSetupDirection = -1;
+            coopSetupRectsValid = false;
+
+            if (SDL_Window* focusWin = SDL_GetKeyboardFocus()) {
+                SDL_StopTextInput(focusWin);
+            }
+
+            // Cancel any pending network session if the coop setup is being closed.
+            if (coopNetworkSession) {
+                coopNetworkSession->shutdown();
+                coopNetworkSession.reset();
+            }
+            coopNetworkHandshakeSent = false;
+            coopNetworkStatusText.clear();
+            coopSetupStep = CoopSetupStep::ChoosePartner;
+            // Resume menu music only when requested (ESC should pass resumeMusic=false)
+            if (resumeMusic && ctx.musicEnabled && *ctx.musicEnabled) {
+                Audio::instance().playMenuMusic();
+            }
+        }
+    }
+}
+
+void MenuState::showHelpPanel(bool show) {
+    if (show) {
+        if (!helpPanelVisible && !helpPanelAnimating) {
+            // Avoid overlapping panels
+            if (aboutPanelVisible && !aboutPanelAnimating) {
+                aboutPanelAnimating = true;
+                aboutDirection = -1;
+            }
+            helpPanelAnimating = true;
+            helpDirection = 1;
+            helpScroll = 0.0;
+        }
+    } else {
+        if (helpPanelVisible && !helpPanelAnimating) {
+            helpPanelAnimating = true;
+            helpDirection = -1;
+        }
+    }
+}
+
+void MenuState::showAboutPanel(bool show) {
+    if (show) {
+        if (!aboutPanelVisible && !aboutPanelAnimating) {
+            // Avoid overlapping panels
+            if (helpPanelVisible && !helpPanelAnimating) {
+                helpPanelAnimating = true;
+                helpDirection = -1;
+            }
+            if (optionsVisible && !optionsAnimating) {
+                optionsAnimating = true;
+                optionsDirection = -1;
+            }
+            if (levelPanelVisible && !levelPanelAnimating) {
+                levelPanelAnimating = true;
+                levelDirection = -1;
+            }
+            if (exitPanelVisible && !exitPanelAnimating) {
+                exitPanelAnimating = true;
+                exitDirection = -1;
+                if (ctx.showExitConfirmPopup) *ctx.showExitConfirmPopup = false;
+            }
+            aboutPanelAnimating = true;
+            aboutDirection = 1;
+        }
+    } else {
+        if (aboutPanelVisible && !aboutPanelAnimating) {
+            aboutPanelAnimating = true;
+            aboutDirection = -1;
+        }
+    }
+}
+
 void MenuState::onEnter() {
-    // nothing for now
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "MenuState::onEnter called");
+    if (ctx.showExitConfirmPopup) {
+        *ctx.showExitConfirmPopup = false;
+    }
+    if (ctx.exitPopupSelectedButton) {
+        *ctx.exitPopupSelectedButton = 1;
+    }
+    // Refresh highscores for classic/cooperate/challenge asynchronously
+    try {
+        std::thread([this]() {
+            try {
+                auto c_classic = supabase::FetchHighscores("classic", 10);
+                auto c_coop = supabase::FetchHighscores("cooperate", 10);
+                auto c_challenge = supabase::FetchHighscores("challenge", 10);
+                std::vector<ScoreEntry> combined;
+                combined.reserve(c_classic.size() + c_coop.size() + c_challenge.size());
+                combined.insert(combined.end(), c_classic.begin(), c_classic.end());
+                combined.insert(combined.end(), c_coop.begin(), c_coop.end());
+                combined.insert(combined.end(), c_challenge.begin(), c_challenge.end());
+                if (this->ctx.scores) this->ctx.scores->replaceAll(combined);
+            } catch (...) {
+                // swallow network errors - keep existing scores
+            }
+        }).detach();
+    } catch (...) {}
+}
+
+void MenuState::renderMainButtonTop(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) {
+    const float LOGICAL_W = 1200.f;
+    const float LOGICAL_H = 1000.f;
+
+    // Use the same layout code as mouse hit-testing so each button is the same size.
+    ui::MenuLayoutParams params{
+        static_cast<int>(LOGICAL_W),
+        static_cast<int>(LOGICAL_H),
+        logicalVP.w,
+        logicalVP.h,
+        logicalScale
+    };
+
+    int startLevel = ctx.startLevelSelection ? *ctx.startLevelSelection : 0;
+    const bool coopVsAI = ctx.coopVsAI ? *ctx.coopVsAI : false;
+    ui::BottomMenu menu = ui::buildBottomMenu(params, startLevel, coopVsAI);
+
+    const int hovered = (ctx.hoveredButton ? *ctx.hoveredButton : -1);
+        const double baseAlpha = 1.0; // Base alpha for button rendering
+    // Pulse is encoded as a signed delta so PLAY can dim/brighten while focused.
+    const double pulseDelta = (buttonPulseAlpha - 1.0);
+    const double flashDelta = buttonFlash * buttonFlashAmount;
+    ui::renderBottomMenu(renderer, ctx.pixelFont, menu, hovered, selectedButton, baseAlpha, pulseDelta + flashDelta);
 }
 
 void MenuState::onExit() {
+    if (ctx.showExitConfirmPopup) {
+        *ctx.showExitConfirmPopup = false;
+    }
+    
+    // Clean up icon textures
+    if (playIcon) { SDL_DestroyTexture(playIcon); playIcon = nullptr; }
+    if (levelIcon) { SDL_DestroyTexture(levelIcon); levelIcon = nullptr; }
+    if (optionsIcon) { SDL_DestroyTexture(optionsIcon); optionsIcon = nullptr; }
+    if (exitIcon) { SDL_DestroyTexture(exitIcon); exitIcon = nullptr; }
+    if (helpIcon) { SDL_DestroyTexture(helpIcon); helpIcon = nullptr; }
+    if (coopInfoTexture) { SDL_DestroyTexture(coopInfoTexture); coopInfoTexture = nullptr; }
 }
 
 void MenuState::handleEvent(const SDL_Event& e) {
-    // Key-specific handling (allow main to handle global keys)
-    (void)e;
+    // Text input for network IP entry (only while coop setup panel is active).
+    if ((coopSetupVisible || coopSetupAnimating) && coopSetupTransition > 0.0 && e.type == SDL_EVENT_TEXT_INPUT) {
+        if (coopSetupStep == CoopSetupStep::NetworkEnterAddress) {
+            std::string& target = (coopNetworkRoleSelected == 0) ? coopNetworkBindAddress : coopNetworkJoinAddress;
+            if (target.size() < 64) {
+                target += e.text.text;
+            }
+            return;
+        }
+    }
+
+    // Coop setup panel navigation (modal within the menu)
+    // Handle this FIRST and consume key events so the main menu navigation doesn't interfere.
+    // Note: Do not require !repeat here; some keyboards/OS configs may emit Enter with repeat.
+    if ((coopSetupVisible || coopSetupAnimating) && coopSetupTransition > 0.0 && e.type == SDL_EVENT_KEY_DOWN) {
+        // Coop setup panel navigation (modal within the menu)
+        switch (e.key.scancode) {
+            case SDL_SCANCODE_UP:
+            case SDL_SCANCODE_DOWN:
+                // Do NOT allow up/down to change anything while this panel is active
+                return;
+            case SDL_SCANCODE_ESCAPE:
+                // When in a nested network step, go back one step; otherwise close the panel.
+                if (coopSetupStep == CoopSetupStep::NetworkChooseRole) {
+                    coopSetupStep = CoopSetupStep::ChoosePartner;
+                    coopNetworkHandshakeSent = false;
+                    coopNetworkStatusText.clear();
+                    return;
+                }
+                if (coopSetupStep == CoopSetupStep::NetworkEnterAddress) {
+                    if (SDL_Window* focusWin = SDL_GetKeyboardFocus()) {
+                        SDL_StopTextInput(focusWin);
+                    }
+                    coopSetupStep = CoopSetupStep::NetworkChooseRole;
+                    coopNetworkHandshakeSent = false;
+                    coopNetworkStatusText.clear();
+                    return;
+                }
+                if (coopSetupStep == CoopSetupStep::NetworkWaiting) {
+                    if (coopNetworkSession) {
+                        coopNetworkSession->shutdown();
+                        coopNetworkSession.reset();
+                    }
+                    if (SDL_Window* focusWin = SDL_GetKeyboardFocus()) {
+                        SDL_StopTextInput(focusWin);
+                    }
+                    coopNetworkHandshakeSent = false;
+                    coopNetworkStatusText.clear();
+                    coopSetupStep = CoopSetupStep::NetworkChooseRole;
+                    return;
+                }
+                showCoopSetupPanel(false, false);
+                return;
+            case SDL_SCANCODE_LEFT:
+            case SDL_SCANCODE_A:
+                if (coopSetupStep == CoopSetupStep::ChoosePartner) {
+                    // 3-way selection: LOCAL / AI / NETWORK
+                    coopSetupSelected = (coopSetupSelected + 3 - 1) % 3;
+                    buttonFlash = 1.0;
+                    return;
+                }
+                if (coopSetupStep == CoopSetupStep::NetworkChooseRole) {
+                    coopNetworkRoleSelected = (coopNetworkRoleSelected + 2 - 1) % 2;
+                    buttonFlash = 1.0;
+                    return;
+                }
+                if (coopSetupStep == CoopSetupStep::NetworkEnterAddress) {
+                    return;
+                }
+                return;
+            case SDL_SCANCODE_RIGHT:
+            case SDL_SCANCODE_D:
+                if (coopSetupStep == CoopSetupStep::ChoosePartner) {
+                    coopSetupSelected = (coopSetupSelected + 1) % 3;
+                    buttonFlash = 1.0;
+                    return;
+                }
+                if (coopSetupStep == CoopSetupStep::NetworkChooseRole) {
+                    coopNetworkRoleSelected = (coopNetworkRoleSelected + 1) % 2;
+                    buttonFlash = 1.0;
+                    return;
+                }
+                if (coopSetupStep == CoopSetupStep::NetworkEnterAddress) {
+                    return;
+                }
+                return;
+            case SDL_SCANCODE_BACKSPACE:
+                if (coopSetupStep == CoopSetupStep::NetworkEnterAddress) {
+                    std::string& target = (coopNetworkRoleSelected == 0) ? coopNetworkBindAddress : coopNetworkJoinAddress;
+                    if (!target.empty()) target.pop_back();
+                    return;
+                }
+                break;
+            case SDL_SCANCODE_RETURN:
+            case SDL_SCANCODE_KP_ENTER:
+            case SDL_SCANCODE_SPACE:
+            {
+                // Existing flows (Local 2P / AI) are preserved exactly.
+                if (coopSetupStep == CoopSetupStep::ChoosePartner && (coopSetupSelected == 0 || coopSetupSelected == 1)) {
+                    const bool useAI = (coopSetupSelected == 1);
+                    if (ctx.coopVsAI) {
+                        *ctx.coopVsAI = useAI;
+                    }
+                    if (ctx.game) {
+                        ctx.game->setMode(GameMode::Cooperate);
+                        ctx.game->reset(ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+                    }
+                    if (ctx.coopGame) {
+                        ctx.coopGame->reset(ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+                    }
+
+                    // Close the panel without restarting menu music; gameplay will take over.
+                    showCoopSetupPanel(false, false);
+
+                    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION,
+                                "MenuState: coop start via key, selected=%d, startPlayTransition_present=%d, stateManager=%p",
+                                coopSetupSelected,
+                                ctx.startPlayTransition ? 1 : 0,
+                                (void*)ctx.stateManager);
+
+                    if (ctx.startPlayTransition) {
+                        ctx.startPlayTransition();
+                    } else if (ctx.stateManager) {
+                        ctx.stateManager->setState(AppState::Playing);
+                    }
+                    return;
+                }
+
+                // Network flow (new): choose host/join, confirm connection before starting.
+                if (coopSetupStep == CoopSetupStep::ChoosePartner && coopSetupSelected == 2) {
+                    coopSetupStep = CoopSetupStep::NetworkChooseRole;
+                    coopNetworkRoleSelected = 0;
+                    coopNetworkHandshakeSent = false;
+                    coopNetworkStatusText.clear();
+                    if (coopNetworkSession) {
+                        coopNetworkSession->shutdown();
+                        coopNetworkSession.reset();
+                    }
+                    buttonFlash = 1.0;
+                    return;
+                }
+
+                if (coopSetupStep == CoopSetupStep::NetworkChooseRole) {
+                    // First, let the user enter the address (bind for host, remote for join).
+                    coopSetupStep = CoopSetupStep::NetworkEnterAddress;
+                    coopNetworkStatusText.clear();
+                    if (SDL_Window* focusWin = SDL_GetKeyboardFocus()) {
+                        SDL_StartTextInput(focusWin);
+                    }
+                    return;
+                }
+
+                if (coopSetupStep == CoopSetupStep::NetworkEnterAddress) {
+                    coopNetworkHandshakeSent = false;
+                    coopNetworkStatusText.clear();
+                    coopNetworkSession = std::make_unique<NetSession>();
+
+                    const uint16_t port = coopNetworkPort;
+                    bool ok = false;
+                    if (coopNetworkRoleSelected == 0) {
+                        const std::string bindIp = coopNetworkBindAddress;
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET COOP] HOST start bind=%s port=%u", bindIp.c_str(), (unsigned)port);
+                        ok = coopNetworkSession->host(bindIp, port);
+                        coopNetworkStatusText = ok ? "WAITING FOR PLAYER..." : ("HOST FAILED: " + coopNetworkSession->lastError());
+                    } else {
+                        const std::string joinIp = coopNetworkJoinAddress.empty() ? std::string("127.0.0.1") : coopNetworkJoinAddress;
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET COOP] JOIN start remote=%s port=%u", joinIp.c_str(), (unsigned)port);
+                        ok = coopNetworkSession->join(joinIp, port);
+                        coopNetworkStatusText = ok ? "CONNECTING..." : ("JOIN FAILED: " + coopNetworkSession->lastError());
+                    }
+
+                    if (SDL_Window* focusWin = SDL_GetKeyboardFocus()) {
+                        SDL_StopTextInput(focusWin);
+                    }
+
+                    if (ok) {
+                        coopSetupStep = CoopSetupStep::NetworkWaiting;
+                    } else {
+                        // Stay on role choice screen so user can back out.
+                        coopNetworkSession.reset();
+                        coopSetupStep = CoopSetupStep::NetworkChooseRole;
+                    }
+                    return;
+                }
+
+                // While waiting for connection, Enter does nothing.
+                return;
+            }
+            default:
+                // Allow other keys, but don't let them affect the main menu while coop is open.
+                return;
+        }
+    }
+
+    // Mouse input for COOP setup panel or inline coop buttons
+    if (e.type == SDL_EVENT_MOUSE_BUTTON_DOWN && e.button.button == SDL_BUTTON_LEFT) {
+        if (coopSetupRectsValid) {
+            // While the coop submenu is active (animating or visible) we disallow
+            // mouse interaction — only keyboard LEFT/RIGHT/ESC is permitted.
+            if (coopSetupAnimating || coopSetupVisible) {
+                return;
+            }
+            const float mx = static_cast<float>(e.button.x);
+            const float my = static_cast<float>(e.button.y);
+            if (mx >= lastLogicalVP.x && my >= lastLogicalVP.y && mx <= (lastLogicalVP.x + lastLogicalVP.w) && my <= (lastLogicalVP.y + lastLogicalVP.h)) {
+                const float lx = (mx - lastLogicalVP.x) / std::max(0.0001f, lastLogicalScale);
+                const float ly = (my - lastLogicalVP.y) / std::max(0.0001f, lastLogicalScale);
+
+                auto hit = [&](const SDL_FRect& r) {
+                    return lx >= r.x && lx <= (r.x + r.w) && ly >= r.y && ly <= (r.y + r.h);
+                };
+
+                int chosen = -1;
+                if (hit(coopSetupBtnRects[0])) chosen = 0;
+                else if (hit(coopSetupBtnRects[1])) chosen = 1;
+
+                if (chosen != -1) {
+                    coopSetupSelected = chosen;
+                    const bool useAI = (coopSetupSelected == 1);
+                    if (ctx.coopVsAI) {
+                        *ctx.coopVsAI = useAI;
+                    }
+                    if (ctx.game) {
+                        ctx.game->setMode(GameMode::Cooperate);
+                        ctx.game->reset(ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+                    }
+                    if (ctx.coopGame) {
+                        ctx.coopGame->reset(ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+                    }
+                    showCoopSetupPanel(false);
+                    if (ctx.startPlayTransition) {
+                        ctx.startPlayTransition();
+                    } else if (ctx.stateManager) {
+                        ctx.stateManager->setState(AppState::Playing);
+                    }
+                    return;
+                }
+            }
+        }
+    }
+
+    // Keyboard navigation for menu buttons
+    if (e.type == SDL_EVENT_KEY_DOWN && !e.key.repeat) {
+        // When the player uses the keyboard, don't let an old mouse hover keep focus on a button.
+        if (ctx.hoveredButton) {
+            *ctx.hoveredButton = -1;
+        }
+
+        auto triggerPlay = [&]() {
+            if (ctx.startPlayTransition) {
+                ctx.startPlayTransition();
+            } else if (ctx.stateManager) {
+                ctx.stateManager->setState(AppState::Playing);
+            }
+        };
+
+        auto setExitSelection = [&](int value) {
+            if (ctx.exitPopupSelectedButton) {
+                *ctx.exitPopupSelectedButton = value;
+            }
+        };
+        auto getExitSelection = [&]() -> int {
+            return ctx.exitPopupSelectedButton ? *ctx.exitPopupSelectedButton : 1;
+        };
+        auto isExitPromptVisible = [&]() -> bool {
+            return ctx.showExitConfirmPopup && *ctx.showExitConfirmPopup;
+        };
+        auto setExitPrompt = [&](bool visible) {
+            if (ctx.showExitConfirmPopup) {
+                *ctx.showExitConfirmPopup = visible;
+            }
+        };
+
+        // Inline exit HUD handling (replaces the old modal popup)
+        if (exitPanelVisible && !exitPanelAnimating) {
+            switch (e.key.scancode) {
+                case SDL_SCANCODE_LEFT:
+                    // Move selection to YES
+                    exitSelectedButton = 0;
+                    if (ctx.exitPopupSelectedButton) *ctx.exitPopupSelectedButton = exitSelectedButton;
+                    return;
+                case SDL_SCANCODE_RIGHT:
+                    // Move selection to NO
+                    exitSelectedButton = 1;
+                    if (ctx.exitPopupSelectedButton) *ctx.exitPopupSelectedButton = exitSelectedButton;
+                    return;
+                case SDL_SCANCODE_RETURN:
+                case SDL_SCANCODE_KP_ENTER:
+                case SDL_SCANCODE_SPACE:
+                    if (exitSelectedButton == 0) {
+                        // Confirm quit
+                        if (ctx.requestQuit) {
+                            ctx.requestQuit();
+                        } else {
+                            SDL_Event quit{}; quit.type = SDL_EVENT_QUIT; SDL_PushEvent(&quit);
+                        }
+                    } else {
+                        // Close HUD
+                        exitPanelAnimating = true; exitDirection = -1;
+                        if (ctx.showExitConfirmPopup) *ctx.showExitConfirmPopup = false;
+                    }
+                    return;
+                case SDL_SCANCODE_ESCAPE:
+                    showCoopSetupPanel(false, true);
+                    // Cannot print std::function as a pointer; print presence (1/0) instead
+                    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "MenuState: coop ENTER pressed, selected=%d, startPlayTransition_present=%d, stateManager=%p", coopSetupSelected, ctx.startPlayTransition ? 1 : 0, (void*)ctx.stateManager);
+                    if (ctx.startPlayTransition) {
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "MenuState: calling startPlayTransition");
+                        ctx.startPlayTransition();
+                    } else {
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "MenuState: startPlayTransition is null");
+                    }
+                    if (ctx.stateManager) {
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "MenuState: setting AppState::Playing on stateManager");
+                        ctx.stateManager->setState(AppState::Playing);
+                    } else {
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "MenuState: stateManager is null");
+                    }
+                    if (ctx.showExitConfirmPopup) *ctx.showExitConfirmPopup = false;
+                    return;
+                case SDL_SCANCODE_PAGEDOWN:
+                case SDL_SCANCODE_DOWN: {
+                    // scroll content down
+                    exitScroll += 40.0; return;
+                }
+                case SDL_SCANCODE_PAGEUP:
+                case SDL_SCANCODE_UP: {
+                    exitScroll -= 40.0; if (exitScroll < 0.0) exitScroll = 0.0; return;
+                }
+                default:
+                    return;
+            }
+        }
+
+        // If the inline options HUD is visible and not animating, capture navigation
+        if (optionsVisible && !optionsAnimating) {
+            // Options rows drawn here are 5 (Fullscreen, Music, Sound FX, Smooth Scroll, Return)
+            constexpr int OPTIONS_ROW_COUNT = 5;
+            switch (e.key.scancode) {
+                case SDL_SCANCODE_UP:
+                {
+                    optionsSelectedRow = (optionsSelectedRow + OPTIONS_ROW_COUNT - 1) % OPTIONS_ROW_COUNT;
+                    return;
+                }
+                case SDL_SCANCODE_DOWN:
+                {
+                    optionsSelectedRow = (optionsSelectedRow + 1) % OPTIONS_ROW_COUNT;
+                    return;
+                }
+                case SDL_SCANCODE_LEFT:
+                case SDL_SCANCODE_RIGHT:
+                case SDL_SCANCODE_RETURN:
+                case SDL_SCANCODE_KP_ENTER:
+                case SDL_SCANCODE_SPACE:
+                {
+                    // Perform toggle/action for the selected option
+                    switch (optionsSelectedRow) {
+                        case 0: {
+                            // FULLSCREEN
+                            bool nextState = ! (ctx.fullscreenFlag ? *ctx.fullscreenFlag : Settings::instance().isFullscreen());
+                            if (ctx.fullscreenFlag) *ctx.fullscreenFlag = nextState;
+                            if (ctx.applyFullscreen) ctx.applyFullscreen(nextState);
+                            Settings::instance().setFullscreen(nextState);
+                            Settings::instance().save();
+                            return;
+                        }
+                        case 1: {
+                            // MUSIC
+                            bool next = !Settings::instance().isMusicEnabled();
+                            Settings::instance().setMusicEnabled(next);
+                            Settings::instance().save();
+                            if (ctx.musicEnabled) *ctx.musicEnabled = next;
+                            return;
+                        }
+                        case 2: {
+                            // SOUND FX
+                            bool next = !SoundEffectManager::instance().isEnabled();
+                            SoundEffectManager::instance().setEnabled(next);
+                            Settings::instance().setSoundEnabled(next);
+                            Settings::instance().save();
+                            return;
+                        }
+                        case 3: {
+                            // SMOOTH SCROLL
+                            bool next = !Settings::instance().isSmoothScrollEnabled();
+                            Settings::instance().setSmoothScrollEnabled(next);
+                            Settings::instance().save();
+                            return;
+                        }
+                        case 4: {
+                            // RETURN TO MENU -> hide panel
+                            optionsAnimating = true;
+                            optionsDirection = -1;
+                            return;
+                        }
+                    }
+                }
+                default:
+                    break;
+            }
+        }
+
+        // If the inline help HUD is visible and not animating, capture navigation
+        if (helpPanelVisible && !helpPanelAnimating) {
+            switch (e.key.scancode) {
+                case SDL_SCANCODE_ESCAPE:
+                case SDL_SCANCODE_RETURN:
+                case SDL_SCANCODE_KP_ENTER:
+                case SDL_SCANCODE_SPACE:
+                    // Close help panel
+                    helpPanelAnimating = true; helpDirection = -1;
+                    return;
+                case SDL_SCANCODE_LEFT:
+                case SDL_SCANCODE_RIGHT:
+                case SDL_SCANCODE_UP:
+                case SDL_SCANCODE_DOWN:
+                    // Arrow keys: close help and immediately return to main menu navigation.
+                    helpPanelAnimating = true; helpDirection = -1;
+                    break;
+                case SDL_SCANCODE_PAGEDOWN:
+                    helpScroll += 40.0;
+                    return;
+                case SDL_SCANCODE_PAGEUP:
+                    helpScroll -= 40.0;
+                    if (helpScroll < 0.0) helpScroll = 0.0;
+                    return;
+                default:
+                    return;
+            }
+        }
+
+        // If the inline about HUD is visible and not animating, capture navigation
+        if (aboutPanelVisible && !aboutPanelAnimating) {
+            switch (e.key.scancode) {
+                case SDL_SCANCODE_ESCAPE:
+                case SDL_SCANCODE_RETURN:
+                case SDL_SCANCODE_KP_ENTER:
+                case SDL_SCANCODE_SPACE:
+                    aboutPanelAnimating = true; aboutDirection = -1;
+                    return;
+                case SDL_SCANCODE_LEFT:
+                case SDL_SCANCODE_RIGHT:
+                case SDL_SCANCODE_UP:
+                case SDL_SCANCODE_DOWN:
+                    aboutPanelAnimating = true; aboutDirection = -1;
+                    break;
+                default:
+                    return;
+            }
+        }
+
+        // If inline level HUD visible and not animating, capture navigation
+        if (levelPanelVisible && !levelPanelAnimating) {
+            // Start navigation from tentative hover if present, otherwise from committed selection
+            int c = (levelHovered >= 0) ? levelHovered : (levelSelected < 0 ? 0 : levelSelected);
+            switch (e.key.scancode) {
+                case SDL_SCANCODE_LEFT:  if (c % 4 > 0) c--; break;
+                case SDL_SCANCODE_RIGHT: if (c % 4 < 3) c++; break;
+                case SDL_SCANCODE_UP:    if (c / 4 > 0) c -= 4; break;
+                case SDL_SCANCODE_DOWN:  if (c / 4 < 4) c += 4; break;
+                case SDL_SCANCODE_RETURN:
+                case SDL_SCANCODE_KP_ENTER:
+                case SDL_SCANCODE_SPACE:
+                    // Confirm tentative selection
+                    levelSelected = c;
+                    if (ctx.startLevelSelection) *ctx.startLevelSelection = levelSelected;
+                    // close HUD
+                    levelPanelAnimating = true; levelDirection = -1;
+                    // clear hover candidate
+                    levelHovered = -1;
+                    return;
+                case SDL_SCANCODE_ESCAPE:
+                    levelPanelAnimating = true; levelDirection = -1;
+                    levelHovered = -1;
+                    return;
+                default: break;
+            }
+            // Move tentative cursor (don't commit to startLevelSelection yet)
+            levelHovered = c;
+            // Consume the event so main menu navigation does not also run
+            return;
+        }
+
+        // Coop setup panel navigation (modal within the menu)
+        if ((coopSetupVisible || coopSetupAnimating) && coopSetupTransition > 0.0) {
+            switch (e.key.scancode) {
+                case SDL_SCANCODE_LEFT:
+                    coopSetupSelected = 0;
+                    buttonFlash = 1.0;
+                    return;
+                case SDL_SCANCODE_RIGHT:
+                    coopSetupSelected = 1;
+                    buttonFlash = 1.0;
+                    return;
+                // Explicitly consume Up/Down so main menu navigation doesn't trigger
+                case SDL_SCANCODE_UP:
+                case SDL_SCANCODE_DOWN:
+                    return;
+                case SDL_SCANCODE_ESCAPE:
+                    // Close coop panel without restarting music
+                    showCoopSetupPanel(false, false);
+                    return;
+                case SDL_SCANCODE_RETURN:
+                case SDL_SCANCODE_KP_ENTER:
+                case SDL_SCANCODE_SPACE:
+                {
+                    const bool useAI = (coopSetupSelected == 1);
+                    if (ctx.coopVsAI) {
+                        *ctx.coopVsAI = useAI;
+                    }
+                    if (ctx.game) {
+                        ctx.game->setMode(GameMode::Cooperate);
+                        ctx.game->reset(ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+                    }
+                    if (ctx.coopGame) {
+                        ctx.coopGame->reset(ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+                    }
+                    showCoopSetupPanel(false, false);
+                    triggerPlay();
+                    return;
+                }
+                default:
+                    break;
+            }
+        }
+
+        switch (e.key.scancode) {
+            case SDL_SCANCODE_LEFT:
+            case SDL_SCANCODE_UP:
+                {
+                const int total = MENU_BTN_COUNT;
+                selectedButton = (selectedButton + total - 1) % total;
+                // brief bright flash on navigation
+                buttonFlash = 1.0;
+                break;
+            }
+            case SDL_SCANCODE_RIGHT:
+            case SDL_SCANCODE_DOWN:
+                {
+                const int total = MENU_BTN_COUNT;
+                selectedButton = (selectedButton + 1) % total;
+                // brief bright flash on navigation
+                buttonFlash = 1.0;
+                break;
+            }
+            case SDL_SCANCODE_RETURN:
+            case SDL_SCANCODE_KP_ENTER:
+            case SDL_SCANCODE_SPACE:
+                if (!ctx.stateManager) {
+                    break;
+                }
+                switch (selectedButton) {
+                    case 0:
+                        // Endless play
+                        if (ctx.game) ctx.game->setMode(GameMode::Endless);
+                        triggerPlay();
+                        break;
+                    case 1:
+                        // Cooperative play: open setup panel (2P vs AI)
+                        showCoopSetupPanel(true);
+                        break;
+                    case 2:
+                        // Start challenge run at level 1
+                        if (ctx.game) {
+                            ctx.game->setMode(GameMode::Challenge);
+                            if (ctx.skipNextLevelUpJingle) {
+                                *ctx.skipNextLevelUpJingle = true;
+                            }
+                            ctx.game->startChallengeRun(1);
+                        }
+                        triggerPlay();
+                        break;
+                    case 3:
+                        // Toggle inline level selector HUD (show/hide)
+                        if (!levelPanelVisible && !levelPanelAnimating) {
+                            levelPanelAnimating = true;
+                            levelDirection = 1; // show
+                            // initialize tentative cursor to current selected level
+                            levelHovered = levelSelected < 0 ? 0 : levelSelected;
+                        } else if (levelPanelVisible && !levelPanelAnimating) {
+                            levelPanelAnimating = true;
+                            levelDirection = -1; // hide
+                        }
+                        break;
+                    case 4:
+                        // Toggle the options panel with an animated slide-in/out.
+                        if (!optionsVisible && !optionsAnimating) {
+                            optionsAnimating = true;
+                            optionsDirection = 1; // show
+                        } else if (optionsVisible && !optionsAnimating) {
+                            optionsAnimating = true;
+                            optionsDirection = -1; // hide
+                        }
+                        break;
+                    case 5:
+                        // Toggle the inline HELP HUD (show/hide)
+                        if (!helpPanelVisible && !helpPanelAnimating) {
+                            helpPanelAnimating = true;
+                            helpDirection = 1; // show
+                            helpScroll = 0.0;
+                        } else if (helpPanelVisible && !helpPanelAnimating) {
+                            helpPanelAnimating = true;
+                            helpDirection = -1; // hide
+                        }
+                        break;
+                    case 6:
+                        // Toggle the inline ABOUT HUD (show/hide)
+                        if (!aboutPanelVisible && !aboutPanelAnimating) {
+                            aboutPanelAnimating = true;
+                            aboutDirection = 1;
+                        } else if (aboutPanelVisible && !aboutPanelAnimating) {
+                            aboutPanelAnimating = true;
+                            aboutDirection = -1;
+                        }
+                        break;
+                    case 7:
+                        // Show the inline exit HUD
+                        if (!exitPanelVisible && !exitPanelAnimating) {
+                            exitPanelAnimating = true;
+                            exitDirection = 1;
+                            exitSelectedButton = 1;
+                            if (ctx.showExitConfirmPopup) *ctx.showExitConfirmPopup = true;
+                            if (ctx.exitPopupSelectedButton) *ctx.exitPopupSelectedButton = exitSelectedButton;
+                        }
+                        break;
+                }
+                break;
+            case SDL_SCANCODE_ESCAPE:
+                if (coopSetupVisible && !coopSetupAnimating) {
+                    showCoopSetupPanel(false, false);
+                    return;
+                }
+                // If options panel is visible, hide it first.
+                if (optionsVisible && !optionsAnimating) {
+                    optionsAnimating = true;
+                    optionsDirection = -1;
+                    return;
+                }
+                // Show inline exit HUD on ESC
+                if (!exitPanelVisible && !exitPanelAnimating) {
+                    exitPanelAnimating = true;
+                    exitDirection = 1;
+                    exitSelectedButton = 1;
+                    if (ctx.showExitConfirmPopup) *ctx.showExitConfirmPopup = true;
+                    if (ctx.exitPopupSelectedButton) *ctx.exitPopupSelectedButton = exitSelectedButton;
+                }
+                break;
+            default:
+                break;
+        }
+    }
 }
 
 void MenuState::update(double frameMs) {
-    // Update logo animation counter and particles similar to main
-    (void)frameMs;
+    // Transient network status message (e.g., disconnect) shown on return to menu.
+    if (ctx.coopNetUiStatusRemainingMs > 0.0) {
+        ctx.coopNetUiStatusRemainingMs -= frameMs;
+        if (ctx.coopNetUiStatusRemainingMs <= 0.0) {
+            ctx.coopNetUiStatusRemainingMs = 0.0;
+            ctx.coopNetUiStatusText.clear();
+        }
+    }
+
+    // Update logo animation counter
+    GlobalState::instance().logoAnimCounter += frameMs;
+    // Advance options panel animation if active
+    if (optionsAnimating) {
+        double delta = (frameMs / optionsTransitionDurationMs) * static_cast<double>(optionsDirection);
+        optionsTransition += delta;
+        if (optionsTransition >= 1.0) {
+            optionsTransition = 1.0;
+            optionsVisible = true;
+            optionsAnimating = false;
+        } else if (optionsTransition <= 0.0) {
+            optionsTransition = 0.0;
+            optionsVisible = false;
+            optionsAnimating = false;
+        }
+    }
+
+    // Advance level panel animation if active
+    if (levelPanelAnimating) {
+        double delta = (frameMs / levelTransitionDurationMs) * static_cast<double>(levelDirection);
+        levelTransition += delta;
+        if (levelTransition >= 1.0) {
+            levelTransition = 1.0;
+            levelPanelVisible = true;
+            levelPanelAnimating = false;
+        } else if (levelTransition <= 0.0) {
+            levelTransition = 0.0;
+            levelPanelVisible = false;
+            levelPanelAnimating = false;
+        }
+    }
+
+    // Advance exit panel animation if active
+    if (exitPanelAnimating) {
+        double delta = (frameMs / exitTransitionDurationMs) * static_cast<double>(exitDirection);
+        exitTransition += delta;
+        if (exitTransition >= 1.0) {
+            exitTransition = 1.0;
+            exitPanelVisible = true;
+            exitPanelAnimating = false;
+        } else if (exitTransition <= 0.0) {
+            exitTransition = 0.0;
+            exitPanelVisible = false;
+            exitPanelAnimating = false;
+        }
+    }
+
+    // Advance help panel animation if active
+    if (helpPanelAnimating) {
+        double delta = (frameMs / helpTransitionDurationMs) * static_cast<double>(helpDirection);
+        helpTransition += delta;
+        if (helpTransition >= 1.0) {
+            helpTransition = 1.0;
+            helpPanelVisible = true;
+            helpPanelAnimating = false;
+        } else if (helpTransition <= 0.0) {
+            helpTransition = 0.0;
+            helpPanelVisible = false;
+            helpPanelAnimating = false;
+        }
+    }
+
+    // Advance about panel animation if active
+    if (aboutPanelAnimating) {
+        double delta = (frameMs / aboutTransitionDurationMs) * static_cast<double>(aboutDirection);
+        aboutTransition += delta;
+        if (aboutTransition >= 1.0) {
+            aboutTransition = 1.0;
+            aboutPanelVisible = true;
+            aboutPanelAnimating = false;
+        } else if (aboutTransition <= 0.0) {
+            aboutTransition = 0.0;
+            aboutPanelVisible = false;
+            aboutPanelAnimating = false;
+        }
+    }
+
+    // Advance coop setup panel animation if active
+    if (coopSetupAnimating) {
+        double delta = (frameMs / coopSetupTransitionDurationMs) * static_cast<double>(coopSetupDirection);
+        coopSetupTransition += delta;
+        if (coopSetupTransition >= 1.0) {
+            coopSetupTransition = 1.0;
+            coopSetupVisible = true;
+            coopSetupAnimating = false;
+        } else if (coopSetupTransition <= 0.0) {
+            coopSetupTransition = 0.0;
+            coopSetupVisible = false;
+            coopSetupAnimating = false;
+        }
+    }
+
+    // Animate level selection highlight position toward the selected cell center
+    if (levelTransition > 0.0 && (lastLogicalScale > 0.0f)) {
+        // Recompute same grid geometry used in render to find target center
+        const float LOGICAL_W = 1200.f;
+        const float LOGICAL_H = 1000.f;
+        float winW = (float)lastLogicalVP.w;
+        float winH = (float)lastLogicalVP.h;
+        float contentOffsetX = 0.0f;
+        float contentOffsetY = 0.0f;
+        UIRenderer::computeContentOffsets(winW, winH, LOGICAL_W, LOGICAL_H, lastLogicalScale, contentOffsetX, contentOffsetY);
+
+        const float PW = std::min(520.0f, LOGICAL_W * 0.65f);
+        const float PH = std::min(360.0f, LOGICAL_H * 0.7f);
+        float panelBaseX = (LOGICAL_W - PW) * 0.5f + contentOffsetX;
+        float panelBaseY = (LOGICAL_H - PH) * 0.5f + contentOffsetY - (LOGICAL_H * 0.10f);
+        float marginX = 34.0f, marginY = 56.0f;
+        SDL_FRect area{ panelBaseX + marginX, panelBaseY + marginY, PW - 2.0f * marginX, PH - marginY - 28.0f };
+        const int cols = 4, rows = 5;
+        const float gapX = 12.0f, gapY = 12.0f;
+        float cellW = (area.w - (cols - 1) * gapX) / cols;
+        float cellH = (area.h - (rows - 1) * gapY) / rows;
+
+        int targetIdx = std::clamp((levelHovered >= 0 ? levelHovered : levelSelected), 0, 19);
+        int tr = targetIdx / cols, tc = targetIdx % cols;
+        double targetX = area.x + tc * (cellW + gapX) + cellW * 0.5f;
+        double targetY = area.y + tr * (cellH + gapY) + cellH * 0.5f;
+
+        if (!levelHighlightInitialized) {
+            levelHighlightX = targetX;
+            levelHighlightY = targetY;
+            levelHighlightInitialized = true;
+        } else {
+            // Exponential smoothing: alpha = 1 - exp(-k * dt)
+            double k = levelHighlightSpeed; // user-tunable speed constant
+            double alpha = 1.0 - std::exp(-k * frameMs);
+            if (alpha < 1e-6) alpha = std::min(1.0, frameMs * 0.02);
+            levelHighlightX += (targetX - levelHighlightX) * alpha;
+            levelHighlightY += (targetY - levelHighlightY) * alpha;
+        }
+    }
+
+        // Update pulsing animation (used for PLAY emphasis)
+        if (buttonPulseEnabled) {
+            buttonPulseTime += frameMs;
+            double t = (buttonPulseTime * 0.001) * buttonPulseSpeed; // seconds * speed
+            double s = 0.0;
+            switch (buttonPulseEasing) {
+                case 0: // sin
+                    s = (std::sin(t * 2.0 * 3.14159265358979323846) * 0.5) + 0.5;
+                    break;
+                case 1: // triangle
+                {
+                    double ft = t - std::floor(t);
+                    s = (ft < 0.5) ? (ft * 2.0) : (2.0 - ft * 2.0);
+                    break;
+                }
+                case 2: // exponential ease-in-out (normalized)
+                {
+                    double ft = t - std::floor(t);
+                    if (ft < 0.5) {
+                        s = 0.5 * std::pow(2.0, 20.0 * ft - 10.0);
+                    } else {
+                        s = 1.0 - 0.5 * std::pow(2.0, -20.0 * ft + 10.0);
+                    }
+                    // Clamp to 0..1 in case of numeric issues
+                    if (s < 0.0) s = 0.0; if (s > 1.0) s = 1.0;
+                    break;
+                }
+                default:
+                    s = (std::sin(t * 2.0 * 3.14159265358979323846) * 0.5) + 0.5;
+            }
+            buttonPulseAlpha = buttonPulseMinAlpha + s * (buttonPulseMaxAlpha - buttonPulseMinAlpha);
+        } else {
+            buttonPulseAlpha = 1.0;
+        }
+
+        // Keep the base group alpha stable; pulsing is applied selectively in the renderer.
+        buttonGroupAlpha = 1.0;
+
+        // Update flash decay
+        if (buttonFlash > 0.0) {
+            buttonFlash -= frameMs * buttonFlashDecay;
+            if (buttonFlash < 0.0) buttonFlash = 0.0;
+        }
 }
 
 void MenuState::render(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) {
-    // Compute content offset using the same math as main
-    float winW = float(logicalVP.w);
-    float winH = float(logicalVP.h);
-    float contentScale = logicalScale;
-    float contentW = LOGICAL_W * contentScale;
-    float contentH = LOGICAL_H * contentScale;
-    float contentOffsetX = (winW - contentW) * 0.5f / contentScale;
-    float contentOffsetY = (winH - contentH) * 0.5f / contentScale;
+    // Use fixed logical dimensions to match main.cpp and ensure consistent layout
+    // This prevents the UI from floating apart on wide/tall screens
+    const float LOGICAL_W = 1200.f;
+    const float LOGICAL_H = 1000.f;
+    
+    // Trace entry to persistent log for debugging abrupt exit/crash during render
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "MenuState::render entry\n"); fclose(f); }
+    }
+    
+    // Compute content offsets (same approach as main.cpp for proper centering)
+    float winW = (float)logicalVP.w;
+    float winH = (float)logicalVP.h;
+    float contentOffsetX = 0.0f;
+    float contentOffsetY = 0.0f;
+    UIRenderer::computeContentOffsets(winW, winH, LOGICAL_W, LOGICAL_H, logicalScale, contentOffsetX, contentOffsetY);
+
+    // Cache logical viewport/scale for update() so it can compute HUD target positions
+    lastLogicalScale = logicalScale;
+    lastLogicalVP = logicalVP;
 
     // Background is drawn by main (stretched to the full window) to avoid double-draw.
-
-    // Draw the animated logo and fireworks using the small logo if available (show whole image)
-    SDL_Texture* logoToUse = ctx.logoSmallTex ? ctx.logoSmallTex : ctx.logoTex;
-    if (logoToUse) {
-        // Use dimensions provided by the shared context when available
-        int texW = (logoToUse == ctx.logoSmallTex && ctx.logoSmallW > 0) ? ctx.logoSmallW : 872;
-        int texH = (logoToUse == ctx.logoSmallTex && ctx.logoSmallH > 0) ? ctx.logoSmallH : 273;
-        float maxW = LOGICAL_W * 0.6f;
-        float scale = std::min(1.0f, maxW / float(texW));
-        float dw = texW * scale;
-        float dh = texH * scale;
-        float logoX = (LOGICAL_W - dw) / 2.f + contentOffsetX;
-        float logoY = LOGICAL_H * 0.05f + contentOffsetY;
-        SDL_FRect dst{logoX, logoY, dw, dh};
-        SDL_RenderTexture(renderer, logoToUse, nullptr, &dst);
-    }
-
-    // Fireworks (draw above high scores / near buttons)
-    menu_drawFireworks(renderer, ctx.blocksTex);
-
-    // Score list and top players with a sine-wave vertical animation (use pixelFont for retro look)
-    float topPlayersY = LOGICAL_H * 0.30f + contentOffsetY; // more top padding
-    FontAtlas* useFont = ctx.pixelFont ? ctx.pixelFont : ctx.font;
-    if (useFont) {
-        useFont->draw(renderer, LOGICAL_W * 0.5f - 110 + contentOffsetX, topPlayersY, std::string("TOP PLAYERS"), 1.8f, SDL_Color{255, 220, 0, 255});
-    }
-
-    // High scores table with wave offset
-    float scoresStartY = topPlayersY + 70; // more spacing under title
-    const auto &hs = ctx.scores ? ctx.scores->all() : *(new std::vector<ScoreEntry>());
-    size_t maxDisplay = std::min(hs.size(), size_t(12));
-
-    // Draw table header
-    if (useFont) {
-        float cx = LOGICAL_W * 0.5f + contentOffsetX;
-        float colX[] = { cx - 280, cx - 180, cx - 20, cx + 90, cx + 200, cx + 300 };
-        useFont->draw(renderer, colX[0], scoresStartY - 28, "RANK", 1.1f, SDL_Color{200,200,220,255});
-        useFont->draw(renderer, colX[1], scoresStartY - 28, "PLAYER", 1.1f, SDL_Color{200,200,220,255});
-        useFont->draw(renderer, colX[2], scoresStartY - 28, "SCORE", 1.1f, SDL_Color{200,200,220,255});
-        useFont->draw(renderer, colX[3], scoresStartY - 28, "LINES", 1.1f, SDL_Color{200,200,220,255});
-        useFont->draw(renderer, colX[4], scoresStartY - 28, "LEVEL", 1.1f, SDL_Color{200,200,220,255});
-        useFont->draw(renderer, colX[5], scoresStartY - 28, "TIME", 1.1f, SDL_Color{200,200,220,255});
-    }
-    for (size_t i = 0; i < maxDisplay; ++i)
     {
-        float baseY = scoresStartY + i * 25;
-        float wave = std::sin((float)menu_getLogoAnimCounter() * 0.006f + i * 0.25f) * 6.0f; // subtle wave
-        float y = baseY + wave;
-
-    // Center columns around mid X, wider
-    float cx = LOGICAL_W * 0.5f + contentOffsetX;
-    float colX[] = { cx - 280, cx - 180, cx - 20, cx + 90, cx + 200, cx + 300 };
-
-        char rankStr[8];
-        std::snprintf(rankStr, sizeof(rankStr), "%zu.", i + 1);
-        if (useFont) useFont->draw(renderer, colX[0], y, rankStr, 1.0f, SDL_Color{220, 220, 230, 255});
-
-        if (useFont) useFont->draw(renderer, colX[1], y, hs[i].name, 1.0f, SDL_Color{220, 220, 230, 255});
-
-        char scoreStr[16]; std::snprintf(scoreStr, sizeof(scoreStr), "%d", hs[i].score);
-        if (useFont) useFont->draw(renderer, colX[2], y, scoreStr, 1.0f, SDL_Color{220, 220, 230, 255});
-
-        char linesStr[8]; std::snprintf(linesStr, sizeof(linesStr), "%d", hs[i].lines);
-        if (useFont) useFont->draw(renderer, colX[3], y, linesStr, 1.0f, SDL_Color{220, 220, 230, 255});
-
-        char levelStr[8]; std::snprintf(levelStr, sizeof(levelStr), "%d", hs[i].level);
-        if (useFont) useFont->draw(renderer, colX[4], y, levelStr, 1.0f, SDL_Color{220, 220, 230, 255});
-
-        char timeStr[16]; int mins = int(hs[i].timeSec) / 60; int secs = int(hs[i].timeSec) % 60;
-        std::snprintf(timeStr, sizeof(timeStr), "%d:%02d", mins, secs);
-        if (useFont) useFont->draw(renderer, colX[5], y, timeStr, 1.0f, SDL_Color{220, 220, 230, 255});
+        FILE* f = fopen("spacetris_trace.log", "a");
+        if (f) {
+            fprintf(f, "MenuState::render ctx.mainScreenTex=%llu (w=%d h=%d)\n",
+                (unsigned long long)(uintptr_t)ctx.mainScreenTex,
+                ctx.mainScreenW,
+                ctx.mainScreenH);
+            fclose(f);
+        }
     }
 
+    FontAtlas* useFont = ctx.pixelFont ? ctx.pixelFont : ctx.font;
+    // Slide-space amount for the options HUD (how much highscores move)
+    const float moveAmount = 420.0f; // increased so lower score rows slide further up
+
+    // Compute eased transition and delta to shift highscores when either options, level, or exit HUD is shown.
+    // Exclude coopSetupTransition from the highscores slide so opening the
+    // COOPERATE setup does not shift the highscores panel upward.
+    float combinedTransition = static_cast<float>(std::max(
+        std::max(std::max(optionsTransition, levelTransition), exitTransition),
+        std::max(helpTransition, aboutTransition)
+    ));
+    float eased = combinedTransition * combinedTransition * (3.0f - 2.0f * combinedTransition); // cubic smoothstep
+    float panelDelta = eased * moveAmount;
+
+    // Draw a larger centered logo above the highscores area, then a small "TOP PLAYER" label
+    // Move the whole block slightly up to better match the main screen overlay framing.
+    float menuYOffset = LOGICAL_H * 0.03f; // same offset used for buttons
+    float scoresYOffset = -LOGICAL_H * 0.05f;
+    // Move logo and highscores upward by ~10% of logical height for better vertical balance
+    float upwardShift = LOGICAL_H * 0.08f;
+    float topPlayersY = LOGICAL_H * 0.20f + contentOffsetY - panelDelta + menuYOffset + scoresYOffset - upwardShift;
+    float scoresStartY = topPlayersY;
+    if (useFont) {
+        // Preferred logo texture (full) if present, otherwise the small logo
+        SDL_Texture* logoTex = ctx.logoTex ? ctx.logoTex : ctx.logoSmallTex;
+        float logoDrawH = 72.0f; // larger logo height
+        if (logoTex) {
+            float texW = 0.0f, texH = 0.0f;
+            SDL_GetTextureSize(logoTex, &texW, &texH);
+            if (texW > 0.0f && texH > 0.0f) {
+                float scale = logoDrawH / texH;
+                float drawW = texW * scale;
+                SDL_FRect dst{ (LOGICAL_W - drawW) * 0.5f + contentOffsetX, topPlayersY, drawW, logoDrawH };
+                SDL_SetTextureAlphaMod(logoTex, 230);
+                SDL_RenderTexture(renderer, logoTex, nullptr, &dst);
+                // move down for title under logo
+                scoresStartY = dst.y + dst.h + 8.0f;
+            }
+        }
+
+        // Small label under the logo — show "COOPERATE" when coop setup is active
+        const std::string smallTitle = (coopSetupAnimating || coopSetupVisible) ? "COOPERATE" : "TOP PLAYER";
+        float titleScale = 0.9f;
+        int tW = 0, tH = 0;
+        useFont->measure(smallTitle, titleScale, tW, tH);
+        float titleX = (LOGICAL_W - (float)tW) * 0.5f + contentOffsetX;
+                useFont->draw(renderer, titleX, scoresStartY, smallTitle, titleScale, SDL_Color{200,220,230,255});
+        scoresStartY += (float)tH + 12.0f;
+
+        if (!ctx.coopNetUiStatusText.empty() && ctx.coopNetUiStatusRemainingMs > 0.0) {
+            float msgScale = 0.75f;
+            int mW = 0, mH = 0;
+            useFont->measure(ctx.coopNetUiStatusText, msgScale, mW, mH);
+            float msgX = (LOGICAL_W - (float)mW) * 0.5f + contentOffsetX;
+            useFont->draw(renderer, msgX, scoresStartY, ctx.coopNetUiStatusText, msgScale, SDL_Color{255, 224, 130, 255});
+            scoresStartY += (float)mH + 10.0f;
+        }
+    }
+    static const std::vector<ScoreEntry> EMPTY_SCORES;
+    const auto& hs = ctx.scores ? ctx.scores->all() : EMPTY_SCORES;
+    // Choose which game_type to show based on current menu selection or mouse hover.
+    // Prefer `hoveredButton` (mouse-over) when available so the TOP PLAYER panel
+    // updates responsively while the user moves the pointer over the bottom menu.
+    int activeBtn = (ctx.hoveredButton ? *ctx.hoveredButton : -1);
+    if (activeBtn < 0) activeBtn = selectedButton;
+    std::string wantedType = "classic";
+    if (activeBtn == 0) wantedType = "classic"; // Play / Endless
+    else if (activeBtn == 1) wantedType = "cooperate"; // Coop
+    else if (activeBtn == 2) wantedType = "challenge"; // Challenge
+    // Filter highscores to the desired game type
+    std::vector<ScoreEntry> filtered;
+    filtered.reserve(hs.size());
+    for (const auto &e : hs) {
+        if (e.gameType == wantedType) filtered.push_back(e);
+    }
+    size_t maxDisplay = std::min(filtered.size(), size_t(10)); // display only top 10
+
+    // Draw highscores as an inline HUD-like panel (no opaque box), matching Options/Level/Exit style
+    // Keep highscores visible while the coop setup is animating; hide them only
+    // once the coop setup is fully visible so the buttons can appear afterward.
+    if (useFont && !coopSetupVisible) {
+        const float panelW = (wantedType == "cooperate") ? std::min(920.0f, LOGICAL_W * 0.92f) : std::min(780.0f, LOGICAL_W * 0.85f);
+        const float panelH = 36.0f + maxDisplay * 36.0f; // header + rows
+        // Shift the entire highscores panel slightly left (~1.5% of logical width)
+        float panelShift = LOGICAL_W * 0.015f;
+        float panelBaseX = (LOGICAL_W - panelW) * 0.5f + contentOffsetX - panelShift;
+        float panelBaseY = scoresStartY - 20.0f - panelDelta; // nudge up and apply HUD slide
+
+        // Column positions inside panel
+        float colLeft = panelBaseX + 12.0f;
+        float colWidth = panelW - 24.0f;
+        // Center the column group inside the panel and place columns relative to center
+        float centerX = panelBaseX + panelW * 0.5f;
+        // Tighter column spacing: compress multipliers around center
+        float rankX = centerX - colWidth * 0.34f;
+        // Move PLAYER column a bit further left while leaving others unchanged
+        float nameX = (wantedType == "cooperate") ? centerX - colWidth * 0.30f : centerX - colWidth * 0.25f;
+        // Move SCORE column slightly left for tighter layout (adjusted for coop)
+        float scoreX = (wantedType == "cooperate") ? centerX - colWidth * 0.02f : centerX - colWidth * 0.06f;
+        float linesX = centerX + colWidth * 0.14f;
+        float levelX = centerX + colWidth * 0.26f;
+        float timeX = centerX + colWidth * 0.38f;
+
+        // Column header labels
+        float headerY = panelBaseY + 26.0f;
+        // Slightly smaller header for compactness
+        float headerScale = 0.75f;
+        // Use same color as Options heading (use full alpha for maximum brightness)
+        SDL_Color headerColor = SDL_Color{120,220,255,255};
+        useFont->draw(renderer, rankX, headerY, "#", headerScale, headerColor);
+        useFont->draw(renderer, nameX, headerY, (wantedType == "cooperate") ? "PLAYERS" : "PLAYER", headerScale, headerColor);
+        useFont->draw(renderer, scoreX, headerY, "SCORE", headerScale, headerColor);
+        useFont->draw(renderer, linesX, headerY, "LINES", headerScale, headerColor);
+        useFont->draw(renderer, levelX, headerY, "LVL", headerScale, headerColor);
+        useFont->draw(renderer, timeX, headerY, "TIME", headerScale, headerColor);
+
+        const float rowHeight = 28.0f;
+        float rowY = panelBaseY + 28.0f;
+        float rowScale = 0.80f;
+
+        for (size_t i = 0; i < maxDisplay; ++i) {
+            float y = rowY + i * rowHeight;
+
+            // (removed thin blue separator between rows per request)
+
+            // Subtle highlight wave for the list similar to before
+            float wave = std::sin((float)GlobalState::instance().logoAnimCounter * 0.006f + i * 0.25f) * 4.0f;
+
+            // Per-row entrance staggering and easing to make movement fancier
+            const float baseEntrance = 40.0f;            // pixels rows slide from
+            const float perRowDelay = 0.06f;            // stagger delay per row (in eased 0..1 space)
+            float rowDelay = perRowDelay * (float)i;
+            float rowT = 0.0f;
+            if (eased > rowDelay) rowT = (eased - rowDelay) / (1.0f - rowDelay);
+            if (rowT < 0.0f) rowT = 0.0f; if (rowT > 1.0f) rowT = 1.0f;
+            // cubic smoothstep per row
+            float rowEase = rowT * rowT * (3.0f - 2.0f * rowT);
+            float entryOffset = (1.0f - rowEase) * baseEntrance;
+            // Slight alpha fade during entrance
+            float alphaMul = 1;
+
+            // Slight scale slip per row (keeps earlier visual taper)
+            float curRowScale = rowScale - std::min(0.20f, 0.05f * (float)i);
+
+            // Base row color matches header brightness; top 3 get vivid medal colors
+            SDL_Color baseRowColor = SDL_Color{ headerColor.r, headerColor.g, headerColor.b, 255 };
+            if (i == 0) {
+                baseRowColor = SDL_Color{255,215,0,255}; // bright gold
+            } else if (i == 1) {
+                baseRowColor = SDL_Color{230,230,235,255}; // bright silver
+            } else if (i == 2) {
+                baseRowColor = SDL_Color{255,165,80,255}; // brighter bronze/orange
+            }
+            SDL_Color rowColor = baseRowColor;
+            // Use entrance alpha to fade in but keep RGB full-brightness; map alphaMul to 0..1
+            rowColor.a = static_cast<Uint8>(std::round(255.0f * alphaMul));
+
+            // horizontal subtle slide for name column to add a little polish
+            float nameXAdj = nameX - (1.0f - rowEase) * 8.0f;
+
+            char rankStr[8]; std::snprintf(rankStr, sizeof(rankStr), "%zu.", i + 1);
+            useFont->draw(renderer, rankX, y + wave + entryOffset, rankStr, curRowScale, rowColor);
+
+            useFont->draw(renderer, nameXAdj, y + wave + entryOffset, filtered[i].name, curRowScale, rowColor);
+
+            char scoreStr[16]; std::snprintf(scoreStr, sizeof(scoreStr), "%d", filtered[i].score);
+            useFont->draw(renderer, scoreX, y + wave + entryOffset, scoreStr, curRowScale, rowColor);
+
+            char linesStr[8]; std::snprintf(linesStr, sizeof(linesStr), "%d", filtered[i].lines);
+            useFont->draw(renderer, linesX, y + wave + entryOffset, linesStr, curRowScale, rowColor);
+
+            char levelStr[8]; std::snprintf(levelStr, sizeof(levelStr), "%d", filtered[i].level);
+            useFont->draw(renderer, levelX, y + wave + entryOffset, levelStr, curRowScale, rowColor);
+
+            char timeStr[16]; int mins = int(filtered[i].timeSec) / 60; int secs = int(filtered[i].timeSec) % 60;
+            std::snprintf(timeStr, sizeof(timeStr), "%d:%02d", mins, secs);
+            useFont->draw(renderer, timeX, y + wave + entryOffset, timeStr, curRowScale, rowColor);
+        }
+    }
+
+    // The main_screen overlay is drawn by main.cpp as the background
+    // We don't need to draw it again here as a logo
+
     // Draw bottom action buttons with responsive sizing (reduced to match main mouse hit-test)
+    // Use the contentW calculated at the top with content offsets
+    float contentW = LOGICAL_W * logicalScale;
     bool isSmall = (contentW < 700.0f);
-    float btnW = isSmall ? (LOGICAL_W * 0.4f) : 300.0f;
-    float btnH = isSmall ? 60.0f : 70.0f;
+    // Adjust button dimensions to match the background button graphics
+    float btnW = 200.0f; // Fixed width to match background buttons
+    float btnH = 70.0f;  // Fixed height to match background buttons
     float btnX = LOGICAL_W * 0.5f + contentOffsetX;
-    // Move buttons down by 40px to match original layout (user requested 30-50px)
-    const float btnYOffset = 40.0f;
-    float btnY = LOGICAL_H * 0.86f + contentOffsetY + btnYOffset; // align with main's button vertical position
+    // Adjust vertical position to align with background buttons; move slightly down
+    float btnY = LOGICAL_H * 0.865f + contentOffsetY + (LOGICAL_H * 0.02f) + menuYOffset;
 
     if (ctx.pixelFont) {
+        {
+            FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "MenuState::render drawing buttons; pixelFont=%llu\n", (unsigned long long)(uintptr_t)ctx.pixelFont); fclose(f); }
+        }
         char levelBtnText[32];
         int startLevel = ctx.startLevelSelection ? *ctx.startLevelSelection : 0;
         std::snprintf(levelBtnText, sizeof(levelBtnText), "LEVEL %d", startLevel);
-        // left = green, right = blue like original
-        menu_drawMenuButton(renderer, *ctx.pixelFont, btnX - btnW * 0.6f, btnY, btnW, btnH, std::string("PLAY"), SDL_Color{60,180,80,255}, SDL_Color{30,120,40,255});
-        menu_drawMenuButton(renderer, *ctx.pixelFont, btnX + btnW * 0.6f, btnY, btnW, btnH, std::string(levelBtnText), SDL_Color{40,140,240,255}, SDL_Color{20,100,200,255});
+
+        struct MenuButtonDef {
+            SDL_Color bg;
+            SDL_Color border;
+            std::string label;
+        };
+
+        std::array<MenuButtonDef,5> buttons = {
+            MenuButtonDef{ SDL_Color{60,180,80,255}, SDL_Color{30,120,40,255}, "PLAY" },
+            MenuButtonDef{ SDL_Color{40,140,240,255}, SDL_Color{20,100,200,255}, levelBtnText },
+            MenuButtonDef{ SDL_Color{130,80,210,255}, SDL_Color{90,40,170,255}, "OPTIONS" },
+            MenuButtonDef{ SDL_Color{200,200,60,255}, SDL_Color{150,150,40,255}, "HELP" },
+            MenuButtonDef{ SDL_Color{200,70,70,255}, SDL_Color{150,40,40,255}, "EXIT" }
+        };
+
+        // Icon array (nullptr if icon not loaded)
+        std::array<SDL_Texture*, 5> icons = {
+            playIcon,
+            levelIcon,
+            optionsIcon,
+            helpIcon,
+            exitIcon
+        };
+
+        // Fixed spacing to match background button positions
+        float spacing = isSmall ? btnW * 1.2f : btnW * 1.15f;
+
+        // Draw each button individually so each can have its own coordinates
+        if (drawMainButtonNormally) {
+            // Draw semi-transparent background panel behind the full button group
+            {
+                float groupCenterX = btnX;
+                float halfSpan = 2.0f * spacing;
+                float panelLeft = groupCenterX - halfSpan - btnW * 0.5f - 14.0f;
+                float panelRight = groupCenterX + halfSpan + btnW * 0.5f + 14.0f;
+                float panelTop = btnY - btnH * 0.5f - 12.0f;
+                float panelH = btnH + 24.0f;
+                SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+                // Backdrop blur pass before tint (use captured scene texture if available)
+                renderBackdropBlur(renderer, logicalVP, logicalScale, panelTop, panelH, ctx.sceneTex, ctx.sceneW, ctx.sceneH);
+                // Brighter, less-opaque background to increase contrast (match top path)
+                SDL_SetRenderDrawColor(renderer, 28, 36, 46, 180);
+                // Fill full-width background so edges are covered in fullscreen
+                float viewportLogicalW = (float)logicalVP.w / logicalScale;
+                SDL_FRect fullPanel{ 0.0f, panelTop, viewportLogicalW, panelH };
+                SDL_RenderFillRect(renderer, &fullPanel);
+                // Also draw the central strip to keep visual center emphasis
+                SDL_FRect panelRect{ panelLeft, panelTop, panelRight - panelLeft, panelH };
+                SDL_RenderFillRect(renderer, &panelRect);
+                // subtle border across full logical width
+                SDL_SetRenderDrawColor(renderer, 120, 140, 160, 200);
+                // Expand border to cover full window width (use actual viewport)
+                SDL_FRect borderFull{ 0.0f, panelTop, viewportLogicalW, panelH };
+                SDL_RenderRect(renderer, &borderFull);
+            }
+            // Button 0 - PLAY
+            {
+                const int i = 0;
+                float cxCenter = 0.0f;
+                float cyCenter = btnY;
+                if (ctx.menuButtonsExplicit) {
+                    cxCenter = ctx.menuButtonCX[i] + contentOffsetX;
+                    cyCenter = ctx.menuButtonCY[i] + contentOffsetY;
+                } else {
+                    float offset = (static_cast<float>(i) - 1.5f) * spacing;
+                    cxCenter = btnX + offset + 15.0f;
+                }
+                UIRenderer::drawButton(renderer, ctx.pixelFont, cxCenter, cyCenter, btnW, btnH,
+                                      buttons[i].label, false, selectedButton == i,
+                                      buttons[i].bg, buttons[i].border, true, icons[i]);
+                // no per-button neon outline; group background handles emphasis
+            }
+
+            // Button 1 - LEVEL
+            {
+                const int i = 1;
+                float cxCenter = 0.0f;
+                float cyCenter = btnY;
+                if (ctx.menuButtonsExplicit) {
+                    cxCenter = ctx.menuButtonCX[i] + contentOffsetX;
+                    cyCenter = ctx.menuButtonCY[i] + contentOffsetY;
+                } else {
+                    float offset = (static_cast<float>(i) - 1.5f) * spacing;
+                    cxCenter = btnX + offset;
+                }
+                UIRenderer::drawButton(renderer, ctx.pixelFont, cxCenter, cyCenter, btnW, btnH,
+                                      buttons[i].label, false, selectedButton == i,
+                                      buttons[i].bg, buttons[i].border, true, icons[i]);
+            }
+
+            // Button 2 - OPTIONS
+            {
+                const int i = 2;
+                float cxCenter = 0.0f;
+                float cyCenter = btnY;
+                if (ctx.menuButtonsExplicit) {
+                    cxCenter = ctx.menuButtonCX[i] + contentOffsetX;
+                    cyCenter = ctx.menuButtonCY[i] + contentOffsetY;
+                } else {
+                    float offset = (static_cast<float>(i) - 1.5f) * spacing;
+                    cxCenter = btnX + offset - 24.0f;
+                }
+                UIRenderer::drawButton(renderer, ctx.pixelFont, cxCenter, cyCenter, btnW, btnH,
+                                      buttons[i].label, false, selectedButton == i,
+                                      buttons[i].bg, buttons[i].border, true, icons[i]);
+            }
+
+            // Button 3 - EXIT
+            {
+                const int i = 3;
+                float cxCenter = 0.0f;
+                float cyCenter = btnY;
+                if (ctx.menuButtonsExplicit) {
+                    cxCenter = ctx.menuButtonCX[i] + contentOffsetX;
+                    cyCenter = ctx.menuButtonCY[i] + contentOffsetY;
+                } else {
+                    float offset = (static_cast<float>(i) - 2.0f) * spacing;
+                    cxCenter = btnX + offset;
+                }
+                UIRenderer::drawButton(renderer, ctx.pixelFont, cxCenter, cyCenter, btnW, btnH,
+                                      buttons[i].label, false, selectedButton == i,
+                                      buttons[i].bg, buttons[i].border, true, icons[i]);
+
+                // Button 4 - EXIT
+                {
+                    const int i = 4;
+                    float cxCenter = 0.0f;
+                    float cyCenter = btnY;
+                    if (ctx.menuButtonsExplicit) {
+                        cxCenter = ctx.menuButtonCX[i] + contentOffsetX;
+                        cyCenter = ctx.menuButtonCY[i] + contentOffsetY;
+                    } else {
+                        float offset = (static_cast<float>(i) - 2.0f) * spacing;
+                        cxCenter = btnX + offset - 24.0f;
+                    }
+                    UIRenderer::drawButton(renderer, ctx.pixelFont, cxCenter, cyCenter, btnW, btnH,
+                                          buttons[i].label, false, selectedButton == i,
+                                          buttons[i].bg, buttons[i].border, true, icons[i]);
+                }
+            }
+        }
     }
 
-    // Popups (level/settings) if requested
-    if (ctx.showLevelPopup && *ctx.showLevelPopup) {
-        // call wrapper which will internally draw on top of current content
-        // prefer pixelFont for retro look
-        FontAtlas* useFont = ctx.pixelFont ? ctx.pixelFont : ctx.font;
-    menu_drawLevelSelectionPopup(renderer, *useFont, ctx.backgroundTex, ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+    // Inline COOP choice buttons: when COOPERATE is selected show two large
+    // choice buttons in the highscores panel area (top of the screen).
+    // coopSetupRectsValid is cleared each frame and set to true when buttons are drawn
+    coopSetupRectsValid = false;
+    // Draw the inline COOP choice buttons as soon as the coop setup starts
+    // animating or is visible. Highscores are no longer slid upward when
+    // the setup opens, so the buttons can show immediately.
+    if (coopSetupAnimating || coopSetupVisible) {
+        // Recompute panel geometry matching highscores layout above so buttons
+        // appear centered inside the same visual area.
+        const float panelW = std::min(920.0f, LOGICAL_W * 0.92f);
+        const float panelShift = LOGICAL_W * 0.015f;
+        const float panelBaseX = (LOGICAL_W - panelW) * 0.5f + contentOffsetX - panelShift;
+        const float panelH = 36.0f + maxDisplay * 36.0f; // same as highscores panel
+        // Highscores are animated upward by `panelDelta` while opening the coop setup.
+        // We want the choice buttons to appear *after* that scroll, in the original
+        // highscores area (not sliding offscreen with the scores).
+        const float panelBaseY = scoresStartY - 20.0f;
+
+        // Choice buttons (partner selection) and nested network host/join UI
+        const float btnH2 = 60.0f;
+        const float gap = 34.0f;
+        const float btnW2 = std::min(280.0f, (panelW - gap * 2.0f) / 3.0f);
+        const float totalChoiceW = btnW2 * 3.0f + gap * 2.0f;
+        // Shift the image and buttons slightly for layout balance
+        const float shiftX = 20.0f;
+        const float bx = panelBaseX + (panelW - totalChoiceW) * 0.5f + shiftX;
+        // Move the buttons up by ~80px to sit closer under the logo
+        const float by = panelBaseY + (panelH - btnH2) * 0.5f - 80.0f;
+
+        coopSetupBtnRects[0] = SDL_FRect{ bx, by, btnW2, btnH2 };
+        coopSetupBtnRects[1] = SDL_FRect{ bx + (btnW2 + gap), by, btnW2, btnH2 };
+        coopSetupBtnRects[2] = SDL_FRect{ bx + (btnW2 + gap) * 2.0f, by, btnW2, btnH2 };
+        coopSetupRectsValid = true;
+
+        SDL_Color bg{ 24, 36, 52, 220 };
+        SDL_Color border{ 110, 200, 255, 220 };
+
+        // Load coop info image once when the coop setup is first shown
+        if (!coopInfoTexture) {
+            const std::string resolved = AssetPath::resolveImagePath("assets/images/cooperate_info.png");
+            if (!resolved.empty()) {
+                SDL_Surface* surf = IMG_Load(resolved.c_str());
+                if (surf) {
+                    // Save dimensions from surface then create texture
+                    coopInfoTexW = surf->w;
+                    coopInfoTexH = surf->h;
+                    coopInfoTexture = SDL_CreateTextureFromSurface(renderer, surf);
+                    SDL_DestroySurface(surf);
+                } else {
+                    SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "MenuState: failed to load %s: %s", resolved.c_str(), SDL_GetError());
+                }
+            }
+        }
+
+        // If the image loaded, render it centered above the choice buttons
+        // Compute fade alpha from the coop transition so it can be used for image, text and buttons
+        float alphaFactor = static_cast<float>(coopSetupTransition);
+        if (alphaFactor < 0.0f) alphaFactor = 0.0f;
+        if (alphaFactor > 1.0f) alphaFactor = 1.0f;
+        // Compute coop info image placement (draw as background for both ChoosePartner and Network steps)
+        float imgX = 0.0f, imgY = 0.0f, targetW = 0.0f, targetH = 0.0f;
+        bool hasCoopImg = false;
+        if (coopInfoTexture && coopInfoTexW > 0 && coopInfoTexH > 0) {
+            float totalW = totalChoiceW;
+            // Keep coop info image slightly smaller than the button row.
+            // Use a modest scale so it doesn't dominate the UI.
+            float maxImgW = totalW * 0.65f;
+            targetW = std::min(maxImgW, static_cast<float>(coopInfoTexW));
+            float scale = targetW / static_cast<float>(coopInfoTexW);
+            targetH = static_cast<float>(coopInfoTexH) * scale;
+            imgX = bx + (totalW - targetW) * 0.5f;
+            imgY = by - targetH - 8.0f; // keep the small gap above buttons
+            float minY = panelBaseY + 6.0f;
+            if (imgY < minY) imgY = minY;
+            SDL_FRect dst{ imgX, imgY, targetW, targetH };
+            SDL_SetTextureBlendMode(coopInfoTexture, SDL_BLENDMODE_BLEND);
+            // Make the coop info image slightly transparent scaled by transition
+            SDL_SetTextureAlphaMod(coopInfoTexture, static_cast<Uint8>(std::round(200.0f * alphaFactor)));
+            SDL_RenderTexture(renderer, coopInfoTexture, nullptr, &dst);
+            hasCoopImg = true;
+
+            // Only draw the instructional overlay text when choosing partner.
+            if (coopSetupStep == CoopSetupStep::ChoosePartner) {
+                FontAtlas* f = ctx.font ? ctx.font : ctx.pixelFont;
+                if (f) {
+                    const float pad = 38.0f;
+                    float textX = panelBaseX + pad;
+                    // Position the text over the lower portion of the image (overlay)
+                    // Move the block upward by ~150px to match UI request
+                    float textY = imgY + targetH - std::min(80.0f, targetH * 0.35f) - 150.0f;
+
+                    // Bulleted list (measure sample line height first)
+                    const std::vector<std::string> bullets = {
+                        "The playfield is shared between two players",
+                        "Each player controls one half of the grid",
+                        "A line clears only when both halves are filled",
+                        "Timing and coordination are essential"
+                    };
+                    float bulletScale = 0.78f;
+                    SDL_Color bulletCol{200,220,230,220};
+                    bulletCol.a = static_cast<Uint8>(std::round(bulletCol.a * alphaFactor));
+                    int sampleLW = 0, sampleLH = 0;
+                    f->measure(bullets[0], bulletScale, sampleLW, sampleLH);
+
+                // Header: move it up by one sample row so it sits higher
+                const std::string header = "* HOW TO PLAY – COOPERATE MODE *";
+                float headerScale = 0.95f;
+                int hW=0, hH=0; f->measure(header, headerScale, hW, hH);
+                float hx = panelBaseX + (panelW - static_cast<float>(hW)) * 0.5f + 40.0f; // nudge header right by 40px
+                float headerY = textY - static_cast<float>(sampleLH);
+                SDL_Color headerCol = SDL_Color{220,240,255,230}; headerCol.a = static_cast<Uint8>(std::round(headerCol.a * alphaFactor));
+                f->draw(renderer, hx, headerY, header, headerScale, headerCol);
+                // Start body text slightly below header
+                textY = headerY + static_cast<float>(hH) + 8.0f;
+
+                // Shift non-header text to the right by 100px and down by 20px
+                float bulletX = textX + 200.0f;
+                textY += 20.0f;
+                for (const auto &line : bullets) {
+                    std::string withBullet = std::string("• ") + line;
+                    f->draw(renderer, bulletX, textY, withBullet, bulletScale, bulletCol);
+                    int lw=0, lH=0; f->measure(withBullet, bulletScale, lw, lH);
+                    textY += static_cast<float>(lH) + 6.0f;
+                }
+
+                // GOAL section (aligned with shifted bullets)
+                textY += 6.0f;
+                std::string goalTitle = "GOAL:";
+                SDL_Color goalTitleCol = SDL_Color{255,215,80,230}; goalTitleCol.a = static_cast<Uint8>(std::round(goalTitleCol.a * alphaFactor));
+                f->draw(renderer, bulletX, textY, goalTitle, 0.88f, goalTitleCol);
+                int gW=0, gH=0; f->measure(goalTitle, 0.88f, gW, gH);
+                float goalX = bulletX + static_cast<float>(gW) + 10.0f;
+                std::string goalText = "Clear lines together and achieve the highest TEAM SCORE";
+                SDL_Color goalTextCol = SDL_Color{220,240,255,220}; goalTextCol.a = static_cast<Uint8>(std::round(goalTextCol.a * alphaFactor));
+                f->draw(renderer, goalX, textY, goalText, 0.86f, goalTextCol);
+            }
+        }
+        }
+
+        // Delay + eased fade specifically for the two coop buttons so they appear after the image/text.
+        const float btnDelay = 0.25f; // fraction of transition to wait before buttons start fading
+        float rawBtn = (alphaFactor - btnDelay) / (1.0f - btnDelay);
+        rawBtn = std::clamp(rawBtn, 0.0f, 1.0f);
+        // ease-in (squared) for a slower, smoother fade
+        float buttonFade = rawBtn * rawBtn;
+        SDL_Color bgA = bg; bgA.a = static_cast<Uint8>(std::round(bgA.a * buttonFade));
+        SDL_Color borderA = border; borderA.a = static_cast<Uint8>(std::round(borderA.a * buttonFade));
+
+        // Step 1: choose partner mode
+        if (coopSetupStep == CoopSetupStep::ChoosePartner) {
+            UIRenderer::drawButton(renderer, ctx.pixelFont,
+                coopSetupBtnRects[0].x + btnW2 * 0.5f,
+                coopSetupBtnRects[0].y + btnH2 * 0.5f,
+                btnW2, btnH2,
+                "LOCAL CO-OP",
+                false,
+                coopSetupSelected == 0,
+                bgA,
+                borderA,
+                false,
+                nullptr);
+
+            UIRenderer::drawButton(renderer, ctx.pixelFont,
+                coopSetupBtnRects[1].x + btnW2 * 0.5f,
+                coopSetupBtnRects[1].y + btnH2 * 0.5f,
+                btnW2, btnH2,
+                "AI PARTNER",
+                false,
+                coopSetupSelected == 1,
+                bgA,
+                borderA,
+                false,
+                nullptr);
+
+            UIRenderer::drawButton(renderer, ctx.pixelFont,
+                coopSetupBtnRects[2].x + btnW2 * 0.5f,
+                coopSetupBtnRects[2].y + btnH2 * 0.5f,
+                btnW2, btnH2,
+                "2 PLAYER (NET)",
+                false,
+                coopSetupSelected == 2,
+                bgA,
+                borderA,
+                false,
+                nullptr);
+        }
+
+        // Step 2: network host/join selection and address entry
+        if (coopSetupStep == CoopSetupStep::NetworkChooseRole || coopSetupStep == CoopSetupStep::NetworkEnterAddress || coopSetupStep == CoopSetupStep::NetworkWaiting) {
+            // Draw two buttons centered under the main row.
+            const float roleBtnW = std::min(280.0f, panelW * 0.30f);
+            const float roleGap = 48.0f;
+            const float roleTotalW = roleBtnW * 2.0f + roleGap;
+            const float roleX = panelBaseX + (panelW - roleTotalW) * 0.5f + shiftX;
+            // Move the host/join buttons down from the previous higher position.
+            // Shift down by one button height plus half a button (effectively lower them):
+            const float roleY = by + (btnH2 * 0.5f) - 18.0f;
+
+            SDL_FRect hostRect{ roleX, roleY, roleBtnW, btnH2 };
+            SDL_FRect joinRect{ roleX + roleBtnW + roleGap, roleY, roleBtnW, btnH2 };
+
+            UIRenderer::drawButton(renderer, ctx.pixelFont,
+                hostRect.x + roleBtnW * 0.5f,
+                hostRect.y + btnH2 * 0.5f,
+                roleBtnW,
+                btnH2,
+                "HOST GAME",
+                false,
+                coopNetworkRoleSelected == 0,
+                bgA,
+                borderA,
+                false,
+                nullptr);
+
+            UIRenderer::drawButton(renderer, ctx.pixelFont,
+                joinRect.x + roleBtnW * 0.5f,
+                joinRect.y + btnH2 * 0.5f,
+                roleBtnW,
+                btnH2,
+                "JOIN GAME",
+                false,
+                coopNetworkRoleSelected == 1,
+                bgA,
+                borderA,
+                false,
+                nullptr);
+
+            FontAtlas* f = ctx.font ? ctx.font : ctx.pixelFont;
+            if (f) {
+                SDL_Color infoCol{200, 220, 230, static_cast<Uint8>(std::round(220.0f * buttonFade))};
+                // Draw connection info on separate lines and shift right by ~200px
+                char portLine[64];
+                std::snprintf(portLine, sizeof(portLine), "PORT %u", (unsigned)coopNetworkPort);
+                char hostLine[128];
+                std::snprintf(hostLine, sizeof(hostLine), "HOST IP %s", coopNetworkBindAddress.c_str());
+                char joinLine[128];
+                std::snprintf(joinLine, sizeof(joinLine), "JOIN IP %s", coopNetworkJoinAddress.c_str());
+
+                const float textShiftX = 200.0f;
+                const float textX = panelBaseX + 60.0f + textShiftX;
+                const float endpointY = (hasCoopImg ? (imgY + targetH * 0.62f) : (roleY + btnH2 + 12.0f));
+                const float lineSpacing = 28.0f;
+                // Show only the minimal info needed for the selected role.
+                f->draw(renderer, textX, endpointY, portLine, 0.90f, infoCol);
+                if (coopNetworkRoleSelected == 0) {
+                    // Host: show bind address only
+                    f->draw(renderer, textX, endpointY + lineSpacing, hostLine, 0.90f, infoCol);
+                } else {
+                    // Client: show join target only
+                    f->draw(renderer, textX, endpointY + lineSpacing, joinLine, 0.90f, infoCol);
+                }
+
+                float hintY = endpointY + lineSpacing * 2.0f + 6.0f;
+
+                // Bottom helper prompt: show a compact instruction under the image window
+                float bottomY = hasCoopImg ? (imgY + targetH + 18.0f) : (hintY + 36.0f);
+                SDL_Color bottomCol{180,200,210,200};
+                if (coopNetworkRoleSelected == 0) {
+                    f->draw(renderer, textX, bottomY, "HOST: press ENTER to edit bind IP, then press ENTER to confirm", 0.82f, bottomCol);
+                } else {
+                    f->draw(renderer, textX, bottomY, "JOIN: press ENTER to type server IP, then press ENTER to connect", 0.82f, bottomCol);
+                }
+                if (coopSetupStep == CoopSetupStep::NetworkWaiting && !coopNetworkStatusText.empty()) {
+                    SDL_Color statusCol{255, 215, 80, static_cast<Uint8>(std::round(240.0f * buttonFade))};
+                    f->draw(renderer, textX, hintY, coopNetworkStatusText, 1.00f, statusCol);
+                } else if (coopSetupStep == CoopSetupStep::NetworkEnterAddress) {
+                    SDL_Color hintCol{160, 190, 210, static_cast<Uint8>(std::round(200.0f * buttonFade))};
+                    const char* label = (coopNetworkRoleSelected == 0) ? "TYPE HOST IP (BIND) THEN ENTER" : "TYPE JOIN IP THEN ENTER";
+                    f->draw(renderer, textX, hintY, label, 0.82f, hintCol);
+                } else {
+                    SDL_Color hintCol{160, 190, 210, static_cast<Uint8>(std::round(200.0f * buttonFade))};
+                    f->draw(renderer, textX, hintY, "PRESS ENTER TO EDIT/CONFIRM   ESC TO GO BACK", 0.82f, hintCol);
+                }
+            }
+        }
     }
+    // NOTE: slide-up COOP panel intentionally removed. Only the inline
+    // highscores-area choice buttons are shown when coop setup is active.
+
+    // Inline exit HUD (no opaque background) - slides into the highscores area
+    if (exitTransition > 0.0) {
+        float easedE = static_cast<float>(exitTransition);
+        easedE = easedE * easedE * (3.0f - 2.0f * easedE);
+        const float panelW = 520.0f;
+        const float panelH = 360.0f;
+        float panelBaseX = (LOGICAL_W - panelW) * 0.5f + contentOffsetX;
+        float panelBaseY = (LOGICAL_H - panelH) * 0.5f + contentOffsetY - (LOGICAL_H * 0.10f);
+        float slideAmount = LOGICAL_H * 0.42f;
+        float panelY = panelBaseY + (1.0f - easedE) * slideAmount;
+
+        FontAtlas* titleFont = ctx.pixelFont ? ctx.pixelFont : ctx.font;
+        if (titleFont) titleFont->draw(renderer, panelBaseX + 12.0f, panelY + 6.0f, "EXIT GAME?", 1.6f, SDL_Color{255,200,80,255});
+
+        SDL_FRect area{ panelBaseX + 12.0f, panelY + 56.0f, panelW - 24.0f, panelH - 120.0f };
+        // Sample long message (scrollable)
+        // Paragraph-style lines for a nicer exit confirmation message
+        std::vector<std::string> lines = {
+            "Quit now to return to your desktop. Your current session will end.",
+            "Press YES to quit immediately, or NO to return to the menu and continue playing.",
+            "Adjust audio, controls and other settings anytime from the Options menu.",
+            "Thanks for playing SPACETRIS — we hope to see you again!"
+        };
+
+        // Draw scrollable text (no background box; increased line spacing)
+        FontAtlas* f = ctx.font ? ctx.font : ctx.pixelFont;
+        float y = area.y - (float)exitScroll;
+        const float lineSpacing = 34.0f; // increased spacing for readability
+                if (f) {
+            for (size_t i = 0; i < lines.size(); ++i) {
+                f->draw(renderer, area.x + 6.0f, y + i * lineSpacing, lines[i], 1.0f, SDL_Color{200,220,240,255});
+            }
+        }
+
+        // Draw buttons at bottom of panel
+        float btnW2 = 160.0f, btnH2 = 48.0f;
+        float bx = panelBaseX + (panelW - (btnW2 * 2.0f + 12.0f)) * 0.5f;
+        float by = panelY + panelH - 56.0f;
+        // YES button
+        SDL_Color yesBg{220,80,60, 200}; SDL_Color yesBorder{160,40,40,200};
+        SDL_Color noBg{60,140,200,200}; SDL_Color noBorder{30,90,160,200};
+        // Apply pulse alpha to buttons
+        double aMul = std::clamp(buttonGroupAlpha + buttonFlash * buttonFlashAmount, 0.0, 1.0);
+        yesBg.a = static_cast<Uint8>(std::round(aMul * static_cast<double>(yesBg.a)));
+        yesBorder.a = static_cast<Uint8>(std::round(aMul * static_cast<double>(yesBorder.a)));
+        noBg.a = static_cast<Uint8>(std::round(aMul * static_cast<double>(noBg.a)));
+        noBorder.a = static_cast<Uint8>(std::round(aMul * static_cast<double>(noBorder.a)));
+
+        UIRenderer::drawButton(renderer, ctx.pixelFont, bx + btnW2*0.5f, by, btnW2, btnH2, "YES", false, exitSelectedButton == 0, yesBg, yesBorder, true, nullptr);
+        UIRenderer::drawButton(renderer, ctx.pixelFont, bx + btnW2*1.5f + 12.0f, by, btnW2, btnH2, "NO", false, exitSelectedButton == 1, noBg, noBorder, true, nullptr);
+
+        // Ensure ctx mirrors selection for any other code
+        if (ctx.exitPopupSelectedButton) *ctx.exitPopupSelectedButton = exitSelectedButton;
+    }
+
+    // Popups (settings only - level popup is now a separate state)
     if (ctx.showSettingsPopup && *ctx.showSettingsPopup) {
-        menu_drawSettingsPopup(renderer, *ctx.font, ctx.musicEnabled ? *ctx.musicEnabled : false);
+        bool musicOn = ctx.musicEnabled ? *ctx.musicEnabled : true;
+        bool soundOn = SoundEffectManager::instance().isEnabled();
+        UIRenderer::drawSettingsPopup(renderer, ctx.font, LOGICAL_W, LOGICAL_H, musicOn, soundOn);
+    }
+
+    // Draw animated options panel if in use (either animating or visible)
+    if (optionsTransition > 0.0) {
+        // HUD-style overlay: no opaque background; draw labels/values directly with separators
+        const float panelW = 520.0f;
+        const float panelH = 420.0f;
+        float panelBaseX = (LOGICAL_W - panelW) * 0.5f + contentOffsetX;
+        // Move the HUD higher by ~10% of logical height so it sits above center
+        float panelBaseY = (LOGICAL_H - panelH) * 0.5f + contentOffsetY - (LOGICAL_H * 0.10f);
+        float panelY = panelBaseY + (1.0f - eased) * moveAmount;
+
+        // For options/settings we prefer the secondary (Exo2) font for longer descriptions.
+        FontAtlas* retroFont = ctx.font ? ctx.font : ctx.pixelFont;
+
+        if (retroFont) {
+            retroFont->draw(renderer, panelBaseX + 12.0f, panelY + 6.0f, "OPTIONS", 1.8f, SDL_Color{120, 220, 255, 255});
+        }
+
+        SDL_FRect area{panelBaseX, panelY + 48.0f, panelW, panelH - 64.0f};
+        constexpr int rowCount = 5;
+        const float rowHeight = 64.0f;
+        const float spacing = 8.0f;
+
+        auto drawField = [&](int idx, float y, const std::string& label, const std::string& value) {
+            SDL_FRect row{area.x, y, area.w, rowHeight};
+
+            // Draw thin separator (1px high filled rect) so we avoid platform-specific line API differences
+            SDL_SetRenderDrawColor(renderer, 60, 120, 160, 120);
+            SDL_FRect sep{ row.x + 6.0f, row.y + row.h - 1.0f, row.w - 12.0f, 1.0f };
+            SDL_RenderFillRect(renderer, &sep);
+
+            // Highlight the selected row with a subtle outline
+            if (idx == optionsSelectedRow) {
+                SDL_SetRenderDrawColor(renderer, 80, 200, 255, 120);
+                SDL_RenderRect(renderer, &row);
+            }
+
+                if (retroFont) {
+                SDL_Color labelColor = SDL_Color{170, 210, 220, 255};
+                SDL_Color valueColor = SDL_Color{160, 240, 255, 255};
+                if (!label.empty()) {
+                    float labelScale = 1.0f;
+                    int labelW = 0, labelH = 0;
+                    retroFont->measure(label, labelScale, labelW, labelH);
+                    float labelY = row.y + (row.h - static_cast<float>(labelH)) * 0.5f;
+                    retroFont->draw(renderer, row.x + 16.0f, labelY, label, labelScale, labelColor);
+                }
+                int valueW = 0, valueH = 0;
+                float valueScale = 1.4f;
+                retroFont->measure(value, valueScale, valueW, valueH);
+                float valX = row.x + row.w - static_cast<float>(valueW) - 16.0f;
+                float valY = row.y + (row.h - valueH) * 0.5f;
+                retroFont->draw(renderer, valX, valY, value, valueScale, valueColor);
+            }
+        };
+
+        float rowY = area.y + spacing;
+        // FULLSCREEN
+        bool isFS = ctx.fullscreenFlag ? *ctx.fullscreenFlag : Settings::instance().isFullscreen();
+        drawField(0, rowY, "FULLSCREEN", isFS ? "ON" : "OFF");
+        rowY += rowHeight + spacing;
+        // MUSIC
+        bool musicOn = ctx.musicEnabled ? *ctx.musicEnabled : Settings::instance().isMusicEnabled();
+        drawField(1, rowY, "MUSIC", musicOn ? "ON" : "OFF");
+        rowY += rowHeight + spacing;
+        // SOUND FX
+        bool soundOn = SoundEffectManager::instance().isEnabled();
+        drawField(2, rowY, "SOUND FX", soundOn ? "ON" : "OFF");
+        rowY += rowHeight + spacing;
+        // SMOOTH SCROLL
+        bool smooth = Settings::instance().isSmoothScrollEnabled();
+        drawField(3, rowY, "SMOOTH SCROLL", smooth ? "ON" : "OFF");
+        rowY += rowHeight + spacing;
+        // RETURN TO MENU
+        drawField(4, rowY, "", "RETURN TO MENU");
+    }
+
+    // Draw inline help HUD (no boxed background) — match Options/Exit style
+    if (helpTransition > 0.0) {
+        float easedH = static_cast<float>(helpTransition);
+        easedH = easedH * easedH * (3.0f - 2.0f * easedH);
+        const float PW = std::min(520.0f, LOGICAL_W * 0.65f);
+        const float PH = std::min(420.0f, LOGICAL_H * 0.72f);
+        float panelBaseX = (LOGICAL_W - PW) * 0.5f + contentOffsetX;
+        float panelBaseY = (LOGICAL_H - PH) * 0.5f + contentOffsetY - (LOGICAL_H * 0.10f);
+        float slideAmount = LOGICAL_H * 0.42f;
+        float panelY = panelBaseY + (1.0f - easedH) * slideAmount;
+
+        FontAtlas* f = ctx.pixelFont ? ctx.pixelFont : ctx.font;
+        if (f) {
+            // Header (smaller)
+            f->draw(renderer, panelBaseX + 12.0f, panelY + 6.0f, "HELP & SHORTCUTS", 1.25f, SDL_Color{255,220,0,255});
+
+            // Content layout (two columns)
+            const float contentPadding = 16.0f;
+            const float columnGap = 18.0f;
+            const float columnWidth = (PW - contentPadding * 2.0f - columnGap) * 0.5f;
+            const float leftX = panelBaseX + contentPadding;
+            const float rightX = leftX + columnWidth + columnGap;
+
+            // Shortcut entries (copied from HelpOverlay)
+            struct ShortcutEntry { const char* combo; const char* description; };
+            const ShortcutEntry generalShortcuts[] = {
+                {"F1", "Toggle this help overlay"},
+                {"ESC", "Back / cancel current popup"},
+                {"F11 or ALT+ENTER", "Toggle fullscreen"},
+                {"M", "Mute or unmute music"},
+                {"K", "Toggle sound effects"}
+            };
+            const ShortcutEntry menuShortcuts[] = {
+                {"ARROW KEYS", "Navigate menu buttons"},
+                {"ENTER / SPACE", "Activate highlighted action"}
+            };
+            const ShortcutEntry gameplayShortcuts[] = {
+                {"LEFT / RIGHT", "Move active piece"},
+                {"DOWN", "Soft drop (faster fall)"},
+                {"SPACE", "Hard drop / instant lock"},
+                {"UP", "Rotate clockwise"},
+                {"H", "Hold / swap current piece"},
+                {"X", "Toggle rotation direction used by UP"},
+                {"P", "Pause or resume"},
+                {"ESC", "Open exit confirmation"}
+            };
+
+            // Helper to draw text with extra letter-spacing (tracking)
+            auto drawSpaced = [&](float sx, float sy, const char* text, float scale, SDL_Color color, float extraPx) {
+                std::string stext(text);
+                float x = sx;
+                for (size_t i = 0; i < stext.size(); ++i) {
+                    std::string ch(1, stext[i]);
+                    f->draw(renderer, x, sy, ch.c_str(), scale, color);
+                    int cw = 0, chh = 0;
+                    f->measure(ch.c_str(), scale, cw, chh);
+                    x += static_cast<float>(cw) + extraPx;
+                }
+            };
+
+            auto drawSection = [&](float sx, float& cursorY, const char* title, const ShortcutEntry* entries, int count) {
+                // Section title (smaller) with added letter spacing (reduced scale)
+                drawSpaced(sx, cursorY, title, 0.85f, SDL_Color{180,200,255,255}, 4.0f);
+                // Add extra gap after the headline so it separates clearly from the first row
+                cursorY += 28.0f;
+                for (int i = 0; i < count; ++i) {
+                    const auto &entry = entries[i];
+                    // Combo/key label
+                    f->draw(renderer, sx, cursorY, entry.combo, 0.70f, SDL_Color{255,255,255,255});
+                    // Slightly more space between the combo/key and the description
+                    cursorY += 26.0f;
+
+                    // Description (smaller) with increased spacing
+                    f->draw(renderer, sx + 6.0f, cursorY, entry.description, 0.62f, SDL_Color{200,210,230,255});
+                    int w=0,h=0; f->measure(entry.description, 0.62f, w, h);
+                    cursorY += static_cast<float>(h) + 16.0f;
+                }
+
+                // (rest of help render continues below)
+                // Add a larger gap between sections
+                cursorY += 22.0f;
+
+        // Draw inline ABOUT HUD (no boxed background) — simple main info
+        if (aboutTransition > 0.0) {
+            float easedA = static_cast<float>(aboutTransition);
+            easedA = easedA * easedA * (3.0f - 2.0f * easedA);
+            const float PW = std::min(520.0f, LOGICAL_W * 0.65f);
+            const float PH = std::min(320.0f, LOGICAL_H * 0.60f);
+            float panelBaseX = (LOGICAL_W - PW) * 0.5f + contentOffsetX;
+            float panelBaseY = (LOGICAL_H - PH) * 0.5f + contentOffsetY - (LOGICAL_H * 0.10f);
+            float slideAmount = LOGICAL_H * 0.42f;
+            float panelY = panelBaseY + (1.0f - easedA) * slideAmount;
+
+            FontAtlas* f = ctx.pixelFont ? ctx.pixelFont : ctx.font;
+            if (f) {
+                f->draw(renderer, panelBaseX + 12.0f, panelY + 6.0f, "ABOUT", 1.25f, SDL_Color{255,220,0,255});
+
+                float x = panelBaseX + 16.0f;
+                float y = panelY + 52.0f;
+                const float lineGap = 30.0f;
+                const SDL_Color textCol{200, 210, 230, 255};
+                const SDL_Color keyCol{255, 255, 255, 255};
+
+                f->draw(renderer, x, y, "SDL3 SPACETRIS", 1.05f, keyCol); y += lineGap;
+                f->draw(renderer, x, y, "C++20 / SDL3 / SDL3_ttf", 0.80f, textCol); y += lineGap + 6.0f;
+
+                f->draw(renderer, x, y, "GAMEPLAY", 0.85f, SDL_Color{180,200,255,255}); y += lineGap;
+                f->draw(renderer, x, y, "H     Hold / swap current piece", 0.78f, textCol); y += lineGap;
+                f->draw(renderer, x, y, "SPACE Hard drop", 0.78f, textCol); y += lineGap;
+                f->draw(renderer, x, y, "P     Pause", 0.78f, textCol); y += lineGap + 6.0f;
+
+                f->draw(renderer, x, y, "UI", 0.85f, SDL_Color{180,200,255,255}); y += lineGap;
+                f->draw(renderer, x, y, "F1    Toggle help overlay", 0.78f, textCol); y += lineGap;
+                f->draw(renderer, x, y, "ESC   Back / exit prompt", 0.78f, textCol); y += lineGap + 10.0f;
+
+                f->draw(renderer, x, y, "PRESS ESC OR ARROW KEYS TO RETURN", 0.75f, SDL_Color{215,220,240,255});
+            }
+        }
+            };
+
+            const float contentTopY = panelY + 30.0f;
+            float leftCursor = contentTopY - static_cast<float>(helpScroll);
+            float rightCursor = contentTopY - static_cast<float>(helpScroll);
+            drawSection(leftX, leftCursor, "GENERAL", generalShortcuts, (int)(sizeof(generalShortcuts)/sizeof(generalShortcuts[0])));
+            drawSection(leftX, leftCursor, "MENUS", menuShortcuts, (int)(sizeof(menuShortcuts)/sizeof(menuShortcuts[0])));
+            drawSection(rightX, rightCursor, "GAMEPLAY", gameplayShortcuts, (int)(sizeof(gameplayShortcuts)/sizeof(gameplayShortcuts[0])));
+
+            // Ensure helpScroll bounds (simple clamp)
+            float contentHeight = std::max(leftCursor, rightCursor) - contentTopY;
+            float maxScroll = std::max(0.0f, contentHeight - (PH - 120.0f));
+            if (helpScroll < 0.0) helpScroll = 0.0;
+            if (helpScroll > maxScroll) helpScroll = maxScroll;
+        }
+    }
+
+    // Draw inline level selector HUD (no background) if active
+    if (levelTransition > 0.0) {
+        float easedL = static_cast<float>(levelTransition);
+        easedL = easedL * easedL * (3.0f - 2.0f * easedL);
+        const float PW = std::min(520.0f, LOGICAL_W * 0.65f);
+        const float PH = std::min(360.0f, LOGICAL_H * 0.7f);
+        float panelBaseX = (LOGICAL_W - PW) * 0.5f + contentOffsetX;
+        float panelBaseY = (LOGICAL_H - PH) * 0.5f + contentOffsetY - (LOGICAL_H * 0.10f);
+        float slideAmount = LOGICAL_H * 0.42f;
+        float panelY = panelBaseY + (1.0f - easedL) * slideAmount;
+
+        // Header
+        FontAtlas* titleFont = ctx.pixelFont ? ctx.pixelFont : ctx.font;
+        if (titleFont) titleFont->draw(renderer, panelBaseX + PW * 0.5f - 140.0f, panelY + 6.0f, "SELECT STARTING LEVEL", 1.1f, SDL_Color{160,220,255,255});
+
+        // Grid area
+        float marginX = 34.0f, marginY = 56.0f;
+        SDL_FRect area{ panelBaseX + marginX, panelY + marginY, PW - 2.0f * marginX, PH - marginY - 28.0f };
+        const int cols = 4, rows = 5;
+        const float gapX = 12.0f, gapY = 12.0f;
+        float cellW = (area.w - (cols - 1) * gapX) / cols;
+        float cellH = (area.h - (rows - 1) * gapY) / rows;
+
+        for (int i = 0; i < 20; ++i) {
+            int r = i / cols, c = i % cols;
+            SDL_FRect rc{ area.x + c * (cellW + gapX), area.y + r * (cellH + gapY), cellW, cellH };
+            bool hovered = (levelSelected == i) || (levelHovered == i);
+            bool selected = (ctx.startLevelSelection && *ctx.startLevelSelection == i);
+            // Use the project's gold/yellow tone for selected level to match UI accents
+            SDL_Color selectedFill = SDL_Color{255,204,0,160};
+            SDL_Color fill = selected ? selectedFill : (hovered ? SDL_Color{60,80,100,120} : SDL_Color{30,40,60,110});
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+            SDL_SetRenderDrawColor(renderer, fill.r, fill.g, fill.b, fill.a);
+            SDL_RenderFillRect(renderer, &rc);
+            SDL_SetRenderDrawColor(renderer, 80,100,120,160);
+            SDL_RenderRect(renderer, &rc);
+
+            // Draw level number
+            FontAtlas* f = ctx.font ? ctx.font : ctx.pixelFont;
+            if (f) {
+                char buf[8]; std::snprintf(buf, sizeof(buf), "%d", i);
+                int w=0,h=0; f->measure(buf, 1.6f, w, h);
+                f->draw(renderer, rc.x + (rc.w - w) * 0.5f, rc.y + (rc.h - h) * 0.5f, buf, 1.6f, SDL_Color{220,230,240,255});
+            }
+        }
+
+        // Draw animated highlight (interpolated) on top of cells
+        if (levelHighlightInitialized) {
+            float hx = (float)levelHighlightX;
+            float hy = (float)levelHighlightY;
+            float hw = cellW + 6.0f;
+            float hh = cellH + 6.0f;
+            // Draw multi-layer glow: outer faint, mid, inner bright
+            SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+            // Outer glow
+            SDL_SetRenderDrawColor(renderer, levelHighlightColor.r, levelHighlightColor.g, levelHighlightColor.b, (Uint8)(levelHighlightGlowAlpha * 80));
+            SDL_FRect outer{ hx - (hw * 0.5f + 8.0f), hy - (hh * 0.5f + 8.0f), hw + 16.0f, hh + 16.0f };
+            SDL_RenderRect(renderer, &outer);
+            // Mid glow
+            SDL_SetRenderDrawColor(renderer, levelHighlightColor.r, levelHighlightColor.g, levelHighlightColor.b, (Uint8)(levelHighlightGlowAlpha * 140));
+            SDL_FRect mid{ hx - (hw * 0.5f + 4.0f), hy - (hh * 0.5f + 4.0f), hw + 8.0f, hh + 8.0f };
+            SDL_RenderRect(renderer, &mid);
+            // Inner outline
+            SDL_SetRenderDrawColor(renderer, levelHighlightColor.r, levelHighlightColor.g, levelHighlightColor.b, levelHighlightColor.a);
+            SDL_FRect inner{ hx - hw * 0.5f, hy - hh * 0.5f, hw, hh };
+            // Draw multiple rects to simulate thickness
+            for (int t = 0; t < levelHighlightThickness; ++t) {
+                SDL_FRect r{ inner.x - t, inner.y - t, inner.w + t * 2.0f, inner.h + t * 2.0f };
+                SDL_RenderRect(renderer, &r);
+            }
+        }
+
+        // Instructions
+        FontAtlas* foot = ctx.font ? ctx.font : ctx.pixelFont;
+        if (foot) foot->draw(renderer, panelBaseX + PW*0.5f - 160.0f, panelY + PH + 40.0f, "ARROWS = NAV  •  ENTER = SELECT  •  ESC = CANCEL", 0.9f, SDL_Color{160,180,200,200});
+    }
+    // Trace exit
+    {
+        FILE* f = fopen("spacetris_trace.log", "a"); if (f) { fprintf(f, "MenuState::render exit\n"); fclose(f); }
+    }
+
+    // Network coop flow polling (non-blocking)
+    if (coopSetupAnimating || coopSetupVisible) {
+        if (coopSetupStep == CoopSetupStep::NetworkWaiting && coopNetworkSession) {
+            coopNetworkSession->poll(0);
+
+            // Update status depending on connection and role.
+            if (!coopNetworkSession->isConnected()) {
+                // Keep existing text (WAITING/CONNECTING) unless an error occurs.
+            } else {
+                // Host sends handshake after peer connects.
+                if (coopNetworkRoleSelected == 0 && !coopNetworkHandshakeSent) {
+                    std::random_device rd;
+                    uint32_t seed = static_cast<uint32_t>(rd());
+                    if (seed == 0u) seed = 1u;
+                    const uint8_t startLevel = static_cast<uint8_t>(ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+                    NetSession::Handshake hs{ seed, 0u, startLevel };
+                    if (coopNetworkSession->sendHandshake(hs)) {
+                        coopNetworkHandshakeSent = true;
+                        ctx.coopNetRngSeed = seed;
+                        coopNetworkStatusText = "CONNECTED";
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET COOP] HOST handshake sent seed=%u level=%u", seed, (unsigned)startLevel);
+                    } else {
+                        coopNetworkStatusText = "HANDSHAKE FAILED";
+                    }
+                }
+
+                // Client waits for handshake.
+                if (coopNetworkRoleSelected == 1) {
+                    auto hs = coopNetworkSession->takeReceivedHandshake();
+                    if (hs.has_value()) {
+                        coopNetworkStatusText = "CONNECTED";
+                        coopNetworkHandshakeSent = true;
+                        ctx.coopNetRngSeed = hs->rngSeed;
+                        if (ctx.startLevelSelection) {
+                            *ctx.startLevelSelection = static_cast<int>(hs->startLevel);
+                        }
+                        SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[NET COOP] CLIENT handshake recv seed=%u level=%u", hs->rngSeed, (unsigned)hs->startLevel);
+                    } else {
+                        coopNetworkStatusText = "CONNECTED - WAITING FOR HOST...";
+                    }
+                }
+
+                // Confirmed connection => start COOPERATE (network) session.
+                // Note: gameplay/network input injection is implemented separately.
+                if (coopNetworkHandshakeSent) {
+                    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION,
+                                "[NET COOP] START gameplay (role=%s localIsLeft=%d seed=%u level=%u)",
+                                (coopNetworkRoleSelected == 0 ? "HOST" : "CLIENT"),
+                                (coopNetworkRoleSelected == 0 ? 1 : 0),
+                                (unsigned)ctx.coopNetRngSeed,
+                                (unsigned)(ctx.startLevelSelection ? *ctx.startLevelSelection : 0));
+                    // Hand off the session to gameplay.
+                    if (ctx.coopNetSession) {
+                        ctx.coopNetSession->shutdown();
+                        ctx.coopNetSession.reset();
+                    }
+
+                    ctx.coopNetEnabled = true;
+                    ctx.coopNetIsHost = (coopNetworkRoleSelected == 0);
+                    ctx.coopNetLocalIsLeft = (coopNetworkRoleSelected == 0);
+                    ctx.coopNetTick = 0;
+                    ctx.coopNetPendingButtons = 0;
+                    ctx.coopNetDesyncDetected = false;
+
+                    const uint32_t seed = (ctx.coopNetRngSeed == 0u) ? 1u : ctx.coopNetRngSeed;
+                    const uint8_t startLevel = static_cast<uint8_t>(ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+
+                    if (ctx.coopVsAI) {
+                        *ctx.coopVsAI = false;
+                    }
+                    if (ctx.game) {
+                        ctx.game->setMode(GameMode::Cooperate);
+                        ctx.game->reset(ctx.startLevelSelection ? *ctx.startLevelSelection : 0);
+                    }
+                    if (ctx.coopGame) {
+                        // Deterministic reset for network coop.
+                        ctx.coopGame->resetDeterministic(startLevel, seed);
+                    }
+
+                    // Transfer ownership of the active session.
+                    ctx.coopNetSession = std::move(coopNetworkSession);
+
+                    // Close the panel without restarting menu music; gameplay will take over.
+                    showCoopSetupPanel(false, false);
+
+                    // For network lockstep, do NOT run the menu->play countdown/fade.
+                    // Any local countdown introduces drift and stalls.
+                    if (ctx.gameplayCountdownActive) *ctx.gameplayCountdownActive = false;
+                    if (ctx.menuPlayCountdownArmed) *ctx.menuPlayCountdownArmed = false;
+                    if (ctx.game) ctx.game->setPaused(false);
+
+                    if (ctx.stateManager) {
+                        ctx.stateManager->setState(AppState::Playing);
+                    } else if (ctx.startPlayTransition) {
+                        // Fallback if state manager is unavailable.
+                        ctx.startPlayTransition();
+                    }
+                }
+            }
+        }
     }
 }
+
+
diff --git a/src/states/MenuState.h b/src/states/MenuState.h
index 7b6f332..0da134d 100644
--- a/src/states/MenuState.h
+++ b/src/states/MenuState.h
@@ -2,6 +2,12 @@
 #pragma once
 #include "State.h"
 
+#include <cstdint>
+#include <memory>
+#include <string>
+
+class NetSession;
+
 class MenuState : public State {
 public:
     MenuState(StateContext& ctx);
@@ -10,4 +16,125 @@ public:
     void handleEvent(const SDL_Event& e) override;
     void update(double frameMs) override;
     void render(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) override;
+    // When false, the main PLAY button is not drawn by `render()` and can be
+    // rendered separately with `renderMainButtonTop` (useful for layer ordering).
+    bool drawMainButtonNormally = true;
+    // Draw only the main PLAY button on top of other layers (expects logical coords).
+    void renderMainButtonTop(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP);
+    // Show or hide the inline HELP panel (menu-style)
+    void showHelpPanel(bool show);
+    // Show or hide the inline ABOUT panel (menu-style)
+    void showAboutPanel(bool show);
+
+    // Show or hide the inline COOPERATE setup panel (2P vs AI).
+    // If `resumeMusic` is false when hiding, the menu music will not be restarted.
+    void showCoopSetupPanel(bool show, bool resumeMusic = true);
+    
+private:
+    int selectedButton = 0; // 0=PLAY,1=COOPERATE,2=CHALLENGE,3=LEVEL,4=OPTIONS,5=HELP,6=ABOUT,7=EXIT
+    
+    // Button icons (optional - will use text if nullptr)
+    SDL_Texture* playIcon = nullptr;
+    SDL_Texture* levelIcon = nullptr;
+    SDL_Texture* optionsIcon = nullptr;
+    SDL_Texture* exitIcon = nullptr;
+    SDL_Texture* helpIcon = nullptr;
+    
+    // Options panel animation state
+    bool optionsVisible = false;
+    bool optionsAnimating = false;
+    double optionsTransition = 0.0; // 0..1
+    double optionsTransitionDurationMs = 400.0;
+    int optionsDirection = 1; // 1 show, -1 hide
+    // Which row in the inline options panel is currently selected (0..4)
+    int optionsSelectedRow = 0;
+    // Inline level selector HUD state
+    bool levelPanelVisible = false;
+    bool levelPanelAnimating = false;
+    double levelTransition = 0.0; // 0..1
+    double levelTransitionDurationMs = 400.0;
+    int levelDirection = 1; // 1 show, -1 hide
+    int levelHovered = -1; // hovered cell
+    int levelSelected = 0; // current selected level
+    // Cache logical viewport/scale for input conversion when needed
+    float lastLogicalScale = 1.0f;
+    SDL_Rect lastLogicalVP{0,0,0,0};
+    // Animated highlight position (world/logical coordinates)
+    double levelHighlightX = 0.0;
+    double levelHighlightY = 0.0;
+    bool levelHighlightInitialized = false;
+    // Highlight tuning parameters
+    double levelHighlightSpeed = 0.018; // smoothing constant - higher = snappier
+    double levelHighlightGlowAlpha = 0.70; // 0..1 base glow alpha
+    int levelHighlightThickness = 3; // inner outline thickness (px)
+    SDL_Color levelHighlightColor = SDL_Color{80, 200, 255, 200};
+    // Button pulsing/fade parameters (used for PLAY emphasis)
+    double buttonGroupAlpha = 1.0; // base alpha for the whole group (kept stable)
+    double buttonPulseAlpha = 1.0; // pulsing alpha (0..1), applied to PLAY only
+    double buttonPulseTime = 0.0;  // accumulator in ms
+    bool   buttonPulseEnabled = true; // enable/disable pulsing
+    double buttonPulseSpeed = 1.0;  // multiplier for pulse frequency
+    double buttonPulseMinAlpha = 0.60; // minimum alpha during pulse
+    double buttonPulseMaxAlpha = 1.00; // maximum alpha during pulse
+    // Pulse easing mode: 0=sin,1=triangle,2=exponential
+    int    buttonPulseEasing = 1;
+    // Short bright flash when navigating buttons
+    double buttonFlash = 0.0; // transient flash amount (0..1)
+    double buttonFlashAmount = 0.45; // how much flash adds to group alpha
+    double buttonFlashDecay = 0.0025; // linear decay per ms
+    // Exit confirmation HUD state (inline HUD like Options/Level)
+    bool exitPanelVisible = false;
+    bool exitPanelAnimating = false;
+    double exitTransition = 0.0; // 0..1
+    double exitTransitionDurationMs = 360.0;
+    int exitDirection = 1; // 1 show, -1 hide
+    int exitSelectedButton = 0; // 0 = YES (quit), 1 = NO (cancel)
+    double exitScroll = 0.0; // vertical scroll offset for content
+    // Help submenu (inline HUD like Options/Exit)
+    bool helpPanelVisible = false;
+    bool helpPanelAnimating = false;
+    double helpTransition = 0.0; // 0..1
+    double helpTransitionDurationMs = 360.0;
+    int helpDirection = 1; // 1 show, -1 hide
+    double helpScroll = 0.0; // vertical scroll offset for content
+
+    // About submenu (inline HUD like Help)
+    bool aboutPanelVisible = false;
+    bool aboutPanelAnimating = false;
+    double aboutTransition = 0.0; // 0..1
+    double aboutTransitionDurationMs = 360.0;
+    int aboutDirection = 1; // 1 show, -1 hide
+
+    // Coop setup panel (inline HUD like Exit/Help)
+    bool coopSetupVisible = false;
+    bool coopSetupAnimating = false;
+    double coopSetupTransition = 0.0; // 0..1
+    double coopSetupTransitionDurationMs = 320.0;
+    int coopSetupDirection = 1; // 1 show, -1 hide
+    // 0 = Local co-op (2 players), 1 = AI partner, 2 = 2 player (network)
+    int coopSetupSelected = 0;
+
+    enum class CoopSetupStep {
+        ChoosePartner,
+        NetworkChooseRole,
+        NetworkEnterAddress,
+        NetworkWaiting,
+    };
+    CoopSetupStep coopSetupStep = CoopSetupStep::ChoosePartner;
+
+    // Network sub-flow state (only used when coopSetupSelected == 2)
+    int coopNetworkRoleSelected = 0; // 0 = host, 1 = join
+    std::string coopNetworkBindAddress = "0.0.0.0";
+    std::string coopNetworkJoinAddress = "127.0.0.1";
+    uint16_t coopNetworkPort = 7777;
+    bool coopNetworkHandshakeSent = false;
+    std::string coopNetworkStatusText;
+    std::unique_ptr<NetSession> coopNetworkSession;
+
+    SDL_FRect coopSetupBtnRects[3]{};
+    bool coopSetupRectsValid = false;
+    // Optional cooperative info image shown when coop setup panel is active
+    SDL_Texture* coopInfoTexture = nullptr;
+    int coopInfoTexW = 0;
+    int coopInfoTexH = 0;
 };
diff --git a/src/states/OptionsState.cpp b/src/states/OptionsState.cpp
new file mode 100644
index 0000000..bec188d
--- /dev/null
+++ b/src/states/OptionsState.cpp
@@ -0,0 +1,286 @@
+#include "OptionsState.h"
+#include "../core/state/StateManager.h"
+#include "../graphics/ui/Font.h"
+#include "../audio/Audio.h"
+#include "../audio/SoundEffect.h"
+#include <SDL3/SDL.h>
+#include <algorithm>
+#include <cctype>
+#include "../core/Settings.h"
+#include "../graphics/renderers/UIRenderer.h"
+
+OptionsState::OptionsState(StateContext& ctx) : State(ctx) {}
+
+void OptionsState::onEnter() {
+    m_selectedField = Field::Fullscreen;
+    m_cursorTimer = 0.0;
+    m_cursorVisible = true;
+    if (SDL_Window* focusWin = SDL_GetKeyboardFocus()) {
+        SDL_StartTextInput(focusWin);
+    }
+}
+
+void OptionsState::onExit() {
+    if (SDL_Window* focusWin = SDL_GetKeyboardFocus()) {
+        SDL_StopTextInput(focusWin);
+    }
+}
+
+void OptionsState::handleEvent(const SDL_Event& e) {
+    if (e.type == SDL_EVENT_KEY_DOWN && !e.key.repeat) {
+        switch (e.key.scancode) {
+            case SDL_SCANCODE_ESCAPE:
+                exitToMenu();
+                return;
+            case SDL_SCANCODE_UP:
+            case SDL_SCANCODE_W:
+                moveSelection(-1);
+                return;
+            case SDL_SCANCODE_DOWN:
+            case SDL_SCANCODE_S:
+                moveSelection(1);
+                return;
+            case SDL_SCANCODE_RETURN:
+            case SDL_SCANCODE_KP_ENTER:
+            case SDL_SCANCODE_SPACE:
+                activateSelection();
+                return;
+            case SDL_SCANCODE_F:
+                toggleFullscreen();
+                return;
+            case SDL_SCANCODE_LEFT:
+            case SDL_SCANCODE_RIGHT:
+                if (m_selectedField == Field::Fullscreen) {
+                    toggleFullscreen();
+                    return;
+                }
+                if (m_selectedField == Field::Music) {
+                    toggleMusic();
+                    return;
+                }
+                if (m_selectedField == Field::SoundFx) {
+                    toggleSoundFx();
+                    return;
+                }
+                if (m_selectedField == Field::SmoothScroll) {
+                    toggleSmoothScroll();
+                    return;
+                }
+                break;
+            default:
+                break;
+        }
+
+    }
+}
+
+void OptionsState::update(double frameMs) {
+    m_cursorTimer += frameMs;
+    if (m_cursorTimer >= 450.0) {
+        m_cursorTimer = 0.0;
+        m_cursorVisible = !m_cursorVisible;
+    }
+}
+
+void OptionsState::render(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) {
+    if (!renderer) return;
+
+    const float LOGICAL_W = 1200.0f;
+    const float LOGICAL_H = 1000.0f;
+
+    float winW = static_cast<float>(logicalVP.w);
+    float winH = static_cast<float>(logicalVP.h);
+    float contentOffsetX = 0.0f;
+    float contentOffsetY = 0.0f;
+    UIRenderer::computeContentOffsets(winW, winH, LOGICAL_W, LOGICAL_H, logicalScale, contentOffsetX, contentOffsetY);
+
+    SDL_Texture* logoTexture = ctx.logoSmallTex ? ctx.logoSmallTex : ctx.logoTex;
+    int logoW = 0, logoH = 0;
+    if (logoTexture == ctx.logoSmallTex && ctx.logoSmallW > 0) {
+        logoW = ctx.logoSmallW;
+        logoH = ctx.logoSmallH;
+    }
+    UIRenderer::drawLogo(renderer, logoTexture, LOGICAL_W, LOGICAL_H, contentOffsetX, contentOffsetY, logoW, logoH);
+
+    const float panelW = 520.0f;
+    const float panelH = 420.0f;
+    SDL_FRect panel{
+        (LOGICAL_W - panelW) * 0.5f + contentOffsetX,
+        (LOGICAL_H - panelH) * 0.5f + contentOffsetY,
+        panelW,
+        panelH
+    };
+
+    UIRenderer::drawSciFiPanel(renderer, panel);
+
+    // For options/settings we prefer the secondary (Exo2) font for longer descriptions.
+    FontAtlas* retroFont = ctx.font ? ctx.font : ctx.pixelFont;
+
+    if (!logoTexture && retroFont) {
+        retroFont->draw(renderer, panel.x + 24.0f, panel.y + 24.0f, "OPTIONS", 2.0f, {255, 230, 120, 255});
+    }
+
+    SDL_FRect inner{panel.x + 20.0f, panel.y + 80.0f, panel.w - 40.0f, panel.h - 120.0f};
+    SDL_SetRenderDrawColor(renderer, 16, 24, 40, 235);
+    SDL_RenderFillRect(renderer, &inner);
+    SDL_SetRenderDrawColor(renderer, 40, 80, 140, 240);
+    SDL_RenderRect(renderer, &inner);
+
+    constexpr int rowCount = 5;
+    const float rowHeight = 60.0f;
+    const float spacing = std::max(0.0f, (inner.h - rowHeight * rowCount) / (rowCount + 1));
+
+    auto drawField = [&](Field field, float y, const std::string& label, const std::string& value) {
+        bool selected = (field == m_selectedField);
+        SDL_FRect row{inner.x + 12.0f, y, inner.w - 24.0f, rowHeight};
+
+        SDL_SetRenderDrawColor(renderer, selected ? 55 : 28, selected ? 90 : 40, selected ? 140 : 60, 235);
+        SDL_RenderFillRect(renderer, &row);
+        SDL_SetRenderDrawColor(renderer, selected ? 180 : 90, selected ? 210 : 120, 255, 255);
+        SDL_RenderRect(renderer, &row);
+
+        if (retroFont) {
+            SDL_Color labelColor = selected ? SDL_Color{255, 220, 120, 255} : SDL_Color{210, 200, 190, 255};
+            SDL_Color valueColor = selected ? SDL_Color{255, 255, 255, 255} : SDL_Color{215, 230, 250, 255};
+
+            if (!label.empty()) {
+                float labelScale = 1.2f;
+                int labelW = 0;
+                int labelH = 0;
+                retroFont->measure(label, labelScale, labelW, labelH);
+                float labelY = row.y + (row.h - static_cast<float>(labelH)) * 0.5f;
+                retroFont->draw(renderer, row.x + 16.0f, labelY, label, labelScale, labelColor);
+            }
+
+            int valueW = 0, valueH = 0;
+            float valueScale = (field == Field::Back) ? 1.3f : 1.5f;
+            retroFont->measure(value, valueScale, valueW, valueH);
+            bool rightAlign = (field == Field::Fullscreen || field == Field::Music || field == Field::SoundFx || field == Field::SmoothScroll);
+            float valX = rightAlign
+                ? (row.x + row.w - static_cast<float>(valueW) - 16.0f)
+                : (row.x + (row.w - static_cast<float>(valueW)) * 0.5f);
+            float valY = row.y + (row.h - valueH) * 0.5f;
+            retroFont->draw(renderer, valX, valY, value, valueScale, valueColor);
+        }
+    };
+
+    float rowY = inner.y + spacing;
+
+    drawField(Field::Fullscreen, rowY, "FULLSCREEN", isFullscreen() ? "ON" : "OFF");
+    rowY += rowHeight + spacing;
+    drawField(Field::Music, rowY, "MUSIC", isMusicEnabled() ? "ON" : "OFF");
+    rowY += rowHeight + spacing;
+    drawField(Field::SoundFx, rowY, "SOUND FX", isSoundFxEnabled() ? "ON" : "OFF");
+    rowY += rowHeight + spacing;
+    drawField(Field::SmoothScroll, rowY, "SMOOTH SCROLL", isSmoothScrollEnabled() ? "ON" : "OFF");
+    rowY += rowHeight + spacing;
+    drawField(Field::Back, rowY, "", "RETURN TO MENU");
+
+    (void)retroFont; // footer removed for cleaner layout
+}
+
+void OptionsState::moveSelection(int delta) {
+    int idx = static_cast<int>(m_selectedField);
+    int total = static_cast<int>(Field::Back) + 1;
+    idx = (idx + delta + total) % total;
+    m_selectedField = static_cast<Field>(idx);
+}
+
+void OptionsState::activateSelection() {
+    switch (m_selectedField) {
+        case Field::Fullscreen:
+            toggleFullscreen();
+            break;
+        case Field::Music:
+            toggleMusic();
+            break;
+        case Field::SoundFx:
+            toggleSoundFx();
+            break;
+        case Field::SmoothScroll:
+            toggleSmoothScroll();
+            break;
+        case Field::Back:
+            exitToMenu();
+            break;
+    }
+}
+
+void OptionsState::toggleFullscreen() {
+    bool nextState = !isFullscreen();
+    if (ctx.applyFullscreen) {
+        ctx.applyFullscreen(nextState);
+    }
+    if (ctx.fullscreenFlag) {
+        *ctx.fullscreenFlag = nextState;
+    }
+    // Save setting
+    Settings::instance().setFullscreen(nextState);
+    Settings::instance().save();
+}
+
+void OptionsState::toggleMusic() {
+    Audio::instance().toggleMute();
+    // If muted, music is disabled. If not muted, music is enabled.
+    // Note: Audio::instance().isMuted() returns true if muted.
+    // But Audio class doesn't expose isMuted directly in header usually?
+    // Let's assume toggleMute toggles internal state.
+    // We can track it via ctx.musicEnabled if it's synced.
+    
+    bool enabled = true;
+    if (ctx.musicEnabled) {
+        *ctx.musicEnabled = !*ctx.musicEnabled;
+        enabled = *ctx.musicEnabled;
+    }
+    
+    // Save setting
+    Settings::instance().setMusicEnabled(enabled);
+    Settings::instance().save();
+}
+
+void OptionsState::toggleSoundFx() {
+    bool next = !SoundEffectManager::instance().isEnabled();
+    SoundEffectManager::instance().setEnabled(next);
+    // Save setting
+    Settings::instance().setSoundEnabled(next);
+    Settings::instance().save();
+}
+
+void OptionsState::toggleSmoothScroll() {
+    bool next = !Settings::instance().isSmoothScrollEnabled();
+    Settings::instance().setSmoothScrollEnabled(next);
+    Settings::instance().save();
+}
+
+void OptionsState::exitToMenu() {
+    // Try a graceful fade transition if available, but always ensure we
+    // return to the Menu state so the UI is responsive to the user's action.
+    if (ctx.requestFadeTransition) {
+        ctx.requestFadeTransition(AppState::Menu);
+    }
+    if (ctx.stateManager) {
+        ctx.stateManager->setState(AppState::Menu);
+    }
+}
+
+bool OptionsState::isFullscreen() const {
+    if (ctx.queryFullscreen) {
+        return ctx.queryFullscreen();
+    }
+    return ctx.fullscreenFlag ? *ctx.fullscreenFlag : false;
+}
+
+bool OptionsState::isMusicEnabled() const {
+    if (ctx.musicEnabled) {
+        return *ctx.musicEnabled;
+    }
+    return true;
+}
+
+bool OptionsState::isSoundFxEnabled() const {
+    return SoundEffectManager::instance().isEnabled();
+}
+
+bool OptionsState::isSmoothScrollEnabled() const {
+    return Settings::instance().isSmoothScrollEnabled();
+}
diff --git a/src/states/OptionsState.h b/src/states/OptionsState.h
new file mode 100644
index 0000000..2ae8638
--- /dev/null
+++ b/src/states/OptionsState.h
@@ -0,0 +1,39 @@
+#pragma once
+
+#include "State.h"
+
+class OptionsState : public State {
+public:
+    explicit OptionsState(StateContext& ctx);
+    void onEnter() override;
+    void onExit() override;
+    void handleEvent(const SDL_Event& e) override;
+    void update(double frameMs) override;
+    void render(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) override;
+
+private:
+    enum class Field : int {
+        Fullscreen = 0,
+        Music = 1,
+        SoundFx = 2,
+        SmoothScroll = 3,
+        Back = 4
+    };
+
+    static constexpr int MAX_NAME_LENGTH = 12;
+    Field m_selectedField = Field::Fullscreen;
+    double m_cursorTimer = 0.0;
+    bool m_cursorVisible = true;
+
+    void moveSelection(int delta);
+    void activateSelection();
+    void toggleFullscreen();
+    void toggleMusic();
+    void toggleSoundFx();
+    void toggleSmoothScroll();
+    void exitToMenu();
+    bool isFullscreen() const;
+    bool isMusicEnabled() const;
+    bool isSoundFxEnabled() const;
+    bool isSmoothScrollEnabled() const;
+};
diff --git a/src/states/PlayingState.cpp b/src/states/PlayingState.cpp
index 91086d7..bd2daeb 100644
--- a/src/states/PlayingState.cpp
+++ b/src/states/PlayingState.cpp
@@ -1,37 +1,344 @@
 #include "PlayingState.h"
-#include "gameplay/Game.h"
-#include "gameplay/LineEffect.h"
-#include "persistence/Scores.h"
+#include "../core/state/StateManager.h"
+#include "../gameplay/core/Game.h"
+#include "../gameplay/coop/CoopGame.h"
+#include "../gameplay/effects/LineEffect.h"
+#include "../persistence/Scores.h"
+#include "../audio/Audio.h"
+#include "../audio/SoundEffect.h"
+#include "../graphics/Font.h"
+#include "../graphics/renderers/GameRenderer.h"
+#include "../core/Settings.h"
+#include "../core/Config.h"
+#include "../network/CoopNetButtons.h"
 #include <SDL3/SDL.h>
 
+// File-scope transport/spawn detection state
+static uint64_t s_lastPieceSequence = 0;
+static bool s_pendingTransport = false;
+
 PlayingState::PlayingState(StateContext& ctx) : State(ctx) {}
 
 void PlayingState::onEnter() {
-    // Nothing yet; main still owns game creation
+    SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[PLAYING] Entering Playing state");
+    // Initialize the game based on mode: endless/cooperate use chosen start level, challenge keeps its run state
+    if (ctx.game) {
+        if (ctx.game->getMode() == GameMode::Endless || ctx.game->getMode() == GameMode::Cooperate) {
+            if (ctx.startLevelSelection) {
+                SDL_LogInfo(SDL_LOG_CATEGORY_APPLICATION, "[PLAYING] Resetting game with level %d", *ctx.startLevelSelection);
+                const bool coopNetActive = (ctx.game->getMode() == GameMode::Cooperate) && ctx.coopNetEnabled && ctx.coopNetSession;
+
+                // For network co-op, MenuState already performed a deterministic reset using the negotiated seed.
+                // Re-resetting here would overwrite it (and will desync).
+                if (!coopNetActive) {
+                    ctx.game->reset(*ctx.startLevelSelection);
+                    if (ctx.game->getMode() == GameMode::Cooperate && ctx.coopGame) {
+                        ctx.coopGame->reset(*ctx.startLevelSelection);
+                    }
+                } else {
+                    ctx.game->setPaused(false);
+                }
+            }
+        } else {
+            // Challenge run is prepared before entering; ensure gameplay is unpaused
+            ctx.game->setPaused(false);
+        }
+
+        s_lastPieceSequence = ctx.game->getCurrentPieceSequence();
+        s_pendingTransport = false;
+    }
+    
+    // (transport state is tracked at file scope)
 }
 
 void PlayingState::onExit() {
+    if (m_renderTarget) {
+        SDL_DestroyTexture(m_renderTarget);
+        m_renderTarget = nullptr;
+    }
+
+    // If we are leaving gameplay during network co-op, tear down the session so
+    // hosting/joining again works without restarting the app.
+    if (ctx.coopNetSession) {
+        ctx.coopNetSession->shutdown();
+        ctx.coopNetSession.reset();
+    }
+    ctx.coopNetEnabled = false;
+    ctx.coopNetStalled = false;
+    ctx.coopNetDesyncDetected = false;
+    ctx.coopNetTick = 0;
+    ctx.coopNetPendingButtons = 0;
 }
 
 void PlayingState::handleEvent(const SDL_Event& e) {
-    // We keep short-circuited input here; main still handles mouse UI
-    if (e.type == SDL_EVENT_KEY_DOWN && !e.key.repeat) {
-        if (!ctx.game) return;
-        // Pause toggle (P)
-        if (e.key.scancode == SDL_SCANCODE_P) {
-            bool paused = ctx.game->isPaused();
-            ctx.game->setPaused(!paused);
-        }
-        // Other gameplay keys already registered by main's Playing handler for now
+    if (!ctx.game) return;
+
+    // If a transport animation is active, ignore gameplay input entirely.
+    if (GameRenderer::isTransportActive()) {
+        return;
     }
+
+    const bool coopActive = ctx.game->getMode() == GameMode::Cooperate && ctx.coopGame;
+
+    auto setExitSelection = [&](int idx) {
+        if (ctx.exitPopupSelectedButton) {
+            *ctx.exitPopupSelectedButton = idx;
+        }
+    };
+    auto getExitSelection = [&]() -> int {
+        return ctx.exitPopupSelectedButton ? *ctx.exitPopupSelectedButton : 1;
+    };
+
+    if (e.type != SDL_EVENT_KEY_DOWN || e.key.repeat) {
+        return;
+    }
+
+    // If exit-confirm popup is visible, handle shortcuts here
+    if (ctx.showExitConfirmPopup && *ctx.showExitConfirmPopup) {
+        // Navigate between YES (0) and NO (1) buttons
+        if (e.key.scancode == SDL_SCANCODE_LEFT || e.key.scancode == SDL_SCANCODE_UP) {
+            setExitSelection(0);
+            return;
+        }
+        if (e.key.scancode == SDL_SCANCODE_RIGHT || e.key.scancode == SDL_SCANCODE_DOWN) {
+            setExitSelection(1);
+            return;
+        }
+
+        // Activate selected button with Enter or Space
+        if (e.key.scancode == SDL_SCANCODE_RETURN || e.key.scancode == SDL_SCANCODE_KP_ENTER || e.key.scancode == SDL_SCANCODE_SPACE) {
+            const bool confirmExit = (getExitSelection() == 0);
+            *ctx.showExitConfirmPopup = false;
+            if (confirmExit) {
+                // YES - Reset game and return to menu
+                if (ctx.startLevelSelection) {
+                    ctx.game->reset(*ctx.startLevelSelection);
+                } else {
+                    ctx.game->reset(0);
+                }
+                ctx.game->setPaused(false);
+                if (ctx.stateManager) ctx.stateManager->setState(AppState::Menu);
+            } else {
+                // NO - Just close popup and resume
+                ctx.game->setPaused(false);
+            }
+            return;
+        }
+        // Cancel with Esc (same as NO)
+        if (e.key.scancode == SDL_SCANCODE_ESCAPE) {
+            *ctx.showExitConfirmPopup = false;
+            ctx.game->setPaused(false);
+            setExitSelection(1);
+            return;
+        }
+        // While modal is open, suppress other gameplay keys
+        return;
+    }
+
+    // ESC key - open confirmation popup
+    if (e.key.scancode == SDL_SCANCODE_ESCAPE) {
+        if (ctx.showExitConfirmPopup) {
+            ctx.game->setPaused(true);
+            *ctx.showExitConfirmPopup = true;
+            setExitSelection(1); // Default to NO for safety
+        }
+        return;
+    }
+
+    // Debug: skip to next challenge level (B)
+    if (e.key.scancode == SDL_SCANCODE_B && ctx.game->getMode() == GameMode::Challenge) {
+        ctx.game->beginNextChallengeLevel();
+        // Cancel any countdown so play resumes immediately on the new level
+        if (ctx.gameplayCountdownActive) *ctx.gameplayCountdownActive = false;
+        if (ctx.menuPlayCountdownArmed) *ctx.menuPlayCountdownArmed = false;
+        ctx.game->setPaused(false);
+        return;
+    }
+
+    // Pause toggle (P) - matches classic behavior; disabled during countdown
+    if (e.key.scancode == SDL_SCANCODE_P) {
+        // Network co-op uses lockstep; local pause would desync/stall the peer.
+        if (ctx.coopNetEnabled && ctx.coopNetSession) {
+            return;
+        }
+        const bool countdown = (ctx.gameplayCountdownActive && *ctx.gameplayCountdownActive) ||
+                               (ctx.menuPlayCountdownArmed && *ctx.menuPlayCountdownArmed);
+        if (!countdown) {
+            ctx.game->setPaused(!ctx.game->isPaused());
+        }
+        return;
+    }
+
+    // Tetris controls (only when not paused)
+    if (ctx.game->isPaused()) {
+        return;
+    }
+
+    if (coopActive && ctx.coopGame) {
+        // Network co-op: route one-shot actions into a pending bitmask for lockstep.
+        if (ctx.coopNetEnabled && ctx.coopNetSession) {
+            const bool localIsLeft = ctx.coopNetLocalIsLeft;
+            const SDL_Scancode sc = e.key.scancode;
+            if (localIsLeft) {
+                if (sc == SDL_SCANCODE_W) {
+                    ctx.coopNetPendingButtons |= coopnet::RotCW;
+                    return;
+                }
+                if (sc == SDL_SCANCODE_Q) {
+                    ctx.coopNetPendingButtons |= coopnet::RotCCW;
+                    return;
+                }
+                if (sc == SDL_SCANCODE_LSHIFT || sc == SDL_SCANCODE_E) {
+                    ctx.coopNetPendingButtons |= coopnet::HardDrop;
+                    return;
+                }
+                if (sc == SDL_SCANCODE_LCTRL) {
+                    ctx.coopNetPendingButtons |= coopnet::Hold;
+                    return;
+                }
+            } else {
+                if (sc == SDL_SCANCODE_UP) {
+                    const bool upIsCW = Settings::instance().isUpRotateClockwise();
+                    ctx.coopNetPendingButtons |= upIsCW ? coopnet::RotCW : coopnet::RotCCW;
+                    return;
+                }
+                if (sc == SDL_SCANCODE_RALT) {
+                    ctx.coopNetPendingButtons |= coopnet::RotCCW;
+                    return;
+                }
+                if (sc == SDL_SCANCODE_SPACE || sc == SDL_SCANCODE_RSHIFT) {
+                    ctx.coopNetPendingButtons |= coopnet::HardDrop;
+                    return;
+                }
+                if (sc == SDL_SCANCODE_RCTRL) {
+                    ctx.coopNetPendingButtons |= coopnet::Hold;
+                    return;
+                }
+            }
+            // If coopNet is active, suppress local co-op direct action keys.
+        }
+
+        const bool coopAIEnabled = (ctx.coopVsAI && *ctx.coopVsAI);
+
+        // Player 1 (left): when AI is enabled it controls the left side so
+        // ignore direct player input for the left board.
+        if (coopAIEnabled) {
+            // Left side controlled by AI; skip left-side input handling here.
+        } else {
+            // Player 1 manual controls (left side)
+            if (e.key.scancode == SDL_SCANCODE_W) {
+                ctx.coopGame->rotate(CoopGame::PlayerSide::Left, 1);
+                return;
+            }
+            if (e.key.scancode == SDL_SCANCODE_Q) {
+                ctx.coopGame->rotate(CoopGame::PlayerSide::Left, -1);
+                return;
+            }
+            // Hard drop (left): keep LSHIFT, also allow E for convenience.
+            if (e.key.scancode == SDL_SCANCODE_LSHIFT || e.key.scancode == SDL_SCANCODE_E) {
+                SoundEffectManager::instance().playSound("hard_drop", 0.7f);
+                ctx.coopGame->hardDrop(CoopGame::PlayerSide::Left);
+                return;
+            }
+            if (e.key.scancode == SDL_SCANCODE_LCTRL) {
+                ctx.coopGame->holdCurrent(CoopGame::PlayerSide::Left);
+                return;
+            }
+        }
+        if (e.key.scancode == SDL_SCANCODE_UP) {
+            bool upIsCW = Settings::instance().isUpRotateClockwise();
+            ctx.coopGame->rotate(CoopGame::PlayerSide::Right, upIsCW ? 1 : -1);
+            return;
+        }
+        if (e.key.scancode == SDL_SCANCODE_RALT) {
+            ctx.coopGame->rotate(CoopGame::PlayerSide::Right, -1);
+            return;
+        }
+        // Hard drop (right): SPACE is the primary key for arrow controls; keep RSHIFT as an alternate.
+        if (e.key.scancode == SDL_SCANCODE_SPACE || e.key.scancode == SDL_SCANCODE_RSHIFT) {
+            SoundEffectManager::instance().playSound("hard_drop", 0.7f);
+            ctx.coopGame->hardDrop(CoopGame::PlayerSide::Right);
+            if (coopAIEnabled) {
+                // Mirror human-initiated hard-drop to AI on left
+                ctx.coopGame->hardDrop(CoopGame::PlayerSide::Left);
+            }
+            return;
+        }
+        if (e.key.scancode == SDL_SCANCODE_RCTRL) {
+            ctx.coopGame->holdCurrent(CoopGame::PlayerSide::Right);
+            return;
+        }
+    } else {
+        // Single-player classic controls
+        // Hold / swap current piece (H)
+        if (e.key.scancode == SDL_SCANCODE_H) {
+            ctx.game->holdCurrent();
+            return;
+        }
+
+        // Rotation (still event-based for precise timing)
+        if (e.key.scancode == SDL_SCANCODE_UP) {
+            // Use user setting to determine whether UP rotates clockwise
+            bool upIsCW = Settings::instance().isUpRotateClockwise();
+            ctx.game->rotate(upIsCW ? 1 : -1);
+            return;
+        }
+        if (e.key.scancode == SDL_SCANCODE_X) {
+            // Toggle the mapping so UP will rotate in the opposite direction
+            bool current = Settings::instance().isUpRotateClockwise();
+            Settings::instance().setUpRotateClockwise(!current);
+            Settings::instance().save();
+            // Play a subtle feedback sound if available
+            SoundEffectManager::instance().playSound("menu_toggle", 0.6f);
+            return;
+        }
+
+        // Hard drop (space)
+        if (e.key.scancode == SDL_SCANCODE_SPACE) {
+            SoundEffectManager::instance().playSound("hard_drop", 0.7f);
+            ctx.game->hardDrop();
+            return;
+        }
+    }
+
+    // Note: Left/Right movement and soft drop are now handled by
+    // ApplicationManager's update handler for proper DAS/ARR timing
 }
 
 void PlayingState::update(double frameMs) {
     if (!ctx.game) return;
-    // forward per-frame gameplay updates (gravity, elapsed)
+
+    const bool coopActive = ctx.game->getMode() == GameMode::Cooperate && ctx.coopGame;
+
+    if (coopActive) {
+        // Visual effects only; gravity and movement handled from ApplicationManager for coop
+        ctx.coopGame->updateVisualEffects(frameMs);
+        // Update line clear effect for coop mode as well (renderer starts the effect)
+        if (ctx.lineEffect && ctx.lineEffect->isActive()) {
+            if (ctx.lineEffect->update(frameMs / 1000.0f)) {
+                ctx.coopGame->clearCompletedLines();
+            }
+        }
+        return;
+    }
+
+    ctx.game->updateVisualEffects(frameMs);
+    // If a transport animation is active, pause gameplay updates and ignore inputs
+    if (GameRenderer::isTransportActive()) {
+        // Keep visual effects updating but skip gravity/timers while transport runs
+        return;
+    }
+
+    // forward per-frame gameplay updates (gravity, line effects)
     if (!ctx.game->isPaused()) {
         ctx.game->tickGravity(frameMs);
-        ctx.game->addElapsed(frameMs);
+        // Detect spawn event (sequence increment) and request transport effect
+        uint64_t seq = ctx.game->getCurrentPieceSequence();
+        if (seq != s_lastPieceSequence) {
+            s_lastPieceSequence = seq;
+            s_pendingTransport = true;
+        }
+        ctx.game->updateElapsedTime();
 
         if (ctx.lineEffect && ctx.lineEffect->isActive()) {
             if (ctx.lineEffect->update(frameMs / 1000.0f)) {
@@ -39,14 +346,251 @@ void PlayingState::update(double frameMs) {
             }
         }
     }
-
-    if (ctx.game->isGameOver()) {
-        if (ctx.scores) ctx.scores->submit(ctx.game->score(), ctx.game->lines(), ctx.game->level(), ctx.game->elapsed());
-        // Transitioning state must be done by the owner (main via StateManager hooks). We can't set state here.
-    }
+    
+    // Note: Game over detection and state transition is now handled by ApplicationManager
 }
 
 void PlayingState::render(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) {
     if (!ctx.game) return;
-    // Rendering kept in main for now to avoid changing many layout calculations in one change.
+
+    const bool coopActive = ctx.game->getMode() == GameMode::Cooperate && ctx.coopGame;
+
+    // Get current window size
+    int winW = 0, winH = 0;
+    SDL_GetRenderOutputSize(renderer, &winW, &winH);
+
+    // Create or resize render target if needed
+    if (!m_renderTarget || m_targetW != winW || m_targetH != winH) {
+        if (m_renderTarget) SDL_DestroyTexture(m_renderTarget);
+        m_renderTarget = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_RGBA8888, SDL_TEXTUREACCESS_TARGET, winW, winH);
+        SDL_SetTextureBlendMode(m_renderTarget, SDL_BLENDMODE_BLEND);
+        m_targetW = winW;
+        m_targetH = winH;
+    }
+
+    bool paused = ctx.game->isPaused();
+    bool exitPopup = ctx.showExitConfirmPopup && *ctx.showExitConfirmPopup;
+    bool countdown = (ctx.gameplayCountdownActive && *ctx.gameplayCountdownActive) || 
+                     (ctx.menuPlayCountdownArmed && *ctx.menuPlayCountdownArmed);
+    bool challengeClearFx = ctx.challengeClearFxActive && *ctx.challengeClearFxActive;
+    const std::vector<int>* challengeClearOrder = ctx.challengeClearFxOrder;
+    double challengeClearElapsed = ctx.challengeClearFxElapsedMs ? *ctx.challengeClearFxElapsedMs : 0.0;
+    double challengeClearDuration = ctx.challengeClearFxDurationMs ? *ctx.challengeClearFxDurationMs : 0.0;
+    
+    // Only blur if paused AND NOT in countdown (and not exit popup, though exit popup implies paused)
+    // Actually, exit popup should probably still blur/dim.
+    // But countdown should definitely NOT show the "PAUSED" overlay.
+    bool shouldBlur = paused && !countdown && !challengeClearFx;
+
+    auto renderNetOverlay = [&]() {
+        if (!coopActive || !ctx.coopNetEnabled || !ctx.pixelFont) return;
+        if (!ctx.coopNetDesyncDetected && !ctx.coopNetStalled) return;
+
+        const char* text = ctx.coopNetDesyncDetected ? "NET: DESYNC" : "NET: STALLED";
+        SDL_Color textColor = ctx.coopNetDesyncDetected ? SDL_Color{255, 230, 180, 255} : SDL_Color{255, 224, 130, 255};
+        float scale = 0.75f;
+        int tw = 0, th = 0;
+        ctx.pixelFont->measure(text, scale, tw, th);
+
+        SDL_BlendMode prevBlend = SDL_BLENDMODE_NONE;
+        SDL_GetRenderDrawBlendMode(renderer, &prevBlend);
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+
+        const float pad = 8.0f;
+        const float x = 18.0f;
+        const float y = 14.0f;
+        SDL_FRect bg{ x - pad, y - pad, (float)tw + pad * 2.0f, (float)th + pad * 2.0f };
+        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 160);
+        SDL_RenderFillRect(renderer, &bg);
+        ctx.pixelFont->draw(renderer, x, y, text, scale, textColor);
+
+        SDL_SetRenderDrawBlendMode(renderer, prevBlend);
+    };
+
+    if (shouldBlur && m_renderTarget) {
+        // Render game to texture
+        SDL_SetRenderTarget(renderer, m_renderTarget);
+        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 0);
+        SDL_RenderClear(renderer);
+
+        // Apply the same view/scale as main.cpp uses
+        SDL_SetRenderViewport(renderer, &logicalVP);
+        SDL_SetRenderScale(renderer, logicalScale, logicalScale);
+
+        // Render game content (no overlays)
+        // If a transport effect was requested due to a recent spawn, start it here so
+        // the renderer has the correct layout and renderer context to compute coords.
+        if (!coopActive && s_pendingTransport) {
+            GameRenderer::startTransportEffectForGame(ctx.game, ctx.blocksTex, 1200.0f, 1000.0f, logicalScale, (float)winW, (float)winH, 0.4f);
+            s_pendingTransport = false;
+        }
+
+        if (coopActive && ctx.coopGame) {
+            GameRenderer::renderCoopPlayingState(
+                renderer,
+                ctx.coopGame,
+                ctx.pixelFont,
+                ctx.lineEffect,
+                ctx.blocksTex,
+                ctx.statisticsPanelTex,
+                ctx.scorePanelTex,
+                ctx.nextPanelTex,
+                ctx.holdPanelTex,
+                paused,
+                1200.0f,
+                1000.0f,
+                logicalScale,
+                (float)winW,
+                (float)winH
+            );
+        } else {
+            GameRenderer::renderPlayingState(
+                renderer,
+                ctx.game,
+                ctx.pixelFont,
+                ctx.lineEffect,
+                ctx.blocksTex,
+                ctx.asteroidsTex,
+                ctx.statisticsPanelTex,
+                ctx.scorePanelTex,
+                ctx.nextPanelTex,
+                ctx.holdPanelTex,
+                countdown,
+                1200.0f, // LOGICAL_W
+                1000.0f, // LOGICAL_H
+                logicalScale,
+                (float)winW,
+                (float)winH,
+                challengeClearFx,
+                challengeClearOrder,
+                challengeClearElapsed,
+                challengeClearDuration,
+                countdown ? nullptr : ctx.challengeStoryText,
+                countdown ? 0.0f : (ctx.challengeStoryAlpha ? *ctx.challengeStoryAlpha : 0.0f)
+            );
+        }
+
+        // Reset to screen
+        SDL_SetRenderTarget(renderer, nullptr);
+        
+        // Draw blurred texture
+        SDL_Rect oldVP;
+        SDL_GetRenderViewport(renderer, &oldVP);
+        float oldSX, oldSY;
+        SDL_GetRenderScale(renderer, &oldSX, &oldSY);
+        
+        SDL_SetRenderViewport(renderer, nullptr);
+        SDL_SetRenderScale(renderer, 1.0f, 1.0f);
+        
+        SDL_FRect dst{0, 0, (float)winW, (float)winH};
+        
+        // Blur pass (accumulate multiple offset copies)
+        int offset = Config::Visuals::PAUSE_BLUR_OFFSET;
+        int iterations = Config::Visuals::PAUSE_BLUR_ITERATIONS;
+        
+        // Base layer
+        SDL_SetTextureAlphaMod(m_renderTarget, Config::Visuals::PAUSE_BLUR_ALPHA); 
+        SDL_RenderTexture(renderer, m_renderTarget, nullptr, &dst);
+        
+        // Accumulate offset layers
+        for (int i = 1; i <= iterations; ++i) {
+            float currentOffset = (float)(offset * i);
+            
+            SDL_FRect d1 = dst; d1.x -= currentOffset; d1.y -= currentOffset;
+            SDL_RenderTexture(renderer, m_renderTarget, nullptr, &d1);
+            
+            SDL_FRect d2 = dst; d2.x += currentOffset; d2.y -= currentOffset;
+            SDL_RenderTexture(renderer, m_renderTarget, nullptr, &d2);
+            
+            SDL_FRect d3 = dst; d3.x -= currentOffset; d3.y += currentOffset;
+            SDL_RenderTexture(renderer, m_renderTarget, nullptr, &d3);
+            
+            SDL_FRect d4 = dst; d4.x += currentOffset; d4.y += currentOffset;
+            SDL_RenderTexture(renderer, m_renderTarget, nullptr, &d4);
+        }
+        
+        SDL_SetTextureAlphaMod(m_renderTarget, 255);
+
+        // Restore state
+        SDL_SetRenderViewport(renderer, &oldVP);
+        SDL_SetRenderScale(renderer, oldSX, oldSY);
+
+        // Net overlay (on top of blurred game, under pause/exit overlays)
+        renderNetOverlay();
+
+        // Draw overlays
+        if (exitPopup) {
+            GameRenderer::renderExitPopup(
+                renderer,
+                ctx.pixelFont,
+                (float)winW,
+                (float)winH,
+                logicalScale,
+                (ctx.exitPopupSelectedButton ? *ctx.exitPopupSelectedButton : 1)
+            );
+        } else {
+            GameRenderer::renderPauseOverlay(
+                renderer,
+                ctx.pixelFont,
+                (float)winW,
+                (float)winH,
+                logicalScale
+            );
+        }
+        
+    } else {
+        // Render normally directly to screen
+        if (!coopActive && s_pendingTransport) {
+            GameRenderer::startTransportEffectForGame(ctx.game, ctx.blocksTex, 1200.0f, 1000.0f, logicalScale, (float)winW, (float)winH, 0.4f);
+            s_pendingTransport = false;
+        }
+
+        if (coopActive && ctx.coopGame) {
+            GameRenderer::renderCoopPlayingState(
+                renderer,
+                ctx.coopGame,
+                ctx.pixelFont,
+                ctx.lineEffect,
+                ctx.blocksTex,
+                ctx.statisticsPanelTex,
+                ctx.scorePanelTex,
+                ctx.nextPanelTex,
+                ctx.holdPanelTex,
+                paused,
+                1200.0f,
+                1000.0f,
+                logicalScale,
+                (float)winW,
+                (float)winH
+            );
+
+            // Net overlay (on top of coop HUD)
+            renderNetOverlay();
+        } else {
+            GameRenderer::renderPlayingState(
+                renderer,
+                ctx.game,
+                ctx.pixelFont,
+                ctx.lineEffect,
+                ctx.blocksTex,
+                ctx.asteroidsTex,
+                ctx.statisticsPanelTex,
+                ctx.scorePanelTex,
+                ctx.nextPanelTex,
+                ctx.holdPanelTex,
+                countdown,
+                1200.0f,
+                1000.0f,
+                logicalScale,
+                (float)winW,
+                (float)winH,
+                challengeClearFx,
+                challengeClearOrder,
+                challengeClearElapsed,
+                challengeClearDuration,
+                countdown ? nullptr : ctx.challengeStoryText,
+                countdown ? 0.0f : (ctx.challengeStoryAlpha ? *ctx.challengeStoryAlpha : 0.0f)
+            );
+        }
+    }
 }
diff --git a/src/states/PlayingState.h b/src/states/PlayingState.h
index f8b177e..002411d 100644
--- a/src/states/PlayingState.h
+++ b/src/states/PlayingState.h
@@ -14,4 +14,9 @@ public:
 private:
     // Local per-state variables if needed
     bool localPaused = false;
+    
+    // Render target for blur effect
+    SDL_Texture* m_renderTarget = nullptr;
+    int m_targetW = 0;
+    int m_targetH = 0;
 };
diff --git a/src/states/State.h b/src/states/State.h
index f5a30dd..f8fc226 100644
--- a/src/states/State.h
+++ b/src/states/State.h
@@ -3,19 +3,32 @@
 #include <SDL3/SDL.h>
 #include <memory>
 #include <vector>
+#include <functional>
+#include <string>
+#include <array>
+#include <cstdint>
+
+#include "../network/NetSession.h"
 
 // Forward declarations for frequently used types
 class Game;
+class CoopGame;
 class ScoreManager;
 class Starfield;
 class Starfield3D;
 class FontAtlas;
 class LineEffect;
+enum class AppState;
+
+// Forward declare StateManager so StateContext can hold a pointer without
+// including the StateManager header here.
+class StateManager;
 
 // Shared context passed to states so they can access common resources
 struct StateContext {
     // Core subsystems (may be null if not available)
     Game* game = nullptr;
+    CoopGame* coopGame = nullptr;
     ScoreManager* scores = nullptr;
     Starfield* starfield = nullptr;
     Starfield3D* starfield3D = nullptr;
@@ -32,15 +45,78 @@ struct StateContext {
     // backgroundTex is set once in `main.cpp` and passed to states via this context.
     // Prefer reading this field instead of relying on any `extern SDL_Texture*` globals.
     SDL_Texture* blocksTex = nullptr;
+    SDL_Texture* asteroidsTex = nullptr;
+    SDL_Texture* scorePanelTex = nullptr;
+    SDL_Texture* statisticsPanelTex = nullptr;
+    SDL_Texture* nextPanelTex = nullptr;
+    SDL_Texture* holdPanelTex = nullptr; // Background for the HOLD preview
+    SDL_Texture* mainScreenTex = nullptr;
+    int mainScreenW = 0;
+    int mainScreenH = 0;
+    // Captured full-scene texture (used by menu for backdrop blur effects)
+    SDL_Texture* sceneTex = nullptr;
+    int sceneW = 0;
+    int sceneH = 0;
 
     // Audio / SFX - forward declared types in main
     // Pointers to booleans/flags used by multiple states
     bool* musicEnabled = nullptr;
+    bool* musicStarted = nullptr;
+    bool* musicLoaded = nullptr;
     int* startLevelSelection = nullptr;
     int* hoveredButton = nullptr;
     // Menu popups (exposed from main)
-    bool* showLevelPopup = nullptr;
     bool* showSettingsPopup = nullptr;
+    bool* showHelpOverlay = nullptr;
+    bool* showExitConfirmPopup = nullptr; // If true, show "Exit game?" confirmation while playing
+    int* exitPopupSelectedButton = nullptr; // 0 = YES, 1 = NO (default)
+    bool* gameplayCountdownActive = nullptr; // True if start-of-game countdown is running
+    bool* menuPlayCountdownArmed = nullptr; // True if we are transitioning to play and countdown is pending
+    bool* skipNextLevelUpJingle = nullptr; // Allows states to silence initial level-up SFX
+    // Challenge clear FX (slow block-by-block explosion before next level)
+    bool* challengeClearFxActive = nullptr;
+    double* challengeClearFxElapsedMs = nullptr;
+    double* challengeClearFxDurationMs = nullptr;
+    std::vector<int>* challengeClearFxOrder = nullptr;
+    std::string* challengeStoryText = nullptr; // Per-level briefing string for Challenge mode
+    int* challengeStoryLevel = nullptr; // Cached level for the current story line
+    float* challengeStoryAlpha = nullptr; // Current render alpha for story text fade
+    std::string* playerName = nullptr; // Shared player name buffer for highscores/options
+    // Coop setting: when true, COOPERATE runs with a computer-controlled right player.
+    bool* coopVsAI = nullptr;
+
+    // COOPERATE (network) --------------------------------------------------
+    // These fields are only meaningful when `coopNetEnabled` is true.
+    bool coopNetEnabled = false;
+    bool coopNetIsHost = false;
+    bool coopNetLocalIsLeft = true; // host = left (WASD), client = right (arrows)
+    uint32_t coopNetRngSeed = 0;
+    uint32_t coopNetTick = 0;
+    uint8_t coopNetPendingButtons = 0; // one-shot actions captured from keydown (rotate/hold/harddrop)
+    bool coopNetStalled = false; // true when waiting for remote input for current tick
+    bool coopNetDesyncDetected = false;
+    std::string coopNetUiStatusText; // transient status shown in menu after net abort
+    double coopNetUiStatusRemainingMs = 0.0;
+    std::unique_ptr<NetSession> coopNetSession;
+    bool* fullscreenFlag = nullptr; // Tracks current fullscreen state when available
+    std::function<void(bool)> applyFullscreen; // Allows states to request fullscreen changes
+    std::function<bool()> queryFullscreen; // Optional callback if fullscreenFlag is not reliable
+    std::function<void()> requestQuit; // Allows menu/option states to close the app gracefully
+    std::function<void()> startPlayTransition; // Optional fade hook when transitioning from menu to gameplay
+    std::function<void(AppState)> requestFadeTransition; // Generic state fade requests (menu/options/level)
+
+    // Startup transition fade (used for intro video -> main).
+    // When active, the app should render a black overlay with alpha = startupFadeAlpha*255.
+    bool* startupFadeActive = nullptr;
+    float* startupFadeAlpha = nullptr;
+    // Pointer to the application's StateManager so states can request transitions
+    StateManager* stateManager = nullptr;
+    // Optional explicit per-button coordinates (logical coordinates). When
+    // `menuButtonsExplicit` is true, MenuState will use these centers for
+    // rendering and hit tests. Values are in logical units (LOGICAL_W/H).
+    std::array<float, 4> menuButtonCX{};
+    std::array<float, 4> menuButtonCY{};
+    bool menuButtonsExplicit = false;
 };
 
 class State {
diff --git a/src/states/VideoState.cpp b/src/states/VideoState.cpp
new file mode 100644
index 0000000..10360dc
--- /dev/null
+++ b/src/states/VideoState.cpp
@@ -0,0 +1,389 @@
+// VideoState.cpp
+#include "VideoState.h"
+
+#include "../video/VideoPlayer.h"
+#include "../audio/Audio.h"
+#include "../core/state/StateManager.h"
+
+#include <SDL3/SDL.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstring>
+#include <cstdint>
+
+extern "C" {
+#include <libavformat/avformat.h>
+#include <libavcodec/avcodec.h>
+#include <libavutil/avutil.h>
+#include <libavutil/channel_layout.h>
+#include <libswresample/swresample.h>
+}
+
+VideoState::VideoState(StateContext& ctx)
+    : State(ctx)
+    , m_player(std::make_unique<VideoPlayer>())
+{
+}
+
+VideoState::~VideoState() {
+    onExit();
+}
+
+bool VideoState::begin(SDL_Renderer* renderer, const std::string& path) {
+    m_path = path;
+
+    if (!m_player) {
+        m_player = std::make_unique<VideoPlayer>();
+    }
+
+    if (!m_player->open(m_path, renderer)) {
+        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "[VideoState] Failed to open intro video: %s", m_path.c_str());
+        return false;
+    }
+
+    if (!m_player->decodeFirstFrame()) {
+        SDL_LogWarn(SDL_LOG_CATEGORY_APPLICATION, "[VideoState] Failed to decode first frame: %s", m_path.c_str());
+        // Still allow entering; we will likely render black.
+    }
+
+    return true;
+}
+
+void VideoState::onEnter() {
+    m_phase = Phase::FadeInFirstFrame;
+    m_phaseClockMs = 0.0;
+    m_blackOverlayAlpha = 1.0f;
+
+    m_audioDecoded.store(false);
+    m_audioDecodeFailed.store(false);
+    m_audioStarted = false;
+    m_audioPcm.clear();
+    m_audioRate = 44100;
+    m_audioChannels = 2;
+
+    // Decode audio in the background during fade-in.
+    m_audioThread = std::make_unique<std::jthread>([this](std::stop_token st) {
+        (void)st;
+        std::vector<int16_t> pcm;
+        int rate = 44100;
+        int channels = 2;
+
+        const bool ok = decodeAudioPcm16Stereo44100(m_path, pcm, rate, channels);
+        if (!ok) {
+            m_audioDecodeFailed.store(true);
+            m_audioDecoded.store(true, std::memory_order_release);
+            return;
+        }
+
+        // Transfer results.
+        m_audioRate = rate;
+        m_audioChannels = channels;
+        m_audioPcm = std::move(pcm);
+        m_audioDecoded.store(true, std::memory_order_release);
+    });
+}
+
+void VideoState::onExit() {
+    stopAudio();
+
+    if (m_audioThread) {
+        // Request stop and join.
+        m_audioThread.reset();
+    }
+}
+
+void VideoState::handleEvent(const SDL_Event& e) {
+    (void)e;
+}
+
+void VideoState::startAudioIfReady() {
+    if (m_audioStarted) return;
+    if (!m_audioDecoded.load(std::memory_order_acquire)) return;
+    if (m_audioDecodeFailed.load()) return;
+    if (m_audioPcm.empty()) return;
+
+    // Use the existing audio output path (same device as music/SFX).
+    Audio::instance().playSfx(m_audioPcm, m_audioChannels, m_audioRate, 1.0f);
+    m_audioStarted = true;
+}
+
+void VideoState::stopAudio() {
+    // We currently feed intro audio as an SFX buffer into the mixer.
+    // It will naturally end; no explicit stop is required.
+}
+
+void VideoState::update(double frameMs) {
+    switch (m_phase) {
+        case Phase::FadeInFirstFrame: {
+            m_phaseClockMs += frameMs;
+            const float t = (FADE_IN_MS > 0.0) ? float(std::clamp(m_phaseClockMs / FADE_IN_MS, 0.0, 1.0)) : 1.0f;
+            m_blackOverlayAlpha = 1.0f - t;
+
+            if (t >= 1.0f) {
+                m_phase = Phase::Playing;
+                m_phaseClockMs = 0.0;
+                if (m_player) {
+                    m_player->start();
+                }
+                startAudioIfReady();
+            }
+            break;
+        }
+        case Phase::Playing: {
+            startAudioIfReady();
+            if (m_player) {
+                m_player->update(frameMs);
+                if (m_player->isFinished()) {
+                    m_phase = Phase::FadeOutToBlack;
+                    m_phaseClockMs = 0.0;
+                    m_blackOverlayAlpha = 0.0f;
+                }
+            } else {
+                m_phase = Phase::FadeOutToBlack;
+                m_phaseClockMs = 0.0;
+                m_blackOverlayAlpha = 0.0f;
+            }
+            break;
+        }
+        case Phase::FadeOutToBlack: {
+            m_phaseClockMs += frameMs;
+            const float t = (FADE_OUT_MS > 0.0) ? float(std::clamp(m_phaseClockMs / FADE_OUT_MS, 0.0, 1.0)) : 1.0f;
+            m_blackOverlayAlpha = t;
+            if (t >= 1.0f) {
+                // Switch to MAIN (Menu) with a fade-in from black.
+                if (ctx.startupFadeAlpha) {
+                    *ctx.startupFadeAlpha = 1.0f;
+                }
+                if (ctx.startupFadeActive) {
+                    *ctx.startupFadeActive = true;
+                }
+                if (ctx.stateManager) {
+                    ctx.stateManager->setState(AppState::Menu);
+                }
+                m_phase = Phase::Done;
+            }
+            break;
+        }
+        case Phase::Done:
+        default:
+            break;
+     }
+ }
+
+ void VideoState::render(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) {
+    (void)logicalScale;
+    (void)logicalVP;
+
+    if (!renderer) return;
+
+    int winW = 0, winH = 0;
+    SDL_GetRenderOutputSize(renderer, &winW, &winH);
+
+    // Draw video fullscreen if available.
+    if (m_player && m_player->isTextureReady()) {
+        SDL_SetRenderViewport(renderer, nullptr);
+        SDL_SetRenderScale(renderer, 1.0f, 1.0f);
+        m_player->render(renderer, winW, winH);
+    } else {
+        SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
+        SDL_FRect r{0.f, 0.f, (float)winW, (float)winH};
+        SDL_RenderFillRect(renderer, &r);
+    }
+
+    // Apply fade overlay (black).
+    if (m_blackOverlayAlpha > 0.0f) {
+        const Uint8 a = (Uint8)std::clamp((int)std::lround(m_blackOverlayAlpha * 255.0f), 0, 255);
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+        SDL_SetRenderDrawColor(renderer, 0, 0, 0, a);
+        SDL_FRect full{0.f, 0.f, (float)winW, (float)winH};
+        SDL_RenderFillRect(renderer, &full);
+    }
+ }
+
+bool VideoState::decodeAudioPcm16Stereo44100(
+    const std::string& path,
+    std::vector<int16_t>& outPcm,
+    int& outRate,
+    int& outChannels
+) {
+    outPcm.clear();
+    outRate = 44100;
+    outChannels = 2;
+
+    AVFormatContext* fmt = nullptr;
+    if (avformat_open_input(&fmt, path.c_str(), nullptr, nullptr) != 0) {
+        return false;
+    }
+
+    if (avformat_find_stream_info(fmt, nullptr) < 0) {
+        avformat_close_input(&fmt);
+        return false;
+    }
+
+    int audioStream = -1;
+    for (unsigned i = 0; i < fmt->nb_streams; ++i) {
+        if (fmt->streams[i]->codecpar->codec_type == AVMEDIA_TYPE_AUDIO) {
+            audioStream = (int)i;
+            break;
+        }
+    }
+    if (audioStream < 0) {
+        avformat_close_input(&fmt);
+        return false;
+    }
+
+    AVCodecParameters* codecpar = fmt->streams[audioStream]->codecpar;
+    const AVCodec* codec = avcodec_find_decoder(codecpar->codec_id);
+    if (!codec) {
+        avformat_close_input(&fmt);
+        return false;
+    }
+
+    AVCodecContext* dec = avcodec_alloc_context3(codec);
+    if (!dec) {
+        avformat_close_input(&fmt);
+        return false;
+    }
+
+    if (avcodec_parameters_to_context(dec, codecpar) < 0) {
+        avcodec_free_context(&dec);
+        avformat_close_input(&fmt);
+        return false;
+    }
+
+    if (avcodec_open2(dec, codec, nullptr) < 0) {
+        avcodec_free_context(&dec);
+        avformat_close_input(&fmt);
+        return false;
+    }
+
+    AVChannelLayout outLayout{};
+    av_channel_layout_default(&outLayout, 2);
+
+    AVChannelLayout inLayout{};
+    if (av_channel_layout_copy(&inLayout, &dec->ch_layout) < 0 || inLayout.nb_channels <= 0) {
+        av_channel_layout_uninit(&inLayout);
+        av_channel_layout_default(&inLayout, 2);
+    }
+
+    SwrContext* swr = nullptr;
+    if (swr_alloc_set_opts2(
+            &swr,
+            &outLayout,
+            AV_SAMPLE_FMT_S16,
+            44100,
+            &inLayout,
+            dec->sample_fmt,
+            dec->sample_rate,
+            0,
+            nullptr
+        ) < 0) {
+        av_channel_layout_uninit(&inLayout);
+        av_channel_layout_uninit(&outLayout);
+        avcodec_free_context(&dec);
+        avformat_close_input(&fmt);
+        return false;
+    }
+
+    if (swr_init(swr) < 0) {
+        swr_free(&swr);
+        av_channel_layout_uninit(&inLayout);
+        av_channel_layout_uninit(&outLayout);
+        avcodec_free_context(&dec);
+        avformat_close_input(&fmt);
+        return false;
+    }
+
+    AVPacket* pkt = av_packet_alloc();
+    AVFrame* frame = av_frame_alloc();
+    if (!pkt || !frame) {
+        if (pkt) av_packet_free(&pkt);
+        if (frame) av_frame_free(&frame);
+        swr_free(&swr);
+        av_channel_layout_uninit(&inLayout);
+        av_channel_layout_uninit(&outLayout);
+        avcodec_free_context(&dec);
+        avformat_close_input(&fmt);
+        return false;
+    }
+
+    const int outRateConst = 44100;
+    const int outCh = 2;
+
+    while (av_read_frame(fmt, pkt) >= 0) {
+        if (pkt->stream_index != audioStream) {
+            av_packet_unref(pkt);
+            continue;
+        }
+
+        if (avcodec_send_packet(dec, pkt) < 0) {
+            av_packet_unref(pkt);
+            continue;
+        }
+        av_packet_unref(pkt);
+
+        while (true) {
+            const int rr = avcodec_receive_frame(dec, frame);
+            if (rr == AVERROR(EAGAIN) || rr == AVERROR_EOF) {
+                break;
+            }
+            if (rr < 0) {
+                break;
+            }
+
+            const int64_t delay = swr_get_delay(swr, dec->sample_rate);
+            const int dstNbSamples = (int)av_rescale_rnd(delay + frame->nb_samples, outRateConst, dec->sample_rate, AV_ROUND_UP);
+
+            std::vector<uint8_t> outBytes;
+            outBytes.resize((size_t)dstNbSamples * (size_t)outCh * sizeof(int16_t));
+
+            uint8_t* outData[1] = { outBytes.data() };
+            const uint8_t** inData = (const uint8_t**)frame->data;
+
+            const int converted = swr_convert(swr, outData, dstNbSamples, inData, frame->nb_samples);
+            if (converted > 0) {
+                const size_t samplesOut = (size_t)converted * (size_t)outCh;
+                const int16_t* asS16 = (const int16_t*)outBytes.data();
+                const size_t oldSize = outPcm.size();
+                outPcm.resize(oldSize + samplesOut);
+                std::memcpy(outPcm.data() + oldSize, asS16, samplesOut * sizeof(int16_t));
+            }
+
+            av_frame_unref(frame);
+        }
+    }
+
+    // Flush decoder
+    avcodec_send_packet(dec, nullptr);
+    while (avcodec_receive_frame(dec, frame) >= 0) {
+        const int64_t delay = swr_get_delay(swr, dec->sample_rate);
+        const int dstNbSamples = (int)av_rescale_rnd(delay + frame->nb_samples, outRateConst, dec->sample_rate, AV_ROUND_UP);
+        std::vector<uint8_t> outBytes;
+        outBytes.resize((size_t)dstNbSamples * (size_t)outCh * sizeof(int16_t));
+        uint8_t* outData[1] = { outBytes.data() };
+        const uint8_t** inData = (const uint8_t**)frame->data;
+        const int converted = swr_convert(swr, outData, dstNbSamples, inData, frame->nb_samples);
+        if (converted > 0) {
+            const size_t samplesOut = (size_t)converted * (size_t)outCh;
+            const int16_t* asS16 = (const int16_t*)outBytes.data();
+            const size_t oldSize = outPcm.size();
+            outPcm.resize(oldSize + samplesOut);
+            std::memcpy(outPcm.data() + oldSize, asS16, samplesOut * sizeof(int16_t));
+        }
+        av_frame_unref(frame);
+    }
+
+    av_frame_free(&frame);
+    av_packet_free(&pkt);
+    swr_free(&swr);
+    av_channel_layout_uninit(&inLayout);
+    av_channel_layout_uninit(&outLayout);
+    avcodec_free_context(&dec);
+    avformat_close_input(&fmt);
+
+    outRate = outRateConst;
+    outChannels = outCh;
+
+    return !outPcm.empty();
+}
diff --git a/src/states/VideoState.h b/src/states/VideoState.h
new file mode 100644
index 0000000..f6a4642
--- /dev/null
+++ b/src/states/VideoState.h
@@ -0,0 +1,67 @@
+// VideoState.h
+#pragma once
+
+#include "State.h"
+
+#include <atomic>
+#include <memory>
+#include <string>
+#include <thread>
+#include <vector>
+
+class VideoPlayer;
+
+class VideoState : public State {
+public:
+    explicit VideoState(StateContext& ctx);
+    ~VideoState() override;
+
+    void onEnter() override;
+    void onExit() override;
+    void handleEvent(const SDL_Event& e) override;
+    void update(double frameMs) override;
+    void render(SDL_Renderer* renderer, float logicalScale, SDL_Rect logicalVP) override;
+
+    // Called from the App's on-enter hook so we can create textures.
+    bool begin(SDL_Renderer* renderer, const std::string& path);
+
+private:
+    enum class Phase {
+        FadeInFirstFrame,
+        Playing,
+        FadeOutToBlack,
+        Done
+    };
+
+    void startAudioIfReady();
+    void stopAudio();
+
+    static bool decodeAudioPcm16Stereo44100(
+        const std::string& path,
+        std::vector<int16_t>& outPcm,
+        int& outRate,
+        int& outChannels
+    );
+
+    std::unique_ptr<VideoPlayer> m_player;
+    std::string m_path;
+
+    Phase m_phase = Phase::FadeInFirstFrame;
+    double m_phaseClockMs = 0.0;
+
+    static constexpr double FADE_IN_MS = 900.0;
+    static constexpr double FADE_OUT_MS = 450.0;
+
+    // Audio decoding runs in the background while we fade in.
+    std::atomic<bool> m_audioDecoded{false};
+    std::atomic<bool> m_audioDecodeFailed{false};
+    std::vector<int16_t> m_audioPcm;
+    int m_audioRate = 44100;
+    int m_audioChannels = 2;
+    bool m_audioStarted = false;
+
+    std::unique_ptr<std::jthread> m_audioThread;
+
+    // Render-time overlay alpha (0..1) for fade stages.
+    float m_blackOverlayAlpha = 1.0f;
+};
diff --git a/src/ui/BottomMenu.cpp b/src/ui/BottomMenu.cpp
new file mode 100644
index 0000000..fa7b3cb
--- /dev/null
+++ b/src/ui/BottomMenu.cpp
@@ -0,0 +1,144 @@
+#include "ui/BottomMenu.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdio>
+
+#include "graphics/renderers/UIRenderer.h"
+#include "graphics/Font.h"
+
+namespace ui {
+
+static bool pointInRect(const SDL_FRect& r, float x, float y) {
+    return x >= r.x && x <= (r.x + r.w) && y >= r.y && y <= (r.y + r.h);
+}
+
+BottomMenu buildBottomMenu(const MenuLayoutParams& params, int startLevel, bool coopVsAI) {
+    BottomMenu menu{};
+
+    auto rects = computeMenuButtonRects(params);
+
+    char levelBtnText[32];
+    std::snprintf(levelBtnText, sizeof(levelBtnText), "LEVEL %d", startLevel);
+
+    menu.buttons[0] = Button{ BottomMenuItem::Play, rects[0], "PLAY", false };
+    // Always show a neutral "COOPERATE" label (remove per-mode suffixes)
+    menu.buttons[1] = Button{ BottomMenuItem::Cooperate, rects[1], "COOPERATE", false };
+    menu.buttons[2] = Button{ BottomMenuItem::Challenge, rects[2], "CHALLENGE", false };
+    menu.buttons[3] = Button{ BottomMenuItem::Level, rects[3], levelBtnText, true };
+    menu.buttons[4] = Button{ BottomMenuItem::Options, rects[4], "OPTIONS", true };
+    menu.buttons[5] = Button{ BottomMenuItem::Help, rects[5], "HELP", true };
+    menu.buttons[6] = Button{ BottomMenuItem::About, rects[6], "ABOUT", true };
+    menu.buttons[7] = Button{ BottomMenuItem::Exit, rects[7], "EXIT", true };
+
+    return menu;
+}
+
+void renderBottomMenu(SDL_Renderer* renderer,
+                      FontAtlas* font,
+                      const BottomMenu& menu,
+                      int hoveredIndex,
+                      int selectedIndex,
+                      double baseAlphaMul,
+                      double flashAddMul) {
+    if (!renderer || !font) return;
+
+    const double baseMul = std::clamp(baseAlphaMul, 0.0, 1.0);
+    const double flashMul = flashAddMul;
+
+    const int focusIndex = (hoveredIndex != -1) ? hoveredIndex : selectedIndex;
+
+    for (int i = 0; i < MENU_BTN_COUNT; ++i) {
+        const Button& b = menu.buttons[i];
+        const SDL_FRect& r = b.rect;
+
+        float cx = r.x + r.w * 0.5f;
+        float cy = r.y + r.h * 0.5f;
+
+        bool isHovered = (hoveredIndex == i);
+        bool isSelected = (selectedIndex == i);
+
+        // Requested behavior: flash only the PLAY button, and only when it's the active/focused item.
+        const bool playIsActive = (i == 0) && (focusIndex == 0);
+        const double aMul = std::clamp(baseMul + (playIsActive ? flashMul : 0.0), 0.0, 1.0);
+
+        if (!b.textOnly) {
+            const bool isPlay = (i == 0);
+            const bool isCoop = (i == 1);
+            const bool isChallenge = (i == 2);
+            SDL_Color bgCol{ 18, 22, 28, static_cast<Uint8>(std::round(180.0 * aMul)) };
+            SDL_Color bdCol{ 255, 200, 70, static_cast<Uint8>(std::round(220.0 * aMul)) };
+            if (isCoop) {
+                // Cooperative mode gets a cyan/magenta accent to separate from Endless/Challenge
+                bgCol = SDL_Color{ 22, 30, 40, static_cast<Uint8>(std::round(190.0 * aMul)) };
+                bdCol = SDL_Color{ 160, 210, 255, static_cast<Uint8>(std::round(230.0 * aMul)) };
+            } else if (isChallenge) {
+                // Give Challenge a teal accent to distinguish from Play
+                bgCol = SDL_Color{ 18, 36, 36, static_cast<Uint8>(std::round(190.0 * aMul)) };
+                bdCol = SDL_Color{ 120, 255, 220, static_cast<Uint8>(std::round(230.0 * aMul)) };
+            }
+            UIRenderer::drawButton(renderer, font, cx, cy, r.w, r.h,
+                                   b.label, isHovered, isSelected,
+                                   bgCol, bdCol, false, nullptr);
+        } else {
+            SDL_Color bgCol{ 20, 30, 42, static_cast<Uint8>(std::round(160.0 * aMul)) };
+            SDL_Color bdCol{ 120, 220, 255, static_cast<Uint8>(std::round(200.0 * aMul)) };
+            UIRenderer::drawButton(renderer, font, cx, cy, r.w, r.h,
+                                   b.label, isHovered, isSelected,
+                                   bgCol, bdCol, true, nullptr);
+        }
+    }
+
+    // '+' separators between the bottom HUD buttons (indices 3..last)
+    {
+        SDL_BlendMode prevBlend = SDL_BLENDMODE_NONE;
+        SDL_GetRenderDrawBlendMode(renderer, &prevBlend);
+        SDL_SetRenderDrawBlendMode(renderer, SDL_BLENDMODE_BLEND);
+        SDL_SetRenderDrawColor(renderer, 120, 220, 255, static_cast<Uint8>(std::round(180.0 * baseMul)));
+
+        const int firstSmall = 3;
+        const int lastSmall = MENU_BTN_COUNT - 1;
+        float y = menu.buttons[firstSmall].rect.y + menu.buttons[firstSmall].rect.h * 0.5f;
+        for (int i = firstSmall; i < lastSmall; ++i) {
+            float x = (menu.buttons[i].rect.x + menu.buttons[i].rect.w + menu.buttons[i + 1].rect.x) * 0.5f;
+            SDL_RenderLine(renderer, x - 4.0f, y, x + 4.0f, y);
+            SDL_RenderLine(renderer, x, y - 4.0f, x, y + 4.0f);
+        }
+
+        SDL_SetRenderDrawBlendMode(renderer, prevBlend);
+    }
+}
+
+BottomMenuInputResult handleBottomMenuInput(const MenuLayoutParams& params,
+                                            const SDL_Event& e,
+                                            float x,
+                                            float y,
+                                            int prevHoveredIndex,
+                                            bool inputEnabled) {
+    BottomMenuInputResult result{};
+    result.hoveredIndex = prevHoveredIndex;
+
+    if (!inputEnabled) {
+        return result;
+    }
+
+    if (e.type == SDL_EVENT_MOUSE_MOTION) {
+        result.hoveredIndex = hitTestMenuButtons(params, x, y);
+        return result;
+    }
+
+    if (e.type == SDL_EVENT_MOUSE_BUTTON_DOWN && e.button.button == SDL_BUTTON_LEFT) {
+        auto rects = computeMenuButtonRects(params);
+        for (int i = 0; i < MENU_BTN_COUNT; ++i) {
+            if (pointInRect(rects[i], x, y)) {
+                result.activated = static_cast<BottomMenuItem>(i);
+                result.hoveredIndex = i;
+                break;
+            }
+        }
+    }
+
+    return result;
+}
+
+} // namespace ui
diff --git a/src/ui/BottomMenu.h b/src/ui/BottomMenu.h
new file mode 100644
index 0000000..6c0e3d7
--- /dev/null
+++ b/src/ui/BottomMenu.h
@@ -0,0 +1,66 @@
+#pragma once
+
+#include <array>
+#include <optional>
+#include <string>
+
+#include <SDL3/SDL.h>
+
+#include "ui/MenuLayout.h"
+#include "ui/UIConstants.h"
+
+struct FontAtlas;
+
+namespace ui {
+
+enum class BottomMenuItem : int {
+    Play = 0,
+    Cooperate = 1,
+    Challenge = 2,
+    Level = 3,
+    Options = 4,
+    Help = 5,
+    About = 6,
+    Exit = 7,
+};
+
+struct Button {
+    BottomMenuItem item{};
+    SDL_FRect rect{};
+    std::string label;
+    bool textOnly = true;
+};
+
+struct BottomMenu {
+    std::array<Button, MENU_BTN_COUNT> buttons{};
+};
+
+BottomMenu buildBottomMenu(const MenuLayoutParams& params, int startLevel, bool coopVsAI);
+
+// Draws the cockpit HUD menu (PLAY + 4 bottom items) using existing UIRenderer primitives.
+// hoveredIndex: -1..7
+// selectedIndex: 0..7 (keyboard selection)
+// alphaMul: 0..1 (overall group alpha)
+void renderBottomMenu(SDL_Renderer* renderer,
+                      FontAtlas* font,
+                      const BottomMenu& menu,
+                      int hoveredIndex,
+                      int selectedIndex,
+                      double baseAlphaMul,
+                      double flashAddMul);
+
+struct BottomMenuInputResult {
+    int hoveredIndex = -1;
+    std::optional<BottomMenuItem> activated;
+};
+
+// Interprets mouse motion/button input for the bottom menu.
+// Expects x/y in the same logical coordinate space used by MenuLayout (the current main loop already provides this).
+BottomMenuInputResult handleBottomMenuInput(const MenuLayoutParams& params,
+                                            const SDL_Event& e,
+                                            float x,
+                                            float y,
+                                            int prevHoveredIndex,
+                                            bool inputEnabled);
+
+} // namespace ui
diff --git a/src/ui/MenuLayout.cpp b/src/ui/MenuLayout.cpp
new file mode 100644
index 0000000..d79b758
--- /dev/null
+++ b/src/ui/MenuLayout.cpp
@@ -0,0 +1,89 @@
+#include "ui/MenuLayout.h"
+#include "ui/UIConstants.h"
+#include <algorithm>
+#include <array>
+#include <cmath>
+
+namespace ui {
+
+std::array<SDL_FRect, MENU_BTN_COUNT> computeMenuButtonRects(const MenuLayoutParams& p) {
+    const float LOGICAL_W = static_cast<float>(p.logicalW);
+    const float LOGICAL_H = static_cast<float>(p.logicalH);
+    float contentOffsetX = (p.winW - LOGICAL_W * p.logicalScale) * 0.5f / p.logicalScale;
+    float contentOffsetY = (p.winH - LOGICAL_H * p.logicalScale) * 0.5f / p.logicalScale;
+
+    // Cockpit HUD layout (matches main_screen art):
+    //  - Top row: PLAY / COOPERATE / CHALLENGE (big buttons)
+    //  - Second row: LEVEL / OPTIONS / HELP / ABOUT / EXIT (smaller buttons)
+    const float marginX = std::max(24.0f, LOGICAL_W * 0.03f);
+    const float marginBottom = std::max(26.0f, LOGICAL_H * 0.03f);
+    const float availableW = std::max(120.0f, LOGICAL_W - marginX * 2.0f);
+
+    float playW = std::min(220.0f, availableW * 0.25f);
+    float playH = 36.0f;
+    float bigGap = 28.0f;
+    float smallW = std::min(210.0f, availableW * 0.22f);
+    float smallH = 34.0f;
+    float smallSpacing = 26.0f;
+
+    // Scale down for narrow windows so nothing goes offscreen.
+    const int bigCount = 3;
+    const int smallCount = MENU_BTN_COUNT - bigCount;
+    float smallTotal = smallW * static_cast<float>(smallCount) + smallSpacing * static_cast<float>(std::max(smallCount - 1, 0));
+    float topRowTotal = playW * static_cast<float>(bigCount) + bigGap * static_cast<float>(bigCount - 1);
+    if (smallTotal > availableW || topRowTotal > availableW) {
+        float s = availableW / std::max(std::max(smallTotal, topRowTotal), 1.0f);
+        smallW *= s;
+        smallH *= s;
+        smallSpacing *= s;
+        playW *= s;
+        playH = std::max(26.0f, playH * std::max(0.75f, s));
+        bigGap *= s;
+        playW = std::min(playW, availableW);
+    }
+
+    float centerX = LOGICAL_W * 0.5f + contentOffsetX;
+    float bottomY = LOGICAL_H + contentOffsetY - marginBottom;
+    float smallCY = bottomY - smallH * 0.5f;
+    // Extra breathing room between PLAY and the bottom row (requested).
+    const float rowGap = 34.0f;
+    float playCY = smallCY - smallH * 0.5f - rowGap - playH * 0.5f;
+
+    std::array<SDL_FRect, MENU_BTN_COUNT> rects{};
+    // Top row big buttons (PLAY / COOPERATE / CHALLENGE)
+    float bigRowW = playW * static_cast<float>(bigCount) + bigGap * static_cast<float>(bigCount - 1);
+    float leftBig = centerX - bigRowW * 0.5f;
+    for (int i = 0; i < bigCount; ++i) {
+        float x = leftBig + i * (playW + bigGap);
+        rects[i] = SDL_FRect{ x, playCY - playH * 0.5f, playW, playH };
+    }
+
+    float rowW = smallW * static_cast<float>(smallCount) + smallSpacing * static_cast<float>(smallCount - 1);
+    float left = centerX - rowW * 0.5f;
+    float minLeft = contentOffsetX + marginX;
+    float maxRight = contentOffsetX + LOGICAL_W - marginX;
+    if (left < minLeft) left = minLeft;
+    if (left + rowW > maxRight) left = std::max(minLeft, maxRight - rowW);
+
+    for (int i = 0; i < smallCount; ++i) {
+        float x = left + i * (smallW + smallSpacing);
+        rects[i + bigCount] = SDL_FRect{ x, smallCY - smallH * 0.5f, smallW, smallH };
+    }
+    return rects;
+}
+
+int hitTestMenuButtons(const MenuLayoutParams& p, float localX, float localY) {
+    auto rects = computeMenuButtonRects(p);
+    for (int i = 0; i < MENU_BTN_COUNT; ++i) {
+        const auto &r = rects[i];
+        if (localX >= r.x && localX <= r.x + r.w && localY >= r.y && localY <= r.y + r.h)
+            return i;
+    }
+    return -1;
+}
+
+SDL_FRect settingsButtonRect(const MenuLayoutParams& p) {
+    return SDL_FRect{SETTINGS_BTN_X, SETTINGS_BTN_Y, SETTINGS_BTN_W, SETTINGS_BTN_H};
+}
+
+} // namespace ui
diff --git a/src/ui/MenuLayout.h b/src/ui/MenuLayout.h
new file mode 100644
index 0000000..e93036e
--- /dev/null
+++ b/src/ui/MenuLayout.h
@@ -0,0 +1,26 @@
+#pragma once
+#include <array>
+#include "ui/UIConstants.h"
+#include <SDL3/SDL.h>
+
+namespace ui {
+
+struct MenuLayoutParams {
+    int logicalW;
+    int logicalH;
+    int winW;
+    int winH;
+    float logicalScale;
+};
+
+// Compute menu button rects in logical coordinates (content-local)
+std::array<SDL_FRect, MENU_BTN_COUNT> computeMenuButtonRects(const MenuLayoutParams& p);
+
+// Hit test a point given in logical content-local coordinates against menu buttons
+// Returns index 0..(MENU_BTN_COUNT-1) or -1 if none
+int hitTestMenuButtons(const MenuLayoutParams& p, float localX, float localY);
+
+// Return settings button rect (logical coords)
+SDL_FRect settingsButtonRect(const MenuLayoutParams& p);
+
+} // namespace ui
diff --git a/src/ui/MenuWrappers.cpp b/src/ui/MenuWrappers.cpp
new file mode 100644
index 0000000..121c162
--- /dev/null
+++ b/src/ui/MenuWrappers.cpp
@@ -0,0 +1,88 @@
+// MenuWrappers.cpp - implementations of menu helper wrappers used by MenuState
+#include "MenuWrappers.h"
+#include "../core/GlobalState.h"
+#include "../graphics/Font.h"
+#include "app/Fireworks.h"
+#include <SDL3/SDL.h>
+
+using namespace Globals;
+
+static void drawRect(SDL_Renderer* renderer, float x, float y, float w, float h, SDL_Color c) {
+    SDL_SetRenderDrawColor(renderer, c.r, c.g, c.b, c.a);
+    SDL_FRect fr{ x, y, w, h };
+    SDL_RenderFillRect(renderer, &fr);
+}
+
+void menu_drawFireworks(SDL_Renderer* renderer, SDL_Texture* blocksTex) {
+    AppFireworks::draw(renderer, blocksTex);
+}
+
+void menu_updateFireworks(double frameMs) {
+    AppFireworks::update(frameMs);
+}
+
+double menu_getLogoAnimCounter() {
+    return AppFireworks::getLogoAnimCounter();
+}
+
+int menu_getHoveredButton() {
+    return AppFireworks::getHoveredButton();
+}
+
+void menu_drawEnhancedButton(SDL_Renderer* renderer, FontAtlas& font, float cx, float cy, float w, float h,
+                            const std::string& label, bool isHovered, bool isSelected) {
+    // Simple wrapper delegating to a basic draw implementation
+    SDL_Color bgColor = isSelected ? SDL_Color{100,190,255,255} : (isHovered ? SDL_Color{120,150,240,255} : SDL_Color{80,110,200,255});
+    float x = cx - w/2; float y = cy - h/2;
+    drawRect(renderer, x-2, y-2, w+4, h+4, SDL_Color{60,80,140,255});
+    drawRect(renderer, x, y, w, h, bgColor);
+    float textScale = 1.5f;
+    float textX = x + (w - label.length() * 12 * textScale) / 2;
+    float textY = y + (h - 20 * textScale) / 2;
+    font.draw(renderer, textX+2, textY+2, label, textScale, SDL_Color{0,0,0,180});
+    font.draw(renderer, textX, textY, label, textScale, SDL_Color{255,255,255,255});
+}
+
+void menu_drawMenuButton(SDL_Renderer* renderer, FontAtlas& font, float cx, float cy, float w, float h,
+                         const std::string& label, SDL_Color bgColor, SDL_Color borderColor) {
+    float x = cx - w/2; float y = cy - h/2;
+    drawRect(renderer, x-6, y-6, w+12, h+12, borderColor);
+    drawRect(renderer, x-4, y-4, w+8, h+8, SDL_Color{255,255,255,255});
+    drawRect(renderer, x, y, w, h, bgColor);
+    float textScale = 1.6f;
+    float approxCharW = 12.0f * textScale;
+    float textW = label.length() * approxCharW;
+    float tx = x + (w - textW) / 2.0f;
+    float ty = y + (h - 20.0f * textScale) / 2.0f;
+    font.draw(renderer, tx+2, ty+2, label, textScale, SDL_Color{0,0,0,180});
+    font.draw(renderer, tx, ty, label, textScale, SDL_Color{255,255,255,255});
+}
+
+void menu_drawLevelSelectionPopup(SDL_Renderer* renderer, FontAtlas& font, SDL_Texture* bgTex, int selectedLevel) {
+    (void)renderer; (void)font; (void)bgTex; (void)selectedLevel; // Not implemented here
+}
+
+void menu_drawSettingsPopup(SDL_Renderer* renderer, FontAtlas& font, bool musicEnabled) {
+    // Copy of main.cpp's drawSettingsPopup behavior adapted here
+    float popupW = 350, popupH = 260;
+    float popupX = (1200 - popupW) / 2;
+    float popupY = (1000 - popupH) / 2;
+    // Overlay
+    SDL_SetRenderDrawColor(renderer, 0, 0, 0, 128);
+    SDL_FRect overlay{0,0,1200,1000};
+    SDL_RenderFillRect(renderer, &overlay);
+    drawRect(renderer, popupX-4, popupY-4, popupW+8, popupH+8, SDL_Color{100,120,160,255});
+    drawRect(renderer, popupX, popupY, popupW, popupH, SDL_Color{40,50,70,255});
+    font.draw(renderer, popupX + 20, popupY + 20, "SETTINGS", 2.0f, SDL_Color{255,220,0,255});
+    font.draw(renderer, popupX + 20, popupY + 70, "MUSIC:", 1.5f, SDL_Color{255,255,255,255});
+    const char* musicStatus = musicEnabled ? "ON" : "OFF";
+    SDL_Color musicColor = musicEnabled ? SDL_Color{0,255,0,255} : SDL_Color{255,0,0,255};
+    font.draw(renderer, popupX + 120, popupY + 70, musicStatus, 1.5f, musicColor);
+    font.draw(renderer, popupX + 20, popupY + 100, "SOUND FX:", 1.5f, SDL_Color{255,255,255,255});
+    // Sound effect manager may be initialized elsewhere; show placeholder status for now
+    bool sfxOn = true;
+    font.draw(renderer, popupX + 140, popupY + 100, sfxOn ? "ON" : "OFF", 1.5f, sfxOn ? SDL_Color{0,255,0,255} : SDL_Color{255,0,0,255});
+    font.draw(renderer, popupX + 20, popupY + 150, "M = TOGGLE MUSIC", 1.0f, SDL_Color{200,200,220,255});
+    font.draw(renderer, popupX + 20, popupY + 170, "K = TOGGLE SOUND FX", 1.0f, SDL_Color{200,200,220,255});
+    font.draw(renderer, popupX + 20, popupY + 190, "ESC = CLOSE", 1.0f, SDL_Color{200,200,220,255});
+}
diff --git a/src/ui/UIConstants.h b/src/ui/UIConstants.h
new file mode 100644
index 0000000..88db763
--- /dev/null
+++ b/src/ui/UIConstants.h
@@ -0,0 +1,18 @@
+#pragma once
+
+static constexpr int MENU_BTN_COUNT = 8;
+static constexpr float MENU_SMALL_THRESHOLD = 700.0f;
+static constexpr float MENU_BTN_WIDTH_LARGE = 300.0f;
+static constexpr float MENU_BTN_WIDTH_SMALL_FACTOR = 0.4f; // multiplied by LOGICAL_W
+static constexpr float MENU_BTN_HEIGHT_LARGE = 70.0f;
+static constexpr float MENU_BTN_HEIGHT_SMALL = 60.0f;
+static constexpr float MENU_BTN_Y_OFFSET = 58.0f; // matches MenuState offset; slightly lower for windowed visibility
+static constexpr float MENU_BTN_SPACING_FACTOR_SMALL = 1.15f;
+static constexpr float MENU_BTN_SPACING_FACTOR_LARGE = 1.05f;
+static constexpr float MENU_BTN_CENTER = (MENU_BTN_COUNT - 1) / 2.0f;
+// Settings button metrics
+static constexpr float SETTINGS_BTN_OFFSET_X = 60.0f;
+static constexpr float SETTINGS_BTN_X = 1200 - SETTINGS_BTN_OFFSET_X; // LOGICAL_W is 1200
+static constexpr float SETTINGS_BTN_Y = 10.0f;
+static constexpr float SETTINGS_BTN_W = 50.0f;
+static constexpr float SETTINGS_BTN_H = 30.0f;
diff --git a/src/utils/ImagePathResolver.h b/src/utils/ImagePathResolver.h
new file mode 100644
index 0000000..75f72e8
--- /dev/null
+++ b/src/utils/ImagePathResolver.h
@@ -0,0 +1,156 @@
+#pragma once
+
+#include <array>
+#include <string>
+#include <filesystem>
+#include <initializer_list>
+
+#include <SDL3/SDL.h>
+
+namespace AssetPath {
+
+inline std::string& baseDirectory() {
+    static std::string base;
+    return base;
+}
+
+inline void setBasePath(std::string path) {
+    baseDirectory() = std::move(path);
+}
+
+inline bool tryOpenFile(const std::string& candidate) {
+    if (candidate.empty()) {
+        return false;
+    }
+    SDL_IOStream* file = SDL_IOFromFile(candidate.c_str(), "rb");
+    if (file) {
+        SDL_CloseIO(file);
+        return true;
+    }
+    return false;
+}
+
+inline bool fileExists(const std::string& path) {
+    if (path.empty()) {
+        return false;
+    }
+
+    if (tryOpenFile(path)) {
+        return true;
+    }
+
+    std::filesystem::path p(path);
+    if (!p.is_absolute()) {
+        const std::string& base = baseDirectory();
+        if (!base.empty()) {
+            std::filesystem::path combined = std::filesystem::path(base) / p;
+            if (tryOpenFile(combined.string())) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+inline std::string resolveWithBase(const std::string& path) {
+    if (path.empty()) {
+        return path;
+    }
+
+    if (tryOpenFile(path)) {
+        return path;
+    }
+
+    std::filesystem::path p(path);
+    if (!p.is_absolute()) {
+        const std::string& base = baseDirectory();
+        if (!base.empty()) {
+            std::filesystem::path combined = std::filesystem::path(base) / p;
+            std::string combinedStr = combined.string();
+            if (tryOpenFile(combinedStr)) {
+                return combinedStr;
+            }
+
+#if defined(__APPLE__)
+            // When running from a macOS bundle, SDL_GetBasePath may point at
+            // Contents/Resources while assets are in Contents/MacOS. Search that
+            // sibling too so Finder launches find the packaged assets.
+            std::filesystem::path basePath(base);
+            auto contentsDir = basePath.parent_path();
+            if (contentsDir.filename() == "Resources") {
+                auto macosDir = contentsDir.parent_path() / "MacOS";
+                std::filesystem::path alt = macosDir / p;
+                std::string altStr = alt.string();
+                if (tryOpenFile(altStr)) {
+                    return altStr;
+                }
+            }
+#endif
+        }
+    }
+    return path;
+}
+
+inline std::string resolveImagePath(const std::string& originalPath) {
+    if (originalPath.empty()) {
+        return originalPath;
+    }
+
+    if (auto resolved = resolveWithBase(originalPath); resolved != originalPath || fileExists(resolved)) {
+        return resolved;
+    }
+
+    const std::size_t dot = originalPath.find_last_of('.');
+    const std::string base = (dot == std::string::npos) ? originalPath : originalPath.substr(0, dot);
+
+    static constexpr std::array<const char*, 5> preferredExtensions{
+        ".jpg",
+        ".jpeg",
+        ".png",
+        ".webp",
+        ".bmp"
+    };
+
+    for (const char* ext : preferredExtensions) {
+        std::string candidate = base + ext;
+        if (candidate == originalPath) {
+            continue;
+        }
+        std::string resolvedCandidate = resolveWithBase(candidate);
+        if (resolvedCandidate != candidate || fileExists(resolvedCandidate)) {
+            return resolvedCandidate;
+        }
+    }
+
+    return originalPath;
+}
+
+inline std::string resolveWithExtensions(const std::string& basePathWithoutExt, std::initializer_list<const char*> extensions) {
+    for (const char* ext : extensions) {
+        std::string candidate = basePathWithoutExt + ext;
+        std::string resolved = resolveWithBase(candidate);
+        if (resolved != candidate || fileExists(resolved)) {
+            return resolved;
+        }
+    }
+    return {};
+}
+
+inline std::string resolveAudioPath(const std::string& basePathWithoutExt) {
+    static constexpr std::array<const char*, 4> AUDIO_EXTENSIONS = {
+        ".ogg",
+        ".flac",
+        ".wav",
+        ".mp3"
+    };
+    for (const char* ext : AUDIO_EXTENSIONS) {
+        std::string candidate = basePathWithoutExt + ext;
+        std::string resolved = resolveWithBase(candidate);
+        if (resolved != candidate || fileExists(resolved)) {
+            return resolved;
+        }
+    }
+    return {};
+}
+
+} // namespace AssetPath
diff --git a/src/video/VideoPlayer.cpp b/src/video/VideoPlayer.cpp
new file mode 100644
index 0000000..d97d587
--- /dev/null
+++ b/src/video/VideoPlayer.cpp
@@ -0,0 +1,172 @@
+#include "VideoPlayer.h"
+
+#include <iostream>
+#include <chrono>
+
+extern "C" {
+#include <libavformat/avformat.h>
+#include <libavcodec/avcodec.h>
+#include <libswscale/swscale.h>
+#include <libavutil/imgutils.h>
+}
+
+VideoPlayer::VideoPlayer() {}
+
+VideoPlayer::~VideoPlayer() {
+    if (m_texture) SDL_DestroyTexture(m_texture);
+    if (m_rgbBuffer) av_free(m_rgbBuffer);
+    if (m_frame) av_frame_free(&m_frame);
+    if (m_sws) sws_freeContext(m_sws);
+    if (m_dec) avcodec_free_context(&m_dec);
+    if (m_fmt) avformat_close_input(&m_fmt);
+}
+
+bool VideoPlayer::open(const std::string& path, SDL_Renderer* renderer) {
+    m_path = path;
+    avformat_network_init();
+    if (avformat_open_input(&m_fmt, path.c_str(), nullptr, nullptr) != 0) {
+        std::cerr << "VideoPlayer: failed to open " << path << "\n";
+        return false;
+    }
+    if (avformat_find_stream_info(m_fmt, nullptr) < 0) {
+        std::cerr << "VideoPlayer: failed to find stream info\n";
+        return false;
+    }
+    // Find video stream
+    m_videoStream = -1;
+    for (unsigned i = 0; i < m_fmt->nb_streams; ++i) {
+        if (m_fmt->streams[i]->codecpar->codec_type == AVMEDIA_TYPE_VIDEO) { m_videoStream = (int)i; break; }
+    }
+    if (m_videoStream < 0) { std::cerr << "VideoPlayer: no video stream\n"; return false; }
+
+    AVCodecParameters* codecpar = m_fmt->streams[m_videoStream]->codecpar;
+    const AVCodec* codec = avcodec_find_decoder(codecpar->codec_id);
+    if (!codec) { std::cerr << "VideoPlayer: decoder not found\n"; return false; }
+    m_dec = avcodec_alloc_context3(codec);
+    if (!m_dec) { std::cerr << "VideoPlayer: failed to alloc codec ctx\n"; return false; }
+    if (avcodec_parameters_to_context(m_dec, codecpar) < 0) { std::cerr << "VideoPlayer: param to ctx failed\n"; return false; }
+    if (avcodec_open2(m_dec, codec, nullptr) < 0) { std::cerr << "VideoPlayer: open codec failed\n"; return false; }
+
+    m_width = m_dec->width;
+    m_height = m_dec->height;
+    m_frame = av_frame_alloc();
+    m_sws = sws_getContext(m_width, m_height, m_dec->pix_fmt, m_width, m_height, AV_PIX_FMT_RGBA, SWS_BILINEAR, nullptr, nullptr, nullptr);
+    m_rgbBufferSize = av_image_get_buffer_size(AV_PIX_FMT_RGBA, m_width, m_height, 1);
+    m_rgbBuffer = (uint8_t*)av_malloc(m_rgbBufferSize);
+
+    if (renderer) {
+        m_texture = SDL_CreateTexture(renderer, SDL_PIXELFORMAT_RGBA32, SDL_TEXTUREACCESS_STREAMING, m_width, m_height);
+        if (!m_texture) { std::cerr << "VideoPlayer: failed create texture\n"; }
+    }
+
+    m_finished = false;
+    m_textureReady = false;
+    m_started = false;
+    m_frameAccumulatorMs = 0.0;
+
+    // Estimate frame interval.
+    m_frameIntervalMs = 33.333;
+    if (m_fmt && m_videoStream >= 0) {
+        AVRational fr = m_fmt->streams[m_videoStream]->avg_frame_rate;
+        if (fr.num > 0 && fr.den > 0) {
+            const double fps = av_q2d(fr);
+            if (fps > 1.0) {
+                m_frameIntervalMs = 1000.0 / fps;
+            }
+        }
+    }
+
+    // Seek to start
+    av_seek_frame(m_fmt, m_videoStream, 0, AVSEEK_FLAG_BACKWARD);
+    if (m_dec) avcodec_flush_buffers(m_dec);
+    return true;
+}
+
+bool VideoPlayer::decodeOneFrame() {
+    if (m_finished || !m_fmt) return false;
+
+    AVPacket* pkt = av_packet_alloc();
+    if (!pkt) {
+        m_finished = true;
+        return false;
+    }
+
+    int ret = 0;
+    while (av_read_frame(m_fmt, pkt) >= 0) {
+        if (pkt->stream_index == m_videoStream) {
+            ret = avcodec_send_packet(m_dec, pkt);
+            if (ret < 0) {
+                av_packet_unref(pkt);
+                continue;
+            }
+
+            while (ret >= 0) {
+                ret = avcodec_receive_frame(m_dec, m_frame);
+                if (ret == AVERROR(EAGAIN) || ret == AVERROR_EOF) break;
+                if (ret < 0) break;
+
+                uint8_t* dstData[4] = { m_rgbBuffer, nullptr, nullptr, nullptr };
+                int dstLinesize[4] = { m_width * 4, 0, 0, 0 };
+                sws_scale(m_sws, m_frame->data, m_frame->linesize, 0, m_height, dstData, dstLinesize);
+                m_textureReady = true;
+                if (m_texture) {
+                    SDL_UpdateTexture(m_texture, nullptr, m_rgbBuffer, dstLinesize[0]);
+                }
+                av_frame_unref(m_frame);
+
+                av_packet_unref(pkt);
+                av_packet_free(&pkt);
+                return true;
+            }
+        }
+        av_packet_unref(pkt);
+    }
+
+    av_packet_free(&pkt);
+    m_finished = true;
+    return false;
+}
+
+bool VideoPlayer::decodeFirstFrame() {
+    if (!m_fmt || m_finished) return false;
+    if (m_textureReady) return true;
+    // Ensure we are at the beginning.
+    av_seek_frame(m_fmt, m_videoStream, 0, AVSEEK_FLAG_BACKWARD);
+    if (m_dec) avcodec_flush_buffers(m_dec);
+    return decodeOneFrame();
+}
+
+void VideoPlayer::start() {
+    m_started = true;
+}
+
+bool VideoPlayer::update(double deltaMs) {
+    if (m_finished || !m_fmt) return false;
+    if (!m_started) return true;
+
+    m_frameAccumulatorMs += deltaMs;
+
+    // Decode at most a small burst per frame to avoid spiral-of-death.
+    int framesDecoded = 0;
+    const int maxFramesPerTick = 4;
+    while (m_frameAccumulatorMs >= m_frameIntervalMs && framesDecoded < maxFramesPerTick) {
+        m_frameAccumulatorMs -= m_frameIntervalMs;
+        if (!decodeOneFrame()) {
+            return false;
+        }
+        ++framesDecoded;
+    }
+    return !m_finished;
+}
+
+bool VideoPlayer::update() {
+    // Legacy behavior: decode exactly one frame.
+    return decodeOneFrame();
+}
+
+void VideoPlayer::render(SDL_Renderer* renderer, int winW, int winH) {
+    if (!m_textureReady || !m_texture || !renderer) return;
+    if (winW <= 0 || winH <= 0) return;
+    SDL_FRect dst = { 0.0f, 0.0f, (float)winW, (float)winH };
+    SDL_RenderTexture(renderer, m_texture, nullptr, &dst);
+}
diff --git a/src/video/VideoPlayer.h b/src/video/VideoPlayer.h
new file mode 100644
index 0000000..1be8e27
--- /dev/null
+++ b/src/video/VideoPlayer.h
@@ -0,0 +1,59 @@
+// Minimal FFmpeg-based video player (video) that decodes into an SDL texture.
+// Audio for the intro is currently handled outside this class.
+#pragma once
+
+#include <string>
+#include <SDL3/SDL.h>
+
+struct AVFormatContext;
+struct AVCodecContext;
+struct SwsContext;
+struct AVFrame;
+
+class VideoPlayer {
+public:
+    VideoPlayer();
+    ~VideoPlayer();
+
+    // Open video file and attach to SDL_Renderer for texture creation
+    bool open(const std::string& path, SDL_Renderer* renderer);
+    // Decode the first frame immediately so it can be used for fade-in.
+    bool decodeFirstFrame();
+
+    // Start time-based playback.
+    void start();
+
+    // Update playback using elapsed time in milliseconds.
+    // Returns false if finished or error.
+    bool update(double deltaMs);
+
+    // Compatibility: advance by one decoded frame.
+    bool update();
+
+    // Render video frame fullscreen to the given renderer using provided output size.
+    void render(SDL_Renderer* renderer, int winW, int winH);
+    bool isFinished() const { return m_finished; }
+    bool isTextureReady() const { return m_textureReady; }
+
+    double getFrameIntervalMs() const { return m_frameIntervalMs; }
+    bool isStarted() const { return m_started; }
+
+private:
+    bool decodeOneFrame();
+
+    AVFormatContext* m_fmt = nullptr;
+    AVCodecContext* m_dec = nullptr;
+    SwsContext* m_sws = nullptr;
+    AVFrame* m_frame = nullptr;
+    int m_videoStream = -1;
+    double m_frameIntervalMs = 33.333;
+    double m_frameAccumulatorMs = 0.0;
+    bool m_started = false;
+    int m_width = 0, m_height = 0;
+    SDL_Texture* m_texture = nullptr;
+    uint8_t* m_rgbBuffer = nullptr;
+    int m_rgbBufferSize = 0;
+    bool m_textureReady = false;
+    bool m_finished = true;
+    std::string m_path;
+};
diff --git a/vcpkg.json b/vcpkg.json
index 0de6b55..f93b924 100644
--- a/vcpkg.json
+++ b/vcpkg.json
@@ -1,7 +1,15 @@
 {
 	"dependencies": [
-	"sdl3",
-	"sdl3-ttf",
-	"catch2"
+		"sdl3",
+		"sdl3-ttf",
+		{
+			"name": "sdl3-image",
+			"features": ["jpeg", "png", "webp"]
+		},
+		"enet",
+		"catch2",
+		"cpr",
+		"nlohmann-json",
+		"ffmpeg"
 	]
-}
+}
\ No newline at end of file