Operator UI guide
=================

.. versionadded:: 1.6

The HTTP service ships an optional browser UI mounted at ``/ui``. It is
deliberately tiny — a single static page with vanilla ES modules and
Tailwind via CDN, no build step — and is meant for a single operator
driving runs end-to-end without curl. For automation, scripted
workflows, or multi-user deployments, talk to the JSON endpoints
directly.

Open the UI
-----------

.. code-block:: console

   $ docker run --rm -p 8000:8000 -v "$PWD/.runs:/data" \
       ghcr.io/california-planet-search/radvel-api:latest
   $ open http://localhost:8000/ui

If the page renders an empty shell, the service is healthy but
``RADVEL_API_ENABLE_UI`` is ``false`` and the routes return 404 — see
*Disabling the UI* below.

Page tour
---------

Runs list (``#/runs``)
~~~~~~~~~~~~~~~~~~~~~~

The home page lists every run created on the server with its
``run_id``, target ``starname``, planet count, and creation time.
Clicking a row drills into the run detail view. The ``+ New run``
button in the top-right opens the create form.

.. note::

   Screenshots are regenerated by maintainers via
   ``scripts/regen_ui_screenshots.py`` (Playwright-based) and committed
   to ``docs/_static/screenshots/``. See *Refreshing UI screenshots* in
   the project's ``CLAUDE.md``.

Create a run (``#/runs/new``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Three tabs let you build a run in whichever form is most convenient:

- **Form** — guided builder. Fill in starname, instrument names,
  fitting basis, planet count, then per-planet ``per/tc/k`` fields
  (each with a "vary" checkbox), and the standard prior toggles
  (eccentricity, positive-K, dvdt/curv Gaussian, jitter hardbounds).
  Click *Preview JSON* to inspect what will be submitted, or
  *Create run* to ``POST /runs`` directly. The form covers ~80% of
  configurations; drop into the JSON tab for anything more exotic.
- **JSON** — paste a full setup payload (the schema is documented in
  :doc:`api_service`). *Load example* fills in the ``epic203771098``
  two-planet payload. Validation errors from Pydantic surface as a
  structured 422 in a red panel below the textarea.
- **Upload .py** — only shown when ``RADVEL_API_ALLOW_PY_UPLOAD=true``.
  Pick an existing ``radvel`` setup module from disk (the same Python
  file the CLI consumes) and upload it. The server imports the module
  to extract metadata, then the rest of the pipeline runs against the
  ``.py`` directly with no JSON round-trip. Disabled by default
  because the upload executes arbitrary Python on the server.

On success any of the three paths navigate to the new run's detail
page.

Run detail (``#/runs/{id}``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Every CLI step has a button: Fit, MCMC, NS, Derive, IC compare,
Tables, Plots (rv/corner), Report. Buttons are enabled or disabled
based on the run's ``.stat`` state machine — for example, the corner
plot is disabled until MCMC or NS has produced chains. Hovering a
disabled button shows the prerequisite as a tooltip.

MCMC and NS open a small modal so you can set ``nsteps``,
``nwalkers``, ``ensembles``, and the ``serial`` flag before kickoff.
Submitting the modal navigates to the live job view.

Live MCMC progress (``#/runs/{id}/jobs/{job_id}``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Polls ``GET /jobs/{id}`` every two seconds and renders a progress bar
plus the convergence telemetry from
:any:`radvel.mcmc.statevars`. Each field is documented in
:doc:`autocorrintro`:

- ``nsteps_complete`` / ``totsteps`` — production-phase progress.
- ``rate``, ``ar`` — sampling rate (steps/s) and acceptance fraction.
- ``minafactor``, ``maxarchange`` — autocorrelation diagnostics.
- ``mintz``, ``maxgr`` — Gelman-Rubin and ``T_z`` across ensembles.
- ``ismixed``, ``burn_complete`` — boolean phase flags.

The *Cancel* button issues ``DELETE /jobs/{id}``; the job reaches the
``cancelled`` terminal state within a few seconds.

Files (``#/runs/{id}/files``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Lists every file the pipeline wrote (``.stat``, ``_post_obj.pkl``,
chain CSVs, plot PDFs, the report PDF) with size and modified time.
Each row is a download link. The chain CSV only appears once MCMC has
finished; the report PDF only after ``POST /runs/{id}/report``.

Disabling the UI
----------------

Set ``RADVEL_API_ENABLE_UI=false`` to unwire the routes. ``/ui`` and
``/ui/{path}`` return 404. The kill-switch exists so you can deploy
the same image on a shared / headless host without exposing the SPA
to anyone who can reach ``/healthz``. JSON endpoints stay available.

Air-gapped Tailwind
-------------------

The UI loads Tailwind from ``cdn.tailwindcss.com``. To run on a host
without internet egress:

1. Vendor a copy of Tailwind locally::

     curl -fsSL https://cdn.tailwindcss.com -o tailwind.min.js

2. Mount it into the container at
   ``/usr/local/lib/python3.12/site-packages/radvel/api/static/tailwind.min.js``.

3. Edit ``index.html`` (or override via a small bind-mount) to reference
   ``/ui/tailwind.min.js`` instead of the CDN URL.

We deliberately don't bundle Tailwind by default — the CDN script keeps
the image ~50 KB lighter and ensures dynamic utility classes work
without a configured purge step.

Browser support
---------------

Latest Chrome, Firefox, and Safari. There is no transpiler or polyfill
shim; the UI is plain ES modules. IE / very old Edge are not supported.

Keyboard shortcuts
------------------

============  ===============================
``g r``       Go to runs list.
``g n``       Go to "new run".
``?``         Show shortcut help.
============  ===============================