refactor(core/audio): Audio owns the engine (migration)

Audio guanya un std::unique_ptr<Ja::Engine> engine_ com a membre privat.
Es construeix a initSDLAudio amb els defaults de Defaults::Audio; es
destrueix sol al ~Audio (cap Ja::quit() explícit).

Totes les crides Ja::funcióN(...) d'audio.cpp passen a engine_->funcióN:
  - playMusicInternal: crossfadeMusic/stopMusic/playMusic
  - pauseMusic, resumeMusic, stopMusic, fadeOutMusic
  - playSound x2, stopAllSounds
  - setSoundVolume, setMusicVolume
  - getMusicState (via instance->engine_ — és static però pot arribar-hi)

Les free functions forwarder del commit 2 (Ja::init/quit/update/playMusic/
pauseMusic/resumeMusic/stopMusic/fadeOutMusic/crossfadeMusic/
getMusicState/setMusicVolume/enableMusic i els equivalents de so) es
retiren del .hpp i del .cpp: ja no les crida ningú.

Queden com a free functions permanents (les usa Resource::Cache):
loadMusic (x2), loadSound, deleteMusic, deleteSound. Aquests darrers
consulten Engine::active() per notificar el motor abans d'alliberar.

audio.hpp forward-declara també `class Ja::Engine` perquè engine_ és
un std::unique_ptr i el dtor es defineix out-of-line al .cpp (= default)
— així no cal incloure jail_audio.hpp al header.

Els NOLINT(readability-make-member-function-const) d'audio.cpp es
mantenen amb raó actualitzada: std::unique_ptr::operator-> retorna T*
(no const T*), per tant clang-tidy veu un mètode d'Audio que podria ser
const encara que muti l'Engine via el punter. La mutació és real; el
NOLINT segueix sent honest.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

source/core/audio/audio.cpp

@@ -31,15 +31,14 @@ auto Audio::get() -> Audio* { return Audio::instance.get(); }
 Audio::Audio(const Config& config)
     : config_(config) { initSDLAudio(); }
 
-// Destructor
-Audio::~Audio() {
-    Ja::quit();
-}
+// Destructor: engine_ és std::unique_ptr, el seu dtor tanca el device SDL i
+// desregistra Ja::Engine::active_. Cap crida explícita necessària.
+Audio::~Audio() = default;
 
-// Mètode principal: l'estat de la música el manté Ja (única font de veritat),
-// per tant no cal cap sincronització aquí.
+// Mètode principal: l'estat de la música el manté el motor (única font de
+// veritat), per tant no cal cap sincronització aquí.
 void Audio::update() {
-    Ja::update();
+    if (instance && instance->engine_) { instance->engine_->update(); }
 }
 
 // Reprodueix la música per nom (amb crossfade opcional)
@@ -78,70 +77,70 @@ void Audio::playMusic(Ja::Music* music, const int loop, const int crossfade_ms)
 void Audio::playMusicInternal(Ja::Music* music, const int loop, const int crossfade_ms) {
     const bool CURRENTLY_PLAYING = (getMusicState() == MusicState::PLAYING);
     if (crossfade_ms > 0 && CURRENTLY_PLAYING) {
-        Ja::crossfadeMusic(music, crossfade_ms, loop);
+        engine_->crossfadeMusic(music, crossfade_ms, loop);
     } else {
         if (CURRENTLY_PLAYING) {
-            Ja::stopMusic();
+            engine_->stopMusic();
         }
-        Ja::playMusic(music, loop);
+        engine_->playMusic(music, loop);
     }
 
     music_.loop = (loop != 0);
 }
 
-// Pausa la música (l'estat el transiciona Ja::pauseMusic)
-// NOLINTNEXTLINE(readability-make-member-function-const) — muta Ja::current_music->state
+// Pausa la música (l'estat el transiciona Engine::pauseMusic)
+// NOLINTNEXTLINE(readability-make-member-function-const) — muta estat via engine_; unique_ptr::operator-> no propaga const
 void Audio::pauseMusic() {
     if (music_enabled_ && getMusicState() == MusicState::PLAYING) {
-        Ja::pauseMusic();
+        engine_->pauseMusic();
     }
 }
 
-// Continua la música pausada (l'estat el transiciona Ja::resumeMusic)
-// NOLINTNEXTLINE(readability-make-member-function-const) — muta Ja::current_music->state
+// Continua la música pausada (l'estat el transiciona Engine::resumeMusic)
+// NOLINTNEXTLINE(readability-make-member-function-const) — muta estat via engine_; unique_ptr::operator-> no propaga const
 void Audio::resumeMusic() {
     if (music_enabled_ && getMusicState() == MusicState::PAUSED) {
-        Ja::resumeMusic();
+        engine_->resumeMusic();
     }
 }
 
-// Detiene la música (l'estat el transiciona Ja::stopMusic)
-// NOLINTNEXTLINE(readability-make-member-function-const) — muta Ja::current_music/outgoing_music
+// Atura la música (l'estat el transiciona Engine::stopMusic)
+// NOLINTNEXTLINE(readability-make-member-function-const) — muta estat via engine_; unique_ptr::operator-> no propaga const
 void Audio::stopMusic() {
     if (music_enabled_) {
-        Ja::stopMusic();
+        engine_->stopMusic();
     }
 }
 
 // Reprodueix un so per nom
-// NOLINTNEXTLINE(readability-make-member-function-const) — muta globals de Ja::channels
+// NOLINTNEXTLINE(readability-make-member-function-const) — muta estat via engine_; unique_ptr::operator-> no propaga const
 void Audio::playSound(const std::string& name, Group group) {
     if (sound_enabled_) {
-        Ja::playSound(AudioResource::getSound(name), 0, static_cast<int>(group));
+        engine_->playSound(AudioResource::getSound(name), 0, static_cast<int>(group));
     }
 }
 
 // Reprodueix un so per punter directe
-// NOLINTNEXTLINE(readability-make-member-function-const) — muta globals de Ja::channels
+// NOLINTNEXTLINE(readability-make-member-function-const) — muta estat via engine_; unique_ptr::operator-> no propaga const
 void Audio::playSound(Ja::Sound* sound, Group group) {
     if (sound_enabled_ && sound != nullptr) {
-        Ja::playSound(sound, 0, static_cast<int>(group));
+        engine_->playSound(sound, 0, static_cast<int>(group));
     }
 }
 
 // Atura tots els sons
-// NOLINTNEXTLINE(readability-make-member-function-const) — muta globals de Ja::channels
+// NOLINTNEXTLINE(readability-make-member-function-const) — muta estat via engine_; unique_ptr::operator-> no propaga const
 void Audio::stopAllSounds() {
     if (sound_enabled_) {
-        Ja::stopChannel(-1);
+        engine_->stopChannel(-1);
     }
 }
 
 // Fa una fosa de sortida de la música
-// NOLINTNEXTLINE(readability-make-member-function-const) — muta Ja::outgoing_music/incoming_fade
+// NOLINTNEXTLINE(readability-make-member-function-const) — muta estat via engine_; unique_ptr::operator-> no propaga const
 void Audio::fadeOutMusic(int milliseconds) {
     if (music_enabled_ && getMusicState() == MusicState::PLAYING) {
-        Ja::fadeOutMusic(milliseconds);
+        engine_->fadeOutMusic(milliseconds);
     }
 }
 
@@ -149,7 +148,8 @@ void Audio::fadeOutMusic(int milliseconds) {
 // exposa Audio (INVALID/DISABLED de Ja col·lapsen a STOPPED — la capa d'usuari
 // només vol saber si està sonant, pausat o parat).
 auto Audio::getMusicState() -> MusicState {
-    switch (Ja::getMusicState()) {
+    if (!instance || !instance->engine_) { return MusicState::STOPPED; }
+    switch (instance->engine_->getMusicState()) {
         case Ja::MusicState::PLAYING:
             return MusicState::PLAYING;
         case Ja::MusicState::PAUSED:
@@ -171,15 +171,15 @@ auto Audio::effectiveVolume(float volume, bool channel_enabled) const -> float {
 }
 
 // Estableix el volum dels sons (float 0.0..1.0)
-// NOLINTNEXTLINE(readability-make-member-function-const) — muta Ja::sound_volume[] i canals actius
+// NOLINTNEXTLINE(readability-make-member-function-const) — muta estat via engine_; unique_ptr::operator-> no propaga const
 void Audio::setSoundVolume(float sound_volume, Group group) {
-    Ja::setSoundVolume(effectiveVolume(sound_volume, sound_enabled_), static_cast<int>(group));
+    engine_->setSoundVolume(effectiveVolume(sound_volume, sound_enabled_), static_cast<int>(group));
 }
 
 // Estableix el volum de la música (float 0.0..1.0)
-// NOLINTNEXTLINE(readability-make-member-function-const) — muta Ja::music_volume i stream actual
+// NOLINTNEXTLINE(readability-make-member-function-const) — muta estat via engine_; unique_ptr::operator-> no propaga const
 void Audio::setMusicVolume(float music_volume) {
-    Ja::setMusicVolume(effectiveVolume(music_volume, music_enabled_));
+    engine_->setMusicVolume(effectiveVolume(music_volume, music_enabled_));
 }
 
 // Aplica una nova configuració (substitueix la config cachejada i reaplica enables/volums)
@@ -212,14 +212,14 @@ void Audio::enableMusic(bool value) {
     setMusicVolume(config_.music_volume);
 }
 
-// Inicialitza SDL Audio
+// Inicialitza SDL Audio i el motor Ja::Engine owned.
 void Audio::initSDLAudio() {
     if (!SDL_Init(SDL_INIT_AUDIO)) {
         std::fprintf(stderr, "Audio: SDL_AUDIO could not initialize! SDL Error: %s\n", SDL_GetError());
-    } else {
-        Ja::init(Defaults::Audio::FREQUENCY, Defaults::Audio::FORMAT, Defaults::Audio::CHANNELS);
-        sound_enabled_ = config_.sound_enabled;
-        music_enabled_ = config_.music_enabled;
-        enable(config_.enabled);
+        return;
     }
+    engine_ = std::make_unique<Ja::Engine>(Defaults::Audio::FREQUENCY, Defaults::Audio::FORMAT, Defaults::Audio::CHANNELS);
+    sound_enabled_ = config_.sound_enabled;
+    music_enabled_ = config_.music_enabled;
+    enable(config_.enabled);
 }

source/core/audio/audio.hpp

@@ -6,9 +6,13 @@
 #include <string>   // Per a string
 #include <utility>  // Per a move
 
-// Forward-declares per no incloure core/audio/jail_audio.hpp al header (conté
-// l'engine complet de streaming amb stb_vorbis).
+// Forward-declares per no incloure core/audio/jail_audio.hpp al header. Els
+// tres símbols (Music/Sound per al punter que exposa la API i Engine per al
+// std::unique_ptr<Engine> membre) s'usen només per punter al header, així que
+// el forward-decl basta. El ~Audio() en .cpp veu la definició completa i
+// instancia correctament el dtor de l'unique_ptr.
 namespace Ja {
+    class Engine;
     struct Music;
     struct Sound;
 }  // namespace Ja
@@ -126,9 +130,10 @@ class Audio {
     // --- Variables membre ---
     static std::unique_ptr<Audio> instance;  // Instància única d'Audio
 
-    Config config_{};           // Configuració injectada (volums, enables)
-    Music music_;               // Estat de la música
-    bool enabled_{true};        // Estat general de l'àudio
-    bool sound_enabled_{true};  // Estat dels efectes de so
-    bool music_enabled_{true};  // Estat de la música
+    std::unique_ptr<Ja::Engine> engine_;  // Motor de baix nivell (owned); viu mentre Audio viu.
+    Config config_{};                     // Configuració injectada (volums, enables)
+    Music music_;                         // Estat de la música (nom + loop cachejats)
+    bool enabled_{true};                  // Estat general de l'àudio
+    bool sound_enabled_{true};            // Estat dels efectes de so
+    bool music_enabled_{true};            // Estat de la música
 };

source/core/audio/jail_audio.cpp

@@ -25,10 +25,6 @@ namespace Ja {
         // Umbral d'audio per davant del cursor de reproducció. Mantenim ≥ 0.5 s a
         // l'SDL_AudioStream per absorbir jitter de frame i evitar underruns.
         constexpr float MUSIC_LOW_WATER_SECONDS = 0.5F;
-
-        // Propietari únic de l'Engine que creen els forwarders Ja::init/quit.
-        // Al commit 3 això desapareix: Audio agafarà ownership directe.
-        std::unique_ptr<Engine> owned_engine;
     }  // namespace
 
     // --- Engine::active_ storage ---
@@ -453,93 +449,6 @@ namespace Ja {
         }
     }
 
-    // --- Free-function forwarders ---
-    // Mantenen l'API actual (Ja::update, Ja::playMusic, ...) contra el motor
-    // actiu. Al commit 3 Audio els substituirà per crides directes a engine_->
-    // i els forwarders de música/so desapareixeran; init/quit/update i els
-    // factories queden de forma permanent.
-
-    void init(const int freq, const SDL_AudioFormat format, const int num_channels) {
-        owned_engine = std::make_unique<Engine>(freq, format, num_channels);
-    }
-
-    void quit() {
-        owned_engine.reset();
-    }
-
-    void update() {
-        if (Engine* eng = Engine::active()) { eng->update(); }
-    }
-
-    void playMusic(Music* music, const int loop) {
-        if (Engine* eng = Engine::active()) { eng->playMusic(music, loop); }
-    }
-
-    void pauseMusic() {
-        if (Engine* eng = Engine::active()) { eng->pauseMusic(); }
-    }
-
-    void resumeMusic() {
-        if (Engine* eng = Engine::active()) { eng->resumeMusic(); }
-    }
-
-    void stopMusic() {
-        if (Engine* eng = Engine::active()) { eng->stopMusic(); }
-    }
-
-    void fadeOutMusic(const int milliseconds) {
-        if (Engine* eng = Engine::active()) { eng->fadeOutMusic(milliseconds); }
-    }
-
-    void crossfadeMusic(Music* music, const int crossfade_ms, const int loop) {
-        if (Engine* eng = Engine::active()) { eng->crossfadeMusic(music, crossfade_ms, loop); }
-    }
-
-    auto getMusicState() -> MusicState {
-        if (const Engine* eng = Engine::active()) { return eng->getMusicState(); }
-        return MusicState::INVALID;
-    }
-
-    auto setMusicVolume(float volume) -> float {
-        if (Engine* eng = Engine::active()) { return eng->setMusicVolume(volume); }
-        return 0.0F;
-    }
-
-    void enableMusic(const bool value) {
-        if (Engine* eng = Engine::active()) { eng->enableMusic(value); }
-    }
-
-    auto playSound(Sound* sound, const int loop, const int group) -> int {
-        if (Engine* eng = Engine::active()) { return eng->playSound(sound, loop, group); }
-        return -1;
-    }
-
-    auto playSoundOnChannel(Sound* sound, const int channel, const int loop, const int group) -> int {
-        if (Engine* eng = Engine::active()) { return eng->playSoundOnChannel(sound, channel, loop, group); }
-        return -1;
-    }
-
-    void pauseChannel(const int channel) {
-        if (Engine* eng = Engine::active()) { eng->pauseChannel(channel); }
-    }
-
-    void resumeChannel(const int channel) {
-        if (Engine* eng = Engine::active()) { eng->resumeChannel(channel); }
-    }
-
-    void stopChannel(const int channel) {
-        if (Engine* eng = Engine::active()) { eng->stopChannel(channel); }
-    }
-
-    auto setSoundVolume(float volume, const int group) -> float {
-        if (Engine* eng = Engine::active()) { return eng->setSoundVolume(volume, group); }
-        return 0.0F;
-    }
-
-    void enableSound(const bool value) {
-        if (Engine* eng = Engine::active()) { eng->enableSound(value); }
-    }
-
     // --- Factories i destructors (permanents) ---
 
     auto loadMusic(const Uint8* buffer, Uint32 length) -> Music* {

source/core/audio/jail_audio.hpp

@@ -178,35 +178,6 @@ namespace Ja {
         static Engine* active_;
     };
 
-    // --- Lifecycle forwarders ---
-    // Compat amb els callers actuals. Creen/destrueixen l'Engine únic via
-    // make_unique emmagatzemat al propi .cpp. Al commit següent Audio agafarà
-    // ownership directe i aquests forwarders desapareixeran per a la capa de
-    // control; els de música/so romanen només el temps de la migració.
-    void init(int freq, SDL_AudioFormat format, int num_channels);
-    void quit();
-    void update();
-
-    // --- Music API forwarders (temporal, eliminats al commit 3) ---
-    void playMusic(Music* music, int loop = -1);
-    void pauseMusic();
-    void resumeMusic();
-    void stopMusic();
-    void fadeOutMusic(int milliseconds);
-    void crossfadeMusic(Music* music, int crossfade_ms, int loop = -1);
-    [[nodiscard]] auto getMusicState() -> MusicState;
-    auto setMusicVolume(float volume) -> float;
-    void enableMusic(bool value);
-
-    // --- Sound API forwarders (temporal, eliminats al commit 3) ---
-    auto playSound(Sound* sound, int loop = 0, int group = 0) -> int;
-    auto playSoundOnChannel(Sound* sound, int channel, int loop = 0, int group = 0) -> int;
-    void pauseChannel(int channel);
-    void resumeChannel(int channel);
-    void stopChannel(int channel);
-    auto setSoundVolume(float volume, int group = -1) -> float;
-    void enableSound(bool value);
-
     // --- Factories i destructors (permanents) ---
     // No depenen de l'estat del motor: loadMusic/loadSound només construeixen
     // objectes, deleteMusic/deleteSound consulten Engine::active() per parar