Add new level transition state machine

src/game/transition.h

@@ -0,0 +1,68 @@
+#ifndef JNR_TRANSITION_H
+#define JNR_TRANSITION_H
+
+#include <stdbool.h>
+#include "engine/camera.h"
+#include "config.h"
+
+/* ═══════════════════════════════════════════════════
+ *  Level transition animations
+ *
+ *  Two-phase system: outro (on the old level) then
+ *  intro (on the new level).  The caller is responsible
+ *  for freeing the old level and loading the new one
+ *  between phases (when transition_needs_load() is true).
+ *
+ *  TransitionStyle enum is defined in config.h so that
+ *  both engine (tilemap) and game code can reference it
+ *  without circular includes.
+ * ═══════════════════════════════════════════════════ */
+
+typedef enum TransitionPhase {
+    TRANS_IDLE,            /* no transition active                   */
+    TRANS_PHASE_OUT,       /* outro animation on the old level       */
+    TRANS_PHASE_LOAD,      /* ready for the caller to swap levels    */
+    TRANS_PHASE_IN,        /* intro animation on the new level       */
+    TRANS_PHASE_DONE,      /* transition complete, return to play    */
+} TransitionPhase;
+
+typedef struct TransitionState {
+    TransitionStyle  out_style;    /* outro style (from departing level) */
+    TransitionStyle  in_style;     /* intro style (from arriving level)  */
+    TransitionPhase  phase;
+    float            timer;        /* elapsed time in current phase      */
+    float            phase_dur;    /* total duration of current phase    */
+    bool             sound_played; /* flag to fire a sound once per phase */
+} TransitionState;
+
+/* Start the outro phase.  out_style comes from the departing level. */
+void transition_start_out(TransitionState *ts, TransitionStyle out_style);
+
+/* Set the intro style (call after loading the new level). */
+void transition_set_in_style(TransitionState *ts, TransitionStyle in_style);
+
+/* Advance the transition.  cam may be NULL during the load gap. */
+void transition_update(TransitionState *ts, float dt, Camera *cam);
+
+/* True when the outro is done and the caller should swap levels. */
+bool transition_needs_load(const TransitionState *ts);
+
+/* Acknowledge the load — advance to the intro phase. */
+void transition_begin_intro(TransitionState *ts);
+
+/* True when the full transition is finished. */
+bool transition_is_done(const TransitionState *ts);
+
+/* Render the transition overlay (call AFTER rendering the level). */
+void transition_render(const TransitionState *ts);
+
+/* Reset to idle. */
+void transition_reset(TransitionState *ts);
+
+/* Parse a style name string ("none", "elevator", etc.). */
+TransitionStyle transition_style_from_name(const char *name);
+
+/* Return the directive string for a style. */
+const char *transition_style_name(TransitionStyle style);
+
+#endif /* JNR_TRANSITION_H */