XGC-GUI Developer Notes
=======================

Overview
^^^^^^^^

The browser GUI under ``utils/input_gui/`` has two major parts:

* The ``Editor`` for manipulating XGC ``input`` files
* The ``Monitor`` for browsing and visualizing output data

The Monitor is intentionally split into separate concerns:

* GUI orchestration and pane state live in the Flask app and browser code
* Data-provider backends manage provider-specific runtime state and expensive sessions
* Plugins adapt Monitor context into plotting or analysis workflows
* Scientific analysis logic lives downstream in reusable libraries such as XGC-Analysis

Data Provider Backends
^^^^^^^^^^^^^^^^^^^^^^

The Monitor should depend on explicit backend adapters rather than on
provider-private state.  The current XGC backend exposes two user-facing data
source modes:

* ``directory-scan`` for direct ADIOS/BP browsing
* ``catalog`` for the XGC-Analysis-backed catalog/provider path

The XGC provider owns provider-specific runtime objects such as

* cached catalogs
* persistent Simulation objects
* worker processes used to isolate catalog-backed plot requests
* request tracking and cancellation state

The generic Monitor should consume stable backend payloads and hooks rather than
reaching through those provider internals directly.

Monitor Request Workflow
^^^^^^^^^^^^^^^^^^^^^^^^

For a typical plot request:

1. The browser selects a source, variable, renderer, frame, and pane options.
2. The Flask app routes the request either to ``directory-scan`` code paths or
   to the provider backend.
3. Built-in renderers either read data directly or ask the provider/catalog for
   the selected variable array.
4. Plugin renderers receive a small context dictionary containing source
   metadata, selected data, pane options, and request hooks.
5. The Monitor serializes the resulting Matplotlib figure or image to PNG for
   display in the pane.

In catalog mode, request and lock state are tracked explicitly so the UI can
show active requests, waiting readers, and stale or timed-out work.

Plugins
^^^^^^^

Monitor plugins live under ``utils/input_gui/plugins/monitor/``.  The GUI
expects a small contract:

* ``supports(meta)`` advertises whether the renderer applies to a selected variable
* ``options_schema(meta)`` describes plugin-specific pane controls
* ``render(ctx)`` returns a figure/image payload

Plugins should stay thin.  If a workflow is scientifically meaningful outside
the GUI, the heavy lifting should live in a reusable downstream module and the
plugin should mainly

* interpret GUI options
* map Monitor frame selection into analysis inputs
* forward optional request/progress/cancellation hooks
* format the resulting plot

Catalog And Simulation Workflow
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In XGC catalog mode, the provider is responsible for

* reporting whether XGC-Analysis and its required modules are importable
* creating or closing cached catalogs
* checking whether the products/texts required for ``Simulation`` are present
* creating or closing a persistent ``Simulation`` object
* passing provider-owned context to plugins

The GUI should not re-implement XGC-Analysis availability checks or Simulation
prerequisite logic on its own.

Design Rules
^^^^^^^^^^^^

When extending the Monitor:

* Keep the ``Editor`` backend independent of Monitor/provider changes.
* Preserve the ability to use XGC-Analysis from ordinary scripts and notebooks.
* Prefer optional hooks over GUI-specific control flow in scientific code.
* Keep provider-specific state ownership explicit.
* Treat worker processes and source readers as infrastructure, not as places to
  embed scientific workflow logic.