Browser-based UI tools
======================

Overview
--------

RAFT includes several browser-based tools in addition to the core CLI:

- manifest generator
- config generator
- report viewer

These tools are launched from the CLI and served by RAFT's built-in FastAPI
UI server.

Workflow-specific templates
---------------------------

The manifest generator and report viewer can use workflow-owned UI templates
when a workflow configuration repository provides them. RAFT looks for files
such as:

- ``manifest-ui.json``
- ``report-ui.json``
- ``<workflow>.<species>.<input>.manifest-ui.json``
- ``<workflow>.<species>.<input>.report-ui.json``

If these files are present, RAFT uses them to customize labels, manifest
columns, sample types, validation hints, and report-bundle expectations. If no
workflow-specific template is available, RAFT falls back to packaged generic
defaults.

Manifest generator
------------------

When creating a new project, omitting ``--manifest`` causes RAFT to launch
the manifest generator:

.. code-block:: console

  $ raft run \
      --project-id demo-lens \
      --workflow lens \
      --version v1.9-dev

You can also reopen the editor for an existing manifest:

.. code-block:: console

  $ raft run \
      --project-id demo-lens \
      --workflow lens \
      --version v1.9-dev \
      --manifest /path/to/manifest.tsv \
      --edit-manifest

Config generator
----------------

For new projects, RAFT can launch a config generator UI to capture
workflow parameters. Use ``--workflow-profile`` to skip that UI and apply a
pre-defined workflow configuration:

.. code-block:: console

  $ raft run \
      --project-id demo-lens \
      --workflow lens \
      --version v1.9-dev \
      --manifest /path/to/manifest.tsv \
      --workflow-profile standard

Report viewer
-------------

Launch the report viewer for a finished project:

.. code-block:: console

  $ raft generate-reports --project-id demo-lens

RAFT will inspect the project, detect the workflow, locate output and QC
directories, and preload those files when possible.

If no local browser is available, RAFT creates a portable report bundle under
``outputs/reports/``. Copy that ``.tar`` file to a machine with browser
access and upload it through the hosted viewer. The bundle is read locally by
the browser and is not saved on the web server.

Very large QC artifacts, such as LENS IGV HTML reports, are not included in
portable report bundles by default. They remain available in the project
``outputs/qc/`` directory for local review, and the bundle metadata records
which files were skipped.

Demo viewer
-----------

To launch the viewer with synthetic data:

.. code-block:: console

  $ raft generate-reports --demo

Headless environments
---------------------

When a local browser is not available (e.g. on a remote server or SSH
session), RAFT automatically falls back to a headless flow for the manifest
generator, configuration generator, and report viewer:

1. For manifest and config generators, RAFT prints a hosted UI URL and waits
   for an encoded response that you paste back into the terminal.
2. For report generation, RAFT writes a portable ``.tar`` report bundle and
   prints the hosted viewer URL where that bundle can be uploaded.

This allows the full browser-based UI to be used without a display on the
remote host.