feat(decals): tiles de decal de sòl compten com a pintats des del load

source/game/map/map.cpp

@@ -1,5 +1,6 @@
 #include "game/map/map.hpp"
 
+#include <cmath>
 #include <iostream>
 #include <stdexcept>
 
@@ -150,6 +151,13 @@ namespace Map {
         return true;
     }
 
+    auto pixelToTile(float px, float py) -> std::pair<int, int> {
+        const auto TS = static_cast<float>(tile_size);
+        const int COL = static_cast<int>(std::floor((px - static_cast<float>(tilemap_origin_x)) / TS));
+        const int ROW = static_cast<int>(std::floor((py - static_cast<float>(tilemap_origin_y)) / TS));
+        return {COL, ROW};
+    }
+
     auto makeInfo() -> Info {
         return {
             .playfield_x = playfield_x,

source/game/map/map.hpp

@@ -3,6 +3,7 @@
 #include <SDL3/SDL.h>
 
 #include <string>
+#include <utility>
 
 // Mapa d'una piràmide: sala rectangular amb marcador superior, muros pels
 // quatre costats i graella de sarcòfags envoltada per un passadís a cada
@@ -105,6 +106,17 @@ namespace Map {
     // usa el `PaintLayer` per filtrar quines cel·les accepten pintat.
     [[nodiscard]] auto isPaintable(int col, int row) -> bool;
 
+    // Converteix una coordenada píxel del canvas en (col, row) del
+    // tilemap. Assumeix `tile_size > 0`; si la coordenada cau fora del
+    // playfield, retorna el tile encara que sigui negatiu o estigui fora
+    // de rang — el caller valida si li cal. El càlcul és el típic
+    // `floor((p - origin) / tile_size)` que apareixia en diversos llocs;
+    // factoritzat aquí per coherència. Consumidors que tinguen un
+    // snapshot de `Map::Info` (p.ex. el Player, decoupling COUP-02) no
+    // han d'usar aquesta funció — han de seguir treballant amb el
+    // snapshot per no re-acoblar-se al namespace global.
+    [[nodiscard]] auto pixelToTile(float px, float py) -> std::pair<int, int>;
+
     // Snapshot plà de la geometria del mapa + punters a `collides` /
     // `insidePlayfield`. Pensat per ser passat per valor (POD petit,
     // trivialment copiable). Un cop construïda, llegeix els valors

source/game/map/paint_layer.cpp

@@ -12,6 +12,27 @@
 #include "game/map/map.hpp"
 #include "game/map/tilemap.hpp"
 
+// CONTRACTE BUS DE PINTAT
+// -----------------------
+// `on_tile_entered` — senyal FÍSICA: un jugador acaba d'entrar a un tile.
+//   La publica `Player::publishTileEnteredIfChanged`. La consumeix aquest
+//   `PaintLayer` per decidir si renderitzar el tile com a pintat (filtra
+//   per `Map::isPaintable` i aplica la regla "primer que pinta guanya").
+//
+// `tile_painted` — senyal LÒGICA: un tile compta com a pintat per a la
+//   lògica de joc (sarcòfags i, en el futur, HUD %completat, events
+//   derivats). La publica el `PaintLayer` quan confirma un pintat físic,
+//   i també la publica `EntityManager::loadFromLevel` com a broadcast
+//   inicial per als tiles ocupats per decals de sòl (Hole, etc.) — que
+//   el jugador mai podrà trepitjar perquè cauria al forat i els
+//   sarcòfags vecins necessiten que aquests tiles comptin com a pintats
+//   per completar el perímetre.
+//
+// REGLA: NO connectar `PaintLayer` al canal `tile_painted` per
+// renderitzar. Si ho féssim, els broadcasts inicials de decals pintarien
+// visualment els tiles d'agujero, incoherent amb la representació
+// gràfica del decal.
+
 namespace {
 
     // Blit d'un tile del tileset sobre un buffer ARGB de destí, respectant