web/README.md

# OncoDSL Lab — React/Next.js front end (Stage 1 MVP)

Interactive front end for the genetic-programming engine. Talks to the
FastAPI backend over JSON + Server-Sent Events. Reuses the same DSL,
airgap harness, GP engine, and data the Streamlit viewer reads — but
shows the GP **evolving live**, with a button-gated reveal at the end.

```
┌─────────────┐    POST /runs        ┌────────────────────┐
│             │ ───────────────────▶ │  FastAPI worker    │
│  Lab page   │  GET /runs/{id}/stream│  thread runs the  │
│ (Next.js)   │ ◀─── SSE per-gen ────│  engine + permut. │
│             │  POST /evaluate      │                    │
└─────────────┘ ───────────────────▶ └────────────────────┘
```

The Lab is **client-side** (App Router `"use client"`) because it
manages SSE, sliders, and reveal state.

## Run

```bash
# 1) Backend (Python) — needs data/processed/{clinical,expression}.parquet
cd ..
source .venv/bin/activate
uvicorn api.app:app --reload          # :8000

# 2) Frontend (Node ≥ 20)
cd web
npm install
npm run dev                           # :3000
```

Open <http://localhost:3000>.

Override the API base URL with `NEXT_PUBLIC_API_URL`:

```bash
NEXT_PUBLIC_API_URL=http://localhost:8001 npm run dev
```

The Streamlit viewer (`streamlit run app/viewer.py`) is unaffected — it
still reads the persisted MSI artefacts via the legacy `/run /result /reveal`
endpoints.

## What's on the page

5 sections, top to bottom:

1. **Objective** — pick MSI separation (AUROC) or Mutation burden
   (negative correlation). Survival and Unsupervised are Stage 2.
2. **Parameters** — generations, population, genes-per-set, λ, seed,
   prefilter top-N, permutations. Sensible defaults.
3. **Run** — POST `/runs`, open SSE.
4. **Live view** — Recharts line chart of best & median fitness per
   generation, updated as events arrive; population grid showing the
   top candidates with survivors in the accent and discarded ones
   faded.
5. **Result + Reveal & evaluate** — once the GP finishes, the winning
   program's metrics show. Click "Reveal & evaluate" against a
   reference gene set (MMR or immune) to translate the opaque IDs
   back to symbols and highlight the overlap.

## What's NOT here (Stage 2 territory)

- React Flow program diagram. Animations. Free-text objective.
  Survival / unsupervised paths. Cross-cohort validation.