Add azimuth and lunar phase computations, enhance target handling

.clang-format

@@ -1,10 +1,13 @@
 ---
+Language: Cpp
 BasedOnStyle: LLVM
-IndentWidth: 4
-ContinuationIndentWidth: 4
-ColumnLimit: 0
-PointerAlignment: Left
-ReferenceAlignment: Left
-AlignConsecutiveAssignments: Consecutive
-AlignConsecutiveDeclarations: Consecutive
-...
+IndentWidth: 2
+ColumnLimit: 80
+AllowShortBlocksOnASingleLine: Never
+AllowShortFunctionsOnASingleLine: All
+AllowShortEnumsOnASingleLine: true
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AllowShortLambdasOnASingleLine: All
+AlwaysBreakTemplateDeclarations: MultiLine
+

CMakeLists.txt

@@ -47,11 +47,14 @@ endif()
 # Build siderust-ffi (depends on tempoch-ffi via tempoch-cpp subdirectory)
 add_custom_target(
     build_siderust_ffi
-    COMMAND ${CARGO_BIN} build --release ${_SIDERUST_FEATURES_ARGS}
+    # Use `cargo rustc --crate-type cdylib` so that the shared library is
+    # produced even though Cargo.toml only lists rlib (which keeps coverage
+    # instrumentation clean during `cargo test`/`cargo llvm-cov`).
+    COMMAND ${CARGO_BIN} rustc --release --crate-type cdylib ${_SIDERUST_FEATURES_ARGS}
     WORKING_DIRECTORY ${SIDERUST_FFI_DIR}
     BYPRODUCTS ${SIDERUST_LIBRARY_PATH}
     DEPENDS build_tempoch_ffi
-    COMMENT "Building siderust-ffi via Cargo"
+    COMMENT "Building siderust-ffi via Cargo (cdylib override)"
     VERBATIM
 )
 
@@ -101,23 +104,27 @@ if(SIDERUST_BUILD_DOCS)
         set(SIDERUST_DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile.siderust_cpp)
         configure_file(${SIDERUST_DOXYFILE_IN} ${SIDERUST_DOXYFILE_OUT} @ONLY)
 
-        add_custom_target(docs
-            COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen
-            COMMAND ${DOXYGEN_EXECUTABLE} ${SIDERUST_DOXYFILE_OUT}
-            WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-            COMMENT "Generating API documentation with Doxygen"
-            VERBATIM
-        )
+        if(NOT TARGET docs)
+            add_custom_target(docs
+                COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen
+                COMMAND ${DOXYGEN_EXECUTABLE} ${SIDERUST_DOXYFILE_OUT}
+                WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+                COMMENT "Generating API documentation with Doxygen"
+                VERBATIM
+            )
+        else()
+            message(STATUS "Top-level 'docs' target already exists; skipping creation to avoid conflict with subprojects")
+        endif()
     else()
         message(STATUS "Doxygen not found; 'docs' target will not be available")
     endif()
 endif()
 
 # RPATH for shared library lookup at runtime
 if(APPLE)
-    set(_siderust_rpath "@loader_path/../siderust/target/release;@loader_path/../tempoch-cpp/tempoch/tempoch-ffi/target/release;@loader_path/../qtty-cpp/qtty/target/release")
+    set(_siderust_rpath "@loader_path/../siderust/siderust-ffi/target/release;@loader_path/../tempoch-cpp/tempoch/tempoch-ffi/target/release;@loader_path/../qtty-cpp/qtty/target/release")
 elseif(UNIX)
-    set(_siderust_rpath "$ORIGIN/../siderust/target/release:$ORIGIN/../tempoch-cpp/tempoch/tempoch-ffi/target/release:$ORIGIN/../qtty-cpp/qtty/target/release")
+    set(_siderust_rpath "$ORIGIN/../siderust/siderust-ffi/target/release:$ORIGIN/../tempoch-cpp/tempoch/tempoch-ffi/target/release:$ORIGIN/../qtty-cpp/qtty/target/release")
 endif()
 
 # ---------------------------------------------------------------------------
@@ -182,6 +189,24 @@ if(DEFINED _siderust_rpath)
     )
 endif()
 
+add_executable(trackable_targets_example examples/trackable_targets_example.cpp)
+target_link_libraries(trackable_targets_example PRIVATE siderust_cpp)
+if(DEFINED _siderust_rpath)
+    set_target_properties(trackable_targets_example PROPERTIES
+        BUILD_RPATH ${_siderust_rpath}
+        INSTALL_RPATH ${_siderust_rpath}
+    )
+endif()
+
+add_executable(azimuth_lunar_phase_example examples/azimuth_lunar_phase_example.cpp)
+target_link_libraries(azimuth_lunar_phase_example PRIVATE siderust_cpp)
+if(DEFINED _siderust_rpath)
+    set_target_properties(azimuth_lunar_phase_example PROPERTIES
+        BUILD_RPATH ${_siderust_rpath}
+        INSTALL_RPATH ${_siderust_rpath}
+    )
+endif()
+
 # ---------------------------------------------------------------------------
 # Tests
 # ---------------------------------------------------------------------------

README.md

@@ -10,38 +10,39 @@ Modern, header-only C++17 wrapper for **siderust** — a high-precision astronom
 |--------|-------------|
 | **Time** (`time.hpp`) | `JulianDate`, `MJD`, `UTC`, `Period` — value types with arithmetic and UTC round-trips |
 | **Coordinates** (`coordinates.hpp`) | Modular typed API (`coordinates/{geodetic,spherical,cartesian,types}.hpp`) plus selective alias headers under `coordinates/types/{spherical,cartesian}/...` |
+| **Frames & Centers** (`frames.hpp`, `centers.hpp`) | Compile-time frame/center tags and transform capability traits |
 | **Bodies** (`bodies.hpp`) | `Star` (RAII, catalog + custom), `Planet` (8 planets), `ProperMotion`, `Orbit` |
 | **Observatories** (`observatories.hpp`) | Named sites: Roque de los Muchachos, Paranal, Mauna Kea, La Silla |
 | **Altitude** (`altitude.hpp`) | Sun / Moon / Star / ICRS altitude: instant, above/below threshold, crossings, culminations |
+| **Azimuth** (`azimuth.hpp`) | Sun / Moon / Star / ICRS azimuth: instant, crossings, extrema, range windows |
+| **Targets** (`trackable.hpp`, `target.hpp`, `body_target.hpp`, `star_target.hpp`) | Polymorphic tracking with `Trackable`, `Target`, `BodyTarget`, and `StarTarget` |
+| **Lunar Phase** (`lunar_phase.hpp`) | Phase geometry/labels, principal phase events, illumination window search |
 | **Ephemeris** (`ephemeris.hpp`) | VSOP87 Sun/Earth positions, ELP2000 Moon position |
 
 ## Quick Start
 
 ```cpp
 #include <siderust/siderust.hpp>
-#include <cstdio>
+#include <iostream>
 
 int main() {
     using namespace siderust;
-    using namespace qtty::literals;
 
     auto obs  = ROQUE_DE_LOS_MUCHACHOS;
     auto jd   = JulianDate::from_utc({2026, 7, 15, 22, 0, 0});
     auto mjd  = MJD::from_jd(jd);
+    auto win  = Period(mjd, mjd + qtty::Day(1.0));
 
-    // Sun altitude
-    qtty::Radian alt = sun::altitude_at(obs, mjd);
-    std::printf("Sun altitude: %.4f rad\n", alt.value());
+    qtty::Degree sun_alt = sun::altitude_at(obs, mjd).to<qtty::Degree>();
+    qtty::Degree sun_az  = sun::azimuth_at(obs, mjd);
+    std::cout << "Sun alt=" << sun_alt.value() << " deg"
+              << " az=" << sun_az.value() << " deg\n";
 
-    // Star from catalog
-    const auto& vega = VEGA;
-    qtty::Radian star_alt = star_altitude::altitude_at(vega, obs, mjd);
-    std::printf("Vega altitude: %.4f rad\n", star_alt.value());
+    Target fixed(279.23473, 38.78369); // Vega-like ICRS target
+    std::cout << "Target alt=" << fixed.altitude_at(obs, mjd).value() << " deg\n";
 
-    // Night periods (astronomical twilight)
-    auto nights = sun::below_threshold(obs, mjd, mjd + 1.0, -18.0_deg);
-    for (auto& p : nights)
-        std::printf("Night: MJD %.4f – %.4f\n", p.start_mjd(), p.end_mjd());
+    auto nights = sun::below_threshold(obs, win, qtty::Degree(-18.0));
+    std::cout << "Astronomical-night periods in next 24h: " << nights.size() << "\n";
 
     return 0;
 }
@@ -65,6 +66,8 @@ cmake --build .
 ./coordinate_systems_example
 ./solar_system_bodies_example
 ./altitude_events_example
+./trackable_targets_example
+./azimuth_lunar_phase_example
 
 # Run tests
 ctest --output-on-failure
@@ -153,6 +156,12 @@ siderust-cpp/
 │   ├── bodies.hpp            ← Star, Planet, ProperMotion
 │   ├── observatories.hpp     ← named observatory locations
 │   ├── altitude.hpp          ← sun/moon/star altitude API
+│   ├── azimuth.hpp           ← azimuth queries and events
+│   ├── lunar_phase.hpp       ← moon phase geometry and events
+│   ├── trackable.hpp         ← polymorphic trackable interface
+│   ├── target.hpp            ← fixed ICRS target (RAII)
+│   ├── body_target.hpp       ← body enum trackable adapter
+│   ├── star_target.hpp       ← star trackable adapter
 │   └── ephemeris.hpp         ← VSOP87/ELP2000 positions
 ├── examples/demo.cpp
 ├── tests/

docs/mainpage.md

@@ -21,6 +21,9 @@ codebase without writing a single line of Rust.
 | **Bodies** (`bodies.hpp`) | `Star` (RAII, catalog + custom), `Planet` (8 planets), `ProperMotion`, `Orbit` |
 | **Observatories** (`observatories.hpp`) | Named sites: Roque de los Muchachos, Paranal, Mauna Kea, La Silla |
 | **Altitude** (`altitude.hpp`) | Sun / Moon / Star / ICRS altitude: instant, above/below threshold, crossings, culminations |
+| **Azimuth** (`azimuth.hpp`) | Sun / Moon / Star / ICRS azimuth: instant, crossings, extrema, range windows |
+| **Targets** (`trackable.hpp`, `target.hpp`, `body_target.hpp`, `star_target.hpp`) | Polymorphic target tracking across bodies, stars, and fixed ICRS directions |
+| **Lunar Phase** (`lunar_phase.hpp`) | Moon phase geometry, labels, principal phase events, illumination windows |
 | **Ephemeris** (`ephemeris.hpp`) | VSOP87 Sun/Earth positions, ELP2000 Moon position |
 
 ---
@@ -29,29 +32,27 @@ codebase without writing a single line of Rust.
 
 ```cpp
 #include <siderust/siderust.hpp>
-#include <cstdio>
+#include <iostream>
+#include <iomanip>
 
 int main() {
     using namespace siderust;
-    using namespace qtty::literals;
 
     auto obs = ROQUE_DE_LOS_MUCHACHOS;
     auto jd  = JulianDate::from_utc({2026, 7, 15, 22, 0, 0});
     auto mjd = MJD::from_jd(jd);
+    auto win = Period(mjd, mjd + qtty::Day(1.0));
 
-    // Sun altitude at the observatory
-    qtty::Radian alt = sun::altitude_at(obs, mjd);
-    std::printf("Sun altitude: %.4f rad\n", alt.value());
+    qtty::Degree sun_alt = sun::altitude_at(obs, mjd).to<qtty::Degree>();
+    qtty::Degree sun_az  = sun::azimuth_at(obs, mjd);
+    std::cout << "Sun alt=" << sun_alt.value() << " deg"
+              << " az=" << sun_az.value() << " deg\n";
 
-    // Star from built-in catalog
-    const auto& vega    = VEGA;
-    qtty::Radian star_alt = star_altitude::altitude_at(vega, obs, mjd);
-    std::printf("Vega altitude: %.4f rad\n", star_alt.value());
+    Target fixed(279.23473, 38.78369); // Vega-like fixed ICRS target
+    std::cout << "Target alt=" << fixed.altitude_at(obs, mjd).value() << " deg\n";
 
-    // Astronomical night periods (twilight < -18°)
-    auto nights = sun::below_threshold(obs, mjd, mjd + 1.0, -18.0_deg);
-    for (auto& p : nights)
-        std::printf("Night: MJD %.4f – %.4f\n", p.start_mjd(), p.end_mjd());
+    auto nights = sun::below_threshold(obs, win, qtty::Degree(-18.0));
+    std::cout << "Astronomical-night periods in next 24h: " << nights.size() << "\n";
 
     return 0;
 }
@@ -112,6 +113,8 @@ cmake --build .
 ./coordinate_systems_example
 ./solar_system_bodies_example
 ./altitude_events_example
+./trackable_targets_example
+./azimuth_lunar_phase_example
 
 # Run tests
 ctest --output-on-failure
@@ -130,6 +133,9 @@ ctest --output-on-failure
 - `siderust/bodies.hpp` — `Star`, `Planet`, and orbital / proper-motion types
 - `siderust/observatories.hpp` — known observatory locations and custom geodetic points
 - `siderust/altitude.hpp` — Sun / Moon / Star altitude queries and event search
+- `siderust/azimuth.hpp` — azimuth queries, crossings, extrema, and azimuth ranges
+- `siderust/trackable.hpp`, `siderust/target.hpp`, `siderust/body_target.hpp`, `siderust/star_target.hpp` — target abstractions and polymorphic tracking
+- `siderust/lunar_phase.hpp` — moon phase geometry, labels, phase events, illumination windows
 - `siderust/ephemeris.hpp` — VSOP87 / ELP2000 position queries
 
 ---

examples/README.md

@@ -3,24 +3,28 @@
 Build from the repository root:
 
 ```bash
-cmake -S . -B build-make
-cmake --build build-make
+cmake -S . -B build
+cmake --build build
 ```
 
 Run selected examples:
 
 ```bash
-./build-make/demo
-./build-make/coordinates_examples
-./build-make/coordinate_systems_example
-./build-make/solar_system_bodies_example
-./build-make/altitude_events_example
+./build/siderust_demo
+./build/coordinates_examples
+./build/coordinate_systems_example
+./build/solar_system_bodies_example
+./build/altitude_events_example
+./build/trackable_targets_example
+./build/azimuth_lunar_phase_example
 ```
 
 ## Files
 
-- `demo.cpp`: broad API walkthrough.
-- `coordinates_examples.cpp`: typed coordinate creation and frame transforms.
-- `coordinate_systems_example.cpp`: coordinate systems + direction/position transforms in one place.
-- `solar_system_bodies_example.cpp`: ephemeris vectors and static planet catalog data.
-- `altitude_events_example.cpp`: altitude periods, crossings, and culminations for Sun, Moon, VEGA, and fixed ICRS directions.
+- `demo.cpp`: end-to-end extended walkthrough (time, typed coordinates, altitude/azimuth, trackables, ephemeris, lunar phase).
+- `coordinates_examples.cpp`: typed coordinate construction and core conversion patterns.
+- `coordinate_systems_example.cpp`: frame-tag traits and practical frame/horizontal transforms.
+- `solar_system_bodies_example.cpp`: planet catalog constants, body-dispatch API, and ephemeris vectors.
+- `altitude_events_example.cpp`: altitude windows/crossings/culminations for Sun, Moon, stars, ICRS directions, and `Target`.
+- `trackable_targets_example.cpp`: polymorphic tracking with `Trackable`, `BodyTarget`, `StarTarget`, and `Target`.
+- `azimuth_lunar_phase_example.cpp`: azimuth events/ranges plus lunar phase geometry, labels, and phase-event searches.