refactor: extract spline math, consolidate packet parsing, decompose TransportManager

Extract CatmullRomSpline (include/math/spline.hpp, src/math/spline.cpp) as a
standalone, immutable, thread-safe spline module with O(log n) binary segment
search and fused position+tangent evaluation — replacing the duplicated O(n)
evalTimedCatmullRom/orientationFromTangent pair in TransportManager.

Consolidate 7 copies of spline packet parsing into shared functions in
game/spline_packet.{hpp,cpp}: parseMonsterMoveSplineBody (WotLK/TBC),
parseMonsterMoveSplineBodyVanilla, parseClassicMoveUpdateSpline,
parseWotlkMoveUpdateSpline, and decodePackedDelta. Named SplineFlag constants
replace magic hex literals throughout.

Extract TransportPathRepository (game/transport_path_repository.{hpp,cpp}) from
TransportManager — owns path data, DBC loading, and path inference. Paths stored
as PathEntry wrapping CatmullRomSpline + metadata (zOnly, fromDBC, worldCoords).
TransportManager reduced from ~1200 to ~500 lines, focused on transport lifecycle
and server sync.

Signed-off-by: Pavel Okhlopkov <pavel.okhlopkov@flant.com>

include/core/application.hpp

@@ -113,7 +113,7 @@ public:
     // World loader access
     WorldLoader* getWorldLoader() { return worldLoader_.get(); }
 
-    // Audio coordinator access (Section 4.1: extracted audio subsystem)
+    // Audio coordinator access
     audio::AudioCoordinator* getAudioCoordinator() { return audioCoordinator_.get(); }
 
 private:

include/game/spline_packet.hpp

@@ -0,0 +1,108 @@
+// include/game/spline_packet.hpp
+// Consolidated spline packet parsing — replaces 7 duplicated parsing locations.
+#pragma once
+#include "network/packet.hpp"
+#include <glm/glm.hpp>
+#include <vector>
+#include <cstdint>
+
+namespace wowee::game {
+
+/// Decoded spline data from a movement or MonsterMove packet.
+struct SplineBlockData {
+    uint32_t splineFlags = 0;
+    uint32_t duration = 0;
+
+    // Animation (splineFlag 0x00400000)
+    bool     hasAnimation = false;
+    uint8_t  animationType = 0;
+    uint32_t animationStartTime = 0;
+
+    // Parabolic (splineFlag 0x00000800 for MonsterMove, 0x00000008 for MoveUpdate)
+    bool     hasParabolic = false;
+    float    verticalAcceleration = 0.0f;
+    uint32_t parabolicStartTime = 0;
+
+    // FINAL_POINT / FINAL_TARGET / FINAL_ANGLE (movement update only)
+    bool     hasFinalPoint = false;
+    glm::vec3 finalPoint{0};
+    bool     hasFinalTarget = false;
+    uint64_t finalTarget = 0;
+    bool     hasFinalAngle = false;
+    float    finalAngle = 0.0f;
+
+    // Timing (movement update only)
+    uint32_t timePassed = 0;
+    uint32_t splineId = 0;
+
+    // Waypoints (server coordinates, decoded from packed-delta if compressed)
+    std::vector<glm::vec3> waypoints;
+    glm::vec3 destination{0};
+    bool hasDest = false;
+
+    // SplineMode (movement update WotLK only)
+    uint8_t splineMode = 0;
+    glm::vec3 endPoint{0};
+    bool hasEndPoint = false;
+};
+
+// ── Spline flag constants ───────────────────────────────────────
+namespace SplineFlag {
+    constexpr uint32_t FINAL_POINT    = 0x00010000;
+    constexpr uint32_t FINAL_TARGET   = 0x00020000;
+    constexpr uint32_t FINAL_ANGLE    = 0x00040000;
+    constexpr uint32_t CATMULLROM     = 0x00080000; // Uncompressed Catmull-Rom
+    constexpr uint32_t CYCLIC         = 0x00100000; // Cyclic path
+    constexpr uint32_t ENTER_CYCLE    = 0x00200000; // Entering cyclic path
+    constexpr uint32_t ANIMATION      = 0x00400000; // Animation spline
+    constexpr uint32_t PARABOLIC_MM   = 0x00000800; // Parabolic in MonsterMove
+    constexpr uint32_t PARABOLIC_MU   = 0x00000008; // Parabolic in MoveUpdate
+
+    // Mask: if any of these are set, waypoints are uncompressed
+    constexpr uint32_t UNCOMPRESSED_MASK = CATMULLROM | CYCLIC | ENTER_CYCLE;
+    // TBC-era alternative for uncompressed check
+    constexpr uint32_t UNCOMPRESSED_MASK_TBC = CATMULLROM | 0x00002000;
+} // namespace SplineFlag
+
+/// Decode a single packed-delta waypoint.
+/// Format: bits [0:10] = X (11-bit signed), [11:21] = Y (11-bit signed), [22:31] = Z (10-bit signed).
+/// Each component is multiplied by 0.25 and subtracted from `midpoint`.
+[[nodiscard]] glm::vec3 decodePackedDelta(uint32_t packed, const glm::vec3& midpoint);
+
+/// Parse a MonsterMove spline body (after splineFlags has already been read).
+/// Handles: Animation, duration, Parabolic, pointCount, compressed/uncompressed waypoints.
+/// `startPos` is the creature's current position (needed for packed-delta midpoint calculation).
+/// `splineFlags` is the already-read spline flags value.
+/// `useTbcUncompressedMask`: if true, use 0x00080000|0x00002000 for uncompressed check (TBC format).
+[[nodiscard]] bool parseMonsterMoveSplineBody(
+    network::Packet& packet,
+    SplineBlockData& out,
+    uint32_t splineFlags,
+    const glm::vec3& startPos,
+    bool useTbcUncompressedMask = false);
+
+/// Parse a MonsterMove spline body where waypoints are always compressed (Vanilla format).
+/// `startPos` is the creature's current position.
+[[nodiscard]] bool parseMonsterMoveSplineBodyVanilla(
+    network::Packet& packet,
+    SplineBlockData& out,
+    uint32_t splineFlags,
+    const glm::vec3& startPos);
+
+/// Parse a Classic/Turtle movement update spline block.
+/// Format: splineFlags, FINAL_POINT/TARGET/ANGLE, timePassed, duration, splineId,
+/// pointCount, uncompressed waypoints (12 bytes each), endPoint (no splineMode).
+[[nodiscard]] bool parseClassicMoveUpdateSpline(
+    network::Packet& packet,
+    SplineBlockData& out);
+
+/// Parse a WotLK movement update spline block.
+/// Format: splineFlags, FINAL_POINT/TARGET/ANGLE, timePassed, duration, splineId,
+/// then WotLK header (durationMod, durationModNext, [Animation], [Parabolic],
+/// pointCount, splineMode, endPoint) with multi-strategy fallback.
+[[nodiscard]] bool parseWotlkMoveUpdateSpline(
+    network::Packet& packet,
+    SplineBlockData& out,
+    const glm::vec3& entityPos = glm::vec3(0));
+
+} // namespace wowee::game

include/game/transport_manager.hpp

@@ -1,5 +1,6 @@
 #pragma once
 
+#include "game/transport_path_repository.hpp"
 #include <cstdint>
 #include <vector>
 #include <unordered_map>
@@ -18,21 +19,6 @@ namespace wowee::pipeline {
 
 namespace wowee::game {
 
-struct TimedPoint {
-    uint32_t tMs;          // Time in milliseconds from DBC
-    glm::vec3 pos;         // Position at this time
-};
-
-struct TransportPath {
-    uint32_t pathId;
-    std::vector<TimedPoint> points;  // Time-indexed waypoints (includes duplicate first point at end for wrap)
-    bool looping;  // Set to false after adding explicit wrap point
-    uint32_t durationMs;   // Total loop duration in ms (includes wrap segment if added)
-    bool zOnly;    // True if path only has Z movement (elevator/bobbing), false if real XY travel
-    bool fromDBC;  // True if loaded from TransportAnimation.dbc, false for runtime fallback/custom paths
-    bool worldCoords = false;  // True if points are absolute world coords (TaxiPathNode), not local offsets
-};
-
 struct ActiveTransport {
     uint64_t guid;              // Entity GUID
     uint32_t wmoInstanceId;     // WMO renderer instance ID
@@ -137,13 +123,12 @@ public:
 
 private:
     void updateTransportMovement(ActiveTransport& transport, float deltaTime);
-    glm::vec3 evalTimedCatmullRom(const TransportPath& path, uint32_t pathTimeMs);
-    glm::quat orientationFromTangent(const TransportPath& path, uint32_t pathTimeMs);
     void updateTransformMatrices(ActiveTransport& transport);
+    /// Legacy transport orientation from tangent (preserves original cross-product order).
+    static glm::quat orientationFromSplineTangent(const glm::vec3& tangent);
 
+    TransportPathRepository pathRepo_;
     std::unordered_map<uint64_t, ActiveTransport> transports_;
-    std::unordered_map<uint32_t, TransportPath> paths_;      // Indexed by transportEntry (pathId from TransportAnimation.dbc)
-    std::unordered_map<uint32_t, TransportPath> taxiPaths_;  // Indexed by TaxiPath.dbc ID (world-coord paths for MO_TRANSPORT)
     rendering::WMORenderer* wmoRenderer_ = nullptr;
     rendering::M2Renderer* m2Renderer_ = nullptr;
     bool clientSideAnimation_ = false;  // DISABLED - use server positions instead of client prediction

include/game/transport_path_repository.hpp

@@ -0,0 +1,67 @@
+// include/game/transport_path_repository.hpp
+// Owns and manages transport path data — DBC, taxi, and custom paths.
+// Uses CatmullRomSpline for spline evaluation (replaces duplicated evalTimedCatmullRom).
+// Separated from TransportManager for SOLID-S (single responsibility).
+#pragma once
+
+#include "math/spline.hpp"
+#include <cstdint>
+#include <vector>
+#include <unordered_map>
+#include <glm/glm.hpp>
+
+namespace wowee::pipeline {
+    class AssetManager;
+}
+
+namespace wowee::game {
+
+/// Metadata + CatmullRomSpline for a transport path.
+struct PathEntry {
+    math::CatmullRomSpline spline;
+    uint32_t pathId = 0;
+    bool zOnly = false;       // Elevator/bobbing — no meaningful XY travel
+    bool fromDBC = false;     // Loaded from TransportAnimation.dbc
+    bool worldCoords = false; // TaxiPathNode absolute world positions (not local offsets)
+
+    PathEntry(math::CatmullRomSpline s, uint32_t id, bool zo, bool dbc, bool wc)
+        : spline(std::move(s)), pathId(id), zOnly(zo), fromDBC(dbc), worldCoords(wc) {}
+};
+
+/// Owns and manages transport path data.
+class TransportPathRepository {
+public:
+    TransportPathRepository() = default;
+
+    // ── DBC loading ─────────────────────────────────────────
+    bool loadTransportAnimationDBC(pipeline::AssetManager* assetMgr);
+    bool loadTaxiPathNodeDBC(pipeline::AssetManager* assetMgr);
+
+    // ── Path construction ───────────────────────────────────
+    void loadPathFromNodes(uint32_t pathId, const std::vector<glm::vec3>& waypoints,
+                           bool looping = true, float speed = 18.0f);
+
+    // ── Lookup ──────────────────────────────────────────────
+    const PathEntry* findPath(uint32_t pathId) const;
+    const PathEntry* findTaxiPath(uint32_t taxiPathId) const;
+    bool hasPathForEntry(uint32_t entry) const;
+    bool hasTaxiPath(uint32_t taxiPathId) const;
+
+    // ── Query ───────────────────────────────────────────────
+    bool hasUsableMovingPathForEntry(uint32_t entry, float minXYRange = 1.0f) const;
+    uint32_t inferDbcPathForSpawn(const glm::vec3& spawnWorldPos, float maxDistance,
+                                  bool allowZOnly) const;
+    uint32_t inferMovingPathForSpawn(const glm::vec3& spawnWorldPos,
+                                     float maxDistance = 1200.0f) const;
+    uint32_t pickFallbackMovingPath(uint32_t entry, uint32_t displayId) const;
+
+    // ── Mutation ─────────────────────────────────────────────
+    /// Store or overwrite a path entry (used by assignTaxiPathToTransport).
+    void storePath(uint32_t pathId, PathEntry entry);
+
+private:
+    std::unordered_map<uint32_t, PathEntry> paths_;
+    std::unordered_map<uint32_t, PathEntry> taxiPaths_;
+};
+
+} // namespace wowee::game

include/math/spline.hpp

@@ -0,0 +1,77 @@
+// include/math/spline.hpp
+// Standalone Catmull-Rom spline module with zero external dependencies beyond GLM.
+// Immutable after construction — thread-safe for concurrent reads.
+#pragma once
+#include <glm/glm.hpp>
+#include <glm/gtc/quaternion.hpp>
+#include <vector>
+#include <cstdint>
+
+namespace wowee::math {
+
+/// A single time-indexed control point on a spline.
+struct SplineKey {
+    uint32_t timeMs;
+    glm::vec3 position;
+};
+
+/// Result of evaluating a spline at a given time — position + tangent.
+struct SplineEvalResult {
+    glm::vec3 position;
+    glm::vec3 tangent;       // Unnormalized derivative
+};
+
+/// Immutable spline path. Constructed once, evaluated many times.
+/// Thread-safe for concurrent reads after construction.
+class CatmullRomSpline {
+public:
+    /// Construct from time-sorted keys.
+    /// If `timeClosed` is true, the path wraps: first and last keys share endpoints.
+    /// If false, uses clamped endpoints (no wrapping).
+    explicit CatmullRomSpline(std::vector<SplineKey> keys, bool timeClosed = false);
+
+    /// Evaluate position at given path time (clamped to [0, duration]).
+    [[nodiscard]] glm::vec3 evaluatePosition(uint32_t pathTimeMs) const;
+
+    /// Evaluate position and tangent at given path time.
+    [[nodiscard]] SplineEvalResult evaluate(uint32_t pathTimeMs) const;
+
+    /// Derive orientation quaternion from tangent (Z-up convention).
+    [[nodiscard]] static glm::quat orientationFromTangent(const glm::vec3& tangent);
+
+    /// Total duration of the spline in milliseconds.
+    [[nodiscard]] uint32_t durationMs() const { return durationMs_; }
+
+    /// Number of control points.
+    [[nodiscard]] size_t keyCount() const { return keys_.size(); }
+
+    /// Direct access to keys (for path inference, etc.).
+    [[nodiscard]] const std::vector<SplineKey>& keys() const { return keys_; }
+
+    /// Whether this spline has meaningful XY movement (not just Z-only like elevators).
+    [[nodiscard]] bool hasXYMovement(float minRange = 1.0f) const;
+
+    /// Find nearest key index to a world position (for phase estimation).
+    [[nodiscard]] size_t findNearestKey(const glm::vec3& position) const;
+
+    /// Whether the spline is time-closed (wrapping).
+    [[nodiscard]] bool isTimeClosed() const { return timeClosed_; }
+
+private:
+    /// Binary search for segment containing pathTimeMs. O(log n).
+    [[nodiscard]] size_t findSegment(uint32_t pathTimeMs) const;
+
+    /// Get 4 control points {p0,p1,p2,p3} for the segment starting at `segIdx`.
+    struct ControlPoints { glm::vec3 p0, p1, p2, p3; };
+    [[nodiscard]] ControlPoints getControlPoints(size_t segIdx) const;
+
+    /// Evaluate position and tangent for a segment at parameter t in [0,1].
+    [[nodiscard]] SplineEvalResult evalSegment(
+        const ControlPoints& cp, float t) const;
+
+    std::vector<SplineKey> keys_;
+    bool timeClosed_;
+    uint32_t durationMs_;
+};
+
+} // namespace wowee::math

include/ui/action_bar_panel.hpp

@@ -71,7 +71,7 @@ public:
     std::unordered_map<uint32_t, uint32_t> macroPrimarySpellCache_;
     size_t macroCacheSpellCount_ = 0;
 
-    // Section 3.5: UIServices injection (Phase B singleton breaking)
+    // UIServices injection (Phase B singleton breaking)
     void setServices(const UIServices& services) { services_ = services; }
 
 private:

include/ui/chat_panel.hpp

@@ -110,14 +110,14 @@ public:
     /** Reset all chat settings to defaults. */
     void restoreDefaults();
 
-    // Section 3.5: UIServices injection (Phase B singleton breaking)
+    // UIServices injection (Phase B singleton breaking)
     void setServices(const UIServices& services) { services_ = services; }
 
     /** Replace $g/$G and $n/$N gender/name placeholders in quest/chat text. */
     std::string replaceGenderPlaceholders(const std::string& text, game::GameHandler& gameHandler);
 
 private:
-    // Section 3.5: Injected UI services (Phase B singleton breaking)
+    // Injected UI services (Phase B singleton breaking)
     UIServices services_;
 
     // ---- Chat input state ----

include/ui/combat_ui.hpp

@@ -72,7 +72,7 @@ public:
     void renderThreatWindow(game::GameHandler& gameHandler);
     void renderBgScoreboard(game::GameHandler& gameHandler);
 
-    // Section 3.5: UIServices injection (Phase B singleton breaking)
+    // UIServices injection (Phase B singleton breaking)
     void setServices(const UIServices& services) { services_ = services; }
 
 private:

include/ui/dialog_manager.hpp

@@ -35,11 +35,11 @@ public:
     /// called in render() after reclaim corpse button
     void renderLateDialogs(game::GameHandler& gameHandler);
 
-    // Section 3.5: UIServices injection (Phase B singleton breaking)
+    // UIServices injection (Phase B singleton breaking)
     void setServices(const UIServices& services) { services_ = services; }
 
 private:
-    // Section 3.5: Injected UI services
+    // Injected UI services
     UIServices services_;
     // Common ImGui window flags for popup dialogs
     static constexpr ImGuiWindowFlags kDialogFlags =

include/ui/game_screen.hpp

@@ -55,7 +55,7 @@ public:
     // Dependency injection for extracted classes (Phase A singleton breaking)
     void setAppearanceComposer(core::AppearanceComposer* ac) { appearanceComposer_ = ac; }
 
-    // Section 3.5: UIServices injection (Phase B singleton breaking)
+    // UIServices injection (Phase B singleton breaking)
     void setServices(const UIServices& services);
 
 private:

include/ui/social_panel.hpp

@@ -73,7 +73,7 @@ public:
     void renderInspectWindow(game::GameHandler& gameHandler,
                              InventoryScreen& inventoryScreen);
 
-    // Section 3.5: UIServices injection (Phase B singleton breaking)
+    // UIServices injection (singleton breaking)
     void setServices(const UIServices& services) { services_ = services; }
 
 private:

include/ui/toast_manager.hpp

@@ -41,7 +41,7 @@ public:
     /// Fire achievement earned toast + sound
     void triggerAchievementToast(uint32_t achievementId, std::string name = {});
 
-    // Section 3.5: UIServices injection (Phase B singleton breaking)
+    // UIServices injection (Phase B singleton breaking)
     void setServices(const UIServices& services) { services_ = services; }
 
     // --- public state consumed by GameScreen for the golden burst overlay ---
@@ -49,7 +49,7 @@ public:
     uint32_t levelUpDisplayLevel = 0;
 
 private:
-    // Section 3.5: Injected UI services
+    // Injected UI services
     UIServices services_;
 
     // ---- Ding effect (own level-up) ----

include/ui/ui_manager.hpp

@@ -75,7 +75,7 @@ public:
         if (gameScreen) gameScreen->setAppearanceComposer(ac);
     }
 
-    // Section 3.5: UIServices injection (Phase B singleton breaking)
+    // UIServices injection (Phase B singleton breaking)
     void setServices(const UIServices& services) {
         services_ = services;
         if (gameScreen) gameScreen->setServices(services);
@@ -86,7 +86,7 @@ public:
 
 private:
     core::Window* window = nullptr;
-    UIServices services_;  // Section 3.5: Injected services
+    UIServices services_;  // Injected services
 
     // UI Screens
     std::unique_ptr<AuthScreen> authScreen;

include/ui/ui_services.hpp

@@ -23,7 +23,7 @@ namespace ui {
 /**
  * UI Services - Dependency injection container for UI components.
  * 
- * Section 3.5: Break the singleton Phase B
+ * Break the singleton Phase B
  * 
  * Replaces Application::getInstance() calls throughout UI code.
  * Application creates this struct and injects it into UIManager,

include/ui/window_manager.hpp

@@ -174,7 +174,7 @@ public:
     std::unordered_map<uint32_t, ExtendedCostEntry> extendedCostCache_;
     bool extendedCostDbLoaded_ = false;
 
-    // Section 3.5: UIServices injection (Phase B singleton breaking)
+    // UIServices injection (Phase B singleton breaking)
     void setServices(const UIServices& services) { services_ = services; }
 
 private: