Rewrite as FastAPI + Jinja + HTMX, replacing Gradio

The Gradio version had recurring brittleness around dynamic group rows
(four prior attempts to make Add/Remove work, each broken in a
different way) and visibility toggling of the results section. Gradio's
component-lifecycle model is the wrong tool for the level of
interactivity this app needs.

The rewrite owns the rendering model end-to-end:

- FastAPI routes for form submission, status polling, plot JSON, and
downloads; Jinja2 templates with HTMX for dynamic group rows; Plotly
JSON rendered client-side via Plotly.js from CDN.
- Pipeline logic moved into pipeline.py (framework-agnostic). Each
group's plots are built and saved on disk under
groups/{name}/{key}.json; a combined reactivity plot is generated
when the input is single-reference with multiple groups.
- Results page navigates groups via a dropdown that re-fetches plot
JSON; per-reference plots (profile, MI, correlation, pairwise
coverage) update via a sequence dropdown that rebuilds them on
demand from the saved HDF5.
- /run-example POSTs the bundled example dataset without requiring a
file upload.
- /results/{job_id}/download/all bundles the HDF5, CSV, log, and PNG
renders of every plot (via kaleido) into a single ZIP.
- pyproject.toml + uv.lock for local dev. The cmuts extra wires the
sibling cmuts checkout so `uv sync --extra cmuts` keeps the binding
in place; without it, the pipeline returns a clean error and the UI
remains testable.
- Dockerfile updated: drops Gradio, adds FastAPI/Jinja/multipart/
kaleido, and copies templates/, static/, and pipeline.py.

Styling: dark theme with light purple accents on the form/header;
plot tiles stay white so cmuts's default Plotly styling is preserved
unchanged. The only layout override is stripping fixed width/height so
each figure fills its tile.

.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.pyc
+.DS_Store

Dockerfile

@@ -44,14 +44,21 @@ RUN sed -i 's/font.family.*=.*"Helvetica"/font.family"] = "Nimbus Sans"/' \
     fc-cache -f && \
     python3 -c "import matplotlib.font_manager; matplotlib.font_manager._load_fontmanager(try_read_cache=False)"
 
-# Install Gradio
-RUN pip install --no-cache-dir gradio plotly h5py uvicorn
+# Install Python web deps
+RUN pip install --no-cache-dir \
+    "fastapi>=0.110" \
+    "uvicorn[standard]>=0.27" \
+    "jinja2>=3.1" \
+    "python-multipart>=0.0.9" \
+    plotly "kaleido==0.2.1" h5py
 
 # Clean up build artifacts
 RUN rm -rf /cmuts/build
 
-# Copy the app and example data
-COPY app.py /app/app.py
+# Copy the app, templates, static assets, and example data
+COPY app.py pipeline.py /app/
+COPY templates /app/templates
+COPY static /app/static
 COPY examples /app/examples
 WORKDIR /app
 
@@ -61,4 +68,4 @@ RUN useradd -m -u 1000 user
 USER user
 ENV HOME=/home/user PATH="/cmuts/bin:/home/user/.local/bin:$PATH"
 
-CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

README.md

@@ -7,3 +7,60 @@ sdk: docker
 pinned: false
 license: mit
 ---
+
+# cmuts web UI
+
+FastAPI + Jinja + HTMX frontend for the
+[cmuts](https://github.com/hmblair/cmuts) RNA chemical-probing pipeline.
+
+## Local development
+
+### Option A — Docker (full pipeline)
+
+The Dockerfile builds `cmuts` from source along with its system
+dependencies (bowtie2, samtools, libhts). This is the only way to run the
+full pipeline locally on macOS.
+
+```bash
+docker build -t cmuts-space .
+docker run --rm -p 7860:7860 cmuts-space
+# Open http://localhost:7860
+```
+
+### Option B — Python venv (UI only; pipeline returns an error)
+
+For working on the UI without rebuilding the cmuts toolchain:
+
+```bash
+uv sync
+uv run python app.py
+# Open http://localhost:7860
+```
+
+The form, group rows, results page, and error states all work.
+Submitting a job will fail cleanly with a "cmuts is not installed"
+message.
+
+### Option C — venv with cmuts linked from a sibling checkout
+
+If you have the `cmuts` repo built locally at `../cmuts` (sibling to
+this directory), plus `bowtie2` and `samtools` on `PATH`, the pipeline
+runs without Docker:
+
+```bash
+brew install bowtie2 samtools hdf5 htslib autoconf automake libtool libomp
+# Build cmuts in ../cmuts (see github.com/hmblair/cmuts) — `./configure`
+uv sync --extra cmuts
+uv run python app.py
+```
+
+`uv sync` strips packages not declared in pyproject. The `cmuts` extra
+declares the sibling path so re-running sync keeps it installed.
+
+## Layout
+
+- `app.py` — FastAPI routes, request handling
+- `pipeline.py` — subprocess orchestration, HDF5/plot generation
+- `templates/` — Jinja2 HTML
+- `static/` — CSS + JS (Plotly via CDN)
+- `examples/` — bundled FASTA/FASTQ for the "Run with example data" button

app.py

@@ -1,1676 +1,534 @@
-#!/usr/bin/env python3
-"""Gradio app for cmuts: chemical mutation profiling for RNA structure analysis."""
+"""FastAPI app for the cmuts web UI.
+
+The HTTP layer; pipeline logic lives in ``pipeline.py``.
+"""
 
 from __future__ import annotations
 
-import csv
-import glob
+import asyncio
+import io
 import json
 import os
-import re
 import shutil
-import subprocess
-import tempfile
 import time
-import traceback
 import uuid
-from dataclasses import dataclass
-
-import gradio as gr
-import h5py
-import numpy as np
-import plotly.graph_objects as go
-import cmuts
-from cmuts.visualize.plotly import (
-    plot_correlation,
-    plot_coverage,
-    plot_cumulative_reads,
-    plot_examples,
-    plot_heatmap,
-    plot_mi,
-    plot_pairwise_coverage,
-    plot_profile,
-    plot_profiles,
-    plot_read_hist,
-    plot_snr_scaling,
-    plot_termination,
+import zipfile
+from typing import Annotated
+
+from fastapi import BackgroundTasks, FastAPI, Form, HTTPException, Request, UploadFile
+from fastapi.responses import (
+    FileResponse,
+    HTMLResponse,
+    JSONResponse,
+    PlainTextResponse,
+    RedirectResponse,
+    StreamingResponse,
+)
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+
+from pipeline import (
+    AlignConfig,
+    CoreConfig,
+    GroupInput,
+    JobState,
+    MAX_FASTQ_MB,
+    MAX_GROUPS,
+    NormConfig,
+    PLOT_KEYS,
+    RESULTS_DIR,
+    RESULTS_TTL_HOURS,
+    build_perref_plot,
+    build_profile_plot,
+    cleanup_old_results,
+    file_size_mb,
+    job_dir_for,
+    read_meta,
+    run_pipeline,
+    sanitize_group_name,
 )
-from fastapi import FastAPI
-from fastapi.responses import FileResponse, HTMLResponse, RedirectResponse
-
-
-# --- Constants and paths ---
-
-EXAMPLES_DIR = os.environ.get("CMUTS_EXAMPLES_DIR", os.path.join(os.path.dirname(__file__), "examples"))
-MAX_FASTQ_MB = int(os.environ.get("CMUTS_MAX_FASTQ_MB", "500"))
-RESULTS_TTL_HOURS = int(os.environ.get("CMUTS_RESULTS_TTL_HOURS", "48"))
-DEFAULT_GROUP_NAME = "profile"
-PIPELINE_TIMEOUT_SEC = int(os.environ.get("CMUTS_PIPELINE_TIMEOUT_SEC", "600"))
-MAX_GROUPS = 5
-
-_default_results_dir = "/data/results" if os.path.isdir("/data") else "/tmp/cmuts_results"
-RESULTS_DIR = os.environ.get("CMUTS_RESULTS_DIR", _default_results_dir)
-os.makedirs(RESULTS_DIR, exist_ok=True)
-
-_FASTQ_SUFFIXES = (".fastq.gz", ".fq.gz", ".fastq", ".fq")
-
-
-# --- Dataclasses ---
-
-
-@dataclass
-class GroupInput:
-    """One experiment group with modified and optional control FASTQ files."""
-    name: str
-    mod_fastq: str
-    nomod_fastq: str | None = None
-
-
-@dataclass
-class ResultUpdate:
-    """Collected Gradio output updates for the results section."""
-    results_group: object = None
-    error_banner: object = None
-    result_url: object = None
-    output_file: object = None
-    csv_file: object = None
-    profile_plot: object = None
-    seq_dropdown: object = None
-    stats: object = None
-    load_status: str = ""
-    mod_heatmap: object = None
-    termination: object = None
-    coverage: object = None
-    read_hist: object = None
-    cumulative_reads: object = None
-    snr_scaling: object = None
-    mi: object = None
-    correlation: object = None
-    pairwise_coverage: object = None
-    log: str = ""
-    structure_files: object = None
-    structure_commands: object = None
-
-    @classmethod
-    def hidden(cls) -> ResultUpdate:
-        h = gr.update(visible=False, value=None)
-        return cls(
-            results_group=gr.update(),
-            error_banner=gr.update(visible=False, value=""),
-            result_url=h, output_file=h, csv_file=h, profile_plot=h,
-            seq_dropdown=None, stats=h, load_status="",
-            mod_heatmap=h, termination=h, coverage=h,
-            read_hist=h, cumulative_reads=h, snr_scaling=h,
-            mi=h, correlation=h, pairwise_coverage=h,
-            log="",
-            structure_files=h, structure_commands=h,
-        )
 
-    def to_tuple(self) -> tuple:
-        return (
-            self.results_group, self.error_banner,
-            self.result_url, self.output_file, self.csv_file,
-            self.profile_plot, self.seq_dropdown,
-            self.stats, self.load_status,
-            self.mod_heatmap, self.termination, self.coverage,
-            self.read_hist, self.cumulative_reads, self.snr_scaling,
-            self.mi, self.correlation, self.pairwise_coverage,
-            self.log,
-            self.structure_files, self.structure_commands,
-        )
 
+# --- App setup ---
 
-@dataclass
-class AlignConfig:
-    trim_5: str = ""
-    trim_3: str = ""
-    local_align: bool = False
-
-
-@dataclass
-class CoreConfig:
-    min_mapq: int = 10
-    min_phred: int = 10
-    min_length: int = 2
-    max_length: int = 1024
-    no_insertions: bool = True
-    no_mismatches: bool = False
-    strand: str = "both"
-    compute_pairwise: bool = False
-
-
-@dataclass
-class NormConfig:
-    norm_method: str = "ubr"
-    no_insertions: bool = True
-    no_deletions: bool = False
-    clip_low: bool = False
-    clip_high: bool = False
-    blank_5p: int = 0
-    blank_3p: int = 0
-    blank_cutoff: int = 10
-    norm_cutoff: int = 500
-    norm_percentile: int = 90
-    sig: float = 0.05
-
-
-# --- FASTA parsing ---
-
-
-def _parse_fasta(fasta_path: str) -> list[tuple[str, str]]:
-    """Parse FASTA file, returning list of (name, sequence) tuples."""
-    entries: list[tuple[str, str]] = []
-    name = ""
-    seq_parts: list[str] = []
-    with open(fasta_path) as f:
-        for line in f:
-            line = line.strip()
-            if line.startswith(">"):
-                if seq_parts:
-                    entries.append((name, "".join(seq_parts)))
-                    seq_parts = []
-                name = line[1:].split()[0]
-            elif line:
-                seq_parts.append(line)
-    if seq_parts:
-        entries.append((name, "".join(seq_parts)))
-    return entries
-
-
-# --- Input validation ---
-
-
-def _sanitize_group_name(raw: str | None) -> str:
-    """Normalize a user-supplied group name to a safe HDF5 path component."""
-    name = re.sub(r"[^\w\-]", "_", (raw or "").strip())
-    return name or DEFAULT_GROUP_NAME
-
-
-def _fastq_stem(path: str) -> str:
-    """Return the sample name from a FASTQ path by stripping known extensions."""
-    name = os.path.basename(path)
-    for suffix in _FASTQ_SUFFIXES:
-        if name.endswith(suffix):
-            return name[: -len(suffix)]
-    return os.path.splitext(name)[0]
-
-
-def _file_size_mb(path: str) -> float:
-    return os.path.getsize(path) / (1024 * 1024)
-
-
-# --- CLI command builders ---
-
-
-def _build_align_cmd(
-    fasta_path: str,
-    output_dir: str,
-    fastq_files: list[str],
-    cfg: AlignConfig,
-) -> list[str]:
-    cmd = ["cmuts", "align", "--fasta", fasta_path, "--output", output_dir]
-    if cfg.trim_5.strip():
-        cmd.extend(["--trim-5", cfg.trim_5.strip()])
-    if cfg.trim_3.strip():
-        cmd.extend(["--trim-3", cfg.trim_3.strip()])
-    if cfg.local_align:
-        cmd.append("--local")
-    cmd.extend(fastq_files)
-    return cmd
-
-
-def _build_core_cmd(
-    fasta_path: str,
-    output_h5: str,
-    bam_files: list[str],
-    cfg: CoreConfig,
-) -> list[str]:
-    cmd = [
-        "cmuts", "core",
-        "-f", fasta_path,
-        "-o", output_h5,
-        "--min-mapq", str(cfg.min_mapq),
-        "--min-phred", str(cfg.min_phred),
-        "--min-length", str(cfg.min_length),
-        "--max-length", str(cfg.max_length),
-    ]
-    if cfg.no_insertions:
-        cmd.append("--no-insertions")
-    if cfg.no_mismatches:
-        cmd.append("--no-mismatches")
-    if cfg.strand == "forward":
-        cmd.append("--no-reverse")
-    elif cfg.strand == "reverse":
-        cmd.append("--only-reverse")
-    if cfg.compute_pairwise:
-        cmd.append("--pairwise")
-    cmd.extend(bam_files)
-    return cmd
-
-
-# --- Intermediate checks ---
-
-
-def _check_bam_files(alignments_dir: str) -> list[str]:
-    """Return sorted absolute BAM paths, or raise if none found."""
-    bam_files = sorted(glob.glob(os.path.join(alignments_dir, "*.bam")))
-    if not bam_files:
-        raise RuntimeError(
-            f"Alignment produced no BAM files in {alignments_dir}. "
-            "Check the log for bowtie2 errors — the reference FASTA may not "
-            "match the reads, or the FASTQ may be empty."
-        )
-    return bam_files
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+TEMPLATES_DIR = os.path.join(BASE_DIR, "templates")
+STATIC_DIR = os.path.join(BASE_DIR, "static")
 
+app = FastAPI(title="cmuts")
+app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
+templates = Jinja2Templates(directory=TEMPLATES_DIR)
 
-def _check_output_h5(path: str, step: str) -> None:
-    """Raise if an expected HDF5 output file is missing."""
-    if not os.path.isfile(path):
-        raise RuntimeError(
-            f"{step} did not produce output file: {os.path.basename(path)}. "
-            "Check the log for errors."
-        )
 
+# In-memory state for jobs currently running in this process. Once a job
+# completes, its results live on disk under RESULTS_DIR; this dict is
+# pruned. A job that's missing from this dict but present on disk is
+# treated as complete (status read from meta.json).
+JOB_STATES: dict[str, JobState] = {}
+_STATES_LOCK = asyncio.Lock()
 
-# --- CSV generation ---
-
-
-def _generate_csv(
-    h5_path: str,
-    fasta_path: str,
-    group_names: list[str],
-) -> str:
-    """Generate a CSV from HDF5 profiles with columns for each group."""
-    fasta_entries = _parse_fasta(fasta_path)
-    csv_path = h5_path.rsplit(".", 1)[0] + ".csv"
-
-    with h5py.File(h5_path, "r") as f, open(csv_path, "w", newline="") as csvfile:
-        writer = csv.writer(csvfile)
-
-        first_grp = f[group_names[0]]
-        n_refs = first_grp["reactivity"].shape[0]
-        seq_len = first_grp["reactivity"].shape[1]
-        multi_ref = n_refs > 1
-
-        header: list[str] = []
-        if multi_ref:
-            header.append("Reference")
-        header.extend(["Position", "Nucleotide"])
-        for gn in group_names:
-            header.extend([gn, f"{gn}_error"])
-        writer.writerow(header)
-
-        for ref_idx in range(n_refs):
-            ref_name = fasta_entries[ref_idx][0] if ref_idx < len(fasta_entries) else f"ref_{ref_idx + 1}"
-            ref_seq = fasta_entries[ref_idx][1] if ref_idx < len(fasta_entries) else ""
-
-            group_data = {}
-            for gn in group_names:
-                group_data[gn] = {
-                    "reactivity": np.array(f[gn]["reactivity"])[ref_idx],
-                    "error": np.array(f[gn]["error"])[ref_idx],
-                }
-
-            for pos in range(seq_len):
-                row: list[str] = []
-                if multi_ref:
-                    row.append(ref_name)
-                row.append(str(pos + 1))
-                row.append(ref_seq[pos] if pos < len(ref_seq) else "")
-                for gn in group_names:
-                    r = group_data[gn]["reactivity"][pos]
-                    e = group_data[gn]["error"][pos]
-                    row.append(f"{r:.6f}" if np.isfinite(r) else "")
-                    row.append(f"{e:.6f}" if np.isfinite(e) else "")
-                writer.writerow(row)
-
-    return csv_path
-
-
-# --- Structure visualization ---
-
-
-def _build_defattrs(
-    cif_path: str,
-    sequence: str,
-    results: list,
-    out_dir: str,
-    chimerax_bin: str = "ChimeraX",
-) -> tuple[list[str], str]:
-    """Generate one defattr per group and the ChimeraX commands to render them.
-
-    Returns (defattr_paths, markdown). ``markdown`` is human-readable text
-    suitable for a gr.Markdown component, with one fenced code block per
-    group containing the command to run locally.
-    """
-    cif_basename = os.path.basename(cif_path)
-    # cmuts aligns sequences in DNA alphabet (it replaces U with T internally
-    # when reading the CIF). Match that here so alignment scores are sensible.
-    aln_seq = sequence.upper().replace("U", "T")
-
-    defattr_paths: list[str] = []
-    blocks: list[str] = [
-        "### Visualize the structure with ChimeraX",
-        "",
-        f"Download each `.defattr` file below, place it next to your "
-        f"`{cif_basename}` (a copy of your uploaded structure), and run the "
-        f"matching command in ChimeraX's command line.",
-        "",
-    ]
-
-    for r in results:
-        name = r.group.name
-        reactivity = np.asarray(r.combined.reactivity)
-        if reactivity.shape[0] != 1:
-            # Not single-reference — skip; defattrs require a 1:1 sequence map.
-            continue
-        defattr_path = os.path.join(out_dir, f"{name}.defattr")
-        try:
-            max_value = cmuts.visualize.make_defattr(
-                reactivity[0], aln_seq, cif_path, defattr_path,
-            )
-        except Exception as e:
-            blocks.append(f"**{name}:** could not generate defattr — {e}")
-            blocks.append("")
-            continue
 
-        cmd = cmuts.visualize.chimerax_command(
-            cif_basename,
-            os.path.basename(defattr_path),
-            color="indianred",
-            max_value=max_value,
-        )
-        blocks.append(f"**{name}:**")
-        blocks.append("```")
-        blocks.append(f"{chimerax_bin} --cmd '{cmd}'")
-        blocks.append("```")
-        blocks.append("")
-        defattr_paths.append(defattr_path)
-
-    if len(defattr_paths) == 0:
-        return [], ""
-    return defattr_paths, "\n".join(blocks)
-
-
-# --- HDF5 reading and plotting ---
-
-
-def _build_plots(
-    mod: cmuts.ProbingData,
-    nomod: cmuts.ProbingData | None,
-    combined: cmuts.ProbingData,
-    name: str,
-    sequence: str | None = None,
-) -> dict[str, go.Figure | None]:
-    """Build all diagnostic plots from in-memory ProbingData objects."""
-    plots: dict[str, go.Figure | None] = {}
-
-    plots["profile"] = plot_examples(
-        np.asarray(combined.reactivity), np.asarray(combined.error), name,
-        sequence=sequence,
-    )
-    plots["mod_heatmap"] = plot_heatmap(np.asarray(combined.heatmap), name)
-    plots["termination"] = plot_termination(np.asarray(combined.terminations), name)
-    plots["coverage"] = plot_coverage(
-        np.asarray(combined.coverage), np.asarray(combined.reads), name,
-    )
-
-    is_multi = not combined.single()
-    reads = np.asarray(combined.reads)
-    plots["read_hist"] = plot_read_hist(reads, name) if is_multi else None
-    plots["cumulative_reads"] = plot_cumulative_reads(reads, name) if is_multi else None
+@app.on_event("startup")
+def _startup() -> None:
+    cleanup_old_results()
 
-    plots["snr_scaling"] = plot_snr_scaling(mod, nomod, combined, name)
 
-    if combined.mi is not None:
-        plots["mi"] = plot_mi(np.asarray(combined.mi)[0], name)
-    else:
-        plots["mi"] = None
+# --- Helpers ---
 
-    if combined.covariance is not None:
-        plots["correlation"] = plot_correlation(np.asarray(combined.covariance)[0], name)
-    else:
-        plots["correlation"] = None
 
-    if combined.probability is not None:
-        prob = np.asarray(combined.probability)
-        plots["pairwise_coverage"] = plot_pairwise_coverage(prob[0, :, :, 1, 1], name)
-    else:
-        plots["pairwise_coverage"] = None
-
-    return plots
-
-
-def _build_seq_names(n: int, sequences: list[str] | None) -> list[str]:
-    """Build display labels for the sequence dropdown, disambiguating
-    duplicates that result from the 50-char truncation."""
-    raw: list[str] = []
-    for i in range(n):
-        seq = sequences[i] if sequences and i < len(sequences) else None
-        if seq and len(seq) > 50:
-            raw.append(seq[:50] + "...")
-        elif seq:
-            raw.append(seq)
-        else:
-            raw.append(f"Sequence {i + 1}")
-    counts: dict[str, int] = {}
-    out: list[str] = []
-    for label in raw:
-        if raw.count(label) > 1:
-            counts[label] = counts.get(label, 0) + 1
-            out.append(f"{label} (#{counts[label]})")
-        else:
-            out.append(label)
+def _save_upload(upload: UploadFile, dest_dir: str, filename: str) -> str:
+    """Save an uploaded file under ``dest_dir`` with the given filename and
+    return its absolute path."""
+    os.makedirs(dest_dir, exist_ok=True)
+    out = os.path.join(dest_dir, filename)
+    with open(out, "wb") as f:
+        shutil.copyfileobj(upload.file, f)
     return out
 
 
-def _read_profiles(h5_path: str, group_name: str) -> tuple[np.ndarray, list[str]]:
-    """Read reactivity profiles and sequence names from an HDF5 file."""
-    with h5py.File(h5_path, "r") as f:
-        grp = f[group_name] if group_name in f else f
-        reactivity = np.array(grp["reactivity"])
-        sequences = None
-        if "sequence" in f:
-            sequences = [
-                s.decode() if isinstance(s, bytes) else s for s in f["sequence"]
-            ]
-    return reactivity, _build_seq_names(reactivity.shape[0], sequences)
-
-
-def _build_stats_table(h5_path: str, group_names: list[str]) -> list[list[str]]:
-    """Build a stats table for one or more groups."""
-    rows: list[list[str]] = []
-    multi = len(group_names) > 1
-    with h5py.File(h5_path, "r") as f:
-        for gn in group_names:
-            grp = f[gn] if gn in f else f
-            reactivity = np.array(grp["reactivity"])
-            reads = np.array(grp["reads"])
-            error = np.array(grp["error"])
-            snr = np.array(grp["SNR"])
-
-            n_refs = reactivity.shape[0]
-            seq_len = reactivity.shape[1]
-            total_reads = int(reads.sum())
-            valid = np.isfinite(reactivity)
-
-            if multi:
-                rows.append([f"--- {gn} ---", ""])
-
-            rows.extend([
-                ["References", f"{n_refs:,}"],
-                ["Reference length", f"{seq_len:,}"],
-                ["Total reads", f"{total_reads:,}"],
-                ["Mean reads per reference", f"{np.mean(reads):,.1f}"],
-                ["Median reads per reference", f"{int(np.median(reads)):,}"],
-            ])
-
-            if valid.any():
-                rows.extend([
-                    ["Mean reactivity", f"{np.mean(reactivity[valid]):.3f}"],
-                    ["Mean error", f"{np.mean(error[valid]):.3f}"],
-                    ["Mean SNR", f"{np.mean(snr):.2f}"],
-                    ["SNR > 1", f"{np.mean(snr > 1):.1%}"],
-                ])
-
-            dropout = float(np.mean(reads == 0))
-            if dropout > 0:
-                rows.append(["Dropout fraction", f"{dropout:.1%}"])
-
-    return rows
-
-
-# --- Results persistence ---
-
-
-def cleanup_old_results() -> None:
-    """Delete result directories older than RESULTS_TTL_HOURS."""
-    cutoff = time.time() - RESULTS_TTL_HOURS * 3600
-    if not os.path.isdir(RESULTS_DIR):
-        return
-    for entry in os.scandir(RESULTS_DIR):
-        if entry.is_dir():
-            meta_path = os.path.join(entry.path, "meta.json")
-            try:
-                if os.path.exists(meta_path):
-                    with open(meta_path) as f:
-                        created = json.load(f).get("created_at", 0)
-                else:
-                    created = entry.stat().st_mtime
-                if created < cutoff:
-                    shutil.rmtree(entry.path, ignore_errors=True)
-            except Exception:
-                pass
-
-
-_PLOT_KEYS = [
-    "profile", "mod_heatmap", "termination", "coverage",
-    "read_hist", "cumulative_reads", "snr_scaling", "mi", "correlation",
-    "pairwise_coverage",
-]
-
-
-def save_results(
-    h5_path: str,
-    csv_path: str | None,
-    group_names: list[str],
-    plots: dict[str, go.Figure | None],
-    stats_rows: list[list[str]],
-    names: list[str],
-    job_id: str | None = None,
-    defattr_paths: list[str] | None = None,
-    chimerax_md: str = "",
-) -> str:
-    """Save pipeline results to persistent storage. Returns the job ID."""
-    if job_id is None:
-        job_id = uuid.uuid4().hex[:12]
-    job_dir = os.path.join(RESULTS_DIR, job_id)
-    os.makedirs(job_dir, exist_ok=True)
-
-    shutil.copy(h5_path, os.path.join(job_dir, "profiles.h5"))
-    if csv_path and os.path.isfile(csv_path):
-        shutil.copy(csv_path, os.path.join(job_dir, "profiles.csv"))
-
-    saved_defattrs: list[str] = []
-    if defattr_paths:
-        defattr_dir = os.path.join(job_dir, "defattr")
-        os.makedirs(defattr_dir, exist_ok=True)
-        for p in defattr_paths:
-            dest = os.path.join(defattr_dir, os.path.basename(p))
-            shutil.copy(p, dest)
-            saved_defattrs.append(dest)
-
-    meta = {
-        "group_names": group_names,
-        "created_at": time.time(),
-        "names": names,
-        "stats_rows": stats_rows,
-        "defattr_files": [os.path.basename(p) for p in saved_defattrs],
-        "chimerax_md": chimerax_md,
-    }
-    with open(os.path.join(job_dir, "meta.json"), "w") as f:
-        json.dump(meta, f)
-
-    for key in _PLOT_KEYS:
-        fig = plots.get(key)
-        if fig is not None:
-            with open(os.path.join(job_dir, f"{key}.json"), "w") as f:
-                f.write(fig.to_json())
-
-    return job_id
-
-
-# --- Pipeline orchestration ---
-
-
-def _plot_update(fig: go.Figure | None):
-    """Wrap a figure in a gr.update that shows/hides the component."""
-    if fig is None:
-        return gr.update(visible=False, value=None)
-    return gr.update(visible=True, value=fig)
-
-
-def _error_yield(msg: str, log_lines: list[str] | None = None) -> tuple:
-    """Build a yield tuple that displays an error banner and the log."""
-    r = ResultUpdate.hidden()
-    r.results_group = gr.update(visible=True)
-    r.error_banner = gr.update(visible=True, value=f"**Error:** {msg}")
-    r.log = "\n".join(log_lines) if log_lines else f"Error: {msg}"
-    return r.to_tuple()
-
-
-def _progress_yield(log_lines: list[str]) -> tuple:
-    """Build the in-progress yield tuple. Result URL stays hidden until success."""
-    r = ResultUpdate.hidden()
-    r.results_group = gr.update(visible=True)
-    r.log = "\n".join(log_lines)
-    return r.to_tuple()
-
-
-def run_pipeline(
-    fasta_file: str,
-    groups: list[GroupInput],
-    align_cfg: AlignConfig,
-    core_cfg: CoreConfig,
-    norm_cfg: NormConfig,
-    cif_file: str | None = None,
-):
-    """Run the full cmuts pipeline for one or more experiment groups.
-
-    All groups share a single alignment and mutation-counting pass.
-    Normalization is computed from pooled data across all groups so that
-    reactivity values are directly comparable.
-    """
-    if fasta_file is None:
-        yield _error_yield("Please upload a FASTA file.")
-        return
-    if not groups:
-        yield _error_yield("Please add at least one group with a modified FASTQ file.")
-        return
-
-    for g in groups:
-        for path, label in [(g.mod_fastq, f"{g.name} Modified FASTQ"),
-                            (g.nomod_fastq, f"{g.name} Control FASTQ")]:
-            if path is not None and _file_size_mb(path) > MAX_FASTQ_MB:
-                yield _error_yield(
-                    f"{label} is {_file_size_mb(path):.0f} MB. "
-                    f"The free tier has limited RAM (16 GB); files over "
-                    f"{MAX_FASTQ_MB} MB may cause out-of-memory errors. "
-                    f"Consider downsampling first."
-                )
-                return
-
-    cleanup_old_results()
+def _is_real_upload(upload: UploadFile | None) -> bool:
+    if upload is None:
+        return False
+    name = (upload.filename or "").strip()
+    return bool(name)
 
-    workdir = tempfile.mkdtemp(prefix="cmuts_")
-    outdir = os.path.join(workdir, "outputs")
-    os.makedirs(outdir)
-
-    job_id = uuid.uuid4().hex[:12]
-    space_host = os.environ.get("SPACE_HOST", "")
-    base = f"https://{space_host}" if space_host else ""
-    result_url = f"{base}/results/{job_id}"
 
+def _job_status(job_id: str) -> tuple[str, list[str], str | None]:
+    """Return (status, log_lines, error) for a job. Reads from in-memory
+    state if the job is running here; otherwise from disk."""
+    state = JOB_STATES.get(job_id)
+    if state is not None:
+        return state.status, list(state.log_lines), state.error
+    meta = read_meta(job_dir_for(job_id))
+    if meta is None:
+        return "missing", [], None
+    log_path = os.path.join(job_dir_for(job_id), "log.txt")
     log_lines: list[str] = []
-
-    def log(msg: str) -> None:
-        log_lines.append(msg)
-
-    def run(cmd: list[str], cwd: str = outdir) -> bool:
-        log(f"$ {' '.join(cmd)}")
-        result = subprocess.run(
-            cmd,
-            cwd=cwd,
-            capture_output=True,
-            text=True,
-            timeout=PIPELINE_TIMEOUT_SEC,
-        )
-        if result.stdout:
-            log(result.stdout.rstrip())
-        if result.stderr:
-            log(result.stderr.rstrip())
-        if result.returncode != 0:
-            log(f"Command failed with exit code {result.returncode}")
-            return False
-        return True
-
-    try:
-        fasta_path = os.path.join(workdir, "ref.fasta")
-        shutil.copy(fasta_file, fasta_path)
-
-        # Copy all FASTQs, prefixed by group name to avoid collisions
-        fastq_dir = os.path.join(workdir, "fastq")
-        os.makedirs(fastq_dir)
-
-        group_fastq_info: list[tuple[str, str, str | None]] = []
-        for g in groups:
-            prefix = g.name + "__"
-            mod_basename = prefix + os.path.basename(g.mod_fastq)
-            mod_stem = _fastq_stem(mod_basename)
-            shutil.copy(g.mod_fastq, os.path.join(fastq_dir, mod_basename))
-
-            nomod_stem = None
-            if g.nomod_fastq is not None:
-                nomod_basename = prefix + os.path.basename(g.nomod_fastq)
-                nomod_stem = _fastq_stem(nomod_basename)
-                shutil.copy(g.nomod_fastq, os.path.join(fastq_dir, nomod_basename))
-
-            group_fastq_info.append((g.name, mod_stem, nomod_stem))
-
-        # Step 1: Align all FASTQs together
-        log("=== Step 1: Aligning reads ===")
-        yield _progress_yield(log_lines)
-
-        fastq_files = sorted(glob.glob(os.path.join(fastq_dir, "*")))
-        alignments_dir = os.path.join(outdir, "alignments")
-        align_cmd = _build_align_cmd(fasta_path, alignments_dir, fastq_files, align_cfg)
-        if not run(align_cmd, cwd=outdir):
-            yield _error_yield("Alignment failed. See log for details.", log_lines)
-            return
-        yield _progress_yield(log_lines)
-
-        # Step 2: Count mutations for all BAMs
-        log("\n=== Step 2: Counting mutations ===")
-        yield _progress_yield(log_lines)
-
-        bam_abs = _check_bam_files(alignments_dir)
-        bam_files = sorted(os.path.relpath(p, outdir) for p in bam_abs)
-        counts_h5 = "counts.h5"
-        core_cmd = _build_core_cmd(fasta_path, counts_h5, bam_files, core_cfg)
-        if not run(core_cmd, cwd=outdir):
-            yield _error_yield("Mutation counting failed. See log for details.", log_lines)
-            return
-        _check_output_h5(os.path.join(outdir, counts_h5), "cmuts core")
-        yield _progress_yield(log_lines)
-
-        # Step 3: Normalize reactivities with shared normalization factor
-        log("\n=== Step 3: Normalizing reactivities ===")
-        yield _progress_yield(log_lines)
-
-        counts_path = os.path.join(outdir, counts_h5)
-
-        cmuts_groups = [
-            cmuts.Group(
-                name=name,
-                mod=[f"alignments/{mod_stem}"],
-                nomod=[f"alignments/{nomod_stem}"] if nomod_stem else None,
-            )
-            for name, mod_stem, nomod_stem in group_fastq_info
-        ]
-
-        norm_opts = cmuts.Opts(
-            cmuts.DataGroups([]),
-            cmuts.DataGroups(None),
-            norm_cfg.blank_cutoff,
-            not norm_cfg.no_insertions,
-            not norm_cfg.no_deletions,
-            norm_cfg.norm_method,
-            (norm_cfg.blank_5p, norm_cfg.blank_3p),
-            (norm_cfg.clip_low, norm_cfg.clip_high),
-            norm_cfg.sig,
-        )
-
-        with h5py.File(counts_path, "r") as f:
-            results = cmuts.compute_reactivities(
-                f, fasta_path, cmuts_groups, norm_opts, shared_norm=True,
-            )
-
-        if len(results) > 1:
-            log(f"  Pooled {norm_cfg.norm_method} normalization across {len(results)} groups.")
-        log("Normalization complete.")
-
-        # Save multi-group HDF5
-        final_path = os.path.join(outdir, "profiles.h5")
-        cmuts.save_groups(final_path, [(r.group.name, r.combined) for r in results])
-
-        # Generate CSV
-        all_group_names = [r.group.name for r in results]
-        csv_path = _generate_csv(final_path, fasta_path, all_group_names)
-        log("Generated CSV output.")
-
-        # Build plots
-        first = results[0]
-        first_name = first.group.name
-
-        # Show the nucleotide sequence on the profile x-axis when there's
-        # exactly one reference (multi-ref runs use a heatmap instead).
-        fasta_entries = _parse_fasta(fasta_path)
-        ref_sequence = (
-            fasta_entries[0][1]
-            if first.combined.single() and len(fasta_entries) == 1
-            else None
-        )
-
-        # Profile: overlay all groups for single-reference data
-        if len(results) > 1 and first.combined.single():
-            reactivities = [np.asarray(r.combined.reactivity)[0] for r in results]
-            profile_fig = plot_profiles(reactivities, all_group_names, sequence=ref_sequence)
-        else:
-            profile_fig = plot_examples(
-                np.asarray(first.combined.reactivity),
-                np.asarray(first.combined.error),
-                first_name,
-                sequence=ref_sequence,
-            )
-
-        # Diagnostic plots from first group
-        diag_plots = _build_plots(
-            first.mod, first.nomod, first.combined, first_name, sequence=ref_sequence,
-        )
-        diag_plots["profile"] = profile_fig
-
-        # Sequence names for dropdown (shared across groups)
-        reactivity, names = _read_profiles(final_path, first_name)
-        dropdown_update = gr.Dropdown(
-            choices=names, value=names[0],
-            visible=(len(names) > 1),
-        )
-
-        # Stats for all groups
-        stats_rows = _build_stats_table(final_path, all_group_names)
-
-        # Optional structure visualization: per-group defattrs + ChimeraX commands
-        defattr_paths: list[str] = []
-        chimerax_md = ""
-        if cif_file is not None and ref_sequence is not None:
-            cif_workdir_path = os.path.join(workdir, os.path.basename(cif_file))
-            shutil.copy(cif_file, cif_workdir_path)
-            defattr_dir = os.path.join(outdir, "defattr")
-            os.makedirs(defattr_dir, exist_ok=True)
-            defattr_paths, chimerax_md = _build_defattrs(
-                cif_workdir_path, ref_sequence, results, defattr_dir,
-            )
-            if defattr_paths:
-                log(f"Wrote {len(defattr_paths)} defattr file(s) for ChimeraX.")
-        elif cif_file is not None:
-            log(
-                "Skipping structure visualization: defattr generation requires "
-                "a single-reference FASTA."
-            )
-
-        save_results(
-            final_path, csv_path, all_group_names,
-            diag_plots, stats_rows, names, job_id=job_id,
-            defattr_paths=defattr_paths, chimerax_md=chimerax_md,
-        )
-
-        log(f"\nDone. Generated profiles for {len(results)} group(s).")
-        log(f"Results available at: {result_url} (expires in {RESULTS_TTL_HOURS}h)")
-        yield ResultUpdate(
-            results_group=gr.update(visible=True),
-            error_banner=gr.update(visible=False, value=""),
-            result_url=gr.update(visible=True, value=result_url),
-            output_file=gr.update(visible=True, value=final_path),
-            csv_file=gr.update(visible=True, value=csv_path),
-            profile_plot=_plot_update(diag_plots["profile"]),
-            seq_dropdown=dropdown_update,
-            stats=gr.update(visible=True, value=stats_rows),
-            mod_heatmap=_plot_update(diag_plots["mod_heatmap"]),
-            termination=_plot_update(diag_plots["termination"]),
-            coverage=_plot_update(diag_plots["coverage"]),
-            read_hist=_plot_update(diag_plots["read_hist"]),
-            cumulative_reads=_plot_update(diag_plots["cumulative_reads"]),
-            snr_scaling=_plot_update(diag_plots["snr_scaling"]),
-            mi=_plot_update(diag_plots["mi"]),
-            correlation=_plot_update(diag_plots["correlation"]),
-            pairwise_coverage=_plot_update(diag_plots["pairwise_coverage"]),
-            log="\n".join(log_lines),
-            structure_files=(
-                gr.update(visible=True, value=defattr_paths)
-                if defattr_paths else gr.update(visible=False, value=None)
-            ),
-            structure_commands=(
-                gr.update(visible=True, value=chimerax_md)
-                if chimerax_md else gr.update(visible=False, value="")
-            ),
-        ).to_tuple()
-
-    except subprocess.TimeoutExpired:
-        log(f"Pipeline timed out ({PIPELINE_TIMEOUT_SEC // 60} minute limit).")
-        yield _error_yield(
-            f"Pipeline timed out after {PIPELINE_TIMEOUT_SEC // 60} minutes.",
-            log_lines,
-        )
-        return
-    except Exception as e:
-        log(f"Error: {e}")
-        log(traceback.format_exc())
-        yield _error_yield(str(e) or "Unexpected error. See log for details.", log_lines)
-        return
-
-
-# --- Gradio callbacks ---
-
-
-def _run_pipeline_gradio(fasta_file, cif_file, visible_count, *args):
-    """Gradio-facing wrapper. Receives MAX_GROUPS * 3 group values (one
-    (name, mod, nomod) triple per row) followed by the option components.
-    Only the first ``visible_count`` rows are considered."""
-    group_args = args[: MAX_GROUPS * 3]
-    cfg = args[MAX_GROUPS * 3 :]
-
-    (norm_method, no_insertions, no_deletions, clip_low, clip_high,
-     trim_5, trim_3, local_align,
-     min_mapq, min_phred, min_length, max_length, no_mismatches, strand,
-     blank_5p, blank_3p, blank_cutoff, norm_cutoff, norm_percentile,
-     compute_pairwise, sig) = cfg
-
-    groups: list[GroupInput] = []
-    for i in range(int(visible_count or 0)):
-        name_val = group_args[3 * i]
-        mod_val = group_args[3 * i + 1]
-        nomod_val = group_args[3 * i + 2]
-        if mod_val is None:
-            continue
-        gn = _sanitize_group_name(name_val) or f"group_{i + 1}"
-        groups.append(GroupInput(gn, mod_val, nomod_val))
-
-    yield from run_pipeline(
-        fasta_file=fasta_file,
-        groups=groups,
-        align_cfg=AlignConfig(
-            trim_5=trim_5 or "",
-            trim_3=trim_3 or "",
-            local_align=local_align,
-        ),
-        core_cfg=CoreConfig(
-            min_mapq=int(min_mapq or 10),
-            min_phred=int(min_phred or 10),
-            min_length=int(min_length or 2),
-            max_length=int(max_length or 1024),
-            no_insertions=no_insertions,
-            no_mismatches=no_mismatches,
-            strand=strand or "both",
-            compute_pairwise=compute_pairwise,
-        ),
-        norm_cfg=NormConfig(
-            norm_method=norm_method or "ubr",
-            no_insertions=no_insertions,
-            no_deletions=no_deletions,
-            clip_low=clip_low,
-            clip_high=clip_high,
-            blank_5p=int(blank_5p or 0),
-            blank_3p=int(blank_3p or 0),
-            blank_cutoff=int(blank_cutoff or 10),
-            norm_cutoff=int(norm_cutoff or 500),
-            norm_percentile=int(norm_percentile or 90),
-            sig=float(sig or 0.05),
-        ),
-        cif_file=cif_file,
+    if os.path.isfile(log_path):
+        with open(log_path) as f:
+            log_lines = f.read().splitlines()
+    if meta.get("status") == "error":
+        return "error", log_lines, meta.get("error")
+    return "done", log_lines, None
+
+
+# --- Routes: form + dynamic rows ---
+
+
+@app.get("/", response_class=HTMLResponse)
+def index(request: Request) -> HTMLResponse:
+    return templates.TemplateResponse(
+        request,
+        "index.html",
+        {
+            "max_groups": MAX_GROUPS,
+            "ttl_hours": RESULTS_TTL_HOURS,
+            "max_fastq_mb": MAX_FASTQ_MB,
+        },
     )
 
 
-def select_profile(seq_name: str, output_file: str) -> tuple:
-    """Switch the displayed profile and pairwise plots for the selected sequence."""
-    if not output_file or not seq_name:
-        no_change = gr.update()
-        return no_change, no_change, no_change, no_change
-
-    with h5py.File(output_file, "r") as f:
-        group_names = sorted(k for k in f.keys() if k != "sequence")
-        if not group_names:
-            no_change = gr.update()
-            return no_change, no_change, no_change, no_change
-
-        first_grp = f[group_names[0]]
-        reactivity = np.array(first_grp["reactivity"])
-
-        # The dropdown is hidden for single-reference runs; an auto-fired
-        # change here would clobber the initial plot (which already has the
-        # FASTA-derived sequence axis), so leave the existing plot alone.
-        if reactivity.shape[0] == 1:
-            no_change = gr.update()
-            return no_change, no_change, no_change, no_change
-
-        sequences = None
-        if "sequence" in f:
-            sequences = [
-                s.decode() if isinstance(s, bytes) else s for s in f["sequence"]
-            ]
-
-        names = _build_seq_names(reactivity.shape[0], sequences)
-
-        try:
-            idx = names.index(seq_name)
-        except ValueError:
-            idx = 0
-
-        ref_sequence = sequences[idx] if sequences and idx < len(sequences) else None
-
-        if len(group_names) > 1:
-            reactivities = [np.array(f[gn]["reactivity"])[idx] for gn in group_names]
-            profile_fig = plot_profiles(reactivities, group_names, sequence=ref_sequence)
-        else:
-            error = np.array(first_grp["error"])
-            profile_fig = plot_profile(reactivity[idx], error[idx], names[idx], sequence=ref_sequence)
-
-        mi_fig = None
-        corr_fig = None
-        if "mutual-information" in first_grp:
-            mi_fig = plot_mi(np.array(first_grp["mutual-information"])[idx], names[idx])
-        if "covariance" in first_grp:
-            corr_fig = plot_correlation(np.array(first_grp["covariance"])[idx], names[idx])
+@app.get("/group-row", response_class=HTMLResponse)
+def group_row(request: Request) -> HTMLResponse:
+    """HTMX partial: returns one new empty group row."""
+    return templates.TemplateResponse(
+        request, "_group_row.html", {"initial": None},
+    )
 
-    # Leave the pairwise plot alone — switching sequences shouldn't hide a
-    # plot that may already be visible from the initial run.
-    return profile_fig, _plot_update(mi_fig), _plot_update(corr_fig), gr.update()
 
+EXAMPLES_DIR = os.environ.get(
+    "CMUTS_EXAMPLES_DIR", os.path.join(BASE_DIR, "examples"),
+)
 
-def load_example():
-    """Load bundled example files into row 0; clear and hide rows 1..MAX_GROUPS-1.
 
-    Returns a tuple consumed by the example button's outputs list, see
-    ``_example_outputs`` in the UI section.
-    """
+@app.post("/run-example")
+def run_example(background_tasks: BackgroundTasks):
+    """Submit the bundled example dataset as a job, skipping the upload form."""
     fasta = None
     treated = None
     untreated = None
-
-    entries = sorted(os.listdir(EXAMPLES_DIR))
-    fastq_paths: list[str] = []
-    for f in entries:
+    for f in sorted(os.listdir(EXAMPLES_DIR)):
         path = os.path.join(EXAMPLES_DIR, f)
         lower = f.lower()
         if lower.endswith((".fasta", ".fa")):
             fasta = path
-        elif lower.endswith(_FASTQ_SUFFIXES):
-            fastq_paths.append(path)
-
-    # First pass: pick control by name keywords.
-    remaining: list[str] = []
-    for p in fastq_paths:
-        lower = os.path.basename(p).lower()
-        if untreated is None and (
-            "untreated" in lower or "nomod" in lower or "control" in lower
-        ):
-            untreated = p
-        else:
-            remaining.append(p)
-    # Second pass: whatever is left is treated.
-    if remaining:
-        treated = remaining[0]
-
-    group_file = os.path.join(EXAMPLES_DIR, "group.txt")
-    if os.path.isfile(group_file):
-        with open(group_file) as f:
-            group_name = f.read().strip() or "example"
-    else:
-        group_name = "example"
-
-    # Row 0 gets the example values; rows 1..MAX_GROUPS-1 are cleared and hidden.
-    row_values: list = [group_name, treated, untreated]
-    for _ in range(MAX_GROUPS - 1):
-        row_values.extend(["", None, None])
-    row_visibilities = [gr.update(visible=(i == 0)) for i in range(MAX_GROUPS)]
-    add_btn_update = gr.update(interactive=True)
-    remove_btn_update = gr.update(interactive=False)
-
-    return (
-        fasta,
-        *row_values,
-        1,  # visible_count
-        *row_visibilities,
-        add_btn_update,
-        remove_btn_update,
-    )
+        elif "untreated" in lower or "nomod" in lower or "control" in lower:
+            untreated = path
+        elif lower.endswith((".fastq", ".fq", ".fastq.gz", ".fq.gz")):
+            treated = path
+    if fasta is None or treated is None:
+        raise HTTPException(500, "Example dataset is missing required files.")
 
-
-def load_saved_result(job_id: str):
-    """Load a previously saved result by job ID."""
-    job_id = (job_id or "").strip()
-    if not job_id:
-        return ResultUpdate.hidden().to_tuple()
-
-    job_dir = os.path.join(RESULTS_DIR, job_id)
-    meta_path = os.path.join(job_dir, "meta.json")
-
-    if not os.path.isdir(job_dir):
-        r = ResultUpdate.hidden()
-        r.load_status = (
-            f"Result not found. It may have expired "
-            f"(results are kept for {RESULTS_TTL_HOURS} hours)."
-        )
-        return r.to_tuple()
-
-    with open(meta_path) as f:
-        meta = json.load(f)
-
-    loaded: dict[str, go.Figure | None] = {}
-    for key in _PLOT_KEYS:
-        path = os.path.join(job_dir, f"{key}.json")
-        if os.path.isfile(path):
-            with open(path) as f:
-                loaded[key] = go.Figure(json.load(f))
-        else:
-            loaded[key] = None
-
-    # Handle both old (group_name) and new (group_names) meta formats
-    group_names = meta.get("group_names")
-    if group_names is None:
-        group_names = [meta.get("group_name", DEFAULT_GROUP_NAME)]
-    names = meta.get("names", [])
-
-    space_host = os.environ.get("SPACE_HOST", "")
-    base = f"https://{space_host}" if space_host else ""
-
-    h5_path = os.path.join(job_dir, "profiles.h5")
-    csv_path = os.path.join(job_dir, "profiles.csv")
-    hidden = gr.update(visible=False, value=None)
-
-    defattr_files = meta.get("defattr_files", [])
-    defattr_paths = [
-        os.path.join(job_dir, "defattr", name)
-        for name in defattr_files
-        if os.path.isfile(os.path.join(job_dir, "defattr", name))
-    ]
-    chimerax_md = meta.get("chimerax_md", "")
-
-    return ResultUpdate(
-        results_group=gr.update(visible=True),
-        error_banner=gr.update(visible=False, value=""),
-        result_url=gr.update(visible=True, value=f"{base}/results/{job_id}"),
-        output_file=gr.update(visible=True, value=h5_path) if os.path.isfile(h5_path) else hidden,
-        csv_file=gr.update(visible=True, value=csv_path) if os.path.isfile(csv_path) else hidden,
-        profile_plot=_plot_update(loaded.get("profile")),
-        seq_dropdown=gr.Dropdown(choices=names, value=names[0] if names else None, visible=len(names) > 1),
-        stats=gr.update(visible=True, value=meta.get("stats_rows", [])),
-        mod_heatmap=_plot_update(loaded.get("mod_heatmap")),
-        termination=_plot_update(loaded.get("termination")),
-        coverage=_plot_update(loaded.get("coverage")),
-        read_hist=_plot_update(loaded.get("read_hist")),
-        cumulative_reads=_plot_update(loaded.get("cumulative_reads")),
-        snr_scaling=_plot_update(loaded.get("snr_scaling")),
-        mi=_plot_update(loaded.get("mi")),
-        correlation=_plot_update(loaded.get("correlation")),
-        pairwise_coverage=_plot_update(loaded.get("pairwise_coverage")),
-        structure_files=(
-            gr.update(visible=True, value=defattr_paths) if defattr_paths else hidden
-        ),
-        structure_commands=(
-            gr.update(visible=True, value=chimerax_md) if chimerax_md else hidden
-        ),
-    ).to_tuple()
-
-
-# --- Gradio UI ---
-
-with gr.Blocks(title="cmuts — RNA Chemical Probing Analysis") as demo:
-    gr.Markdown(
-        """
-        # cmuts — RNA Chemical Probing Analysis
-
-        Upload a FASTA reference and FASTQ file(s) from a MaP-seq experiment
-        to compute normalized reactivity profiles.  Use **+ Add group** to
-        compare multiple conditions (e.g. with/without ligand) — normalization
-        is applied across all groups so values are directly comparable.
-
-        **Pipeline:** `cmuts align` &rarr; `cmuts core` &rarr; `cmuts normalize`
-        &ensp;|&ensp;
-        [GitHub](https://github.com/hmblair/cmuts)
-        &ensp;|&ensp;
-        [Documentation](https://hmblair.github.io/cmuts)
-        &ensp;|&ensp;
-        Free and open-source under the
-        [MIT License](https://github.com/hmblair/cmuts/blob/main/LICENSE)
-        """
-    )
-
-    with gr.Tab("Run"):
-        with gr.Column() as input_section:
-            gr.Markdown("### Input data")
-            fasta_input = gr.File(label="Reference FASTA", file_types=[".fasta", ".fa"])
-            cif_input = gr.File(
-                label=(
-                    "Reference structure CIF (optional) — produces a "
-                    ".defattr per group plus a ChimeraX command for local "
-                    "visualization. Single-reference FASTAs only."
-                ),
-                file_types=[".cif"],
+    job_id = uuid.uuid4().hex[:12]
+    job_dir = job_dir_for(job_id)
+    uploads_dir = os.path.join(job_dir, "uploads")
+    os.makedirs(uploads_dir, exist_ok=True)
+    fasta_path = os.path.join(uploads_dir, "ref.fasta")
+    shutil.copy(fasta, fasta_path)
+    mod_path = os.path.join(uploads_dir, "example__" + os.path.basename(treated))
+    shutil.copy(treated, mod_path)
+    nomod_path: str | None = None
+    if untreated is not None:
+        nomod_path = os.path.join(uploads_dir, "example__" + os.path.basename(untreated))
+        shutil.copy(untreated, nomod_path)
+
+    state = JobState(job_id=job_id)
+    state.log(f"Submitted example job {job_id}.")
+    JOB_STATES[job_id] = state
+
+    groups = [GroupInput(name="example", mod_fastq=mod_path, nomod_fastq=nomod_path)]
+
+    def _runner() -> None:
+        try:
+            run_pipeline(
+                job_id=job_id, job_dir=job_dir,
+                fasta_path=fasta_path, groups=groups,
+                align_cfg=AlignConfig(),
+                core_cfg=CoreConfig(),
+                norm_cfg=NormConfig(),
+                cif_path=None, state=state,
             )
+        finally:
+            asyncio.get_event_loop().call_later(60, JOB_STATES.pop, job_id, None)
+
+    background_tasks.add_task(asyncio.to_thread, _runner)
+    return RedirectResponse(f"/results/{job_id}", status_code=303)
+
+
+# --- Routes: submit + status ---
+
+
+@app.post("/run")
+async def run(
+    request: Request,
+    background_tasks: BackgroundTasks,
+    fasta: UploadFile,
+    cif: UploadFile | None = None,
+    group_name: list[str] = Form(default=[]),
+    mod_fastq: list[UploadFile] = Form(default=[]),
+    nomod_fastq: list[UploadFile] = Form(default=[]),
+    # Alignment
+    trim_5: str = Form(default=""),
+    trim_3: str = Form(default=""),
+    local_align: bool = Form(default=False),
+    # Core
+    min_mapq: int = Form(default=10),
+    min_phred: int = Form(default=10),
+    min_length: int = Form(default=2),
+    max_length: int = Form(default=1024),
+    no_mismatches: bool = Form(default=False),
+    strand: str = Form(default="both"),
+    compute_pairwise: bool = Form(default=False),
+    sig: float = Form(default=0.05),
+    # Norm
+    norm_method: str = Form(default="ubr"),
+    no_insertions: bool = Form(default=True),
+    no_deletions: bool = Form(default=False),
+    clip_low: bool = Form(default=False),
+    clip_high: bool = Form(default=False),
+    blank_5p: int = Form(default=0),
+    blank_3p: int = Form(default=0),
+    blank_cutoff: int = Form(default=10),
+    norm_cutoff: int = Form(default=500),
+    norm_percentile: int = Form(default=90),
+):
+    if not _is_real_upload(fasta):
+        raise HTTPException(400, "A reference FASTA is required.")
 
-            # Pre-create MAX_GROUPS static rows. Each row is toggled by
-            # visibility on a shared ``visible_count`` state. Components are
-            # never recreated, so values persist across Add/Remove and are
-            # editable after Load Example without re-render quirks.
-            group_rows: list = []
-            group_names: list = []
-            group_mods: list = []
-            group_nomods: list = []
-            group_removes: list = []
-            for i in range(MAX_GROUPS):
-                with gr.Row(visible=(i == 0)) as _row:
-                    gn = gr.Textbox(
-                        label=f"Group {i + 1} name",
-                        placeholder="e.g. 2A3_with_cdiGMP",
-                        scale=2,
-                    )
-                    mod = gr.File(
-                        label=f"Group {i + 1} Modified FASTQ (required)",
-                        file_types=[".fastq", ".fq", ".gz"],
-                        scale=3,
-                    )
-                    nomod = gr.File(
-                        label=f"Group {i + 1} Control FASTQ (optional)",
-                        file_types=[".fastq", ".fq", ".gz"],
-                        scale=3,
-                    )
-                    rm = gr.Button("Remove", size="sm", scale=1)
-                group_rows.append(_row)
-                group_names.append(gn)
-                group_mods.append(mod)
-                group_nomods.append(nomod)
-                group_removes.append(rm)
-
-            visible_count = gr.State(1)
-
-            with gr.Row():
-                add_group_btn = gr.Button("+ Add group", variant="secondary", size="sm")
-                remove_group_btn = gr.Button(
-                    "- Remove last group", variant="secondary", size="sm",
-                    interactive=False,
-                )
-                example_btn = gr.Button("Load example data", variant="secondary", size="sm")
-
-            gr.Markdown("### Options")
-            with gr.Accordion("Alignment", open=False):
-                gr.Markdown(
-                    "*If no adapter sequences are provided, cmuts will attempt to "
-                    "recognize adapters outside the reference sequence and auto-trim.*"
-                )
-                with gr.Row():
-                    trim_5 = gr.Textbox(label="5' adapter to trim (optional)", placeholder="auto-detected if blank")
-                    trim_3 = gr.Textbox(label="3' adapter to trim (optional)", placeholder="auto-detected if blank")
-                    local_align = gr.Checkbox(label="Local alignment", value=False)
-
-            with gr.Accordion("Read filtering", open=False):
-                with gr.Row():
-                    min_mapq = gr.Slider(minimum=0, maximum=60, step=1, value=10, label="Min mapping quality")
-                    min_phred = gr.Slider(minimum=0, maximum=40, step=1, value=10, label="Min PHRED score")
-                with gr.Row():
-                    min_length = gr.Number(value=2, label="Min read length", precision=0)
-                    max_length = gr.Number(value=1024, label="Max read length", precision=0)
-                with gr.Row():
-                    no_mismatches = gr.Checkbox(label="Exclude mismatches", value=False)
-                    strand = gr.Radio(choices=["both", "forward", "reverse"], value="both", label="Strand")
-
-            with gr.Accordion("Normalization", open=False):
-                norm_method = gr.Radio(
-                    choices=["ubr", "outlier", "raw"],
-                    value="ubr",
-                    label="Normalization method",
-                )
-                with gr.Row():
-                    no_insertions = gr.Checkbox(label="Exclude insertions", value=True)
-                    no_deletions = gr.Checkbox(label="Exclude deletions", value=False)
-                with gr.Row():
-                    clip_low = gr.Checkbox(label="Clip negative reactivities", value=False)
-                    clip_high = gr.Checkbox(label="Clip reactivities above 1", value=False)
-                with gr.Row():
-                    blank_5p = gr.Number(value=0, label="Blank 5' bases", precision=0)
-                    blank_3p = gr.Number(value=0, label="Blank 3' bases", precision=0)
-                    blank_cutoff = gr.Number(value=10, label="Min reads for position", precision=0)
-                with gr.Row():
-                    norm_cutoff = gr.Number(value=500, label="Min reads for normalization", precision=0)
-                    norm_percentile = gr.Slider(minimum=50, maximum=100, step=1, value=90, label="Normalization percentile")
-
-            with gr.Accordion("Pairwise analysis", open=False):
-                gr.Markdown(
-                    "Compute pairwise modification correlations (mutual information "
-                    "and Pearson correlation). Cost is O(L&sup2;) in sequence length, "
-                    "so this is slow for long references."
-                )
-                compute_pairwise = gr.Checkbox(label="Compute pairwise correlations", value=False)
-                sig = gr.Slider(
-                    minimum=0.001, maximum=0.1, step=0.001, value=0.05,
-                    label="Significance threshold (Bonferroni-corrected)",
-                )
-
-            run_btn = gr.Button("Run Pipeline", variant="primary")
+    # Validate group inputs and stage files to the job dir.
+    job_id = uuid.uuid4().hex[:12]
+    job_dir = job_dir_for(job_id)
+    os.makedirs(job_dir, exist_ok=True)
+    uploads_dir = os.path.join(job_dir, "uploads")
+    os.makedirs(uploads_dir, exist_ok=True)
+
+    fasta_path = _save_upload(fasta, uploads_dir, "ref.fasta")
+    cif_path: str | None = None
+    if _is_real_upload(cif):
+        cif_path = _save_upload(cif, uploads_dir, cif.filename or "ref.cif")
+
+    # Pair the form list values. Browsers always send equal-length lists,
+    # but be defensive.
+    n_rows = max(len(group_name), len(mod_fastq), len(nomod_fastq))
+    while len(group_name) < n_rows:
+        group_name.append("")
+    while len(mod_fastq) < n_rows:
+        mod_fastq.append(UploadFile(filename="", file=io.BytesIO()))  # type: ignore[call-arg]
+    while len(nomod_fastq) < n_rows:
+        nomod_fastq.append(UploadFile(filename="", file=io.BytesIO()))  # type: ignore[call-arg]
 
-        with gr.Group(visible=False) as results_group:
-            gr.Markdown("### Results")
-            error_banner = gr.Markdown(value="", visible=False)
-            result_url = gr.Textbox(
-                label=f"Result link (bookmark this — expires in {RESULTS_TTL_HOURS}h)",
-                interactive=False,
-                visible=False,
-            )
-            with gr.Accordion("Log", open=False):
-                output_log = gr.Textbox(label="Log", lines=15, max_lines=30, show_label=False)
-            output_file = gr.File(label="Output HDF5", visible=False)
-            csv_file = gr.File(label="Output CSV", visible=False)
-            seq_dropdown = gr.Dropdown(label="Sequence", visible=False, interactive=True)
-            output_plot = gr.Plot(label="Reactivity Profile", visible=False)
-            mod_heatmap_plot = gr.Plot(label="Modification Heatmap", visible=False)
-            with gr.Row():
-                termination_plot = gr.Plot(label="Termination by Position", visible=False)
-                coverage_plot = gr.Plot(label="Coverage by Position", visible=False)
-            with gr.Row():
-                read_hist_plot = gr.Plot(label="Read Depth Distribution", visible=False)
-                cumulative_reads_plot = gr.Plot(label="Cumulative Reads", visible=False)
-            snr_scaling_plot = gr.Plot(label="SNR vs Read Depth", visible=False)
-            with gr.Row():
-                mi_plot = gr.Plot(label="Mutual Information", visible=False)
-                correlation_plot = gr.Plot(label="Correlation", visible=False)
-            pairwise_coverage_plot = gr.Plot(label="Pairwise Coverage", visible=False)
-            output_stats = gr.Dataframe(
-                label="Summary Statistics",
-                headers=["Statistic", "Value"],
-                interactive=False,
-                visible=False,
+    groups: list[GroupInput] = []
+    seen_names: set[str] = set()
+    for i in range(n_rows):
+        mod = mod_fastq[i]
+        if not _is_real_upload(mod):
+            continue
+        gn = sanitize_group_name(group_name[i]) or f"group_{i + 1}"
+        # Disambiguate clashing names.
+        base = gn
+        k = 2
+        while gn in seen_names:
+            gn = f"{base}_{k}"
+            k += 1
+        seen_names.add(gn)
+
+        mod_path = _save_upload(mod, uploads_dir, f"{gn}__{mod.filename}")
+        if file_size_mb(mod_path) > MAX_FASTQ_MB:
+            raise HTTPException(
+                400,
+                f"Modified FASTQ for group '{gn}' is "
+                f"{file_size_mb(mod_path):.0f} MB; the limit is "
+                f"{MAX_FASTQ_MB} MB.",
             )
-            structure_files = gr.Files(label="ChimeraX defattr files", visible=False)
-            structure_commands = gr.Markdown(visible=False)
-
-        with gr.Accordion("Load previous results", open=False):
-            with gr.Row():
-                prev_job_id = gr.Textbox(label="Job ID", placeholder="e.g. a3f2b1c4d5e6", scale=3)
-                load_btn = gr.Button("Load", variant="secondary", scale=1)
-            load_status = gr.Textbox(label="Status", interactive=False)
-
-        # Flat list of all per-row value components, ordered row by row.
-        group_value_components: list = []
-        for i in range(MAX_GROUPS):
-            group_value_components.extend([group_names[i], group_mods[i], group_nomods[i]])
-
-        # Standard outputs tuple for the group state buttons (Add / Remove
-        # last / per-row Remove). Order: visible_count, all values, all rows,
-        # add button, remove button.
-        _groups_state_outputs = (
-            [visible_count] + group_value_components
-            + group_rows + [add_group_btn, remove_group_btn]
-        )
-
-        def _groups_state(vc: int, values) -> tuple:
-            flat = list(values)
-            rows_vis = [gr.update(visible=(k < vc)) for k in range(MAX_GROUPS)]
-            add_int = gr.update(interactive=(vc < MAX_GROUPS))
-            rem_int = gr.update(interactive=(vc > 1))
-            return (vc, *flat, *rows_vis, add_int, rem_int)
-
-        def _add_group_handler(vc, *vals):
-            new_vc = min(int(vc or 1) + 1, MAX_GROUPS)
-            return _groups_state(new_vc, vals)
-
-        def _remove_last_handler(vc, *vals):
-            cur = int(vc or 1)
-            new_vc = max(cur - 1, 1)
-            if new_vc == cur:
-                return _groups_state(cur, vals)
-            triples = [list(vals[3 * k : 3 * k + 3]) for k in range(MAX_GROUPS)]
-            triples[new_vc] = ["", None, None]
-            flat = [v for t in triples for v in t]
-            return _groups_state(new_vc, flat)
-
-        def _make_remove_at(idx: int):
-            def fn(vc, *vals):
-                cur = int(vc or 1)
-                triples = [list(vals[3 * k : 3 * k + 3]) for k in range(MAX_GROUPS)]
-                if idx >= cur:
-                    return _groups_state(cur, vals)
-                if cur <= 1:
-                    triples[0] = ["", None, None]
-                    flat = [v for t in triples for v in t]
-                    return _groups_state(1, flat)
-                for k in range(idx, cur - 1):
-                    triples[k] = triples[k + 1]
-                triples[cur - 1] = ["", None, None]
-                flat = [v for t in triples for v in t]
-                return _groups_state(cur - 1, flat)
-            return fn
-
-        add_group_btn.click(
-            _add_group_handler,
-            inputs=[visible_count] + group_value_components,
-            outputs=_groups_state_outputs,
-        )
-        remove_group_btn.click(
-            _remove_last_handler,
-            inputs=[visible_count] + group_value_components,
-            outputs=_groups_state_outputs,
-        )
-        for i in range(MAX_GROUPS):
-            group_removes[i].click(
-                _make_remove_at(i),
-                inputs=[visible_count] + group_value_components,
-                outputs=_groups_state_outputs,
+        nomod_path: str | None = None
+        if _is_real_upload(nomod_fastq[i]):
+            nomod_path = _save_upload(
+                nomod_fastq[i], uploads_dir,
+                f"{gn}__{nomod_fastq[i].filename}",
             )
+            if file_size_mb(nomod_path) > MAX_FASTQ_MB:
+                raise HTTPException(
+                    400,
+                    f"Control FASTQ for group '{gn}' is "
+                    f"{file_size_mb(nomod_path):.0f} MB; the limit is "
+                    f"{MAX_FASTQ_MB} MB.",
+                )
+        groups.append(GroupInput(name=gn, mod_fastq=mod_path, nomod_fastq=nomod_path))
 
-        _example_outputs = (
-            [fasta_input] + group_value_components
-            + [visible_count] + group_rows
-            + [add_group_btn, remove_group_btn]
-        )
-        example_btn.click(
-            fn=load_example,
-            inputs=None,
-            outputs=_example_outputs,
-        )
-
-        # Outputs list matching ResultUpdate.to_tuple() field order.
-        _result_outputs = [
-            results_group, error_banner,
-            result_url, output_file, csv_file,
-            output_plot, seq_dropdown,
-            output_stats, load_status,
-            mod_heatmap_plot, termination_plot, coverage_plot,
-            read_hist_plot, cumulative_reads_plot, snr_scaling_plot,
-            mi_plot, correlation_plot, pairwise_coverage_plot,
-            output_log,
-            structure_files, structure_commands,
-        ]
-
-        run_inputs: list = [fasta_input, cif_input, visible_count]
-        run_inputs.extend(group_value_components)
-        run_inputs.extend([
-            norm_method, no_insertions, no_deletions, clip_low, clip_high,
-            trim_5, trim_3, local_align,
-            min_mapq, min_phred, min_length, max_length, no_mismatches, strand,
-            blank_5p, blank_3p, blank_cutoff, norm_cutoff, norm_percentile,
-            compute_pairwise, sig,
-        ])
-        run_btn.click(
-            fn=_run_pipeline_gradio,
-            inputs=run_inputs,
-            outputs=_result_outputs,
-        )
+    if not groups:
+        raise HTTPException(400, "At least one group with a Modified FASTQ is required.")
+
+    align_cfg = AlignConfig(trim_5=trim_5, trim_3=trim_3, local_align=local_align)
+    core_cfg = CoreConfig(
+        min_mapq=min_mapq, min_phred=min_phred,
+        min_length=min_length, max_length=max_length,
+        no_insertions=no_insertions, no_mismatches=no_mismatches,
+        strand=strand, compute_pairwise=compute_pairwise,
+    )
+    norm_cfg = NormConfig(
+        norm_method=norm_method,
+        no_insertions=no_insertions, no_deletions=no_deletions,
+        clip_low=clip_low, clip_high=clip_high,
+        blank_5p=blank_5p, blank_3p=blank_3p,
+        blank_cutoff=blank_cutoff, norm_cutoff=norm_cutoff,
+        norm_percentile=norm_percentile, sig=sig,
+    )
 
-        seq_dropdown.change(
-            fn=select_profile,
-            inputs=[seq_dropdown, output_file],
-            outputs=[output_plot, mi_plot, correlation_plot, pairwise_coverage_plot],
-        )
+    state = JobState(job_id=job_id)
+    state.log(f"Submitted job {job_id} with {len(groups)} group(s).")
+    JOB_STATES[job_id] = state
 
-        load_btn.click(
-            fn=load_saved_result,
-            inputs=[prev_job_id],
-            outputs=_result_outputs,
+    def _runner() -> None:
+        try:
+            run_pipeline(
+                job_id=job_id,
+                job_dir=job_dir,
+                fasta_path=fasta_path,
+                groups=groups,
+                align_cfg=align_cfg,
+                core_cfg=core_cfg,
+                norm_cfg=norm_cfg,
+                cif_path=cif_path,
+                state=state,
+            )
+        finally:
+            # Keep the state briefly so the UI can read the final transition,
+            # then drop it. The on-disk meta + log are authoritative after.
+            import threading
+            threading.Timer(60.0, JOB_STATES.pop, args=(job_id, None)).start()
+
+    background_tasks.add_task(asyncio.to_thread, _runner)
+    return RedirectResponse(f"/results/{job_id}", status_code=303)
+
+
+@app.get("/results/{job_id}/status", response_class=JSONResponse)
+def status(job_id: str) -> JSONResponse:
+    status_, log_lines, error = _job_status(job_id)
+    return JSONResponse({
+        "status": status_,
+        "log": "\n".join(log_lines),
+        "error": error,
+    })
+
+
+# --- Routes: results page + plot data ---
+
+
+@app.get("/results/{job_id}", response_class=HTMLResponse)
+def results(request: Request, job_id: str) -> HTMLResponse:
+    status_, log_lines, error = _job_status(job_id)
+    if status_ == "missing":
+        return templates.TemplateResponse(
+            request,
+            "results.html",
+            {
+                "job_id": job_id,
+                "status": "missing",
+                "ttl_hours": RESULTS_TTL_HOURS,
+                "log": "",
+                "error": None,
+                "meta": None,
+                "first_group": None,
+            },
+            status_code=404,
         )
-
-    _load_outputs = [input_section] + _result_outputs
-
-    def _load_from_query(request: gr.Request):
-        """Auto-load results when ?job_id= is present in the URL."""
-        job_id = (request.query_params.get("job_id") or "").strip()
-        if not job_id:
-            return [gr.update()] * len(_load_outputs)
-        result = load_saved_result(job_id)
-        return (gr.update(visible=False),) + result
-
-    demo.load(
-        fn=_load_from_query,
-        outputs=_load_outputs,
+    meta = read_meta(job_dir_for(job_id))
+    first_group = None
+    if meta and meta.get("group_names"):
+        first_group = meta["group_names"][0]
+    return templates.TemplateResponse(
+        request,
+        "results.html",
+        {
+            "job_id": job_id,
+            "status": status_,
+            "ttl_hours": RESULTS_TTL_HOURS,
+            "log": "\n".join(log_lines),
+            "error": error,
+            "meta": meta,
+            "first_group": first_group,
+            "plot_keys": PLOT_KEYS,
+        },
     )
 
-    with gr.Tab("About"):
-        gr.Markdown(
-            """
-            ## Why cmuts?
-
-            Existing tools for analyzing MaP-seq data — such as ShapeMapper2 and
-            RNAframework — were designed for single-RNA experiments and do not
-            scale to modern high-throughput libraries with thousands or millions
-            of reference sequences.
-
-            **cmuts** is a ground-up rewrite in C/C++ that addresses these
-            limitations:
-
-            - **100-200x faster** than ShapeMapper2 and RNAframework. A dataset
-              of 100 billion aligned reads across 24 million references was
-              processed in under 24 hours on 32 cores — a task that would take
-              RNAframework approximately 3 months.
-            - **Constant memory footprint** regardless of library size, thanks to
-              streamed single-pass I/O. Competing tools either grow linearly in
-              memory or require processing one reference at a time.
-            - **More accurate deletion handling.** cmuts uses a depth-first
-              search algorithm to enumerate all possible positions of ambiguous
-              deletions and weights them probabilistically using observed mutation
-              rates. Prior tools arbitrarily assign deletions to the 3'-most
-              position, which can misplace reactivity signals — particularly in
-              homopolymer regions and structurally important motifs like
-              kink-turns.
-            - **HDF5 output** for compact storage, fast random access, and direct
-              compatibility with Python and machine-learning pipelines.
-            """
-        )
 
-    with gr.Tab("Help"):
-        gr.Markdown(
-            f"""
-            ## Quick Start
-
-            1. Click **Load example data** on the Run tab to populate the inputs
-               with a bundled dataset.
-            2. Leave the default settings and click **Run Pipeline**.
-            3. The pipeline runs three steps — alignment, mutation counting, and
-               normalization — and streams its progress to the log.
-            4. When finished, download the output HDF5 or CSV file and explore
-               the interactive reactivity profile. If multiple reference
-               sequences are present, use the dropdown to switch between them.
-
-            ## Inputs
-
-            | Field | Description |
-            |-------|-------------|
-            | **Reference FASTA** | One or more RNA sequences in FASTA format. Each sequence is treated as a separate reference for alignment. |
-            | **Modified FASTQ** | Reads from the chemically treated condition (e.g., DMS, 2A3, SHAPE). Compressed `.fastq.gz` is accepted. |
-            | **Control FASTQ** | *(Optional)* Reads from the untreated/DMSO condition. Providing a control enables background subtraction during normalization. |
-            | **Group name** | A label for the experiment group, used in the output files. |
-
-            ### Multiple groups
-
-            Use **+ Add group** to compare multiple experimental conditions
-            (e.g. with/without a ligand). Each group has its own modified and
-            control FASTQ files. All groups share the same reference FASTA.
-
-            Normalization is applied **across all groups** so that reactivity
-            values are directly comparable. The profile plot overlays all
-            groups for easy visual comparison.
+def _read_plot_json(path: str) -> str | None:
+    if not os.path.isfile(path):
+        return None
+    with open(path) as f:
+        return f.read()
+
+
+@app.get("/results/{job_id}/plot/combined", response_class=PlainTextResponse)
+def plot_combined(job_id: str) -> PlainTextResponse:
+    path = os.path.join(job_dir_for(job_id), "combined_profile.json")
+    body = _read_plot_json(path)
+    if body is None:
+        raise HTTPException(404, "Combined plot not available.")
+    return PlainTextResponse(body, media_type="application/json")
+
+
+@app.get("/results/{job_id}/plot/{group}/{key}", response_class=PlainTextResponse)
+def plot_group_key(
+    job_id: str, group: str, key: str, seq: int = 0,
+) -> PlainTextResponse:
+    if key not in PLOT_KEYS:
+        raise HTTPException(404, "Unknown plot key.")
+    job_dir = job_dir_for(job_id)
+    # For seq=0 use the pre-computed JSON. For seq>0 on per-ref plots,
+    # build on demand from the HDF5.
+    if seq == 0:
+        path = os.path.join(job_dir, "groups", group, f"{key}.json")
+        body = _read_plot_json(path)
+        if body is not None:
+            return PlainTextResponse(body, media_type="application/json")
+        # Falls through to on-demand below for missing plots.
+    if key == "profile":
+        body = build_profile_plot(job_dir, group, seq)
+    elif key in {"mi", "correlation", "pairwise_coverage"}:
+        body = build_perref_plot(job_dir, group, key, seq)
+    else:
+        body = None
+    if body is None:
+        raise HTTPException(404, "Plot not available for this group/sequence.")
+    return PlainTextResponse(body, media_type="application/json")
 
-            ## Adapter trimming
 
-            If no adapter sequences are provided in the Alignment settings,
-            cmuts will attempt to recognize adapter sequences outside the
-            reference and auto-trim them.
+# --- Routes: downloads ---
 
-            ## Settings
 
-            | Setting | Description |
-            |---------|-------------|
-            | **Normalization method** | `ubr` (default): divides by the 90th percentile of reactivities at positions with >100 reads, giving a robust upper-bound reference. `outlier`: from the top 10% of reactivities, discards the top 2% as outliers and divides by the mean of the remaining 8%. `raw`: no normalization — returns raw mutation rates. |
-            | **Exclude insertions** | Do not count inserted bases as mutations (recommended for most protocols). |
-            | **Exclude deletions** | Do not count deleted bases as mutations. |
-            | **Clip negative reactivities** | Set negative normalized reactivities to zero. |
-            | **Clip reactivities above 1** | Cap normalized reactivities at 1.0. |
+@app.get("/results/{job_id}/download/h5")
+def download_h5(job_id: str) -> FileResponse:
+    path = os.path.join(job_dir_for(job_id), "profiles.h5")
+    if not os.path.isfile(path):
+        raise HTTPException(404, "HDF5 not available.")
+    meta = read_meta(job_dir_for(job_id)) or {}
+    group_names = meta.get("group_names") or [job_id]
+    filename = "-".join(group_names) + "-profiles.h5"
+    return FileResponse(path, media_type="application/x-hdf5", filename=filename)
 
-            ## Interpreting the Output
 
-            ### Reactivity profile
+@app.get("/results/{job_id}/download/csv")
+def download_csv(job_id: str) -> FileResponse:
+    path = os.path.join(job_dir_for(job_id), "profiles.csv")
+    if not os.path.isfile(path):
+        raise HTTPException(404, "CSV not available.")
+    meta = read_meta(job_dir_for(job_id)) or {}
+    group_names = meta.get("group_names") or [job_id]
+    filename = "-".join(group_names) + "-profiles.csv"
+    return FileResponse(path, media_type="text/csv", filename=filename)
 
-            The interactive chart shows per-nucleotide reactivity values.
-            Hover over any position to see the exact position, nucleotide
-            identity, and reactivity value. Peaks correspond to unpaired or
-            flexible nucleotides; low/near-zero regions correspond to
-            base-paired or otherwise protected positions.
 
-            When multiple groups are present, the profile overlays all groups
-            for direct comparison.
+@app.get("/results/{job_id}/download/defattr/{name}")
+def download_defattr(job_id: str, name: str) -> FileResponse:
+    safe = os.path.basename(name)  # prevent traversal
+    path = os.path.join(job_dir_for(job_id), "defattr", safe)
+    if not os.path.isfile(path):
+        raise HTTPException(404, "Defattr not available.")
+    return FileResponse(path, media_type="text/plain", filename=safe)
 
-            ### Output files
 
-            **HDF5** (`profiles.h5`) contains normalized per-nucleotide
-            reactivity profiles organized by group. Open it in Python with:
+def _plot_json_to_png(json_path: str) -> bytes | None:
+    """Render a saved Plotly JSON to PNG bytes. Returns None on failure."""
+    try:
+        import plotly.graph_objects as go
+        with open(json_path) as f:
+            fig = go.Figure(json.load(f))
+        return fig.to_image(format="png", width=1000, height=600, scale=2)
+    except Exception:
+        return None
 
-            ```python
-            import h5py
 
-            with h5py.File("profiles.h5") as f:
-                for group in f:
-                    if group == "sequence":
+@app.get("/results/{job_id}/download/all")
+def download_all(job_id: str) -> StreamingResponse:
+    job_dir = job_dir_for(job_id)
+    if not os.path.isdir(job_dir):
+        raise HTTPException(404, "Job not found.")
+
+    def _gen():
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+            for root, _dirs, files in os.walk(job_dir):
+                rel = os.path.relpath(root, job_dir)
+                # Skip raw uploads to keep the bundle small.
+                if rel.startswith("uploads"):
+                    continue
+                for name in files:
+                    full = os.path.join(root, name)
+                    arc_rel = os.path.relpath(full, job_dir)
+                    # Convert plot JSONs to PNG; include the underlying h5,
+                    # csv, log, defattr, meta as-is.
+                    if name.endswith(".json") and (
+                        rel.startswith("groups")
+                        or name == "combined_profile.json"
+                    ):
+                        png = _plot_json_to_png(full)
+                        if png is not None:
+                            zf.writestr(
+                                os.path.join(job_id, arc_rel[:-5] + ".png"),
+                                png,
+                            )
                         continue
-                    reactivities = f[group]["reactivity"][:]
-                    print(group, reactivities.shape)
-            ```
-
-            **CSV** (`profiles.csv`) contains the same data in a flat table
-            with columns: Position, Nucleotide, and for each group:
-            group_name, group_name_error. This is convenient for spreadsheet
-            analysis or cross-checking with other tools.
-
-            ### Result link
-
-            After the pipeline completes, a **result link** is displayed that
-            you can bookmark or share. Opening the link loads the results
-            directly into the app with the interactive plots, summary
-            statistics, and file downloads. Results are stored for
-            **{RESULTS_TTL_HOURS} hours** and automatically deleted after that.
-
-            To reload previous results manually, expand
-            **Load previous results** on the Run tab and enter the job ID.
-
-            ## Limits
-
-            This server has limited resources (16 GB RAM, CPU only). Very
-            large FASTQ files may cause out-of-memory errors. For larger
-            datasets, install cmuts locally:
-
-            ```bash
-            pip install cmuts
-            ```
-
-            See the [full documentation](https://hmblair.github.io/cmuts) for
-            CLI usage and advanced options.
-
-            ## Privacy
-
-            All uploaded data is processed in ephemeral temporary directories.
-            Pipeline results (reactivity profiles, plots, and summary
-            statistics) are stored for **{RESULTS_TTL_HOURS} hours** to provide
-            bookmarkable result links, then automatically deleted. No user
-            accounts, tracking, or cookies are used.
-            """
-        )
-
-
-# --- FastAPI routes ---
-
-app = FastAPI()
-
-
-@app.get("/results/{job_id}")
-async def results_page(job_id: str):
-    """Redirect to the Gradio app with the job ID as a query parameter."""
-    return RedirectResponse(url=f"/?job_id={job_id}")
-
-
-@app.get("/results/{job_id}/download")
-async def results_download(job_id: str):
-    h5_path = os.path.join(RESULTS_DIR, job_id, "profiles.h5")
-    if not os.path.isfile(h5_path):
-        return HTMLResponse(
-            "<h1>File not found</h1><p>This result may have expired.</p>",
-            status_code=404,
-        )
-
-    with open(os.path.join(RESULTS_DIR, job_id, "meta.json")) as f:
-        meta = json.load(f)
-    group_names = meta.get("group_names", [meta.get("group_name", "profiles")])
-    filename = "-".join(group_names) + "-profiles.h5"
-
-    return FileResponse(
-        h5_path,
-        media_type="application/x-hdf5",
-        filename=filename,
-    )
-
-
-@app.get("/results/{job_id}/download/csv")
-async def results_download_csv(job_id: str):
-    csv_path = os.path.join(RESULTS_DIR, job_id, "profiles.csv")
-    if not os.path.isfile(csv_path):
-        return HTMLResponse(
-            "<h1>File not found</h1><p>CSV not available for this result.</p>",
-            status_code=404,
-        )
-
-    with open(os.path.join(RESULTS_DIR, job_id, "meta.json")) as f:
-        meta = json.load(f)
-    group_names = meta.get("group_names", [meta.get("group_name", "profiles")])
-    filename = "-".join(group_names) + "-profiles.csv"
+                    if name == "meta.json":
+                        # Skip — internal app state, not useful to the user.
+                        continue
+                    zf.write(full, os.path.join(job_id, arc_rel))
+        buf.seek(0)
+        yield buf.read()
 
-    return FileResponse(
-        csv_path,
-        media_type="text/csv",
-        filename=filename,
-    )
+    headers = {"Content-Disposition": f'attachment; filename="{job_id}-results.zip"'}
+    return StreamingResponse(_gen(), media_type="application/zip", headers=headers)
 
 
-# Mount Gradio onto the FastAPI app
-app = gr.mount_gradio_app(app, demo, path="")
+# --- Local dev entry point ---
 
-# Run cleanup on startup
-cleanup_old_results()
 
 if __name__ == "__main__":
     import uvicorn
-    uvicorn.run(app, host="0.0.0.0", port=7860)
+
+    uvicorn.run(
+        "app:app",
+        host=os.environ.get("HOST", "127.0.0.1"),
+        port=int(os.environ.get("PORT", "7860")),
+        reload=bool(os.environ.get("RELOAD", "1") == "1"),
+    )

pipeline.py

@@ -0,0 +1,784 @@
+"""Pipeline orchestration for the cmuts web app.
+
+Framework-agnostic. Takes input paths + configs, runs ``cmuts align`` /
+``core`` / ``compute_reactivities``, and writes everything for one job
+into a single directory under ``RESULTS_DIR``.
+
+On-disk job layout::
+
+    {job_dir}/
+        profiles.h5               final per-group HDF5
+        profiles.csv              flat per-position table
+        meta.json                 status, group/sequence names, stats, log
+        log.txt                   raw streaming log
+        defattr/{group}.defattr   (if a CIF was supplied)
+        groups/{group}/{key}.json plotly figure JSON, first reference
+        combined_profile.json     overlay across groups (single-ref + multi-group)
+"""
+
+from __future__ import annotations
+
+import csv
+import glob
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import time
+import traceback
+from dataclasses import dataclass, field
+from typing import Callable
+
+import h5py
+import numpy as np
+import plotly.graph_objects as go
+
+
+# --- Constants ---
+
+MAX_GROUPS = int(os.environ.get("CMUTS_MAX_GROUPS", "5"))
+MAX_FASTQ_MB = int(os.environ.get("CMUTS_MAX_FASTQ_MB", "500"))
+RESULTS_TTL_HOURS = int(os.environ.get("CMUTS_RESULTS_TTL_HOURS", "48"))
+PIPELINE_TIMEOUT_SEC = int(os.environ.get("CMUTS_PIPELINE_TIMEOUT_SEC", "600"))
+DEFAULT_GROUP_NAME = "profile"
+
+_default_results_dir = "/data/results" if os.path.isdir("/data") else "/tmp/cmuts_results"
+RESULTS_DIR = os.environ.get("CMUTS_RESULTS_DIR", _default_results_dir)
+os.makedirs(RESULTS_DIR, exist_ok=True)
+
+_FASTQ_SUFFIXES = (".fastq.gz", ".fq.gz", ".fastq", ".fq")
+
+PLOT_KEYS = [
+    "profile", "mod_heatmap", "termination", "coverage",
+    "read_hist", "cumulative_reads", "snr_scaling",
+    "mi", "correlation", "pairwise_coverage",
+]
+
+
+# --- Dataclasses ---
+
+
+@dataclass
+class GroupInput:
+    name: str
+    mod_fastq: str
+    nomod_fastq: str | None = None
+
+
+@dataclass
+class AlignConfig:
+    trim_5: str = ""
+    trim_3: str = ""
+    local_align: bool = False
+
+
+@dataclass
+class CoreConfig:
+    min_mapq: int = 10
+    min_phred: int = 10
+    min_length: int = 2
+    max_length: int = 1024
+    no_insertions: bool = True
+    no_mismatches: bool = False
+    strand: str = "both"
+    compute_pairwise: bool = False
+
+
+@dataclass
+class NormConfig:
+    norm_method: str = "ubr"
+    no_insertions: bool = True
+    no_deletions: bool = False
+    clip_low: bool = False
+    clip_high: bool = False
+    blank_5p: int = 0
+    blank_3p: int = 0
+    blank_cutoff: int = 10
+    norm_cutoff: int = 500
+    norm_percentile: int = 90
+    sig: float = 0.05
+
+
+@dataclass
+class JobState:
+    """Mutable in-memory state for an in-flight job."""
+    job_id: str
+    status: str = "running"  # "running" | "done" | "error"
+    log_lines: list[str] = field(default_factory=list)
+    error: str | None = None
+
+    def log(self, msg: str) -> None:
+        self.log_lines.append(msg)
+
+
+# --- FASTA / FASTQ helpers ---
+
+
+def parse_fasta(fasta_path: str) -> list[tuple[str, str]]:
+    entries: list[tuple[str, str]] = []
+    name = ""
+    seq_parts: list[str] = []
+    with open(fasta_path) as f:
+        for line in f:
+            line = line.strip()
+            if line.startswith(">"):
+                if seq_parts:
+                    entries.append((name, "".join(seq_parts)))
+                    seq_parts = []
+                name = line[1:].split()[0]
+            elif line:
+                seq_parts.append(line)
+    if seq_parts:
+        entries.append((name, "".join(seq_parts)))
+    return entries
+
+
+def sanitize_group_name(raw: str | None) -> str:
+    name = re.sub(r"[^\w\-]", "_", (raw or "").strip())
+    return name or DEFAULT_GROUP_NAME
+
+
+def fastq_stem(path: str) -> str:
+    name = os.path.basename(path)
+    for suffix in _FASTQ_SUFFIXES:
+        if name.endswith(suffix):
+            return name[: -len(suffix)]
+    return os.path.splitext(name)[0]
+
+
+def file_size_mb(path: str) -> float:
+    return os.path.getsize(path) / (1024 * 1024)
+
+
+def build_seq_names(n: int, sequences: list[str] | None) -> list[str]:
+    """Build display labels for the sequence selector, disambiguating
+    truncated duplicates."""
+    raw: list[str] = []
+    for i in range(n):
+        seq = sequences[i] if sequences and i < len(sequences) else None
+        if seq and len(seq) > 50:
+            raw.append(seq[:50] + "...")
+        elif seq:
+            raw.append(seq)
+        else:
+            raw.append(f"Sequence {i + 1}")
+    counts: dict[str, int] = {}
+    out: list[str] = []
+    for label in raw:
+        if raw.count(label) > 1:
+            counts[label] = counts.get(label, 0) + 1
+            out.append(f"{label} (#{counts[label]})")
+        else:
+            out.append(label)
+    return out
+
+
+# --- CLI command builders ---
+
+
+def _build_align_cmd(
+    fasta_path: str,
+    output_dir: str,
+    fastq_files: list[str],
+    cfg: AlignConfig,
+) -> list[str]:
+    cmd = ["cmuts", "align", "--fasta", fasta_path, "--output", output_dir]
+    if cfg.trim_5.strip():
+        cmd.extend(["--trim-5", cfg.trim_5.strip()])
+    if cfg.trim_3.strip():
+        cmd.extend(["--trim-3", cfg.trim_3.strip()])
+    if cfg.local_align:
+        cmd.append("--local")
+    cmd.extend(fastq_files)
+    return cmd
+
+
+def _build_core_cmd(
+    fasta_path: str,
+    output_h5: str,
+    bam_files: list[str],
+    cfg: CoreConfig,
+) -> list[str]:
+    cmd = [
+        "cmuts", "core",
+        "-f", fasta_path,
+        "-o", output_h5,
+        "--min-mapq", str(cfg.min_mapq),
+        "--min-phred", str(cfg.min_phred),
+        "--min-length", str(cfg.min_length),
+        "--max-length", str(cfg.max_length),
+    ]
+    if cfg.no_insertions:
+        cmd.append("--no-insertions")
+    if cfg.no_mismatches:
+        cmd.append("--no-mismatches")
+    if cfg.strand == "forward":
+        cmd.append("--no-reverse")
+    elif cfg.strand == "reverse":
+        cmd.append("--only-reverse")
+    if cfg.compute_pairwise:
+        cmd.append("--pairwise")
+    cmd.extend(bam_files)
+    return cmd
+
+
+# --- CSV generation ---
+
+
+def _generate_csv(
+    h5_path: str,
+    fasta_path: str,
+    group_names: list[str],
+) -> str:
+    """Generate a CSV from HDF5 profiles with columns for each group."""
+    fasta_entries = parse_fasta(fasta_path)
+    csv_path = h5_path.rsplit(".", 1)[0] + ".csv"
+
+    with h5py.File(h5_path, "r") as f, open(csv_path, "w", newline="") as csvfile:
+        writer = csv.writer(csvfile)
+
+        first_grp = f[group_names[0]]
+        n_refs = first_grp["reactivity"].shape[0]
+        seq_len = first_grp["reactivity"].shape[1]
+        multi_ref = n_refs > 1
+
+        header: list[str] = []
+        if multi_ref:
+            header.append("Reference")
+        header.extend(["Position", "Nucleotide"])
+        for gn in group_names:
+            header.extend([gn, f"{gn}_error"])
+        writer.writerow(header)
+
+        for ref_idx in range(n_refs):
+            ref_name = fasta_entries[ref_idx][0] if ref_idx < len(fasta_entries) else f"ref_{ref_idx + 1}"
+            ref_seq = fasta_entries[ref_idx][1] if ref_idx < len(fasta_entries) else ""
+
+            group_data: dict[str, dict[str, np.ndarray]] = {}
+            for gn in group_names:
+                group_data[gn] = {
+                    "reactivity": np.array(f[gn]["reactivity"])[ref_idx],
+                    "error": np.array(f[gn]["error"])[ref_idx],
+                }
+
+            for pos in range(seq_len):
+                row: list[str] = []
+                if multi_ref:
+                    row.append(ref_name)
+                row.append(str(pos + 1))
+                row.append(ref_seq[pos] if pos < len(ref_seq) else "")
+                for gn in group_names:
+                    r = group_data[gn]["reactivity"][pos]
+                    e = group_data[gn]["error"][pos]
+                    row.append(f"{r:.6f}" if np.isfinite(r) else "")
+                    row.append(f"{e:.6f}" if np.isfinite(e) else "")
+                writer.writerow(row)
+
+    return csv_path
+
+
+# --- Structure visualization (ChimeraX defattr) ---
+
+
+def _build_defattrs(
+    cif_path: str,
+    sequence: str,
+    results: list,
+    out_dir: str,
+    chimerax_bin: str = "ChimeraX",
+):
+    """Generate one defattr per group plus a markdown command snippet.
+
+    Returns (defattr_paths, markdown).
+    """
+    import cmuts as _cmuts  # imported lazily so app starts without cmuts
+
+    cif_basename = os.path.basename(cif_path)
+    aln_seq = sequence.upper().replace("U", "T")
+
+    defattr_paths: list[str] = []
+    blocks: list[str] = [
+        "### Visualize the structure with ChimeraX",
+        "",
+        f"Download each `.defattr` file below, place it next to your "
+        f"`{cif_basename}` (a copy of your uploaded structure), and run "
+        f"the matching command in ChimeraX's command line.",
+        "",
+    ]
+
+    for r in results:
+        name = r.group.name
+        reactivity = np.asarray(r.combined.reactivity)
+        if reactivity.shape[0] != 1:
+            continue
+        defattr_path = os.path.join(out_dir, f"{name}.defattr")
+        try:
+            max_value = _cmuts.visualize.make_defattr(
+                reactivity[0], aln_seq, cif_path, defattr_path,
+            )
+        except Exception as e:  # noqa: BLE001
+            blocks.append(f"**{name}:** could not generate defattr — {e}")
+            blocks.append("")
+            continue
+        cmd = _cmuts.visualize.chimerax_command(
+            cif_basename, os.path.basename(defattr_path),
+            color="indianred", max_value=max_value,
+        )
+        blocks.append(f"**{name}:**")
+        blocks.append("```")
+        blocks.append(f"{chimerax_bin} --cmd '{cmd}'")
+        blocks.append("```")
+        blocks.append("")
+        defattr_paths.append(defattr_path)
+
+    if not defattr_paths:
+        return [], ""
+    return defattr_paths, "\n".join(blocks)
+
+
+# --- Plot building ---
+
+
+def _build_plots_for_group(
+    mod, nomod, combined,
+    group_name: str,
+    sequence: str | None,
+) -> dict[str, go.Figure | None]:
+    """Build every diagnostic plot for one group. Returns key -> Figure or
+    None when the underlying data is absent."""
+    from cmuts.visualize.plotly import (
+        plot_correlation, plot_coverage, plot_cumulative_reads, plot_examples,
+        plot_heatmap, plot_mi, plot_pairwise_coverage,
+        plot_read_hist, plot_snr_scaling, plot_termination,
+    )
+
+    plots: dict[str, go.Figure | None] = {}
+    plots["profile"] = plot_examples(
+        np.asarray(combined.reactivity), np.asarray(combined.error),
+        group_name, sequence=sequence,
+    )
+    plots["mod_heatmap"] = plot_heatmap(np.asarray(combined.heatmap), group_name)
+    plots["termination"] = plot_termination(np.asarray(combined.terminations), group_name)
+    plots["coverage"] = plot_coverage(
+        np.asarray(combined.coverage), np.asarray(combined.reads), group_name,
+    )
+
+    is_multi = not combined.single()
+    reads = np.asarray(combined.reads)
+    plots["read_hist"] = plot_read_hist(reads, group_name) if is_multi else None
+    plots["cumulative_reads"] = plot_cumulative_reads(reads, group_name) if is_multi else None
+
+    plots["snr_scaling"] = plot_snr_scaling(mod, nomod, combined, group_name)
+
+    plots["mi"] = (
+        plot_mi(np.asarray(combined.mi)[0], group_name)
+        if combined.mi is not None else None
+    )
+    plots["correlation"] = (
+        plot_correlation(np.asarray(combined.covariance)[0], group_name)
+        if combined.covariance is not None else None
+    )
+    if combined.probability is not None:
+        prob = np.asarray(combined.probability)
+        plots["pairwise_coverage"] = plot_pairwise_coverage(prob[0, :, :, 1, 1], group_name)
+    else:
+        plots["pairwise_coverage"] = None
+    return plots
+
+
+def _save_plot_json(fig: go.Figure | None, path: str) -> bool:
+    if fig is None:
+        return False
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w") as f:
+        f.write(fig.to_json())
+    return True
+
+
+def _build_stats_for_group(grp, ref_count: int) -> list[list[str]]:
+    reactivity = np.array(grp["reactivity"])
+    reads = np.array(grp["reads"])
+    error = np.array(grp["error"])
+    snr = np.array(grp["SNR"])
+
+    n_refs = reactivity.shape[0]
+    seq_len = reactivity.shape[1]
+    total_reads = int(reads.sum())
+    valid = np.isfinite(reactivity)
+
+    rows: list[list[str]] = [
+        ["References", f"{n_refs:,}"],
+        ["Reference length", f"{seq_len:,}"],
+        ["Total reads", f"{total_reads:,}"],
+        ["Mean reads per reference", f"{np.mean(reads):,.1f}"],
+        ["Median reads per reference", f"{int(np.median(reads)):,}"],
+    ]
+    if valid.any():
+        rows.extend([
+            ["Mean reactivity", f"{np.mean(reactivity[valid]):.3f}"],
+            ["Mean error", f"{np.mean(error[valid]):.3f}"],
+            ["Mean SNR", f"{np.mean(snr):.2f}"],
+            ["SNR > 1", f"{np.mean(snr > 1):.1%}"],
+        ])
+    dropout = float(np.mean(reads == 0))
+    if dropout > 0:
+        rows.append(["Dropout fraction", f"{dropout:.1%}"])
+    return rows
+
+
+# --- Results persistence + cleanup ---
+
+
+def job_dir_for(job_id: str) -> str:
+    return os.path.join(RESULTS_DIR, job_id)
+
+
+def cleanup_old_results() -> None:
+    """Delete result directories older than RESULTS_TTL_HOURS."""
+    cutoff = time.time() - RESULTS_TTL_HOURS * 3600
+    if not os.path.isdir(RESULTS_DIR):
+        return
+    for entry in os.scandir(RESULTS_DIR):
+        if not entry.is_dir():
+            continue
+        meta_path = os.path.join(entry.path, "meta.json")
+        try:
+            if os.path.exists(meta_path):
+                with open(meta_path) as f:
+                    created = json.load(f).get("created_at", 0)
+            else:
+                created = entry.stat().st_mtime
+            if created < cutoff:
+                shutil.rmtree(entry.path, ignore_errors=True)
+        except Exception:
+            pass
+
+
+def write_meta(job_dir: str, meta: dict) -> None:
+    with open(os.path.join(job_dir, "meta.json"), "w") as f:
+        json.dump(meta, f)
+
+
+def read_meta(job_dir: str) -> dict | None:
+    path = os.path.join(job_dir, "meta.json")
+    if not os.path.isfile(path):
+        return None
+    with open(path) as f:
+        return json.load(f)
+
+
+def write_log(job_dir: str, log_lines: list[str]) -> None:
+    with open(os.path.join(job_dir, "log.txt"), "w") as f:
+        f.write("\n".join(log_lines))
+
+
+# --- On-demand plot generation (sequence switching) ---
+
+
+def build_profile_plot(job_dir: str, group_name: str, seq_idx: int) -> str | None:
+    """Build a profile plot JSON on demand for a given group/sequence."""
+    from cmuts.visualize.plotly import plot_profile
+
+    h5_path = os.path.join(job_dir, "profiles.h5")
+    if not os.path.isfile(h5_path):
+        return None
+    with h5py.File(h5_path, "r") as f:
+        if group_name not in f:
+            return None
+        grp = f[group_name]
+        reactivity = np.array(grp["reactivity"])
+        error = np.array(grp["error"])
+        sequences = None
+        if "sequence" in f:
+            sequences = [
+                s.decode() if isinstance(s, bytes) else s for s in f["sequence"]
+            ]
+    if seq_idx < 0 or seq_idx >= reactivity.shape[0]:
+        return None
+    seq = sequences[seq_idx] if sequences and seq_idx < len(sequences) else None
+    names = build_seq_names(reactivity.shape[0], sequences)
+    fig = plot_profile(reactivity[seq_idx], error[seq_idx], names[seq_idx], sequence=seq)
+    return fig.to_json()
+
+
+def build_perref_plot(
+    job_dir: str, group_name: str, key: str, seq_idx: int,
+) -> str | None:
+    """Rebuild a per-reference plot (mi / correlation / pairwise_coverage)
+    for a different reference. Returns None if not available."""
+    from cmuts.visualize.plotly import (
+        plot_correlation, plot_mi, plot_pairwise_coverage,
+    )
+
+    h5_path = os.path.join(job_dir, "profiles.h5")
+    if not os.path.isfile(h5_path):
+        return None
+    with h5py.File(h5_path, "r") as f:
+        if group_name not in f:
+            return None
+        grp = f[group_name]
+        if key == "mi":
+            if "mutual-information" not in grp:
+                return None
+            arr = np.array(grp["mutual-information"])
+        elif key == "correlation":
+            if "covariance" not in grp:
+                return None
+            arr = np.array(grp["covariance"])
+        elif key == "pairwise_coverage":
+            if "probability" not in grp:
+                return None
+            arr = np.array(grp["probability"])
+        else:
+            return None
+    if seq_idx < 0 or seq_idx >= arr.shape[0]:
+        return None
+    if key == "mi":
+        fig = plot_mi(arr[seq_idx], group_name)
+    elif key == "correlation":
+        fig = plot_correlation(arr[seq_idx], group_name)
+    else:  # pairwise_coverage
+        fig = plot_pairwise_coverage(arr[seq_idx, :, :, 1, 1], group_name)
+    return fig.to_json()
+
+
+# --- Main pipeline ---
+
+
+def run_pipeline(
+    job_id: str,
+    job_dir: str,
+    fasta_path: str,
+    groups: list[GroupInput],
+    align_cfg: AlignConfig,
+    core_cfg: CoreConfig,
+    norm_cfg: NormConfig,
+    cif_path: str | None,
+    state: JobState,
+) -> None:
+    """Run the full pipeline. All status/log goes through ``state``.
+
+    Writes results into ``job_dir``. On failure, ``state.status`` becomes
+    ``"error"`` and ``state.error`` holds a short message. On success,
+    ``state.status`` becomes ``"done"``.
+    """
+    workdir = tempfile.mkdtemp(prefix="cmuts_")
+    outdir = os.path.join(workdir, "outputs")
+    os.makedirs(outdir)
+
+    def log(msg: str) -> None:
+        state.log(msg)
+
+    def run_subprocess(cmd: list[str], cwd: str = outdir) -> bool:
+        log(f"$ {' '.join(cmd)}")
+        try:
+            result = subprocess.run(
+                cmd, cwd=cwd, capture_output=True, text=True,
+                timeout=PIPELINE_TIMEOUT_SEC,
+            )
+        except subprocess.TimeoutExpired:
+            log(f"Command timed out after {PIPELINE_TIMEOUT_SEC}s")
+            return False
+        if result.stdout:
+            log(result.stdout.rstrip())
+        if result.stderr:
+            log(result.stderr.rstrip())
+        if result.returncode != 0:
+            log(f"Command failed with exit code {result.returncode}")
+            return False
+        return True
+
+    try:
+        try:
+            import cmuts as _cmuts
+        except ImportError as e:
+            raise RuntimeError(
+                "cmuts is not installed in this environment. "
+                "Run the app under Docker (see Dockerfile) or install cmuts."
+            ) from e
+
+        # Stage FASTQ files with a group-name prefix to avoid collisions.
+        fastq_dir = os.path.join(workdir, "fastq")
+        os.makedirs(fastq_dir)
+
+        group_fastq_info: list[tuple[str, str, str | None]] = []
+        for g in groups:
+            prefix = g.name + "__"
+            mod_basename = prefix + os.path.basename(g.mod_fastq)
+            mod_stem = fastq_stem(mod_basename)
+            shutil.copy(g.mod_fastq, os.path.join(fastq_dir, mod_basename))
+
+            nomod_stem = None
+            if g.nomod_fastq is not None:
+                nomod_basename = prefix + os.path.basename(g.nomod_fastq)
+                nomod_stem = fastq_stem(nomod_basename)
+                shutil.copy(g.nomod_fastq, os.path.join(fastq_dir, nomod_basename))
+
+            group_fastq_info.append((g.name, mod_stem, nomod_stem))
+
+        # Step 1: align
+        log("=== Step 1: Aligning reads ===")
+        fastq_files = sorted(glob.glob(os.path.join(fastq_dir, "*")))
+        alignments_dir = os.path.join(outdir, "alignments")
+        if not run_subprocess(_build_align_cmd(fasta_path, alignments_dir, fastq_files, align_cfg)):
+            raise RuntimeError("Alignment failed. See log for details.")
+
+        bam_files_abs = sorted(glob.glob(os.path.join(alignments_dir, "*.bam")))
+        if not bam_files_abs:
+            raise RuntimeError(
+                "Alignment produced no BAM files. Check log — the reference "
+                "may not match the reads, or the FASTQ may be empty."
+            )
+
+        # Step 2: count mutations
+        log("\n=== Step 2: Counting mutations ===")
+        bam_files = sorted(os.path.relpath(p, outdir) for p in bam_files_abs)
+        counts_h5 = "counts.h5"
+        if not run_subprocess(_build_core_cmd(fasta_path, counts_h5, bam_files, core_cfg)):
+            raise RuntimeError("Mutation counting failed. See log for details.")
+
+        counts_path = os.path.join(outdir, counts_h5)
+        if not os.path.isfile(counts_path):
+            raise RuntimeError("cmuts core did not produce counts.h5.")
+
+        # Step 3: normalize
+        log("\n=== Step 3: Normalizing reactivities ===")
+        cmuts_groups = [
+            _cmuts.Group(
+                name=name,
+                mod=[f"alignments/{mod_stem}"],
+                nomod=[f"alignments/{nomod_stem}"] if nomod_stem else None,
+            )
+            for name, mod_stem, nomod_stem in group_fastq_info
+        ]
+
+        norm_opts = _cmuts.Opts(
+            _cmuts.DataGroups([]),
+            _cmuts.DataGroups(None),
+            norm_cfg.blank_cutoff,
+            not norm_cfg.no_insertions,
+            not norm_cfg.no_deletions,
+            norm_cfg.norm_method,
+            (norm_cfg.blank_5p, norm_cfg.blank_3p),
+            (norm_cfg.clip_low, norm_cfg.clip_high),
+            norm_cfg.sig,
+        )
+
+        with h5py.File(counts_path, "r") as f:
+            results = _cmuts.compute_reactivities(
+                f, fasta_path, cmuts_groups, norm_opts, shared_norm=True,
+            )
+
+        if len(results) > 1:
+            log(f"  Pooled {norm_cfg.norm_method} normalization across {len(results)} groups.")
+        log("Normalization complete.")
+
+        # Save the combined HDF5 + CSV.
+        final_h5 = os.path.join(job_dir, "profiles.h5")
+        _cmuts.save_groups(final_h5, [(r.group.name, r.combined) for r in results])
+
+        group_names = [r.group.name for r in results]
+        csv_path = _generate_csv(final_h5, fasta_path, group_names)
+        # Move CSV next to HDF5.
+        final_csv = os.path.join(job_dir, "profiles.csv")
+        if csv_path != final_csv:
+            shutil.move(csv_path, final_csv)
+        log("Wrote profiles.h5 and profiles.csv.")
+
+        # Sequence names + single-ref check.
+        fasta_entries = parse_fasta(fasta_path)
+        first_combined = results[0].combined
+        single_ref = bool(first_combined.single()) and len(fasta_entries) == 1
+        ref_sequence = fasta_entries[0][1] if single_ref else None
+        sequence_names_per_group: dict[str, list[str]] = {}
+
+        # Per-group plots: profile, heatmap, termination, coverage, ... (first ref).
+        for r in results:
+            gname = r.group.name
+            group_plot_dir = os.path.join(job_dir, "groups", gname)
+            os.makedirs(group_plot_dir, exist_ok=True)
+            plots = _build_plots_for_group(
+                r.mod, r.nomod, r.combined, gname, sequence=ref_sequence,
+            )
+            for key, fig in plots.items():
+                _save_plot_json(fig, os.path.join(group_plot_dir, f"{key}.json"))
+
+        # Combined profile across groups (only when single-ref + >1 group).
+        has_combined = False
+        if single_ref and len(results) > 1:
+            from cmuts.visualize.plotly import plot_profiles
+            reactivities = [np.asarray(r.combined.reactivity)[0] for r in results]
+            combined_fig = plot_profiles(reactivities, group_names, sequence=ref_sequence)
+            _save_plot_json(combined_fig, os.path.join(job_dir, "combined_profile.json"))
+            has_combined = True
+
+        # Per-group sequence names + stats.
+        stats: dict[str, list[list[str]]] = {}
+        with h5py.File(final_h5, "r") as f:
+            sequences = None
+            if "sequence" in f:
+                sequences = [
+                    s.decode() if isinstance(s, bytes) else s for s in f["sequence"]
+                ]
+            for gname in group_names:
+                reactivity = np.array(f[gname]["reactivity"])
+                seq_names = build_seq_names(reactivity.shape[0], sequences)
+                sequence_names_per_group[gname] = seq_names
+                stats[gname] = _build_stats_for_group(f[gname], reactivity.shape[0])
+
+        # Optional CIF visualization (per-group defattrs).
+        defattr_files: list[str] = []
+        chimerax_md = ""
+        if cif_path is not None and ref_sequence is not None:
+            defattr_dir = os.path.join(job_dir, "defattr")
+            os.makedirs(defattr_dir, exist_ok=True)
+            cif_workdir_path = os.path.join(workdir, os.path.basename(cif_path))
+            shutil.copy(cif_path, cif_workdir_path)
+            paths, md = _build_defattrs(cif_workdir_path, ref_sequence, results, defattr_dir)
+            defattr_files = [os.path.basename(p) for p in paths]
+            chimerax_md = md
+            if defattr_files:
+                log(f"Wrote {len(defattr_files)} defattr file(s).")
+        elif cif_path is not None:
+            log(
+                "Skipping structure visualization: defattr generation requires "
+                "a single-reference FASTA."
+            )
+
+        meta = {
+            "job_id": job_id,
+            "group_names": group_names,
+            "sequence_names": sequence_names_per_group,
+            "single_ref": single_ref,
+            "has_combined_profile": has_combined,
+            "ref_count": int(np.array(results[0].combined.reactivity).shape[0]),
+            "is_pairwise": core_cfg.compute_pairwise,
+            "stats": stats,
+            "defattr_files": defattr_files,
+            "chimerax_md": chimerax_md,
+            "created_at": time.time(),
+        }
+        write_meta(job_dir, meta)
+        write_log(job_dir, state.log_lines)
+
+        log(f"\nDone. Generated profiles for {len(results)} group(s).")
+        state.status = "done"
+
+    except Exception as e:  # noqa: BLE001
+        msg = str(e) or "Unexpected error. See log for details."
+        log(f"Error: {msg}")
+        log(traceback.format_exc())
+        state.error = msg
+        state.status = "error"
+        # Still persist meta + log so the results page can show what happened.
+        write_meta(job_dir, {
+            "job_id": job_id,
+            "status": "error",
+            "error": msg,
+            "created_at": time.time(),
+        })
+        write_log(job_dir, state.log_lines)
+    finally:
+        shutil.rmtree(workdir, ignore_errors=True)

pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "cmuts-space"
+version = "0.1.0"
+description = "Web UI for the cmuts RNA chemical-probing pipeline."
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.27",
+    "jinja2>=3.1",
+    "python-multipart>=0.0.9",
+    "plotly>=5.20",
+    "kaleido==0.2.1",
+    "h5py>=3.10",
+    "numpy>=1.26",
+]
+
+[project.optional-dependencies]
+# Install with `uv sync --extra cmuts` once the cmuts repo is built locally.
+# Skip this group if you only want to work on the UI; the pipeline will
+# return a clean error.
+cmuts = ["cmuts"]
+
+[tool.uv.sources]
+cmuts = { path = "../cmuts" }
+

static/app.css

@@ -0,0 +1,274 @@
+:root {
+  color-scheme: dark;
+  --fg: #e6e9ef;
+  --muted: #8b94a5;
+  --bg: #14161a;
+  --bg-soft: #1d2027;
+  --bg-elev: #232732;
+  --border: #2c313c;
+  --primary: #c4a7ff;
+  --primary-strong: #b794f6;
+  --primary-fg: #14161a;
+  --error-bg: #2a1418;
+  --error-fg: #f5808d;
+  --radius: 6px;
+}
+
+* { box-sizing: border-box; }
+
+html, body {
+  margin: 0;
+  padding: 0;
+  font: 14px/1.45 -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  color: var(--fg);
+  background: var(--bg);
+}
+
+main {
+  max-width: 1100px;
+  margin: 0 auto;
+  padding: 1.5rem 1rem 3rem;
+}
+
+.site-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.75rem 1.25rem;
+  border-bottom: 1px solid var(--border);
+}
+.site-header .brand {
+  font-weight: 700;
+  font-size: 1.1rem;
+  text-decoration: none;
+  color: var(--fg);
+}
+.site-header nav a {
+  margin-left: 1rem;
+  color: var(--muted);
+  text-decoration: none;
+}
+.site-header nav a:hover { color: var(--fg); }
+
+.site-footer {
+  text-align: center;
+  color: var(--muted);
+  padding: 1rem;
+  border-top: 1px solid var(--border);
+}
+
+h1, h2, h3 { line-height: 1.2; margin-top: 0; }
+h1 { font-size: 1.5rem; }
+h2 { font-size: 1.2rem; }
+h3 { font-size: 1.0rem; color: var(--muted); }
+
+.muted { color: var(--muted); }
+.hint { color: var(--muted); font-size: 0.9rem; }
+
+a { color: var(--primary); }
+
+.card {
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 1rem 1.25rem;
+  margin-bottom: 1.25rem;
+  background: var(--bg-soft);
+}
+fieldset.card { display: block; }
+fieldset.card legend {
+  font-weight: 600;
+  padding: 0 0.4rem;
+}
+
+.intro { margin-bottom: 1rem; }
+.intro h1 { margin-bottom: 0.25rem; }
+
+label { display: block; margin: 0.4rem 0; }
+label.check { display: flex; align-items: center; gap: 0.4rem; }
+
+input[type="text"], input[type="number"], select {
+  width: 100%;
+  padding: 0.4rem 0.5rem;
+  font: inherit;
+  color: var(--fg);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  background: var(--bg-elev);
+}
+input[type="text"]:focus, input[type="number"]:focus, select:focus,
+input[type="file"]:focus {
+  outline: 2px solid var(--primary);
+  outline-offset: -1px;
+}
+
+input[type="file"] {
+  display: block;
+  margin-top: 0.25rem;
+  color: var(--muted);
+  font: inherit;
+}
+input[type="file"]::file-selector-button {
+  font: inherit;
+  margin-right: 0.6rem;
+  padding: 0.35rem 0.7rem;
+  border-radius: var(--radius);
+  border: 1px solid var(--border);
+  background: var(--bg-elev);
+  color: var(--fg);
+  cursor: pointer;
+}
+input[type="file"]::file-selector-button:hover {
+  background: var(--border);
+}
+
+.file-pick { display: block; }
+.file-pick > span { font-weight: 500; }
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
+  gap: 0.5rem 1rem;
+  margin-top: 0.5rem;
+}
+
+details {
+  border-top: 1px solid var(--border);
+  margin-top: 0.5rem;
+  padding-top: 0.5rem;
+}
+details:first-of-type { border-top: 0; padding-top: 0; }
+summary {
+  cursor: pointer;
+  font-weight: 600;
+  padding: 0.25rem 0;
+}
+
+.group-row {
+  display: grid;
+  grid-template-columns: minmax(160px, 1fr) 2fr 2fr auto;
+  gap: 0.5rem;
+  align-items: end;
+  padding: 0.5rem;
+  border: 1px dashed var(--border);
+  border-radius: var(--radius);
+  margin-bottom: 0.5rem;
+}
+.group-row .file-pick { margin: 0; }
+
+button, .button {
+  display: inline-block;
+  font: inherit;
+  border: 1px solid var(--border);
+  background: var(--bg-elev);
+  color: var(--fg);
+  border-radius: var(--radius);
+  padding: 0.4rem 0.8rem;
+  cursor: pointer;
+  text-decoration: none;
+  text-align: center;
+  transition: background 0.12s ease, border-color 0.12s ease;
+}
+button:hover, .button:hover {
+  background: var(--border);
+  border-color: var(--primary);
+}
+button.primary, .button.primary {
+  background: var(--primary);
+  color: var(--primary-fg);
+  border-color: var(--primary);
+  font-weight: 600;
+}
+button.primary:hover, .button.primary:hover {
+  background: var(--primary-strong);
+  border-color: var(--primary-strong);
+}
+button.secondary { background: var(--bg-elev); }
+button.remove-row { padding: 0.4rem 0.7rem; }
+
+.row-actions {
+  display: flex;
+  gap: 0.5rem;
+  margin-top: 0.5rem;
+}
+
+.submit-row {
+  display: flex;
+  justify-content: flex-end;
+  margin-bottom: 1rem;
+}
+
+.results-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-end;
+  gap: 1rem;
+  margin-bottom: 1rem;
+  flex-wrap: wrap;
+}
+.header-actions { display: flex; gap: 0.4rem; }
+
+.selectors { display: flex; gap: 1rem; margin-bottom: 1rem; }
+.selectors label { flex: 0 1 auto; }
+.selectors select { min-width: 220px; }
+
+.stats { width: 100%; border-collapse: collapse; margin-bottom: 1.5rem; }
+.stats td { padding: 0.25rem 0.5rem; border-bottom: 1px solid var(--border); }
+.stats td:first-child { color: var(--muted); width: 18rem; }
+
+.plot-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(420px, 1fr));
+  gap: 1rem;
+}
+.plot-tile {
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 0.75rem;
+  background: #ffffff;
+  color: #1c1f24;
+  overflow: hidden;
+  min-width: 0;
+}
+.plot-tile h3 { margin-bottom: 0.5rem; color: #4a525f; }
+.plot { width: 100%; height: 380px; min-width: 0; }
+.plot .js-plotly-plot, .plot .plot-container { width: 100% !important; }
+
+pre.log {
+  background: #0b0d12;
+  color: #d6e1f0;
+  border: 1px solid var(--border);
+  padding: 0.75rem;
+  border-radius: var(--radius);
+  overflow-x: auto;
+  font-size: 0.85rem;
+  white-space: pre-wrap;
+  max-height: 30rem;
+}
+
+pre.markdown {
+  background: var(--bg-elev);
+  border: 1px solid var(--border);
+  padding: 0.75rem;
+  border-radius: var(--radius);
+  white-space: pre-wrap;
+  color: var(--fg);
+}
+
+.error { border-color: var(--error-fg); background: var(--error-bg); }
+.error h1 { color: var(--error-fg); }
+.error-msg { color: var(--error-fg); font-weight: 600; }
+
+a { color: var(--primary); }
+a:hover { color: var(--primary-strong); }
+
+h3 { color: var(--fg); opacity: 0.85; }
+
+.group-row {
+  background: var(--bg-elev);
+  border-color: var(--border);
+}
+
+.stats td { border-color: var(--border); }
+.stats td:first-child { color: var(--muted); }
+
+.downloads { display: flex; gap: 0.5rem; flex-wrap: wrap; margin-top: 0.5rem; }

static/app.js

@@ -0,0 +1 @@
+// Global helpers. Page-specific code lives in dedicated files.

static/results.js

@@ -0,0 +1,125 @@
+// Results page: per-group + per-sequence plot navigation.
+
+(function () {
+  const meta = JSON.parse(document.getElementById('meta-data').textContent);
+  const jobId = window.location.pathname.split('/').filter(Boolean)[1];
+
+  const groupSelect = document.getElementById('group-select');
+  const seqSelect = document.getElementById('seq-select');
+  const seqWrapper = document.getElementById('seq-select-wrapper');
+  const statsTable = document.getElementById('stats-table');
+  const tiles = Array.from(document.querySelectorAll('.plot-tile'));
+
+  // Plots whose data is per-reference (sequence selector applies).
+  const PER_REF = new Set(['profile', 'mi', 'correlation', 'pairwise_coverage']);
+
+  function emptyTile(tile, msg) {
+    const plot = tile.querySelector('.plot');
+    plot.innerHTML = `<p class="muted">${msg}</p>`;
+  }
+
+  function normalizeLayout(layout) {
+    // Strip fixed width/height so the container drives sizing. Everything
+    // else (theme, fonts, axes, colors) is left exactly as cmuts emits.
+    const out = Object.assign({}, layout || {});
+    delete out.width;
+    delete out.height;
+    out.autosize = true;
+    return out;
+  }
+
+  async function renderPlot(tile, group, key, seq) {
+    const plotEl = tile.querySelector('.plot');
+    tile.style.display = '';
+    plotEl.innerHTML = '<p class="muted">Loading…</p>';
+    const url = `/results/${jobId}/plot/${encodeURIComponent(group)}/${encodeURIComponent(key)}?seq=${seq}`;
+    try {
+      const resp = await fetch(url);
+      if (resp.status === 404) {
+        tile.style.display = 'none';
+        return;
+      }
+      if (!resp.ok) {
+        emptyTile(tile, `Failed to load (HTTP ${resp.status}).`);
+        return;
+      }
+      const fig = await resp.json();
+      if (typeof Plotly === 'undefined') {
+        emptyTile(tile, 'Plotly library failed to load.');
+        return;
+      }
+      plotEl.innerHTML = '';
+      await Plotly.newPlot(
+        plotEl, fig.data, normalizeLayout(fig.layout),
+        {responsive: true, displaylogo: false},
+      );
+    } catch (e) {
+      console.error('Plot render failed', key, group, e);
+      emptyTile(tile, `Error: ${e.message || e}`);
+    }
+  }
+
+  function renderStats(group) {
+    const rows = (meta.stats && meta.stats[group]) || [];
+    statsTable.innerHTML = rows.map(r =>
+      `<tr><td>${r[0]}</td><td>${r[1]}</td></tr>`
+    ).join('');
+  }
+
+  function refreshSeqOptions(group) {
+    const names = (meta.sequence_names && meta.sequence_names[group]) || [];
+    seqSelect.innerHTML = names.map((n, i) =>
+      `<option value="${i}">${escapeHtml(n)}</option>`
+    ).join('');
+    if (names.length > 1) {
+      seqWrapper.style.display = '';
+    } else {
+      seqWrapper.style.display = 'none';
+    }
+  }
+
+  function escapeHtml(s) {
+    return String(s).replace(/[&<>"']/g, c => ({
+      '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'
+    }[c]));
+  }
+
+  async function renderCombined() {
+    const el = document.getElementById('plot-combined');
+    if (!el) return;
+    try {
+      const resp = await fetch(`/results/${jobId}/plot/combined`);
+      if (!resp.ok) return;
+      const fig = await resp.json();
+      Plotly.newPlot(el, fig.data, fig.layout, {responsive: true, displaylogo: false});
+    } catch (e) { /* ignore */ }
+  }
+
+  async function refreshAll() {
+    const group = groupSelect.value;
+    const seq = parseInt(seqSelect.value || '0', 10);
+    renderStats(group);
+    await Promise.all(tiles.map(tile =>
+      renderPlot(tile, group, tile.dataset.key, PER_REF.has(tile.dataset.key) ? seq : 0)
+    ));
+  }
+
+  async function refreshPerRef() {
+    const group = groupSelect.value;
+    const seq = parseInt(seqSelect.value || '0', 10);
+    await Promise.all(tiles
+      .filter(t => PER_REF.has(t.dataset.key))
+      .map(tile => renderPlot(tile, group, tile.dataset.key, seq))
+    );
+  }
+
+  groupSelect.addEventListener('change', () => {
+    refreshSeqOptions(groupSelect.value);
+    refreshAll();
+  });
+  seqSelect.addEventListener('change', refreshPerRef);
+
+  refreshSeqOptions(groupSelect.value);
+  renderCombined();
+  refreshAll();
+})();

templates/_group_row.html

@@ -0,0 +1,15 @@
+<div class="group-row">
+  <input type="text" name="group_name"
+         placeholder="Group name (e.g. 2A3_with_cdiGMP)"
+         value="{{ (initial.name if initial else '') }}">
+  <label class="file-pick">
+    <span>Modified FASTQ (required)</span>
+    <input type="file" name="mod_fastq" accept=".fastq,.fq,.gz">
+  </label>
+  <label class="file-pick">
+    <span>Control FASTQ (optional)</span>
+    <input type="file" name="nomod_fastq" accept=".fastq,.fq,.gz">
+  </label>
+  <button type="button" class="remove-row"
+          onclick="this.closest('.group-row').remove()">Remove</button>
+</div>

templates/base.html

@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>{% block title %}cmuts — RNA Chemical Probing Analysis{% endblock %}</title>
+  <link rel="stylesheet" href="/static/app.css">
+  <script src="https://unpkg.com/htmx.org@1.9.12" defer></script>
+  <script src="https://cdn.plot.ly/plotly-3.0.1.min.js" defer></script>
+</head>
+<body>
+  <header class="site-header">
+    <a href="/" class="brand">cmuts</a>
+    <nav>
+      <a href="https://github.com/hmblair/cmuts">GitHub</a>
+      <a href="https://hmblair.github.io/cmuts">Docs</a>
+    </nav>
+  </header>
+  <main>
+    {% block content %}{% endblock %}
+  </main>
+  <footer class="site-footer">
+    <span>MIT licensed</span>
+  </footer>
+  {% block scripts %}{% endblock %}
+</body>
+</html>

templates/index.html

@@ -0,0 +1,110 @@
+{% extends "base.html" %}
+{% block content %}
+<section class="intro">
+  <h1>cmuts — RNA Chemical Probing Analysis</h1>
+  <p>
+    Upload a FASTA reference and FASTQ file(s) from a MaP-seq experiment to
+    compute normalized reactivity profiles. Use <strong>+ Add group</strong>
+    to compare multiple conditions — normalization is applied across all
+    groups so values are directly comparable.
+  </p>
+</section>
+
+<form id="run-form" method="post" action="/run" enctype="multipart/form-data">
+  <fieldset class="card">
+    <legend>Input data</legend>
+    <label class="file-pick">
+      <span>Reference FASTA (required)</span>
+      <input type="file" name="fasta" accept=".fasta,.fa" required>
+    </label>
+    <label class="file-pick">
+      <span>Reference structure CIF (optional, single-reference FASTAs only)</span>
+      <input type="file" name="cif" accept=".cif">
+    </label>
+  </fieldset>
+
+  <fieldset class="card">
+    <legend>Experiment groups</legend>
+    <div id="groups">
+      {% include "_group_row.html" %}
+    </div>
+    <div class="row-actions">
+      <button type="button" class="secondary"
+              hx-get="/group-row"
+              hx-target="#groups"
+              hx-swap="beforeend">+ Add group</button>
+      <button type="button" class="secondary"
+              onclick="document.getElementById('example-form').submit()">Run with example data</button>
+    </div>
+  </fieldset>
+
+  <fieldset class="card">
+    <legend>Options</legend>
+
+    <details>
+      <summary>Alignment</summary>
+      <p class="hint">If no adapter sequences are provided, cmuts will attempt to recognize adapters outside the reference sequence and auto-trim.</p>
+      <div class="grid">
+        <label>5' adapter <input type="text" name="trim_5" placeholder="auto-detected if blank"></label>
+        <label>3' adapter <input type="text" name="trim_3" placeholder="auto-detected if blank"></label>
+        <label class="check"><input type="checkbox" name="local_align" value="true"> Local alignment</label>
+      </div>
+    </details>
+
+    <details>
+      <summary>Read filtering</summary>
+      <div class="grid">
+        <label>Min mapping quality <input type="number" name="min_mapq" value="10" min="0" max="60"></label>
+        <label>Min PHRED <input type="number" name="min_phred" value="10" min="0" max="40"></label>
+        <label>Min read length <input type="number" name="min_length" value="2" min="0"></label>
+        <label>Max read length <input type="number" name="max_length" value="1024" min="0"></label>
+        <label class="check"><input type="checkbox" name="no_mismatches" value="true"> Exclude mismatches</label>
+        <label>Strand
+          <select name="strand">
+            <option value="both" selected>both</option>
+            <option value="forward">forward</option>
+            <option value="reverse">reverse</option>
+          </select>
+        </label>
+      </div>
+    </details>
+
+    <details>
+      <summary>Normalization</summary>
+      <div class="grid">
+        <label>Method
+          <select name="norm_method">
+            <option value="ubr" selected>ubr</option>
+            <option value="outlier">outlier</option>
+            <option value="raw">raw</option>
+          </select>
+        </label>
+        <label class="check"><input type="checkbox" name="no_insertions" value="true" checked> Exclude insertions</label>
+        <label class="check"><input type="checkbox" name="no_deletions" value="true"> Exclude deletions</label>
+        <label class="check"><input type="checkbox" name="clip_low" value="true"> Clip negative</label>
+        <label class="check"><input type="checkbox" name="clip_high" value="true"> Clip above 1</label>
+        <label>Blank 5' bases <input type="number" name="blank_5p" value="0" min="0"></label>
+        <label>Blank 3' bases <input type="number" name="blank_3p" value="0" min="0"></label>
+        <label>Min reads / position <input type="number" name="blank_cutoff" value="10" min="0"></label>
+        <label>Min reads for norm <input type="number" name="norm_cutoff" value="500" min="0"></label>
+        <label>Norm percentile <input type="number" name="norm_percentile" value="90" min="50" max="100"></label>
+      </div>
+    </details>
+
+    <details>
+      <summary>Pairwise analysis</summary>
+      <p class="hint">O(L²) in sequence length, slow for long references.</p>
+      <label class="check"><input type="checkbox" name="compute_pairwise" value="true"> Compute pairwise correlations</label>
+      <label>Significance (Bonferroni) <input type="number" name="sig" value="0.05" min="0.001" max="0.1" step="0.001"></label>
+    </details>
+  </fieldset>
+
+  <div class="submit-row">
+    <button type="submit" class="primary">Run Pipeline</button>
+  </div>
+</form>
+
+<form id="example-form" method="post" action="/run-example" style="display:none"></form>
+
+<p class="hint">FASTQ files larger than {{ max_fastq_mb }} MB may exceed memory limits. Results persist for {{ ttl_hours }} hours.</p>
+{% endblock %}

templates/results.html

@@ -0,0 +1,153 @@
+{% extends "base.html" %}
+{% block content %}
+
+{% if status == "missing" %}
+  <section class="card">
+    <h1>Result not found</h1>
+    <p>This job ID is unknown, or the results have expired
+       (kept for {{ ttl_hours }} hours).</p>
+    <p><a href="/">Return to the form</a></p>
+  </section>
+
+{% elif status == "running" %}
+  <section class="card" id="running-card">
+    <h1>Running — job {{ job_id }}</h1>
+    <p>This page will reload automatically when the pipeline finishes.</p>
+    <details open>
+      <summary>Log</summary>
+      <pre id="live-log" class="log">{{ log }}</pre>
+    </details>
+  </section>
+  <script>
+    (function poll() {
+      const jobId = {{ job_id | tojson }};
+      fetch(`/results/${jobId}/status`).then(r => r.json()).then(s => {
+        document.getElementById('live-log').textContent = s.log || '';
+        if (s.status === 'done' || s.status === 'error') {
+          window.location.reload();
+        } else {
+          setTimeout(poll, 1500);
+        }
+      }).catch(() => setTimeout(poll, 3000));
+    })();
+  </script>
+
+{% elif status == "error" %}
+  <section class="card error">
+    <h1>Pipeline failed — job {{ job_id }}</h1>
+    <p class="error-msg">{{ error or "See log for details." }}</p>
+    <details open>
+      <summary>Log</summary>
+      <pre class="log">{{ log }}</pre>
+    </details>
+    <p><a href="/">Return to the form</a></p>
+  </section>
+
+{% else %}
+  <section class="results-header">
+    <div>
+      <h1>Results — job {{ job_id }}</h1>
+      <p class="muted">
+        Bookmark this URL to come back later
+        (kept for {{ ttl_hours }} hours).
+      </p>
+    </div>
+    <div class="header-actions">
+      <a class="button" href="/results/{{ job_id }}/download/h5">HDF5</a>
+      <a class="button" href="/results/{{ job_id }}/download/csv">CSV</a>
+      <a class="button primary" href="/results/{{ job_id }}/download/all">Download all</a>
+    </div>
+  </section>
+
+  {% if meta.has_combined_profile %}
+  <section class="card">
+    <h2>Combined reactivity profile</h2>
+    <div id="plot-combined" class="plot"></div>
+  </section>
+  {% endif %}
+
+  <section class="card">
+    <h2>Per-group diagnostics</h2>
+
+    <div class="selectors">
+      <label>Group
+        <select id="group-select">
+          {% for gn in meta.group_names %}
+            <option value="{{ gn }}">{{ gn }}</option>
+          {% endfor %}
+        </select>
+      </label>
+      <label id="seq-select-wrapper" style="display:none">Sequence
+        <select id="seq-select"></select>
+      </label>
+    </div>
+
+    <h3>Summary statistics</h3>
+    <table class="stats" id="stats-table"></table>
+
+    <div class="plot-grid">
+      <div class="plot-tile" data-key="profile">
+        <h3>Reactivity profile</h3>
+        <div class="plot"></div>
+      </div>
+      <div class="plot-tile" data-key="mod_heatmap">
+        <h3>Modification heatmap</h3>
+        <div class="plot"></div>
+      </div>
+      <div class="plot-tile" data-key="termination">
+        <h3>Termination by position</h3>
+        <div class="plot"></div>
+      </div>
+      <div class="plot-tile" data-key="coverage">
+        <h3>Coverage by position</h3>
+        <div class="plot"></div>
+      </div>
+      <div class="plot-tile" data-key="read_hist">
+        <h3>Read depth distribution</h3>
+        <div class="plot"></div>
+      </div>
+      <div class="plot-tile" data-key="cumulative_reads">
+        <h3>Cumulative reads</h3>
+        <div class="plot"></div>
+      </div>
+      <div class="plot-tile" data-key="snr_scaling">
+        <h3>SNR vs read depth</h3>
+        <div class="plot"></div>
+      </div>
+      <div class="plot-tile" data-key="mi">
+        <h3>Mutual information</h3>
+        <div class="plot"></div>
+      </div>
+      <div class="plot-tile" data-key="correlation">
+        <h3>Correlation</h3>
+        <div class="plot"></div>
+      </div>
+      <div class="plot-tile" data-key="pairwise_coverage">
+        <h3>Pairwise coverage</h3>
+        <div class="plot"></div>
+      </div>
+    </div>
+  </section>
+
+  {% if meta.chimerax_md %}
+  <section class="card">
+    <h2>Structure visualization</h2>
+    <pre class="markdown">{{ meta.chimerax_md }}</pre>
+    <div class="downloads">
+      {% for name in meta.defattr_files %}
+        <a class="button" href="/results/{{ job_id }}/download/defattr/{{ name }}">{{ name }}</a>
+      {% endfor %}
+    </div>
+  </section>
+  {% endif %}
+
+  <details class="card">
+    <summary><h2 style="display:inline">Log</h2></summary>
+    <pre class="log">{{ log }}</pre>
+  </details>
+
+  <script id="meta-data" type="application/json">{{ meta | tojson }}</script>
+  <script src="/static/results.js" defer></script>
+{% endif %}
+
+{% endblock %}