idem

CLAUDE.md

@@ -44,24 +44,38 @@ make tidy-fix             # run clang-tidy with auto-fix
 
 ## Architecture
 
-### Singletons (core systems)
-- **Director** (`source/director.hpp`) — Application state machine, orchestrates scene transitions (Logo → Intro → Title → Game → Credits/HiScore → Title)
-- **Screen** (`source/screen.hpp`) — Window management, SDL3 GPU rendering pipeline, post-processing effects
-- **Resource** (`source/resource.hpp`) — Asset loading/caching with PRELOAD and LAZY_LOAD modes, reads from `resources.pack`
-- **Audio** (`source/audio.hpp`) — Music and SFX management
-- **Input** (`source/input.hpp`) — Keyboard and gamepad input handling
+### Source layout
+The `source/` tree is organised in the same style as the sibling projects `projecte_2026` and `jaildoctors_dilemma`:
 
-### Scenes (source/sections/)
+```
+source/
+├── core/           # engine: audio, input, locale, rendering (+ sdl3gpu, sprite), resources, system
+├── game/           # gameplay: entities, gameplay, scenes, ui, options
+├── utils/          # color, param, utils
+├── external/       # vendored third-party headers (json, fkyaml, stb_*)
+└── main.cpp
+```
+
+`#include` paths are absolute relative to `source/` (e.g. `#include "core/audio/audio.hpp"`, `#include "game/scenes/logo.hpp"`). The CMake build adds a single `-I${CMAKE_SOURCE_DIR}/source`.
+
+### Singletons (core systems)
+- **Director** (`source/core/system/director.hpp`) — Application state machine, orchestrates scene transitions (Logo → Intro → Title → Game → Credits/HiScore → Title)
+- **Screen** (`source/core/rendering/screen.hpp`) — Window management, SDL3 GPU rendering pipeline, post-processing effects
+- **Resource** (`source/core/resources/resource.hpp`) — Asset loading/caching with PRELOAD and LAZY_LOAD modes, reads from `resources.pack`
+- **Audio** (`source/core/audio/audio.hpp`) — Music and SFX management
+- **Input** (`source/core/input/input.hpp`) — Keyboard and gamepad input handling
+
+### Scenes (source/game/scenes/)
 Each scene is a self-contained class with update/render lifecycle. Scene flow is managed by Director.
 
 ### Entity Managers
-- `BalloonManager` / `BulletManager` — Object pool-based entity management
-- `Player` — Two-player support (player 1: keyboard, player 2: gamepad)
+- `BalloonManager` / `BulletManager` — Object pool-based entity management (`source/game/gameplay/`)
+- `Player` — Two-player support (player 1: keyboard, player 2: gamepad) (`source/game/entities/`)
 
 ### Rendering Pipeline
 - SDL3 GPU API (Vulkan/Metal/D3D12 backends)
 - SPIR-V shaders compiled offline from GLSL (`data/shaders/`) via `glslc`
-- Compiled shader headers embedded in `source/rendering/sdl3gpu/postfx_*_spv.h`
+- Compiled shader headers embedded in `source/core/rendering/sdl3gpu/postfx_*_spv.h`
 - macOS uses Metal (no SPIR-V compilation needed)
 
 ### Configuration
@@ -72,7 +86,9 @@ Each scene is a self-contained class with update/render lifecycle. Scene flow is
 - Gamepad mappings: `config/gamecontrollerdb.txt`
 
 ### External Libraries (header-only/vendored in source/external/)
-- nlohmann/json, fkyaml (YAML), stb_image, stb_vorbis, jail_audio
+- nlohmann/json, fkyaml (YAML), stb_image, stb_vorbis
+
+`jail_audio` lives in `source/core/audio/` and `gif.{hpp,cpp}` in `source/core/rendering/` — these are first-party, not third-party.
 
 ## Code Style