scenes: infraestructura de la capa scenes:: (scene, timeline, sprite mover, frame animator, palette fade, surface handle, registry)

source/scenes/surface_handle.hpp

@@ -0,0 +1,38 @@
+#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);
+
+    // 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