#ifndef FESA_ELEMENTS_FINITE_ROTATION_H_
#define FESA_ELEMENTS_FINITE_ROTATION_H_

#include "fesa/core/status.h"
#include "fesa/math/matrix.h"
#include "fesa/math/vector3.h"

namespace fesa {

/// @brief Stores one finite-rotation coordinate and its derived triad state.
struct FiniteRotationState {
  /// @brief Fixed-global principal-chart rotation coordinate in radians.
  Vector3 phi;

  /// @brief Proper orthogonal triad computed as exp(phi^) times the initial
  /// frame.
  Matrix q;

  /// @brief Current director computed from the third column of q.
  Vector3 director;
};

/// @brief Computes Rodrigues' exponential of the three-dimensional skew map.
/// @param phi Fixed-global rotation coordinate in radians.
/// @return The 3-by-3 rotation tensor exp(phi^).
/// @pre phi is finite and lies inside the approved principal chart.
Matrix ExpSkew(const Vector3& phi);

/// @brief Computes the SO(3) left Jacobian for a fixed-global coordinate.
/// @param phi Fixed-global rotation coordinate in radians.
/// @return The 3-by-3 left Jacobian that maps coordinate variations to spatial
/// rotations.
/// @pre phi is finite and lies inside the approved principal chart.
Matrix LeftJacobianSO3(const Vector3& phi);

/// @brief Solves J(phi)^T * moment = generalized for a spatial moment.
/// @param phi Fixed-global principal-chart rotation coordinate in radians.
/// @param generalized Work-conjugate moment in fixed-global chart coordinates.
/// @return A finite spatial moment in the same force-length units, or failure.
/// @pre phi is finite and lies inside the approved principal chart.
/// @note Inputs remain unchanged; no inverse Jacobian is constructed.
Result<Vector3> SpatialMomentSO3(const Vector3& phi, const Vector3& generalized);

/// @brief Builds a checked finite-rotation state from its reference frame.
/// @param phi Fixed-global principal-chart rotation coordinate in radians.
/// @param initial_frame Valid initial right-handed 3-by-3 triad.
/// @return A complete finite state or an `invalid-accepted-state` failure.
/// @note The input frame is validated but never normalized or repaired.
Result<FiniteRotationState> MakeFiniteRotationState(
    const Vector3& phi, const Matrix& initial_frame);

/// @brief Applies a fixed-global Newton rotation increment to one state.
/// @param committed Fully validated state that remains unchanged by this call.
/// @param delta_phi Fixed-global additive rotation correction in radians.
/// @param initial_frame Valid initial right-handed 3-by-3 triad.
/// @return A rebuilt trial state or an `invalid-accepted-state` failure.
/// @note The result is recomputed from phi plus delta_phi and initial_frame;
/// incremental tensors are not successively composed.
Result<FiniteRotationState> ApplyGlobalRotationIncrement(
    const FiniteRotationState& committed, const Vector3& delta_phi,
    const Matrix& initial_frame);

}  // namespace fesa

#endif  // FESA_ELEMENTS_FINITE_ROTATION_H_