docs: Add maneuver UI controls implementation plan

docs/planning/maneuver_ui_controls.md

@@ -0,0 +1,149 @@
+# Maneuver UI Controls - Implementation Plan
+
+## Overview
+Add functionality to the maneuver.h module to support UI controls for creating and managing maneuvers in the graphical simulation.
+
+## Current Interface Analysis
+
+The maneuver module currently has:
+- **Burn direction functions**: `calculate_prograde_dir()`, `calculate_normal_dir()`, etc.
+- **Burn application**: `apply_impulsive_burn()`, `apply_custom_burn()`
+- **Maneuver execution**: `check_maneuver_trigger()`, `execute_maneuver()`
+- **No dynamic maneuver management**: Maneuvers are only loaded from config files
+
+## Recommended Additions to maneuver.h
+
+### 1. Maneuver Creation and Management
+
+```cpp
+// Create a new maneuver structure from parameters
+Maneuver create_maneuver(const char* name, int craft_index, BurnDirection direction,
+                         double delta_v, TriggerType trigger_type, double trigger_value);
+
+// Add maneuver to simulation (returns index or -1 on error)
+int add_maneuver_to_simulation(SimulationState* sim, Maneuver maneuver);
+
+// Remove maneuver by name or index
+bool remove_maneuver_by_name(SimulationState* sim, const char* name);
+bool remove_maneuver_by_index(SimulationState* sim, int index);
+
+// Clear all unexecuted maneuvers for a spacecraft
+void clear_pending_maneuvers(SimulationState* sim, int craft_index);
+```
+
+### 2. Burn Preview/Optimization
+
+```cpp
+// Preview burn result without executing (returns new orbital elements)
+OrbitalElements preview_burn_result(Spacecraft* craft, BurnDirection direction,
+                                    double delta_v, double parent_mass);
+
+// Calculate required delta-v for target orbital elements
+double calculate_delta_v_for_elements(Spacecraft* craft, OrbitalElements target_elements,
+                                      double parent_mass);
+
+// Calculate Hohmann transfer delta-v (two burns)
+struct HohmannTransfer {
+    double dv1;          // First burn delta-v
+    double dv2;          // Second burn delta-v
+    double transfer_time;  // Time to apoapsis
+    double true_anomaly_2;  // True anomaly for second burn
+};
+HohmannTransfer calculate_hohmann_transfer(double r1, double r2, double central_mass);
+```
+
+### 3. Maneuver Information and Validation
+
+```cpp
+// Get descriptive string for burn direction
+const char* get_burn_direction_name(BurnDirection direction);
+
+// Get descriptive string for trigger type
+const char* get_trigger_type_name(TriggerType trigger_type);
+
+// Check if a burn is feasible (e.g., not exceeding escape velocity if unintended)
+bool validate_burn_parameters(Spacecraft* craft, BurnDirection direction,
+                              double delta_v, double parent_mass);
+
+// Calculate time until true anomaly trigger
+double calculate_time_to_true_anomaly(Spacecraft* craft, double target_anomaly,
+                                      double parent_mass);
+```
+
+### 4. Undo/Snapshot Support
+
+```cpp
+// Save spacecraft state before burn
+struct SpacecraftSnapshot {
+    OrbitalElements orbit;
+    Vec3 local_position;
+    Vec3 local_velocity;
+};
+SpacecraftSnapshot save_spacecraft_snapshot(Spacecraft* craft);
+
+// Restore spacecraft state
+void restore_spacecraft_snapshot(Spacecraft* craft, SpacecraftSnapshot snapshot);
+
+// Create reversible maneuver structure
+struct ReversibleManeuver {
+    Maneuver maneuver;
+    SpacecraftSnapshot pre_burn_state;
+};
+```
+
+### 5. Maneuver Query Functions
+
+```cpp
+// Find maneuver by name (already exists in tests but not in header)
+int find_maneuver_by_name(SimulationState* sim, const char* name);
+
+// Get next pending maneuver for a spacecraft
+Maneuver* get_next_pending_maneuver(SimulationState* sim, int craft_index);
+
+// Get count of pending maneuvers for a spacecraft
+int get_pending_maneuver_count(SimulationState* sim, int craft_index);
+
+// Get all pending maneuvers for a spacecraft (returns array and count)
+Maneuver** get_pending_maneuvers_for_craft(SimulationState* sim, int craft_index, int* out_count);
+```
+
+### 6. Burn Direction Visualization
+
+```cpp
+// Get burn direction vector at specific orbital position
+Vec3 get_burn_direction_at_anomaly(Spacecraft* craft, BurnDirection direction,
+                                    double true_anomaly, double parent_mass);
+```
+
+## Implementation Considerations
+
+1. **Dynamic array management**: Since `SimulationState` has `max_maneuvers`, the add function should check capacity before adding.
+
+2. **Name uniqueness**: The config loader already enforces unique names; the UI should too.
+
+3. **Craft index validation**: When adding maneuvers via UI, verify the craft index is valid.
+
+4. **UI integration points**: These functions would be called from:
+   - **Main loop**: When user adds/edits maneuvers
+   - **UI renderer**: For displaying burn previews and validation feedback
+   - **Config saving**: To export UI-created maneuvers to TOML
+
+## Priority Recommendations
+
+**High Priority** (core UI functionality):
+1. `add_maneuver_to_simulation()` - Essential for UI creation
+2. `remove_maneuver_by_index()` - For editing/deleting
+3. `create_maneuver()` - Helper for constructing maneuvers
+4. `get_burn_direction_name()` - For UI labels
+
+**Medium Priority** (enhanced UX):
+5. `preview_burn_result()` - Show result before committing
+6. `calculate_hohmann_transfer()` - Common operation
+7. `validate_burn_parameters()` - Prevent errors
+
+**Lower Priority** (advanced features):
+8. Snapshot/undo functions
+9. Time-to-trigger calculations
+10. Reversible maneuvers
+
+This follows the existing C-style patterns in the codebase (structs, enums, simple functions) and provides the core functionality needed for a maneuver creation UI.