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. A panel is a section of the left rail, not a window of its own. The three steps this entry used to give were true and left out every way the work actually goes wrong, so they are spelled out here with the guard that catches each one.

  1. Add the module and give it a section. A module under ui/shell/src/panels/, declared and re-exported in panels/mod.rs, plus a UnifiedTab variant (viewer/core/src/ui_state/analysis.rs) listed in sections_for_mode (panels/unified.rs). Two matches there are exhaustive, so a new variant fails the compile until it has an accent colour and a body; what nothing forces is sections_for_mode, which returns a different list for edit mode and for view mode. A variant in neither list compiles, runs, and never appears.
  2. Return an action; do not reach out of the panel. Add a field to UnifiedPanelActions and handle it in viewer_loop/runtime/redraw/panels/mod.rs. A panel that needs a menu action calls dispatch_menu_action, which does the frame swap around it; only_one_dispatcher_builds_a_menu_action_context scans the sources and fails on a second dispatcher, because the landing card grew one and lost the tab focus with it.
  3. Know which half of the state you are writing. The panel is handed a full clone of UiState and sync_ui_state_from_temp (ui/shell/src/orchestration/sync.rs) copies it back, but not uniformly:
     • Copied whole, so a new field needs nothing: analysis, measurements, trajectory, chrome.panel, overlay, style, markup.annotations.
     • Copied field by name, so a new field is silently discarded every frame and reads as a checkbox that will not stick: viewport.view, selection, placement, edit, console, export, and markup.labels (one field of it, atom_label_overrides). Add the copy and extend the matching exhaustive-literal guard in that file (every_view_setting_survives_the_per_frame_clone, edit_settings_survive_the_per_frame_clone, camera_settings_survive_the_per_frame_clone), which then fails the compile rather than the behaviour. selection, console, export and markup.labels have no such guard yet; a new field there is on you.
     • Reconciled by an exhaustive destructure: runtime, through RuntimeUiState::merge_frame_edits, which classifies every field (50 today) as the frame’s, this copy’s, or session-gated. A new field there fails to compile until it is classified.
     • Not copied back at all: summaries, bundle, settings, dialogs, requests. The last two are deliberate (see PendingRequests), so a dialog can close itself.
     The cheapest way past all of this is to put new panel state in a sub-struct that is copied whole.
  4. A panel that loads something writes both copies through one call. A companion file, a volumetric dataset or an appearance bundle has to land on the canonical UiState as well as the frame’s, because the rest of the frame and the scene rebuild read it there. Use orchestration::frame_edit::edit_both; no_site_writes_the_two_copies_by_hand scans ui/shell/src for the hand-written pair and names the offender. A toast is the one thing that does not belong in it: push_toast appends, so applying it to both copies raises the message twice. A panel that only draws meets none of this.
  5. If it changes what is drawn, say so twice. Set render_data_changed = true on the actions, and make sure the new input is represented in RenderCacheKey (ui/shell/src/render_cache/key.rs) — otherwise the cache hits and returns the previous build, which is the inert-toggle bug this repo has shipped more than once. The key’s own doc comment lists the two compiler-enforced safeguards and the one gap they leave, which is forgetting to add the field at all; mirror a test in render_cache/tests.rs when you wire a new render-affecting control. One specific trap: do not hash a raw colour float that a widget writes back. color_edit_button_rgb round-trips through HSV and moves a channel by one ulp with no interaction, so SurfaceEntry::current_hash quantises colour to eight bits per channel.
  6. If it should survive a session, add the field to ui/shell/src/session/types.rs with a #[serde(default)], write it in save.rs and read it in restore.rs. A new UnifiedTab also needs an arm in unified_tab_from_str, or a session reopens on a different section than it was saved on. That one is enforced: every_unified_tab_round_trips_through_its_name (ui/shell/src/session/helpers.rs) walks the variants as a chain through an exhaustive match, so a new one fails the test’s compile rather than going unchecked.

  Gone, and listed because older notes still mention it: the loop no longer keeps mirror copies of view flags, chrome flags, measurement state, selection, the summary caches or the status line. UiState is the one owner of each, so a panel no longer has to write a value in two places to make it take effect.

• Expose a new CLI subcommand

  1. Update automation/cli/src/cli/mod.rs with the Clap definition (enum Commands).
  2. Implement the handler in a module under automation/cli/src/handlers/commands/, declared and re-exported in handlers/commands/mod.rs, and add its arm to the match on Commands in automation/cli/src/app.rs::run.
  3. Implement the logic using OrbitronServices instead of re-implementing loaders.
  4. Add user-facing documentation and tests (ideally under automation/cli/tests or as integration binaries). A test launches the binary through common::orbitron() (automation/cli/tests/support/common.rs), never Command::new(cargo_bin!("orbitron")): the helper points ORBITRON_CONFIG at a path nothing creates, so the run gets built-in defaults instead of your own config.toml. automation/cli/tests/config_isolation.rs scans the test sources and fails on a direct call site.

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