# 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.