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

CLAUDE.md

@@ -228,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()`
@@ -279,6 +317,7 @@ JD8_Flip produces ABGR byte order: `0xFF000000 + R + (G<<8) + (B<<16)`. SDL text
 - **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)