feat: resource.pack estil coffee_crisis — Fase 1 (pack + helper + eina pack_resources)

.gitignore

@@ -1,4 +1,5 @@
 aee
+aee.exe
 .DS_Store
 trick.ini
 .vscode/

CLAUDE.md

@@ -24,26 +24,74 @@ The executable is output to the project root. The `data/` folder must be in the
 
 ## Architecture
 
-### Golden Rule: Do Not Touch Gameplay
+### New Rules (Modernization Phase)
 
-The original game logic (gameplay, entities, map, scoring, collisions, animations) must remain untouched. All modernization work targets the presentation layer and infrastructure only. Any new feature must be implemented as an overlay on top of the existing game, never by modifying original gameplay code.
+The old "Golden Rule: Do Not Touch Gameplay" has been **revoked**. The original C-style code (jail engine + gameplay modules) is now a **modernization target**, not a sacred zone. The parallel-overlay approach has reached its ceiling: fades and cinematics are still blocking loops, audio relies on an async `SDL_AddTimer`, and the emulator-style game thread blocking at `publishFrame` is incompatible with an emscripten port.
+
+The five current objectives are:
+
+1. **Idiomatic C++**: RAII, `std::vector`/`std::string`/`std::optional`, classes with real constructors/destructors. No more raw `malloc/free` in structs.
+2. **Zero blocking events**: no `while (...) { poll; }`, no `SDL_Delay` inside gameplay, no `cv.wait()` in `publishFrame`. Every subsystem must be able to advance in a single tick call.
+3. **Time-based**: animations, cinematics and fades measured in milliseconds, not frames. `JG_ShouldUpdate()` as gameplay gate is on its way out.
+4. **Overlay integrated**: overlay stops being a post-game layer painted by Director — it becomes part of the same render pass the game tick produces.
+5. **SDL3 callbacks**: main loop handed over to `SDL_AppInit` / `SDL_AppIterate` / `SDL_AppEvent` / `SDL_AppQuit`, single-threaded, compatible with emscripten.
+
+**Iron rule: zero gameplay regressions.** Each phase of the modernization must leave the game playing identically — same feel, same timings, same collisions, same scoring. See [docs/scenes-migration-plan.md](docs/scenes-migration-plan.md) for the phased plan.
+
+### Migration Status (2026-04-16)
+
+**Completat.** Totes les fases del pla original (0–7) i la migració `scenes::` (Steps 0–10) estan fetes, ModuleGame és una `scenes::Scene` tick-based, el cooperative fiber s'ha eliminat, i el build emscripten/WASM arrenca i es publica a maverick.
+
+**Arquitectura actual**:
+- Un sol thread (Director). Main loop via SDL3 Callback API (`SDL_MAIN_USE_CALLBACKS`): `SDL_AppInit/Iterate/Event/Quit` a [main.cpp](source/main.cpp).
+- `Director::iterate()` posseeix l'estat d'escena (`current_scene_`, `game_state_`) i fa input → tick de l'escena → `JD8_Flip` (sense yield, només converteix `screen` → `pixel_data`) → overlay → present. Tot en línia recta, zero fibers, zero mutex.
+- Totes les escenes (inclòs `ModuleGame`) implementen `scenes::Scene` amb `onEnter/tick(delta_ms)/done/nextState`.
+- `ModuleSequence` (el vell dispatcher) eliminat. Despatxa via `game_state_ == 0` (gameplay → `ModuleGame`) o `game_state_ == 1` (cinemàtica → `SceneRegistry::tryCreate(num_piramide)`).
+
+**Escenes migrades** (totes registrades a `Director::init` via `SceneRegistry`):
+- `MortScene` (state 100) · `BannerScene` (2..5) · `MenuScene` (0) · `SlidesScene` (1, 7)
+- `CreditsScene` (8) · `SecretaScene` (6) · `IntroNewLogoScene` (255, `use_new_logo=true`)
+- `IntroScene` (255, `use_new_logo=false`) · `IntroSpritesScene` (sub-escena de les dues intros)
+
+**Files d'`Options::game` exposats per a tests ràpids** (persistits a `config.yaml`):
+`piramide_inicial`, `habitacio_inicial`, `vides`, `diamants_inicial`, `diners_inicial`, `use_new_logo`, `show_title_credits`.
+
+**La capa `scenes::`** ([source/scenes/](source/scenes/)): `scene.hpp` (interfície), `scene_registry.hpp/.cpp`, `timeline`, `sprite_mover`, `frame_animator`, `palette_fade`, `surface_handle`, `scene_utils` (`playMusic`). Pures tick-based, zero while, zero `JG_ShouldUpdate`.
+
+### Modernization Targets
+
+**Invariants to preserve** (touch these and you broke the game):
+- Gameplay feel, movement speed, enemy AI behavior
+- Collision detection, scoring, lives, level progression
+- Visible animation cadence (once translated to ms, must look identical)
+- Difficulty curves and cinematic timings
+- Cheat codes (`reviu`, `alone`, `obert`)
+- Original palettes, fades, music cues
+
+**Free to change** (internal representation):
+- Data structures (structs → classes with RAII)
+- Ownership (raw pointers → `std::unique_ptr`/`std::vector`/`std::string`)
+- Timing representation (frame counters → ms accumulators)
+- Threading model (game thread → single-threaded state machine)
+- Global state (the old `info::` namespace is now an `inline` singleton `info::ctx` of type `GameContext`; access is `info::ctx.X` instead of `info::X`. Can be reset with `info::ctx.reset()`)
+- API shapes of jail subsystems (as long as callers are updated consistently)
 
 ### Boundary: Original vs New Code
 
 | Path | Owner | Rule |
 |------|-------|------|
-| `source/core/jail/` | Original engine | **Do not modify** gameplay behavior |
-| `source/game/*.cpp/hpp` (except options/defines/defaults) | Original game | **Do not modify** |
+| `source/core/jail/` | Legacy engine, modernization target | Free to modify with care — preserve external behavior |
+| `source/game/*.cpp/hpp` | Legacy gameplay, modernization target | Free to modify with care — preserve gameplay invariants |
 | `source/core/rendering/` | New presentation layer | Free to modify |
 | `source/core/input/` | New input layer | Free to modify |
 | `source/utils/` | New utilities | Free to modify |
 | `source/game/options,defines,defaults` | New config system | Free to modify |
-| `data/*.gif, *.ogg` | Original assets | **Do not modify** |
+| `data/*.gif, *.ogg` | Original assets | **Do not modify** — assets remain untouchable |
 | `data/fonts/, data/ui/, data/shaders/` | New assets | Free to modify |
 
-### Original "Jail" Engine (`source/core/jail/`)
+### Legacy "Jail" Engine (`source/core/jail/`) — modernization target
 
-Flat C-style APIs (no classes), prefixed by subsystem. **Do not touch gameplay logic.**
+Flat C-style APIs (no classes), prefixed by subsystem. Being progressively converted to idiomatic C++ (see Phase 1 of the plan). External API names are kept stable during the transition to avoid churning call sites.
 
 - **JG** (`jgame`) — Game loop timing: init/finalize, fixed-timestep update via `JG_ShouldUpdate()`
 - **JD8** (`jdraw8`) — 8-bit paletted software renderer. 320x200 screen buffer (`JD8_Surface` = `Uint8*`), palette-indexed blitting with color-key transparency, fade effects. `JD8_Flip()` converts palette→ARGB and delegates to `Screen::present()`
@@ -53,7 +101,7 @@ Flat C-style APIs (no classes), prefixed by subsystem. **Do not touch gameplay l
 
 ### System Layer (`source/core/system/`)
 
-- **Director** (`director.hpp/cpp`) — **Orchestrator singleton**. Owns main thread. Launches game thread that runs `ModuleGame`/`ModuleSequence::Go()`. Emulator-style architecture: Director runs at ~60 FPS independently, polls SDL events, updates overlay, presents frames. Game thread blocks at `JD8_Flip()` → `Director::publishFrame()` until Director consumes the frame. Director is **non-blocking**: if no new frame is available, it re-presents the last known game frame with fresh overlay on top
+- **Director** (`director.hpp/cpp`) — **Orchestrator singleton**, únic thread del runtime. Posseeix l'estat d'escena (`current_scene_: unique_ptr<Scene>`, `game_state_`, `last_tick_ms_`) directament com a members. `iterate()` fa: poll events (via `SDL_AppEvent`) → input (Gamepad/KeyRemap/GlobalInputs/Mouse) → `JA_Update` → transició d'escena si `done()` → `scene->tick(delta_ms)` → `JD8_Flip` (converteix `screen` → `pixel_data`) → overlay → present → `SDL_Delay` al frame target. Dispatcher: `game_state_ == 0` → `new ModuleGame`, `game_state_ == 1` → `SceneRegistry::tryCreate(info::ctx.num_piramide)` (amb redirect `num_piramide == 6 && diners < 200 → 7` replicant el vell `ModuleSequence::Go`).
 
 ### Presentation Layer (`source/core/rendering/`)
 
@@ -101,7 +149,7 @@ Follows the pattern from `jaildoctors_dilemma`, persists to YAML:
 | F8 | Cycle shader presets |
 | F9 | Toggle stretch filter (nearest ↔ linear) |
 | F10 | Cycle render info (off → top → bottom → off) |
-| F11 | Toggle pause (blocks game thread at publishFrame + `JA_PauseMusic`/`JA_ResumeMusic`) |
+| F11 | Toggle pause (Director skips `scene->tick()` + `JA_PauseMusic`/`JA_ResumeMusic`) |
 | F12 | Toggle floating options menu |
 | ESC | Double-press to quit (with overlay notification) / close menu if open |
 | Backspace | Go up one menu level / close menu if at root |
@@ -109,30 +157,48 @@ Follows the pattern from `jaildoctors_dilemma`, persists to YAML:
 
 All key bindings are configurable via `Options::keys_gui` and stored in `config.yaml` (section `controls:` with SDL scancode names). Game movement keys (`Options::keys_game.up/down/left/right`) can be remapped via the CONTROLS submenu — the `KeyRemap` module mirrors custom physical keys to virtual standard scancodes so hardcoded game code keeps working.
 
-### Threading Model (Emulator Architecture)
+### Execution Model (Single-threaded, Scene-based)
+
+Zero threads, zero fibers, zero mutex. Main loop via SDL3 Callback API (`SDL_MAIN_USE_CALLBACKS`) a [main.cpp](source/main.cpp). Cada frame entra pel `SDL_AppIterate` → `Director::iterate()`:
 
 ```
-Main thread (Director)              Game thread (ModuleGame/Sequence::Go())
-────────────────────                ────────────────────────────────────
-loop at ~60 FPS {                   loop {
-  SDL_PollEvent()                     ... game logic ...
-  GlobalInputs, Mouse                 JD8_Flip():
-  if new_frame_available:               palette→ARGB in pixel_data
-    copy to game_frame                  publishFrame(pixel_data)  ⏸
-    signal → ────────────────────→      (blocks until Director consumes)
-  copy game_frame → present_buffer      ←──── signal_consumed
-  Overlay::render(present_buffer)       continue game loop
-  Screen::present(present_buffer)     }
-  SDL_Delay to hit 60fps
+SDL_AppIterate → Director::iterate() {
+  if (quit_requested_) { scene.reset(); return false; }
+  if (!context_initialized_) initGameContext();
+
+  Gamepad/KeyRemap/GlobalInputs/Mouse::update
+  JA_Update()                     ← audio pump
+
+  if (!paused_) {
+    if (scene && (scene->done() || JG_Quitting()))
+      game_state_ = scene->nextState(); scene.reset();
+    if (!scene) {
+      if (game_state_ == -1 || JG_Quitting()) return false;
+      scene = createNextScene();     ← ModuleGame o registry.tryCreate()
+      scene->onEnter();
     }
+    JI_Update()
+    scene->tick(now - last_tick_ms_)
+    JD8_Flip()                       ← converteix screen indexat → pixel_data
+    memcpy pixel_data → game_frame
+  }
+
+  memcpy game_frame → presentation_buffer
+  Overlay::render(presentation_buffer)
+  Screen::present(presentation_buffer)
+  SDL_Delay(frame_target - elapsed)
+}
+SDL_AppEvent → Director::handleEvent()    ← events lliurats un a un per SDL
+SDL_AppQuit  → Director::teardown()       ← Options::save + descàrrega ordenada
 ```
 
 **Key points:**
-- Director is NON-BLOCKING: if no new frame, re-presents the last one with fresh overlay
-- Double buffer: `game_frame` (untouched copy from game) + `presentation_buffer` (regenerated with overlay each frame)
-- Game thread pauses at `JD8_Flip()` waiting for Director — natural sync point
-- SDL events processed ONLY on main thread (SDL requirement)
-- `JI_Update()` no longer polls events — reads Director's state
+- `Director` posseeix `current_scene_`, `game_state_`, `last_tick_ms_`, `context_initialized_` com a members — abans vivien al stack del fiber.
+- `JD8_Flip()` només converteix paleta + `screen` a ARGB (`pixel_data`). Ja **no fa yield** — tot corre lineal.
+- `JG_ShouldUpdate()` encara existeix a `jgame.cpp` com a timing-gate per a `ModuleGame::Update()` (10 ms fix), però ja no fa yield. Cap caller fa spin-wait.
+- Pausa (F11) simplement salta el bloc de tick; overlay i present continuen, es re-presenta l'últim frame congelat.
+- Doble buffer (`game_frame` + `presentation_buffer`) es manté perquè el Director pot presentar múltiples frames per cada tick durant pausa; el cost (256 KB memcpy) és trivial a 320×200.
+- SDL3 Callback API compatible amb emscripten: el navegador posseeix el main loop i ens crida via `requestAnimationFrame`. Zero canvis de codi per a portabilitat.
 
 ### Rendering Pipeline (inside Screen::present)
 
@@ -162,6 +228,44 @@ JD8_Flip produces ABGR byte order: `0xFF000000 + R + (G<<8) + (B<<16)`. SDL text
 | `~/.config/jailgames/aee/postfx.yaml` | PostFX shader presets (6 defaults: CRT, NTSC, CURVED, SCANLINES, SUBTLE, CRT LIVE) |
 | `~/.config/jailgames/aee/crtpi.yaml` | CRT-Pi shader presets (4 defaults: DEFAULT, CURVED, SHARP, MINIMAL) |
 
+### Resource Pack (`source/core/resources/`) — **en construcció**
+
+Sistema d'empaquetat d'assets a l'estil `coffee_crisis_arcade_edition`. Genera un sol fitxer binari opac `resource.pack` que substitueix la carpeta `data/` als releases natius.
+
+**Format AEE1** (fidel a CCAE amb clau pròpia):
+```
+Header:   "AEE1" (4B) + version uint32 + resource_count uint32
+Index:    per recurs → filename_len uint32 + filename + offset uint64 + size uint64 + checksum uint32
+Payload:  data_size uint64 + bytes XOR-xifrats amb "AEE_RESOURCES__2026"
+```
+Checksum: djb2-like amb seed `0x12345678`. Càrrega full-to-RAM (sense mmap).
+
+**Fitxers**:
+- [source/core/resources/resource_pack.hpp/cpp](source/core/resources/) — classe `ResourcePack`: `loadPack`, `savePack`, `addFile`, `addDirectory`, `getResource(name) → std::vector<uint8_t>`, `hasResource`
+- [source/core/resources/resource_helper.hpp/cpp](source/core/resources/) — namespace `ResourceHelper`: `initializeResourceSystem(pack, enable_fallback)`, `loadFile(relative_path)`, `shutdownResourceSystem`. Prova el pack primer, cau a `file_getresourcefolder()+path` si el fallback està actiu.
+- [tools/pack_resources/pack_resources.cpp](tools/pack_resources/pack_resources.cpp) — eina standalone CLI: `pack_resources [input_dir=data] [output=resource.pack]` + `--list pack`.
+
+**Build**:
+- `make pack` compila l'eina (target `pack_resources` a `EXCLUDE_FROM_ALL` de [CMakeLists.txt](CMakeLists.txt)) i genera `resource.pack` a la rel. 33 entrades ≈ 4 MB.
+- `./build/pack_resources --list resource.pack` inspecciona el pack.
+
+**Estat actual (Fase 1 completada, 2026-04-16)**:
+- Classes + eina compilen i funcionen. El pack es genera correctament i el `--list` mostra les 33 entrades (totes les GIFs, OGGs, font `.fnt`+`.gif`, `locale/ca.yaml`, `shaders/*`).
+- **Encara no està cablejat al joc**: cap callsite usa `ResourceHelper::loadFile`. Tots segueixen cridant `file_readfile`. El joc funciona exactament igual que abans.
+- Nou getter `file_getresourcefolder()` afegit a [jfile.hpp](source/core/jail/jfile.hpp) perquè ResourceHelper puga construir el path del fallback.
+
+**Pendent (Fases 2-6 del pla [.claude/plans/declarative-popping-breeze.md](/home/sergio/.claude/plans/declarative-popping-breeze.md))**:
+1. **Fase 2** — Afegir `ResourceHelper::initializeResourceSystem(pack_path, enable_fallback=true)` a [main.cpp](source/main.cpp) just després de `file_setresourcefolder`, i `shutdownResourceSystem()` a `SDL_AppQuit`.
+2. **Fase 3** — Migrar callsites `file_readfile` → `ResourceHelper::loadFile` (tipus canvia `std::vector<char>` → `std::vector<uint8_t>`):
+   - [locale.cpp:30](source/core/locale/locale.cpp#L30)
+   - [text.cpp:65, 129](source/core/rendering/text.cpp) (`.fnt` + bitmap)
+   - [scene_utils.cpp:12](source/scenes/scene_utils.cpp) (música escenes)
+   - [modulegame.cpp:52](source/game/modulegame.cpp) (música gameplay)
+   - [jdraw8.cpp:47, 65](source/core/jail/jdraw8.cpp) (`JD8_LoadSurface`, `JD8_LoadPalette`)
+3. **Fase 4** — Eliminar scaffold `.jrf` de [jfile.cpp](source/core/jail/jfile.cpp): `file_setresourcefilename`, `file_setsource`, `SOURCE_FILE`/`SOURCE_FOLDER`, `dictionary_loaded()`, `file_getfilepointer()`, `file_readfile()`. Mantenir només config-folder + `file_setresourcefolder` + `file_getresourcefolder`.
+4. **Fase 5** — Als targets release de [Makefile](Makefile) (`_linux_release`/`_windows_release`/`_macos_release`): afegir dependència `pack` i canviar `cp -r data` → `cp resource.pack`. WASM intacte (segueix usant `--preload-file data@/data`).
+5. **Fase 6** — A [main.cpp](source/main.cpp): `enable_fallback = false` només per a `NDEBUG && !__EMSCRIPTEN__` (pack obligatori a Release natiu; Debug i WASM mantenen fallback).
+
 ### External Libraries (`source/external/`)
 
 - `gif.h` — Header-only GIF decoder. **Cannot be included from more than one .cpp** (no include guards on functions). Other files use `extern` declarations for `LoadGif()`
@@ -179,11 +283,32 @@ JD8_Flip produces ABGR byte order: `0xFF000000 + R + (G<<8) + (B<<16)`. SDL text
 ### Known Issues & Technical Debt
 
 1. **gif.h cannot be included twice**: Functions are not `static` or `inline`, causing multiple definition errors. Text class uses `extern` forward declarations as workaround
-2. **Cheats are broken (`reviu`, `alone`, `obert`)**: `JI_CheatActivated` in [jinput.cpp:46](source/core/jail/jinput.cpp#L46) compares `SDL_Scancode` values (e.g. `SDL_SCANCODE_R`=21) against ASCII chars (`'r'`=114). They never match. Regression from SDL3 migration. Fix requires either scancode→char conversion in `JI_moveCheats` or storing chars directly.
+2. ~~**Cheats are broken (`reviu`, `alone`, `obert`)**~~: Fixed. `JI_moveCheats` tradueix `SDL_Scancode` → ASCII via `scancode_to_ascii` abans de ficar-los al buffer ([jinput.cpp:32-37, 55-61](source/core/jail/jinput.cpp#L32-L61)), i `JI_CheatActivated` compara ASCII amb ASCII.
 3. **No sound effects in game**: Game code never calls `JA_PlaySound*`/`JA_LoadSound` — only music via `JA_PlayMusic`/`JA_FadeOutMusic`. The SONS and VOL SONS menu items control volume of an empty channel pool. Infrastructure ready for future SFX.
+4. ~~**Raw `malloc`/`free` in gameplay structs**~~: Majoritàriament arreglat. `Sprite`/`Entitat` usen `std::vector<Frame>` i `std::vector<Animacio>` ([sprite.hpp](source/game/sprite.hpp)). `jfile.cpp` ja no té el global `scratch[255]` (substituït per `thread_local std::string`). L'API `file_getfilebuffer` (que tornava raw `char*` amb `malloc`) s'ha substituït per `file_readfile` que retorna `std::vector<char>` RAII — elimina els leaks silenciosos que hi havia a `JD8_LoadPalette`, `ModuleGame::Go()` i `scenes::playMusic`. Queda `jail_audio.hpp` barrejant `new`/`malloc`/`SDL_malloc` de forma pairada i correcta (no leak), pendent de polir amb `std::unique_ptr` quan toque.
+5. ~~**Blocking loops in cinematics and fades**~~: Fixed. Migració completa de `ModuleSequence::do*()` a la capa `scenes::` (Steps 1–10) + `ModuleGame` també tick-based (Phase A). Tot `while(!JG_ShouldUpdate())` i `wait_frame_or_skip()` eliminat. Els fades bloquejants `JD8_FadeOut`/`JD8_FadeToPal` també eliminats (Phase B.2): només queda l'API tick-step `JD8_FadeStart*` + `JD8_FadeTickStep`, encapsulada pel wrapper `scenes::PaletteFade`. ModuleGame té fases `FadingIn`/`FadingOut` pròpies.
+6. ~~**`SDL_AddTimer` in audio**~~: Fixed in Phase 3. `jail_audio` is now a header-only `inline` module (single `.cpp` stub only hosts the `stb_vorbis` implementation to avoid multiple definitions). Music uses true streaming via `stb_vorbis_open_memory` + `JA_PumpMusic` with a 0.5s low-water-mark instead of decoding the whole OGG into RAM. Mixing/fade update runs manually via `JA_Update()` called once per frame from `Director::iterate()`. Ported from the `jaildoctors_dilemma` codebase.
+7. ~~**Game thread + `publishFrame` mutex/cv**~~: Fixed in Phase 4+5 via cooperative `GameFiber`; **eliminated entirely in Phase B.2**. `JD8_Flip()` ja no fa yield — només converteix `screen` → `pixel_data`. Director posseeix l'estat d'escena (`current_scene_`, `game_state_`) i crida `scene->tick()` directament des d'`iterate()`. Fitxers `source/core/system/fiber.{hpp,cpp}` esborrats. Zero threads, zero mutex, zero fibers.
+8. ~~**`ModuleSequence` legacy dispatcher**~~: Eliminated in Step 10. Era el vell switch per `num_piramide`, ara substituït per `SceneRegistry::tryCreate()` i dispatch directe des de `Director::iterate()`. `modulesequence.{hpp,cpp}` esborrats.
+
+### WebAssembly Build
+
+`make wasm` genera el build WASM via Docker (`emscripten/emsdk:latest`) i copia els 3 fitxers (`.js`/`.wasm`/`.data`) a `maverick:/home/sergio/gitea/web_jailgames/static/games/aee/wasm/`, amb un `ssh maverick './deploy.sh'` final. Output local a `dist/wasm/`.
+
+**Diferències respecte build natiu** (a [CMakeLists.txt](CMakeLists.txt) dins `if(EMSCRIPTEN)`):
+- SDL3 compilat des de font via `FetchContent` (no hi ha paquet de sistema).
+- Shaders SPIR-V omesos (SDL3 GPU no suportat a WebGL2).
+- `sdl3gpu_shader.cpp` exclòs dels sources — el fallback `SDL_Renderer` fa tota la presentació.
+- [screen.cpp](source/core/rendering/screen.cpp) guarda `#ifndef NO_SHADERS` al voltant de l'include i les crides a `SDL3GPUShader` directes. La resta del codi va via interfície base `ShaderBackend`.
+- Link flags: `--preload-file data@/data`, `-fexceptions`, `-sALLOW_MEMORY_GROWTH=1`, `-sMAX_WEBGL_VERSION=2`, `-sINITIAL_MEMORY=67108864`, `-sASSERTIONS=1`, `-sASYNCIFY=1`.
+- Defines: `EMSCRIPTEN_BUILD`, `NO_SHADERS`.
+
+**Filesystem**: MEMFS default — no persistent entre recàrregues. `file_setconfigfolder` té fallbacks robustos (`getpwuid` → `getenv("HOME")` → `/tmp`) perquè no pete quan emscripten no té `/etc/passwd`. La config es carrega per defecte cada vegada. IDBFS pendent si mai volguéssem persistència a web.
 
 ### Pending / Ideas for Later
 
+- **Sound effects**: infraestructura `JA_PlaySound*`/`JA_LoadSound` ja preparada. Cablejar events de gameplay (col·lisió momia, mort, recollir objecte, trencar tomba, cheat activat). Menus SONS/VOL SONS ja controlen el volum del pool.
+- **IDBFS persistence a WASM**: montar `/home/web_user/.config` com a IDBFS a l'init i `FS.syncfs` després de cada save. Opcional — ara per ara la config no persistix entre recàrregues de pàgina.
 - **Gamepad**: map Y button (North) to `P` key for Pepe character selection at title screen (only input path not covered by current mapping).
 - **Menu items for game**: habitacio_inicial, piramide_inicial, vides (already in `Options::game`, not exposed).
 - **Multi-language**: add `data/locale/es.yaml` / `en.yaml` and a language selector item in menu. `Locale::load()` already handles arbitrary files.
@@ -191,6 +316,8 @@ JD8_Flip produces ABGR byte order: `0xFF000000 + R + (G<<8) + (B<<16)`. SDL text
 - **Notification persistence**: notifications clear on each new one (`showNotification` does `notifications_.clear()`). Could queue instead.
 - **FPS counter jitter**: time segment width changes per frame (100 Hz centi updates) causes ~1-2 px horizontal jitter in centered layout. Could lock to max-width or use monospace digits.
 - **Notification messages partially hardcoded**: overlay/global_inputs/director now use Locale, but the window title (`Texts::WINDOW_TITLE`) and some game-layer strings remain hardcoded.
+- **jail_audio `JA_Sound_t` RAII**: `JA_Music_t` ja està net (vector + string), però `JA_Sound_t` encara usa `Uint8*` via `SDL_LoadWAV` out-param. Petit polish per a completar la coherència RAII.
+- **Resource Pack — Fases 2-6**: la classe `ResourcePack`, `ResourceHelper` i l'eina `pack_resources` ja estan fetes (Fase 1). Queda cablejar-ho al joc: init a `main.cpp`, migrar 5 callsites de `file_readfile` a `ResourceHelper::loadFile`, eliminar l'scaffold `.jrf` de `jfile`, integrar `resource.pack` als bundles release, i flip `enable_fallback=false` per a Release natiu. Detall complet a la secció *Resource Pack* i al pla [.claude/plans/declarative-popping-breeze.md](/home/sergio/.claude/plans/declarative-popping-breeze.md).
 
 ### Previously Fixed (kept for reference)
 
@@ -212,4 +339,4 @@ Director loop uses `FRAME_MS_VSYNC = 16` (60 FPS) or `FRAME_MS_NO_VSYNC = 4` (~2
 
 Init order: `file_setconfigfolder` → `Options::load` → `Locale::load("locale/ca.yaml")` → `Options::loadPostFX/CrtPi` → `JG_Init` → `Screen::init` → `JD8_Init` → `JA_Init` → `Options::applyAudio()` → `Overlay::init` → `Menu::init` → `Director::init` (also calls `Gamepad::init()`) → `Director::run()` (blocks until quit). Shutdown: `Options::save` → `Director::destroy` → `Menu::destroy` → `Overlay::destroy` → `JA_Quit` → `JD8_Quit` → `Screen::destroy` → `JG_Finalize`.
 
-The state machine (alternating `ModuleSequence` state=1 and `ModuleGame` state=0) now lives inside `Director::gameThreadFunc()`, running on the game thread.
+The state machine (alternating `ModuleSequence` state=1 and `ModuleGame` state=0) lives inside `gameFiberEntry()` in an anonymous namespace in [director.cpp](source/core/system/director.cpp), invoked as the entry of the cooperative fiber (single-threaded).

CMakeLists.txt

@@ -22,6 +22,10 @@ set(APP_SOURCES
     # Core - Locale (nova capa)
     source/core/locale/locale.cpp
 
+    # Core - Resources (pack binari AEE1, estil coffee_crisis)
+    source/core/resources/resource_pack.cpp
+    source/core/resources/resource_helper.cpp
+
     # Core - Capa de presentación (nueva)
     source/core/rendering/menu.cpp
     source/core/rendering/overlay.cpp
@@ -40,6 +44,24 @@ set(APP_SOURCES
     # Core - System (nova capa)
     source/core/system/director.cpp
 
+    # Scenes (cinemàtiques i menús reescrits)
+    source/scenes/timeline.cpp
+    source/scenes/sprite_mover.cpp
+    source/scenes/frame_animator.cpp
+    source/scenes/palette_fade.cpp
+    source/scenes/surface_handle.cpp
+    source/scenes/scene_registry.cpp
+    source/scenes/scene_utils.cpp
+    source/scenes/mort_scene.cpp
+    source/scenes/banner_scene.cpp
+    source/scenes/menu_scene.cpp
+    source/scenes/intro_new_logo_scene.cpp
+    source/scenes/intro_scene.cpp
+    source/scenes/intro_sprites_scene.cpp
+    source/scenes/slides_scene.cpp
+    source/scenes/credits_scene.cpp
+    source/scenes/secreta_scene.cpp
+
     # Game
     source/game/options.cpp
     source/game/bola.cpp
@@ -48,7 +70,6 @@ set(APP_SOURCES
     source/game/mapa.cpp
     source/game/marcador.cpp
     source/game/modulegame.cpp
-    source/game/modulesequence.cpp
     source/game/momia.cpp
     source/game/prota.cpp
     source/game/sprite.cpp
@@ -63,8 +84,22 @@ set(APP_SOURCES
 
 # Configuración de SDL3
 # En macOS bundle mode usamos el xcframework (universal arm64+x86_64).
-# En el resto de casos, o en macOS sin bundle, usamos SDL3 del sistema via find_package.
-if(APPLE AND MACOS_BUNDLE)
+# En emscripten compilamos SDL3 desde source con FetchContent (no hi ha paquet de sistema).
+# En el resto de casos, usamos SDL3 del sistema via find_package.
+if(EMSCRIPTEN)
+    include(FetchContent)
+    FetchContent_Declare(
+        SDL3
+        GIT_REPOSITORY https://github.com/libsdl-org/SDL.git
+        GIT_TAG release-3.4.4
+        GIT_SHALLOW TRUE
+    )
+    set(SDL_SHARED OFF CACHE BOOL "" FORCE)
+    set(SDL_STATIC ON CACHE BOOL "" FORCE)
+    set(SDL_TEST_LIBRARY OFF CACHE BOOL "" FORCE)
+    FetchContent_MakeAvailable(SDL3)
+    message(STATUS "SDL3: compilat des de source per a Emscripten (FetchContent)")
+elseif(APPLE AND MACOS_BUNDLE)
     set(SDL3_XCFRAMEWORK_SLICE "${CMAKE_SOURCE_DIR}/release/macos/frameworks/SDL3.xcframework/macos-arm64_x86_64")
     message(STATUS "SDL3: usando xcframework (${SDL3_XCFRAMEWORK_SLICE})")
 else()
@@ -72,8 +107,8 @@ else()
     message(STATUS "SDL3 encontrado: ${SDL3_INCLUDE_DIRS}")
 endif()
 
-# --- COMPILACIÓ SHADERS SPIR-V (Linux/Windows — macOS usa Metal) ---
-if(NOT APPLE)
+# --- COMPILACIÓ SHADERS SPIR-V (Linux/Windows — macOS usa Metal, Emscripten no suporta SDL3 GPU) ---
+if(NOT APPLE AND NOT EMSCRIPTEN)
     find_program(GLSLC_EXE NAMES glslc)
 
     set(SHADERS_DIR "${CMAKE_SOURCE_DIR}/data/shaders")
@@ -120,15 +155,25 @@ if(NOT APPLE)
         endforeach()
         message(STATUS "glslc no trobat — usant headers SPIR-V precompilats")
     endif()
+elseif(EMSCRIPTEN)
+    message(STATUS "Emscripten: shaders SPIR-V omesos (SDL3 GPU no suportat a WebGL2)")
 else()
     message(STATUS "macOS: shaders SPIR-V omesos (usa Metal)")
 endif()
 
 # --- EJECUTABLE ---
+# A emscripten excloïm sdl3gpu_shader.cpp — SDL3 GPU no suporta WebGL2, i el
+# fallback SDL_Renderer de Screen (amb NO_SHADERS) fa tota la presentació.
+if(EMSCRIPTEN)
+    set(APP_SOURCES_WASM ${APP_SOURCES})
+    list(REMOVE_ITEM APP_SOURCES_WASM source/core/rendering/sdl3gpu/sdl3gpu_shader.cpp)
+    add_executable(${PROJECT_NAME} ${APP_SOURCES_WASM})
+else()
     add_executable(${PROJECT_NAME} ${APP_SOURCES})
+endif()
 
 # Shaders han de compilar-se abans que l'executable (Linux/Windows amb glslc)
-if(NOT APPLE AND GLSLC_EXE)
+if(NOT APPLE AND NOT EMSCRIPTEN AND GLSLC_EXE)
     add_dependencies(${PROJECT_NAME} shaders)
 endif()
 
@@ -159,10 +204,44 @@ target_compile_options(${PROJECT_NAME} PRIVATE $<$<CONFIG:RELEASE>:-Os -ffunctio
 # --- CONFIGURACIÓN POR PLATAFORMA ---
 if(WIN32)
     target_link_libraries(${PROJECT_NAME} PRIVATE mingw32)
+elseif(EMSCRIPTEN)
+    target_compile_definitions(${PROJECT_NAME} PRIVATE EMSCRIPTEN_BUILD NO_SHADERS)
+    # -fexceptions: SDL3 i fkyaml llancen std::exception; sense això, `throw`
+    # acaba en `abort()`. També requerit al link per congruència ABI.
+    target_compile_options(${PROJECT_NAME} PRIVATE -fexceptions)
+    target_link_options(${PROJECT_NAME} PRIVATE
+        "SHELL:--preload-file ${CMAKE_SOURCE_DIR}/data@/data"
+        -fexceptions
+        -sALLOW_MEMORY_GROWTH=1
+        -sMAX_WEBGL_VERSION=2
+        -sINITIAL_MEMORY=67108864
+        -sASSERTIONS=1
+        # ASYNCIFY permet que Emscripten gestione yields durant la precarga
+        # d'assets. El main loop del joc ja usa SDL3 Callback API i no depén
+        # d'Asyncify — però el preloader del `.data` sí.
+        -sASYNCIFY=1
+    )
+    set_target_properties(${PROJECT_NAME} PROPERTIES SUFFIX ".html")
 endif()
 
-# Ejecutable en la raíz del proyecto
+# Ejecutable en la raíz del proyecto (solo nativos). A Emscripten queda dins build/.
+if(NOT EMSCRIPTEN)
     set_target_properties(${PROJECT_NAME} PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_SOURCE_DIR})
+endif()
+
+# --- EINA STANDALONE: pack_resources ---
+# Executable auxiliar que empaqueta `data/` a `resource.pack` (format AEE1).
+# No es compila per defecte (EXCLUDE_FROM_ALL). Build explícit:
+#   cmake --build build --target pack_resources
+# Després executar: ./build/pack_resources data resource.pack
+if(NOT EMSCRIPTEN)
+    add_executable(pack_resources EXCLUDE_FROM_ALL
+        tools/pack_resources/pack_resources.cpp
+        source/core/resources/resource_pack.cpp
+    )
+    target_include_directories(pack_resources PRIVATE "${CMAKE_SOURCE_DIR}/source")
+    target_compile_options(pack_resources PRIVATE -Wall)
+endif()
 
 # --- CLANG-FORMAT TARGETS ---
 find_program(CLANG_FORMAT_EXE NAMES clang-format)

Makefile

@@ -76,6 +76,12 @@ debug:
 	@cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
 	@cmake --build build
 
+# Empaqueta data/ a resource.pack (format AEE1). Build previ de l'eina + execució.
+pack:
+	@cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+	@cmake --build build --target pack_resources
+	@./build/pack_resources data resource.pack
+
 # ==============================================================================
 # RELEASE AUTOMÁTICO (detecta SO)
 # ==============================================================================
@@ -112,7 +118,7 @@ _windows_release:
 	@powershell -Command "Copy-Item 'README.md' -Destination '$(RELEASE_FOLDER)'"
 	@powershell -Command "Copy-Item 'gamecontrollerdb.txt' -Destination '$(RELEASE_FOLDER)'"
 	@powershell -Command "Copy-Item 'release\windows\dll\*.dll' -Destination '$(RELEASE_FOLDER)'"
-	@powershell -Command "Copy-Item -Path '$(TARGET_FILE)' -Destination '\"$(WIN_RELEASE_FILE).exe\"'"
+	@powershell -Command "Copy-Item -Path '$(TARGET_FILE).exe' -Destination '$(WIN_RELEASE_FILE).exe'"
 	strip -s -R .comment -R .gnu.version "$(WIN_RELEASE_FILE).exe" --strip-unneeded
 
 # Crea el fichero .zip
@@ -217,6 +223,32 @@ _macos_release:
 	$(RMDIR) build/arm
 	$(RMFILE) "$(DIST_DIR)"/rw.*
 
+# ==============================================================================
+# COMPILACIÓN PARA WEBASSEMBLY (requiere Docker amb emscripten/emsdk)
+# ==============================================================================
+# Genera aee.{html,js,wasm,data} a dist/wasm/. Es pot provar servint amb un
+# servidor HTTP local (els navegadors no carreguen `file://` WASM):
+#   cd dist/wasm && python3 -m http.server 8000
+#   # després obrir http://localhost:8000/aee.html
+wasm:
+	@echo "Creando release para WebAssembly - Version: $(VERSION)"
+	docker run --rm \
+		--user $(shell id -u):$(shell id -g) \
+		-v $(DIR_ROOT):/src \
+		-w /src \
+		emscripten/emsdk:latest \
+		bash -c "emcmake cmake -S . -B build/wasm -DCMAKE_BUILD_TYPE=Release && cmake --build build/wasm"
+	@$(MKDIR) "$(DIST_DIR)/wasm"
+	@cp build/wasm/$(TARGET_NAME).html $(DIST_DIR)/wasm/
+	@cp build/wasm/$(TARGET_NAME).js $(DIST_DIR)/wasm/
+	@cp build/wasm/$(TARGET_NAME).wasm $(DIST_DIR)/wasm/
+	@cp build/wasm/$(TARGET_NAME).data $(DIST_DIR)/wasm/
+	@echo "Output: $(DIST_DIR)/wasm/$(TARGET_NAME).html"
+	scp $(DIST_DIR)/wasm/$(TARGET_NAME).js $(DIST_DIR)/wasm/$(TARGET_NAME).wasm $(DIST_DIR)/wasm/$(TARGET_NAME).data \
+		maverick:/home/sergio/gitea/web_jailgames/static/games/aee/wasm/
+	ssh maverick 'cd /home/sergio/gitea/web_jailgames && ./deploy.sh'
+	@echo "Deployed to maverick"
+
 # ==============================================================================
 # COMPILACIÓN PARA LINUX (RELEASE)
 # ==============================================================================
@@ -247,4 +279,4 @@ _linux_release:
 # Elimina la carpeta temporal
 	$(RMDIR) "$(RELEASE_FOLDER)"
 
-.PHONY: all debug release _windows_release _linux_release _macos_release
+.PHONY: all debug pack release wasm _windows_release _linux_release _macos_release

data/locale/ca.yaml

@@ -8,11 +8,15 @@ menu:
     video: "VIDEO"
     audio: "AUDIO"
     controls: "CONTROLS"
+    game: "JOC"
 
   items:
     video: "VIDEO"
     audio: "AUDIO"
     controls: "CONTROLS"
+    game: "JOC"
+    use_new_logo: "LOGO NOU"
+    show_title_credits: "CREDITS DEL PORT"
     zoom: "ZOOM"
     screen: "PANTALLA"
     shader: "SHADER"

docs/scenes-migration-plan.md

@@ -0,0 +1,463 @@
+# Reescritura de cinemáticas: capa `scenes::` + migración escena a escena
+
+## Current Status (actualitzat 2026-04-16)
+
+**Steps completats** — capa `scenes::` estable i 7 de 9 escenes migrades:
+
+- ✅ **Step 0** — Infraestructura: `Scene`, `Timeline`, `SpriteMover`, `FrameAnimator`, `PaletteFade`, `SurfaceHandle`, `SceneRegistry`, `scene_utils`, dispatch al `gameFiberEntry`.
+- ✅ **Step 1** — `MortScene` (state 100). Pantalla game over + fade-in/out + música "00000001.ogg" → "00000003.ogg".
+- ✅ **Step 2** — `BannerScene` (states 2..5). Banner pre-piràmide amb les 4 variants consolidades a `(idx%2)*160, (idx/2)*75`.
+- ✅ **Step 3** — `MenuScene` (state 0). Primera ús real de `FrameAnimator` (camell 8×160ms). Scrollers manuals amb acumulador ms per palmeres/horitzó. Parpalleig "polsa tecla" time-based.
+- ✅ **Step 4** — `IntroNewLogoScene` (state 255, condicional a `use_new_logo`). Revelat lletra a lletra + cicle de paleta 256 passos. **Delega temporalment a `ModuleSequence::doIntroSprites()`** via `SurfaceHandle::release()` perquè el legacy allibera `gfx` internament. La delegació desapareixerà al Step 9.
+- ✅ **Step 5** — `SlidesScene` (states 1 i 7). Wipe suau amb `Easing::outCubic` (el "rasca" del vell s'ha evaporat). Redirect `6→7` replicat al `gameFiberEntry` abans del `tryCreate` perquè el flux "no tens prou diners" caiga a slides de fracàs.
+- ✅ **Step 6** — `CreditsScene` (state 8). Scroll vertical + parallax condicional si `diamants == 16`. Música heretable (només arranca si no en sona cap ja). Escriu `trick.ini` al final.
+- ✅ **Step 7** — `SecretaScene` (state 6). 11 fases amb swap de `tomba1.gif→tomba2.gif` via `SurfaceHandle::reset()` i efecte "red pulse" sobre els índexs 254/253 de la paleta. Primera ús d'`InitialFadeOut` (fade-out sobre la paleta prèvia abans de muntar la nova).
+
+**Steps pendents** — ataquen el cor de la intro:
+
+- 📋 **Step 8** — `IntroScene` (state 255 quan `use_new_logo == false`). 11 passos lineals del wordmark "JAILGAMES" llegat + cicle de paleta. Delegaria a `doIntroSprites` legacy igual que `IntroNewLogoScene`. Estimació: ~150 línies. Complexitat Media-Alta, però lineal.
+- 📋 **Step 9** — `IntroSpritesScene`. **El hueso**. `switch (rand() % 3)` amb 3 variants completament diferents (~900–1100 frames cada una), 6–8 loops anidats per variant, frames subsamplejats amb màscares diferents. Mateix arxiu `gfx` que la intro que la crida. Si l'API escala mal, s'acceptarà un `tick()` manual sense Timeline. En migrar aquest step s'elimina la delegació temporal `IntroNewLogoScene → doIntroSprites` i `doIntroSprites` pot passar de `public` a privat/eliminat. Complexitat Alta.
+- 📋 **Step 10** — Neteja final. `ModuleSequence::doIntro()` legacy també desapareix quan `IntroScene` + `IntroSpritesScene` estan fetes. `wait_frame_or_skip()` helper s'elimina. `ModuleSequence::Go()` queda reduït a ~5 línies o desapareix del tot si es pot treure del `gameFiberEntry`. Pot ser també aquí on s'elimine el `fiber` per fi quan `ModuleGame` siga tick-based, però això és un altre capítol.
+
+**Configuració per a proves ràpides** — afegits al `Options::game` (persistents a `config.yaml`):
+
+- `piramide_inicial` (ja existia) — state d'entrada. Valors útils: `255` = intro normal, `0` = menú, `5` = banner piràmide 5, `6` = SecretaScene, `8` = Credits, `100` = Mort.
+- `habitacio_inicial` (ja existia) — sala d'entrada dins la piràmide (1..5).
+- `vides` (ja existia).
+- `diamants_inicial` — per al final "bo" dels crèdits amb parallax + cotxe, posar a `16`.
+- `diners_inicial` — necessari posar `200` per entrar a `SecretaScene` sense el redirect a slides-fracàs (si entres directament en state 6 o hi arribes des del gameplay).
+- `show_title_credits` (ja existia) — desactivar-ho accelera els tests.
+
+**Bugs notables resolts al llarg del camí** (mantenir present — poden reaparèixer si es toca codi similar):
+
+1. `JI_Update()` no es cridava dins del mini-while del fiber → `JI_AnyKey()` no es refrescava → les escenes ignoraven les tecles de skip. Fix a [director.cpp:gameFiberEntry](source/core/system/director.cpp) al Step 3.
+2. `IntroNewLogoScene::~` doble-free de `gfx_` perquè `doIntroSprites` sempre allibera el `gfx` que rep (tant al final normal com als paths de skip). Fix: `SurfaceHandle::release()` abans de delegar. Step 4.
+3. `IntroNewLogoScene` no mutava `info::ctx.num_piramide = 0` al terminar, el fiber tornava a crear la mateixa escena — loop infinit. El `Go()` vell ho feia post-switch. Step 4.
+4. Skip per tecla durant el revelat del logo nou saltava només les lletres i executava igualment `doIntroSprites`. El vell retornava abans de cridar doIntroSprites. Fix al Step 4: `Phase::Done` direct en skip, `Phase::Delegate` només per terminació natural.
+
+---
+
+## Context
+
+Las fases 0–7b del plan anterior están completas. El runtime de AEE ya es moderno: fibers cooperativos, audio streaming sin `SDL_AddTimer`, callbacks `SDL_AppInit/Iterate/Event/Quit`, C++ idiomático en la capa jail. Lo que queda de *legacy pesado* es [source/game/modulesequence.cpp](source/game/modulesequence.cpp): **1309 líneas** con 9 funciones de cinemáticas lineales, 38+ `wait_frame_or_skip()` calls, constantes mágicas esparcidas, tres sub-variantes aleatorias en `doIntroSprites`, y código procedural difícil de editar.
+
+Un refactor mecánico de eso no tiene sentido — las escenas son contenido, no plumbing. Cada una tiene su propia lógica específica y no se benefician de una state machine genérica ni de sed. Lo que sí tiene sentido es **reescribirlas de arriba a abajo** sobre una capa fina `scenes::` reutilizable (Timeline, SpriteMover, FrameAnimator, PaletteFade, surface handle RAII), convirtiendo cada función en una clase `Scene`. Cada escena migrada elimina su código legacy del modulesequence, hasta que la función Go() sólo quede como un delegador hacia el registry.
+
+**Objetivos**:
+
+1. Capa `scenes::` **pequeña y reutilizable** — helpers obvios, sin sobreingeniería, reusando [easing.hpp](source/utils/easing.hpp) y los `JD8_*` existentes.
+2. Cada escena nueva: **~20–80 líneas** de código declarativo (vs los cientos actuales).
+3. **Fácil de añadir escenas nuevas** — derivar de `scenes::Scene`, llenar un Timeline o un `tick()` directo, registrar en el `SceneRegistry`.
+4. **Time-based**: todo `delta_ms` explícito. Las escenas no tocan fibers, no tienen whiles, no llaman `JG_ShouldUpdate`.
+5. **Migración gradual**: el fiber existente sigue corriendo por debajo. Las escenas nuevas se ejecutan *dentro* del fiber (por debajo del capó) pero su código es puro tick-based. Cuando las 9 estén migradas + ModuleGame también, el fiber se elimina de una pieza.
+6. **Zero regresiones visuales** — cada escena nueva debe verse/sonar indistinguible de la vieja antes de eliminar el código legacy asociado.
+
+---
+
+## Capa `scenes::` — API
+
+Namespace `scenes::` (plano, consistente con `Overlay::`, `Screen::`, `Menu::`).
+
+### `scenes::Scene` — interfaz base [source/scenes/scene.hpp]
+
+```cpp
+class Scene {
+public:
+    virtual ~Scene() = default;
+
+    // Llamado una vez cuando el Director la activa. Buen sitio para arrancar
+    // música o disparar un fade-in. Los assets pueden cargarse aquí o en el
+    // constructor (ambos válidos).
+    virtual void onEnter() {}
+
+    // Un paso de la escena. No debe bloquear, no debe llamar a JD8_Flip
+    // (lo hace el caller). delta_ms = tiempo real transcurrido desde el
+    // tick anterior.
+    virtual void tick(int delta_ms) = 0;
+
+    // True cuando la escena ha acabado y el Director debe pasar a la siguiente.
+    virtual bool done() const = 0;
+
+    // Valor de retorno equivalente al int que devolvía Go(). El caller lo
+    // usa para decidir el siguiente módulo. Consultado sólo cuando done().
+    virtual int nextState() const { return 1; }
+};
+```
+
+### `scenes::Timeline` — secuencia de steps [source/scenes/timeline.hpp]
+
+```cpp
+class Timeline {
+public:
+    using StepFn = std::function<void(float progress_0_1)>;
+
+    // Step con duración y callback que recibe el progreso [0..1] cada tick.
+    // Si fn es nullptr, el step es una espera pura.
+    Timeline& step(int duration_ms, StepFn fn = nullptr);
+
+    // Step que se ejecuta una sola vez al entrar (pinta algo estático y listo).
+    Timeline& once(std::function<void()> fn);
+
+    void tick(int delta_ms);
+    void skip();   // marca todos los steps restantes como done inmediatamente
+    void reset();
+    bool done() const;
+    int  currentStepIndex() const;
+    float currentProgress() const;  // 0..1 dentro del step actual
+};
+```
+
+### `scenes::SpriteMover` — movimiento 2D con easing [source/scenes/sprite_mover.hpp]
+
+```cpp
+class SpriteMover {
+public:
+    using EaseFn = float(*)(float);
+    void moveTo(int x0, int y0, int x1, int y1, int duration_ms,
+                EaseFn ease = Easing::linear);
+    void tick(int delta_ms);
+    int x() const;
+    int y() const;
+    bool done() const;
+};
+```
+
+No gestiona surfaces — sólo posición. La escena hace `JD8_BlitCK(mover.x(), mover.y(), gfx, ...)` ella misma. Reutilizable para el coche de créditos, slides, Sam caminando, etc.
+
+### `scenes::FrameAnimator` — iteración de frames subsampleados [source/scenes/frame_animator.hpp]
+
+```cpp
+class FrameAnimator {
+public:
+    FrameAnimator(int num_frames, int frame_ms, bool loop = true);
+    void tick(int delta_ms);
+    int  frame() const;   // índice [0, num_frames)
+    bool done() const;    // sólo relevante si loop=false
+    void reset();
+};
+```
+
+Cubre camello (8 frames × 4 ticks), palmeras (4 × 8 ticks), Sam caminando con `(i/5) % fr`.
+
+### `scenes::PaletteFade` — wrapper time-based de `JD8_Fade*` [source/scenes/palette_fade.hpp]
+
+```cpp
+class PaletteFade {
+public:
+    void startFadeOut();
+    void startFadeTo(JD8_Palette target);
+    void tick(int delta_ms);   // avanza un step de fade por tick
+    bool active() const;
+    bool done() const;
+};
+```
+
+Wrapper sobre `JD8_FadeStartOut` / `JD8_FadeStartToPal` / `JD8_FadeTickStep` que ya existen.
+
+### `scenes::SurfaceHandle` — RAII para `JD8_Surface` [source/scenes/surface_handle.hpp]
+
+```cpp
+class SurfaceHandle {
+public:
+    SurfaceHandle() = default;
+    explicit SurfaceHandle(const char* file);
+    ~SurfaceHandle();
+    SurfaceHandle(const SurfaceHandle&) = delete;
+    SurfaceHandle& operator=(const SurfaceHandle&) = delete;
+    SurfaceHandle(SurfaceHandle&&) noexcept;
+    SurfaceHandle& operator=(SurfaceHandle&&) noexcept;
+
+    operator JD8_Surface() const;  // conversión implícita → pasable a JD8_Blit*
+    JD8_Surface get() const;
+    bool valid() const;
+    void reset(const char* file);  // libera + recarga (doSecreta lo necesita)
+};
+```
+
+### `scenes::SceneRegistry` — factory [source/scenes/scene_registry.hpp/cpp]
+
+```cpp
+class SceneRegistry {
+public:
+    using Factory = std::function<std::unique_ptr<Scene>()>;
+
+    // Llamado al boot para registrar cada escena migrada.
+    void registerScene(int state_key, Factory f);
+
+    // Intenta crear la escena para un state dado. nullptr si no registrada.
+    // El caller (gameFiberEntry) cae al viejo Go() legacy si devuelve null.
+    std::unique_ptr<Scene> tryCreate(int state_key) const;
+
+    // Singleton accedido desde el Director al boot.
+    static SceneRegistry& instance();
+};
+```
+
+El `state_key` es un valor sintético que combina `info::ctx.num_piramide` con el módulo objetivo (sequence vs game). Los valores exactos los resolvemos al implementar — podría ser el propio `num_piramide` si es suficiente para distinguir (255=intro, 0=menu, 1/7=slides, 2-5=banner, 6=secreta, 8=credits, 100=mort).
+
+---
+
+## Organización de archivos
+
+```
+source/scenes/
+├── scene.hpp
+├── scene_registry.hpp/.cpp
+├── timeline.hpp/.cpp
+├── sprite_mover.hpp/.cpp
+├── frame_animator.hpp/.cpp
+├── palette_fade.hpp/.cpp
+├── surface_handle.hpp/.cpp
+├── mort_scene.hpp/.cpp           # orden de migración
+├── banner_scene.hpp/.cpp
+├── menu_scene.hpp/.cpp
+├── intro_new_logo_scene.hpp/.cpp
+├── slides_scene.hpp/.cpp
+├── credits_scene.hpp/.cpp
+├── secreta_scene.hpp/.cpp
+├── intro_scene.hpp/.cpp
+└── intro_sprites_scene.hpp/.cpp
+```
+
+Estructura plana — sin subdirectorios `helpers/` o `concrete/`. Añadir archivo nuevo = una línea al `CMakeLists.txt`.
+
+---
+
+## Integración con el Director existente
+
+**No creo un Director nuevo**. Modifico [source/core/system/director.cpp](source/core/system/director.cpp) — concretamente `gameFiberEntry()` en el namespace anónimo — para que consulte el `SceneRegistry` antes de caer al viejo `ModuleSequence::Go()`:
+
+```cpp
+// pseudocodigo dentro de gameFiberEntry()
+int state = 1;
+while (state != -1 && !JG_Quitting()) {
+    // Intentamos resolver la escena por el state actual.
+    if (auto scene = SceneRegistry::instance().tryCreate(info::ctx.num_piramide)) {
+        scene->onEnter();
+        Uint32 last = SDL_GetTicks();
+        while (!scene->done() && !JG_Quitting()) {
+            Uint32 now = SDL_GetTicks();
+            scene->tick(static_cast<int>(now - last));
+            last = now;
+            JD8_Flip();   // yields al Director (presenta con overlay encima)
+        }
+        state = scene->nextState();
+        continue;
+    }
+    // Fallback: todavía no migrada, usa el Go() legacy
+    if (state == 1) {
+        auto* ms = new ModuleSequence();
+        state = ms->Go();
+        delete ms;
+    } else if (state == 0) {
+        auto* mg = new ModuleGame();
+        state = mg->Go();
+        delete mg;
+    }
+}
+```
+
+**Claves**:
+- Las escenas nuevas son puras tick-based. `tick(delta_ms)` no sabe del fiber.
+- El mini-while que las ejecuta vive en `gameFiberEntry`, que sí corre dentro del fiber. `JD8_Flip()` es el que hace el yield al Director — igual que ahora.
+- Cuando todas las escenas + `ModuleGame` estén migradas, este mini-while migra al `Director::iterate()` directo y se elimina `gameFiberEntry` + `GameFiber::*`. Pero eso no es para esta tanda.
+- Registro de escenas: se hace en `Director::init()` llamando a `SceneRegistry::instance().registerScene(state_key, []{ return std::make_unique<scenes::MortScene>(); })` para cada escena ya migrada.
+
+---
+
+## Orden de migración (simple → complejo)
+
+Cada paso = una PR / commit / validación visual antes de seguir. Al migrar una escena, **se elimina la función legacy correspondiente** de modulesequence.cpp.
+
+### Step 0 — Infraestructura
+Crear los archivos de la capa `scenes::` (scene, timeline, sprite_mover, frame_animator, palette_fade, surface_handle, scene_registry) sin ninguna escena concreta todavía. Compilar para confirmar que la capa es sólida.
+
+### Step 1 — `MortScene` (complejidad **Baja**)
+Reemplaza `ModuleSequence::doMort()`. ~15 líneas originales: blit fullscreen `gameover.gif` + `JD8_FadeToPal` + música `00000001.ogg` + espera 1000ms o tecla + `info::ctx.vida = 5`. Es la primera víctima: valida la API mínima (`Scene` + `PaletteFade` + `SurfaceHandle`).
+
+### Step 2 — `BannerScene` (complejidad **Baja**)
+Reemplaza `ModuleSequence::doBanner()`. Blits estáticos "PIRÀMIDE X" + número + fade entrada + espera 5000ms + `JA_FadeOutMusic(250)` + fade salida. Primera prueba de `Timeline::step()` con `once()`.
+
+### Step 3 — `MenuScene` (complejidad **Media-Baja**)
+Reemplaza `ModuleSequence::doMenu()`. Primera prueba de `FrameAnimator` (palmeras, camello, horizonte). Bucle infinito hasta input. Lee/escribe `info::ctx.pepe_activat` y `info::ctx.nou_personatge`. Texto condicional con `Locale::get`.
+
+### Step 4 — `IntroNewLogoScene` (complejidad **Media**)
+Reemplaza `ModuleSequence::doIntroNewLogo()`. Revelado letra a letra (9 letras × 150ms) + cursor parpadeando + logo completo + ciclo de paleta 256 pasos. Timeline con 20+ steps. Mantiene la llamada final a `doIntroSprites` (que aún no está migrada — delegación legacy temporal).
+
+### Step 5 — `SlidesScene` (complejidad **Media**)
+Reemplaza `ModuleSequence::doSlides()`. 3 slides con scroll entrada-derecha + espera + scroll salida-izquierda. Primera prueba seria de `SpriteMover` con `Easing::outCubic`. Elige asset según `info::ctx.num_piramide` + `info::ctx.diners`. Fade de música al final.
+
+### Step 6 — `CreditsScene` (complejidad **Media**)
+Reemplaza `ModuleSequence::doCredits()`. Scroll vertical largo (~3100 frames = ~62s a 20ms) + scroll parallax condicional si `info::ctx.diamants == 16` con animación de coche. Escribe `info::ctx.nou_personatge = true` y crea `trick.ini`.
+
+### Step 7 — `SecretaScene` (complejidad **Media-Alta**)
+Reemplaza `ModuleSequence::doSecreta()`. 11 estados originales: scroll + recarga de asset a mitad (`SurfaceHandle::reset`) + animación RGB dinámica del rojo (`JD8_SetPaletteColor`). Primera escena que usa `SurfaceHandle::reset()`.
+
+### Step 8 — `IntroScene` (complejidad **Media-Alta**)
+Reemplaza `ModuleSequence::doIntro()` (el logo JAILGAMES legacy). 11 pasos lineales de construcción del wordmark + ciclo de paleta + delegación a `IntroSpritesScene`. Timeline con muchos `once()` + `step()`.
+
+### Step 9 — `IntroSpritesScene` (complejidad **Alta**)
+Reemplaza `ModuleSequence::doIntroSprites()`. La bestia: `switch(rand() % 3)` con 3 variantes completamente distintas (~900-1100 frames cada una). Cada variante tiene 6-8 loops anidados. Aquí probablemente hace falta combinar `Timeline` + `SpriteMover` + `FrameAnimator` + lógica ad-hoc. Si la API no escala limpia, se acepta que esta escena tenga `tick()` manual sin Timeline.
+
+### Step 10 — Limpieza final
+En este punto `ModuleSequence` ya no tiene ninguna función `doX()` — sólo el `Go()` que delega al registry. Se puede:
+- Eliminar `ModuleSequence` completo y mover el dispatch al `gameFiberEntry` directo.
+- Eliminar el helper `wait_frame_or_skip()`.
+- Eliminar el include de `fiber.hpp` desde `jgame.cpp` si `ModuleGame` también es tick-based (fuera de scope de este plan, pero queda preparado).
+
+---
+
+## Invariantes por escena
+
+Cada paso **debe cumplir**:
+1. Visualmente indistinguible de la vieja versión (mismo timing, mismas transiciones, mismo feel). Validar jugándolo.
+2. Skip por tecla funciona idéntico (misma tecla, mismo momento).
+3. Build nativo compila limpio, sin warnings nuevos.
+4. Audio sigue: música arranca, fades suaves, no hay cortes.
+5. Overlay sigue animándose encima (pause, notificaciones, render info) — lo hace el Director sin tocar la escena.
+6. La función legacy `doX()` se elimina en el mismo commit que su `XScene`, no se deja código muerto.
+
+---
+
+## Fuera de scope (explícito)
+
+- **`ModuleGame`** (gameplay puro). Sigue con Go() + fiber. Se migrará más tarde con otra estructura (probablemente no Scene — es interactivo y no lineal).
+- **Emscripten fiber backend** + build WASM (fases 7c/7d del plan anterior). Cuando estén migradas las escenas + ModuleGame, los fibers se eliminan y este punto se vuelve trivial.
+- **Fase 6** (time-based total con accumulator pattern). La saltamos — no aporta valor real con el framerate actual.
+- **Multi-language** de textos en escenas. Se usa `Locale::get` directamente donde haga falta, sin envoltorio nuevo.
+
+---
+
+## Critical files
+
+| Archivo | Step | Tipo |
+|---|---|---|
+| [source/scenes/scene.hpp](source/scenes/scene.hpp) | 0 | nuevo, interfaz base |
+| [source/scenes/timeline.hpp](source/scenes/timeline.hpp) + .cpp | 0 | nuevo, helper central |
+| [source/scenes/sprite_mover.hpp](source/scenes/sprite_mover.hpp) + .cpp | 0 | nuevo |
+| [source/scenes/frame_animator.hpp](source/scenes/frame_animator.hpp) + .cpp | 0 | nuevo |
+| [source/scenes/palette_fade.hpp](source/scenes/palette_fade.hpp) + .cpp | 0 | nuevo |
+| [source/scenes/surface_handle.hpp](source/scenes/surface_handle.hpp) + .cpp | 0 | nuevo, RAII |
+| [source/scenes/scene_registry.hpp](source/scenes/scene_registry.hpp) + .cpp | 0 | nuevo, factory |
+| [source/scenes/*_scene.hpp](source/scenes/) + .cpp | 1–9 | una por paso |
+| [source/core/system/director.cpp](source/core/system/director.cpp) | 0 | modificar `gameFiberEntry` |
+| [source/game/modulesequence.cpp](source/game/modulesequence.cpp) | 1–9 | borrar funciones `doX()` una a una |
+| [CMakeLists.txt](CMakeLists.txt) | 0–9 | añadir archivos nuevos |
+
+## Reusables existentes
+
+- [source/utils/easing.hpp](source/utils/easing.hpp) — `Easing::linear`, `outQuad`, `outCubic`, `inOutQuad`, `lerp`, `lerpInt`. Usados por `SpriteMover` y cualquier step de `Timeline` que reciba progress.
+- [source/core/jail/jdraw8.hpp](source/core/jail/jdraw8.hpp) — `JD8_FadeStartOut`, `JD8_FadeStartToPal`, `JD8_FadeTickStep`, `JD8_FadeIsActive`. Usados por `PaletteFade`.
+- [source/core/jail/jail_audio.hpp](source/core/jail/jail_audio.hpp) — `JA_PlayMusic`, `JA_FadeOutMusic`, `JA_PauseMusic`, `JA_ResumeMusic`.
+- [source/core/locale/locale.hpp](source/core/locale/locale.hpp) — `Locale::get("key")` para strings de UI en las escenas.
+- [source/core/rendering/overlay.hpp](source/core/rendering/overlay.hpp) — sigue siendo responsabilidad del Director; las escenas no tocan overlay.
+- [source/core/jail/jinput.hpp](source/core/jail/jinput.hpp) — `JI_AnyKey`, `JI_KeyPressed` para detectar skip y navegación de menú.
+
+---
+
+## Ejemplos concretos
+
+### `MortScene` (Step 1) — ~20 líneas de lógica
+
+```cpp
+// mort_scene.hpp
+namespace scenes {
+class MortScene : public Scene {
+public:
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return done_; }
+    int  nextState() const override { return 1; }  // igual que doMort → vuelve a seq
+private:
+    SurfaceHandle gfx_;
+    PaletteFade fade_;
+    int remaining_ms_ = 1000;
+    bool done_ = false;
+};
+}
+
+// mort_scene.cpp
+void MortScene::onEnter() {
+    // Lo que hacía ModuleSequence::doMort() linealmente, declarativo.
+    int size = 0;
+    char* buf = file_getfilebuffer("00000001.ogg", size);
+    JA_PlayMusic(JA_LoadMusic((Uint8*)buf, size, "00000001.ogg"));
+    JI_DisableKeyboard(60);
+    info::ctx.vida = 5;
+
+    gfx_ = SurfaceHandle("gameover.gif");
+    JD8_Palette pal = JD8_LoadPalette("gameover.gif");
+    JD8_ClearScreen(0);
+    JD8_Blit(gfx_);
+    fade_.startFadeTo(pal);
+}
+
+void MortScene::tick(int delta_ms) {
+    fade_.tick(delta_ms);
+    if (JI_AnyKey()) { done_ = true; return; }
+    remaining_ms_ -= delta_ms;
+    if (remaining_ms_ <= 0) done_ = true;
+}
+```
+
+### `BannerScene` (Step 2) — Timeline + fades
+
+```cpp
+void BannerScene::onEnter() {
+    play_music("00000004.ogg");
+    gfx_ = SurfaceHandle("ffase.gif");
+    JD8_Palette pal = JD8_LoadPalette("ffase.gif");
+
+    timeline_
+        .once([this]{
+            JD8_ClearScreen(0);
+            // blits del banner + número según info::ctx.num_piramide
+            fade_in_.startFadeTo(pal);
+        })
+        .step(5000);  // espera. Cualquier tecla hace timeline_.skip().
+}
+
+void BannerScene::tick(int delta_ms) {
+    fade_in_.tick(delta_ms);
+    if (!timeline_.done()) {
+        if (JI_AnyKey()) timeline_.skip();
+        timeline_.tick(delta_ms);
+        if (timeline_.done() && !fade_out_started_) {
+            JA_FadeOutMusic(250);
+            fade_out_.startFadeOut();
+            fade_out_started_ = true;
+        }
+    } else {
+        fade_out_.tick(delta_ms);
+    }
+}
+
+bool BannerScene::done() const { return timeline_.done() && fade_out_.done(); }
+```
+
+---
+
+## Verification
+
+Tras **cada step**:
+
+1. `cmake --build build` limpio, sin warnings nuevos.
+2. Ejecutar el juego entero desde intro hasta muerte, con atención específica a la escena migrada. Comparar con un git stash temporal del viejo código si hace falta.
+3. **Skip por tecla** en la escena migrada — debe saltar a la siguiente igual que antes.
+4. **Pausa F11** durante la escena — el juego se congela, el overlay sigue animándose.
+5. **Menú F12** durante la escena — debe abrir encima.
+6. **Cerrar ventana** durante la escena — responde al instante (sin el viejo bug de congelamiento).
+7. **Audio** — la música debe arrancar cuando toca, los fades suaves, sin cortes.
+8. **ESC doble-press** — sale limpiamente.
+
+Tras el **step 10** (limpieza final):
+- `modulesequence.cpp` tiene ~50 líneas (solo `Go()` mínimo) o desaparece del todo.
+- El juego entero es jugable de principio a fin.
+- FPS estable ≥60 con vsync.
+- Cero referencias a `wait_frame_or_skip` en el código.
+
+---
+
+## Cadencia
+
+Igual que antes: **paso a paso con pausa**. Cada step (0–9) se cierra con build verde + validación visual antes de arrancar el siguiente. No encadeno pasos automáticamente.

source/core/jail/jail_audio.cpp

@@ -1,450 +1,12 @@
-#ifndef JA_USESDLMIXER
-#include "core/jail/jail_audio.hpp"
-
-#include <SDL3/SDL.h>
-#include <stdio.h>
+// Aquest fitxer existeix per a albergar la implementació completa de
+// stb_vorbis en una única unitat de compilació. Totes les funcions JA_*
+// viuen `inline` a jail_audio.hpp (header-only, inspirat en el motor de
+// jaildoctors_dilemma). Sense aquest stub tindríem múltiples definicions
+// de les funcions de stb_vorbis si més d'un .cpp inclou el header.
 
+// clang-format off
+#undef STB_VORBIS_HEADER_ONLY
 #include "external/stb_vorbis.h"
+// clang-format on
 
-#define JA_MAX_SIMULTANEOUS_CHANNELS 5
-
-struct JA_Sound_t {
-    SDL_AudioSpec spec{SDL_AUDIO_S16, 2, 48000};
-    Uint32 length{0};
-    Uint8* buffer{NULL};
-};
-
-struct JA_Channel_t {
-    JA_Sound_t* sound{nullptr};
-    int pos{0};
-    int times{0};
-    SDL_AudioStream* stream{nullptr};
-    JA_Channel_state state{JA_CHANNEL_FREE};
-};
-
-struct JA_Music_t {
-    SDL_AudioSpec spec{SDL_AUDIO_S16, 2, 48000};
-    Uint32 length{0};
-    Uint8* buffer{nullptr};
-    char* filename{nullptr};
-
-    int pos{0};
-    int times{0};
-    SDL_AudioStream* stream{nullptr};
-    JA_Music_state state{JA_MUSIC_INVALID};
-};
-
-JA_Music_t* current_music{nullptr};
-JA_Channel_t channels[JA_MAX_SIMULTANEOUS_CHANNELS];
-
-SDL_AudioSpec JA_audioSpec{SDL_AUDIO_S16, 2, 48000};
-float JA_musicVolume{1.0f};
-float JA_soundVolume{0.5f};
-bool JA_musicEnabled{true};
-bool JA_soundEnabled{true};
-SDL_AudioDeviceID sdlAudioDevice{0};
-SDL_TimerID JA_timerID{0};
-
-bool fading = false;
-int fade_start_time;
-int fade_duration;
-int fade_initial_volume;
-
-/*
-void audioCallback(void * userdata, uint8_t * stream, int len) {
-    SDL_memset(stream, 0, len);
-    if (current_music != NULL && current_music->state == JA_MUSIC_PLAYING) {
-        const int size = SDL_min(len, current_music->samples*2-current_music->pos);
-        SDL_MixAudioFormat(stream, (Uint8*)(current_music->output+current_music->pos), AUDIO_S16, size, JA_musicVolume);
-        current_music->pos += size/2;
-        if (size < len) {
-            if (current_music->times != 0) {
-                SDL_MixAudioFormat(stream+size, (Uint8*)current_music->output, AUDIO_S16, len-size, JA_musicVolume);
-                current_music->pos = (len-size)/2;
-                if (current_music->times > 0) current_music->times--;
-            } else {
-                current_music->pos = 0;
-                current_music->state = JA_MUSIC_STOPPED;
-            }
-        }
-    }
-    // Mixar els channels mi amol
-    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
-        if (channels[i].state == JA_CHANNEL_PLAYING) {
-            const int size = SDL_min(len, channels[i].sound->length - channels[i].pos);
-            SDL_MixAudioFormat(stream, channels[i].sound->buffer + channels[i].pos, AUDIO_S16, size, JA_soundVolume);
-            channels[i].pos += size;
-            if (size < len) {
-                if (channels[i].times != 0) {
-                    SDL_MixAudioFormat(stream + size, channels[i].sound->buffer, AUDIO_S16, len-size, JA_soundVolume);
-                    channels[i].pos = len-size;
-                    if (channels[i].times > 0) channels[i].times--;
-                } else {
-                    JA_StopChannel(i);
-                }
-            }
-        }
-    }
-}
-*/
-
-Uint32 JA_UpdateCallback(void* userdata, SDL_TimerID timerID, Uint32 interval) {
-    if (JA_musicEnabled && current_music && current_music->state == JA_MUSIC_PLAYING) {
-        if (fading) {
-            int time = SDL_GetTicks();
-            if (time > (fade_start_time + fade_duration)) {
-                fading = false;
-                JA_StopMusic();
-                return 30;
-            } else {
-                const int time_passed = time - fade_start_time;
-                const float percent = (float)time_passed / (float)fade_duration;
-                SDL_SetAudioStreamGain(current_music->stream, JA_musicVolume * (1.0 - percent));
-            }
-        }
-
-        if (current_music->times != 0) {
-            if (SDL_GetAudioStreamAvailable(current_music->stream) < int(current_music->length / 2)) {
-                SDL_PutAudioStreamData(current_music->stream, current_music->buffer, current_music->length);
-            }
-            if (current_music->times > 0) current_music->times--;
-        } else {
-            if (SDL_GetAudioStreamAvailable(current_music->stream) == 0) JA_StopMusic();
-        }
-    }
-
-    if (JA_soundEnabled) {
-        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; ++i)
-            if (channels[i].state == JA_CHANNEL_PLAYING) {
-                if (channels[i].times != 0) {
-                    if (SDL_GetAudioStreamAvailable(channels[i].stream) < int(channels[i].sound->length / 2)) {
-                        SDL_PutAudioStreamData(channels[i].stream, channels[i].sound->buffer, channels[i].sound->length);
-                        if (channels[i].times > 0) channels[i].times--;
-                    }
-                } else {
-                    if (SDL_GetAudioStreamAvailable(channels[i].stream) == 0) JA_StopChannel(i);
-                }
-            }
-    }
-
-    return 30;
-}
-
-void JA_Init(const int freq, const SDL_AudioFormat format, const int num_channels) {
-#ifdef DEBUG
-    SDL_SetLogPriority(SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_PRIORITY_DEBUG);
-#endif
-
-    SDL_Log("Iniciant JailAudio...");
-    JA_audioSpec = {format, num_channels, freq};
-    if (!sdlAudioDevice) SDL_CloseAudioDevice(sdlAudioDevice);
-    sdlAudioDevice = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &JA_audioSpec);
-    SDL_Log((sdlAudioDevice == 0) ? "Failed to initialize SDL audio!\n" : "OK!\n");
-    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; ++i) channels[i].state = JA_CHANNEL_FREE;
-    // SDL_PauseAudioDevice(sdlAudioDevice);
-    JA_timerID = SDL_AddTimer(30, JA_UpdateCallback, nullptr);
-}
-
-void JA_Quit() {
-    if (JA_timerID) SDL_RemoveTimer(JA_timerID);
-
-    if (!sdlAudioDevice) SDL_CloseAudioDevice(sdlAudioDevice);
-    sdlAudioDevice = 0;
-}
-
-JA_Music_t* JA_LoadMusic(Uint8* buffer, Uint32 length, const char* filename) {
-    JA_Music_t* music = new JA_Music_t();
-
-    int chan, samplerate;
-    short* output;
-    music->length = stb_vorbis_decode_memory(buffer, length, &chan, &samplerate, &output) * chan * 2;
-
-    music->spec.channels = chan;
-    music->spec.freq = samplerate;
-    music->spec.format = SDL_AUDIO_S16;
-    music->buffer = (Uint8*)SDL_malloc(music->length);
-    SDL_memcpy(music->buffer, output, music->length);
-    free(output);
-    music->pos = 0;
-    music->state = JA_MUSIC_STOPPED;
-    if (filename) {
-        music->filename = (char*)malloc(strlen(filename) + 1);
-        strcpy(music->filename, filename);
-    }
-
-    return music;
-}
-
-JA_Music_t* JA_LoadMusic(const char* filename) {
-    // [RZC 28/08/22] Carreguem primer el arxiu en memòria i després el descomprimim. Es algo més rapid.
-    FILE* f = fopen(filename, "rb");
-    fseek(f, 0, SEEK_END);
-    long fsize = ftell(f);
-    fseek(f, 0, SEEK_SET);
-    Uint8* buffer = (Uint8*)malloc(fsize + 1);
-    if (fread(buffer, fsize, 1, f) != 1) return NULL;
-    fclose(f);
-
-    JA_Music_t* music = JA_LoadMusic(buffer, fsize, filename);
-
-    free(buffer);
-
-    return music;
-}
-
-void JA_PlayMusic(JA_Music_t* music, const int loop) {
-    if (!JA_musicEnabled) return;
-
-    JA_StopMusic();
-
-    current_music = music;
-    current_music->pos = 0;
-    current_music->state = JA_MUSIC_PLAYING;
-    current_music->times = loop;
-
-    current_music->stream = SDL_CreateAudioStream(&current_music->spec, &JA_audioSpec);
-    if (!SDL_PutAudioStreamData(current_music->stream, current_music->buffer, current_music->length)) printf("[ERROR] SDL_PutAudioStreamData failed!\n");
-    SDL_SetAudioStreamGain(current_music->stream, JA_musicVolume);
-    if (!SDL_BindAudioStream(sdlAudioDevice, current_music->stream)) printf("[ERROR] SDL_BindAudioStream failed!\n");
-    // SDL_ResumeAudioStreamDevice(current_music->stream);
-}
-
-char* JA_GetMusicFilename(JA_Music_t* music) {
-    if (!music) music = current_music;
-    return music->filename;
-}
-
-void JA_PauseMusic() {
-    if (!JA_musicEnabled) return;
-    if (!current_music || current_music->state == JA_MUSIC_INVALID) return;
-
-    current_music->state = JA_MUSIC_PAUSED;
-    // SDL_PauseAudioStreamDevice(current_music->stream);
-    SDL_UnbindAudioStream(current_music->stream);
-}
-
-void JA_ResumeMusic() {
-    if (!JA_musicEnabled) return;
-    if (!current_music || current_music->state == JA_MUSIC_INVALID) return;
-
-    current_music->state = JA_MUSIC_PLAYING;
-    // SDL_ResumeAudioStreamDevice(current_music->stream);
-    SDL_BindAudioStream(sdlAudioDevice, current_music->stream);
-}
-
-void JA_StopMusic() {
-    if (!JA_musicEnabled) return;
-    if (!current_music || current_music->state == JA_MUSIC_INVALID) return;
-
-    current_music->pos = 0;
-    current_music->state = JA_MUSIC_STOPPED;
-    // SDL_PauseAudioStreamDevice(current_music->stream);
-    SDL_DestroyAudioStream(current_music->stream);
-    current_music->stream = nullptr;
-    free(current_music->filename);
-    current_music->filename = nullptr;
-}
-
-void JA_FadeOutMusic(const int milliseconds) {
-    if (!JA_musicEnabled) return;
-    if (current_music == NULL || current_music->state == JA_MUSIC_INVALID) return;
-
-    fading = true;
-    fade_start_time = SDL_GetTicks();
-    fade_duration = milliseconds;
-    fade_initial_volume = JA_musicVolume;
-}
-
-JA_Music_state JA_GetMusicState() {
-    if (!JA_musicEnabled) return JA_MUSIC_DISABLED;
-    if (!current_music) return JA_MUSIC_INVALID;
-
-    return current_music->state;
-}
-
-void JA_DeleteMusic(JA_Music_t* music) {
-    if (current_music == music) current_music = nullptr;
-    SDL_free(music->buffer);
-    if (music->stream) SDL_DestroyAudioStream(music->stream);
-    delete music;
-}
-
-float JA_SetMusicVolume(float volume) {
-    JA_musicVolume = SDL_clamp(volume, 0.0f, 1.0f);
-    if (current_music) SDL_SetAudioStreamGain(current_music->stream, JA_musicVolume);
-    return JA_musicVolume;
-}
-
-void JA_SetMusicPosition(float value) {
-    if (!current_music) return;
-    current_music->pos = value * current_music->spec.freq;
-}
-
-float JA_GetMusicPosition() {
-    if (!current_music) return 0;
-    return float(current_music->pos) / float(current_music->spec.freq);
-}
-
-void JA_EnableMusic(const bool value) {
-    if (!value && current_music && (current_music->state == JA_MUSIC_PLAYING)) JA_StopMusic();
-
-    JA_musicEnabled = value;
-}
-
-JA_Sound_t* JA_NewSound(Uint8* buffer, Uint32 length) {
-    JA_Sound_t* sound = new JA_Sound_t();
-    sound->buffer = buffer;
-    sound->length = length;
-    return sound;
-}
-
-JA_Sound_t* JA_LoadSound(uint8_t* buffer, uint32_t size) {
-    JA_Sound_t* sound = new JA_Sound_t();
-    SDL_LoadWAV_IO(SDL_IOFromMem(buffer, size), 1, &sound->spec, &sound->buffer, &sound->length);
-
-    return sound;
-}
-
-JA_Sound_t* JA_LoadSound(const char* filename) {
-    JA_Sound_t* sound = new JA_Sound_t();
-    SDL_LoadWAV(filename, &sound->spec, &sound->buffer, &sound->length);
-
-    return sound;
-}
-
-int JA_PlaySound(JA_Sound_t* sound, const int loop) {
-    if (!JA_soundEnabled) return -1;
-
-    int channel = 0;
-    while (channel < JA_MAX_SIMULTANEOUS_CHANNELS && channels[channel].state != JA_CHANNEL_FREE) { channel++; }
-    if (channel == JA_MAX_SIMULTANEOUS_CHANNELS) channel = 0;
-    JA_StopChannel(channel);
-
-    channels[channel].sound = sound;
-    channels[channel].times = loop;
-    channels[channel].pos = 0;
-    channels[channel].state = JA_CHANNEL_PLAYING;
-    channels[channel].stream = SDL_CreateAudioStream(&channels[channel].sound->spec, &JA_audioSpec);
-    SDL_PutAudioStreamData(channels[channel].stream, channels[channel].sound->buffer, channels[channel].sound->length);
-    SDL_SetAudioStreamGain(channels[channel].stream, JA_soundVolume);
-    SDL_BindAudioStream(sdlAudioDevice, channels[channel].stream);
-
-    return channel;
-}
-
-int JA_PlaySoundOnChannel(JA_Sound_t* sound, const int channel, const int loop) {
-    if (!JA_soundEnabled) return -1;
-
-    if (channel < 0 || channel >= JA_MAX_SIMULTANEOUS_CHANNELS) return -1;
-    JA_StopChannel(channel);
-
-    channels[channel].sound = sound;
-    channels[channel].times = loop;
-    channels[channel].pos = 0;
-    channels[channel].state = JA_CHANNEL_PLAYING;
-    channels[channel].stream = SDL_CreateAudioStream(&channels[channel].sound->spec, &JA_audioSpec);
-    SDL_PutAudioStreamData(channels[channel].stream, channels[channel].sound->buffer, channels[channel].sound->length);
-    SDL_SetAudioStreamGain(channels[channel].stream, JA_soundVolume);
-    SDL_BindAudioStream(sdlAudioDevice, channels[channel].stream);
-
-    return channel;
-}
-
-void JA_DeleteSound(JA_Sound_t* sound) {
-    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
-        if (channels[i].sound == sound) JA_StopChannel(i);
-    }
-    SDL_free(sound->buffer);
-    delete sound;
-}
-
-void JA_PauseChannel(const int channel) {
-    if (!JA_soundEnabled) return;
-
-    if (channel == -1) {
-        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++)
-            if (channels[i].state == JA_CHANNEL_PLAYING) {
-                channels[i].state = JA_CHANNEL_PAUSED;
-                // SDL_PauseAudioStreamDevice(channels[i].stream);
-                SDL_UnbindAudioStream(channels[i].stream);
-            }
-    } else if (channel >= 0 && channel < JA_MAX_SIMULTANEOUS_CHANNELS) {
-        if (channels[channel].state == JA_CHANNEL_PLAYING) {
-            channels[channel].state = JA_CHANNEL_PAUSED;
-            // SDL_PauseAudioStreamDevice(channels[channel].stream);
-            SDL_UnbindAudioStream(channels[channel].stream);
-        }
-    }
-}
-
-void JA_ResumeChannel(const int channel) {
-    if (!JA_soundEnabled) return;
-
-    if (channel == -1) {
-        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++)
-            if (channels[i].state == JA_CHANNEL_PAUSED) {
-                channels[i].state = JA_CHANNEL_PLAYING;
-                // SDL_ResumeAudioStreamDevice(channels[i].stream);
-                SDL_BindAudioStream(sdlAudioDevice, channels[i].stream);
-            }
-    } else if (channel >= 0 && channel < JA_MAX_SIMULTANEOUS_CHANNELS) {
-        if (channels[channel].state == JA_CHANNEL_PAUSED) {
-            channels[channel].state = JA_CHANNEL_PLAYING;
-            // SDL_ResumeAudioStreamDevice(channels[channel].stream);
-            SDL_BindAudioStream(sdlAudioDevice, channels[channel].stream);
-        }
-    }
-}
-
-void JA_StopChannel(const int channel) {
-    if (!JA_soundEnabled) return;
-
-    if (channel == -1) {
-        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
-            if (channels[i].state != JA_CHANNEL_FREE) SDL_DestroyAudioStream(channels[i].stream);
-            channels[i].stream = nullptr;
-            channels[i].state = JA_CHANNEL_FREE;
-            channels[i].pos = 0;
-            channels[i].sound = NULL;
-        }
-    } else if (channel >= 0 && channel < JA_MAX_SIMULTANEOUS_CHANNELS) {
-        if (channels[channel].state != JA_CHANNEL_FREE) SDL_DestroyAudioStream(channels[channel].stream);
-        channels[channel].stream = nullptr;
-        channels[channel].state = JA_CHANNEL_FREE;
-        channels[channel].pos = 0;
-        channels[channel].sound = NULL;
-    }
-}
-
-JA_Channel_state JA_GetChannelState(const int channel) {
-    if (!JA_soundEnabled) return JA_SOUND_DISABLED;
-
-    if (channel < 0 || channel >= JA_MAX_SIMULTANEOUS_CHANNELS) return JA_CHANNEL_INVALID;
-
-    return channels[channel].state;
-}
-
-float JA_SetSoundVolume(float volume) {
-    JA_soundVolume = SDL_clamp(volume, 0.0f, 1.0f);
-
-    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++)
-        if ((channels[i].state == JA_CHANNEL_PLAYING) || (channels[i].state == JA_CHANNEL_PAUSED))
-            SDL_SetAudioStreamGain(channels[i].stream, JA_soundVolume);
-
-    return JA_soundVolume;
-}
-
-void JA_EnableSound(const bool value) {
-    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
-        if (channels[i].state == JA_CHANNEL_PLAYING) JA_StopChannel(i);
-    }
-    JA_soundEnabled = value;
-}
-
-float JA_SetVolume(float volume) {
-    JA_SetSoundVolume(JA_SetMusicVolume(volume) / 2.0f);
-
-    return JA_musicVolume;
-}
-
-#endif
+#include "core/jail/jail_audio.hpp"

source/core/jail/jail_audio.hpp

@@ -1,49 +1,537 @@
 #pragma once
-#include <SDL3/SDL.h>
 
-enum JA_Channel_state { JA_CHANNEL_INVALID,
+// --- Includes ---
+#include <SDL3/SDL.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <memory>
+#include <string>
+#include <vector>
+
+#define STB_VORBIS_HEADER_ONLY
+#include "external/stb_vorbis.h"
+
+// Deleter stateless per a buffers reservats amb `SDL_malloc` / `SDL_LoadWAV*`.
+// Compatible amb `std::unique_ptr<Uint8[], SDLFreeDeleter>` — zero size
+// overhead gràcies a EBO, igual que un unique_ptr amb default_delete.
+struct SDLFreeDeleter {
+    void operator()(Uint8* p) const noexcept {
+        if (p) SDL_free(p);
+    }
+};
+
+// --- Public Enums ---
+enum JA_Channel_state {
+    JA_CHANNEL_INVALID,
     JA_CHANNEL_FREE,
     JA_CHANNEL_PLAYING,
     JA_CHANNEL_PAUSED,
-    JA_SOUND_DISABLED };
-enum JA_Music_state { JA_MUSIC_INVALID,
+    JA_SOUND_DISABLED,
+};
+enum JA_Music_state {
+    JA_MUSIC_INVALID,
     JA_MUSIC_PLAYING,
     JA_MUSIC_PAUSED,
     JA_MUSIC_STOPPED,
-    JA_MUSIC_DISABLED };
+    JA_MUSIC_DISABLED,
+};
 
-struct JA_Sound_t;
-struct JA_Music_t;
+// --- Struct Definitions ---
+#define JA_MAX_SIMULTANEOUS_CHANNELS 20
+#define JA_MAX_GROUPS 2
 
-void JA_Init(const int freq, const SDL_AudioFormat format, const int num_channels);
-void JA_Quit();
+struct JA_Sound_t {
+    SDL_AudioSpec spec{SDL_AUDIO_S16, 2, 48000};
+    Uint32 length{0};
+    // Buffer descomprimit (PCM) propietat del sound. Reservat per SDL_LoadWAV
+    // via SDL_malloc; el deleter `SDLFreeDeleter` allibera amb SDL_free.
+    std::unique_ptr<Uint8[], SDLFreeDeleter> buffer;
+};
 
-JA_Music_t* JA_LoadMusic(const char* filename);
-JA_Music_t* JA_LoadMusic(Uint8* buffer, Uint32 length, const char* filename = nullptr);
-void JA_PlayMusic(JA_Music_t* music, const int loop = -1);
-char* JA_GetMusicFilename(JA_Music_t* music = nullptr);
-void JA_PauseMusic();
-void JA_ResumeMusic();
-void JA_StopMusic();
-void JA_FadeOutMusic(const int milliseconds);
-JA_Music_state JA_GetMusicState();
-void JA_DeleteMusic(JA_Music_t* music);
-float JA_SetMusicVolume(float volume);
-void JA_SetMusicPosition(float value);
-float JA_GetMusicPosition();
-void JA_EnableMusic(const bool value);
+struct JA_Channel_t {
+    JA_Sound_t* sound{nullptr};
+    int pos{0};
+    int times{0};
+    int group{0};
+    SDL_AudioStream* stream{nullptr};
+    JA_Channel_state state{JA_CHANNEL_FREE};
+};
 
-JA_Sound_t* JA_NewSound(Uint8* buffer, Uint32 length);
-JA_Sound_t* JA_LoadSound(Uint8* buffer, Uint32 length);
-JA_Sound_t* JA_LoadSound(const char* filename);
-int JA_PlaySound(JA_Sound_t* sound, const int loop = 0);
-int JA_PlaySoundOnChannel(JA_Sound_t* sound, const int channel, const int loop = 0);
-void JA_PauseChannel(const int channel);
-void JA_ResumeChannel(const int channel);
-void JA_StopChannel(const int channel);
-JA_Channel_state JA_GetChannelState(const int channel);
-void JA_DeleteSound(JA_Sound_t* sound);
-float JA_SetSoundVolume(float volume);
-void JA_EnableSound(const bool value);
+struct JA_Music_t {
+    SDL_AudioSpec spec{SDL_AUDIO_S16, 2, 48000};
 
-float JA_SetVolume(float volume);
+    // OGG comprimit en memòria. Propietat nostra; es copia des del buffer
+    // d'entrada una sola vegada en JA_LoadMusic i es descomprimix en chunks
+    // per streaming. Com que stb_vorbis guarda un punter persistent al
+    // `.data()` d'aquest vector, no el podem resize'jar un cop establert
+    // (una reallocation invalidaria el punter que el decoder conserva).
+    std::vector<Uint8> ogg_data;
+    stb_vorbis* vorbis{nullptr};  // handle del decoder, viu tot el cicle del JA_Music_t
+
+    std::string filename;
+
+    int times{0};  // loops restants (-1 = infinit, 0 = un sol play)
+    SDL_AudioStream* stream{nullptr};
+    JA_Music_state state{JA_MUSIC_INVALID};
+};
+
+// --- Internal Global State (inline, C++17) ---
+
+inline JA_Music_t* current_music{nullptr};
+inline JA_Channel_t channels[JA_MAX_SIMULTANEOUS_CHANNELS];
+
+inline SDL_AudioSpec JA_audioSpec{SDL_AUDIO_S16, 2, 48000};
+inline float JA_musicVolume{1.0f};
+inline float JA_soundVolume[JA_MAX_GROUPS];
+inline bool JA_musicEnabled{true};
+inline bool JA_soundEnabled{true};
+inline SDL_AudioDeviceID sdlAudioDevice{0};
+
+inline bool fading{false};
+inline int fade_start_time{0};
+inline int fade_duration{0};
+inline float fade_initial_volume{0.0f};
+
+// --- Forward Declarations ---
+inline void JA_StopMusic();
+inline void JA_StopChannel(const int channel);
+inline int JA_PlaySoundOnChannel(JA_Sound_t* sound, const int channel, const int loop = 0, const int group = 0);
+
+// --- Music streaming internals ---
+// Bytes-per-sample per canal (sempre s16)
+static constexpr int JA_MUSIC_BYTES_PER_SAMPLE = 2;
+// Quants shorts decodifiquem per crida a get_samples_short_interleaved.
+// 8192 shorts = 4096 samples/channel en estèreo ≈ 85ms de so a 48kHz.
+static constexpr int JA_MUSIC_CHUNK_SHORTS = 8192;
+// Umbral d'àudio per davant del cursor de reproducció. Mantenim ≥ 0.5 s a
+// l'SDL_AudioStream per absorbir jitter de frame i evitar underruns.
+static constexpr float JA_MUSIC_LOW_WATER_SECONDS = 0.5f;
+
+// Decodifica un chunk del vorbis i el volca a l'stream. Retorna samples
+// decodificats per canal (0 = EOF de l'stream vorbis).
+inline int JA_FeedMusicChunk(JA_Music_t* music) {
+    if (!music || !music->vorbis || !music->stream) return 0;
+
+    short chunk[JA_MUSIC_CHUNK_SHORTS];
+    const int channels = music->spec.channels;
+    const int samples_per_channel = stb_vorbis_get_samples_short_interleaved(
+        music->vorbis,
+        channels,
+        chunk,
+        JA_MUSIC_CHUNK_SHORTS);
+    if (samples_per_channel <= 0) return 0;
+
+    const int bytes = samples_per_channel * channels * JA_MUSIC_BYTES_PER_SAMPLE;
+    SDL_PutAudioStreamData(music->stream, chunk, bytes);
+    return samples_per_channel;
+}
+
+// Reompli l'stream fins que tinga ≥ JA_MUSIC_LOW_WATER_SECONDS bufferats.
+// En arribar a EOF del vorbis, aplica el loop (times) o deixa drenar.
+inline void JA_PumpMusic(JA_Music_t* music) {
+    if (!music || !music->vorbis || !music->stream) return;
+
+    const int bytes_per_second = music->spec.freq * music->spec.channels * JA_MUSIC_BYTES_PER_SAMPLE;
+    const int low_water_bytes = static_cast<int>(JA_MUSIC_LOW_WATER_SECONDS * static_cast<float>(bytes_per_second));
+
+    while (SDL_GetAudioStreamAvailable(music->stream) < low_water_bytes) {
+        const int decoded = JA_FeedMusicChunk(music);
+        if (decoded > 0) continue;
+
+        // EOF: si queden loops, rebobinar; si no, tallar i deixar drenar.
+        if (music->times != 0) {
+            stb_vorbis_seek_start(music->vorbis);
+            if (music->times > 0) music->times--;
+        } else {
+            break;
+        }
+    }
+}
+
+// --- Core Functions ---
+
+// Crida-la una vegada per frame des del main loop (Director). Substituïx
+// el callback asíncron SDL_AddTimer de la versió antiga — imprescindible
+// per al port a emscripten/SDL_AppIterate.
+inline void JA_Update() {
+    if (JA_musicEnabled && current_music && current_music->state == JA_MUSIC_PLAYING) {
+        if (fading) {
+            int time = SDL_GetTicks();
+            if (time > (fade_start_time + fade_duration)) {
+                fading = false;
+                JA_StopMusic();
+                return;
+            } else {
+                const int time_passed = time - fade_start_time;
+                const float percent = (float)time_passed / (float)fade_duration;
+                SDL_SetAudioStreamGain(current_music->stream, JA_musicVolume * (1.0f - percent));
+            }
+        }
+
+        // Streaming: rellenem l'stream fins al low-water-mark i parem si el
+        // vorbis s'ha esgotat i no queden loops.
+        JA_PumpMusic(current_music);
+        if (current_music->times == 0 && SDL_GetAudioStreamAvailable(current_music->stream) == 0) {
+            JA_StopMusic();
+        }
+    }
+
+    if (JA_soundEnabled) {
+        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; ++i)
+            if (channels[i].state == JA_CHANNEL_PLAYING) {
+                if (channels[i].times != 0) {
+                    if ((Uint32)SDL_GetAudioStreamAvailable(channels[i].stream) < (channels[i].sound->length / 2)) {
+                        SDL_PutAudioStreamData(channels[i].stream, channels[i].sound->buffer.get(), channels[i].sound->length);
+                        if (channels[i].times > 0) channels[i].times--;
+                    }
+                } else {
+                    if (SDL_GetAudioStreamAvailable(channels[i].stream) == 0) JA_StopChannel(i);
+                }
+            }
+    }
+}
+
+inline void JA_Init(const int freq, const SDL_AudioFormat format, const int num_channels) {
+#ifdef _DEBUG
+    SDL_SetLogPriority(SDL_LOG_CATEGORY_APPLICATION, SDL_LOG_PRIORITY_DEBUG);
+#endif
+
+    JA_audioSpec = {format, num_channels, freq};
+    if (sdlAudioDevice) SDL_CloseAudioDevice(sdlAudioDevice);
+    sdlAudioDevice = SDL_OpenAudioDevice(SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK, &JA_audioSpec);
+    if (sdlAudioDevice == 0) SDL_Log("Failed to initialize SDL audio!");
+    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; ++i) channels[i].state = JA_CHANNEL_FREE;
+    for (int i = 0; i < JA_MAX_GROUPS; ++i) JA_soundVolume[i] = 0.5f;
+}
+
+inline void JA_Quit() {
+    if (sdlAudioDevice) SDL_CloseAudioDevice(sdlAudioDevice);
+    sdlAudioDevice = 0;
+}
+
+// --- Music Functions ---
+
+inline JA_Music_t* JA_LoadMusic(const Uint8* buffer, Uint32 length) {
+    if (!buffer || length == 0) return nullptr;
+
+    // Allocem el JA_Music_t primer per aprofitar el seu `std::vector<Uint8>`
+    // com a propietari del OGG comprimit. stb_vorbis guarda un punter
+    // persistent al buffer; com que ací no el resize'jem, el .data() és
+    // estable durant tot el cicle de vida del music.
+    auto* music = new JA_Music_t();
+    music->ogg_data.assign(buffer, buffer + length);
+
+    int error = 0;
+    music->vorbis = stb_vorbis_open_memory(music->ogg_data.data(),
+                                           static_cast<int>(length), &error, nullptr);
+    if (!music->vorbis) {
+        SDL_Log("JA_LoadMusic: stb_vorbis_open_memory failed (error %d)", error);
+        delete music;
+        return nullptr;
+    }
+
+    const stb_vorbis_info info = stb_vorbis_get_info(music->vorbis);
+    music->spec.channels = info.channels;
+    music->spec.freq = static_cast<int>(info.sample_rate);
+    music->spec.format = SDL_AUDIO_S16;
+    music->state = JA_MUSIC_STOPPED;
+
+    return music;
+}
+
+// Overload amb filename — els callers l'usen per poder comparar la música
+// en curs amb JA_GetMusicFilename() i no rearrancar-la si ja és la mateixa.
+inline JA_Music_t* JA_LoadMusic(Uint8* buffer, Uint32 length, const char* filename) {
+    JA_Music_t* music = JA_LoadMusic(static_cast<const Uint8*>(buffer), length);
+    if (music && filename) music->filename = filename;
+    return music;
+}
+
+inline void JA_PlayMusic(JA_Music_t* music, const int loop = -1) {
+    if (!JA_musicEnabled || !music || !music->vorbis) return;
+
+    JA_StopMusic();
+
+    current_music = music;
+    current_music->state = JA_MUSIC_PLAYING;
+    current_music->times = loop;
+
+    // Rebobinem l'stream de vorbis al principi. Cobreix tant play-per-primera-
+    // vegada com replays/canvis de track que tornen a la mateixa pista.
+    stb_vorbis_seek_start(current_music->vorbis);
+
+    current_music->stream = SDL_CreateAudioStream(&current_music->spec, &JA_audioSpec);
+    if (!current_music->stream) {
+        SDL_Log("Failed to create audio stream!");
+        current_music->state = JA_MUSIC_STOPPED;
+        return;
+    }
+    SDL_SetAudioStreamGain(current_music->stream, JA_musicVolume);
+
+    // Pre-cargem el buffer abans de bindejar per evitar un underrun inicial.
+    JA_PumpMusic(current_music);
+
+    if (!SDL_BindAudioStream(sdlAudioDevice, current_music->stream)) printf("[ERROR] SDL_BindAudioStream failed!\n");
+}
+
+inline const char* JA_GetMusicFilename(JA_Music_t* music = nullptr) {
+    if (!music) music = current_music;
+    if (!music || music->filename.empty()) return nullptr;
+    return music->filename.c_str();
+}
+
+inline void JA_PauseMusic() {
+    if (!JA_musicEnabled) return;
+    if (!current_music || current_music->state != JA_MUSIC_PLAYING) return;
+
+    current_music->state = JA_MUSIC_PAUSED;
+    SDL_UnbindAudioStream(current_music->stream);
+}
+
+inline void JA_ResumeMusic() {
+    if (!JA_musicEnabled) return;
+    if (!current_music || current_music->state != JA_MUSIC_PAUSED) return;
+
+    current_music->state = JA_MUSIC_PLAYING;
+    SDL_BindAudioStream(sdlAudioDevice, current_music->stream);
+}
+
+inline void JA_StopMusic() {
+    if (!current_music || current_music->state == JA_MUSIC_INVALID || current_music->state == JA_MUSIC_STOPPED) return;
+
+    current_music->state = JA_MUSIC_STOPPED;
+    if (current_music->stream) {
+        SDL_DestroyAudioStream(current_music->stream);
+        current_music->stream = nullptr;
+    }
+    // Deixem el handle de vorbis viu — es tanca en JA_DeleteMusic.
+    // Rebobinem perquè un futur JA_PlayMusic comence des del principi.
+    if (current_music->vorbis) {
+        stb_vorbis_seek_start(current_music->vorbis);
+    }
+}
+
+inline void JA_FadeOutMusic(const int milliseconds) {
+    if (!JA_musicEnabled) return;
+    if (!current_music || current_music->state == JA_MUSIC_INVALID) return;
+
+    fading = true;
+    fade_start_time = SDL_GetTicks();
+    fade_duration = milliseconds;
+    fade_initial_volume = JA_musicVolume;
+}
+
+inline JA_Music_state JA_GetMusicState() {
+    if (!JA_musicEnabled) return JA_MUSIC_DISABLED;
+    if (!current_music) return JA_MUSIC_INVALID;
+
+    return current_music->state;
+}
+
+inline void JA_DeleteMusic(JA_Music_t* music) {
+    if (!music) return;
+    if (current_music == music) {
+        JA_StopMusic();
+        current_music = nullptr;
+    }
+    if (music->stream) SDL_DestroyAudioStream(music->stream);
+    if (music->vorbis) stb_vorbis_close(music->vorbis);
+    // ogg_data (std::vector) i filename (std::string) s'alliberen sols
+    // al destructor de JA_Music_t.
+    delete music;
+}
+
+inline float JA_SetMusicVolume(float volume) {
+    JA_musicVolume = SDL_clamp(volume, 0.0f, 1.0f);
+    if (current_music && current_music->stream) {
+        SDL_SetAudioStreamGain(current_music->stream, JA_musicVolume);
+    }
+    return JA_musicVolume;
+}
+
+inline void JA_SetMusicPosition(float /*value*/) {
+    // No implementat amb el backend de streaming.
+}
+
+inline float JA_GetMusicPosition() {
+    return 0.0f;
+}
+
+inline void JA_EnableMusic(const bool value) {
+    if (!value && current_music && (current_music->state == JA_MUSIC_PLAYING)) JA_StopMusic();
+    JA_musicEnabled = value;
+}
+
+// --- Sound Functions ---
+
+inline JA_Sound_t* JA_LoadSound(uint8_t* buffer, uint32_t size) {
+    auto sound = std::make_unique<JA_Sound_t>();
+    Uint8* raw = nullptr;
+    if (!SDL_LoadWAV_IO(SDL_IOFromMem(buffer, size), 1, &sound->spec, &raw, &sound->length)) {
+        SDL_Log("Failed to load WAV from memory: %s", SDL_GetError());
+        return nullptr;
+    }
+    sound->buffer.reset(raw);  // adopta el SDL_malloc'd buffer
+    return sound.release();
+}
+
+inline JA_Sound_t* JA_LoadSound(const char* filename) {
+    auto sound = std::make_unique<JA_Sound_t>();
+    Uint8* raw = nullptr;
+    if (!SDL_LoadWAV(filename, &sound->spec, &raw, &sound->length)) {
+        SDL_Log("Failed to load WAV file: %s", SDL_GetError());
+        return nullptr;
+    }
+    sound->buffer.reset(raw);  // adopta el SDL_malloc'd buffer
+    return sound.release();
+}
+
+inline int JA_PlaySound(JA_Sound_t* sound, const int loop = 0, const int group = 0) {
+    if (!JA_soundEnabled || !sound) return -1;
+
+    int channel = 0;
+    while (channel < JA_MAX_SIMULTANEOUS_CHANNELS && channels[channel].state != JA_CHANNEL_FREE) { channel++; }
+    if (channel == JA_MAX_SIMULTANEOUS_CHANNELS) channel = 0;
+
+    return JA_PlaySoundOnChannel(sound, channel, loop, group);
+}
+
+inline int JA_PlaySoundOnChannel(JA_Sound_t* sound, const int channel, const int loop, const int group) {
+    if (!JA_soundEnabled || !sound) return -1;
+    if (channel < 0 || channel >= JA_MAX_SIMULTANEOUS_CHANNELS) return -1;
+
+    JA_StopChannel(channel);
+
+    channels[channel].sound = sound;
+    channels[channel].times = loop;
+    channels[channel].pos = 0;
+    channels[channel].group = group;
+    channels[channel].state = JA_CHANNEL_PLAYING;
+    channels[channel].stream = SDL_CreateAudioStream(&channels[channel].sound->spec, &JA_audioSpec);
+
+    if (!channels[channel].stream) {
+        SDL_Log("Failed to create audio stream for sound!");
+        channels[channel].state = JA_CHANNEL_FREE;
+        return -1;
+    }
+
+    SDL_PutAudioStreamData(channels[channel].stream, channels[channel].sound->buffer.get(), channels[channel].sound->length);
+    SDL_SetAudioStreamGain(channels[channel].stream, JA_soundVolume[group]);
+    SDL_BindAudioStream(sdlAudioDevice, channels[channel].stream);
+
+    return channel;
+}
+
+inline void JA_DeleteSound(JA_Sound_t* sound) {
+    if (!sound) return;
+    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
+        if (channels[i].sound == sound) JA_StopChannel(i);
+    }
+    // buffer es destrueix automàticament via RAII (SDLFreeDeleter).
+    delete sound;
+}
+
+inline void JA_PauseChannel(const int channel) {
+    if (!JA_soundEnabled) return;
+
+    if (channel == -1) {
+        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++)
+            if (channels[i].state == JA_CHANNEL_PLAYING) {
+                channels[i].state = JA_CHANNEL_PAUSED;
+                SDL_UnbindAudioStream(channels[i].stream);
+            }
+    } else if (channel >= 0 && channel < JA_MAX_SIMULTANEOUS_CHANNELS) {
+        if (channels[channel].state == JA_CHANNEL_PLAYING) {
+            channels[channel].state = JA_CHANNEL_PAUSED;
+            SDL_UnbindAudioStream(channels[channel].stream);
+        }
+    }
+}
+
+inline void JA_ResumeChannel(const int channel) {
+    if (!JA_soundEnabled) return;
+
+    if (channel == -1) {
+        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++)
+            if (channels[i].state == JA_CHANNEL_PAUSED) {
+                channels[i].state = JA_CHANNEL_PLAYING;
+                SDL_BindAudioStream(sdlAudioDevice, channels[i].stream);
+            }
+    } else if (channel >= 0 && channel < JA_MAX_SIMULTANEOUS_CHANNELS) {
+        if (channels[channel].state == JA_CHANNEL_PAUSED) {
+            channels[channel].state = JA_CHANNEL_PLAYING;
+            SDL_BindAudioStream(sdlAudioDevice, channels[channel].stream);
+        }
+    }
+}
+
+inline void JA_StopChannel(const int channel) {
+    if (channel == -1) {
+        for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
+            if (channels[i].state != JA_CHANNEL_FREE) {
+                if (channels[i].stream) SDL_DestroyAudioStream(channels[i].stream);
+                channels[i].stream = nullptr;
+                channels[i].state = JA_CHANNEL_FREE;
+                channels[i].pos = 0;
+                channels[i].sound = nullptr;
+            }
+        }
+    } else if (channel >= 0 && channel < JA_MAX_SIMULTANEOUS_CHANNELS) {
+        if (channels[channel].state != JA_CHANNEL_FREE) {
+            if (channels[channel].stream) SDL_DestroyAudioStream(channels[channel].stream);
+            channels[channel].stream = nullptr;
+            channels[channel].state = JA_CHANNEL_FREE;
+            channels[channel].pos = 0;
+            channels[channel].sound = nullptr;
+        }
+    }
+}
+
+inline JA_Channel_state JA_GetChannelState(const int channel) {
+    if (!JA_soundEnabled) return JA_SOUND_DISABLED;
+    if (channel < 0 || channel >= JA_MAX_SIMULTANEOUS_CHANNELS) return JA_CHANNEL_INVALID;
+
+    return channels[channel].state;
+}
+
+inline float JA_SetSoundVolume(float volume, const int group = -1) {
+    const float v = SDL_clamp(volume, 0.0f, 1.0f);
+
+    if (group == -1) {
+        for (int i = 0; i < JA_MAX_GROUPS; ++i) {
+            JA_soundVolume[i] = v;
+        }
+    } else if (group >= 0 && group < JA_MAX_GROUPS) {
+        JA_soundVolume[group] = v;
+    } else {
+        return v;
+    }
+
+    // Aplicar volum als canals actius.
+    for (int i = 0; i < JA_MAX_SIMULTANEOUS_CHANNELS; i++) {
+        if ((channels[i].state == JA_CHANNEL_PLAYING) || (channels[i].state == JA_CHANNEL_PAUSED)) {
+            if (group == -1 || channels[i].group == group) {
+                if (channels[i].stream) {
+                    SDL_SetAudioStreamGain(channels[i].stream, JA_soundVolume[channels[i].group]);
+                }
+            }
+        }
+    }
+    return v;
+}
+
+inline void JA_EnableSound(const bool value) {
+    if (!value) {
+        JA_StopChannel(-1);
+    }
+    JA_soundEnabled = value;
+}
+
+inline float JA_SetVolume(float volume) {
+    float v = JA_SetMusicVolume(volume);
+    JA_SetSoundVolume(v, -1);
+    return v;
+}

source/core/jail/jdraw8.cpp

@@ -3,7 +3,6 @@
 #include <fstream>
 
 #include "core/jail/jfile.hpp"
-#include "core/system/director.hpp"
 #if defined(__clang__)
 #pragma clang diagnostic push
 #pragma clang diagnostic ignored "-Wunused-but-set-variable"
@@ -45,13 +44,10 @@ JD8_Surface JD8_NewSurface() {
 }
 
 JD8_Surface JD8_LoadSurface(const char* file) {
-    int filesize = 0;
-    char* buffer = file_getfilebuffer(file, filesize);
+    auto buffer = file_readfile(file);
 
     unsigned short w, h;
-    Uint8* pixels = LoadGif((unsigned char*)buffer, &w, &h);
-
-    free(buffer);
+    Uint8* pixels = LoadGif(reinterpret_cast<unsigned char*>(buffer.data()), &w, &h);
 
     if (pixels == NULL) {
         printf("Unable to load bitmap: %s\n", SDL_GetError());
@@ -66,13 +62,8 @@ JD8_Surface JD8_LoadSurface(const char* file) {
 }
 
 JD8_Palette JD8_LoadPalette(const char* file) {
-    int filesize = 0;
-    char* buffer = NULL;
-    buffer = file_getfilebuffer(file, filesize);
-
-    JD8_Palette palette = (JD8_Palette)LoadPalette((unsigned char*)buffer);
-
-    return palette;
+    auto buffer = file_readfile(file);
+    return (JD8_Palette)LoadPalette(reinterpret_cast<unsigned char*>(buffer.data()));
 }
 
 void JD8_SetScreenPalette(JD8_Palette palette) {
@@ -159,13 +150,20 @@ void JD8_BlitCKToSurface(int x, int y, JD8_Surface surface, int sx, int sy, int
 }
 
 void JD8_Flip() {
+    // Converteix el framebuffer indexat (paletted) a ARGB (pixel_data).
+    // El Director crida aquesta funció després del tick de cada escena
+    // per preparar el frame abans de presentar-lo. Ja no fa yield —
+    // tot corre en un sol thread sense fibers des de Phase B.2.
     for (int x = 0; x < 320; x++) {
         for (int y = 0; y < 200; y++) {
             Uint32 color = 0xFF000000 + main_palette[screen[x + (y * 320)]].r + (main_palette[screen[x + (y * 320)]].g << 8) + (main_palette[screen[x + (y * 320)]].b << 16);
             pixel_data[x + (y * 320)] = color;
         }
     }
-    Director::get()->publishFrame(pixel_data);
+}
+
+Uint32* JD8_GetFramebuffer() {
+    return pixel_data;
 }
 
 void JD8_FreeSurface(JD8_Surface surface) {
@@ -186,44 +184,78 @@ void JD8_SetPaletteColor(Uint8 index, Uint8 r, Uint8 g, Uint8 b) {
     main_palette[index].b = b << 2;
 }
 
-void JD8_FadeOut() {
-    for (int j = 0; j < 32; j++) {
+// Màquina d'estats del fade. Evita que JD8_FadeOut/JD8_FadeToPal hagen de
+// mantindre whiles interns. Cada pas aplica un delta a la paleta activa i
+// el caller decideix quan fer Flip.
+namespace {
+
+enum FadeType {
+    FADE_NONE = 0,
+    FADE_OUT,
+    FADE_TO_PAL,
+};
+
+constexpr int FADE_STEPS = 32;
+
+FadeType fade_type = FADE_NONE;
+Color fade_target[256];
+int fade_step = 0;
+
+void apply_fade_step() {
+    if (fade_type == FADE_OUT) {
         for (int i = 0; i < 256; i++) {
-            if (main_palette[i].r >= 8)
-                main_palette[i].r -= 8;
-            else
-                main_palette[i].r = 0;
-            if (main_palette[i].g >= 8)
-                main_palette[i].g -= 8;
-            else
-                main_palette[i].g = 0;
-            if (main_palette[i].b >= 8)
-                main_palette[i].b -= 8;
-            else
-                main_palette[i].b = 0;
+            main_palette[i].r = main_palette[i].r >= 8 ? main_palette[i].r - 8 : 0;
+            main_palette[i].g = main_palette[i].g >= 8 ? main_palette[i].g - 8 : 0;
+            main_palette[i].b = main_palette[i].b >= 8 ? main_palette[i].b - 8 : 0;
+        }
+    } else if (fade_type == FADE_TO_PAL) {
+        for (int i = 0; i < 256; i++) {
+            main_palette[i].r = main_palette[i].r <= int(fade_target[i].r) - 8
+                                    ? main_palette[i].r + 8
+                                    : fade_target[i].r;
+            main_palette[i].g = main_palette[i].g <= int(fade_target[i].g) - 8
+                                    ? main_palette[i].g + 8
+                                    : fade_target[i].g;
+            main_palette[i].b = main_palette[i].b <= int(fade_target[i].b) - 8
+                                    ? main_palette[i].b + 8
+                                    : fade_target[i].b;
         }
-        JD8_Flip();
     }
 }
 
-#define MAX(a, b) (a) > (b) ? (a) : (b)
+}  // namespace
 
-void JD8_FadeToPal(JD8_Palette pal) {
-    for (int j = 0; j < 32; j++) {
-        for (int i = 0; i < 256; i++) {
-            if (main_palette[i].r <= int(pal[i].r) - 8)
-                main_palette[i].r += 8;
-            else
-                main_palette[i].r = pal[i].r;
-            if (main_palette[i].g <= int(pal[i].g) - 8)
-                main_palette[i].g += 8;
-            else
-                main_palette[i].g = pal[i].g;
-            if (main_palette[i].b <= int(pal[i].b) - 8)
-                main_palette[i].b += 8;
-            else
-                main_palette[i].b = pal[i].b;
+void JD8_FadeStartOut() {
+    fade_type = FADE_OUT;
+    fade_step = 0;
 }
-        JD8_Flip();
+
+void JD8_FadeStartToPal(JD8_Palette pal) {
+    fade_type = FADE_TO_PAL;
+    memcpy(fade_target, pal, sizeof(Color) * 256);
+    fade_step = 0;
 }
+
+bool JD8_FadeIsActive() {
+    return fade_type != FADE_NONE;
 }
+
+bool JD8_FadeTickStep() {
+    if (fade_type == FADE_NONE) return true;
+
+    apply_fade_step();
+    fade_step++;
+
+    if (fade_step >= FADE_STEPS) {
+        fade_type = FADE_NONE;
+        return true;
+    }
+    return false;
+}
+
+// Els shims bloquejants `JD8_FadeOut` i `JD8_FadeToPal` han estat
+// eliminats a Phase B.2: feien un bucle de 32 iteracions amb `JD8_Flip`
+// entre cada una que només funcionava mentre l'entorn tenia fibers i
+// `JD8_Flip` cedia el control al Director. Ara tot fade es fa tick a
+// tick via `scenes::PaletteFade` (que encapsula `JD8_FadeStartOut` /
+// `JD8_FadeStartToPal` + `JD8_FadeTickStep`).

source/core/jail/jdraw8.hpp

@@ -40,8 +40,15 @@ void JD8_BlitCKScroll(int y, JD8_Surface surface, int sx, int sy, int sh, Uint8
 
 void JD8_BlitCKToSurface(int x, int y, JD8_Surface surface, int sx, int sy, int sw, int sh, JD8_Surface dest, Uint8 colorkey);
 
+// Converteix la pantalla indexada a ARGB. El Director crida aquesta
+// funció al final de cada tick i després llegeix el framebuffer via
+// JD8_GetFramebuffer() per presentar-lo.
 void JD8_Flip();
 
+// Accés al framebuffer ARGB de 320x200 actualitzat per l'última crida a
+// JD8_Flip(). Propietat de jdraw8 — el caller no ha de lliberar-lo.
+Uint32* JD8_GetFramebuffer();
+
 void JD8_FreeSurface(JD8_Surface surface);
 
 Uint8 JD8_GetPixel(JD8_Surface surface, int x, int y);
@@ -50,9 +57,17 @@ void JD8_PutPixel(JD8_Surface surface, int x, int y, Uint8 pixel);
 
 void JD8_SetPaletteColor(Uint8 index, Uint8 r, Uint8 g, Uint8 b);
 
-void JD8_FadeOut();
-
-void JD8_FadeToPal(JD8_Palette pal);
+// API de fade no bloquejant (màquina d'estats). `FadeStart*` inicia el
+// fade; `FadeTickStep` aplica un pas i retorna `true` quan el fade ha
+// acabat. Un pas correspon visualment a una iteració del fade original
+// (32 passos en total). El caller és responsable de fer el Flip entre
+// passos si el vol veure animat. `FadeIsActive` permet saber si hi ha
+// un fade en curs per a enllaçar-lo amb un altre subsistema.
+// L'embolcall `scenes::PaletteFade` ho fa més idiomàtic per a escenes.
+void JD8_FadeStartOut();
+void JD8_FadeStartToPal(JD8_Palette pal);
+bool JD8_FadeTickStep();
+bool JD8_FadeIsActive();
 
 // JD_Font JD_LoadFont( char *file, int width, int height);
 

source/core/jail/jfile.cpp

@@ -17,202 +17,208 @@
 #include <pwd.h>
 #endif
 
-#define DEFAULT_FILENAME "data.jf2"
-#define DEFAULT_FOLDER "data/"
-#define CONFIG_FILENAME "config.txt"
+namespace {
 
-struct file_t {
+constexpr const char* DEFAULT_FILENAME = "data.jf2";
+constexpr const char* DEFAULT_FOLDER = "data/";
+
+struct file_entry {
     std::string path;
     uint32_t size;
     uint32_t offset;
 };
 
-std::vector<file_t> toc;
-
-/* El std::map me fa coses rares, vaig a usar un good old std::vector amb una estructura key,value propia i au, que sempre funciona */
-struct keyvalue_t {
-    std::string key, value;
+struct keyvalue {
+    std::string key;
+    std::string value;
 };
 
-char* resource_filename = NULL;
-char* resource_folder = NULL;
+std::vector<file_entry> toc;
+std::vector<keyvalue> config;
+
+std::string resource_filename;
+std::string resource_folder;
+std::string config_folder;
 int file_source = SOURCE_FILE;
-char scratch[255];
-static std::string config_folder;
-std::vector<keyvalue_t> config;
 
-void file_setresourcefilename(const char* str) {
-    if (resource_filename != NULL) free(resource_filename);
-    resource_filename = (char*)malloc(strlen(str) + 1);
-    strcpy(resource_filename, str);
-}
-
-void file_setresourcefolder(const char* str) {
-    if (resource_folder != NULL) free(resource_folder);
-    resource_folder = (char*)malloc(strlen(str) + 1);
-    strcpy(resource_folder, str);
-}
-
-void file_setsource(const int src) {
-    file_source = src % 2;  // mod 2 so it always is a valid value, 0 (file) or 1 (folder)
-    if (src == SOURCE_FOLDER && resource_folder == NULL) file_setresourcefolder(DEFAULT_FOLDER);
-}
-
-bool file_getdictionary() {
-    if (resource_filename == NULL) file_setresourcefilename(DEFAULT_FILENAME);
+bool dictionary_loaded() {
+    if (resource_filename.empty()) resource_filename = DEFAULT_FILENAME;
 
     std::ifstream fi(resource_filename, std::ios::binary);
     if (!fi.is_open()) return false;
+
     char header[4];
     fi.read(header, 4);
     uint32_t num_files, toc_offset;
-    fi.read((char*)&num_files, 4);
-    fi.read((char*)&toc_offset, 4);
+    fi.read(reinterpret_cast<char*>(&num_files), 4);
+    fi.read(reinterpret_cast<char*>(&toc_offset), 4);
     fi.seekg(toc_offset);
 
     for (uint32_t i = 0; i < num_files; ++i) {
         uint32_t file_offset, file_size;
-        fi.read((char*)&file_offset, 4);
-        fi.read((char*)&file_size, 4);
+        fi.read(reinterpret_cast<char*>(&file_offset), 4);
+        fi.read(reinterpret_cast<char*>(&file_size), 4);
         uint8_t path_size;
-        fi.read((char*)&path_size, 1);
+        fi.read(reinterpret_cast<char*>(&path_size), 1);
         char file_name[256];
         fi.read(file_name, path_size);
         file_name[path_size] = 0;
-        std::string filename = file_name;
-        toc.push_back({filename, file_size, file_offset});
+        toc.push_back({std::string(file_name), file_size, file_offset});
     }
-    fi.close();
     return true;
 }
 
-char* file_getfilenamewithfolder(const char* filename) {
-    strcpy(scratch, resource_folder);
-    strcat(scratch, filename);
-    return scratch;
+std::string filename_with_folder(const char* filename) {
+    return resource_folder + filename;
+}
+
+void load_config_values() {
+    config.clear();
+    const std::string config_file = config_folder + "/config.txt";
+    std::ifstream fi(config_file);
+    if (!fi.is_open()) return;
+
+    std::string line;
+    while (std::getline(fi, line)) {
+        const auto eq = line.find('=');
+        if (eq == std::string::npos) continue;
+        config.push_back({line.substr(0, eq), line.substr(eq + 1)});
+    }
+}
+
+void save_config_values() {
+    const std::string config_file = config_folder + "/config.txt";
+    std::ofstream fo(config_file);
+    if (!fo.is_open()) return;
+    for (const auto& pair : config) {
+        fo << pair.key << '=' << pair.value << '\n';
+    }
+}
+
+}  // namespace
+
+void file_setresourcefilename(const char* str) {
+    resource_filename = str;
+}
+
+void file_setresourcefolder(const char* str) {
+    resource_folder = str;
+}
+
+const char* file_getresourcefolder() {
+    return resource_folder.c_str();
+}
+
+void file_setsource(const int src) {
+    file_source = src % 2;
+    if (src == SOURCE_FOLDER && resource_folder.empty()) file_setresourcefolder(DEFAULT_FOLDER);
 }
 
 FILE* file_getfilepointer(const char* resourcename, int& filesize, const bool binary) {
-    if (file_source == SOURCE_FILE and toc.size() == 0) {
-        if (not file_getdictionary()) file_setsource(SOURCE_FOLDER);
+    if (file_source == SOURCE_FILE && toc.empty()) {
+        if (!dictionary_loaded()) file_setsource(SOURCE_FOLDER);
     }
 
-    FILE* f;
+    FILE* f = nullptr;
 
     if (file_source == SOURCE_FILE) {
-        bool found = false;
-        uint32_t count = 0;
-        while (!found && count < toc.size()) {
-            found = (std::string(resourcename) == toc[count].path);
-            if (!found) count++;
+        const std::string name(resourcename);
+        size_t count = 0;
+        for (; count < toc.size(); ++count) {
+            if (toc[count].path == name) break;
         }
-
-        if (!found) {
+        if (count == toc.size()) {
             perror("El recurs no s'ha trobat en l'arxiu de recursos");
             exit(1);
         }
 
-        filesize = toc[count].size;
+        filesize = static_cast<int>(toc[count].size);
 
-        f = fopen(resource_filename, binary ? "rb" : "r");
-        if (not f) {
+        f = fopen(resource_filename.c_str(), binary ? "rb" : "r");
+        if (!f) {
             perror("No s'ha pogut obrir l'arxiu de recursos");
             exit(1);
         }
         fseek(f, toc[count].offset, SEEK_SET);
     } else {
-        f = fopen(file_getfilenamewithfolder(resourcename), binary ? "rb" : "r");
+        const std::string full = filename_with_folder(resourcename);
+        f = fopen(full.c_str(), binary ? "rb" : "r");
+        if (!f) return nullptr;
         fseek(f, 0, SEEK_END);
-        filesize = ftell(f);
+        filesize = static_cast<int>(ftell(f));
         fseek(f, 0, SEEK_SET);
     }
     return f;
 }
 
-char* file_getfilebuffer(const char* resourcename, int& filesize, const bool zero_terminate) {
+std::vector<char> file_readfile(const char* resourcename) {
+    int filesize = 0;
     FILE* f = file_getfilepointer(resourcename, filesize, true);
-    char* buffer = (char*)malloc(zero_terminate ? filesize : filesize + 1);
-    fread(buffer, filesize, 1, f);
-    if (zero_terminate) buffer[filesize] = 0;
+    if (!f) return {};
+    std::vector<char> buffer(filesize);
+    fread(buffer.data(), filesize, 1, f);
     fclose(f);
     return buffer;
 }
 
-// Crea la carpeta del sistema donde guardar datos.
-// Acepta rutas con subdirectorios (ej: "jailgames/aee") y crea toda la jerarquía.
+// Crea la carpeta del sistema on guardar les dades.
+// Accepta rutes amb subdirectoris (ex: "jailgames/aee") i crea tota la jerarquia.
 void file_setconfigfolder(const char* foldername) {
 #ifdef _WIN32
-    config_folder = std::string(getenv("APPDATA")) + "/" + foldername;
+    const char* base = getenv("APPDATA");
+    if (!base) base = "C:/";
+    config_folder = std::string(base) + "/" + foldername;
 #elif __APPLE__
     struct passwd* pw = getpwuid(getuid());
-    const char* homedir = pw->pw_dir;
+    const char* homedir = (pw && pw->pw_dir) ? pw->pw_dir : nullptr;
+    if (!homedir) homedir = getenv("HOME");
+    if (!homedir) homedir = "/tmp";
     config_folder = std::string(homedir) + "/Library/Application Support/" + foldername;
 #elif __linux__
+    // Nota emscripten: `__linux__` també està definit, però `getpwuid` no
+    // troba cap /etc/passwd al MEMFS i retorna nullptr. Amb els fallbacks
+    // HOME → /tmp evitem crashejar al primer arranque dins del navegador.
+    // La config no persistirà entre recàrregues de la pàgina (MEMFS és
+    // volàtil); caldria IDBFS si volguéssem persistència a web.
     struct passwd* pw = getpwuid(getuid());
-    const char* homedir = pw->pw_dir;
+    const char* homedir = (pw && pw->pw_dir) ? pw->pw_dir : nullptr;
+    if (!homedir) homedir = getenv("HOME");
+    if (!homedir) homedir = "/tmp";
     config_folder = std::string(homedir) + "/.config/" + foldername;
 #endif
 
+    if (!config_folder.empty()) {
         std::filesystem::create_directories(config_folder);
     }
+}
 
 const char* file_getconfigfolder() {
-    static std::string folder;
+    thread_local std::string folder;
     folder = config_folder + "/";
     return folder.c_str();
 }
 
-void file_loadconfigvalues() {
-    config.clear();
-    std::string config_file = config_folder + "/config.txt";
-    FILE* f = fopen(config_file.c_str(), "r");
-    if (!f) return;
-
-    char line[1024];
-    while (fgets(line, sizeof(line), f)) {
-        char* value = strchr(line, '=');
-        if (value) {
-            *value = '\0';
-            value++;
-            value[strlen(value) - 1] = '\0';
-            config.push_back({line, value});
-        }
-    }
-    fclose(f);
-}
-
-void file_saveconfigvalues() {
-    std::string config_file = config_folder + "/config.txt";
-    FILE* f = fopen(config_file.c_str(), "w");
-    if (f) {
-        for (auto pair : config) {
-            fprintf(f, "%s=%s\n", pair.key.c_str(), pair.value.c_str());
-        }
-        fclose(f);
-    }
-}
-
 const char* file_getconfigvalue(const char* key) {
-    if (config.empty()) file_loadconfigvalues();
-    for (auto pair : config) {
-        if (pair.key == std::string(key)) {
-            strcpy(scratch, pair.value.c_str());
-            return scratch;
+    if (config.empty()) load_config_values();
+    for (const auto& pair : config) {
+        if (pair.key == key) {
+            thread_local std::string value_cache;
+            value_cache = pair.value;
+            return value_cache.c_str();
         }
     }
-    return NULL;
+    return nullptr;
 }
 
 void file_setconfigvalue(const char* key, const char* value) {
-    if (config.empty()) file_loadconfigvalues();
+    if (config.empty()) load_config_values();
     for (auto& pair : config) {
-        if (pair.key == std::string(key)) {
+        if (pair.key == key) {
             pair.value = value;
-            file_saveconfigvalues();
+            save_config_values();
             return;
         }
     }
-    config.push_back({key, value});
-    file_saveconfigvalues();
-    return;
+    config.push_back({std::string(key), std::string(value)});
+    save_config_values();
 }

source/core/jail/jfile.hpp

@@ -1,6 +1,8 @@
 #pragma once
 #include <stdio.h>
 
+#include <vector>
+
 #define SOURCE_FILE 0
 #define SOURCE_FOLDER 1
 
@@ -9,10 +11,16 @@ const char* file_getconfigfolder();
 
 void file_setresourcefilename(const char* str);
 void file_setresourcefolder(const char* str);
+const char* file_getresourcefolder();
 void file_setsource(const int src);
 
 FILE* file_getfilepointer(const char* resourcename, int& filesize, const bool binary = false);
-char* file_getfilebuffer(const char* resourcename, int& filesize, const bool zero_terminate = false);
+
+// Llig tot el contingut d'un recurs (fitxer solt o entrada del .jrf).
+// Retorna un vector buit si el recurs no existeix. El vector es destrueix
+// automàticament en eixir d'àmbit — no fa falta cap free() manual. Mida =
+// bytes llegits (el buffer no està null-terminated).
+std::vector<char> file_readfile(const char* resourcename);
 
 const char* file_getconfigvalue(const char* key);
 void file_setconfigvalue(const char* key, const char* value);

source/core/jail/jgame.cpp

@@ -1,14 +1,19 @@
 #include "core/jail/jgame.hpp"
 
-bool eixir = false;
-Uint32 updateTicks = 0;
-Uint32 updateTime = 0;
+namespace {
+
+bool quitting = false;
+Uint32 update_ticks = 0;
+Uint32 update_time = 0;
 Uint32 cycle_counter = 0;
+Uint32 last_delta_time = 0;
+
+}  // namespace
 
 void JG_Init() {
     SDL_Init(SDL_INIT_VIDEO | SDL_INIT_AUDIO);
-    // SDL_WM_SetCaption( title, NULL );
-    updateTime = SDL_GetTicks();
+    update_time = SDL_GetTicks();
+    last_delta_time = update_time;
 }
 
 void JG_Finalize() {
@@ -16,27 +21,37 @@ void JG_Finalize() {
 }
 
 void JG_QuitSignal() {
-    eixir = true;
+    quitting = true;
 }
 
 bool JG_Quitting() {
-    return eixir;
+    return quitting;
 }
 
 void JG_SetUpdateTicks(Uint32 milliseconds) {
-    updateTicks = milliseconds;
+    update_ticks = milliseconds;
 }
 
 bool JG_ShouldUpdate() {
-    if (SDL_GetTicks() - updateTime > updateTicks) {
-        updateTime = SDL_GetTicks();
+    const Uint32 now = SDL_GetTicks();
+    if (now - update_time > update_ticks) {
+        update_time = now;
         cycle_counter++;
         return true;
-    } else {
-        return false;
     }
+    // No toca update — retornem false sense més. Des de Phase B.2 ja no
+    // hi ha fibers: cap caller fa spin-waits (`while (!JG_ShouldUpdate())`)
+    // i el Director pren el control del main loop frame a frame.
+    return false;
 }
 
 Uint32 JG_GetCycleCounter() {
     return cycle_counter;
 }
+
+Uint32 JG_GetDeltaMs() {
+    const Uint32 now = SDL_GetTicks();
+    const Uint32 delta = now - last_delta_time;
+    last_delta_time = now;
+    return delta;
+}

source/core/jail/jgame.hpp

@@ -14,3 +14,7 @@ void JG_SetUpdateTicks(Uint32 milliseconds);
 bool JG_ShouldUpdate();
 
 Uint32 JG_GetCycleCounter();
+
+// Temps transcorregut (en ms) des de l'última crida a JG_GetDeltaMs.
+// Helper per a la migració progressiva a time-based (Fase 4+).
+Uint32 JG_GetDeltaMs();

source/core/jail/jinput.cpp

@@ -1,39 +1,63 @@
 #include "core/jail/jinput.hpp"
 
-#include <string>
+#include <cstring>
 
 #include "core/system/director.hpp"
 
+namespace {
+
 // keystates és actualitzat per SDL internament. Des del joc només fem lectures.
 const bool* keystates = nullptr;
-Uint8 cheat[5];
-bool key_pressed = false;
-int waitTime = 0;
 
-void JI_DisableKeyboard(Uint32 time) {
-    waitTime = time;
+// Buffer dels últims 5 caràcters tecle. Emmagatzemem caràcters ASCII
+// lowercase (traduïts des de SDL_Scancode) per a poder comparar directament
+// amb les cadenes dels cheats ("reviu", "alone", "obert").
+Uint8 cheat[5] = {0, 0, 0, 0, 0};
+
+bool key_pressed = false;
+
+// Temps restant en mil·lisegons durant el qual JI_KeyPressed/JI_AnyKey
+// retornen false. Utilitzat per a evitar que pulsacions fortuïtes
+// saltin cinemàtiques al començament.
+float wait_ms = 0.0f;
+
+// Per a calcular el delta entre crides a JI_Update sense que els callers
+// hagen de passar-lo explícitament. Es reinicia a la primera crida.
+Uint64 last_update_tick = 0;
+
+bool input_blocked = false;
+
+Uint8 virtual_keystates[JI_VSRC_COUNT][SDL_SCANCODE_COUNT] = {{0}};
+
+Uint8 scancode_to_ascii(Uint8 scancode) {
+    if (scancode >= SDL_SCANCODE_A && scancode <= SDL_SCANCODE_Z) {
+        return static_cast<Uint8>('a' + (scancode - SDL_SCANCODE_A));
+    }
+    return 0;
 }
 
-static bool input_blocked = false;
+}  // namespace
+
+void JI_DisableKeyboard(Uint32 time) {
+    wait_ms = static_cast<float>(time);
+}
 
 void JI_SetInputBlocked(bool blocked) {
     input_blocked = blocked;
 }
 
-static Uint8 virtual_keystates[JI_VSRC_COUNT][SDL_SCANCODE_COUNT] = {{0}};
-
 void JI_SetVirtualKey(int scancode, int source, bool pressed) {
     if (scancode < 0 || scancode >= SDL_SCANCODE_COUNT) return;
     if (source < 0 || source >= JI_VSRC_COUNT) return;
     virtual_keystates[source][scancode] = pressed ? 1 : 0;
 }
 
-void JI_moveCheats(Uint8 new_key) {
+void JI_moveCheats(Uint8 scancode) {
     cheat[0] = cheat[1];
     cheat[1] = cheat[2];
     cheat[2] = cheat[3];
     cheat[3] = cheat[4];
-    cheat[4] = new_key;
+    cheat[4] = scancode_to_ascii(scancode);
 }
 
 void JI_Update() {
@@ -43,14 +67,22 @@ void JI_Update() {
         keystates = SDL_GetKeyboardState(NULL);
     }
 
-    if (waitTime > 0) waitTime--;
+    const Uint64 now = SDL_GetTicks();
+    if (last_update_tick == 0) last_update_tick = now;
+    const float delta_ms = static_cast<float>(now - last_update_tick);
+    last_update_tick = now;
+
+    if (wait_ms > 0.0f) {
+        wait_ms -= delta_ms;
+        if (wait_ms < 0.0f) wait_ms = 0.0f;
+    }
 
     // Consumim el flag de "alguna tecla no-GUI polsada" del director
     key_pressed = Director::get()->consumeKeyPressed();
 }
 
 bool JI_KeyPressed(int key) {
-    if (waitTime > 0 || keystates == nullptr) return false;
+    if (wait_ms > 0.0f || keystates == nullptr) return false;
     // Input bloquejat (p.ex. menú flotant obert)
     if (input_blocked) return false;
     // ESC bloquejada pel Director (primera pulsació mostra notificació)
@@ -64,13 +96,17 @@ bool JI_KeyPressed(int key) {
 }
 
 bool JI_CheatActivated(const char* cheat_code) {
-    bool found = true;
-    for (size_t i = 0; i < strlen(cheat_code); i++) {
-        if (cheat[i] != cheat_code[i]) found = false;
+    const size_t len = std::strlen(cheat_code);
+    if (len > sizeof(cheat)) return false;
+    // Compara contra els últims `len` caràcters del buffer. El buffer té
+    // mida fixa 5 i acumula sempre el darrer tecle a la posició 4.
+    const size_t offset = sizeof(cheat) - len;
+    for (size_t i = 0; i < len; i++) {
+        if (cheat[offset + i] != static_cast<Uint8>(cheat_code[i])) return false;
     }
-    return found;
+    return true;
 }
 
 bool JI_AnyKey() {
-    return waitTime > 0 ? false : key_pressed;
+    return wait_ms > 0.0f ? false : key_pressed;
 }

source/core/locale/locale.cpp

@@ -27,14 +27,12 @@ namespace Locale {
     }
 
     bool load(const char* filename) {
-        int size = 0;
-        char* buffer = file_getfilebuffer(filename, size, true);
-        if (!buffer || size <= 0) {
+        auto buffer = file_readfile(filename);
+        if (buffer.empty()) {
             std::cerr << "Locale: unable to load " << filename << '\n';
             return false;
         }
-        std::string content(buffer, size);
-        free(buffer);
+        std::string content(buffer.data(), buffer.size());
 
         try {
             auto yaml = fkyaml::node::deserialize(content);

source/core/rendering/menu.cpp

@@ -101,12 +101,14 @@ namespace Menu {
     static Page buildVideo();
     static Page buildAudio();
     static Page buildControls();
+    static Page buildGame();
 
     static Page buildRoot() {
         Page p{Locale::get("menu.titles.root"), {}, 0};
         p.items.push_back({Locale::get("menu.items.video"), ItemKind::Submenu, nullptr, nullptr, [] { pushPage(buildVideo()); }, nullptr});
         p.items.push_back({Locale::get("menu.items.audio"), ItemKind::Submenu, nullptr, nullptr, [] { pushPage(buildAudio()); }, nullptr});
         p.items.push_back({Locale::get("menu.items.controls"), ItemKind::Submenu, nullptr, nullptr, [] { pushPage(buildControls()); }, nullptr});
+        p.items.push_back({Locale::get("menu.items.game"), ItemKind::Submenu, nullptr, nullptr, [] { pushPage(buildGame()); }, nullptr});
         return p;
     }
 
@@ -207,6 +209,16 @@ namespace Menu {
         return p;
     }
 
+    static Page buildGame() {
+        Page p{Locale::get("menu.titles.game"), {}, 0};
+
+        p.items.push_back({Locale::get("menu.items.use_new_logo"), ItemKind::Toggle, [] { return yesNo(Options::game.use_new_logo); }, [](int) { Options::game.use_new_logo = !Options::game.use_new_logo; }, nullptr});
+
+        p.items.push_back({Locale::get("menu.items.show_title_credits"), ItemKind::Toggle, [] { return yesNo(Options::game.show_title_credits); }, [](int) { Options::game.show_title_credits = !Options::game.show_title_credits; }, nullptr});
+
+        return p;
+    }
+
     // --- Dibuix ---
 
     // Alpha blending per pixel sobre el buffer ARGB (ABGR en memòria)

source/core/rendering/screen.cpp

@@ -5,7 +5,9 @@
 
 #include "core/locale/locale.hpp"
 #include "core/rendering/overlay.hpp"
+#ifndef NO_SHADERS
 #include "core/rendering/sdl3gpu/sdl3gpu_shader.hpp"
+#endif
 #include "game/defines.hpp"
 #include "game/options.hpp"
 #include "utils/utils.hpp"
@@ -40,10 +42,9 @@ Screen::Screen() {
 
     window_ = SDL_CreateWindow(Locale::get("window.title"), w, h, fullscreen_ ? SDL_WINDOW_FULLSCREEN : 0);
     renderer_ = SDL_CreateRenderer(window_, nullptr);
-    SDL_SetRenderLogicalPresentation(renderer_, GAME_WIDTH, GAME_HEIGHT, SDL_LOGICAL_PRESENTATION_LETTERBOX);
 
     texture_ = SDL_CreateTexture(renderer_, SDL_PIXELFORMAT_ABGR8888, SDL_TEXTUREACCESS_STREAMING, GAME_WIDTH, GAME_HEIGHT);
-    SDL_SetTextureScaleMode(texture_, SDL_SCALEMODE_NEAREST);
+    applyFallbackPresentation();
 
     // Inicialitza backend GPU si l'acceleració està activada
     initShaders();
@@ -56,10 +57,12 @@ Screen::~Screen() {
     Options::window.zoom = zoom_;
     Options::window.fullscreen = fullscreen_;
 
-    // Destrueix el backend GPU
+    // Destrueix el backend GPU (només existeix si s'ha compilat amb shaders)
     if (shader_backend_) {
+#ifndef NO_SHADERS
         auto* gpu = dynamic_cast<Rendering::SDL3GPUShader*>(shader_backend_.get());
         if (gpu) gpu->destroy();
+#endif
         shader_backend_.reset();
     }
 
@@ -69,6 +72,13 @@ Screen::~Screen() {
 }
 
 void Screen::initShaders() {
+#ifdef NO_SHADERS
+    // Build sense shaders (p.ex. emscripten/WebGL2, on SDL3 GPU no està
+    // disponible). Es salta tota la inicialització — shader_backend_ es
+    // queda nul·lptr i tots els `if (shader_backend_)` del render path
+    // curtcircuiten cap al fallback SDL_Renderer.
+    return;
+#else
     if (!Options::video.gpu_acceleration) return;
 
     shader_backend_ = std::make_unique<Rendering::SDL3GPUShader>();
@@ -122,6 +132,7 @@ void Screen::initShaders() {
 
     applyCurrentPostFXPreset();
     applyCurrentCrtPiPreset();
+#endif
 }
 
 void Screen::present(Uint32* pixel_data) {
@@ -192,6 +203,8 @@ void Screen::toggleAspectRatio() {
     Options::video.aspect_ratio_4_3 = !Options::video.aspect_ratio_4_3;
     if (shader_backend_) {
         shader_backend_->setStretch4_3(Options::video.aspect_ratio_4_3);
+    } else {
+        applyFallbackPresentation();
     }
     if (!fullscreen_) {
         adjustWindowSize();
@@ -202,6 +215,8 @@ void Screen::toggleIntegerScale() {
     Options::video.integer_scale = !Options::video.integer_scale;
     if (shader_backend_) {
         shader_backend_->setScaleMode(Options::video.integer_scale);
+    } else {
+        applyFallbackPresentation();
     }
 }
 
@@ -216,6 +231,8 @@ void Screen::toggleStretchFilter() {
     Options::video.stretch_filter_linear = !Options::video.stretch_filter_linear;
     if (shader_backend_) {
         shader_backend_->setStretchFilter(Options::video.stretch_filter_linear);
+    } else {
+        applyFallbackPresentation();
     }
 }
 
@@ -371,6 +388,27 @@ void Screen::updateRenderInfo() {
         0b1001);
 }
 
+void Screen::applyFallbackPresentation() {
+    // Fallback SDL_Renderer (p.ex. emscripten/WebGL2 sense shaders GPU): tria
+    // el mode de presentació lògica segons 4:3 i integer_scale, i aplica el
+    // filtre de la textura segons stretch_filter_linear. Sense açò, el path
+    // fallback mostrava sempre LETTERBOX i ignorava les tres flags.
+    SDL_ScaleMode scale = Options::video.stretch_filter_linear ? SDL_SCALEMODE_LINEAR : SDL_SCALEMODE_NEAREST;
+    if (texture_) SDL_SetTextureScaleMode(texture_, scale);
+
+    SDL_RendererLogicalPresentation mode;
+    if (Options::video.aspect_ratio_4_3) {
+        // La finestra ja té aspect 4:3 (alçada × 1.2); STRETCH estira la
+        // textura 320×200 fins a omplir-la exactament.
+        mode = SDL_LOGICAL_PRESENTATION_STRETCH;
+    } else if (Options::video.integer_scale) {
+        mode = SDL_LOGICAL_PRESENTATION_INTEGER_SCALE;
+    } else {
+        mode = SDL_LOGICAL_PRESENTATION_LETTERBOX;
+    }
+    SDL_SetRenderLogicalPresentation(renderer_, GAME_WIDTH, GAME_HEIGHT, mode);
+}
+
 void Screen::adjustWindowSize() {
     int w = GAME_WIDTH * zoom_;
     // Si 4:3 actiu, l'alçada visual és 240 per zoom (200 * 1.2)

source/core/rendering/screen.hpp

@@ -53,6 +53,7 @@ class Screen {
     void adjustWindowSize();
     void calculateMaxZoom();
     void initShaders();
+    void applyFallbackPresentation();  // Logical presentation + scale mode per al path SDL_Renderer
 
     static Screen* instance_;
 

source/core/rendering/text.cpp

@@ -62,15 +62,13 @@ auto Text::nextCodepoint(const char*& ptr) -> uint32_t {
 // --- Càrrega de font ---
 
 void Text::loadFont(const char* fnt_file) {
-    int filesize = 0;
-    char* buffer = file_getfilebuffer(fnt_file, filesize, true);
-    if (!buffer) {
+    auto buffer = file_readfile(fnt_file);
+    if (buffer.empty()) {
         std::cerr << "Text: unable to load font file: " << fnt_file << '\n';
         return;
     }
 
-    std::istringstream stream(std::string(buffer, filesize));
-    free(buffer);
+    std::istringstream stream(std::string(buffer.data(), buffer.size()));
 
     std::string line;
     int glyph_index = 0;
@@ -128,15 +126,14 @@ void Text::loadFont(const char* fnt_file) {
 }
 
 void Text::loadBitmap(const char* gif_file) {
-    int filesize = 0;
-    char* buffer = file_getfilebuffer(gif_file, filesize);
-    if (!buffer) {
+    auto buffer = file_readfile(gif_file);
+    if (buffer.empty()) {
         std::cerr << "Text: unable to load bitmap: " << gif_file << '\n';
         return;
     }
 
     // Extrau dimensions del header GIF (bytes 6-7 = width, 8-9 = height, little-endian)
-    auto* raw = reinterpret_cast<unsigned char*>(buffer);
+    auto* raw = reinterpret_cast<unsigned char*>(buffer.data());
     int w = raw[6] | (raw[7] << 8);
     int h = raw[8] | (raw[9] << 8);
 
@@ -144,7 +141,6 @@ void Text::loadBitmap(const char* gif_file) {
     Uint8* pixels = LoadGif(raw, &gw, &gh);
     if (!pixels) {
         std::cerr << "Text: unable to decode GIF: " << gif_file << '\n';
-        free(buffer);
         return;
     }
 
@@ -152,7 +148,6 @@ void Text::loadBitmap(const char* gif_file) {
     bitmap_height_ = h;
     bitmap_ = pixels;
 
-    free(buffer);
     std::cout << "Text: bitmap loaded " << w << "x" << h << '\n';
 }
 

source/core/resources/resource_helper.cpp

@@ -0,0 +1,67 @@
+#include "core/resources/resource_helper.hpp"
+
+#include <fstream>
+#include <iostream>
+
+#include "core/jail/jfile.hpp"
+#include "core/resources/resource_pack.hpp"
+
+namespace ResourceHelper {
+
+    namespace {
+        ResourcePack pack_;
+        bool pack_loaded_ = false;
+        bool fallback_enabled_ = true;
+
+        auto readFromDisk(const std::string& relative_path) -> std::vector<uint8_t> {
+            const std::string full = std::string(file_getresourcefolder()) + relative_path;
+            std::ifstream file(full, std::ios::binary | std::ios::ate);
+            if (!file) return {};
+
+            std::streamsize size = file.tellg();
+            file.seekg(0, std::ios::beg);
+
+            std::vector<uint8_t> data(size);
+            if (!file.read(reinterpret_cast<char*>(data.data()), size)) return {};
+            return data;
+        }
+    }  // namespace
+
+    auto initializeResourceSystem(const std::string& pack_file, bool enable_fallback) -> bool {
+        fallback_enabled_ = enable_fallback;
+        pack_loaded_ = pack_.loadPack(pack_file);
+
+        if (pack_loaded_) {
+            std::cout << "ResourceHelper: pack loaded (" << pack_.getResourceCount()
+                      << " entries) from " << pack_file << '\n';
+        } else if (enable_fallback) {
+            std::cout << "ResourceHelper: no pack at " << pack_file
+                      << " — using filesystem fallback\n";
+        } else {
+            std::cerr << "ResourceHelper: FATAL — no pack at " << pack_file
+                      << " and fallback disabled\n";
+            return false;
+        }
+        return true;
+    }
+
+    void shutdownResourceSystem() {
+        pack_.clear();
+        pack_loaded_ = false;
+    }
+
+    auto loadFile(const std::string& relative_path) -> std::vector<uint8_t> {
+        if (pack_loaded_ && pack_.hasResource(relative_path)) {
+            return pack_.getResource(relative_path);
+        }
+        if (fallback_enabled_) {
+            return readFromDisk(relative_path);
+        }
+        return {};
+    }
+
+    auto hasPack() -> bool {
+        return pack_loaded_;
+    }
+
+}  // namespace ResourceHelper

source/core/resources/resource_helper.hpp

@@ -0,0 +1,27 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+// API d'alt nivell per a llegir recursos. Prova primer el pack (si està
+// carregat), després cau al fitxer solt dins `file_getresourcefolder()`
+// si el fallback està activat.
+namespace ResourceHelper {
+
+    // Inicialitza el sistema. `pack_file` és la ruta absoluta (o relativa al
+    // CWD) al fitxer de recursos. `enable_fallback` permet llegir de disc
+    // quan el pack no conté l'entrada (útil per a Debug i WASM).
+    auto initializeResourceSystem(const std::string& pack_file, bool enable_fallback) -> bool;
+
+    // Allibera el pack carregat a memòria.
+    void shutdownResourceSystem();
+
+    // Llegeix un recurs per ruta relativa (p.ex. "logo.gif", "fonts/8bithud.fnt").
+    // Retorna un vector buit si no es troba.
+    auto loadFile(const std::string& relative_path) -> std::vector<uint8_t>;
+
+    // True si el sistema es va inicialitzar amb un pack vàlid.
+    [[nodiscard]] auto hasPack() -> bool;
+
+}  // namespace ResourceHelper

source/core/resources/resource_pack.cpp

@@ -0,0 +1,220 @@
+#include "core/resources/resource_pack.hpp"
+
+#include <algorithm>
+#include <array>
+#include <filesystem>
+#include <fstream>
+#include <iostream>
+
+const std::string ResourcePack::DEFAULT_ENCRYPT_KEY = "AEE_RESOURCES__2026";
+
+namespace {
+constexpr const char* MAGIC = "AEE1";
+constexpr uint32_t VERSION = 1;
+}  // namespace
+
+ResourcePack::ResourcePack() = default;
+
+ResourcePack::~ResourcePack() {
+    clear();
+}
+
+auto ResourcePack::calculateChecksum(const std::vector<uint8_t>& data) -> uint32_t {
+    // djb2-like hash, seed 0x12345678 (idèntic a CCAE).
+    uint32_t checksum = 0x12345678;
+    for (unsigned char b : data) {
+        checksum = ((checksum << 5) + checksum) + b;
+    }
+    return checksum;
+}
+
+void ResourcePack::encryptData(std::vector<uint8_t>& data, const std::string& key) {
+    if (key.empty()) return;
+    for (size_t i = 0; i < data.size(); ++i) {
+        data[i] ^= static_cast<uint8_t>(key[i % key.length()]);
+    }
+}
+
+void ResourcePack::decryptData(std::vector<uint8_t>& data, const std::string& key) {
+    encryptData(data, key);  // XOR és simètric
+}
+
+auto ResourcePack::loadPack(const std::string& pack_file) -> bool {
+    std::ifstream file(pack_file, std::ios::binary);
+    if (!file) {
+        return false;  // No imprimim error: el caller decideix si cal fallback
+    }
+
+    std::array<char, 4> header{};
+    file.read(header.data(), 4);
+    if (std::string(header.data(), 4) != MAGIC) {
+        std::cerr << "ResourcePack: invalid pack file format (bad magic): " << pack_file << '\n';
+        return false;
+    }
+
+    uint32_t version = 0;
+    file.read(reinterpret_cast<char*>(&version), sizeof(version));
+    if (version != VERSION) {
+        std::cerr << "ResourcePack: unsupported pack version: " << version << '\n';
+        return false;
+    }
+
+    uint32_t resource_count = 0;
+    file.read(reinterpret_cast<char*>(&resource_count), sizeof(resource_count));
+
+    resources_.clear();
+    resources_.reserve(resource_count);
+
+    for (uint32_t i = 0; i < resource_count; ++i) {
+        uint32_t filename_length = 0;
+        file.read(reinterpret_cast<char*>(&filename_length), sizeof(filename_length));
+
+        std::string filename(filename_length, '\0');
+        file.read(filename.data(), filename_length);
+
+        ResourceEntry entry;
+        entry.filename = filename;
+        file.read(reinterpret_cast<char*>(&entry.offset), sizeof(entry.offset));
+        file.read(reinterpret_cast<char*>(&entry.size), sizeof(entry.size));
+        file.read(reinterpret_cast<char*>(&entry.checksum), sizeof(entry.checksum));
+
+        resources_[filename] = entry;
+    }
+
+    uint64_t data_size = 0;
+    file.read(reinterpret_cast<char*>(&data_size), sizeof(data_size));
+
+    data_.resize(data_size);
+    file.read(reinterpret_cast<char*>(data_.data()), static_cast<std::streamsize>(data_size));
+
+    decryptData(data_, DEFAULT_ENCRYPT_KEY);
+
+    loaded_ = true;
+    return true;
+}
+
+auto ResourcePack::savePack(const std::string& pack_file) -> bool {
+    std::ofstream file(pack_file, std::ios::binary);
+    if (!file) {
+        std::cerr << "ResourcePack: could not create pack file: " << pack_file << '\n';
+        return false;
+    }
+
+    file.write(MAGIC, 4);
+
+    uint32_t version = VERSION;
+    file.write(reinterpret_cast<const char*>(&version), sizeof(version));
+
+    auto resource_count = static_cast<uint32_t>(resources_.size());
+    file.write(reinterpret_cast<const char*>(&resource_count), sizeof(resource_count));
+
+    for (const auto& [filename, entry] : resources_) {
+        auto filename_length = static_cast<uint32_t>(filename.length());
+        file.write(reinterpret_cast<const char*>(&filename_length), sizeof(filename_length));
+        file.write(filename.c_str(), filename_length);
+        file.write(reinterpret_cast<const char*>(&entry.offset), sizeof(entry.offset));
+        file.write(reinterpret_cast<const char*>(&entry.size), sizeof(entry.size));
+        file.write(reinterpret_cast<const char*>(&entry.checksum), sizeof(entry.checksum));
+    }
+
+    std::vector<uint8_t> encrypted = data_;
+    encryptData(encrypted, DEFAULT_ENCRYPT_KEY);
+
+    uint64_t data_size = encrypted.size();
+    file.write(reinterpret_cast<const char*>(&data_size), sizeof(data_size));
+    file.write(reinterpret_cast<const char*>(encrypted.data()), static_cast<std::streamsize>(data_size));
+
+    return true;
+}
+
+auto ResourcePack::addFile(const std::string& filename, const std::string& filepath) -> bool {
+    std::ifstream file(filepath, std::ios::binary | std::ios::ate);
+    if (!file) {
+        std::cerr << "ResourcePack: could not open file: " << filepath << '\n';
+        return false;
+    }
+
+    std::streamsize file_size = file.tellg();
+    file.seekg(0, std::ios::beg);
+
+    std::vector<uint8_t> file_data(file_size);
+    if (!file.read(reinterpret_cast<char*>(file_data.data()), file_size)) {
+        std::cerr << "ResourcePack: could not read file: " << filepath << '\n';
+        return false;
+    }
+
+    ResourceEntry entry;
+    entry.filename = filename;
+    entry.offset = data_.size();
+    entry.size = file_data.size();
+    entry.checksum = calculateChecksum(file_data);
+
+    data_.insert(data_.end(), file_data.begin(), file_data.end());
+    resources_[filename] = entry;
+
+    return true;
+}
+
+auto ResourcePack::addDirectory(const std::string& directory) -> bool {
+    if (!std::filesystem::exists(directory)) {
+        std::cerr << "ResourcePack: directory does not exist: " << directory << '\n';
+        return false;
+    }
+
+    for (const auto& entry : std::filesystem::recursive_directory_iterator(directory)) {
+        if (!entry.is_regular_file()) continue;
+
+        std::string filepath = entry.path().string();
+        std::string filename = std::filesystem::relative(entry.path(), directory).string();
+        std::ranges::replace(filename, '\\', '/');
+
+        if (!addFile(filename, filepath)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+auto ResourcePack::getResource(const std::string& filename) -> std::vector<uint8_t> {
+    auto it = resources_.find(filename);
+    if (it == resources_.end()) return {};
+
+    const ResourceEntry& entry = it->second;
+    if (entry.offset + entry.size > data_.size()) {
+        std::cerr << "ResourcePack: invalid resource data: " << filename << '\n';
+        return {};
+    }
+
+    std::vector<uint8_t> result(data_.begin() + entry.offset,
+        data_.begin() + entry.offset + entry.size);
+
+    uint32_t checksum = calculateChecksum(result);
+    if (checksum != entry.checksum) {
+        std::cerr << "ResourcePack: checksum mismatch for: " << filename << '\n';
+    }
+
+    return result;
+}
+
+auto ResourcePack::hasResource(const std::string& filename) const -> bool {
+    return resources_.contains(filename);
+}
+
+void ResourcePack::clear() {
+    resources_.clear();
+    data_.clear();
+    loaded_ = false;
+}
+
+auto ResourcePack::getResourceCount() const -> size_t {
+    return resources_.size();
+}
+
+auto ResourcePack::getResourceList() const -> std::vector<std::string> {
+    std::vector<std::string> result;
+    result.reserve(resources_.size());
+    for (const auto& [filename, entry] : resources_) {
+        result.push_back(filename);
+    }
+    return result;
+}

source/core/resources/resource_pack.hpp

@@ -0,0 +1,52 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+// Entrada d'un recurs dins el pack (format AEE, equivalent a CCAE).
+struct ResourceEntry {
+    std::string filename;
+    uint64_t offset{0};
+    uint64_t size{0};
+    uint32_t checksum{0};
+};
+
+// Pack binari de recursos carregat a memòria. Formato:
+//   Header:   "AEE1" (4 bytes) + version uint32 + resource_count uint32
+//   Index:    per cada recurs -> filename_len uint32 + filename + offset uint64
+//             + size uint64 + checksum uint32
+//   Payload:  data_size uint64 + bytes xifrats amb XOR (DEFAULT_ENCRYPT_KEY)
+class ResourcePack {
+   public:
+    ResourcePack();
+    ~ResourcePack();
+
+    // I/O del fitxer
+    auto loadPack(const std::string& pack_file) -> bool;
+    auto savePack(const std::string& pack_file) -> bool;
+
+    // Builders usats per l'eina pack_resources
+    auto addFile(const std::string& filename, const std::string& filepath) -> bool;
+    auto addDirectory(const std::string& directory) -> bool;
+
+    [[nodiscard]] auto getResource(const std::string& filename) -> std::vector<uint8_t>;
+    [[nodiscard]] auto hasResource(const std::string& filename) const -> bool;
+
+    void clear();
+    [[nodiscard]] auto getResourceCount() const -> size_t;
+    [[nodiscard]] auto getResourceList() const -> std::vector<std::string>;
+
+    static const std::string DEFAULT_ENCRYPT_KEY;
+
+   private:
+    std::unordered_map<std::string, ResourceEntry> resources_;
+    std::vector<uint8_t> data_;
+    bool loaded_{false};
+
+    static auto calculateChecksum(const std::vector<uint8_t>& data) -> uint32_t;
+    static void encryptData(std::vector<uint8_t>& data, const std::string& key);
+    static void decryptData(std::vector<uint8_t>& data, const std::string& key);
+};

source/core/system/director.cpp

@@ -8,6 +8,7 @@
 #include "core/input/key_remap.hpp"
 #include "core/input/mouse.hpp"
 #include "core/jail/jail_audio.hpp"
+#include "core/jail/jdraw8.hpp"
 #include "core/jail/jgame.hpp"
 #include "core/jail/jinput.hpp"
 #include "core/locale/locale.hpp"
@@ -16,17 +17,91 @@
 #include "core/rendering/screen.hpp"
 #include "game/info.hpp"
 #include "game/modulegame.hpp"
-#include "game/modulesequence.hpp"
 #include "game/options.hpp"
+#include "scenes/banner_scene.hpp"
+#include "scenes/credits_scene.hpp"
+#include "scenes/intro_new_logo_scene.hpp"
+#include "scenes/intro_scene.hpp"
+#include "scenes/menu_scene.hpp"
+#include "scenes/mort_scene.hpp"
+#include "scenes/scene.hpp"
+#include "scenes/scene_registry.hpp"
+#include "scenes/secreta_scene.hpp"
+#include "scenes/slides_scene.hpp"
 
 // Cheats del joc original — declarats a jinput.cpp
 extern void JI_moveCheats(Uint8 new_key);
 
 Director* Director::instance_ = nullptr;
 
+Director::~Director() = default;
+
+void Director::initGameContext() {
+    info::ctx.num_habitacio = Options::game.habitacio_inicial;
+    info::ctx.num_piramide = Options::game.piramide_inicial;
+    info::ctx.diners = Options::game.diners_inicial;
+    info::ctx.diamants = Options::game.diamants_inicial;
+    info::ctx.vida = Options::game.vides;
+    info::ctx.momies = 0;
+    info::ctx.nou_personatge = false;
+    info::ctx.pepe_activat = false;
+
+    FILE* ini = fopen("trick.ini", "rb");
+    if (ini != nullptr) {
+        info::ctx.nou_personatge = true;
+        fclose(ini);
+    }
+}
+
+std::unique_ptr<scenes::Scene> Director::createNextScene() {
+    if (game_state_ == 0) {
+        // Gameplay. ModuleGame és una scenes::Scene des de la Phase A.
+        return std::make_unique<ModuleGame>();
+    }
+    // game_state_ == 1: dispatch al registry per num_piramide. Replica
+    // del redirect que el vell ModuleSequence::Go() feia: si el jugador
+    // arriba a la Secreta (6) sense prou diners, salta als slides de
+    // fracàs (7) abans de buscar l'escena al registry.
+    if (info::ctx.num_piramide == 6 && info::ctx.diners < 200) {
+        info::ctx.num_piramide = 7;
+    }
+    return scenes::SceneRegistry::instance().tryCreate(info::ctx.num_piramide);
+}
+
 void Director::init() {
     instance_ = new Director();
     Gamepad::init();
+
+    // Registre d'escenes. Cada entrada = un state_key (`num_piramide`)
+    // amb una factory de `scenes::Scene`. iterate() consulta aquest
+    // registry per a tots els states de seqüència (game_state_ == 1); si
+    // una clau no apareix ací, Director surt ordenadament.
+    auto& registry = scenes::SceneRegistry::instance();
+    registry.registerScene(0, [] { return std::make_unique<scenes::MenuScene>(); });
+    registry.registerScene(100, [] { return std::make_unique<scenes::MortScene>(); });
+    // BannerScene cobreix les piràmides 2..5 (el vell doBanner decideix
+    // pel switch intern llegint info::ctx.num_piramide).
+    for (int p = 2; p <= 5; ++p) {
+        registry.registerScene(p, [] { return std::make_unique<scenes::BannerScene>(); });
+    }
+    // SlidesScene cobreix els dos states on el vell `doSlides` s'invocava:
+    // - num_piramide == 1: slides narratius inicials (entrada al joc)
+    // - num_piramide == 7: slides de fracàs (ve del redirect 6→7 quan
+    //   l'usuari no té prou diners per a la Secreta)
+    registry.registerScene(1, [] { return std::make_unique<scenes::SlidesScene>(); });
+    registry.registerScene(7, [] { return std::make_unique<scenes::SlidesScene>(); });
+    registry.registerScene(6, [] { return std::make_unique<scenes::SecretaScene>(); });
+    registry.registerScene(8, [] { return std::make_unique<scenes::CreditsScene>(); });
+    // State 255 (intro): dues variants segons `Options::game.use_new_logo`.
+    // La factory tria a runtime — així es pot togglar des del menú sense
+    // re-registrar. Les dues escenes construeixen una IntroSpritesScene
+    // com a sub-escena per a la part d'animacions de sprites.
+    registry.registerScene(255, []() -> std::unique_ptr<scenes::Scene> {
+        if (Options::game.use_new_logo) {
+            return std::make_unique<scenes::IntroNewLogoScene>();
+        }
+        return std::make_unique<scenes::IntroScene>();
+    });
 }
 
 void Director::destroy() {
@@ -48,35 +123,47 @@ void Director::togglePause() {
     }
 }
 
-void Director::run() {
-    // Llança el game thread
-    game_thread_ = std::thread(&Director::gameThreadFunc, this);
+void Director::setup() {
+    // Els buffers són membres (director.hpp); només els inicialitzem.
+    std::memset(game_frame_, 0, sizeof(game_frame_));
+    std::memset(presentation_buffer_, 0, sizeof(presentation_buffer_));
+    has_frame_ = false;
+}
 
-    // Doble buffer: game_frame és el frame net del joc, presentation_buffer
-    // és el frame + overlay (es regenera cada iteració des de game_frame)
-    Uint32 game_frame[320 * 200]{};
-    Uint32 presentation_buffer[320 * 200]{};
-    bool has_frame = false;
+bool Director::iterate() {
+    if (quit_requested_) {
+        JG_QuitSignal();
+        current_scene_.reset();  // destrueix l'escena actual ordenadament
+        return false;
+    }
+
+    if (!context_initialized_) {
+        initGameContext();
+        context_initialized_ = true;
+    }
 
     constexpr Uint32 FRAME_MS_VSYNC = 16;    // ~60 FPS amb VSync
     constexpr Uint32 FRAME_MS_NO_VSYNC = 4;  // ~250 FPS sense VSync (límit superior)
 
-    // Bucle principal del director (no-bloquejant)
-    while (!game_thread_done_ && !quit_requested_) {
-        Uint32 frame_start = SDL_GetTicks();
+    const Uint32 frame_start = SDL_GetTicks();
 
-        handleEvents();
     Gamepad::update();
     KeyRemap::update();
     GlobalInputs::handle();
     Mouse::updateCursorVisibility();
 
+    // Bombeig de l'àudio: reomple l'stream de música i para els canals
+    // drenats. Substituïx el callback de SDL_AddTimer de la versió
+    // antiga — imprescindible per al port a emscripten.
+    JA_Update();
+
     // Dispara els crèdits cinematogràfics la primera vegada que el joc
-        // arriba al menú del títol (info::num_piramide == 0). Lectura no
-        // atòmica d'un int global: race benigna, tard d'1 frame en el pitjor cas.
+    // arriba al menú del títol (info::ctx.num_piramide == 0).
     static bool credits_triggered = false;
-        if (!credits_triggered && info::num_piramide == 0) {
+    if (!credits_triggered && info::ctx.num_piramide == 0) {
+        if (Options::game.show_title_credits) {
             Overlay::startCredits();
+        }
         credits_triggered = true;
     }
 
@@ -85,54 +172,89 @@ void Director::run() {
         esc_blocked_ = false;
     }
 
-        // Consumeix un frame nou si n'hi ha un disponible (no bloqueja).
-        // Si estem en pausa, no consumim: el game thread es queda bloquejat a publishFrame.
-        bool new_frame = false;
+    // Avança l'escena (si no estem pausats). En pausa, es manté l'escena
+    // congelada i re-presentem l'últim frame amb l'overlay fresc per
+    // damunt.
     if (!paused_) {
-            std::lock_guard lock(mutex_);
-            if (frame_ready_ && latest_frame_ != nullptr) {
-                memcpy(game_frame, latest_frame_, sizeof(game_frame));
-                frame_ready_ = false;
-                frame_consumed_ = true;
-                has_frame = true;
-                new_frame = true;
+        // Transicions: si l'escena actual ha acabat (o s'ha senyalat
+        // quit), llegim el seu next state i la destruïm per crear la
+        // següent a continuació.
+        if (current_scene_ && (current_scene_->done() || JG_Quitting())) {
+            game_state_ = current_scene_->nextState();
+            current_scene_.reset();
         }
+
+        // Si no hi ha escena activa, construeix la pròxima segons
+        // game_state_ i info::ctx. Si és impossible (game_state_ == -1,
+        // quit, o state no registrat), eixim del loop.
+        if (!current_scene_) {
+            if (game_state_ == -1 || JG_Quitting()) return false;
+            current_scene_ = createNextScene();
+            if (!current_scene_) return false;
+            current_scene_->onEnter();
+            last_tick_ms_ = SDL_GetTicks();
         }
-        if (new_frame) {
-            frame_consumed_cv_.notify_one();  // desbloqueja el joc
+
+        // Tick de l'escena. JI_Update refresca key_pressed/any_key; el
+        // delta_ms és el temps real transcorregut des de l'últim tick.
+        JI_Update();
+        const Uint32 now = SDL_GetTicks();
+        const int delta_ms = static_cast<int>(now - last_tick_ms_);
+        last_tick_ms_ = now;
+        current_scene_->tick(delta_ms);
+
+        // Converteix `screen` indexat → `pixel_data` ARGB amb la paleta
+        // actual. JD8_Flip ja no fa yield (Phase B.2 eliminà els fibers);
+        // ara només omple el framebuffer perquè el Director l'aprofite.
+        JD8_Flip();
+        std::memcpy(game_frame_, JD8_GetFramebuffer(), sizeof(game_frame_));
+        has_frame_ = true;
     }
 
     // Presenta sempre: parteix del frame net del joc, afegeix overlay i envia
-        if (has_frame) {
-            memcpy(presentation_buffer, game_frame, sizeof(presentation_buffer));
-            Screen::get()->present(presentation_buffer);
+    if (has_frame_) {
+        std::memcpy(presentation_buffer_, game_frame_, sizeof(presentation_buffer_));
+        Screen::get()->present(presentation_buffer_);
     }
 
-        // Límit de framerate segons VSync
-        Uint32 target_ms = Options::video.vsync ? FRAME_MS_VSYNC : FRAME_MS_NO_VSYNC;
-        Uint32 elapsed = SDL_GetTicks() - frame_start;
+    // Límit de framerate segons VSync.
+    // Nota: quan el runtime posseïx el main loop (SDL_AppIterate /
+    // emscripten), aquest SDL_Delay no és ideal. Fase 7 afegirà un mode
+    // que es basa en el timing intern de SDL en lloc del delay explícit.
+    const Uint32 target_ms = Options::video.vsync ? FRAME_MS_VSYNC : FRAME_MS_NO_VSYNC;
+    const Uint32 elapsed = SDL_GetTicks() - frame_start;
     if (elapsed < target_ms) {
         SDL_Delay(target_ms - elapsed);
     }
+
+    return true;
 }
 
-    // Assegura que el game thread ix (despertar-lo per si està esperant)
-    quit_requested_ = true;
+void Director::teardown() {
+    // Senyal de quit i descàrrega ordenada de l'escena en curs. Els
+    // destructors de cada escena són no-bloquejants — ja no fan fades
+    // bloquejants. La resta de cleanup la gestiona `destroy()`.
     JG_QuitSignal();
-    {
-        std::lock_guard lock(mutex_);
-        frame_consumed_ = true;
-    }
-    frame_consumed_cv_.notify_all();
-
-    if (game_thread_.joinable()) {
-        game_thread_.join();
-    }
+    current_scene_.reset();
 }
 
-void Director::handleEvents() {
+void Director::run() {
+    setup();
+    while (true) {
+        pollAllEvents();
+        if (!iterate()) break;
+    }
+    teardown();
+}
+
+void Director::pollAllEvents() {
     SDL_Event event;
     while (SDL_PollEvent(&event)) {
+        handleEvent(event);
+    }
+}
+
+void Director::handleEvent(const SDL_Event& event) {
     if (event.type == SDL_EVENT_QUIT) {
         JG_QuitSignal();
         requestQuit();
@@ -140,24 +262,24 @@ void Director::handleEvents() {
     // Hot-plug de gamepad
     if (event.type == SDL_EVENT_GAMEPAD_ADDED || event.type == SDL_EVENT_GAMEPAD_REMOVED) {
         Gamepad::handleEvent(event);
-            continue;
+        return;
     }
     // Salta els crèdits amb qualsevol tecla; no deixem que arribi al joc
     if (event.type == SDL_EVENT_KEY_DOWN && !event.key.repeat && Overlay::creditsActive()) {
         Overlay::cancelCredits();
-            continue;
+        return;
     }
     // Empassar-se el KEY_UP de qualsevol tecla que el menú va consumir en KEY_DOWN
     if (event.type == SDL_EVENT_KEY_UP && event.key.scancode >= 0 &&
         event.key.scancode < SDL_SCANCODE_COUNT && menu_keys_held_[event.key.scancode]) {
         menu_keys_held_[event.key.scancode] = false;
-            continue;
+        return;
     }
     // Captura de tecla (remapeig al menú): intercepta KEY_DOWN abans de tot
     if (Menu::isCapturing() && event.type == SDL_EVENT_KEY_DOWN && !event.key.repeat) {
         Menu::captureKey(event.key.scancode);
         menu_keys_held_[event.key.scancode] = true;
-            continue;
+        return;
     }
     // Pausa: F11 (o tecla configurada) pausa/reprén la simulació
     if (event.type == SDL_EVENT_KEY_DOWN && !event.key.repeat &&
@@ -165,7 +287,7 @@ void Director::handleEvents() {
         togglePause();
         Overlay::showNotification(paused_ ? Locale::get("notifications.pause") : Locale::get("notifications.resume"));
         menu_keys_held_[event.key.scancode] = true;
-            continue;
+        return;
     }
     // Menú: F12 (o tecla configurada) obre/tanca el menú flotant
     if (event.type == SDL_EVENT_KEY_DOWN && !event.key.repeat &&
@@ -173,7 +295,7 @@ void Director::handleEvents() {
         Menu::toggle();
         JI_SetInputBlocked(Menu::isOpen());
         menu_keys_held_[event.key.scancode] = true;
-            continue;
+        return;
     }
     // Si el menú està obert, consumeix tot l'input de teclat
     if (Menu::isOpen() && event.type == SDL_EVENT_KEY_DOWN && !event.key.repeat) {
@@ -190,15 +312,15 @@ void Director::handleEvents() {
             }
         }
         menu_keys_held_[event.key.scancode] = true;
-            continue;
+        return;
     }
     if (Menu::isOpen() && event.type == SDL_EVENT_KEY_UP) {
-            continue;  // no deixem passar KEY_UP al joc tampoc
+        return;  // no deixem passar KEY_UP al joc tampoc
     }
     // Allibera el bloqueig d'ESC quan l'usuari la deixa anar
     if (event.type == SDL_EVENT_KEY_UP && event.key.scancode == SDL_SCANCODE_ESCAPE && esc_swallow_until_release_) {
         esc_swallow_until_release_ = false;
-            continue;
+        return;
     }
     // ESC: interceptem KEY_DOWN per bloquejar-la ABANS que el joc la veja per polling
     if (event.type == SDL_EVENT_KEY_DOWN && event.key.scancode == SDL_SCANCODE_ESCAPE && !event.key.repeat) {
@@ -211,19 +333,18 @@ void Director::handleEvents() {
             esc_blocked_ = false;
             key_pressed_ = true;
             JG_QuitSignal();
-                // Si estem en pausa, la desactivem (sense reprendre la música,
-                // estem eixint): el game thread està bloquejat a publishFrame
-                // i necessita que Director consumeixca frames per despertar-lo
-                // i poder veure la senyal de quit.
+            // Si estem en pausa, la desactivem: el fiber del joc està
+            // congelat i necessita ser reprès per veure la senyal de
+            // quit i poder tornar de forma natural.
             paused_ = false;
         }
-            continue;  // no processa més aquest event
+        return;  // no processa més aquest event
     }
     if (event.type == SDL_EVENT_KEY_UP) {
         if (event.key.scancode == SDL_SCANCODE_ESCAPE) {
             // Ja processat a KEY_DOWN, només deixem netejar el bloqueig
             // quan l'overlay faça timeout
-                continue;
+            return;
         } else {
             // Comprova si és una tecla GUI (no passa al joc)
             const auto sc = event.key.scancode;
@@ -245,72 +366,12 @@ void Director::handleEvents() {
     }
     Mouse::handleEvent(event);
 }
-}
-
-void Director::publishFrame(Uint32* pixels) {
-    {
-        std::lock_guard lock(mutex_);
-        latest_frame_ = pixels;
-        frame_ready_ = true;
-        frame_consumed_ = false;
-    }
-    frame_produced_cv_.notify_one();
-
-    // Espera que el director consumeixca el frame
-    {
-        std::unique_lock lock(mutex_);
-        frame_consumed_cv_.wait(lock, [this] {
-            return frame_consumed_ || quit_requested_;
-        });
-    }
-}
 
 void Director::requestQuit() {
     quit_requested_ = true;
     JG_QuitSignal();
-    frame_consumed_cv_.notify_all();
-    frame_produced_cv_.notify_all();
 }
 
 auto Director::consumeKeyPressed() -> bool {
     return key_pressed_.exchange(false);
 }
-
-void Director::gameThreadFunc() {
-    info::num_habitacio = Options::game.habitacio_inicial;
-    info::num_piramide = Options::game.piramide_inicial;
-    info::diners = 0;
-    info::diamants = 0;
-    info::vida = Options::game.vides;
-    info::momies = 0;
-    info::nou_personatge = false;
-    info::pepe_activat = false;
-
-    FILE* ini = fopen("trick.ini", "rb");
-    if (ini != nullptr) {
-        info::nou_personatge = true;
-        fclose(ini);
-    }
-
-    int gameState = 1;
-    while (gameState != -1 && !quit_requested_) {
-        switch (gameState) {
-            case 0: {
-                auto* moduleGame = new ModuleGame();
-                gameState = moduleGame->Go();
-                delete moduleGame;
-                break;
-            }
-            case 1: {
-                auto* moduleSequence = new ModuleSequence();
-                gameState = moduleSequence->Go();
-                delete moduleSequence;
-                break;
-            }
-        }
-    }
-
-    game_thread_done_ = true;
-    // Despertar el director per si esperava un frame
-    frame_produced_cv_.notify_all();
-}

source/core/system/director.hpp

@@ -3,30 +3,38 @@
 #include <SDL3/SDL.h>
 
 #include <atomic>
-#include <condition_variable>
 #include <cstdint>
-#include <mutex>
-#include <thread>
+#include <memory>
 
-// El Director és el thread principal que controla la presentació i els inputs.
-// Executa el joc en un thread secundari (game thread) com si fos una "fibra emulada":
-// el joc produeix un frame, es bloqueja a JD8_Flip(), i el director el presenta
-// abans de donar-li via per produir el següent.
+#include "scenes/scene.hpp"
+
+// El Director és l'únic thread del runtime. Cada iterate() fa input →
+// tick de l'escena actual → JD8_Flip → overlay → present → sleep al frame
+// target. Totes les escenes (`scenes::Scene` i `ModuleGame`) són
+// tick-based i no bloquegen — no hi ha fibers, mutex ni condition_variable.
+// Compatible amb SDL_AppIterate i amb el futur port a emscripten.
 class Director {
    public:
     static void init();
     static void destroy();
     static auto get() -> Director*;
 
-    // Bucle principal del director. Crida des de main().
+    // Bucle principal clàssic (build natiu sense SDL_MAIN_USE_CALLBACKS).
+    // Internament crida setup() + bucle d'iterate() + teardown(). Crida des de main().
     void run();
 
-    // Invocat pel game thread des de JD8_Flip(). Bloqueja fins que el director
-    // consumeix el frame i dona via per produir el següent.
-    void publishFrame(Uint32* pixels);
+    // Punts d'entrada compatibles amb SDL_AppInit / SDL_AppIterate /
+    // SDL_AppEvent / SDL_AppQuit. Permeten que el Director siga driven
+    // per l'event loop de SDL3 en lloc d'un bucle propi — imprescindible
+    // per al port a emscripten, on el runtime posseïx el main loop.
+    void setup();
+    bool iterate();  // torna false quan el joc vol eixir
+    void teardown();
+    void handleEvent(const SDL_Event& event);
 
     // Demana l'eixida (ex: segona pulsació d'ESC o SDL_QUIT)
     void requestQuit();
+    auto isQuitRequested() const -> bool { return quit_requested_; }
 
     // Consumeix el flag de "tecla polsada" (com l'antic JI_AnyKey)
     auto consumeKeyPressed() -> bool;
@@ -34,30 +42,41 @@ class Director {
     // Indica si ESC està bloquejada (el joc no l'ha de veure)
     auto isEscBlocked() const -> bool { return esc_blocked_ || esc_swallow_until_release_; }
 
-    // Pausa: bloqueja el consum de frames del game thread + pausa la música
+    // Pausa: mentre està activa, iterate() no avança l'escena — es
+    // continua presentant el darrer frame amb overlay fresc.
     void togglePause();
     auto isPaused() const -> bool { return paused_; }
 
    private:
     Director() = default;
-    ~Director() = default;
+    ~Director();
 
     static Director* instance_;
 
-    void gameThreadFunc();
-    void handleEvents();
+    void pollAllEvents();  // drenatge amb SDL_PollEvent, només per al bucle natiu
 
-    std::thread game_thread_;
-    std::mutex mutex_;
-    std::condition_variable frame_produced_cv_;
-    std::condition_variable frame_consumed_cv_;
+    // Inicialitza info::ctx a partir de Options::game.* i comprova trick.ini.
+    // Es crida una sola vegada des d'iterate() a la primera invocació.
+    void initGameContext();
+    // Construeix l'escena apropiada segons game_state_ i info::ctx.
+    // Retorna nullptr si l'state actual no té escena registrada (bug).
+    std::unique_ptr<scenes::Scene> createNextScene();
 
-    Uint32* latest_frame_{nullptr};
-    bool frame_ready_{false};
-    bool frame_consumed_{true};
+    // Buffers persistents entre iteracions. Abans eren locals a run(),
+    // ara són membres perquè iterate() els pot reutilitzar sense tornar-los
+    // a reservar en cada crida del callback.
+    Uint32 game_frame_[320 * 200]{};
+    Uint32 presentation_buffer_[320 * 200]{};
+    bool has_frame_{false};
+
+    // Estat de l'escena actual. Abans vivia al stack del GameFiber; des
+    // de la Phase B.2 de la migració viu directament al Director.
+    std::unique_ptr<scenes::Scene> current_scene_;
+    int game_state_{1};  // 0 = gameplay (ModuleGame), 1 = via SceneRegistry, -1 = quit
+    Uint32 last_tick_ms_{0};
+    bool context_initialized_{false};
 
     std::atomic<bool> quit_requested_{false};
-    std::atomic<bool> game_thread_done_{false};
     std::atomic<bool> key_pressed_{false};
     std::atomic<bool> esc_blocked_{false};
     std::atomic<bool> paused_{false};

source/game/bola.cpp

@@ -8,26 +8,12 @@ Bola::Bola(JD8_Surface gfx, Prota* sam)
     : Sprite(gfx) {
     this->sam = sam;
 
-    this->entitat = (Entitat*)malloc(sizeof(Entitat));
-    // Frames
-    this->entitat->num_frames = 2;
-    this->entitat->frames = (Frame*)malloc(this->entitat->num_frames * sizeof(Frame));
-    this->entitat->frames[0].w = 15;
-    this->entitat->frames[0].h = 15;
-    this->entitat->frames[0].x = 30;
-    this->entitat->frames[0].y = 155;
-    this->entitat->frames[1].w = 15;
-    this->entitat->frames[1].h = 15;
-    this->entitat->frames[1].x = 45;
-    this->entitat->frames[1].y = 155;
+    entitat.frames.reserve(2);
+    entitat.frames.push_back({30, 155, 15, 15});
+    entitat.frames.push_back({45, 155, 15, 15});
 
-    // Animacions
-    this->entitat->num_animacions = 1;
-    this->entitat->animacions = (Animacio*)malloc(this->entitat->num_animacions * sizeof(Animacio));
-    this->entitat->animacions[0].num_frames = 2;
-    this->entitat->animacions[0].frames = (Uint8*)malloc(2);
-    this->entitat->animacions[0].frames[0] = 0;
-    this->entitat->animacions[0].frames[1] = 1;
+    entitat.animacions.resize(1);
+    entitat.animacions[0].frames = {0, 1};
 
     this->cur_frame = 0;
     this->o = 0;
@@ -50,14 +36,14 @@ void Bola::update() {
         // Augmentem el frame
         if (JG_GetCycleCounter() % this->cycles_per_frame == 0) {
             this->cur_frame++;
-            if (this->cur_frame == this->entitat->animacions[this->o].num_frames) this->cur_frame = 0;
+            if (this->cur_frame == entitat.animacions[this->o].frames.size()) this->cur_frame = 0;
         }
 
         // Comprovem si ha tocat a Sam
         if (this->x > (this->sam->x - 7) && this->x < (this->sam->x + 7) && this->y > (this->sam->y - 7) && this->y < (this->sam->y + 7)) {
             this->contador = 200;
-            info::vida--;
-            if (info::vida == 0) this->sam->o = 5;
+            info::ctx.vida--;
+            if (info::ctx.vida == 0) this->sam->o = 5;
         }
     } else {
         this->contador--;

source/game/defaults.hpp

@@ -57,5 +57,8 @@ namespace Defaults::Game {
     constexpr int HABITACIO_INICIAL = 1;
     constexpr int PIRAMIDE_INICIAL = 255;
     constexpr int VIDES = 5;
+    constexpr int DIAMANTS_INICIAL = 0;
+    constexpr int DINERS_INICIAL = 0;
     constexpr bool USE_NEW_LOGO = true;
+    constexpr bool SHOW_TITLE_CREDITS = true;
 }  // namespace Defaults::Game

source/game/defines.hpp

@@ -3,7 +3,7 @@
 // Textos
 namespace Texts {
     constexpr const char* WINDOW_TITLE = "© 2000 Aventures en Egipte — JailDesigner";
-    constexpr const char* VERSION = "1.1";
+    constexpr const char* VERSION = "1.11";
 }  // namespace Texts
 
 // Resolución del juego

source/game/engendro.cpp

@@ -6,33 +6,20 @@
 
 Engendro::Engendro(JD8_Surface gfx, Uint16 x, Uint16 y)
     : Sprite(gfx) {
-    this->entitat = (Entitat*)malloc(sizeof(Entitat));
-    // Frames
-    this->entitat->num_frames = 4;
-    this->entitat->frames = (Frame*)malloc(this->entitat->num_frames * sizeof(Frame));
-
-    Uint8 frame = 0;
-    for (int y = 50; y <= 65; y += 15) {
-        for (int x = 225; x <= 240; x += 15) {
-            this->entitat->frames[frame].w = 15;
-            this->entitat->frames[frame].h = 15;
-            this->entitat->frames[frame].x = x;
-            this->entitat->frames[frame].y = y;
-            frame++;
+    entitat.frames.reserve(4);
+    for (int py = 50; py <= 65; py += 15) {
+        for (int px = 225; px <= 240; px += 15) {
+            Frame f;
+            f.w = 15;
+            f.h = 15;
+            f.x = px;
+            f.y = py;
+            entitat.frames.push_back(f);
         }
     }
 
-    // Animacions
-    this->entitat->num_animacions = 1;
-    this->entitat->animacions = (Animacio*)malloc(this->entitat->num_animacions * sizeof(Animacio));
-    this->entitat->animacions[0].num_frames = 6;
-    this->entitat->animacions[0].frames = (Uint8*)malloc(6);
-    this->entitat->animacions[0].frames[0] = 0;
-    this->entitat->animacions[0].frames[1] = 1;
-    this->entitat->animacions[0].frames[2] = 2;
-    this->entitat->animacions[0].frames[3] = 3;
-    this->entitat->animacions[0].frames[4] = 2;
-    this->entitat->animacions[0].frames[5] = 1;
+    entitat.animacions.resize(1);
+    entitat.animacions[0].frames = {0, 1, 2, 3, 2, 1};
 
     this->cur_frame = 0;
     this->vida = 18;
@@ -51,7 +38,7 @@ bool Engendro::update() {
 
     if (JG_GetCycleCounter() % this->cycles_per_frame == 0) {
         this->cur_frame++;
-        if (this->cur_frame == this->entitat->animacions[this->o].num_frames) this->cur_frame = 0;
+        if (this->cur_frame == entitat.animacions[this->o].frames.size()) this->cur_frame = 0;
         this->vida--;
     }
 

source/game/info.cpp

@@ -1,13 +1,4 @@
 #include "game/info.hpp"
 
-namespace info {
-    int num_piramide;
-    int num_habitacio;
-    int diners;
-    int diamants;
-    int vida;
-    int momies;
-    int engendros;
-    bool nou_personatge;
-    bool pepe_activat;
-};  // namespace info
+// La instància `info::ctx` està definida com a `inline` al header;
+// aquest fitxer es manté per a si cal afegir lògica addicional més endavant.

source/game/info.hpp

@@ -1,13 +1,24 @@
 #pragma once
 
 namespace info {
-    extern int num_piramide;
-    extern int num_habitacio;
-    extern int diners;
-    extern int diamants;
-    extern int vida;
-    extern int momies;
-    extern int engendros;
-    extern bool nou_personatge;
-    extern bool pepe_activat;
-};  // namespace info
+
+struct GameContext {
+    int num_piramide = 0;
+    int num_habitacio = 0;
+    int diners = 0;
+    int diamants = 0;
+    int vida = 0;
+    int momies = 0;
+    int engendros = 0;
+    bool nou_personatge = false;
+    bool pepe_activat = false;
+
+    void reset() { *this = GameContext{}; }
+};
+
+// Instància única de l'estat del joc. Reemplaça les variables soltes del
+// namespace `info::` per una struct encapsulada. A Fase 5 (single-threaded)
+// es podrà passar per referència als mòduls en lloc d'accedir via singleton.
+inline GameContext ctx;
+
+}  // namespace info

source/game/mapa.cpp

@@ -26,7 +26,7 @@ Mapa::~Mapa(void) {
 }
 
 void Mapa::draw() {
-    if (info::num_piramide != 4) {
+    if (info::ctx.num_piramide != 4) {
         switch (sam->o) {
             case 0:  // Down
                 JD8_BlitCKToSurface(sam->x, sam->y, this->gfx, 15, 125 + sam->frame_pejades, 15, 1, this->fondo, 255);
@@ -88,7 +88,7 @@ bool Mapa::novaMomia() {
 void Mapa::preparaFondoEstatic() {
     // Prepara el fondo est<73>tic de l'habitaci<63>
     this->fondo = JD8_NewSurface();
-    if (info::num_piramide == 6) {
+    if (info::ctx.num_piramide == 6) {
         JD8_BlitToSurface(9, 2, this->gfx, 227, 185, 92, 7, this->fondo);  // Text "SECRETA"
     } else {
         JD8_BlitToSurface(9, 2, this->gfx, 60, 185, 39, 7, this->fondo);   // Text "NIVELL"
@@ -96,12 +96,12 @@ void Mapa::preparaFondoEstatic() {
     }
     JD8_BlitToSurface(130, 2, this->gfx, 225, 192, 19, 8, this->fondo);  // Montonet de monedes + signe '='
     JD8_BlitToSurface(220, 2, this->gfx, 160, 185, 48, 7, this->fondo);  // Text "ENERGIA"
-    if (info::diners >= 200) JD8_BlitToSurface(175, 3, this->gfx, 60, 193, 7, 6, this->fondo);
+    if (info::ctx.diners >= 200) JD8_BlitToSurface(175, 3, this->gfx, 60, 193, 7, 6, this->fondo);
 
     // Pinta taulells
     for (int y = 0; y < 11; y++) {
         for (int x = 0; x < 19; x++) {
-            switch (info::num_piramide) {
+            switch (info::ctx.num_piramide) {
                 case 1:
                     JD8_BlitToSurface(20 + (x * 15), 30 + (y * 15), this->gfx, 0, 80, 15, 15, this->fondo);
                     break;
@@ -145,7 +145,7 @@ void Mapa::preparaFondoEstatic() {
     // Pinta la porta
     JD8_BlitCKToSurface(150, 18, this->gfx, 0, 143, 15, 12, this->fondo, 255);
 
-    if (info::num_piramide == 2) {
+    if (info::ctx.num_piramide == 2) {
         JD8_BlitToSurface(5, 100, this->gfx, 30, 140, 15, 15, this->fondo);
     }
 }
@@ -157,9 +157,9 @@ void swap(Uint8& a, Uint8& b) {
 }
 
 void Mapa::preparaTombes() {
-    const Uint8 contingut = info::num_piramide == 6 ? CONTE_DIAMANT : CONTE_RES;
-    int cx = info::num_piramide == 6 ? 270 : 0;
-    int cy = info::num_piramide == 6 ? 50 : 0;
+    const Uint8 contingut = info::ctx.num_piramide == 6 ? CONTE_DIAMANT : CONTE_RES;
+    int cx = info::ctx.num_piramide == 6 ? 270 : 0;
+    int cy = info::ctx.num_piramide == 6 ? 50 : 0;
 
     for (int i = 0; i < 16; i++) {
         this->tombes[i].contingut = contingut;
@@ -171,7 +171,7 @@ void Mapa::preparaTombes() {
         this->tombes[i].x = cx;
         this->tombes[i].y = cy;
     }
-    if (info::num_piramide == 6) return;
+    if (info::ctx.num_piramide == 6) return;
     this->tombes[0].contingut = CONTE_FARAO;
     this->tombes[1].contingut = CONTE_CLAU;
     this->tombes[2].contingut = CONTE_PERGAMI;
@@ -241,7 +241,7 @@ void Mapa::comprovaCaixa(Uint8 num) {
             break;
         case CONTE_TRESOR:
             this->tombes[num].x = 100;
-            info::diners++;
+            info::ctx.diners++;
             break;
         case CONTE_FARAO:
             this->tombes[num].x = 150;
@@ -261,9 +261,9 @@ void Mapa::comprovaCaixa(Uint8 num) {
             break;
         case CONTE_DIAMANT:
             this->tombes[num].y = 70;
-            info::diamants++;
-            info::diners += VALOR_DIAMANT;
-            if (info::diamants == 16) this->farao = this->clau = true;
+            info::ctx.diamants++;
+            info::ctx.diners += VALOR_DIAMANT;
+            if (info::ctx.diamants == 16) this->farao = this->clau = true;
             break;
     }
 

source/game/marcador.cpp

@@ -9,19 +9,19 @@ Marcador::~Marcador(void) {
 }
 
 void Marcador::draw() {
-    if (info::num_piramide < 6) {
-        this->pintaNumero(55, 2, info::num_piramide);
-        this->pintaNumero(80, 2, info::num_habitacio);
+    if (info::ctx.num_piramide < 6) {
+        this->pintaNumero(55, 2, info::ctx.num_piramide);
+        this->pintaNumero(80, 2, info::ctx.num_habitacio);
     }
 
-    this->pintaNumero(149, 2, info::diners / 100);
-    this->pintaNumero(156, 2, (info::diners % 100) / 10);
-    this->pintaNumero(163, 2, info::diners % 10);
+    this->pintaNumero(149, 2, info::ctx.diners / 100);
+    this->pintaNumero(156, 2, (info::ctx.diners % 100) / 10);
+    this->pintaNumero(163, 2, info::ctx.diners % 10);
 
     if (this->sam->pergami) JD8_BlitCK(190, 1, this->gfx, 209, 185, 15, 14, 255);
 
-    JD8_BlitCK(271, 1, this->gfx, 0, 20, 15, info::vida * 3, 255);
-    if (info::vida < 5) JD8_BlitCK(271, 1 + (info::vida * 3), this->gfx, 75, 20, 15, 15 - (info::vida * 3), 255);
+    JD8_BlitCK(271, 1, this->gfx, 0, 20, 15, info::ctx.vida * 3, 255);
+    if (info::ctx.vida < 5) JD8_BlitCK(271, 1 + (info::ctx.vida * 3), this->gfx, 75, 20, 15, 15 - (info::ctx.vida * 3), 255);
 }
 
 void Marcador::pintaNumero(Uint16 x, Uint16 y, Uint8 num) {

source/game/modulegame.cpp

@@ -7,28 +7,25 @@
 #include "core/jail/jinput.hpp"
 
 ModuleGame::ModuleGame() {
-    this->gfx = JD8_LoadSurface(info::pepe_activat ? "frames2.gif" : "frames.gif");
+    this->gfx = JD8_LoadSurface(info::ctx.pepe_activat ? "frames2.gif" : "frames.gif");
     JG_SetUpdateTicks(10);
 
     this->sam = new Prota(this->gfx);
     this->mapa = new Mapa(this->gfx, this->sam);
     this->marcador = new Marcador(this->gfx, this->sam);
-    if (info::num_piramide == 2) {
+    if (info::ctx.num_piramide == 2) {
         this->bola = new Bola(this->gfx, this->sam);
     } else {
-        this->bola = NULL;
+        this->bola = nullptr;
     }
-    this->momies = NULL;
+    this->momies = nullptr;
 
-    this->final = 0;
     this->iniciarMomies();
 }
 
-ModuleGame::~ModuleGame(void) {
-    JD8_FadeOut();
-
-    if (this->bola != NULL) delete this->bola;
-    if (this->momies != NULL) {
+ModuleGame::~ModuleGame() {
+    if (this->bola != nullptr) delete this->bola;
+    if (this->momies != nullptr) {
         this->momies->clear();
         delete this->momies;
     }
@@ -39,88 +36,130 @@ ModuleGame::~ModuleGame(void) {
     JD8_FreeSurface(this->gfx);
 }
 
-int ModuleGame::Go() {
+void ModuleGame::onEnter() {
+    // Primera Draw per omplir `screen` amb el contingut del gameplay
+    // abans que el fade-in arranque. Si no, les primeres iteracions del
+    // fade interpolarien cap a una paleta amb pantalla buida.
     this->Draw();
 
-    const char* music = info::num_piramide == 3 ? "00000008.ogg" : (info::num_piramide == 2 ? "00000007.ogg" : (info::num_piramide == 6 ? "00000002.ogg" : "00000006.ogg"));
+    const char* music = info::ctx.num_piramide == 3    ? "00000008.ogg"
+                        : info::ctx.num_piramide == 2  ? "00000007.ogg"
+                        : info::ctx.num_piramide == 6  ? "00000002.ogg"
+                                                       : "00000006.ogg";
     const char* current_music = JA_GetMusicFilename();
-    if ((JA_GetMusicState() != JA_MUSIC_PLAYING) || !(strcmp(music, current_music) == 0)) {
-        int size;
-        char* buffer = file_getfilebuffer(music, size);
-        JA_PlayMusic(JA_LoadMusic((Uint8*)buffer, size, music));
+    if ((JA_GetMusicState() != JA_MUSIC_PLAYING) || !current_music ||
+        strcmp(music, current_music) != 0) {
+        auto buffer = file_readfile(music);
+        JA_PlayMusic(JA_LoadMusic(reinterpret_cast<Uint8*>(buffer.data()),
+                                  static_cast<Uint32>(buffer.size()), music));
     }
 
-    JD8_FadeToPal(JD8_LoadPalette(info::pepe_activat ? "frames2.gif" : "frames.gif"));
+    // Arranca el fade-in tick-based. El `PaletteFade` avança un pas (de
+    // 32) per cada tick; durant aquesta fase el gameplay no corre,
+    // només Draw+fade. Substituïx la crida bloquejant `JD8_FadeToPal`.
+    fade_.startFadeTo(JD8_LoadPalette(info::ctx.pepe_activat ? "frames2.gif" : "frames.gif"));
+    phase_ = Phase::FadingIn;
+}
 
-    while (this->final == 0 && !JG_Quitting()) {
+void ModuleGame::tick(int delta_ms) {
+    switch (phase_) {
+        case Phase::FadingIn:
+            // No redibuixem durant el fade: el `screen` ja va ser omplit
+            // per la Draw() d'onEnter. Només el JD8_Flip del caller muta
+            // pixel_data segons la paleta que avança pas a pas.
+            fade_.tick(delta_ms);
+            if (fade_.done()) phase_ = Phase::Playing;
+            break;
+
+        case Phase::Playing:
             this->Draw();
             this->Update();
+            if (this->final_ != 0) {
+                this->applyFinalTransitions();
+                fade_.startFadeOut();
+                phase_ = Phase::FadingOut;
+            }
+            break;
+
+        case Phase::FadingOut:
+            // No redibuixem: el `screen` té l'últim frame pintat per la
+            // fase Playing (just abans que Update() setegés `final_`).
+            // El vell `JD8_FadeOut` feia exactament això — flips amb
+            // paleta fading però sense tocar el buffer. Redibuixar ací
+            // mostraria l'estat post-Update del sprite (p.ex. el prota
+            // "tornant" davant la porta després d'haver eixit).
+            fade_.tick(delta_ms);
+            if (fade_.done()) phase_ = Phase::Done;
+            break;
+
+        case Phase::Done:
+            break;
+    }
 }
 
-    // JS_FadeOutMusic();
-
-    if (this->final == 1) {
-        info::num_habitacio++;
-        if (info::num_habitacio == 6) {
-            info::num_habitacio = 1;
-            info::num_piramide++;
-        }
-        if (info::num_piramide == 6 && info::num_habitacio == 2) info::num_piramide++;
-    } else if (this->final == 2) {
-        info::num_piramide = 100;
-    }
-
-    if (JG_Quitting()) {
-        return -1;
-    } else {
-        if (info::num_habitacio == 1 || info::num_piramide == 100 || info::num_piramide == 7) {
+int ModuleGame::nextState() const {
+    if (JG_Quitting()) return -1;
+    if (info::ctx.num_habitacio == 1 ||
+        info::ctx.num_piramide == 100 ||
+        info::ctx.num_piramide == 7) {
         return 1;
-        } else {
+    }
     return 0;
 }
+
+void ModuleGame::applyFinalTransitions() {
+    if (this->final_ == 1) {
+        info::ctx.num_habitacio++;
+        if (info::ctx.num_habitacio == 6) {
+            info::ctx.num_habitacio = 1;
+            info::ctx.num_piramide++;
+        }
+        if (info::ctx.num_piramide == 6 && info::ctx.num_habitacio == 2) info::ctx.num_piramide++;
+    } else if (this->final_ == 2) {
+        info::ctx.num_piramide = 100;
     }
 }
 
 void ModuleGame::Draw() {
+    // No crida JD8_Flip — el caller (mini-loop del fiber, o Director a
+    // Phase B.2) ho fa després de cada tick.
     this->mapa->draw();
     this->marcador->draw();
     this->sam->draw();
-    if (this->momies != NULL) this->momies->draw();
-    if (this->bola != NULL) this->bola->draw();
-
-    JD8_Flip();
+    if (this->momies != nullptr) this->momies->draw();
+    if (this->bola != nullptr) this->bola->draw();
 }
 
 void ModuleGame::Update() {
     if (JG_ShouldUpdate()) {
         JI_Update();
 
-        this->final = this->sam->update();
-        if (this->momies != NULL && this->momies->update()) {
+        this->final_ = this->sam->update();
+        if (this->momies != nullptr && this->momies->update()) {
             Momia* seguent = this->momies->next;
             delete this->momies;
             this->momies = seguent;
-            info::momies--;
+            info::ctx.momies--;
         }
-        if (this->bola != NULL) this->bola->update();
+        if (this->bola != nullptr) this->bola->update();
         this->mapa->update();
         if (this->mapa->novaMomia()) {
-            if (this->momies != NULL) {
+            if (this->momies != nullptr) {
                 this->momies->insertar(new Momia(this->gfx, true, 0, 0, this->sam));
-                info::momies++;
+                info::ctx.momies++;
             } else {
                 this->momies = new Momia(this->gfx, true, 0, 0, this->sam);
-                info::momies++;
+                info::ctx.momies++;
             }
         }
 
-        if (JI_CheatActivated("reviu")) info::vida = 5;
+        if (JI_CheatActivated("reviu")) info::ctx.vida = 5;
         if (JI_CheatActivated("alone")) {
-            if (this->momies != NULL) {
+            if (this->momies != nullptr) {
                 this->momies->clear();
                 delete this->momies;
-                this->momies = NULL;
-                info::momies = 0;
+                this->momies = nullptr;
+                info::ctx.momies = 0;
             }
         }
         if (JI_CheatActivated("obert")) {
@@ -140,18 +179,18 @@ void ModuleGame::Update() {
 }
 
 void ModuleGame::iniciarMomies() {
-    if (info::num_habitacio == 1) {
-        info::momies = 1;
+    if (info::ctx.num_habitacio == 1) {
+        info::ctx.momies = 1;
     } else {
-        info::momies++;
+        info::ctx.momies++;
     }
-    if (info::num_piramide == 6) info::momies = 8;
+    if (info::ctx.num_piramide == 6) info::ctx.momies = 8;
 
     int x = 20;
     int y = 170;
-    bool dimonis = info::num_piramide == 6;
-    for (int i = 0; i < info::momies; i++) {
-        if (this->momies == NULL) {
+    bool dimonis = info::ctx.num_piramide == 6;
+    for (int i = 0; i < info::ctx.momies; i++) {
+        if (this->momies == nullptr) {
             this->momies = new Momia(this->gfx, dimonis, x, y, this->sam);
         } else {
             this->momies->insertar(new Momia(this->gfx, dimonis, x, y, this->sam));

source/game/modulegame.hpp

@@ -6,26 +6,55 @@
 #include "game/marcador.hpp"
 #include "game/momia.hpp"
 #include "game/prota.hpp"
+#include "scenes/palette_fade.hpp"
+#include "scenes/scene.hpp"
 
-class ModuleGame {
+// Escena de gameplay pur. Reemplaça el vell `Go()` bloquejant amb
+// l'interfície `scenes::Scene` tick-based: `onEnter()` arranca la
+// música i un fade-in, el `tick()` avança un frame (Draw + Update
+// gated per JG_ShouldUpdate), i quan la partida acaba fa un fade-out
+// abans de retornar el next state.
+//
+// Tres fases internes:
+//   1. FadingIn  — fade-in 32 passos mentre el render segueix viu.
+//   2. Playing   — gameplay normal; `final_` es setja quan el prota mor
+//                  o canvia de sala. `Update()` només avança cada 10 ms
+//                  via `JG_ShouldUpdate` (ticker fix del jail).
+//   3. FadingOut — fade-out 32 passos mantenint l'últim frame visible
+//                  (substituïx el `JD8_FadeOut` bloquejant que feia el
+//                  destructor legacy).
+class ModuleGame : public scenes::Scene {
    public:
     ModuleGame();
-    ~ModuleGame(void);
+    ~ModuleGame() override;
 
-    int Go();
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return phase_ == Phase::Done; }
+    int nextState() const override;
 
    private:
-    void Draw();
-    void Update();
+    enum class Phase {
+        FadingIn,
+        Playing,
+        FadingOut,
+        Done,
+    };
+
+    void Draw();    // render a `screen`; no crida JD8_Flip (ho fa el caller)
+    void Update();  // gated per JG_ShouldUpdate
 
     void iniciarMomies();
+    void applyFinalTransitions();  // muta info::ctx quan final_ passa a !=0
 
-    Uint8 final;
-    JD8_Surface gfx;
+    Phase phase_{Phase::FadingIn};
+    scenes::PaletteFade fade_;
+    Uint8 final_{0};
+    JD8_Surface gfx{nullptr};
 
-    Mapa* mapa;
-    Prota* sam;
-    Marcador* marcador;
-    Momia* momies;
-    Bola* bola;
+    Mapa* mapa{nullptr};
+    Prota* sam{nullptr};
+    Marcador* marcador{nullptr};
+    Momia* momies{nullptr};
+    Bola* bola{nullptr};
 };

source/game/modulesequence.hpp

@@ -1,26 +0,0 @@
-#pragma once
-
-#include <SDL3/SDL.h>
-
-#include "game/info.hpp"
-
-class ModuleSequence {
-   public:
-    ModuleSequence();
-    ~ModuleSequence(void);
-
-    int Go();
-
-   private:
-    void doIntro();
-    void doIntroNewLogo();
-    void doIntroSprites(Uint8* gfx);
-    void doMenu();
-    void doSlides();
-    void doBanner();
-    void doSecreta();
-    void doCredits();
-    void doMort();
-
-    int contador;
-};

source/game/momia.cpp

@@ -9,36 +9,32 @@ Momia::Momia(JD8_Surface gfx, bool dimoni, Uint16 x, Uint16 y, Prota* sam)
     this->dimoni = dimoni;
     this->sam = sam;
 
-    this->entitat = (Entitat*)malloc(sizeof(Entitat));
-    // Frames
-    this->entitat->num_frames = 20;
-    this->entitat->frames = (Frame*)malloc(this->entitat->num_frames * sizeof(Frame));
-    Uint16 frame = 0;
+    entitat.frames.reserve(20);
     for (int y = 0; y < 4; y++) {
         for (int x = 0; x < 5; x++) {
-            this->entitat->frames[frame].w = 15;
-            this->entitat->frames[frame].h = 15;
-            if (info::num_piramide == 4) this->entitat->frames[frame].h -= 5;
-            this->entitat->frames[frame].x = (x * 15) + 75;
-            if (this->dimoni) this->entitat->frames[frame].x += 75;
-            this->entitat->frames[frame].y = 20 + (y * 15);
-            frame++;
+            Frame f;
+            f.w = 15;
+            f.h = 15;
+            if (info::ctx.num_piramide == 4) f.h -= 5;
+            f.x = (x * 15) + 75;
+            if (this->dimoni) f.x += 75;
+            f.y = 20 + (y * 15);
+            entitat.frames.push_back(f);
         }
     }
-    // Animacions
-    this->entitat->num_animacions = 4;
-    this->entitat->animacions = (Animacio*)malloc(this->entitat->num_animacions * sizeof(Animacio));
+
+    entitat.animacions.resize(4);
     for (int i = 0; i < 4; i++) {
-        this->entitat->animacions[i].num_frames = 8;
-        this->entitat->animacions[i].frames = (Uint8*)malloc(8);
-        this->entitat->animacions[i].frames[0] = 0 + (i * 5);
-        this->entitat->animacions[i].frames[1] = 1 + (i * 5);
-        this->entitat->animacions[i].frames[2] = 2 + (i * 5);
-        this->entitat->animacions[i].frames[3] = 1 + (i * 5);
-        this->entitat->animacions[i].frames[4] = 0 + (i * 5);
-        this->entitat->animacions[i].frames[5] = 3 + (i * 5);
-        this->entitat->animacions[i].frames[6] = 4 + (i * 5);
-        this->entitat->animacions[i].frames[7] = 3 + (i * 5);
+        entitat.animacions[i].frames = {
+            static_cast<Uint8>(0 + i * 5),
+            static_cast<Uint8>(1 + i * 5),
+            static_cast<Uint8>(2 + i * 5),
+            static_cast<Uint8>(1 + i * 5),
+            static_cast<Uint8>(0 + i * 5),
+            static_cast<Uint8>(3 + i * 5),
+            static_cast<Uint8>(4 + i * 5),
+            static_cast<Uint8>(3 + i * 5),
+        };
     }
 
     this->cur_frame = 0;
@@ -81,7 +77,7 @@ void Momia::draw() {
     } else {
         Sprite::draw();
 
-        if (info::num_piramide == 4) {
+        if (info::ctx.num_piramide == 4) {
             if ((JG_GetCycleCounter() % 40) < 20) {
                 JD8_BlitCK(this->x, this->y, this->gfx, 220, 80, 15, 15, 255);
             } else {
@@ -101,7 +97,7 @@ bool Momia::update() {
             this->engendro = NULL;
         }
     } else {
-        if (this->sam->o < 4 && (this->dimoni || info::num_piramide == 5 || JG_GetCycleCounter() % 2 == 0)) {
+        if (this->sam->o < 4 && (this->dimoni || info::ctx.num_piramide == 5 || JG_GetCycleCounter() % 2 == 0)) {
             if ((this->x - 20) % 65 == 0 && (this->y - 30) % 35 == 0) {
                 if (this->dimoni) {
                     if (rand() % 2 == 0) {
@@ -147,7 +143,7 @@ bool Momia::update() {
 
             if (JG_GetCycleCounter() % this->cycles_per_frame == 0) {
                 this->cur_frame++;
-                if (this->cur_frame == this->entitat->animacions[this->o].num_frames) this->cur_frame = 0;
+                if (this->cur_frame == entitat.animacions[this->o].frames.size()) this->cur_frame = 0;
             }
 
             if (this->x > (this->sam->x - 7) && this->x < (this->sam->x + 7) && this->y > (this->sam->y - 7) && this->y < (this->sam->y + 7)) {
@@ -155,8 +151,8 @@ bool Momia::update() {
                 if (this->sam->pergami) {
                     this->sam->pergami = false;
                 } else {
-                    info::vida--;
-                    if (info::vida == 0) this->sam->o = 5;
+                    info::ctx.vida--;
+                    if (info::ctx.vida == 0) this->sam->o = 5;
                 }
             }
         }
@@ -167,7 +163,7 @@ bool Momia::update() {
             Momia* seguent = this->next->next;
             delete this->next;
             this->next = seguent;
-            info::momies--;
+            info::ctx.momies--;
         }
     }
 

source/game/options.cpp

@@ -144,8 +144,14 @@ namespace Options {
             game.piramide_inicial = node["piramide_inicial"].get_value<int>();
         if (node.contains("vides"))
             game.vides = node["vides"].get_value<int>();
+        if (node.contains("diamants_inicial"))
+            game.diamants_inicial = node["diamants_inicial"].get_value<int>();
+        if (node.contains("diners_inicial"))
+            game.diners_inicial = node["diners_inicial"].get_value<int>();
         if (node.contains("use_new_logo"))
             game.use_new_logo = node["use_new_logo"].get_value<bool>();
+        if (node.contains("show_title_credits"))
+            game.show_title_credits = node["show_title_credits"].get_value<bool>();
     }
 
     // Carrega les opcions des del fitxer configurat
@@ -276,7 +282,10 @@ namespace Options {
         file << "  habitacio_inicial: " << game.habitacio_inicial << "\n";
         file << "  piramide_inicial: " << game.piramide_inicial << "\n";
         file << "  vides: " << game.vides << "\n";
+        file << "  diamants_inicial: " << game.diamants_inicial << "\n";
+        file << "  diners_inicial: " << game.diners_inicial << "\n";
         file << "  use_new_logo: " << (game.use_new_logo ? "true" : "false") << "\n";
+        file << "  show_title_credits: " << (game.show_title_credits ? "true" : "false") << "\n";
         file << "\n";
 
         // CONTROLS

source/game/options.hpp

@@ -83,7 +83,10 @@ namespace Options {
         int habitacio_inicial{Defaults::Game::HABITACIO_INICIAL};
         int piramide_inicial{Defaults::Game::PIRAMIDE_INICIAL};
         int vides{Defaults::Game::VIDES};
+        int diamants_inicial{Defaults::Game::DIAMANTS_INICIAL};
+        int diners_inicial{Defaults::Game::DINERS_INICIAL};
         bool use_new_logo{Defaults::Game::USE_NEW_LOGO};
+        bool show_title_credits{Defaults::Game::SHOW_TITLE_CREDITS};
     };
 
     // Preset PostFX

source/game/prota.cpp

@@ -7,79 +7,78 @@
 
 Prota::Prota(JD8_Surface gfx)
     : Sprite(gfx) {
-    this->entitat = (Entitat*)malloc(sizeof(Entitat));
-    this->entitat->num_frames = 82;
-    this->entitat->frames = (Frame*)malloc(this->entitat->num_frames * sizeof(Frame));
-    Uint16 frame = 0;
+    entitat.frames.reserve(82);
+
     for (int y = 0; y < 4; y++) {
         for (int x = 0; x < 5; x++) {
-            this->entitat->frames[frame].w = 15;
-            this->entitat->frames[frame].h = 15;
-            if (info::num_piramide == 4) this->entitat->frames[frame].h -= 5;
-            this->entitat->frames[frame].x = x * 15;
-            this->entitat->frames[frame].y = 20 + (y * 15);
-            frame++;
+            Frame f;
+            f.w = 15;
+            f.h = 15;
+            if (info::ctx.num_piramide == 4) f.h -= 5;
+            f.x = x * 15;
+            f.y = 20 + (y * 15);
+            entitat.frames.push_back(f);
         }
     }
     for (int y = 95; y < 185; y += 30) {
         for (int x = 60; x < 315; x += 15) {
             if (x != 300 || y != 155) {
-                this->entitat->frames[frame].w = 15;
-                this->entitat->frames[frame].h = 30;
-                if (info::num_piramide == 4) this->entitat->frames[frame].h -= 5;
-                this->entitat->frames[frame].x = x;
-                this->entitat->frames[frame].y = y;
-                frame++;
+                Frame f;
+                f.w = 15;
+                f.h = 30;
+                if (info::ctx.num_piramide == 4) f.h -= 5;
+                f.x = x;
+                f.y = y;
+                entitat.frames.push_back(f);
             }
         }
     }
     for (int y = 20; y < 50; y += 15) {
         for (int x = 225; x < 315; x += 15) {
-            this->entitat->frames[frame].w = 15;
-            this->entitat->frames[frame].h = 15;
-            if (info::num_piramide == 4) this->entitat->frames[frame].h -= 5;
-            this->entitat->frames[frame].x = x;
-            this->entitat->frames[frame].y = y;
-            frame++;
+            Frame f;
+            f.w = 15;
+            f.h = 15;
+            if (info::ctx.num_piramide == 4) f.h -= 5;
+            f.x = x;
+            f.y = y;
+            entitat.frames.push_back(f);
         }
     }
 
-    this->entitat->num_animacions = 6;
-    this->entitat->animacions = (Animacio*)malloc(this->entitat->num_animacions * sizeof(Animacio));
+    entitat.animacions.resize(6);
     for (int i = 0; i < 4; i++) {
-        this->entitat->animacions[i].num_frames = 8;
-        this->entitat->animacions[i].frames = (Uint8*)malloc(8);
-        this->entitat->animacions[i].frames[0] = 0 + (i * 5);
-        this->entitat->animacions[i].frames[1] = 1 + (i * 5);
-        this->entitat->animacions[i].frames[2] = 2 + (i * 5);
-        this->entitat->animacions[i].frames[3] = 1 + (i * 5);
-        this->entitat->animacions[i].frames[4] = 0 + (i * 5);
-        this->entitat->animacions[i].frames[5] = 3 + (i * 5);
-        this->entitat->animacions[i].frames[6] = 4 + (i * 5);
-        this->entitat->animacions[i].frames[7] = 3 + (i * 5);
+        entitat.animacions[i].frames = {
+            static_cast<Uint8>(0 + i * 5),
+            static_cast<Uint8>(1 + i * 5),
+            static_cast<Uint8>(2 + i * 5),
+            static_cast<Uint8>(1 + i * 5),
+            static_cast<Uint8>(0 + i * 5),
+            static_cast<Uint8>(3 + i * 5),
+            static_cast<Uint8>(4 + i * 5),
+            static_cast<Uint8>(3 + i * 5),
+        };
     }
-    this->entitat->animacions[4].num_frames = 50;
-    this->entitat->animacions[4].frames = (Uint8*)malloc(50);
-    for (int i = 0; i < 50; i++) this->entitat->animacions[4].frames[i] = i + 20;
 
-    this->entitat->animacions[5].num_frames = 48;
-    this->entitat->animacions[5].frames = (Uint8*)malloc(48);
-    for (int i = 0; i < 12; i++) this->entitat->animacions[5].frames[i] = i + 70;
-    for (int i = 12; i < 48; i++) this->entitat->animacions[5].frames[i] = 81;
+    entitat.animacions[4].frames.resize(50);
+    for (int i = 0; i < 50; i++) entitat.animacions[4].frames[i] = i + 20;
 
-    this->cur_frame = 0;
-    this->x = 150;
-    this->y = 30;
-    this->o = 0;
-    this->cycles_per_frame = 4;
-    this->pergami = false;
-    this->frame_pejades = 0;
+    entitat.animacions[5].frames.resize(48);
+    for (int i = 0; i < 12; i++) entitat.animacions[5].frames[i] = i + 70;
+    for (int i = 12; i < 48; i++) entitat.animacions[5].frames[i] = 81;
+
+    cur_frame = 0;
+    x = 150;
+    y = 30;
+    o = 0;
+    cycles_per_frame = 4;
+    pergami = false;
+    frame_pejades = 0;
 }
 
 void Prota::draw() {
     Sprite::draw();
 
-    if (info::num_piramide == 4 && this->o != 4) {
+    if (info::ctx.num_piramide == 4 && this->o != 4) {
         if ((JG_GetCycleCounter() % 40) < 20) {
             JD8_BlitCK(this->x, this->y, this->gfx, 220, 80, 15, 15, 255);
         } else {
@@ -132,14 +131,14 @@ Uint8 Prota::update() {
             if (this->frame_pejades == 15) this->frame_pejades = 0;
             if (JG_GetCycleCounter() % this->cycles_per_frame == 0) {
                 this->cur_frame++;
-                if (this->cur_frame == this->entitat->animacions[this->o].num_frames) this->cur_frame = 0;
+                if (this->cur_frame == entitat.animacions[this->o].frames.size()) this->cur_frame = 0;
             }
         }
         eixir = false;
     } else {
         if (JG_GetCycleCounter() % this->cycles_per_frame == 0) {
             this->cur_frame++;
-            if (this->cur_frame == this->entitat->animacions[this->o].num_frames) {
+            if (this->cur_frame == entitat.animacions[this->o].frames.size()) {
                 if (this->o == 4) {
                     eixir = 1;
                 } else {

source/game/sprite.cpp

@@ -1,26 +1,9 @@
 #include "game/sprite.hpp"
 
-#include <stdlib.h>
-
-Sprite::Sprite(JD8_Surface gfx) {
-    this->gfx = gfx;
-    this->entitat = NULL;
-}
-
-Sprite::~Sprite(void) {
-    if (this->entitat != NULL) {
-        if (this->entitat->num_frames > 0) free(this->entitat->frames);
-
-        if (this->entitat->num_animacions > 0) {
-            for (int i = 0; i < this->entitat->num_animacions; i++) {
-                if (this->entitat->animacions[i].num_frames > 0) free(this->entitat->animacions[i].frames);
-            }
-        }
-
-        free(this->entitat);
-    }
-}
+Sprite::Sprite(JD8_Surface gfx)
+    : gfx(gfx) {}
 
 void Sprite::draw() {
-    JD8_BlitCK(this->x, this->y, this->gfx, this->entitat->frames[this->entitat->animacions[this->o].frames[this->cur_frame]].x, this->entitat->frames[this->entitat->animacions[this->o].frames[this->cur_frame]].y, this->entitat->frames[this->entitat->animacions[this->o].frames[this->cur_frame]].w, this->entitat->frames[this->entitat->animacions[this->o].frames[this->cur_frame]].h, 255);
+    const Frame& f = entitat.frames[entitat.animacions[o].frames[cur_frame]];
+    JD8_BlitCK(x, y, gfx, f.x, f.y, f.w, f.h, 255);
 }

source/game/sprite.hpp

@@ -1,5 +1,7 @@
 #pragma once
 
+#include <vector>
+
 #include "core/jail/jdraw8.hpp"
 
 struct Frame {
@@ -10,31 +12,28 @@ struct Frame {
 };
 
 struct Animacio {
-    Uint8 num_frames;
-    Uint8* frames;
+    std::vector<Uint8> frames;  // índexs dins d'Entitat::frames
 };
 
 struct Entitat {
-    Uint8 num_frames;
-    Frame* frames;
-    Uint8 num_animacions;
-    Animacio* animacions;
+    std::vector<Frame> frames;
+    std::vector<Animacio> animacions;
 };
 
 class Sprite {
    public:
     Sprite(JD8_Surface gfx);
-    ~Sprite(void);
+    virtual ~Sprite() = default;
 
     void draw();
 
-    Entitat* entitat;
-    Uint8 cur_frame;
-    Uint16 x;
-    Uint16 y;
-    Uint16 o;
+    Entitat entitat;
+    Uint8 cur_frame = 0;
+    Uint16 x = 0;
+    Uint16 y = 0;
+    Uint16 o = 0;
 
    protected:
     JD8_Surface gfx;
-    Uint8 cycles_per_frame;
+    Uint8 cycles_per_frame = 1;
 };

source/main.cpp

@@ -1,4 +1,12 @@
+// Port a l'API de callbacks de SDL3: el runtime posseïx el main loop i ens
+// crida a SDL_AppInit/SDL_AppIterate/SDL_AppEvent/SDL_AppQuit. Imprescindible
+// per al port a emscripten on no podem tindre un bucle while propi al hilo
+// principal. Funciona igual en build natiu (Linux/macOS/Windows) perquè
+// SDL3 embolcalla el seu propi main loop darrere d'aquestes callbacks.
+
+#define SDL_MAIN_USE_CALLBACKS
 #include <SDL3/SDL.h>
+#include <SDL3/SDL_main.h>
 
 #include <ctime>
 #include <string>
@@ -14,8 +22,8 @@
 #include "core/system/director.hpp"
 #include "game/options.hpp"
 
-int main(int /*argc*/, char* /*args*/[]) {
-    srand(unsigned(time(NULL)));
+SDL_AppResult SDL_AppInit(void** /*appstate*/, int /*argc*/, char* /*argv*/[]) {
+    srand(unsigned(time(nullptr)));
 
     // Crea la carpeta de configuració i carrega les opcions
     file_setconfigfolder("jailgames/aee");
@@ -25,12 +33,21 @@ int main(int /*argc*/, char* /*args*/[]) {
     // (retorna Contents/Resources/) o en un executable normal (carpeta del binari).
     const char* base_path = SDL_GetBasePath();
     if (base_path) {
-        std::string data_path = std::string(base_path) + "data/";
+        const std::string data_path = std::string(base_path) + "data/";
         file_setresourcefolder(data_path.c_str());
     }
     Options::setConfigFile(std::string(file_getconfigfolder()) + "config.yaml");
     Options::loadFromFile();
 
+#ifdef __EMSCRIPTEN__
+    // MEMFS no persistix entre recàrregues: força valors sensats per a web.
+    Options::window.fullscreen = false;
+    Options::window.zoom = 1;
+    Options::video.aspect_ratio_4_3 = true;
+    Options::video.integer_scale = true;
+    Options::video.stretch_filter_linear = true;
+#endif
+
     // Carrega textos (idioma per defecte: valencià)
     Locale::load("locale/ca.yaml");
 
@@ -48,9 +65,33 @@ int main(int /*argc*/, char* /*args*/[]) {
     Overlay::init();
     Menu::init();
     Director::init();
+    Director::get()->setup();
 
-    // Arranca el Director: crea game thread, bucle principal, sincronització de frames
-    Director::get()->run();
+    return SDL_APP_CONTINUE;
+}
+
+SDL_AppResult SDL_AppIterate(void* /*appstate*/) {
+    // Una iteració del bucle del Director. Abans els events es drenaven
+    // amb SDL_PollEvent dins d'aquesta funció; ara SDL ens els lliura
+    // d'un en un via SDL_AppEvent, així que iterate() no els toca.
+    if (!Director::get()->iterate()) {
+        return SDL_APP_SUCCESS;
+    }
+    return SDL_APP_CONTINUE;
+}
+
+SDL_AppResult SDL_AppEvent(void* /*appstate*/, SDL_Event* event) {
+    if (!event) return SDL_APP_CONTINUE;
+    Director::get()->handleEvent(*event);
+    if (Director::get()->isQuitRequested()) {
+        return SDL_APP_SUCCESS;
+    }
+    return SDL_APP_CONTINUE;
+}
+
+void SDL_AppQuit(void* /*appstate*/, SDL_AppResult /*result*/) {
+    // Neteja en ordre invers al de SDL_AppInit.
+    Director::get()->teardown();
 
     Options::saveToFile();
 
@@ -61,6 +102,4 @@ int main(int /*argc*/, char* /*args*/[]) {
     JD8_Quit();
     Screen::destroy();
     JG_Finalize();
-
-    return 0;
 }

source/scenes/banner_scene.cpp

@@ -0,0 +1,71 @@
+#include "scenes/banner_scene.hpp"
+
+#include <cstdlib>
+
+#include "core/jail/jail_audio.hpp"
+#include "core/jail/jdraw8.hpp"
+#include "core/jail/jinput.hpp"
+#include "game/info.hpp"
+#include "scenes/scene_utils.hpp"
+
+namespace scenes {
+
+void BannerScene::onEnter() {
+    playMusic("00000004.ogg");
+
+    gfx_ = SurfaceHandle("ffase.gif");
+
+    JD8_ClearScreen(0);
+    // Títols superior i inferior del banner (compartits per tots els nivells)
+    JD8_Blit(81, 24, gfx_, 81, 155, 168, 21);
+    JD8_Blit(39, 150, gfx_, 39, 175, 248, 20);
+
+    // Número de piràmide: les 4 variants del vell `doBanner` es reduïxen
+    // a coordenades (sx,sy) calculades a partir de l'índex 0..3.
+    const int idx = info::ctx.num_piramide - 2;  // 2..5 → 0..3
+    if (idx >= 0 && idx <= 3) {
+        const int sx = (idx % 2) * 160;
+        const int sy = (idx / 2) * 75;
+        JD8_Blit(82, 60, gfx_, sx, sy, 160, 75);
+    }
+
+    // PaletteFade copia internament amb memcpy; alliberem la paleta temporal.
+    JD8_Palette pal = JD8_LoadPalette("ffase.gif");
+    fade_.startFadeTo(pal);
+    std::free(pal);
+
+    phase_ = Phase::FadingIn;
+    remaining_ms_ = 5000;
+}
+
+void BannerScene::tick(int delta_ms) {
+    switch (phase_) {
+        case Phase::FadingIn:
+            fade_.tick(delta_ms);
+            if (fade_.done()) phase_ = Phase::Showing;
+            break;
+
+        case Phase::Showing:
+            if (JI_AnyKey()) {
+                remaining_ms_ = 0;
+            } else {
+                remaining_ms_ -= delta_ms;
+            }
+            if (remaining_ms_ <= 0) {
+                JA_FadeOutMusic(250);
+                fade_.startFadeOut();
+                phase_ = Phase::FadingOut;
+            }
+            break;
+
+        case Phase::FadingOut:
+            fade_.tick(delta_ms);
+            if (fade_.done()) phase_ = Phase::Done;
+            break;
+
+        case Phase::Done:
+            break;
+    }
+}
+
+}  // namespace scenes

source/scenes/banner_scene.hpp

@@ -0,0 +1,40 @@
+#pragma once
+
+#include "scenes/palette_fade.hpp"
+#include "scenes/scene.hpp"
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+// Banner pre-piràmide ("PIRÀMIDE X"). Reemplaça `ModuleSequence::doBanner()`.
+//
+// Flux:
+//   1. Arranca música "00000004.ogg" i carrega ffase.gif.
+//   2. Pinta títol, subtítol i número de piràmide segons info::ctx.num_piramide.
+//   3. Fade-in de paleta.
+//   4. Mostra ~5s o fins que es polse una tecla.
+//   5. JA_FadeOutMusic(250) + fade-out de paleta.
+//   6. Retorna nextState=0 per a entrar al ModuleGame.
+//
+// Registrat al SceneRegistry amb state_keys 2..5 (els num_piramide on
+// el vell `doBanner()` es cridava).
+class BannerScene : public Scene {
+   public:
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return phase_ == Phase::Done; }
+    int nextState() const override { return 0; }
+
+   private:
+    enum class Phase { FadingIn,
+                       Showing,
+                       FadingOut,
+                       Done };
+
+    SurfaceHandle gfx_;
+    PaletteFade fade_;
+    Phase phase_{Phase::FadingIn};
+    int remaining_ms_{5000};
+};
+
+}  // namespace scenes

source/scenes/credits_scene.cpp

@@ -0,0 +1,139 @@
+#include "scenes/credits_scene.hpp"
+
+#include <cstdio>
+#include <cstdlib>
+
+#include "core/jail/jail_audio.hpp"
+#include "core/jail/jdraw8.hpp"
+#include "core/jail/jinput.hpp"
+#include "game/info.hpp"
+#include "scenes/scene_utils.hpp"
+
+namespace {
+
+// Frames del cotxe: 8 posicions dins del sprite sheet final.gif. El
+// vell doCredits tenia aquesta taula inline — la reproduïm idèntica.
+struct CocheFrame {
+    Uint16 x, y;
+};
+
+constexpr CocheFrame COCHE_FRAMES[8] = {
+    {214, 152}, {214, 104}, {214, 56}, {214, 104}, {214, 152}, {214, 8}, {108, 152}, {214, 8},
+};
+
+constexpr int CONTADOR_MAX = 3100;  // ~62 s de crèdits a 20 ms/tick
+constexpr int TICK_MS = 20;         // JG_SetUpdateTicks heretat del doSlides previ
+constexpr int BG_INDEX = 255;
+
+}  // namespace
+
+namespace scenes {
+
+CreditsScene::~CreditsScene() {
+    // No toquem la paleta activa: SetScreenPalette n'ha pres ownership.
+}
+
+void CreditsScene::onEnter() {
+    // El vell doCredits no tocava música — heretava la del doSlides
+    // previ ("00000005.ogg"). Si l'escena s'arrenca directament (test
+    // amb piramide_inicial=8) no hi ha res que heretar, així que
+    // arranquem la mateixa pista només si no sona res. Inocu en el
+    // flux normal: JA_MUSIC_PLAYING fa que no la tornem a tocar.
+    if (JA_GetMusicState() != JA_MUSIC_PLAYING) {
+        playMusic("00000005.ogg");
+    }
+
+    vaddr2_ = SurfaceHandle("final.gif");
+    vaddr3_ = SurfaceHandle("finals.gif");
+
+    JD8_Palette pal = JD8_LoadPalette("final.gif");
+    JD8_SetScreenPalette(pal);
+    // `pal` passa a ser propietat de main_palette — no l'alliberem.
+
+    phase_ = Phase::Rolling;
+    contador_ = 1;
+    contador_acc_ms_ = 0;
+}
+
+void CreditsScene::render() {
+    JD8_ClearScreen(BG_INDEX);
+
+    // Columna 1: scroll vertical del bloc (0,0,80,200) pujant des de
+    // y=200 fins que el contador supera 2750.
+    if (contador_ < 2750) {
+        JD8_BlitCKCut(115, 200 - (contador_ / 6), vaddr2_, 0, 0, 80, 200, 0);
+    }
+
+    // Columna 2: scroll vertical del bloc (85,0,120,140), arrenca
+    // a contador 1200 i s'atura (fix en y=20) a partir de 2250.
+    if ((contador_ > 1200) && (contador_ < 2280)) {
+        JD8_BlitCKCut(100, 200 - ((contador_ - 1200) / 6), vaddr2_, 85, 0, 120, 140, 0);
+    } else if (contador_ >= 2250) {
+        JD8_BlitCK(100, 20, vaddr2_, 85, 0, 120, 140, 0);
+    }
+
+    // Fons: 4 capes parallax + cotxe només si l'usuari ha aconseguit
+    // tots els diamants (final "bo"). Altrament fons estàtic.
+    if (info::ctx.diamants == 16) {
+        JD8_BlitCKScroll(50, vaddr3_, ((contador_ >> 3) % 320) + 1, 0, 50, 255);
+        JD8_BlitCKScroll(50, vaddr3_, ((contador_ >> 2) % 320) + 1, 50, 50, 255);
+        JD8_BlitCKScroll(50, vaddr3_, ((contador_ >> 1) % 320) + 1, 100, 50, 255);
+        JD8_BlitCKScroll(50, vaddr3_, (contador_ % 320) + 1, 150, 50, 255);
+
+        const CocheFrame& cf = COCHE_FRAMES[coche_.frame()];
+        JD8_BlitCK(100, 50, vaddr2_, cf.x, cf.y, 106, 48, 255);
+    } else {
+        JD8_BlitCK(0, 50, vaddr3_, 0, 0, 320, 50, 255);
+        JD8_BlitCK(0, 50, vaddr3_, 0, 50, 320, 50, 255);
+    }
+
+    // Barres de marc que cobreixen els extrems del scroll vertical.
+    JD8_FillSquare(0, 50, BG_INDEX);
+    JD8_FillSquare(100, 10, BG_INDEX);
+}
+
+void CreditsScene::writeTrickIni() {
+    FILE* ini = std::fopen("trick.ini", "wb");
+    if (ini) {
+        std::fwrite("1", 1, 1, ini);
+        std::fclose(ini);
+    }
+    info::ctx.nou_personatge = true;
+}
+
+void CreditsScene::tick(int delta_ms) {
+    switch (phase_) {
+        case Phase::Rolling: {
+            // Avancem el contador en passos discrets de 20 ms, igual
+            // que feia JG_ShouldUpdate(20) al vell doCredits.
+            contador_acc_ms_ += delta_ms;
+            while (contador_acc_ms_ >= TICK_MS) {
+                contador_acc_ms_ -= TICK_MS;
+                ++contador_;
+            }
+
+            coche_.tick(delta_ms);
+            render();
+
+            if (JI_AnyKey() || contador_ >= CONTADOR_MAX) {
+                writeTrickIni();
+                fade_.startFadeOut();
+                phase_ = Phase::FadingOut;
+            }
+            break;
+        }
+
+        case Phase::FadingOut:
+            fade_.tick(delta_ms);
+            if (fade_.done()) {
+                info::ctx.num_piramide = 255;
+                phase_ = Phase::Done;
+            }
+            break;
+
+        case Phase::Done:
+            break;
+    }
+}
+
+}  // namespace scenes

source/scenes/credits_scene.hpp

@@ -0,0 +1,52 @@
+#pragma once
+
+#include "core/jail/jdraw8.hpp"
+#include "scenes/frame_animator.hpp"
+#include "scenes/palette_fade.hpp"
+#include "scenes/scene.hpp"
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+// Crèdits finals del joc. Reemplaça `ModuleSequence::doCredits()`.
+//
+// Flux:
+//   1. Carrega final.gif (sprites de crèdits) i finals.gif (fons).
+//   2. Mostra els crèdits amb scroll vertical de 2 columnes durant
+//      ~62 segons (contador 0..3100 × 20 ms).
+//   3. Si `info::ctx.diamants == 16`, pinta addicionalment un parallax
+//      de 4 capes amb cotxe animat (8 frames). Si no, 2 blits fixos.
+//   4. Al acabar (per tecla o per contador), crea el fitxer `trick.ini`
+//      i activa `info::ctx.nou_personatge`.
+//   5. Fade-out de paleta. Torna a la intro (num_piramide = 255).
+//
+// Registrada al SceneRegistry amb state_key = 8.
+class CreditsScene : public Scene {
+   public:
+    CreditsScene() = default;
+    ~CreditsScene() override;
+
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return phase_ == Phase::Done; }
+    int nextState() const override { return 1; }
+
+   private:
+    enum class Phase { Rolling,
+                       FadingOut,
+                       Done };
+
+    void render();
+    void writeTrickIni();
+
+    SurfaceHandle vaddr2_;  // final.gif (sprites i coches)
+    SurfaceHandle vaddr3_;  // finals.gif (fons / parallax)
+    PaletteFade fade_;
+    FrameAnimator coche_{8, 60, true};  // 8 frames × 60 ms (~3 × 20 ms tick vell)
+
+    Phase phase_{Phase::Rolling};
+    int contador_{1};
+    int contador_acc_ms_{0};
+};
+
+}  // namespace scenes

source/scenes/frame_animator.cpp

@@ -0,0 +1,36 @@
+#include "scenes/frame_animator.hpp"
+
+#include <algorithm>
+
+namespace scenes {
+
+FrameAnimator::FrameAnimator(int num_frames, int frame_ms, bool loop)
+    : num_frames_(std::max(1, num_frames)),
+      frame_ms_(std::max(1, frame_ms)),
+      loop_(loop) {}
+
+void FrameAnimator::tick(int delta_ms) {
+    if (finished_) return;
+    elapsed_ms_ += delta_ms;
+    while (elapsed_ms_ >= frame_ms_) {
+        elapsed_ms_ -= frame_ms_;
+        ++current_frame_;
+        if (current_frame_ >= num_frames_) {
+            if (loop_) {
+                current_frame_ = 0;
+            } else {
+                current_frame_ = num_frames_ - 1;
+                finished_ = true;
+                return;
+            }
+        }
+    }
+}
+
+void FrameAnimator::reset() {
+    current_frame_ = 0;
+    elapsed_ms_ = 0;
+    finished_ = false;
+}
+
+}  // namespace scenes

source/scenes/frame_animator.hpp

@@ -0,0 +1,34 @@
+#pragma once
+
+namespace scenes {
+
+// Cicla per un conjunt de frames numerats (0..num_frames-1) avançant un
+// frame cada `frame_ms` mil·lisegons. No carrega ni dibuixa cap sprite —
+// només el caller sap quins frames dibuixar a partir de `frame()`.
+//
+// Usat per animacions periòdiques amb frames subsamplejats: palmeres,
+// camell, aigua, torxes, Sam caminant amb `(i/5) % fr` del codi original.
+class FrameAnimator {
+   public:
+    FrameAnimator() = default;
+    FrameAnimator(int num_frames, int frame_ms, bool loop = true);
+
+    void tick(int delta_ms);
+
+    int frame() const { return current_frame_; }
+    bool done() const { return !loop_ && finished_; }
+    int numFrames() const { return num_frames_; }
+
+    void reset();
+    void setFrameMs(int frame_ms) { frame_ms_ = frame_ms; }
+
+   private:
+    int num_frames_{1};
+    int frame_ms_{100};
+    bool loop_{true};
+    int current_frame_{0};
+    int elapsed_ms_{0};
+    bool finished_{false};
+};
+
+}  // namespace scenes

source/scenes/intro_new_logo_scene.cpp

@@ -0,0 +1,218 @@
+#include "scenes/intro_new_logo_scene.hpp"
+
+#include <cstring>
+
+#include "core/jail/jdraw8.hpp"
+#include "core/jail/jinput.hpp"
+#include "game/info.hpp"
+#include "scenes/scene_utils.hpp"
+
+namespace {
+
+// Coordenades mesurades del wordmark "Jailgames" dins logo/logo_new.gif.
+// Idèntiques a les del doIntroNewLogo vell — si canvies el logo, aquí i
+// al GIF són els únics llocs a tocar.
+constexpr int LOGO_SRC_X = 60;
+constexpr int LOGO_SRC_Y = 158;
+constexpr int LOGO_DST_Y = 78;
+constexpr int LOGO_HEIGHT = 28;
+constexpr int LETTER_WIDTHS[9] = {16, 39, 50, 69, 92, 115, 146, 169, 188};
+constexpr int CURSOR_X[9] = {77, 100, 111, 130, 153, 176, 207, 230, 249};
+constexpr int CURSOR_W = 12;
+constexpr int CURSOR_H = 3;
+constexpr int CURSOR_Y = LOGO_DST_Y + LOGO_HEIGHT - CURSOR_H;  // y = 103
+constexpr Uint8 CURSOR_COLOR = 17;                             // mateix index verd que les lletres
+
+// Timings (ms) — idèntics als de doIntroNewLogo vell.
+constexpr int INITIAL_MS = 1000;
+constexpr int REVEAL_FRAME_MS = 150;
+constexpr int FULL_LOGO_MS = 200;
+constexpr int PALETTE_CYCLE_STEP_MS = 20;
+constexpr int FINAL_WAIT_MS = 20;
+constexpr int PALETTE_CYCLE_STEPS = 256;
+
+}  // namespace
+
+namespace scenes {
+
+IntroNewLogoScene::IntroNewLogoScene() = default;
+
+IntroNewLogoScene::~IntroNewLogoScene() {
+    // No alliberem `pal_`: JD8_SetScreenPalette n'ha pres ownership i
+    // el proper SetScreenPalette / FadeToPal el lliurarà. Alliberar-lo
+    // ací provocaria double free.
+}
+
+void IntroNewLogoScene::onEnter() {
+    playMusic("00000003.ogg");
+
+    gfx_ = SurfaceHandle("logo/logo_new.gif");
+    pal_ = JD8_LoadPalette("logo/logo_new.gif");
+    JD8_SetScreenPalette(pal_);
+
+    // Surface auxiliar omplida amb el color del cursor — permet pintar
+    // el "subratllat" amb un blit normal.
+    cursor_surf_.adopt(JD8_NewSurface());
+    std::memset(cursor_surf_.get(), CURSOR_COLOR, 64000);
+
+    JD8_ClearScreen(0);
+
+    phase_ = Phase::Initial;
+    phase_acc_ms_ = 0;
+    reveal_letter_ = 0;
+    reveal_cursor_visible_ = true;
+    palette_step_ = 0;
+}
+
+void IntroNewLogoScene::render() {
+    switch (phase_) {
+        case Phase::Initial:
+            JD8_ClearScreen(0);
+            break;
+
+        case Phase::Revealing: {
+            JD8_ClearScreen(0);
+            JD8_Blit(LOGO_SRC_X, LOGO_DST_Y, gfx_, LOGO_SRC_X, LOGO_SRC_Y,
+                     LETTER_WIDTHS[reveal_letter_], LOGO_HEIGHT);
+            if (reveal_cursor_visible_) {
+                JD8_Blit(CURSOR_X[reveal_letter_], CURSOR_Y, cursor_surf_,
+                         0, 0, CURSOR_W, CURSOR_H);
+            }
+            break;
+        }
+
+        case Phase::FullLogoFlash:
+            JD8_ClearScreen(0);
+            JD8_Blit(LOGO_SRC_X, LOGO_DST_Y, gfx_, LOGO_SRC_X, LOGO_SRC_Y,
+                     LETTER_WIDTHS[8], LOGO_HEIGHT);
+            JD8_Blit(CURSOR_X[8], CURSOR_Y, cursor_surf_, 0, 0, CURSOR_W, CURSOR_H);
+            break;
+
+        case Phase::PaletteCycle:
+        case Phase::FinalWait:
+            // Logo complet sense cursor — els pixels del cursor
+            // ciclarien de color durant el cicle de paleta.
+            JD8_ClearScreen(0);
+            JD8_Blit(LOGO_SRC_X, LOGO_DST_Y, gfx_, LOGO_SRC_X, LOGO_SRC_Y,
+                     LETTER_WIDTHS[8], LOGO_HEIGHT);
+            break;
+
+        case Phase::Sprites:
+        case Phase::Done:
+            break;
+    }
+}
+
+void IntroNewLogoScene::advancePaletteCycle() {
+    // Replica exacta del ciclo de paleta del doIntroNewLogo vell sobre
+    // els índexs 16..31 (grup del verd brillant del logo).
+    for (int i = 16; i < 32; i++) {
+        if (i == 17) {
+            if (pal_[i].r < 255) pal_[i].r++;
+            if (pal_[i].g < 255) pal_[i].g++;
+            if (pal_[i].b < 255) pal_[i].b++;
+        }
+        if (pal_[i].b < pal_[i].g) pal_[i].b++;
+        if (pal_[i].b > pal_[i].g) pal_[i].b--;
+        if (pal_[i].r < pal_[i].g) pal_[i].r++;
+        if (pal_[i].r > pal_[i].g) pal_[i].r--;
+    }
+}
+
+void IntroNewLogoScene::tick(int delta_ms) {
+    // Qualsevol tecla durant el revelat o el ciclo de paleta salta
+    // TOTA la intro (inclou saltar la fase de sprites). Durant Sprites
+    // deixem que la sub-escena gestione el seu propi skip (que a més
+    // respecta la fase "final" no skippable de la variant 0).
+    if (phase_ != Phase::Sprites && phase_ != Phase::Done && JI_AnyKey()) {
+        info::ctx.num_piramide = 0;
+        phase_ = Phase::Done;
+        return;
+    }
+
+    switch (phase_) {
+        case Phase::Initial:
+            phase_acc_ms_ += delta_ms;
+            render();
+            if (phase_acc_ms_ >= INITIAL_MS) {
+                phase_ = Phase::Revealing;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::Revealing:
+            phase_acc_ms_ += delta_ms;
+            render();
+            if (phase_acc_ms_ >= REVEAL_FRAME_MS) {
+                phase_acc_ms_ = 0;
+                reveal_cursor_visible_ = !reveal_cursor_visible_;
+                // Quan acabem els dos frames d'una lletra (cursor on → off),
+                // passem a la següent lletra.
+                if (reveal_cursor_visible_) {
+                    ++reveal_letter_;
+                    if (reveal_letter_ >= 9) {
+                        phase_ = Phase::FullLogoFlash;
+                        reveal_letter_ = 8;
+                    }
+                }
+            }
+            break;
+
+        case Phase::FullLogoFlash:
+            phase_acc_ms_ += delta_ms;
+            render();
+            if (phase_acc_ms_ >= FULL_LOGO_MS) {
+                phase_ = Phase::PaletteCycle;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::PaletteCycle:
+            phase_acc_ms_ += delta_ms;
+            // Avancem passos de paleta cada 20 ms. Si el delta és gran,
+            // consumim múltiples passos en la mateixa crida.
+            while (phase_acc_ms_ >= PALETTE_CYCLE_STEP_MS &&
+                   palette_step_ < PALETTE_CYCLE_STEPS) {
+                phase_acc_ms_ -= PALETTE_CYCLE_STEP_MS;
+                advancePaletteCycle();
+                ++palette_step_;
+            }
+            render();
+            if (palette_step_ >= PALETTE_CYCLE_STEPS) {
+                phase_ = Phase::FinalWait;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::FinalWait:
+            phase_acc_ms_ += delta_ms;
+            render();
+            if (phase_acc_ms_ >= FINAL_WAIT_MS) {
+                phase_ = Phase::Sprites;
+            }
+            break;
+
+        case Phase::Sprites:
+            // Sub-escena construïda al primer tick. Transferim el gfx_
+            // per move — la sub-escena se n'ocupa fins que es destruix.
+            // Cada tick successiu delega l'animació dels sprites.
+            if (!sprites_scene_) {
+                sprites_scene_ = std::make_unique<IntroSpritesScene>(std::move(gfx_));
+                sprites_scene_->onEnter();
+            }
+            sprites_scene_->tick(delta_ms);
+            if (sprites_scene_->done()) {
+                // El vell `Go()` post-switch feia `num_piramide = 0`
+                // per passar al menú. Sense açò el while del fiber
+                // tornaria a crear IntroNewLogoScene infinitament.
+                info::ctx.num_piramide = 0;
+                phase_ = Phase::Done;
+            }
+            break;
+
+        case Phase::Done:
+            break;
+    }
+}
+
+}  // namespace scenes

source/scenes/intro_new_logo_scene.hpp

@@ -0,0 +1,68 @@
+#pragma once
+
+#include <memory>
+
+#include "core/jail/jdraw8.hpp"
+#include "scenes/intro_sprites_scene.hpp"
+#include "scenes/scene.hpp"
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+// Intro "moderna" del logo Jailgames amb revelat lletra-a-lletra +
+// ciclo de paleta final. Reemplaça `ModuleSequence::doIntroNewLogo()`.
+//
+// Flux:
+//   1. Carrega logo/logo_new.gif, arranca música "00000003.ogg" i posa
+//      la paleta directament (sense fade-in). Mostra pantalla negra 1s.
+//   2. Revelat: 9 lletres × 2 frames (amb cursor / sense cursor), 150 ms
+//      cada frame.
+//   3. Logo complet amb cursor fix 200 ms.
+//   4. Cicle de paleta de 256 passos modificant índexs 16–31 cada 20 ms.
+//   5. Espera final 20 ms.
+//   6. Transfereix el gfx_ a una `IntroSpritesScene` com a sub-escena
+//      i li delega els ticks fins que acaba (anima el prota + momia +
+//      mapa, amb 3 variants aleatòries). En acabar, setzea num_piramide
+//      = 0 per passar al menú.
+//
+// Registrada al SceneRegistry amb state_key = 255, amb una factory
+// condicional: només s'activa si `Options::game.use_new_logo == true`.
+// Si és false, la factory retorna nullptr i el gameFiberEntry cau al
+// path legacy (`ModuleSequence::doIntro()` vell).
+class IntroNewLogoScene : public Scene {
+   public:
+    IntroNewLogoScene();
+    ~IntroNewLogoScene() override;
+
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return phase_ == Phase::Done; }
+    int nextState() const override { return 1; }
+
+   private:
+    enum class Phase {
+        Initial,        // pantalla negra 1000 ms
+        Revealing,      // 9 × 2 frames × 150 ms cada un
+        FullLogoFlash,  // logo complet + cursor, 200 ms
+        PaletteCycle,   // 256 passos × 20 ms modificant paleta
+        FinalWait,      // 20 ms final
+        Sprites,        // tick delegat a IntroSpritesScene fins que acaba
+        Done,
+    };
+
+    void render();
+    void advancePaletteCycle();
+
+    SurfaceHandle gfx_;
+    SurfaceHandle cursor_surf_;
+    JD8_Palette pal_{nullptr};  // propietat transferida a main_palette via SetScreenPalette
+    std::unique_ptr<IntroSpritesScene> sprites_scene_;
+
+    Phase phase_{Phase::Initial};
+    int phase_acc_ms_{0};
+    int reveal_letter_{0};
+    bool reveal_cursor_visible_{true};
+    int palette_step_{0};
+};
+
+}  // namespace scenes

source/scenes/intro_scene.cpp

@@ -0,0 +1,218 @@
+#include "scenes/intro_scene.hpp"
+
+#include "core/jail/jdraw8.hpp"
+#include "core/jail/jinput.hpp"
+#include "game/info.hpp"
+#include "scenes/scene_utils.hpp"
+
+namespace {
+
+// Timings idèntics als del vell `doIntro()`: el JG_SetUpdateTicks(1000)
+// inicial, (100) per a les 3 primeres lletres (J, A, I), (200) per a
+// "JAIL" i el seu clear, (100) per a les 4 lletres centrals
+// (G, A, M, E) i (200) per a la resta fins al cicle de paleta.
+constexpr int INITIAL_MS = 1000;
+constexpr int PALETTE_CYCLE_STEP_MS = 20;
+constexpr int PALETTE_CYCLE_STEPS = 256;
+constexpr int FINAL_WAIT_MS = 200;
+
+// Un pas del revelat. Dos blits configurables (cos del wordmark + avió)
+// més una variant per al wordmark sencer i un flag de ClearScreen previ.
+struct RevealStep {
+    int duration_ms;
+    int body_w;    // amplada del blit body (43,78) ← (43,155, body_w, 45); 0 si s'usa wordmark
+    int plane_x;   // x del blit de l'avió (274,155, 27×45); -1 = no avió
+    bool clear;    // fa ClearScreen(0) abans dels blits
+    bool wordmark; // usa drawWordmark() en lloc del blit body (wordmark complet)
+};
+
+constexpr RevealStep REVEAL_STEPS[] = {
+    {100, 27, 68, false, false},    // J
+    {100, 53, 96, false, false},    // JA
+    {100, 66, 109, false, false},   // JAI
+    {200, 92, 136, false, false},   // JAIL
+    {200, 92, -1, true, false},     // JAIL (clear, sense avió — parpelleig)
+    {100, 118, 160, false, false},  // JAILG
+    {100, 145, 188, false, false},  // JAILGA
+    {100, 178, 221, false, false},  // JAILGAM
+    {100, 205, 248, false, false},  // JAILGAME
+    {200, 0, 274, false, true},     // JAILGAMES (wordmark complet) + avió
+    {200, 0, -1, true, true},       // JAILGAMES (clear, sense avió)
+    {200, 0, 274, false, true},     // JAILGAMES + avió (sense clear)
+    {200, 0, -1, true, true},       // JAILGAMES (clear, sense avió)
+    {200, 0, 274, false, true},     // JAILGAMES + avió (sense clear)
+    {200, 0, -1, true, true},       // JAILGAMES (clear, sense avió)
+};
+constexpr int REVEAL_COUNT = sizeof(REVEAL_STEPS) / sizeof(REVEAL_STEPS[0]);
+
+// Branca `!use_new_logo` del drawIntroWordmark de modulesequence.cpp:
+// blit únic del wordmark "JAILGAMES" complet (231×45 al destí 43,78).
+// IntroScene només s'activa quan use_new_logo == false, així que la
+// branca use_new_logo d'aquell helper aquí no es necessita.
+void drawWordmark(JD8_Surface gfx) {
+    JD8_Blit(43, 78, gfx, 43, 155, 231, 45);
+}
+
+}  // namespace
+
+namespace scenes {
+
+IntroScene::IntroScene() = default;
+
+IntroScene::~IntroScene() {
+    // No alliberem `pal_`: JD8_SetScreenPalette n'ha pres ownership i el
+    // proper SetScreenPalette / FadeToPal la lliurarà. Alliberar-la ací
+    // provocaria double free.
+}
+
+void IntroScene::onEnter() {
+    playMusic("00000003.ogg");
+
+    gfx_ = SurfaceHandle("logo.gif");
+    pal_ = JD8_LoadPalette("logo.gif");
+    JD8_SetScreenPalette(pal_);
+
+    JD8_ClearScreen(0);
+
+    phase_ = Phase::InitialWait;
+    phase_acc_ms_ = 0;
+    reveal_index_ = 0;
+    palette_step_ = 0;
+}
+
+void IntroScene::render() {
+    switch (phase_) {
+        case Phase::InitialWait:
+            JD8_ClearScreen(0);
+            break;
+
+        case Phase::Reveal: {
+            const RevealStep& s = REVEAL_STEPS[reveal_index_];
+            if (s.clear) JD8_ClearScreen(0);
+            if (s.wordmark) {
+                drawWordmark(gfx_);
+            } else if (s.body_w > 0) {
+                JD8_Blit(43, 78, gfx_, 43, 155, s.body_w, 45);
+            }
+            if (s.plane_x >= 0) {
+                JD8_Blit(s.plane_x, 78, gfx_, 274, 155, 27, 45);
+            }
+            break;
+        }
+
+        case Phase::PaletteCycle:
+        case Phase::FinalWait:
+            // Wordmark complet fix mentre cicla la paleta — l'últim
+            // pas del revelat (PAS 15) deixa la pantalla en aquest mateix
+            // estat, i el vell doIntro no redibuixava durant el cicle.
+            JD8_ClearScreen(0);
+            drawWordmark(gfx_);
+            break;
+
+        case Phase::Sprites:
+        case Phase::Done:
+            break;
+    }
+}
+
+void IntroScene::advancePaletteCycle() {
+    // Replica exacta del cicle del doIntro vell sobre pal[16..31] — el
+    // grup del verd brillant del logo. Index 17 s'acosta a blanc mentre
+    // els altres convergeixen cap al mateix gris mitjà.
+    for (int i = 16; i < 32; i++) {
+        if (i == 17) {
+            if (pal_[i].r < 255) pal_[i].r++;
+            if (pal_[i].g < 255) pal_[i].g++;
+            if (pal_[i].b < 255) pal_[i].b++;
+        }
+        if (pal_[i].b < pal_[i].g) pal_[i].b++;
+        if (pal_[i].b > pal_[i].g) pal_[i].b--;
+        if (pal_[i].r < pal_[i].g) pal_[i].r++;
+        if (pal_[i].r > pal_[i].g) pal_[i].r--;
+    }
+}
+
+void IntroScene::tick(int delta_ms) {
+    // Qualsevol tecla durant revelat/paleta salta TOTA la intro
+    // (inclou saltar la fase de sprites). Durant Sprites deixem que
+    // la sub-escena gestione el seu propi skip internament, que a més
+    // respecta la fase "final" no skippable de la variant 0.
+    if (phase_ != Phase::Sprites && phase_ != Phase::Done && JI_AnyKey()) {
+        info::ctx.num_piramide = 0;
+        phase_ = Phase::Done;
+        return;
+    }
+
+    switch (phase_) {
+        case Phase::InitialWait:
+            phase_acc_ms_ += delta_ms;
+            render();
+            if (phase_acc_ms_ >= INITIAL_MS) {
+                phase_ = Phase::Reveal;
+                phase_acc_ms_ = 0;
+                reveal_index_ = 0;
+            }
+            break;
+
+        case Phase::Reveal:
+            phase_acc_ms_ += delta_ms;
+            render();
+            if (phase_acc_ms_ >= REVEAL_STEPS[reveal_index_].duration_ms) {
+                phase_acc_ms_ = 0;
+                ++reveal_index_;
+                if (reveal_index_ >= REVEAL_COUNT) {
+                    phase_ = Phase::PaletteCycle;
+                }
+            }
+            break;
+
+        case Phase::PaletteCycle:
+            phase_acc_ms_ += delta_ms;
+            // Avancem tants passos com permet el delta, per evitar
+            // saltar-ne si el frame ha vingut lent.
+            while (phase_acc_ms_ >= PALETTE_CYCLE_STEP_MS &&
+                   palette_step_ < PALETTE_CYCLE_STEPS) {
+                phase_acc_ms_ -= PALETTE_CYCLE_STEP_MS;
+                advancePaletteCycle();
+                ++palette_step_;
+            }
+            render();
+            if (palette_step_ >= PALETTE_CYCLE_STEPS) {
+                phase_ = Phase::FinalWait;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::FinalWait:
+            phase_acc_ms_ += delta_ms;
+            render();
+            if (phase_acc_ms_ >= FINAL_WAIT_MS) {
+                phase_ = Phase::Sprites;
+            }
+            break;
+
+        case Phase::Sprites:
+            // Sub-escena construïda al vol al primer tick d'aquesta fase.
+            // Transferim el gfx_ per move — la sub-escena se n'ocupa
+            // fins que es destruix. Una vegada feta, els ticks delegats
+            // avancen l'animació dels sprites.
+            if (!sprites_scene_) {
+                sprites_scene_ = std::make_unique<IntroSpritesScene>(std::move(gfx_));
+                sprites_scene_->onEnter();
+            }
+            sprites_scene_->tick(delta_ms);
+            if (sprites_scene_->done()) {
+                // Equivalent al vell `Go()` post-switch: passem al menú.
+                // Sense açò el while del fiber tornaria a crear IntroScene
+                // infinitament amb num_piramide encara a 255.
+                info::ctx.num_piramide = 0;
+                phase_ = Phase::Done;
+            }
+            break;
+
+        case Phase::Done:
+            break;
+    }
+}
+
+}  // namespace scenes

source/scenes/intro_scene.hpp

@@ -0,0 +1,66 @@
+#pragma once
+
+#include <memory>
+
+#include "core/jail/jdraw8.hpp"
+#include "scenes/intro_sprites_scene.hpp"
+#include "scenes/scene.hpp"
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+// Intro "legacy" del wordmark JAILGAMES lletra a lletra + cicle de paleta.
+// Reemplaça `ModuleSequence::doIntro()`. S'activa quan
+// `Options::game.use_new_logo == false`; l'alternativa moderna és
+// `IntroNewLogoScene`.
+//
+// Flux:
+//   1. Carrega logo.gif, arranca música "00000003.ogg", pantalla negra
+//      1000 ms.
+//   2. Revelat: 15 passos (100 o 200 ms) que van acumulant les lletres
+//      "JAILGAMES" d'esquerra a dreta amb un avió escombrant al final
+//      de la paraula. Els passos 5, 11, 13 i 15 netegen la pantalla
+//      per generar els parpelleigs finals.
+//   3. Cicle de paleta: 256 passos × 20 ms modificant els índexs 16..31.
+//   4. Espera final 200 ms.
+//   5. Transfereix el gfx_ a una `IntroSpritesScene` com a sub-escena
+//      i li delega els ticks fins que acaba (anima el prota + momia +
+//      mapa, amb 3 variants aleatòries). En acabar, setzea num_piramide
+//      = 0 per passar al menú.
+//
+// Registrada al SceneRegistry amb state_key = 255: la mateixa factory que
+// per a IntroNewLogoScene, però retornada quan `use_new_logo == false`.
+class IntroScene : public Scene {
+   public:
+    IntroScene();
+    ~IntroScene() override;
+
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return phase_ == Phase::Done; }
+    int nextState() const override { return 1; }
+
+   private:
+    enum class Phase {
+        InitialWait,   // 1000 ms pantalla negra
+        Reveal,        // 15 passos del wordmark
+        PaletteCycle,  // 256 × 20 ms mutant pal[16..31]
+        FinalWait,     // 200 ms abans de la sub-escena de sprites
+        Sprites,       // tick delegat a IntroSpritesScene fins que acaba
+        Done,
+    };
+
+    void render();
+    void advancePaletteCycle();
+
+    SurfaceHandle gfx_;
+    JD8_Palette pal_{nullptr};  // propietat transferida a main_palette via SetScreenPalette
+    std::unique_ptr<IntroSpritesScene> sprites_scene_;
+
+    Phase phase_{Phase::InitialWait};
+    int phase_acc_ms_{0};
+    int reveal_index_{0};
+    int palette_step_{0};
+};
+
+}  // namespace scenes

source/scenes/intro_sprites_scene.cpp

@@ -0,0 +1,346 @@
+#include "scenes/intro_sprites_scene.hpp"
+
+#include <algorithm>
+#include <cstdlib>
+
+#include "core/jail/jdraw8.hpp"
+#include "core/jail/jinput.hpp"
+#include "game/options.hpp"
+
+namespace {
+
+// Duració d'un pas. El vell doIntroSprites feia JG_SetUpdateTicks(20);
+// cada iteració del seu for (i) consumia un tick de 20 ms.
+constexpr int TICK_MS = 20;
+
+// Taules de frames. Ubicacions de cada sprite dins el gfx de la intro
+// (logo.gif o logo/logo_new.gif — el layout de sprites és el mateix).
+// Cada sprite ocupa 15×15 px, disposats horitzontalment per fila.
+// Els valors són els offsets x (la y la posa l'invocador al src_y).
+// Derivats dels `fr_ani_N[i] = ...` del vell doIntroSprites.
+constexpr Uint16 fr1[] = {0, 15, 30, 45, 60, 75, 90, 105, 120, 135, 150, 165, 180};   // camina dreta (y=0)
+constexpr Uint16 fr2[] = {0, 15, 30, 45, 60, 75, 90, 105, 120, 135, 150, 165, 180};   // camina esquerra (y=15)
+constexpr Uint16 fr3[] = {0, 15, 30, 45, 60, 75, 90, 105, 120, 135, 150};             // trau mapa dreta (y=30)
+constexpr Uint16 fr4[] = {0, 15, 30, 45, 60, 75, 90, 105, 120, 135, 150};             // trau mapa esquerra (y=45)
+constexpr Uint16 fr5[] = {165, 180, 195, 210, 225, 240, 255, 270, 285, 300,
+                          300, 285, 270, 255, 240, 225, 210, 195, 180, 165};          // bot de susto (y=45, mirror)
+constexpr Uint16 fr6[] = {0, 15, 30, 45, 60, 75, 90, 105};                            // momia (y=60)
+constexpr Uint16 fr7[] = {75, 90, 105, 120, 135, 150, 165, 180, 195, 210, 225, 240, 255, 270,    // paper (y=75, idx 0..13)
+                          0, 15, 30, 45, 60, 75, 90, 105, 120, 135, 150, 165, 180, 195, 210};    // sombra (y=105, idx 14..28)
+constexpr Uint16 fr8[] = {15, 30, 45, 60};                                            // pedra (y=75)
+constexpr Uint16 fr9[] = {0, 15, 30, 45, 60, 75, 90, 105, 120, 135, 150, 165, 180, 195, 210, 225};   // prota ball (y=120)
+constexpr Uint16 fr10[] = {0, 15, 30, 45, 60, 75, 90, 105, 120, 135, 150, 165, 180, 195, 210, 225}; // momia ball (y=135)
+constexpr Uint16 fr11[] = {15, 30, 45, 60, 75, 60};                                   // altaveu (y=90, [5]=[3] pel loop de 4)
+
+constexpr Uint16 CREU = 75;          // src_y de la creu (overlay)
+constexpr Uint16 INTERROGANT = 90;   // src_y del signe d'interrogant
+
+// Equivalent de la funció `drawIntroWordmark` de modulesequence.cpp.
+// Branqueja segons use_new_logo perquè la mateixa sub-escena es
+// reutilitza des de IntroScene (logo vell) i IntroNewLogoScene (logo
+// nou) amb arxius diferents però mateix layout de sprites.
+void drawWordmark(JD8_Surface gfx) {
+    if (Options::game.use_new_logo) {
+        JD8_Blit(60, 78, gfx, 60, 158, 188, 28);
+    } else {
+        JD8_Blit(43, 78, gfx, 43, 155, 231, 45);
+    }
+}
+
+using RenderFn = void (*)(JD8_Surface, int);
+
+// Una fase — rang [start_i..end_i] inclusive (direcció implícita per
+// signe), funció de render, i flag d'skippable. Totes les fases actuals
+// són skippables; el flag es conserva per si alguna futura ha de ser
+// no interrompuda (p.ex. un logo fatídic que cal veure sencer).
+struct SpritePhase {
+    int start_i;
+    int end_i;
+    RenderFn render;
+    bool skippable;
+};
+
+// =========================================================================
+// Variant 0 — Interrogant / Momia
+// =========================================================================
+
+void v0_walk_right(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(i, 150, gfx, fr1[(i / 5) % 13], 0, 15, 15, 0);
+}
+
+void v0_pull_map_right(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(200, 150, gfx, fr3[std::min(i / 5, 10)], 30, 15, 15, 0);
+}
+
+void v0_walk_left_to_80(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(i, 150, gfx, fr2[(i / 5) % 13], 15, 15, 15, 0);
+}
+
+void v0_pull_map_left(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(80, 150, gfx, fr4[std::min(i / 5, 10)], 45, 15, 15, 0);
+}
+
+void v0_momia_left(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(i, 150, gfx, fr6[(i / 5) % 8], 60, 15, 15, 0);
+    JD8_BlitCK(80, 150, gfx, fr4[10], 45, 15, 15, 0);
+}
+
+void v0_turn(JD8_Surface gfx, int /*i*/) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(80, 150, gfx, fr1[1], 0, 15, 15, 0);
+    JD8_BlitCK(95, 150, gfx, fr6[4], 60, 15, 15, 0);
+    JD8_BlitCK(80, 133, gfx, 0, INTERROGANT, 15, 15, 0);
+}
+
+void v0_jump1(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(80, 150 - ((i % 50) / 5), gfx, fr5[std::min(i / 5, 19)], 45, 15, 15, 0);
+    JD8_BlitCK(95, 150, gfx, fr6[4], 60, 15, 15, 0);
+}
+
+void v0_jump2(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(80, 140 + ((i % 50) / 5), gfx, fr5[std::min(i / 5, 19)], 45, 15, 15, 0);
+    JD8_BlitCK(95, 150, gfx, fr6[4], 60, 15, 15, 0);
+}
+
+void v0_walk_final(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(i, 150, gfx, fr2[(i / 5) % 13], 15, 15, 15, 0);
+    JD8_BlitCK(95, 150, gfx, fr6[4], 60, 15, 15, 0);
+}
+
+void v0_final(JD8_Surface gfx, int /*i*/) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(95, 150, gfx, fr6[4], 60, 15, 15, 0);
+    JD8_BlitCK(95, 133, gfx, 0, INTERROGANT, 15, 15, 0);
+}
+
+constexpr SpritePhase variant_0[] = {
+    {0, 200, v0_walk_right, true},
+    {0, 200, v0_pull_map_right, true},
+    {200, 0, v0_pull_map_right, true},   // guarda el mapa (reprodueix inversament)
+    {200, 80, v0_walk_left_to_80, true},
+    {0, 200, v0_pull_map_left, true},
+    {300, 95, v0_momia_left, true},
+    {0, 50, v0_turn, true},
+    {0, 49, v0_jump1, true},
+    {50, 99, v0_jump2, true},
+    {80, 0, v0_walk_final, true},
+    {0, 150, v0_final, true},
+};
+
+// =========================================================================
+// Variant 1 — Creu / Pedra
+// =========================================================================
+
+void v1_walk_right(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(200, 155, gfx, 0, CREU, 15, 15, 255);
+    JD8_BlitCK(i, 150, gfx, fr1[(i / 5) % 13], 0, 15, 15, 255);
+}
+
+void v1_pull_map(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(200, 155, gfx, 0, CREU, 15, 15, 255);
+    JD8_BlitCK(200, 150, gfx, fr3[std::min(i / 5, 10)], 30, 15, 15, 255);
+}
+
+void v1_interrogant(JD8_Surface gfx, int /*i*/) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(200, 155, gfx, 0, CREU, 15, 15, 255);
+    JD8_BlitCK(200, 134, gfx, 0, INTERROGANT, 15, 15, 255);
+    JD8_BlitCK(200, 150, gfx, fr3[10], 30, 15, 15, 255);
+}
+
+void v1_drop_map(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(200, 155, gfx, 0, CREU, 15, 15, 255);
+    const int idx = std::min(i / 5, 28);
+    // fr7 té 29 frames dividits en dos grups: paper (idx 0..13, src_y=75)
+    // i sombra (idx 14..28, src_y=105). El vell feia una branca al bucle.
+    if (idx <= 13) {
+        JD8_BlitCK(200, 150, gfx, fr7[idx], 75, 15, 15, 255);
+    } else {
+        JD8_BlitCK(200, 150, gfx, fr7[idx], 105, 15, 15, 255);
+    }
+}
+
+void v1_stone_fall(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(200, 155, gfx, 0, CREU, 15, 15, 255);
+    JD8_BlitCK(200, 150, gfx, fr7[28], 105, 15, 15, 255);
+    JD8_BlitCK(200, i * 2, gfx, fr8[0], 75, 15, 15, 255);
+}
+
+void v1_stone_break(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(200, 155, gfx, 0, CREU, 15, 15, 255);
+    JD8_BlitCK(200, 150, gfx, fr8[i / 10], 75, 15, 15, 255);
+}
+
+void v1_final(JD8_Surface gfx, int /*i*/) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(200, 155, gfx, 0, CREU, 15, 15, 255);
+    JD8_BlitCK(200, 150, gfx, fr8[1], 75, 15, 15, 255);
+    JD8_BlitCK(185, 150, gfx, fr8[2], 75, 15, 15, 255);
+    JD8_BlitCK(215, 150, gfx, fr8[3], 75, 15, 15, 255);
+}
+
+constexpr SpritePhase variant_1[] = {
+    {0, 200, v1_walk_right, true},
+    {0, 300, v1_pull_map, true},
+    {0, 100, v1_interrogant, true},
+    {0, 200, v1_drop_map, true},
+    {0, 75, v1_stone_fall, true},
+    {0, 19, v1_stone_break, true},
+    {0, 200, v1_final, true},
+};
+
+// =========================================================================
+// Variant 2 — Ball de carnaval
+// =========================================================================
+
+void v2_approach(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(i, 150, gfx, fr1[(i / 5) % 13], 0, 15, 15, 255);
+    JD8_BlitCK(304 - i, 150, gfx, fr6[(i / 10) % 8], 60, 15, 15, 255);
+}
+
+void v2_still(JD8_Surface gfx, int /*i*/) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(145, 150, gfx, fr1[1], 0, 15, 15, 255);
+    JD8_BlitCK(160, 150, gfx, fr6[1], 60, 15, 15, 255);
+}
+
+void v2_horn(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(125, 150, gfx, fr11[(i / 10) % 2], 90, 15, 15, 255);
+    JD8_BlitCK(145, 150, gfx, fr1[1], 0, 15, 15, 255);
+    JD8_BlitCK(160, 150, gfx, fr6[1], 60, 15, 15, 255);
+}
+
+void v2_ball(JD8_Surface gfx, int i) {
+    JD8_ClearScreen(0);
+    drawWordmark(gfx);
+    JD8_BlitCK(145, 150, gfx, fr9[(i / 10) % 16], 120, 15, 15, 255);
+    JD8_BlitCK(160, 150, gfx, fr10[(i / 10) % 16], 135, 15, 15, 255);
+    JD8_BlitCK(125, 150, gfx, fr11[((i / 5) % 4) + 2], 90, 15, 15, 255);
+}
+
+constexpr SpritePhase variant_2[] = {
+    {0, 145, v2_approach, true},
+    {0, 100, v2_still, true},
+    {0, 50, v2_horn, true},
+    {0, 800, v2_ball, true},
+};
+
+// =========================================================================
+// Dispatch per variant
+// =========================================================================
+
+const SpritePhase* variant_table(int variant) {
+    switch (variant) {
+        case 0: return variant_0;
+        case 1: return variant_1;
+        case 2: return variant_2;
+    }
+    return variant_0;
+}
+
+int variant_length(int variant) {
+    switch (variant) {
+        case 0: return sizeof(variant_0) / sizeof(variant_0[0]);
+        case 1: return sizeof(variant_1) / sizeof(variant_1[0]);
+        case 2: return sizeof(variant_2) / sizeof(variant_2[0]);
+    }
+    return 0;
+}
+
+int phase_step_count(const SpritePhase& p) {
+    return std::abs(p.end_i - p.start_i) + 1;
+}
+
+int phase_current_i(const SpritePhase& p, int step) {
+    return p.end_i >= p.start_i ? p.start_i + step : p.start_i - step;
+}
+
+}  // namespace
+
+namespace scenes {
+
+IntroSpritesScene::IntroSpritesScene(SurfaceHandle&& gfx)
+    : gfx_(std::move(gfx)) {}
+
+void IntroSpritesScene::onEnter() {
+    // El vell doIntroSprites feia `rand() % 3` al principi. El seed ve
+    // establert per `srand(time(0))` al boot del joc (info.cpp / main),
+    // així que la variant canvia entre execucions.
+    variant_ = std::rand() % 3;
+    phase_ = 0;
+    phase_step_ = 0;
+    step_acc_ms_ = 0;
+    done_ = false;
+
+    // Renderitzem ja el primer frame (step 0 de la primera fase) perquè
+    // el JD8_Flip del mini-loop del fiber el pinte al primer cicle.
+    const SpritePhase* phases = variant_table(variant_);
+    phases[0].render(gfx_.get(), phase_current_i(phases[0], 0));
+}
+
+void IntroSpritesScene::tick(int delta_ms) {
+    if (done_) return;
+
+    const SpritePhase* phases = variant_table(variant_);
+    const int num_phases = variant_length(variant_);
+
+    // Skip per tecla. Durant la fase marcada com a no skippable (només
+    // v0_final al vell codi) s'ignora — preserva la semàntica del vell
+    // bucle final de la variant 0 que no cridava wait_frame_or_skip.
+    if (phases[phase_].skippable && JI_AnyKey()) {
+        done_ = true;
+        return;
+    }
+
+    step_acc_ms_ += delta_ms;
+    while (step_acc_ms_ >= TICK_MS && !done_) {
+        step_acc_ms_ -= TICK_MS;
+        ++phase_step_;
+        if (phase_step_ >= phase_step_count(phases[phase_])) {
+            ++phase_;
+            phase_step_ = 0;
+            if (phase_ >= num_phases) {
+                done_ = true;
+                return;
+            }
+        }
+    }
+    phases[phase_].render(gfx_.get(), phase_current_i(phases[phase_], phase_step_));
+}
+
+}  // namespace scenes

source/scenes/intro_sprites_scene.hpp

@@ -0,0 +1,43 @@
+#pragma once
+
+#include "scenes/scene.hpp"
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+// Sub-escena de sprites de la intro (prota + momia + mapa + etc).
+// Reemplaça `ModuleSequence::doIntroSprites()`. No es registra al
+// SceneRegistry — es construeix com a membre de `IntroScene` o
+// `IntroNewLogoScene` quan aquestes completen el seu revelat del logo.
+// Rep el `SurfaceHandle` del gfx de la intro via move, de manera que
+// quan acabe l'escena el surface es lliberarà automàticament.
+//
+// En entrar tria una de 3 variants (`rand() % 3`): "interrogant/momia",
+// "creu/pedra" o "ball de carnaval". Cada variant té un nombre
+// diferent de fases però comparteixen el mateix motor: un comptador
+// `step` que s'incrementa cada 20 ms, amb una taula per variant que
+// mapeja (rang d'i, renderer) a cada fase. Qualsevol tecla salta
+// l'escena — el flag `skippable` per fase es manté com a mecanisme
+// per si alguna fase futura ha de ser no interrompuda (al vell codi
+// la fase "final" de la variant 0 no cridava wait_frame_or_skip, cosa
+// molt probablement un oversight: ací es tracta com a skippable).
+class IntroSpritesScene : public Scene {
+   public:
+    explicit IntroSpritesScene(SurfaceHandle&& gfx);
+    ~IntroSpritesScene() override = default;
+
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return done_; }
+    int nextState() const override { return 1; }
+
+   private:
+    SurfaceHandle gfx_;
+    int variant_{0};       // 0..2 — triada a onEnter() amb rand() % 3
+    int phase_{0};         // índex dins la variant actual
+    int phase_step_{0};    // passos consumits dins la fase actual
+    int step_acc_ms_{0};   // acumulador per emetre steps de 20 ms
+    bool done_{false};
+};
+
+}  // namespace scenes

source/scenes/menu_scene.cpp

@@ -0,0 +1,113 @@
+#include "scenes/menu_scene.hpp"
+
+#include <cstdlib>
+
+#include "core/jail/jdraw8.hpp"
+#include "core/jail/jinput.hpp"
+#include "game/info.hpp"
+
+namespace scenes {
+
+void MenuScene::onEnter() {
+    fondo_ = SurfaceHandle("menu.gif");
+    gfx_ = SurfaceHandle("menu2.gif");
+
+    // Pintat inicial (congelat durant el fade-in de paleta). El loop
+    // d'animació repintarà tot des de zero en el primer tick de Showing.
+    JD8_Blit(fondo_);
+    JD8_BlitCK(100, 25, gfx_, 0, 74, 124, 68, 255);  // logo
+    JD8_BlitCK(130, 100, gfx_, 0, 0, 80, 74, 255);   // camell (frame 0)
+    JD8_BlitCK(0, 150, gfx_, 0, 150, 320, 50, 255);  // base "jdes"
+
+    JD8_Palette pal = JD8_LoadPalette("menu2.gif");
+    fade_.startFadeTo(pal);
+    std::free(pal);
+
+    phase_ = Phase::FadingIn;
+}
+
+void MenuScene::render() {
+    // Cel estàtic (els primers 100 pixels verticals)
+    JD8_Blit(0, 0, fondo_, 0, 0, 320, 100);
+
+    // Fondo mòvil (horitzó) amb wrap a 320
+    JD8_BlitCK(horitzo_, 100, fondo_, 0, 100, 320 - horitzo_, 100, 255);
+    JD8_BlitCK(0, 100, fondo_, 320 - horitzo_, 100, horitzo_, 100, 255);
+
+    // Logo i camell animat
+    JD8_BlitCK(100, 25, gfx_, 0, 74, 124, 68, 255);
+    JD8_BlitCK(130, 100, gfx_, camello_.frame() * 80, 0, 80, 74, 255);
+
+    // Palmeres mòvils amb wrap a 320
+    JD8_BlitCK(palmeres_, 150, gfx_, 0, 150, 320 - palmeres_, 50, 255);
+    JD8_BlitCK(0, 150, gfx_, 320 - palmeres_, 150, palmeres_, 50, 255);
+
+    // "jdes" estàtic (davant dels scrollers) i versió a la cantonada
+    JD8_BlitCK(87, 167, gfx_, 127, 124, 150, 24, 255);
+    JD8_BlitCK(303, 193, gfx_, 305, 143, 15, 5, 255);
+
+    // "Polsa tecla" parpallejant. Al vell `contador % 100 > 30` amb
+    // updateTicks=20 ms, el cicle són 2000 ms amb un llindar de 600 ms:
+    // amagat els primers 600 ms, visible els següents 1400 ms.
+    const bool blink_on = (blink_ms_ % 2000) > 600;
+    if (blink_on) {
+        JD8_BlitCK(98, 130, gfx_, 161, 92, 127, 9, 255);
+        if (info::ctx.nou_personatge) {
+            JD8_BlitCK(68, 141, gfx_, 128, 105, 189, 9, 255);
+        }
+    }
+}
+
+void MenuScene::tick(int delta_ms) {
+    switch (phase_) {
+        case Phase::FadingIn:
+            fade_.tick(delta_ms);
+            if (fade_.done()) phase_ = Phase::Showing;
+            break;
+
+        case Phase::Showing: {
+            // Palmeres: 1 pixel cada 80 ms (= cada 4 ticks × 20 ms originals)
+            palmeres_acc_ms_ += delta_ms;
+            while (palmeres_acc_ms_ >= 80) {
+                palmeres_acc_ms_ -= 80;
+                if (--palmeres_ < 0) palmeres_ = 319;
+            }
+
+            // Horitzó: 1 pixel cada 320 ms (= cada 16 ticks × 20 ms)
+            horitzo_acc_ms_ += delta_ms;
+            while (horitzo_acc_ms_ >= 320) {
+                horitzo_acc_ms_ -= 320;
+                if (--horitzo_ < 0) horitzo_ = 319;
+            }
+
+            camello_.tick(delta_ms);
+
+            blink_ms_ += delta_ms;
+            if (blink_ms_ >= 2000) blink_ms_ %= 2000;
+
+            render();
+
+            // Qualsevol tecla tanca el menú. Llegim 'P' explícitament abans
+            // de reiniciar el flag de input perquè `info::ctx.pepe_activat`
+            // reflecteixca si l'usuari estava polsant P al moment d'eixir.
+            if (JI_AnyKey() || JI_KeyPressed(SDL_SCANCODE_P)) {
+                info::ctx.pepe_activat = JI_KeyPressed(SDL_SCANCODE_P);
+                JI_DisableKeyboard(60);
+                info::ctx.num_piramide = 1;
+                fade_.startFadeOut();
+                phase_ = Phase::FadingOut;
+            }
+            break;
+        }
+
+        case Phase::FadingOut:
+            fade_.tick(delta_ms);
+            if (fade_.done()) phase_ = Phase::Done;
+            break;
+
+        case Phase::Done:
+            break;
+    }
+}
+
+}  // namespace scenes

source/scenes/menu_scene.hpp

@@ -0,0 +1,57 @@
+#pragma once
+
+#include "scenes/frame_animator.hpp"
+#include "scenes/palette_fade.hpp"
+#include "scenes/scene.hpp"
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+// Menú del títol. Reemplaça `ModuleSequence::doMenu()`.
+//
+// Flux:
+//   1. Carrega menu.gif (fondo) i menu2.gif (sprites) + paleta.
+//   2. Pintat inicial estàtic (fondo, logo, camell frame 0, base "jdes"),
+//      fade-in de paleta.
+//   3. Loop d'animació: escroll parallax de horitzó (cada 320 ms) i
+//      palmeres (cada 80 ms), cicle del camell (4 frames × 160 ms),
+//      i el text "polsa tecla" parpallejant cada 2 s (visible 1.4 s,
+//      amagat 0.6 s, igual que el `contador % 100 > 30` original).
+//   4. Quan l'usuari polsa qualsevol tecla — o 'P' per a activar Pepe —
+//      llegim `info::ctx.pepe_activat`, disparem fade-out i marquem
+//      num_piramide=1 (vas a doSlides).
+//
+// Registrat al SceneRegistry amb state_key = 0.
+class MenuScene : public Scene {
+   public:
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return phase_ == Phase::Done; }
+    int nextState() const override { return 1; }
+
+   private:
+    enum class Phase { FadingIn,
+                       Showing,
+                       FadingOut,
+                       Done };
+
+    void render();
+
+    SurfaceHandle fondo_;
+    SurfaceHandle gfx_;
+    PaletteFade fade_;
+    FrameAnimator camello_{4, 160, true};
+
+    Phase phase_{Phase::FadingIn};
+
+    // Scrollers horizontals. Mouen 1 pixel per pas.
+    int palmeres_{0};
+    int horitzo_{0};
+    int palmeres_acc_ms_{0};
+    int horitzo_acc_ms_{0};
+
+    // Acumulador per al parpalleig del text "polsa tecla".
+    int blink_ms_{0};
+};
+
+}  // namespace scenes

source/scenes/mort_scene.cpp

@@ -0,0 +1,64 @@
+#include "scenes/mort_scene.hpp"
+
+#include <cstdlib>
+
+#include "core/jail/jdraw8.hpp"
+#include "core/jail/jinput.hpp"
+#include "game/info.hpp"
+#include "scenes/scene_utils.hpp"
+
+namespace scenes {
+
+void MortScene::onEnter() {
+    playMusic("00000001.ogg");
+    JI_DisableKeyboard(60);
+    info::ctx.vida = 5;
+
+    gfx_ = SurfaceHandle("gameover.gif");
+    JD8_ClearScreen(0);
+    JD8_Blit(gfx_);
+
+    // PaletteFade en fa una còpia interna via memcpy, així que alliberem
+    // la paleta temporal immediatament.
+    JD8_Palette pal = JD8_LoadPalette("gameover.gif");
+    fade_.startFadeTo(pal);
+    std::free(pal);
+
+    phase_ = Phase::FadingIn;
+    remaining_ms_ = 10000;
+}
+
+void MortScene::tick(int delta_ms) {
+    switch (phase_) {
+        case Phase::FadingIn:
+            fade_.tick(delta_ms);
+            if (fade_.done()) phase_ = Phase::Showing;
+            break;
+
+        case Phase::Showing:
+            if (JI_AnyKey()) {
+                remaining_ms_ = 0;
+            } else {
+                remaining_ms_ -= delta_ms;
+            }
+            if (remaining_ms_ <= 0) {
+                // Arrenca música del següent mòdul abans del fade out,
+                // igual que la versió vella feia al final de doMort().
+                playMusic("00000003.ogg");
+                info::ctx.num_piramide = 0;
+                fade_.startFadeOut();
+                phase_ = Phase::FadingOut;
+            }
+            break;
+
+        case Phase::FadingOut:
+            fade_.tick(delta_ms);
+            if (fade_.done()) phase_ = Phase::Done;
+            break;
+
+        case Phase::Done:
+            break;
+    }
+}
+
+}  // namespace scenes

source/scenes/mort_scene.hpp

@@ -0,0 +1,36 @@
+#pragma once
+
+#include "scenes/palette_fade.hpp"
+#include "scenes/scene.hpp"
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+// Pantalla de "game over". Reemplaça `ModuleSequence::doMort()`.
+//
+// Flux:
+//   1. Carrega gameover.gif, arranca música "00000001.ogg", fade-in de paleta.
+//   2. Mostra la pantalla ~10 segons o fins que l'usuari polse una tecla.
+//   3. Arranca música del menú ("00000003.ogg") i fade-out de paleta.
+//   4. Marca num_piramide=0 i retorna nextState=1 perquè el Director
+//      passe a l'escena del menú.
+class MortScene : public Scene {
+   public:
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return phase_ == Phase::Done; }
+    int nextState() const override { return 1; }
+
+   private:
+    enum class Phase { FadingIn,
+                       Showing,
+                       FadingOut,
+                       Done };
+
+    SurfaceHandle gfx_;
+    PaletteFade fade_;
+    Phase phase_{Phase::FadingIn};
+    int remaining_ms_{10000};  // 1000 ticks × 10 ms/tick del doMort original
+};
+
+}  // namespace scenes

source/scenes/palette_fade.cpp

@@ -0,0 +1,28 @@
+#include "scenes/palette_fade.hpp"
+
+namespace scenes {
+
+void PaletteFade::startFadeOut() {
+    JD8_FadeStartOut();
+    active_ = true;
+}
+
+void PaletteFade::startFadeTo(JD8_Palette target) {
+    JD8_FadeStartToPal(target);
+    active_ = true;
+}
+
+void PaletteFade::tick(int /*delta_ms*/) {
+    if (!active_) return;
+    // El fade té 32 passos interns. Amb un tick per frame (~16ms)
+    // dura ~512ms — el mateix temps que la versió bloquejant original.
+    // Si en el futur volem fer-lo genuinament time-based (p.ex. "fade
+    // de 500ms exactes independent del framerate") podem convertir la
+    // màquina d'estats de jdraw8 a time-based ací sense tocar cap altre
+    // call site.
+    if (JD8_FadeTickStep()) {
+        active_ = false;
+    }
+}
+
+}  // namespace scenes

source/scenes/palette_fade.hpp

@@ -0,0 +1,30 @@
+#pragma once
+
+#include "core/jail/jdraw8.hpp"
+
+namespace scenes {
+
+// Embolcall fi damunt de la màquina d'estats de fade de jdraw8
+// (`JD8_FadeStart*` / `JD8_FadeTickStep`). Exposa una API time-based
+// però internament avança un pas del fade per cada crida a `tick()`.
+// La raó de tindre-ho com a classe a banda: que una escena no puga
+// cridar accidentalment a `JD8_FadeOut`/`JD8_FadeToPal` (els shims
+// bloquejants vells) i que el `done()` siga consultable com la resta
+// dels helpers.
+class PaletteFade {
+   public:
+    PaletteFade() = default;
+
+    void startFadeOut();
+    void startFadeTo(JD8_Palette target);
+
+    void tick(int delta_ms);
+
+    bool active() const { return active_; }
+    bool done() const { return !active_; }
+
+   private:
+    bool active_{false};
+};
+
+}  // namespace scenes

source/scenes/scene.hpp

@@ -0,0 +1,37 @@
+#pragma once
+
+// Interfície base per a una escena (cinemàtica, menú, banner, etc.) del
+// joc. Una escena és una unitat autònoma amb un `tick(delta_ms)` no
+// bloquejant. El Director la fa avançar cada frame fins que `done()` és
+// cert, i llavors consulta `nextState()` per decidir la següent.
+//
+// Contracte:
+//  - `tick(delta_ms)` no pot bloquejar ni cridar JD8_Flip — el caller
+//    s'encarrega de fer el flip després del tick.
+//  - `done()` es consulta just després de cada tick.
+//  - Els assets són propietat de l'escena (normalment via SurfaceHandle)
+//    i s'alliberen al destructor.
+//  - `onEnter()` es crida una vegada just abans del primer tick. És el
+//    moment bo per a arrancar música, disparar un fade-in, etc.
+
+namespace scenes {
+
+class Scene {
+   public:
+    virtual ~Scene() = default;
+
+    virtual void onEnter() {}
+
+    virtual void tick(int delta_ms) = 0;
+
+    virtual bool done() const = 0;
+
+    // Valor retornat al caller quan l'escena acaba — equivalent al int
+    // que retornaven les velles funcions `Go()` de ModuleSequence:
+    //   1 = continuar amb la següent escena segons info::ctx
+    //   0 = entrar al gameplay (ModuleGame)
+    //  -1 = eixir del joc
+    virtual int nextState() const { return 1; }
+};
+
+}  // namespace scenes

source/scenes/scene_registry.cpp

@@ -0,0 +1,20 @@
+#include "scenes/scene_registry.hpp"
+
+namespace scenes {
+
+SceneRegistry& SceneRegistry::instance() {
+    static SceneRegistry inst;
+    return inst;
+}
+
+void SceneRegistry::registerScene(int state_key, Factory factory) {
+    factories_[state_key] = std::move(factory);
+}
+
+std::unique_ptr<Scene> SceneRegistry::tryCreate(int state_key) const {
+    const auto it = factories_.find(state_key);
+    if (it == factories_.end()) return nullptr;
+    return it->second();
+}
+
+}  // namespace scenes

source/scenes/scene_registry.hpp

@@ -0,0 +1,37 @@
+#pragma once
+
+#include <functional>
+#include <memory>
+#include <unordered_map>
+
+#include "scenes/scene.hpp"
+
+namespace scenes {
+
+// Mapa de `state_key` (actualment = `info::ctx.num_piramide`) a factory
+// d'escena. Permet que el dispatch de `gameFiberEntry` provi primer una
+// Scene nova i caiga al vell `ModuleSequence::Go()` si encara no està
+// migrada.
+//
+// Registre inicial: `Director::init()` cridarà `instance()` i afegirà
+// una entrada per cada escena ja portada. A mesura que vagen caient, les
+// línies del registre creixen i les funcions `doX()` del modulesequence
+// desapareixen.
+class SceneRegistry {
+   public:
+    using Factory = std::function<std::unique_ptr<Scene>()>;
+
+    static SceneRegistry& instance();
+
+    void registerScene(int state_key, Factory factory);
+
+    // Retorna `nullptr` si no hi ha cap escena registrada per a aquest
+    // state. El caller hauria de caure al path legacy en aquest cas.
+    std::unique_ptr<Scene> tryCreate(int state_key) const;
+
+   private:
+    SceneRegistry() = default;
+    std::unordered_map<int, Factory> factories_;
+};
+
+}  // namespace scenes

source/scenes/scene_utils.cpp

@@ -0,0 +1,21 @@
+#include "scenes/scene_utils.hpp"
+
+#include <SDL3/SDL.h>
+
+#include "core/jail/jail_audio.hpp"
+#include "core/jail/jfile.hpp"
+
+namespace scenes {
+
+void playMusic(const char* filename, int loop) {
+    if (!filename) return;
+    auto buffer = file_readfile(filename);
+    if (buffer.empty()) return;
+    // JA_LoadMusic fa una còpia interna del OGG comprimit (via SDL_malloc)
+    // per a stb_vorbis. El `buffer` local es destruirà en sortir d'àmbit.
+    JA_PlayMusic(JA_LoadMusic(reinterpret_cast<Uint8*>(buffer.data()),
+                              static_cast<Uint32>(buffer.size()), filename),
+                 loop);
+}
+
+}  // namespace scenes

source/scenes/scene_utils.hpp

@@ -0,0 +1,13 @@
+#pragma once
+
+// Helpers compartits per les escenes. Aquest header és petit i creix
+// quan una abstracció comú apareix en dos o més escenes.
+
+namespace scenes {
+
+// Carrega un OGG de `data/` i arranca'l com a música de fons. Substituïx
+// el `play_music()` repetit en tots els doX() del vell modulesequence.
+// `loop`: -1 = infinit (per defecte), 0 = una sola vegada, N = N+1 passades.
+void playMusic(const char* filename, int loop = -1);
+
+}  // namespace scenes

source/scenes/secreta_scene.cpp

@@ -0,0 +1,205 @@
+#include "scenes/secreta_scene.hpp"
+
+#include <algorithm>
+#include <cstdlib>
+#include <cstring>
+
+#include "core/jail/jail_audio.hpp"
+#include "core/jail/jdraw8.hpp"
+#include "core/jail/jinput.hpp"
+#include "game/info.hpp"
+#include "scenes/scene_utils.hpp"
+
+namespace {
+
+constexpr int TICK_MS = 20;  // JG_SetUpdateTicks(20) del vell doSecreta
+
+// Durades per fase, derivades dels contador-thresholds del vell:
+//   tomba1 scroll: 127 passos (contador 1→128) × 20ms
+//   tomba1 hold:   128 passos (contador 128→0) × 20ms
+//   tomba2 scroll: 94 passos × 20ms
+//   tomba2 hold:   94 passos × 20ms
+//   reveal horit:  80 passos × 20ms
+//   reveal hold:   80 passos × 20ms
+//   red pulse:     51 passos × 20ms
+//   red pulse hold: 51 passos × 20ms
+constexpr int TOMBA1_SCROLL_MS = 127 * TICK_MS;
+constexpr int TOMBA1_HOLD_MS = 128 * TICK_MS;
+constexpr int TOMBA2_SCROLL_MS = 94 * TICK_MS;
+constexpr int TOMBA2_HOLD_MS = 94 * TICK_MS;
+constexpr int TOMBA2_REVEAL_MS = 80 * TICK_MS;
+constexpr int TOMBA2_REVEAL_HOLD_MS = 80 * TICK_MS;
+constexpr int RED_PULSE_MS = 51 * TICK_MS;
+constexpr int RED_PULSE_HOLD_MS = 51 * TICK_MS;
+
+}  // namespace
+
+namespace scenes {
+
+SecretaScene::~SecretaScene() {
+    if (pal_aux_) std::free(pal_aux_);
+    // pal_active_ NO s'allibera: propietat de main_palette via SetScreenPalette.
+}
+
+void SecretaScene::onEnter() {
+    playMusic("00000002.ogg");
+
+    // Fade-out de la paleta anterior. Els assets es carreguen ja
+    // però no fem SetScreenPalette fins que acabe el fade — així
+    // el fade opera sobre la paleta del mòdul anterior.
+    fade_.startFadeOut();
+
+    gfx_ = SurfaceHandle("tomba1.gif");
+    pal_aux_ = JD8_LoadPalette("tomba1.gif");
+    pal_active_ = static_cast<JD8_Palette>(std::malloc(768));
+    std::memcpy(pal_active_, pal_aux_, 768);
+
+    phase_ = Phase::InitialFadeOut;
+    phase_acc_ms_ = 0;
+}
+
+void SecretaScene::swapToTomba2() {
+    JD8_ClearScreen(255);
+    gfx_.reset("tomba2.gif");
+
+    std::free(pal_aux_);
+    pal_aux_ = JD8_LoadPalette("tomba2.gif");
+    // pal_active_ continua sent el mateix buffer: només actualitzem
+    // el seu contingut. main_palette ja apunta ací.
+    std::memcpy(pal_active_, pal_aux_, 768);
+}
+
+void SecretaScene::beginRedPulseSetup() {
+    JD8_ClearScreen(0);
+    JD8_SetPaletteColor(254, 12, 11, 11);
+    JD8_SetPaletteColor(253, 12, 11, 11);
+}
+
+void SecretaScene::beginFinalFade() {
+    JA_FadeOutMusic(250);
+    fade_.startFadeOut();
+    phase_ = Phase::FinalFadeOut;
+}
+
+void SecretaScene::tick(int delta_ms) {
+    // Skip per tecla (després del fade inicial, no mentre). Salta
+    // directament al FinalFadeOut. Mateix patró que el vell, on
+    // qualsevol tecla sortia del loop.
+    if (!skip_triggered_ && phase_ != Phase::InitialFadeOut && JI_AnyKey()) {
+        skip_triggered_ = true;
+        beginFinalFade();
+    }
+
+    switch (phase_) {
+        case Phase::InitialFadeOut:
+            fade_.tick(delta_ms);
+            if (fade_.done()) {
+                // Ara main_palette (la vella) té tots els canals a 0.
+                // SetScreenPalette allibera la vella i adopta pal_active_
+                // — des d'ara main_palette == pal_active_, així que les
+                // futures escriptures a pal_active_ afecten la pantalla.
+                JD8_SetScreenPalette(pal_active_);
+                JD8_ClearScreen(255);
+                phase_ = Phase::Tomba1ScrollIn;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::Tomba1ScrollIn: {
+            phase_acc_ms_ += delta_ms;
+            const int contador = std::min(128, phase_acc_ms_ / TICK_MS + 1);
+            // Dos blits solapats: el primer avança a velocitat completa,
+            // el segon (contingut de la dreta del src) a meitat (contador>>1).
+            JD8_Blit(70, 60, gfx_, 0, contador, 178, 70);
+            JD8_BlitCK(70, 60, gfx_, 178, contador >> 1, 142, 70, 255);
+            if (phase_acc_ms_ >= TOMBA1_SCROLL_MS) {
+                phase_ = Phase::Tomba1Hold;
+                phase_acc_ms_ = 0;
+            }
+            break;
+        }
+
+        case Phase::Tomba1Hold:
+            phase_acc_ms_ += delta_ms;
+            if (phase_acc_ms_ >= TOMBA1_HOLD_MS) {
+                swapToTomba2();
+                phase_ = Phase::Tomba2ScrollIn;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::Tomba2ScrollIn: {
+            phase_acc_ms_ += delta_ms;
+            const int contador = std::min(94, phase_acc_ms_ / TICK_MS + 1);
+            JD8_Blit(55, 53, gfx_, 0, 158 - contador, 211, contador);
+            if (phase_acc_ms_ >= TOMBA2_SCROLL_MS) {
+                phase_ = Phase::Tomba2Hold;
+                phase_acc_ms_ = 0;
+            }
+            break;
+        }
+
+        case Phase::Tomba2Hold:
+            phase_acc_ms_ += delta_ms;
+            if (phase_acc_ms_ >= TOMBA2_HOLD_MS) {
+                beginRedPulseSetup();
+                phase_ = Phase::Tomba2Reveal;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::Tomba2Reveal: {
+            phase_acc_ms_ += delta_ms;
+            const int contador = std::min(80, phase_acc_ms_ / TICK_MS + 1);
+            // Revelat horitzontal simètric: l'amplada creix 2px per tick
+            // i el src_x es desplaça a l'esquerra el mateix.
+            JD8_Blit(80, 68, gfx_, 160 - (contador * 2), 0, contador * 2, 64);
+            if (phase_acc_ms_ >= TOMBA2_REVEAL_MS) {
+                phase_ = Phase::Tomba2RevealHold;
+                phase_acc_ms_ = 0;
+            }
+            break;
+        }
+
+        case Phase::Tomba2RevealHold:
+            phase_acc_ms_ += delta_ms;
+            if (phase_acc_ms_ >= TOMBA2_REVEAL_HOLD_MS) {
+                phase_ = Phase::RedPulse;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::RedPulse: {
+            phase_acc_ms_ += delta_ms;
+            const int contador = std::min(51, phase_acc_ms_ / TICK_MS);
+            // Anima el canal R dels índexs 254 i 253 (aquest a la meitat
+            // de brillantor). Va de (12,11,11) fins a (63,11,11) / (31,11,11).
+            JD8_SetPaletteColor(254, contador + 12, 11, 11);
+            JD8_SetPaletteColor(253, (contador + 12) >> 1, 11, 11);
+            if (phase_acc_ms_ >= RED_PULSE_MS) {
+                phase_ = Phase::RedPulseHold;
+                phase_acc_ms_ = 0;
+            }
+            break;
+        }
+
+        case Phase::RedPulseHold:
+            phase_acc_ms_ += delta_ms;
+            if (phase_acc_ms_ >= RED_PULSE_HOLD_MS) {
+                beginFinalFade();
+            }
+            break;
+
+        case Phase::FinalFadeOut:
+            fade_.tick(delta_ms);
+            if (fade_.done()) {
+                phase_ = Phase::Done;
+            }
+            break;
+
+        case Phase::Done:
+            break;
+    }
+}
+
+}  // namespace scenes

source/scenes/secreta_scene.hpp

@@ -0,0 +1,66 @@
+#pragma once
+
+#include "core/jail/jdraw8.hpp"
+#include "scenes/palette_fade.hpp"
+#include "scenes/scene.hpp"
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+// Pre-Secreta. Reemplaça `ModuleSequence::doSecreta()`.
+//
+// Flux:
+//   1. Arranca música "00000002.ogg" i fa fade-out de la paleta anterior.
+//   2. Carrega tomba1.gif + paleta i pinta un scroll vertical doble
+//      (dos blits solapats, un a velocitat meitat que l'altre) durant
+//      ~2.5 s + ~2.5 s de pausa.
+//   3. Swap a tomba2.gif + reset de paleta, scroll vertical del segon
+//      asset (~1.9 s + ~1.9 s de pausa).
+//   4. ClearScreen a 0, set colors 253/254 a vermell fosc (12,11,11)
+//      i pinta un revelat horitzontal (~1.6 s + ~1.6 s de pausa).
+//   5. "Red pulse": anima els colors 253/254 incrementant el canal R
+//      de 12 a 62 durant ~1 s (+ ~1 s de pausa).
+//   6. FadeOut + JA_FadeOutMusic(250).
+//   7. Retorna nextState=0 per entrar al ModuleGame amb num_piramide=6.
+//
+// Registrada al SceneRegistry amb state_key = 6.
+class SecretaScene : public Scene {
+   public:
+    SecretaScene() = default;
+    ~SecretaScene() override;
+
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return phase_ == Phase::Done; }
+    int nextState() const override { return 0; }
+
+   private:
+    enum class Phase {
+        InitialFadeOut,
+        Tomba1ScrollIn,
+        Tomba1Hold,
+        Tomba2ScrollIn,
+        Tomba2Hold,
+        Tomba2Reveal,
+        Tomba2RevealHold,
+        RedPulse,
+        RedPulseHold,
+        FinalFadeOut,
+        Done,
+    };
+
+    void swapToTomba2();
+    void beginRedPulseSetup();
+    void beginFinalFade();
+
+    SurfaceHandle gfx_;
+    JD8_Palette pal_aux_{nullptr};
+    JD8_Palette pal_active_{nullptr};  // propietat transferida a main_palette
+    PaletteFade fade_;
+
+    Phase phase_{Phase::InitialFadeOut};
+    int phase_acc_ms_{0};
+    bool skip_triggered_{false};
+};
+
+}  // namespace scenes

source/scenes/slides_scene.cpp

@@ -0,0 +1,186 @@
+#include "scenes/slides_scene.hpp"
+
+#include <algorithm>
+#include <cstdlib>
+#include <cstring>
+
+#include "core/jail/jail_audio.hpp"
+#include "core/jail/jdraw8.hpp"
+#include "core/jail/jinput.hpp"
+#include "game/info.hpp"
+#include "scenes/scene_utils.hpp"
+#include "utils/easing.hpp"
+
+namespace {
+
+constexpr int SCROLL_MS = 1600;  // 80 iters × 20 ms del vell doSlides
+constexpr int HOLD_MS = 4600;    // 230 iters × 20 ms (80 + 150) del vell
+constexpr int SLIDE_Y = 65;
+constexpr int SLIDE_H = 65;
+constexpr int BG_COLOR_INDEX = 255;
+
+// Desplaçament inicial del slide segons direcció del wipe.
+// Slide 1 i 3: "scroll in from right" (pos_x va de 320 → 0).
+// Slide 2: "wipe reverse" (pos_x va de -320 → 0), el mateix efecte
+// estrany del doSlides vell on la imatge es desplaça des de l'esquerra
+// però revela primer el lateral dret del src.
+constexpr int SLIDE_START_X[3] = {320, -320, 320};
+
+}  // namespace
+
+namespace scenes {
+
+SlidesScene::~SlidesScene() {
+    if (pal_aux_) std::free(pal_aux_);
+    // pal_active_ NO s'allibera: propietat de main_palette via SetScreenPalette.
+}
+
+void SlidesScene::onEnter() {
+    num_piramide_at_start_ = info::ctx.num_piramide;
+
+    const char* arxiu = nullptr;
+    if (num_piramide_at_start_ == 7) {
+        // loop=1 per replicar el vell `play_music("00000005.ogg", 1)`.
+        playMusic("00000005.ogg", 1);
+        arxiu = (info::ctx.diners < 200) ? "intro2.gif" : "intro3.gif";
+    } else {
+        arxiu = "intro.gif";
+    }
+
+    gfx_ = SurfaceHandle(arxiu);
+    pal_aux_ = JD8_LoadPalette(arxiu);
+
+    // Còpia editable de la paleta. `pal_active_` comparteix memòria amb
+    // main_palette després del SetScreenPalette — modificar-la modifica
+    // main_palette directament. `pal_aux_` es manté intacte per a poder
+    // restaurar després de cada fade-out intermedi.
+    pal_active_ = static_cast<JD8_Palette>(std::malloc(768));
+    std::memcpy(pal_active_, pal_aux_, 768);
+    JD8_SetScreenPalette(pal_active_);
+
+    JD8_ClearScreen(BG_COLOR_INDEX);
+
+    phase_ = Phase::Slide1Enter;
+    phase_acc_ms_ = 0;
+    next_state_ = 0;
+}
+
+void SlidesScene::drawSlide(int slide_idx, int pos_x) {
+    const int src_y = slide_idx * SLIDE_H;
+
+    // Clipping manual: translada un rect de 320×65 des de (pos_x, SLIDE_Y)
+    // a l'àrea visible (0..319, SLIDE_Y..SLIDE_Y+64).
+    int dst_x = pos_x;
+    int src_x = 0;
+    int w = 320;
+
+    if (dst_x < 0) {
+        src_x = -dst_x;
+        w = 320 + dst_x;
+        dst_x = 0;
+    } else if (dst_x > 0) {
+        w = 320 - dst_x;
+    }
+
+    if (w > 0) {
+        JD8_Blit(dst_x, SLIDE_Y, gfx_, src_x, src_y, w, SLIDE_H);
+    }
+}
+
+void SlidesScene::restorePalette() {
+    std::memcpy(pal_active_, pal_aux_, 768);
+}
+
+void SlidesScene::beginFinalFade() {
+    if (num_piramide_at_start_ != 7) {
+        JA_FadeOutMusic(250);
+    }
+    fade_.startFadeOut();
+    phase_ = Phase::FadeFinal;
+}
+
+void SlidesScene::tick(int delta_ms) {
+    // Skip: qualsevol tecla salta directament al fade final. Per fidelitat
+    // al vell doSlides, el skip NO atura la música explícitament — només
+    // el final natural crida JA_FadeOutMusic (beginFinalFade() distingeix).
+    if (!skip_triggered_ && JI_AnyKey()) {
+        skip_triggered_ = true;
+        if (num_piramide_at_start_ != 7) JA_FadeOutMusic(250);
+        fade_.startFadeOut();
+        phase_ = Phase::FadeFinal;
+    }
+
+    switch (phase_) {
+        case Phase::Slide1Enter:
+        case Phase::Slide2Enter:
+        case Phase::Slide3Enter: {
+            phase_acc_ms_ += delta_ms;
+            const int slide_idx = (phase_ == Phase::Slide1Enter   ? 0
+                                   : phase_ == Phase::Slide2Enter ? 1
+                                                                  : 2);
+            const float t = std::min(1.0f, static_cast<float>(phase_acc_ms_) /
+                                               static_cast<float>(SCROLL_MS));
+            const float eased = Easing::outCubic(t);
+            const int pos_x = Easing::lerpInt(SLIDE_START_X[slide_idx], 0, eased);
+            drawSlide(slide_idx, pos_x);
+
+            if (phase_acc_ms_ >= SCROLL_MS) {
+                // Garanteix posició final exacta (pos_x=0).
+                drawSlide(slide_idx, 0);
+                if (phase_ == Phase::Slide1Enter) phase_ = Phase::Slide1Hold;
+                else if (phase_ == Phase::Slide2Enter) phase_ = Phase::Slide2Hold;
+                else phase_ = Phase::Slide3Hold;
+                phase_acc_ms_ = 0;
+            }
+            break;
+        }
+
+        case Phase::Slide1Hold:
+        case Phase::Slide2Hold:
+            phase_acc_ms_ += delta_ms;
+            if (phase_acc_ms_ >= HOLD_MS) {
+                fade_.startFadeOut();
+                if (phase_ == Phase::Slide1Hold) phase_ = Phase::FadeOut1;
+                else phase_ = Phase::FadeOut2;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::Slide3Hold:
+            phase_acc_ms_ += delta_ms;
+            if (phase_acc_ms_ >= HOLD_MS) {
+                beginFinalFade();
+            }
+            break;
+
+        case Phase::FadeOut1:
+        case Phase::FadeOut2:
+            fade_.tick(delta_ms);
+            if (fade_.done()) {
+                restorePalette();
+                JD8_ClearScreen(BG_COLOR_INDEX);
+                if (phase_ == Phase::FadeOut1) phase_ = Phase::Slide2Enter;
+                else phase_ = Phase::Slide3Enter;
+                phase_acc_ms_ = 0;
+            }
+            break;
+
+        case Phase::FadeFinal:
+            fade_.tick(delta_ms);
+            if (fade_.done()) {
+                if (num_piramide_at_start_ == 7) {
+                    info::ctx.num_piramide = 8;
+                    next_state_ = 1;
+                } else {
+                    next_state_ = 0;
+                }
+                phase_ = Phase::Done;
+            }
+            break;
+
+        case Phase::Done:
+            break;
+    }
+}
+
+}  // namespace scenes

source/scenes/slides_scene.hpp

@@ -0,0 +1,79 @@
+#pragma once
+
+#include "core/jail/jdraw8.hpp"
+#include "scenes/palette_fade.hpp"
+#include "scenes/scene.hpp"
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+// 3 slides narratius amb scroll d'entrada + espera + transició amb
+// fade-out. Reemplaça `ModuleSequence::doSlides()`.
+//
+// Tria d'asset segons context:
+//   - num_piramide == 7 i diners < 200: intro2.gif + música "00000005.ogg"
+//   - num_piramide == 7 i diners >= 200: intro3.gif + música "00000005.ogg"
+//   - altre cas (num_piramide == 1): intro.gif, sense música nova
+//
+// Flux:
+//   Slide1Enter (1600 ms scroll dreta→centre, easing outCubic)
+//   → Slide1Hold (4600 ms)
+//   → FadeOut1 + clear + reset paleta
+//   → Slide2Enter (1600 ms scroll esquerra→centre)
+//   → Slide2Hold (4600 ms)
+//   → FadeOut2 + clear + reset paleta
+//   → Slide3Enter (1600 ms scroll dreta→centre)
+//   → Slide3Hold (4600 ms)
+//   → FadeFinal (JA_FadeOutMusic si num_piramide != 7 + fade paleta)
+//   → Done
+//
+// Qualsevol tecla salta directament a FadeFinal (sense cortar la música
+// si hem entrat per num_piramide==7, per fidelitat al vell).
+//
+// NextState:
+//   - num_piramide==7 al entrar → num_piramide=8 + return 1 (a Credits)
+//   - altre cas → return 0 (entra al ModuleGame)
+class SlidesScene : public Scene {
+   public:
+    SlidesScene() = default;
+    ~SlidesScene() override;
+
+    void onEnter() override;
+    void tick(int delta_ms) override;
+    bool done() const override { return phase_ == Phase::Done; }
+    int nextState() const override { return next_state_; }
+
+   private:
+    enum class Phase {
+        Slide1Enter,
+        Slide1Hold,
+        FadeOut1,
+        Slide2Enter,
+        Slide2Hold,
+        FadeOut2,
+        Slide3Enter,
+        Slide3Hold,
+        FadeFinal,
+        Done,
+    };
+
+    // Pinta un slide amb desplaçament horitzontal. `slide_idx` = 0..2
+    // (correspon a la franja 65x65 a y = 0, 65, 130 dins de gfx_).
+    // `pos_x` = desplaçament, amb clipping manual quan surt de pantalla.
+    void drawSlide(int slide_idx, int pos_x);
+    void restorePalette();
+    void beginFinalFade();
+
+    SurfaceHandle gfx_;
+    JD8_Palette pal_aux_{nullptr};     // còpia "neta" que preservem
+    JD8_Palette pal_active_{nullptr};  // propietat transferida a main_palette
+    PaletteFade fade_;
+
+    Phase phase_{Phase::Slide1Enter};
+    int phase_acc_ms_{0};
+    int num_piramide_at_start_{1};
+    int next_state_{0};
+    bool skip_triggered_{false};
+};
+
+}  // namespace scenes

source/scenes/sprite_mover.cpp

@@ -0,0 +1,46 @@
+#include "scenes/sprite_mover.hpp"
+
+#include <algorithm>
+
+namespace scenes {
+
+void SpriteMover::moveTo(int x0, int y0, int x1, int y1, int duration_ms, EaseFn ease) {
+    x0_ = x0;
+    y0_ = y0;
+    x1_ = x1;
+    y1_ = y1;
+    duration_ms_ = std::max(0, duration_ms);
+    elapsed_ms_ = 0;
+    ease_ = ease ? ease : Easing::linear;
+    cur_x_ = x0;
+    cur_y_ = y0;
+}
+
+void SpriteMover::setPosition(int x, int y) {
+    cur_x_ = x;
+    cur_y_ = y;
+    x0_ = x1_ = x;
+    y0_ = y1_ = y;
+    duration_ms_ = 0;
+    elapsed_ms_ = 0;
+}
+
+void SpriteMover::tick(int delta_ms) {
+    if (duration_ms_ <= 0) {
+        cur_x_ = x1_;
+        cur_y_ = y1_;
+        return;
+    }
+    elapsed_ms_ = std::min(elapsed_ms_ + delta_ms, duration_ms_);
+    const float t = static_cast<float>(elapsed_ms_) / static_cast<float>(duration_ms_);
+    const float eased = ease_(t);
+    cur_x_ = Easing::lerpInt(x0_, x1_, eased);
+    cur_y_ = Easing::lerpInt(y0_, y1_, eased);
+}
+
+float SpriteMover::progress() const {
+    if (duration_ms_ <= 0) return 1.0f;
+    return static_cast<float>(elapsed_ms_) / static_cast<float>(duration_ms_);
+}
+
+}  // namespace scenes

source/scenes/sprite_mover.hpp

@@ -0,0 +1,39 @@
+#pragma once
+
+#include "utils/easing.hpp"
+
+namespace scenes {
+
+// Interpola una posició 2D entre dos punts durant un temps donat amb
+// una funció d'easing. No toca cap surface — el caller llegix x()/y()
+// i fa el blit ell mateix. Pensat per a scrolls, sprites que entren/
+// ixen per pantalla, i moviments d'objectes interpolats.
+class SpriteMover {
+   public:
+    using EaseFn = float (*)(float);
+
+    SpriteMover() = default;
+
+    // Arrenca un moviment nou. Si ja n'hi havia un en curs, es descarta.
+    void moveTo(int x0, int y0, int x1, int y1, int duration_ms,
+                EaseFn ease = Easing::linear);
+
+    // Posicionament immediat (útil per a "teleportar" entre moviments).
+    void setPosition(int x, int y);
+
+    void tick(int delta_ms);
+
+    int x() const { return cur_x_; }
+    int y() const { return cur_y_; }
+    bool done() const { return elapsed_ms_ >= duration_ms_; }
+    float progress() const;  // 0..1 sense easing aplicat
+
+   private:
+    int x0_{0}, y0_{0}, x1_{0}, y1_{0};
+    int duration_ms_{0};
+    int elapsed_ms_{0};
+    int cur_x_{0}, cur_y_{0};
+    EaseFn ease_{Easing::linear};
+};
+
+}  // namespace scenes

source/scenes/surface_handle.cpp

@@ -0,0 +1,42 @@
+#include "scenes/surface_handle.hpp"
+
+namespace scenes {
+
+SurfaceHandle::SurfaceHandle(const char* file)
+    : surface_(JD8_LoadSurface(file)) {}
+
+SurfaceHandle::~SurfaceHandle() {
+    if (surface_) JD8_FreeSurface(surface_);
+}
+
+SurfaceHandle::SurfaceHandle(SurfaceHandle&& other) noexcept
+    : surface_(other.surface_) {
+    other.surface_ = nullptr;
+}
+
+SurfaceHandle& SurfaceHandle::operator=(SurfaceHandle&& other) noexcept {
+    if (this != &other) {
+        if (surface_) JD8_FreeSurface(surface_);
+        surface_ = other.surface_;
+        other.surface_ = nullptr;
+    }
+    return *this;
+}
+
+void SurfaceHandle::reset(const char* file) {
+    if (surface_) JD8_FreeSurface(surface_);
+    surface_ = file ? JD8_LoadSurface(file) : nullptr;
+}
+
+void SurfaceHandle::adopt(JD8_Surface raw) {
+    if (surface_) JD8_FreeSurface(surface_);
+    surface_ = raw;
+}
+
+JD8_Surface SurfaceHandle::release() {
+    JD8_Surface r = surface_;
+    surface_ = nullptr;
+    return r;
+}
+
+}  // namespace scenes

source/scenes/surface_handle.hpp

@@ -0,0 +1,49 @@
+#pragma once
+
+#include "core/jail/jdraw8.hpp"
+
+namespace scenes {
+
+// Wrapper RAII damunt de `JD8_Surface`. Allibera automàticament amb
+// `JD8_FreeSurface` al destructor. Move-only per evitar dobles alliberaments.
+// Converteix implícitament a `JD8_Surface` per a poder passar-lo
+// directament a `JD8_Blit*` sense haver de cridar `.get()`.
+class SurfaceHandle {
+   public:
+    SurfaceHandle() = default;
+    explicit SurfaceHandle(const char* file);
+    ~SurfaceHandle();
+
+    SurfaceHandle(const SurfaceHandle&) = delete;
+    SurfaceHandle& operator=(const SurfaceHandle&) = delete;
+
+    SurfaceHandle(SurfaceHandle&& other) noexcept;
+    SurfaceHandle& operator=(SurfaceHandle&& other) noexcept;
+
+    // Allibera la surface actual (si n'hi ha) i carrega una nova.
+    // Usat per escenes que recarreguen assets a mitja cinemàtica
+    // (p.ex. doSecreta que passa de tomba1 a tomba2).
+    void reset(const char* file);
+
+    // Adopta una surface ja creada (p.ex. amb JD8_NewSurface). Pren ownership
+    // — la surface adoptada s'allibera al destructor o al següent reset/adopt.
+    void adopt(JD8_Surface raw);
+
+    // Allibera ownership sense destruir la surface. Retorna el pointer cru;
+    // el caller passa a ser responsable d'alliberar-lo (o de passar-lo a un
+    // altre propietari). Usat quan una escena delega a codi legacy que
+    // també allibera la mateixa surface — cal "soltar" el ownership per
+    // evitar double free.
+    [[nodiscard]] JD8_Surface release();
+
+    // Conversió implícita per al confort d'ús: JD8_Blit(handle)
+    // en lloc de JD8_Blit(handle.get()).
+    operator JD8_Surface() const { return surface_; }
+    JD8_Surface get() const { return surface_; }
+    bool valid() const { return surface_ != nullptr; }
+
+   private:
+    JD8_Surface surface_{nullptr};
+};
+
+}  // namespace scenes

source/scenes/timeline.cpp

@@ -0,0 +1,85 @@
+#include "scenes/timeline.hpp"
+
+#include <algorithm>
+
+namespace scenes {
+
+Timeline& Timeline::step(int duration_ms, StepFn fn) {
+    Step s;
+    s.duration_ms = duration_ms;
+    s.continuous = std::move(fn);
+    steps_.push_back(std::move(s));
+    return *this;
+}
+
+Timeline& Timeline::once(OnceFn fn) {
+    Step s;
+    s.duration_ms = 0;
+    s.oneshot = std::move(fn);
+    steps_.push_back(std::move(s));
+    return *this;
+}
+
+void Timeline::flushOneShots() {
+    while (current_ < steps_.size() && steps_[current_].duration_ms == 0) {
+        auto& s = steps_[current_];
+        if (!s.entered) {
+            s.entered = true;
+            if (s.oneshot) s.oneshot();
+        }
+        ++current_;
+        elapsed_in_step_ = 0;
+    }
+}
+
+void Timeline::tick(int delta_ms) {
+    if (skipped_) return;
+    flushOneShots();
+    if (current_ >= steps_.size()) return;
+
+    auto& s = steps_[current_];
+    if (!s.entered) {
+        s.entered = true;
+        // Primer tick dins del pas: cridem amb progress=0 si hi ha callback.
+        if (s.continuous) s.continuous(0.0f);
+    }
+
+    elapsed_in_step_ += delta_ms;
+    if (elapsed_in_step_ >= s.duration_ms) {
+        // Tancament del pas: una crida final amb progress=1.
+        if (s.continuous) s.continuous(1.0f);
+        ++current_;
+        elapsed_in_step_ = 0;
+        // Pot ser que el següent pas siga una cadena de one-shots.
+        flushOneShots();
+    } else if (s.continuous) {
+        const float p = static_cast<float>(elapsed_in_step_) /
+                        static_cast<float>(std::max(1, s.duration_ms));
+        s.continuous(p);
+    }
+}
+
+void Timeline::skip() {
+    skipped_ = true;
+    current_ = steps_.size();
+}
+
+void Timeline::reset() {
+    for (auto& s : steps_) s.entered = false;
+    current_ = 0;
+    elapsed_in_step_ = 0;
+    skipped_ = false;
+}
+
+bool Timeline::done() const {
+    return skipped_ || current_ >= steps_.size();
+}
+
+float Timeline::currentProgress() const {
+    if (current_ >= steps_.size()) return 1.0f;
+    const auto& s = steps_[current_];
+    if (s.duration_ms <= 0) return 0.0f;
+    return static_cast<float>(elapsed_in_step_) / static_cast<float>(s.duration_ms);
+}
+
+}  // namespace scenes

source/scenes/timeline.hpp

@@ -0,0 +1,57 @@
+#pragma once
+
+#include <functional>
+#include <vector>
+
+namespace scenes {
+
+// Timeline declaratiu de passos seqüencials. Cada pas té una duració en
+// ms i un callback. Exemple d'ús:
+//
+//   timeline_
+//       .once([this] { JD8_ClearScreen(0); fade_.startFadeTo(pal); })
+//       .step(5000)                              // espera pura
+//       .step(1000, [this](float p) { /*...*/ }) // animat amb progress
+//       .once([this] { JA_FadeOutMusic(250); });
+//
+// `tick(delta_ms)` avança el temps. Els passos one-shot s'executen al
+// moment d'entrar-hi i avancen immediatament. Els passos amb duració
+// criden el seu callback cada tick amb el progress [0..1] i passen al
+// següent quan s'exhaureix el temps. `skip()` marca tota la timeline
+// com a acabada (no executa res més) — útil per als "polsa una tecla
+// per a saltar la cinemàtica".
+class Timeline {
+   public:
+    using StepFn = std::function<void(float progress_0_1)>;
+    using OnceFn = std::function<void()>;
+
+    Timeline& step(int duration_ms, StepFn fn = nullptr);
+    Timeline& once(OnceFn fn);
+
+    void tick(int delta_ms);
+    void skip();
+    void reset();
+
+    bool done() const;
+    int currentStepIndex() const { return static_cast<int>(current_); }
+    float currentProgress() const;
+
+   private:
+    struct Step {
+        int duration_ms{0};  // 0 = one-shot
+        StepFn continuous;
+        OnceFn oneshot;
+        bool entered{false};
+    };
+
+    // Avança els one-shots consecutius des de `current_` fins a trobar
+    // un pas amb duració > 0 o l'endoll de la llista.
+    void flushOneShots();
+
+    std::vector<Step> steps_;
+    std::size_t current_{0};
+    int elapsed_in_step_{0};
+    bool skipped_{false};
+};
+
+}  // namespace scenes

tools/pack_resources/pack_resources.cpp

@@ -0,0 +1,98 @@
+#include <filesystem>
+#include <iostream>
+#include <string>
+
+#include "core/resources/resource_pack.hpp"
+
+namespace {
+
+void showHelp() {
+    std::cout << "AEE - Resource Packer\n";
+    std::cout << "=====================\n";
+    std::cout << "Usage: pack_resources [options] [input_dir] [output_file]\n\n";
+    std::cout << "Options:\n";
+    std::cout << "  --help     Show this help message\n";
+    std::cout << "  --list     List contents of an existing pack file\n\n";
+    std::cout << "Arguments:\n";
+    std::cout << "  input_dir   Directory to pack (default: data)\n";
+    std::cout << "  output_file Pack file name (default: resource.pack)\n\n";
+    std::cout << "Examples:\n";
+    std::cout << "  pack_resources                    # Pack 'data' to 'resource.pack'\n";
+    std::cout << "  pack_resources mydata mypack.pack # Pack 'mydata' to 'mypack.pack'\n";
+    std::cout << "  pack_resources --list my.pack     # List contents of 'my.pack'\n";
+}
+
+void listPackContents(const std::string& pack_file) {
+    ResourcePack pack;
+    if (!pack.loadPack(pack_file)) {
+        std::cerr << "Error: cannot open pack file: " << pack_file << '\n';
+        return;
+    }
+    auto resources = pack.getResourceList();
+    std::cout << "Pack file: " << pack_file << '\n';
+    std::cout << "Resources: " << resources.size() << '\n';
+    for (const auto& r : resources) std::cout << "  " << r << '\n';
+}
+
+}  // namespace
+
+int main(int argc, char* argv[]) {
+    std::string data_dir = "data";
+    std::string output_file = "resource.pack";
+    bool list_mode = false;
+    bool data_dir_set = false;
+
+    for (int i = 1; i < argc; ++i) {
+        std::string arg = argv[i];
+        if (arg == "--help" || arg == "-h") {
+            showHelp();
+            return 0;
+        }
+        if (arg == "--list") {
+            list_mode = true;
+            if (i + 1 < argc) output_file = argv[++i];
+            continue;
+        }
+        if (!arg.empty() && arg[0] != '-') {
+            if (!data_dir_set) {
+                data_dir = arg;
+                data_dir_set = true;
+            } else {
+                output_file = arg;
+            }
+        }
+    }
+
+    if (list_mode) {
+        listPackContents(output_file);
+        return 0;
+    }
+
+    std::cout << "AEE - Resource Packer\n=====================\n";
+    std::cout << "Input directory: " << data_dir << '\n';
+    std::cout << "Output file: " << output_file << '\n';
+
+    if (!std::filesystem::exists(data_dir)) {
+        std::cerr << "Error: input directory does not exist: " << data_dir << '\n';
+        return 1;
+    }
+
+    ResourcePack pack;
+    std::cout << "Scanning and packing resources...\n";
+    if (!pack.addDirectory(data_dir)) {
+        std::cerr << "Error: failed to add directory to pack\n";
+        return 1;
+    }
+    std::cout << "Found " << pack.getResourceCount() << " resources\n";
+
+    std::cout << "Saving pack file...\n";
+    if (!pack.savePack(output_file)) {
+        std::cerr << "Error: failed to save pack file\n";
+        return 1;
+    }
+
+    auto file_size = std::filesystem::file_size(std::filesystem::path(output_file));
+    std::cout << "Pack file created: " << output_file << " ("
+              << (static_cast<double>(file_size) / 1024.0 / 1024.0) << " MB)\n";
+    return 0;
+}