refactor(room-fsm): timeline pur amb music_tail; fades INTRO/OUTRO via Transitions::FadeToBlack i sense callbacks de fi de música

source/game/scenes/game_scene.hpp

@@ -6,6 +6,7 @@
 #include <string>
 #include <vector>
 
+#include "core/rendering/transitions/fade_to_black.hpp"
 #include "core/scene/scene.hpp"
 #include "core/ui/ui_config.hpp"
 #include "game/debug_config.hpp"
@@ -136,14 +137,13 @@ class GameScene : public Scene {
     // caigut tots o si encara no estem dins la finestra (intro_completed_).
     void spawnDuePlayers();
 
-    // Hi ha un únic slot global de callback de fi de música a `Ja::Engine`.
-    // Cada estat (INTRO, OUTRO) ha de registrar el seu en entrar i pot
-    // sobreescriure'l amb el del següent estat. Aquests flags marquen
-    // si el callback corresponent ja ha disparat: són la frontera entre
-    // el thread d'audio (que invoca el callback dins `Engine::update`)
-    // i la lògica de transició (`updateRoomTransition`).
+    // Sentinel que marca el moment "música d'INTRO acabada" dins del
+    // timeline. Ja no ve d'un callback d'àudio: el setja el GameScene
+    // quan la FSM ha consumit l'última fase d'INTRO (la `music_tail`,
+    // calculada perquè coincideixi amb el final del .ogg). Habilita el
+    // tick de `intro_spawn_elapsed_ms_` i el spawn aeri escalonat dels
+    // slots actius.
     bool intro_completed_{false};
-    bool outro_music_ended_{false};
 
     // Mil·lisegons acumulats des del callback de fi de música d'INTRO,
     // per gatejar l'spawn aeri escalonat dels slots actius. P1 fa
@@ -236,6 +236,19 @@ class GameScene : public Scene {
     // reseteja a {0, 0}.
     RoomFsm::Transition transition_{};
 
+    // Fade-in d'INTRO: alpha 255 → 0 durant `intro_fade_in_ms`. Es comença
+    // a `enterRoomIntro` i tica cada frame; un cop finished, `render()`
+    // pinta alpha=0 (no-op) durant la resta del cicle.
+    Transitions::FadeToBlack intro_fade_;
+
+    // Fade-out d'OUTRO: alpha 0 → 255 durant `outro_fade_out_ms`, només
+    // arrencat quan la FSM entra a la fase corresponent (detectada via
+    // `outro_fade_started_`). Un cop finished, `render()` segueix
+    // pintant alpha=255: això cobreix de manera natural la fase final
+    // de `black_hold` sense lògica especial.
+    Transitions::FadeToBlack outro_fade_;
+    bool outro_fade_started_{false};
+
     // Píxels del fade negre i del text de la transició de sala.
     // Cridats des de `render()` entre el bloc d'actors i el HUD —
     // així marcador, notificacions i service menu queden per damunt.
@@ -283,11 +296,13 @@ class GameScene : public Scene {
     void advanceToNextRoom();
 
     // Inicia (o reinicia) el cicle d'entrada de sala: posa l'estat a
-    // ROOM_INTRO, reseteja `transition_` i `intro_completed_`, i comença
-    // la pista `room_intro.ogg` amb un callback de fi que dispararà
-    // `completeIntro()`. Si la càrrega de la música falla, dispara
-    // `completeIntro()` síncronament perquè la sala no quedi bloquejada.
-    // Idempotent quan ja s'estava a INTRO — útil per als salts debug.
+    // ROOM_INTRO, reseteja `transition_` i `intro_completed_`, comença
+    // la pista `room_intro.ogg` i resol el `intro_music_tail_ms` perquè
+    // el timeline acabi just al final del .ogg. Sense callback de fi de
+    // música — la transició a PLAYING la dispara `updateRoomTransition`
+    // quan la FSM consumeix l'última fase. Si la música no arrenca, la
+    // cua queda a 0 i l'INTRO acaba al final del text. Idempotent quan
+    // ja s'estava a INTRO — útil per als salts debug.
     void enterRoomIntro();
 
 #ifdef _DEBUG