Appendix: Common Tasks

• Add a new file parser — see the I/O Pipelines chapter, §6.1. Not summarised here: this entry used to give four steps that left out registering the FormatHandler, which is what actually makes a file load.

• Add a keyboard shortcut

  1. Define the key mapping in ui/shell/src/keyboard.rs.
  2. Handle the action inside viewer_loop/key_actions/ (update KeyActionContext if new state is required).
  3. Update the User Guide’s shortcut tables.

• Create a new viewer panel

  1. Add a module under ui/shell/src/panels/.
  2. Expose actions via enums in the panels/ modules and wire them through ViewerLoop.
  3. Persist any new state in UiState and update serialisation logic if applicable.

• Expose a new CLI subcommand

  1. Update automation/cli/src/cli.rs with the Clap definition (enum Commands).
  2. Implement the logic using OrbitronServices instead of re-implementing loaders.
  3. Add user-facing documentation and tests (ideally under automation/cli/tests or as integration binaries).

• Expose functionality in the Python bridge

  1. Add public methods to the Orbitron or Scene pyclass (Rust PyOrbitron/PyScene) in extensions/python-bridge/src/python/ (orbitron.rs, scene.rs).
  2. Reuse existing service helpers; avoid duplicating logic already present in the CLI.
  3. Update docstrings and provide a short example in the User Guide or Python README.
  4. Rebuild through the PEP 517 wrapper so viewer assets are staged: conda run --no-capture-output -n orbitron-dev python -m pip install -e extensions/python-bridge. Add a focused test under extensions/python-bridge/tests.

• Add an analysis module shared by CLI/TUI

  1. Implement the core logic under automation/cli/src/handlers/ (the analyze handler lives at handlers/commands/analyze.rs; follow existing modules for geometry/orbitals).
  2. Expose the module through the AnalyzeCommands enum and handler.
  3. If the TUI should display the data, add a helper in automation/tui/src/analysis.rs and render it inside the appropriate panel.
  4. Capture representative fixtures in regression tests.

By following the patterns described in this guide and reusing existing abstractions, new features remain consistent with the rest of the Orbitron workspace while minimising regressions.