Redesign the MuSProt website for the new database release

New frontend (home with live hierarchical knowledge graph, browse, sequence,
chain, statistics and docs pages) and explorer API backed by the
MuSProt-index.db sidecar; supports the new schema (tm_aln, coverage,
Pfam/ECOD, observed order/disorder labels).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -37,7 +37,7 @@ Recommended Dataset repository files:
 
 ```text
 MuSProt.db
-MuSProt-node-lookup.db
+MuSProt-index.db
 musprot_summary.json
 MuSProt_documentation.md
 plots/
@@ -47,7 +47,7 @@ Optional Space variables:
 
 ```text
 MUSPROT_DB_PATH=/data/MuSProt.db
-MUSPROT_NODE_DB_PATH=/data/MuSProt-node-lookup.db
+MUSPROT_INDEX_DB_PATH=/data/MuSProt-index.db
 MUSPROT_SUMMARY_PATH=/data/musprot_summary.json
 MUSPROT_DOCS_PATH=/data/MuSProt_documentation.md
 MUSPROT_PLOTS_DIR=/data/plots
@@ -61,13 +61,18 @@ For a private Dataset repository, add `HF_TOKEN` as a Space secret.
 
 ## Updating the database
 
-When publishing a new `MuSProt.db`, regenerate the bundled summary sidecar:
+When publishing a new `MuSProt.db`, rebuild the website index sidecar
+(sequence catalog, search, state pairs, ECOD groups and dataset statistics).
+It reads the DB once and takes about 6 minutes:
 
 ```bash
-cd backend
-python scripts/generate_summary.py /path/to/MuSProt.db -o assets/musprot_summary.json
+python backend/scripts/build_index.py /path/to/MuSProt.db --out-dir <staging dir> \
+    --ecod /path/to/ecod.latest.domains.txt
 ```
 
+Upload `MuSProt.db`, `MuSProt-index.db` and `MuSProt_documentation.md` to the
+storage bucket mounted at `/data`, then restart the Space.
+
 The deployed application does not create indexes or modify the SQLite file.
 Create any required indexes before uploading the database to the Dataset
 repository.
@@ -81,6 +86,7 @@ npm run build
 
 cd ../backend
 MUSPROT_DB_PATH=/path/to/MuSProt.db \
+MUSPROT_INDEX_DB_PATH=/path/to/MuSProt-index.db \
 MUSPROT_FRONTEND_DIR=../frontend/build \
 uvicorn space_app:app --host 0.0.0.0 --port 8501
 ```

backend/app/protein/api/routes/explore.py

@@ -0,0 +1,143 @@
+"""Explorer API: overview, search, sequence catalog, sequence and chain detail."""
+from __future__ import annotations
+
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Query
+from starlette.concurrency import run_in_threadpool
+
+from app.protein import catalog, records
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+
+def _index_required(value):
+    if value is None:
+        raise HTTPException(status_code=503, detail="The MuSProt index is not available yet")
+    return value
+
+
+@router.get("/overview")
+async def get_overview():
+    """Dataset-level counts and distributions (precomputed)."""
+    return _index_required(await run_in_threadpool(catalog.overview))
+
+
+@router.get("/search")
+async def search(q: str = Query(..., min_length=1, max_length=200), limit: int = Query(12, ge=1, le=50)):
+    """Search by chain (3vgk.A), PDB entry, sequence ID, UniProt accession or function text."""
+    return await run_in_threadpool(catalog.search, q, limit)
+
+
+@router.get("/sequences")
+async def list_sequences(
+    sort: str = Query("states"),
+    order: str = Query("desc", pattern="^(asc|desc)$"),
+    q: Optional[str] = Query(None, max_length=200),
+    min_states: Optional[int] = Query(None, ge=1),
+    min_obs: Optional[int] = Query(None, ge=1),
+    method: Optional[str] = Query(None, max_length=64),
+    ligand: Optional[str] = Query(None, pattern="^(both|holo|apo)$"),
+    cath: Optional[str] = Query(None, max_length=32),
+    offset: int = Query(0, ge=0),
+    limit: int = Query(25, ge=1, le=100),
+    ids: Optional[str] = Query(None, max_length=1000, description="Comma-separated sequence IDs"),
+    ecod: Optional[str] = Query(None, max_length=200, description="ECOD H-group (e.g. 11.1) or exact H-set (11.1;2003.1)"),
+    pfam: Optional[str] = Query(None, max_length=20),
+):
+    """Browse the sequence catalog with filters, sorting and pagination."""
+    id_list = [i.strip().upper() for i in ids.split(",") if i.strip()][:100] if ids else None
+    result = await run_in_threadpool(
+        catalog.list_sequences, sort, order, q, min_states, min_obs, method, ligand, cath, offset, limit, id_list,
+        ecod, pfam,
+    )
+    return _index_required(result)
+
+
+@router.get("/sequence/{sequence_id}")
+async def get_sequence(sequence_id: str):
+    """One sequence: states, member chains and the state-state similarity matrix."""
+    seq = _index_required(await run_in_threadpool(catalog.get_sequence, sequence_id))
+    if not seq:
+        raise HTTPException(status_code=404, detail=f"Sequence {sequence_id} not found")
+    rep = await run_in_threadpool(records.get_node, seq["rep_pdb"], seq["rep_chain"])
+    if rep:
+        seq["sequence"] = rep["sequence"]
+        seq["functions"] = rep["functions"]
+        seq["cath_superfamilies"] = rep["cath_superfamilies"]
+    return seq
+
+
+@router.get("/chain/{pdb_id}/{chain_id}")
+async def get_chain(pdb_id: str, chain_id: str):
+    """Full record for one chain plus a summary of its sequence family."""
+    node = await run_in_threadpool(records.get_node, pdb_id, chain_id)
+    if node is None:
+        raise HTTPException(status_code=404, detail=f"{pdb_id.upper()}.{chain_id} is not in MuSProt")
+    node["family"] = await run_in_threadpool(catalog.sequence_summary, node["sequence_id"])
+    node["ecod_names"] = await run_in_threadpool(catalog.ecod_names, None, node["ecod_fids"])
+    return node
+
+
+@router.get("/chain/{pdb_id}/{chain_id}/transitions")
+async def get_chain_transitions(pdb_id: str, chain_id: str):
+    """Every comparison from this chain to other observations of the same sequence."""
+    node = await run_in_threadpool(records.get_node, pdb_id, chain_id)
+    if node is None:
+        raise HTTPException(status_code=404, detail=f"{pdb_id.upper()}.{chain_id} is not in MuSProt")
+    edges = await run_in_threadpool(records.get_transitions, node["pdb_id"], node["auth_asym_id"])
+    members = await run_in_threadpool(catalog.sequence_members, node["sequence_id"])
+    for e in edges:
+        m = members.get((e["pdb_id"], e["auth_asym_id"]))
+        if m:
+            e.update(
+                experimental_method=m["experimental_method"],
+                resolution=m["resolution"],
+                binding_status=m["binding_status"],
+                chain_composition=m["chain_composition"],
+                binders=m["binders"],
+                release_date=m["release_date"],
+            )
+    return {
+        "pdb_id": node["pdb_id"],
+        "auth_asym_id": node["auth_asym_id"],
+        "state_id": node["state_id"],
+        "sequence_id": node["sequence_id"],
+        "transitions": edges,
+    }
+
+
+@router.get("/graph/outer")
+async def get_outer_graph(
+    seq: str = Query(..., max_length=400, description="Comma-separated sequence IDs whose ECOD groups to show"),
+    per_group: int = Query(14, ge=2, le=40),
+):
+    """Outer layer of the knowledge graph around the given sequences (one clique per ECOD H-set)."""
+    ids = [i.strip().upper() for i in seq.split(",") if i.strip()][:12]
+    listed = _index_required(await run_in_threadpool(catalog.list_sequences, "sequence", "asc", None, None, None,
+                                                     None, None, None, 0, len(ids), ids))
+    hsets = []
+    for s_ in sorted(listed["items"], key=lambda x: ids.index(x["sequence_id"])):
+        hs = ";".join(s_["ecod_hset"])
+        if hs and hs not in hsets:
+            hsets.append(hs)
+    return await run_in_threadpool(catalog.outer_graph, hsets, per_group, ids)
+
+
+@router.get("/graph/inner/{sequence_id}")
+async def get_inner_graph(
+    sequence_id: str,
+    max_nodes: int = Query(60, ge=2, le=150),
+    max_states: int = Query(7, ge=1, le=40),
+):
+    """Inner layer for one sequence: observations of its largest states and their pairwise similarities."""
+    data = _index_required(
+        await run_in_threadpool(catalog.inner_graph_nodes, sequence_id.upper(), max_nodes, max_states)
+    )
+    if not data:
+        raise HTTPException(status_code=404, detail=f"Sequence {sequence_id} not found")
+    chains = [(n["pdb_id"], n["auth_asym_id"]) for n in data["nodes"]]
+    data["edges"] = await run_in_threadpool(records.pair_similarities, chains)
+    return data

backend/app/protein/catalog.py

@@ -0,0 +1,467 @@
+"""
+Queries against the website index sidecar (MuSProt-index.db).
+
+The sidecar is built by scripts/build_index.py and holds the sequence catalog,
+per-chain membership, state sizes, state-pair similarities and an FTS index of
+function text. Every function degrades to None / [] when the sidecar is absent,
+so chain-level pages keep working off the main DB alone.
+"""
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from functools import lru_cache
+from typing import Any, Dict, List, Optional, Tuple
+
+from app.protein.config import get_index_database_path
+from app.protein.database import connect_readonly
+
+MAX_HEATMAP_STATES = 40
+
+SORTABLE = {
+    "states": "n_states",
+    "observations": "n_obs",
+    "entries": "n_entries",
+    "length": "length",
+    "released": "last_release",
+    "sequence": "sequence_id",
+}
+
+CHAIN_RE = re.compile(r"^([0-9][A-Za-z0-9]{3})\s*[.:_\s/-]\s*([A-Za-z0-9]{1,4})$")
+PDB_RE = re.compile(r"^[0-9][A-Za-z0-9]{3}$")
+SEQ_RE = re.compile(r"^SEQ\d{1,6}$", re.IGNORECASE)
+UNIPROT_RE = re.compile(
+    r"^([OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9]([A-Z][A-Z0-9]{2}[0-9]){1,2})(-\d+)?$",
+    re.IGNORECASE,
+)
+
+
+def available() -> bool:
+    return get_index_database_path() is not None
+
+
+def _connect() -> Optional[sqlite3.Connection]:
+    path = get_index_database_path()
+    if path is None:
+        return None
+    conn = connect_readonly(path)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+@lru_cache(maxsize=1)
+def overview() -> Optional[Dict[str, Any]]:
+    conn = _connect()
+    if conn is None:
+        return None
+    try:
+        row = conn.execute("SELECT value FROM meta WHERE key = 'overview'").fetchone()
+        return json.loads(row[0]) if row else None
+    finally:
+        conn.close()
+
+
+def _sequence_dict(r: sqlite3.Row) -> Dict[str, Any]:
+    return {
+        "sequence_id": r["sequence_id"],
+        "uniprot_id": r["uniprot_id"],
+        "length": r["length"],
+        "n_obs": r["n_obs"],
+        "n_states": r["n_states"],
+        "n_entries": r["n_entries"],
+        "n_holo": r["n_holo"],
+        "n_apo": r["n_apo"],
+        "n_cross_pairs": r["n_cross_pairs"],
+        "largest_state": r["largest_state"],
+        "rep_pdb": r["rep_pdb"],
+        "rep_chain": r["rep_chain"],
+        "cath_superfamily": r["cath_superfamily"],
+        "methods": [m for m in (r["methods"] or "").split(";") if m],
+        "first_release": r["first_release"],
+        "last_release": r["last_release"],
+        "top_function": r["top_function"],
+        "ecod_hset": [h for h in (r["ecod_hset"] or "").split(";") if h],
+        "pfam_ids": [h for h in (r["pfam_ids"] or "").split(";") if h],
+    }
+
+
+def _member_dict(r: sqlite3.Row) -> Dict[str, Any]:
+    return {
+        "pdb_id": r["pdb_id"].lower(),
+        "auth_asym_id": r["auth_asym_id"],
+        "state_id": r["state_id"],
+        "uniprot_id": r["uniprot_id"],
+        "experimental_method": r["experimental_method"],
+        "resolution": r["resolution"],
+        "binding_status": r["binding_status"],
+        "chain_composition": r["chain_composition"],
+        "binders": [b for b in (r["binders"] or "").split(";") if b],
+        "release_date": r["release_date"],
+        "resolved_coverage": r["resolved_coverage"],
+        "cath_id": r["cath_id"],
+        "pfam_id": r["pfam_id"],
+        "ecod_id": r["ecod_id"],
+        "ecod_fid": r["ecod_fid"],
+    }
+
+
+def ecod_names(conn: Optional[sqlite3.Connection], f_ids: List[str] = (), h_ids: List[str] = ()) -> Dict[str, Any]:
+    """Names for ECOD family ids (x.h.t.f) and homology ids (x.h)."""
+    own = conn is None
+    conn = conn or _connect()
+    if conn is None:
+        return {"families": {}, "homologies": {}}
+    try:
+        h_all = set(h_ids) | {".".join(f.split(".")[:2]) for f in f_ids}
+        fams = {}
+        for f in f_ids:
+            r = conn.execute("SELECT t_name, f_name FROM ecod_f WHERE f_id = ?", (f,)).fetchone()
+            if r:
+                fams[f] = {"t_name": r[0], "f_name": r[1]}
+        homs = {}
+        for h in h_all:
+            r = conn.execute("SELECT architecture, x_name, h_name FROM ecod_h WHERE h_id = ?", (h,)).fetchone()
+            if r:
+                homs[h] = {"architecture": r[0], "x_name": r[1], "h_name": r[2]}
+        return {"families": fams, "homologies": homs}
+    finally:
+        if own:
+            conn.close()
+
+
+def group_info(conn: sqlite3.Connection, hset: List[str]) -> Optional[Dict[str, Any]]:
+    if not hset:
+        return None
+    r = conn.execute("SELECT * FROM ecod_group WHERE hset = ?", (";".join(hset),)).fetchone()
+    if r is None:
+        return None
+    return {
+        "hset": r["hset"].split(";"), "label": r["label"], "n_sequences": r["n_sequences"],
+        "n_obs": r["n_obs"], "n_multistate": r["n_multistate"], "n_states": r["n_states"],
+    }
+
+
+def _fts_query(q: str) -> str:
+    """Turn free text into a safe FTS5 prefix query (every term must match)."""
+    terms = re.findall(r"[A-Za-z0-9]+", q)
+    return " ".join(f'"{t}"*' for t in terms[:8])
+
+
+# ─────────────────────────────────────────────────────────── browse
+def list_sequences(
+    sort: str = "states",
+    order: str = "desc",
+    q: Optional[str] = None,
+    min_states: Optional[int] = None,
+    min_obs: Optional[int] = None,
+    method: Optional[str] = None,
+    ligand: Optional[str] = None,
+    cath: Optional[str] = None,
+    offset: int = 0,
+    limit: int = 25,
+    ids: Optional[List[str]] = None,
+    ecod: Optional[str] = None,
+    pfam: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    conn = _connect()
+    if conn is None:
+        return None
+    where: List[str] = []
+    params: List[Any] = []
+    if ids:
+        where.append(f"s.sequence_id IN ({','.join('?' * len(ids))})")
+        params.extend(ids)
+    if q and _fts_query(q):
+        where.append("s.sequence_id IN (SELECT sequence_id FROM function_fts WHERE function_fts MATCH ?)")
+        params.append(_fts_query(q))
+    if min_states:
+        where.append("s.n_states >= ?")
+        params.append(min_states)
+    if min_obs:
+        where.append("s.n_obs >= ?")
+        params.append(min_obs)
+    if method:
+        where.append("(';' || s.methods || ';') LIKE ?")
+        params.append(f"%;{method};%")
+    if ligand == "both":
+        where.append("s.n_holo > 0 AND s.n_apo > 0")
+    elif ligand == "holo":
+        where.append("s.n_holo > 0")
+    elif ligand == "apo":
+        where.append("s.n_apo > 0")
+    if cath:
+        where.append("s.cath_superfamily LIKE ?")
+        params.append(f"{cath}%")
+    if ecod:
+        # an exact H-set (outer-graph group, e.g. "11.1;2003.1") or one H-group contained in it
+        if ";" in ecod:
+            where.append("s.ecod_hset = ?")
+            params.append(ecod)
+        else:
+            where.append("(';' || s.ecod_hset || ';') LIKE ?")
+            params.append(f"%;{ecod};%")
+    if pfam:
+        where.append("(';' || s.pfam_ids || ';') LIKE ?")
+        params.append(f"%;{pfam.upper()};%")
+    where_sql = f"WHERE {' AND '.join(where)}" if where else ""
+    col = SORTABLE.get(sort, "n_states")
+    direction = "ASC" if order == "asc" else "DESC"
+    try:
+        total = conn.execute(f"SELECT COUNT(*) FROM sequence s {where_sql}", params).fetchone()[0]
+        rows = conn.execute(
+            f"SELECT s.* FROM sequence s {where_sql} "
+            f"ORDER BY s.{col} {direction} NULLS LAST, s.n_obs DESC, s.sequence_id "
+            f"LIMIT ? OFFSET ?",
+            [*params, max(1, min(limit, 100)), max(0, offset)],
+        ).fetchall()
+    finally:
+        conn.close()
+    return {"total": total, "offset": offset, "items": [_sequence_dict(r) for r in rows]}
+
+
+# ─────────────────────────────────────────────────────────── sequence detail
+def get_sequence(sequence_id: str) -> Optional[Dict[str, Any]]:
+    conn = _connect()
+    if conn is None:
+        return None
+    try:
+        row = conn.execute(
+            "SELECT * FROM sequence WHERE sequence_id = ? COLLATE NOCASE", (sequence_id,)
+        ).fetchone()
+        if row is None:
+            return {}
+        seq = _sequence_dict(row)
+        sid = seq["sequence_id"]
+        members = [
+            _member_dict(r) for r in conn.execute(
+                "SELECT * FROM member WHERE sequence_id = ? ORDER BY state_id, resolution IS NULL, resolution",
+                (sid,),
+            )
+        ]
+        states = [
+            {"state_id": r["state_id"], "n_members": r["n_members"]}
+            for r in conn.execute(
+                "SELECT state_id, n_members FROM state WHERE sequence_id = ? "
+                "ORDER BY n_members DESC, state_id",
+                (sid,),
+            )
+        ]
+        shown = {s["state_id"] for s in states[:MAX_HEATMAP_STATES]}
+        pairs = [
+            {
+                "a": r["state_a"], "b": r["state_b"], "similarity": r["similarity"],
+                "fidelity": r["fidelity"], "n_pairs": r["n_pairs"],
+            }
+            for r in conn.execute(
+                "SELECT state_a, state_b, similarity, fidelity, n_pairs FROM state_pair "
+                "WHERE sequence_id = ?",
+                (sid,),
+            )
+            if r["state_a"] in shown and r["state_b"] in shown
+        ]
+        seq["ecod_group"] = group_info(conn, seq["ecod_hset"])
+        seq["ecod_names"] = ecod_names(conn, h_ids=seq["ecod_hset"])
+    finally:
+        conn.close()
+    seq.update(states=states, members=members, state_pairs=pairs,
+               heatmap_truncated=len(states) > MAX_HEATMAP_STATES)
+    return seq
+
+
+def sequence_members(sequence_id: str) -> Dict[Tuple[str, str], Dict[str, Any]]:
+    """Map (pdb_id, chain) -> member metadata for one sequence."""
+    conn = _connect()
+    if conn is None:
+        return {}
+    try:
+        return {
+            (r["pdb_id"].lower(), r["auth_asym_id"]): _member_dict(r)
+            for r in conn.execute("SELECT * FROM member WHERE sequence_id = ?", (sequence_id,))
+        }
+    finally:
+        conn.close()
+
+
+def sequence_summary(sequence_id: str) -> Optional[Dict[str, Any]]:
+    conn = _connect()
+    if conn is None:
+        return None
+    try:
+        row = conn.execute("SELECT * FROM sequence WHERE sequence_id = ?", (sequence_id,)).fetchone()
+        states = [
+            {"state_id": r["state_id"], "n_members": r["n_members"]}
+            for r in conn.execute(
+                "SELECT state_id, n_members FROM state WHERE sequence_id = ? ORDER BY n_members DESC, state_id",
+                (sequence_id,),
+            )
+        ]
+    finally:
+        conn.close()
+    if row is None:
+        return None
+    out = _sequence_dict(row)
+    out["states"] = states
+    return out
+
+
+# ─────────────────────────────────────────────────────────── search
+def search(q: str, limit: int = 12) -> Dict[str, Any]:
+    """Classify a free-text query and return typed hits."""
+    q = q.strip()
+    if not q:
+        return {"query": q, "kind": "empty", "chains": [], "sequences": []}
+
+    m = CHAIN_RE.match(q)
+    if m:
+        from app.protein import records
+        pdb, chain = m.group(1).lower(), m.group(2)
+        node_chains = [c for c in records.list_entry_chains(pdb)]
+        exact = [c for c in node_chains if c["auth_asym_id"] == chain] or [
+            c for c in node_chains if c["auth_asym_id"].lower() == chain.lower()
+        ]
+        return {"query": q, "kind": "chain", "chains": exact, "sequences": [], "entry_chains": node_chains}
+
+    if PDB_RE.match(q) and not SEQ_RE.match(q):
+        from app.protein import records
+        chains = records.list_entry_chains(q.lower())
+        if chains:
+            return {"query": q, "kind": "entry", "chains": chains, "sequences": []}
+
+    conn = _connect()
+    if conn is None:
+        return {"query": q, "kind": "unavailable", "chains": [], "sequences": []}
+    try:
+        if SEQ_RE.match(q):
+            digits = re.sub(r"\D", "", q)
+            rows = conn.execute(
+                "SELECT * FROM sequence WHERE sequence_id = ?", (f"SEQ{int(digits):06d}",)
+            ).fetchall()
+            return {"query": q, "kind": "sequence", "chains": [], "sequences": [_sequence_dict(r) for r in rows]}
+
+        if UNIPROT_RE.match(q):
+            rows = conn.execute(
+                "SELECT * FROM sequence WHERE sequence_id IN "
+                "(SELECT DISTINCT sequence_id FROM member WHERE uniprot_id = ? COLLATE NOCASE) "
+                "ORDER BY n_obs DESC LIMIT ?",
+                (q, limit),
+            ).fetchall()
+            if not rows:
+                # multi-accession sequences store e.g. "O43318;Q15750"; the FTS column tokenises them
+                rows = conn.execute(
+                    "SELECT s.* FROM function_fts f JOIN sequence s ON s.sequence_id = f.sequence_id "
+                    "WHERE function_fts MATCH ? ORDER BY s.n_obs DESC LIMIT ?",
+                    (f'uniprot_id : "{q}"', limit),
+                ).fetchall()
+            if rows:
+                return {"query": q, "kind": "uniprot", "chains": [], "sequences": [_sequence_dict(r) for r in rows]}
+
+        fts = _fts_query(q)
+        if not fts:
+            return {"query": q, "kind": "text", "chains": [], "sequences": []}
+        rows = conn.execute(
+            "SELECT s.* FROM function_fts f JOIN sequence s ON s.sequence_id = f.sequence_id "
+            "WHERE function_fts MATCH ? ORDER BY bm25(function_fts), s.n_obs DESC LIMIT ?",
+            (fts, limit),
+        ).fetchall()
+        total = conn.execute(
+            "SELECT COUNT(*) FROM function_fts WHERE function_fts MATCH ?", (fts,)
+        ).fetchone()[0]
+        return {
+            "query": q, "kind": "text", "chains": [], "total": total,
+            "sequences": [_sequence_dict(r) for r in rows],
+        }
+    finally:
+        conn.close()
+
+
+# ─────────────────────────────────────────────────────────── knowledge graph
+def outer_graph(hsets: List[str], per_group: int = 14, include: List[str] = ()) -> Optional[Dict[str, Any]]:
+    """Outer layer: sequences grouped by identical ECOD H-set (each group is a clique)."""
+    conn = _connect()
+    if conn is None:
+        return None
+    try:
+        groups = []
+        for hs in hsets:
+            info = group_info(conn, hs.split(";"))
+            if info is None:
+                continue
+            must = [
+                _sequence_dict(r) for r in conn.execute(
+                    f"SELECT * FROM sequence WHERE ecod_hset = ? AND sequence_id IN ({','.join('?' * len(include))})",
+                    (hs, *include),
+                )
+            ] if include else []
+            rest = [
+                _sequence_dict(r) for r in conn.execute(
+                    "SELECT * FROM sequence WHERE ecod_hset = ? ORDER BY n_states DESC, n_obs DESC LIMIT ?",
+                    (hs, per_group),
+                )
+            ]
+            seen = {m["sequence_id"] for m in must}
+            members = (must + [r for r in rest if r["sequence_id"] not in seen])[:per_group]
+            groups.append({**info, "sequences": members})
+        names = ecod_names(conn, h_ids=[h for g in groups for h in g["hset"]])
+    finally:
+        conn.close()
+    return {"groups": groups, "names": names["homologies"]}
+
+
+def inner_graph_nodes(sequence_id: str, max_nodes: int = 60, max_states: int = 7) -> Optional[Dict[str, Any]]:
+    """Pick up to max_nodes observations from the sequence's max_states largest states."""
+    conn = _connect()
+    if conn is None:
+        return None
+    try:
+        row = conn.execute("SELECT * FROM sequence WHERE sequence_id = ?", (sequence_id,)).fetchone()
+        if row is None:
+            return {}
+        members = [_member_dict(r) for r in conn.execute(
+            "SELECT * FROM member WHERE sequence_id = ? ORDER BY state_id, resolution IS NULL, resolution",
+            (sequence_id,),
+        )]
+        states = [
+            {"state_id": r[0], "n_members": r[1]} for r in conn.execute(
+                "SELECT state_id, n_members FROM state WHERE sequence_id = ? ORDER BY n_members DESC, state_id",
+                (sequence_id,),
+            )
+        ]
+        pairs = [
+            {"a": r[0], "b": r[1], "similarity": r[2], "fidelity": r[3], "n_pairs": r[4]}
+            for r in conn.execute(
+                "SELECT state_a, state_b, similarity, fidelity, n_pairs FROM state_pair WHERE sequence_id = ?",
+                (sequence_id,),
+            )
+        ]
+    finally:
+        conn.close()
+
+    order = [s["state_id"] for s in states[:max_states]]
+    pool = [m for m in members if m["state_id"] in set(order)]
+    if len(pool) <= max_nodes:
+        chosen = pool
+    else:
+        # round-robin across the kept states (largest first) so smaller states still appear
+        by_state: Dict[int, List[Dict[str, Any]]] = {}
+        for m in pool:
+            by_state.setdefault(m["state_id"], []).append(m)
+        chosen, depth = [], 0
+        while len(chosen) < max_nodes:
+            added = False
+            for st in order:
+                bucket = by_state.get(st, [])
+                if depth < len(bucket) and len(chosen) < max_nodes:
+                    chosen.append(bucket[depth])
+                    added = True
+            if not added:
+                break
+            depth += 1
+    shown_states = {s["state_id"] for s in states[:MAX_HEATMAP_STATES]}
+    return {
+        "sequence": _sequence_dict(row),
+        "nodes": chosen,
+        "n_total": len(members),
+        "states": states,
+        "state_pairs": [p for p in pairs if p["a"] in shown_states and p["b"] in shown_states],
+    }

backend/app/protein/config.py

@@ -66,18 +66,18 @@ def get_summary_path() -> Path | None:
     )
 
 
-def get_node_database_path() -> Path:
-    """Return an optional indexed node lookup sidecar, falling back to the main DB."""
-    explicit_path = os.getenv("MUSPROT_NODE_DB_PATH")
+def get_index_database_path() -> Path | None:
+    """Return the website index sidecar (built by scripts/build_index.py), if present."""
+    explicit_path = os.getenv("MUSPROT_INDEX_DB_PATH")
     if explicit_path:
         path = Path(explicit_path).expanduser().resolve()
-        if path.exists():
-            return path
+        return path if path.exists() else None
 
-    return (
-        _existing_path(DEFAULT_VOLUME_DIR / "MuSProt-node-lookup.db")
-        or get_database_path()
-    ).resolve()
+    return _existing_path(
+        DEFAULT_VOLUME_DIR / "MuSProt-index.db",
+        ASSETS_DIR / "MuSProt-index.db",
+        LOCAL_DATA_DIR / "MuSProt-index.db",
+    )
 
 
 def get_docs_path() -> Path | None:

backend/app/protein/data_loader.py

@@ -44,6 +44,13 @@ class DataManager:
         if summary_path:
             self._summary = json.loads(summary_path.read_text(encoding="utf-8"))
             self._total_records = int(self._summary.get("total_records", 0))
+        from app.protein import catalog
+        overview = catalog.overview()
+        if overview:
+            # the index is rebuilt with every DB release, so its count wins over a stale summary
+            self._total_records = int(overview["counts"]["transitions"])
+            if self._summary:
+                self._summary["total_records"] = self._total_records
 
         conn = connect_readonly(self.db_path)
         try:
@@ -100,7 +107,7 @@ class DataManager:
         try:
             cur = conn.cursor()
             cur.execute(
-                "SELECT MIN(CAST(TM1 AS REAL)), MAX(CAST(TM1 AS REAL)),"
+                "SELECT MIN(CAST(tm_aln AS REAL)), MAX(CAST(tm_aln AS REAL)),"
                 "       MIN(CAST(RMSD AS REAL)), MAX(CAST(RMSD AS REAL))"
                 " FROM edge"
             )
@@ -161,16 +168,16 @@ class DataManager:
             where_clauses.append("CAST(RMSD AS REAL) <= ?")
             params.append(rmsd_max)
         if tm_min is not None:
-            where_clauses.append("CAST(TM1 AS REAL) >= ?")
+            where_clauses.append("CAST(tm_aln AS REAL) >= ?")
             params.append(tm_min)
         if tm_max is not None:
-            where_clauses.append("CAST(TM1 AS REAL) <= ?")
+            where_clauses.append("CAST(tm_aln AS REAL) <= ?")
             params.append(tm_max)
 
         where_sql = ("WHERE " + " AND ".join(where_clauses)) if where_clauses else ""
         sql = f"""
             SELECT e.pdb_id_A, e.auth_asym_id_A, e.pdb_id_B, e.auth_asym_id_B,
-                   CAST(e.TM1 AS REAL) AS TM1,
+                   CAST(e.tm_aln AS REAL) AS TM1,
                    CAST(e.RMSD AS REAL) AS RMSD,
                    CAST(e.pair_similarity AS REAL) AS structure_sim,
                    e."delta_Rosetta", e."delta_FoldX", e."delta_EvoEF2",
@@ -249,10 +256,10 @@ class DataManager:
             where_clauses.append("CAST(RMSD AS REAL) <= ?")
             params.append(rmsd_max)
         if tm_min is not None:
-            where_clauses.append("CAST(TM1 AS REAL) >= ?")
+            where_clauses.append("CAST(tm_aln AS REAL) >= ?")
             params.append(tm_min)
         if tm_max is not None:
-            where_clauses.append("CAST(TM1 AS REAL) <= ?")
+            where_clauses.append("CAST(tm_aln AS REAL) <= ?")
             params.append(tm_max)
 
         where_sql = ("WHERE " + " AND ".join(where_clauses)) if where_clauses else ""
@@ -261,7 +268,7 @@ class DataManager:
         try:
             cur = conn.cursor()
             cur.execute(
-                f"SELECT COUNT(*), AVG(CAST(RMSD AS REAL)), AVG(CAST(TM1 AS REAL))"
+                f"SELECT COUNT(*), AVG(CAST(RMSD AS REAL)), AVG(CAST(tm_aln AS REAL))"
                 f" FROM edge {where_sql}",
                 params,
             )
@@ -292,7 +299,7 @@ class DataManager:
                 ["0-0.5", "0.5-1.0", "1.0-1.5", "1.5-2.0", "2.0-5.0", ">5.0"],
             )
             tm_dist = _dist(
-                "TM1",
+                "tm_aln",
                 [0, 0.5, 0.7, 0.85, 0.95, 1.01],
                 ["0-0.5", "0.5-0.7", "0.7-0.85", "0.85-0.95", "0.95-1.0"],
             )

backend/app/protein/models.py

@@ -1,144 +1,144 @@
-"""
-Data models for the protein visualization API.
-"""
-from typing import Optional, List, Dict, Any
-from pydantic import BaseModel, Field
-
-
-class CrystalGrow(BaseModel):
-    """Crystal growth conditions."""
-    pH: Optional[float] = None
-    pH_structured: Optional[float] = None
-    pH_from_details: Optional[float] = None
-    temp: Optional[float] = None
-    pdbx_details: Optional[str] = None
-
-
-class EntryInfo(BaseModel):
-    """Entry-level information."""
-    rcsb_id: Optional[str] = None
-    title: Optional[str] = None
-    initial_release_date: Optional[str] = None
-    exptl_method: Optional[str] = None
-    resolution_combined: Optional[List[float]] = None
-    crystal_grow: Optional[CrystalGrow] = None
-
-
-class PolymerEntity(BaseModel):
-    """Polymer entity (sequence-level) information."""
-    rcsb_id: Optional[str] = None
-    entity_id: Optional[str] = None
-    sequence_length: Optional[int] = None
-    seq_can: Optional[str] = None
-    reference_sequences: Optional[List[Dict[str, str]]] = None
-
-
-class PolymerEntityInstance(BaseModel):
-    """Polymer entity instance (chain-level) information."""
-    rcsb_id: Optional[str] = None
-    asym_id: Optional[str] = None
-    auth_asym_id: Optional[str] = None
-    binding_affinity: Optional[Any] = None
-
-
-class NonpolymerEntity(BaseModel):
-    """Nonpolymer entity (ligand/binder) information."""
-    rcsb_id: Optional[str] = None
-    name: Optional[str] = None
-    formula_weight: Optional[float] = None
-    smiles: Optional[str] = None
-    inchi: Optional[str] = None
-
-
-class ChainMetadata(BaseModel):
-    """Complete chain metadata from RCSB."""
-    pdb_id: str
-    chain_id: str
-    entry: EntryInfo
-    polymer_entity: Optional[PolymerEntity] = None
-    polymer_entity_instance: Optional[PolymerEntityInstance] = None
-    nonpolymer_entities: Optional[List[NonpolymerEntity]] = None
-    binding_status: Optional[str] = None
-    chain_composition: Optional[str] = None
-    cath_id: Optional[str] = None
-    cath_superfamily: Optional[str] = None
-    state_id: Optional[str] = None
-
-
-class FilterParams(BaseModel):
-    """Request model for filtering protein data."""
-    chain_ids: Optional[List[str]] = Field(default=None, description="List of chain IDs to filter")
-    pdb_id: Optional[str] = Field(default=None, description="PDB ID for single chain search")
-    auth_asym_id: Optional[str] = Field(default=None, description="Chain ID for single chain search")
-    rmsd_min: Optional[float] = Field(default=None, ge=0, description="Minimum RMSD value")
-    rmsd_max: Optional[float] = Field(default=None, ge=0, description="Maximum RMSD value")
-    tm_score_min: Optional[float] = Field(default=None, ge=0, le=1, description="Minimum TM-score")
-    tm_score_max: Optional[float] = Field(default=None, ge=0, le=1, description="Maximum TM-score")
-    length_min: Optional[int] = Field(default=None, ge=0, description="Minimum sequence length")
-    length_max: Optional[int] = Field(default=None, ge=0, description="Maximum sequence length")
-    include_duplicates: Optional[bool] = Field(default=None, description="Include duplicate structures")
-    cluster_id: Optional[str] = Field(default=None, description="Structural similarity cluster ID")
-    limit: Optional[int] = Field(default=1000, ge=1, le=10000, description="Maximum results to return")
-
-
-class FilterOptions(BaseModel):
-    """Available filter options and ranges."""
-    chain_ids: List[str] = Field(description="Available chain IDs")
-    rmsd_range: Dict[str, float] = Field(description="Min and max RMSD values")
-    tm_score_range: Dict[str, float] = Field(description="Min and max TM-score values")
-    length_range: Dict[str, int] = Field(description="Min and max sequence lengths")
-    clusters: List[str] = Field(description="Available similarity clusters")
-    total_records: int = Field(description="Total number of records")
-
-
-class DataRecord(BaseModel):
-    """Single protein comparison record."""
-    pdb_id_a: str
-    auth_asym_id_a: str
-    pdb_id_b: str
-    auth_asym_id_b: str
-    tm_score: float
-    rmsd: float
-    structure_sim: Optional[float] = None
-    sequence_identity: Optional[float] = None
-    length_a: Optional[int] = None
-    length_b: Optional[int] = None
-    aligned_length: Optional[int] = None
-    status: Optional[str] = None
-    cluster_id: Optional[str] = None
-    exptl_method: Optional[str] = None
-    temp: Optional[float] = None
-    pH: Optional[float] = None
-    # Matched-chain (B) annotations from the node table
-    binding_status: Optional[str] = None
-    chain_composition: Optional[str] = None
-    # Energy score deltas fetched directly from the edge table
-    delta_rosetta: Optional[float] = None
-    delta_foldx: Optional[float] = None
-    delta_evoef2: Optional[float] = None
-    delta_rw: Optional[float] = None
-    delta_rw_plus: Optional[float] = None
-    # Alternative state similarity fields from edge table
-    state_id_b: Optional[str] = None
-    state_fidelity: Optional[str] = None
-    avg_sim: Optional[str] = None
-    observation_fidelity: Optional[str] = None
-
-
-class DataResponse(BaseModel):
-    """Response model for filtered data."""
-    data: List[DataRecord]
-    total: int
-    filtered: int
-
-
-class SummaryStats(BaseModel):
-    """Aggregate statistics for the dataset."""
-    total_records: int
-    unique_chains: int
-    avg_rmsd: float
-    avg_tm_score: float
-    avg_sequence_length: float
-    rmsd_distribution: Dict[str, int]
-    tm_score_distribution: Dict[str, int]
-    length_distribution: Dict[str, int]
+"""
+Data models for the protein visualization API.
+"""
+from typing import Optional, List, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class CrystalGrow(BaseModel):
+    """Crystal growth conditions."""
+    pH: Optional[float] = None
+    pH_structured: Optional[float] = None
+    pH_from_details: Optional[float] = None
+    temp: Optional[float] = None
+    pdbx_details: Optional[str] = None
+
+
+class EntryInfo(BaseModel):
+    """Entry-level information."""
+    rcsb_id: Optional[str] = None
+    title: Optional[str] = None
+    initial_release_date: Optional[str] = None
+    exptl_method: Optional[str] = None
+    resolution_combined: Optional[List[float]] = None
+    crystal_grow: Optional[CrystalGrow] = None
+
+
+class PolymerEntity(BaseModel):
+    """Polymer entity (sequence-level) information."""
+    rcsb_id: Optional[str] = None
+    entity_id: Optional[str] = None
+    sequence_length: Optional[int] = None
+    seq_can: Optional[str] = None
+    reference_sequences: Optional[List[Dict[str, str]]] = None
+
+
+class PolymerEntityInstance(BaseModel):
+    """Polymer entity instance (chain-level) information."""
+    rcsb_id: Optional[str] = None
+    asym_id: Optional[str] = None
+    auth_asym_id: Optional[str] = None
+    binding_affinity: Optional[Any] = None
+
+
+class NonpolymerEntity(BaseModel):
+    """Nonpolymer entity (ligand/binder) information."""
+    rcsb_id: Optional[str] = None
+    name: Optional[str] = None
+    formula_weight: Optional[float] = None
+    smiles: Optional[str] = None
+    inchi: Optional[str] = None
+
+
+class ChainMetadata(BaseModel):
+    """Complete chain metadata from RCSB."""
+    pdb_id: str
+    chain_id: str
+    entry: EntryInfo
+    polymer_entity: Optional[PolymerEntity] = None
+    polymer_entity_instance: Optional[PolymerEntityInstance] = None
+    nonpolymer_entities: Optional[List[NonpolymerEntity]] = None
+    binding_status: Optional[str] = None
+    chain_composition: Optional[str] = None
+    cath_id: Optional[str] = None
+    cath_superfamily: Optional[str] = None
+    state_id: Optional[str] = None
+
+
+class FilterParams(BaseModel):
+    """Request model for filtering protein data."""
+    chain_ids: Optional[List[str]] = Field(default=None, description="List of chain IDs to filter")
+    pdb_id: Optional[str] = Field(default=None, description="PDB ID for single chain search")
+    auth_asym_id: Optional[str] = Field(default=None, description="Chain ID for single chain search")
+    rmsd_min: Optional[float] = Field(default=None, ge=0, description="Minimum RMSD value")
+    rmsd_max: Optional[float] = Field(default=None, ge=0, description="Maximum RMSD value")
+    tm_score_min: Optional[float] = Field(default=None, ge=0, le=1, description="Minimum TM-score")
+    tm_score_max: Optional[float] = Field(default=None, ge=0, le=1, description="Maximum TM-score")
+    length_min: Optional[int] = Field(default=None, ge=0, description="Minimum sequence length")
+    length_max: Optional[int] = Field(default=None, ge=0, description="Maximum sequence length")
+    include_duplicates: Optional[bool] = Field(default=None, description="Include duplicate structures")
+    cluster_id: Optional[str] = Field(default=None, description="Structural similarity cluster ID")
+    limit: Optional[int] = Field(default=1000, ge=1, le=10000, description="Maximum results to return")
+
+
+class FilterOptions(BaseModel):
+    """Available filter options and ranges."""
+    chain_ids: List[str] = Field(description="Available chain IDs")
+    rmsd_range: Dict[str, float] = Field(description="Min and max RMSD values")
+    tm_score_range: Dict[str, float] = Field(description="Min and max TM-score values")
+    length_range: Dict[str, int] = Field(description="Min and max sequence lengths")
+    clusters: List[str] = Field(description="Available similarity clusters")
+    total_records: int = Field(description="Total number of records")
+
+
+class DataRecord(BaseModel):
+    """Single protein comparison record."""
+    pdb_id_a: str
+    auth_asym_id_a: str
+    pdb_id_b: str
+    auth_asym_id_b: str
+    tm_score: float
+    rmsd: float
+    structure_sim: Optional[float] = None
+    sequence_identity: Optional[float] = None
+    length_a: Optional[int] = None
+    length_b: Optional[int] = None
+    aligned_length: Optional[int] = None
+    status: Optional[str] = None
+    cluster_id: Optional[str] = None
+    exptl_method: Optional[str] = None
+    temp: Optional[float] = None
+    pH: Optional[float] = None
+    # Matched-chain (B) annotations from the node table
+    binding_status: Optional[str] = None
+    chain_composition: Optional[str] = None
+    # Energy score deltas fetched directly from the edge table
+    delta_rosetta: Optional[float] = None
+    delta_foldx: Optional[float] = None
+    delta_evoef2: Optional[float] = None
+    delta_rw: Optional[float] = None
+    delta_rw_plus: Optional[float] = None
+    # Alternative state similarity fields from edge table
+    state_id_b: Optional[str] = None
+    state_fidelity: Optional[str] = None
+    avg_sim: Optional[str] = None
+    observation_fidelity: Optional[str] = None
+
+
+class DataResponse(BaseModel):
+    """Response model for filtered data."""
+    data: List[DataRecord]
+    total: int
+    filtered: int
+
+
+class SummaryStats(BaseModel):
+    """Aggregate statistics for the dataset."""
+    total_records: int
+    unique_chains: int
+    avg_rmsd: float
+    avg_tm_score: float
+    avg_sequence_length: float
+    rmsd_distribution: Dict[str, int]
+    tm_score_distribution: Dict[str, int]
+    length_distribution: Dict[str, int]

backend/app/protein/records.py

@@ -0,0 +1,270 @@
+"""
+Per-chain reads from the main MuSProt.db.
+
+Both tables carry a (pdb_id COLLATE NOCASE, chain) index, so every query here
+is a single index seek. pdb_id is case-insensitive; chain ids are case-sensitive
+(`d` and `D` are different chains), with a case-insensitive fallback for
+convenience when the exact chain does not exist.
+"""
+from __future__ import annotations
+
+import json
+import math
+import sqlite3
+from typing import Any, Dict, List, Optional
+
+from app.protein.config import get_database_path
+from app.protein.database import connect_readonly
+
+ENERGY_TERMS = ["Rosetta", "FoldX", "EvoEF2", "RW", "RW+"]
+
+EDGE_COLUMNS = [
+    "pdb_id_B", "auth_asym_id_B", "tm_aln", "RMSD", "coverage", "pair_similarity",
+    "delta_Rosetta", "delta_FoldX", "delta_EvoEF2", "delta_RW", "delta_RW+",
+    "state_id_B", "state_similarity", "state_fidelity", "pair_fidelity",
+    "n_shared_resolved", "delta_order_valid", "order_invalid_reason", "n_ordered", "n_disordered",
+    "ordered_ranges", "disordered_ranges", "longest_ordered_segment", "longest_disordered_segment",
+    "n_terminal_ordered", "n_internal_ordered", "order_evidence", "ordering_with_ligand_change",
+]
+
+
+def _connect() -> sqlite3.Connection:
+    conn = connect_readonly(get_database_path())
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def num(value: Any) -> Optional[float]:
+    if value is None or value == "":
+        return None
+    try:
+        f = float(value)
+    except (TypeError, ValueError):
+        return None
+    return None if math.isnan(f) or math.isinf(f) else f
+
+
+def integer(value: Any) -> Optional[int]:
+    f = num(value)
+    return None if f is None else int(f)
+
+
+def text(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    s = str(value).strip()
+    return None if s in ("", "None", "nan", "<NA>") else s
+
+
+def _parse_list(raw: Any) -> List[Any]:
+    raw = (raw or "").strip() if isinstance(raw, str) else raw
+    if not raw:
+        return []
+    try:
+        val = json.loads(raw)
+    except ValueError:
+        import ast
+        try:
+            val = ast.literal_eval(raw)
+        except (ValueError, SyntaxError):
+            return [s.strip() for s in str(raw).split(";") if s.strip()]
+    return val if isinstance(val, list) else []
+
+
+def _parse_ranges(raw: Optional[str]) -> List[List[int]]:
+    """'5-173,187-353,400' -> [[5, 173], [187, 353], [400, 400]] (1-based, inclusive)."""
+    out = []
+    for part in (raw or "").split(","):
+        bounds = part.strip().split("-")
+        if len(bounds) == 2 and bounds[0].isdigit() and bounds[1].isdigit():
+            out.append([int(bounds[0]), int(bounds[1])])
+        elif len(bounds) == 1 and bounds[0].isdigit():
+            out.append([int(bounds[0]), int(bounds[0])])
+    return out
+
+
+def _split(raw: Any) -> List[str]:
+    return [x for x in (text(raw) or "").split(";") if x]
+
+
+def _flag(raw: Any) -> Optional[bool]:
+    t = text(raw)
+    return None if t is None else t == "True"
+
+
+def resolve_chain_key(conn: sqlite3.Connection, pdb_id: str, chain: str) -> Optional[str]:
+    """Return the stored chain id for (pdb_id, chain), preferring an exact match."""
+    row = conn.execute(
+        "SELECT auth_asym_id FROM node WHERE pdb_id = ? COLLATE NOCASE AND auth_asym_id = ? LIMIT 1",
+        (pdb_id, chain),
+    ).fetchone()
+    if row:
+        return row[0]
+    candidates = [
+        r[0] for r in conn.execute(
+            "SELECT auth_asym_id FROM node WHERE pdb_id = ? COLLATE NOCASE", (pdb_id,)
+        )
+    ]
+    for c in candidates:
+        if c.lower() == chain.lower():
+            return c
+    return None
+
+
+def get_node(pdb_id: str, chain: str) -> Optional[Dict[str, Any]]:
+    """Full, parsed node record for one chain, or None when absent."""
+    conn = _connect()
+    try:
+        stored = resolve_chain_key(conn, pdb_id, chain)
+        if stored is None:
+            return None
+        r = conn.execute(
+            "SELECT * FROM node WHERE pdb_id = ? COLLATE NOCASE AND auth_asym_id = ? LIMIT 1",
+            (pdb_id, stored),
+        ).fetchone()
+    finally:
+        conn.close()
+
+    functions = [str(f).strip() for f in _parse_list(r["ranked_functions"])]
+    scores = _parse_list(r["matching_scores"])
+    ranked = []
+    for i, name in enumerate(functions):
+        if len(name) <= 10:
+            continue
+        ranked.append({"function": name, "score": num(scores[i]) if i < len(scores) else None})
+
+    return {
+        "pdb_id": r["pdb_id"].lower(),
+        "auth_asym_id": r["auth_asym_id"],
+        "sequence_id": r["sequence_id"],
+        "uniprot_id": text(r["uniprot_id"]),
+        "state_id": integer(r["state_id"]),
+        "sequence": text(r["sequence"]) or "",
+        "sequence_length": integer(r["sequence_length"]),
+        "modeled_sequence_length": integer(r["modeled_sequence_length"]),
+        "resolved_ranges": _parse_ranges(r["resolved_label_seq"]),
+        "n_resolved_aa": integer(r["n_resolved_aa"]),
+        "resolved_coverage": num(r["resolved_coverage"]),
+        "binders": [b for b in (text(r["binders"]) or "").split(";") if b],
+        "binding_status": text(r["binding_status"]),
+        "experimental_method": text(r["experimental_method"]),
+        "resolution": num(r["resolution"]),
+        "pH": num(r["pH"]),
+        "temp_K": num(r["temp_K"]),
+        "experimental_details": text(r["experimental_details"]),
+        "chain_composition": text(r["chain_composition"]),
+        "nucleic_acid_binding": text(r["non_protein_polymer_binding"]),
+        "release_date": text(r["initial_release_date"]),
+        "cath_domains": _split(r["cath_id"]),
+        "cath_superfamilies": _split(r["cath_superfamily"]),
+        "pfam_ids": _split(r["pfam_id"]),
+        "ecod_domains": _split(r["ecod_id"]),
+        "ecod_fids": _split(r["ecod_fid"]),
+        "energies": {term: num(r[term]) for term in ENERGY_TERMS},
+        "scoring": {
+            "n_seqres": integer(r["n_seqres"]),
+            "n_scored": integer(r["n_scored"]),
+            "scored_coverage": num(r["scored_coverage"]),
+            "foldx_n_scored": integer(r["foldx_n_scored"]),
+            "foldx_coverage": num(r["foldx_coverage"]),
+        },
+        "functions": ranked,
+    }
+
+
+def get_transitions(pdb_id: str, chain: str, limit: int = 20000) -> List[Dict[str, Any]]:
+    """All directed edges leaving one chain (A = the given chain)."""
+    cols = ", ".join(f'"{c}"' for c in EDGE_COLUMNS)
+    conn = _connect()
+    try:
+        stored = resolve_chain_key(conn, pdb_id, chain) or chain
+        rows = conn.execute(
+            f"SELECT {cols} FROM edge WHERE pdb_id_A = ? COLLATE NOCASE AND auth_asym_id_A = ? LIMIT ?",
+            (pdb_id, stored, limit),
+        ).fetchall()
+    finally:
+        conn.close()
+
+    out = []
+    for r in rows:
+        sim = num(r["pair_similarity"])
+        out.append({
+            "pdb_id": r["pdb_id_B"].lower(),
+            "auth_asym_id": r["auth_asym_id_B"],
+            "state_id": integer(r["state_id_B"]),
+            "tm_aln": num(r["tm_aln"]),
+            # no shared residues: RMSD/coverage are stored as 0.0 but are really undefined
+            "rmsd": num(r["RMSD"]) if sim is not None else None,
+            "coverage": num(r["coverage"]) if sim is not None else None,
+            "similarity": sim,
+            "fidelity": text(r["pair_fidelity"]),
+            "state_similarity": num(r["state_similarity"]),
+            "state_fidelity": text(r["state_fidelity"]),
+            "delta": {
+                "Rosetta": num(r["delta_Rosetta"]),
+                "FoldX": num(r["delta_FoldX"]),
+                "EvoEF2": num(r["delta_EvoEF2"]),
+                "RW": num(r["delta_RW"]),
+                "RW+": num(r["delta_RW+"]),
+            },
+            "order": {
+                "valid": _flag(r["delta_order_valid"]),
+                "reason": text(r["order_invalid_reason"]),
+                "n_shared_resolved": integer(r["n_shared_resolved"]),
+                "n_ordered": integer(r["n_ordered"]),
+                "n_disordered": integer(r["n_disordered"]),
+                "ordered_ranges": _parse_ranges(r["ordered_ranges"]),
+                "disordered_ranges": _parse_ranges(r["disordered_ranges"]),
+                "longest_ordered": integer(r["longest_ordered_segment"]),
+                "longest_disordered": integer(r["longest_disordered_segment"]),
+                "n_terminal_ordered": integer(r["n_terminal_ordered"]),
+                "n_internal_ordered": integer(r["n_internal_ordered"]),
+                "evidence": text(r["order_evidence"]),
+                "with_ligand_change": _flag(r["ordering_with_ligand_change"]),
+            },
+        })
+    return out
+
+
+def pair_similarities(chains: List[tuple]) -> List[Dict[str, Any]]:
+    """Undirected similarity edges among a set of (pdb_id, chain) observations of one sequence."""
+    keep = {(p.lower(), c): i for i, (p, c) in enumerate(chains)}
+    out = []
+    conn = _connect()
+    try:
+        for i, (pdb, chain) in enumerate(chains):
+            for r in conn.execute(
+                "SELECT pdb_id_B, auth_asym_id_B, pair_similarity, pair_fidelity FROM edge "
+                "WHERE pdb_id_A = ? COLLATE NOCASE AND auth_asym_id_A = ?",
+                (pdb, chain),
+            ):
+                j = keep.get((r[0].lower(), r[1]))
+                if j is not None and j > i:
+                    out.append({"s": i, "t": j, "sim": num(r[2]), "fid": text(r[3])})
+    finally:
+        conn.close()
+    return out
+
+
+def list_entry_chains(pdb_id: str) -> List[Dict[str, Any]]:
+    """Chains of one PDB entry present in MuSProt (lightweight columns only)."""
+    conn = _connect()
+    try:
+        rows = conn.execute(
+            "SELECT pdb_id, auth_asym_id, sequence_id, uniprot_id, state_id, sequence_length "
+            "FROM node WHERE pdb_id = ? COLLATE NOCASE",
+            (pdb_id,),
+        ).fetchall()
+    finally:
+        conn.close()
+    return [
+        {
+            "pdb_id": r["pdb_id"].lower(),
+            "auth_asym_id": r["auth_asym_id"],
+            "sequence_id": r["sequence_id"],
+            "uniprot_id": text(r["uniprot_id"]),
+            "state_id": integer(r["state_id"]),
+            "sequence_length": integer(r["sequence_length"]),
+        }
+        for r in rows
+    ]

backend/app/protein/tsv_loader.py

@@ -8,11 +8,10 @@ key the first occurrence is kept.
 import ast
 import sqlite3
 import logging
-import zlib
 from functools import lru_cache
 from typing import Dict, List, Optional, Tuple, Any
 
-from app.protein.config import get_database_path, get_node_database_path
+from app.protein.config import get_database_path
 from app.protein.database import connect_readonly
 
 logger = logging.getLogger(__name__)
@@ -83,23 +82,25 @@ def reset_index() -> None:
 
 @lru_cache(maxsize=4096)
 def _lookup_node_row(pdb_id: str, auth_asym_id: str) -> Optional[_Row]:
-    """Read one node row without blocking on a full-table in-memory index."""
-    conn = connect_readonly(get_node_database_path())
+    """Read one node row via the (pdb_id COLLATE NOCASE, auth_asym_id) index."""
+    from app.protein.records import resolve_chain_key
+
+    conn = connect_readonly(get_database_path())
     try:
         conn.row_factory = sqlite3.Row
+        stored = resolve_chain_key(conn, pdb_id, auth_asym_id)
+        if stored is None:
+            return None
         row = conn.execute(
             'SELECT binding_status, sequence, sequence_length, cath_id, cath_superfamily,'
             '       Rosetta, FoldX, EvoEF2, RW, "RW+", ranked_functions,'
             '       state_id, experimental_method, pH, temp_K, chain_composition, matching_scores'
-            ' FROM node WHERE LOWER(pdb_id) = ? AND UPPER(auth_asym_id) = ? LIMIT 1',
-            (pdb_id.lower(), auth_asym_id.upper()),
+            ' FROM node WHERE pdb_id = ? COLLATE NOCASE AND auth_asym_id = ? LIMIT 1',
+            (pdb_id, stored),
         ).fetchone()
         if row is None:
             return None
-        return {
-            key: zlib.decompress(value).decode("utf-8") if isinstance(value, bytes) else value or ""
-            for key, value in ((key, row[key]) for key in row.keys())
-        }
+        return {key: row[key] or "" for key in row.keys()}
     finally:
         conn.close()
 

backend/assets/MuSProt_documentation.md

@@ -1,91 +1,192 @@
 # MuSProt Dataset Documentation
 
-**MuSProt** (Multistate Protein Database) is a million-scale multimodal database for multistate proteins, designed to support programmable protein design and AI model development. It links experimentally observed conformational states of identical protein sequences from the PDB, organizes them into state clusters and transition relationships, and enriches each record with structural similarity, experimental context, state-specific function rankings and transition fidelity labels. Users can search, browse and download MuSProt records to study conformational diversity, state-dependent functions and feasible protein state transitions.
+**MuSProt** (Multistate Protein Database) is a million-scale multimodal database for multistate proteins, designed to support programmable protein design and AI model development. It links experimentally observed conformational states of identical protein sequences from the PDB, organizes them into state clusters and transition relationships, and enriches each record with structural similarity, experimental context, state-specific function rankings and transition fidelity labels.
 
 ---
 
-## Download
+## At a glance
+
+| | Count |
+|---|---|
+| Conformational observations (`node` rows, one per PDB chain) | 863,643 |
+| Sequences (identical SEQRES observed ≥ 2 times) | 102,790 |
+| Sequences with ≥ 2 conformational states | 24,673 |
+| State clusters | 162,601 |
+| Transition triplets (`edge` rows, ordered observation pairs) | 113,663,858 |
+| Transitions between distinct states | 25,568,258 |
+
+---
+
+## Concepts
+
+### Observation
+
+One protein chain (`pdb_id`, `auth_asym_id`) in one PDB entry. Observations whose full deposited sequence (SEQRES) is 100% identical share a `sequence_id`. Only sequences observed at least twice are included.
+
+### State cluster
+
+Within each sequence, two observations are linked when their **pair similarity is ≥ 0.95**. The connected components of that graph are the conformational states, numbered `0, 1, 2, …` per sequence (`state_id`).
+
+### Transition
+
+Every ordered pair (A → B) of observations of the same sequence is an `edge` row. Both directions are stored; they share all structural fields and differ only in the sign of the energy differences (B − A).
+
+### Structural similarity
+
+Pairs are superposed with US-align on a fixed residue correspondence (identical SEQRES numbering), and similarity is computed over the aligned core so that disordered or unmodelled termini do not penalise otherwise identical conformations:
+
+```
+tm_aln          = (TM_A · L_A + TM_B · L_B) / (2 · aligned_length)
+pair_similarity = 0.8 · tm_aln + 0.2 · exp(−(RMSD / 5 Å)²)
+coverage        = aligned_length / max(L_A, L_B)
+```
 
-The full dataset is distributed as a single SQLite database file (`MuSProt.db`, ~31 GB). Download it from the dataset page using the **Download DB** button.
+`coverage` is reported separately as the completeness axis.
 
-For detailed protein structures and atom coordinates, users are expected to download [Protein Data Bank (PDB)](https://rcsb.org) and fetch from `mmCIF` or `.pdb` files based on the PDB entry and chain ID.
+### Fidelity labels
+
+`pair_fidelity` (from `pair_similarity`) and `state_fidelity` (from `state_similarity`) bin how far a transition moves:
+
+| Label | Similarity | Meaning |
+|---|---|---|
+| `identical` | ≥ 0.95 | Same conformation |
+| `low` | 0.70 – 0.95 | Subtle rearrangement |
+| `medium` | 0.50 – 0.70 | Clear conformational change |
+| `high` | ≤ 0.50 | Large-scale transition |
+| empty | — | Not computable (the two chains share no resolved residues) |
 
 ---
 
-## Database Schema
+## Download
+
+The full dataset is a single SQLite database file (`MuSProt.db`, ~37 GB) with two tables, **`node`** and **`edge`**. Download it with the **Download** button at the top of the site.
 
-The database contains two tables: **`node`** and **`edge`**.
+Atomic coordinates are not included: fetch mmCIF files from the [RCSB PDB](https://www.rcsb.org) or [PDBe](https://www.ebi.ac.uk/pdbe/) using `pdb_id` and `auth_asym_id`.
 
 ---
 
+## Database Schema
+
 ### Table: `node`
 
-Each row represents a single protein chain instance (one PDB entry + chain).
+One row per observation (PDB chain).
 
 | Column | Type | Description |
 |---|---|---|
-| `sequence_id` | TEXT | Internal sequence cluster identifier (e.g. `SEQ087470`); shared by chains with the same sequence |
-| `uniprot_id` | TEXT | UniProt accession number |
+| `sequence_id` | TEXT | Sequence identifier (e.g. `SEQ049914`), shared by all chains with an identical SEQRES |
+| `uniprot_id` | TEXT | UniProt accession(s) from SIFTS; `;`-joined for chimeric chains; empty if none |
 | `pdb_id` | TEXT | 4-character PDB entry ID (lowercase) |
-| `auth_asym_id` | TEXT | Author chain identifier (e.g. `A`) |
-| `sequence` | TEXT | SEQRES amino acid sequence |
-| `sequence_length` | INT | Number of residues in the SEQRES sequence |
-| `modeled_sequence` | TEXT | Amino acid sequence actually resolved (modeled) in the structure |
-| `modeled_sequence_length` | INT | Number of modeled residues |
-| `binders` | TEXT | Bound ligand / small-molecule component IDs present in the structure; empty when none |
-| `binding_status` | TEXT | Ligand-binding state of the chain: `apo` or `holo` |
-| `experimental_method` | TEXT | Structure determination method (e.g. `X-RAY DIFFRACTION`, `ELECTRON MICROSCOPY`, `SOLUTION NMR`) |
-| `resolution` | FLOAT | Experimental resolution in Å (lower is sharper; empty for methods without a resolution) |
-| `pH` | FLOAT | pH of the experimental / crystallization condition |
-| `temp_K` | FLOAT | Temperature of the experiment, in Kelvin |
-| `experimental_details` | TEXT | Free-text crystallization / sample-preparation details |
-| `chain_composition` | TEXT | Quaternary composition of the deposited assembly: `monomeric`, `homomeric`, or `heteromeric` |
-| `non_protein_polymer_binding` | TEXT | Non-protein polymer bound in the structure (`DNA`, `RNA`, or `DNA/RNA`); `None` when absent |
-| `initial_release_date` | TEXT | PDB entry initial release date (`YYYY-MM-DD`) |
-| `cath_id` | TEXT | CATH domain assignment; empty when unassigned |
-| `cath_superfamily` | TEXT | Full CATH superfamily code (e.g. `1.10.10.10`) |
-| `state_id` | TEXT | Conformational state cluster this chain is assigned to (`0`, `1`, `2`, …) |
-| `Rosetta` | FLOAT | Rosetta total energy score |
-| `FoldX` | FLOAT | FoldX total energy score |
-| `EvoEF2` | FLOAT | EvoEF2 total energy score |
-| `RW` | FLOAT | Random-Walk (RW) energy score |
-| `RW+` | FLOAT | Random-Walk+ (RWplus) energy score |
-| `ranked_functions` | TEXT | JSON-encoded list of ranked GO/functional annotations |
-| `matching_scores` | TEXT | JSON-encoded list of function-matching scores, aligned with `ranked_functions` |
-
-
----
+| `auth_asym_id` | TEXT | Author chain identifier (case-sensitive: `d` and `D` are different chains) |
+| `sequence` | TEXT | Full deposited (canonical) sequence, including unmodelled residues |
+| `sequence_length` | INT | Length of `sequence` |
+| `modeled_sequence` | TEXT | Residues present in the coordinates, concatenated (gaps closed up) |
+| `modeled_sequence_length` | INT | Length of `modeled_sequence` |
+| `resolved_label_seq` | TEXT | Resolved SEQRES positions as ranges (`label_seq_id`, 1-based), e.g. `5-173,187-353` |
+| `n_resolved_aa` | INT | Number of resolved standard amino acids |
+| `resolved_coverage` | FLOAT | `n_resolved_aa / sequence_length` |
+| `binders` | TEXT | Ligands, metals and cofactors on this chain (component IDs, `;`-joined; water and common buffers excluded) |
+| `binding_status` | TEXT | `holo` if the chain has any binder, otherwise `apo` |
+| `experimental_method` | TEXT | e.g. `X-RAY DIFFRACTION`, `ELECTRON MICROSCOPY`, `SOLUTION NMR` |
+| `resolution` | FLOAT | Resolution in Å; empty when not applicable (e.g. NMR) |
+| `pH` | FLOAT | pH of the crystallisation / sample condition |
+| `temp_K` | FLOAT | Temperature in Kelvin |
+| `experimental_details` | TEXT | Free-text crystallisation / sample-preparation details |
+| `chain_composition` | TEXT | Entry composition: `monomeric`, `homomeric` or `heteromeric` |
+| `non_protein_polymer_binding` | TEXT | Bound nucleic acid: `DNA`, `RNA`, `DNA/RNA`, `Other polymers` or `None` |
+| `initial_release_date` | TEXT | Initial PDB release date (`YYYY-MM-DD`) |
+| `cath_id` | TEXT | CATH domain IDs for the chain (e.g. `3vgkA01;3vgkA02`); empty if unassigned |
+| `cath_superfamily` | TEXT | CATH superfamily code(s) (e.g. `3.30.420.40`) |
+| `pfam_id` | TEXT | Pfam family accession(s), `;`-joined (e.g. `PF00069`); empty if none |
+| `ecod_id` | TEXT | ECOD domain ID(s) for the chain, `;`-joined (e.g. `e3vgkA1;e3vgkA2`) |
+| `ecod_fid` | TEXT | ECOD family ID(s) `x.h.t.f` (e.g. `2484.1.1.8`); the first two levels (`x.h`) are the homology group |
+| `state_id` | TEXT | Conformational state of this observation within its sequence (`0`, `1`, …) |
+| `Rosetta` | FLOAT | Rosetta total score |
+| `FoldX` | FLOAT | FoldX total energy |
+| `EvoEF2` | FLOAT | EvoEF2 total energy |
+| `RW` | FLOAT | RW statistical potential |
+| `RW+` | FLOAT | RW+ statistical potential |
+| `n_seqres` | INT | SEQRES length used for energy scoring |
+| `n_resolved` | INT | Resolved residues used for scoring |
+| `n_scored` | INT | Residues in the consensus set scored by Rosetta / EvoEF2 / RW / RW+ |
+| `scored_coverage` | FLOAT | `n_scored / n_seqres` |
+| `foldx_n_scored` | INT | Residues scored by FoldX |
+| `foldx_coverage` | FLOAT | `foldx_n_scored / n_seqres` |
+| `ranked_functions` | TEXT | JSON list of functional annotations, ranked for this observation |
+| `matching_scores` | TEXT | JSON list of matching scores, index-aligned with `ranked_functions` |
+
+Energies are computed on a consensus residue set shared by all observations of a sequence, so they are comparable within a sequence. Lower is more favourable.
 
 ### Table: `edge`
 
-Each row represents a pairwise structural comparison between two chain instances (A and B) that share the same UniProt identity.
+One row per ordered pair of observations (A → B) of the same sequence.
 
 | Column | Type | Description |
 |---|---|---|
-| `pdb_id_A` | TEXT | PDB ID of chain A |
-| `auth_asym_id_A` | TEXT | Chain identifier of chain A |
-| `pdb_id_B` | TEXT | PDB ID of chain B |
-| `auth_asym_id_B` | TEXT | Chain identifier of chain B |
-| `TM1` | FLOAT | TM-score of the alignment (chain A as reference) |
-| `RMSD` | FLOAT | Root-mean-square deviation of Cα atoms (Å) |
-| `pair_similarity` | FLOAT | Composite structural similarity score for the A–B pair |
-| `delta_Rosetta` | FLOAT | Rosetta energy difference (B − A) |
-| `delta_FoldX` | FLOAT | FoldX energy difference (B − A) |
-| `delta_EvoEF2` | FLOAT | EvoEF2 energy difference (B − A) |
-| `delta_RW` | FLOAT | Random-Walk (RW) energy difference (B − A) |
-| `delta_RW+` | FLOAT | Random-Walk+ (RWplus) energy difference (B − A) |
-| `state_id_A` | TEXT | Conformational state cluster of chain A |
-| `state_id_B` | TEXT | Conformational state cluster of chain B |
-| `state_similarity` | TEXT | Average structural similarity within the state cluster |
-| `state_fidelity` | TEXT | State-level transition fidelity label: `identical`, `high`, `medium`, or `low` |
-| `pair_fidelity` | TEXT | Pairwise (observation-level) transition fidelity label: `identical`, `high`, `medium`, or `low` |
-| `sequence_id` | TEXT | Internal sequence cluster identifier shared by chains A and B |
+| `pdb_id_A` | TEXT | PDB ID of observation A |
+| `auth_asym_id_A` | TEXT | Chain of observation A |
+| `pdb_id_B` | TEXT | PDB ID of observation B |
+| `auth_asym_id_B` | TEXT | Chain of observation B |
+| `tm_aln` | FLOAT | TM-score normalised by the aligned length (conformation only) |
+| `RMSD` | FLOAT | Cα RMSD over the aligned residues (Å) |
+| `coverage` | FLOAT | `aligned_length / max(L_A, L_B)` |
+| `pair_similarity` | FLOAT | `0.8 · tm_aln + 0.2 · exp(−(RMSD/5)²)` |
+| `delta_Rosetta` | FLOAT | Rosetta(B) − Rosetta(A) |
+| `delta_FoldX` | FLOAT | FoldX(B) − FoldX(A) |
+| `delta_EvoEF2` | FLOAT | EvoEF2(B) − EvoEF2(A) |
+| `delta_RW` | FLOAT | RW(B) − RW(A) |
+| `delta_RW+` | FLOAT | RW+(B) − RW+(A) |
+| `state_id_A` | TEXT | State of A |
+| `state_id_B` | TEXT | State of B |
+| `state_similarity` | FLOAT | Mean `pair_similarity` over all observation pairs between the two states (within-state when `state_id_A = state_id_B`) |
+| `state_fidelity` | TEXT | Fidelity label of `state_similarity` |
+| `pair_fidelity` | TEXT | Fidelity label of `pair_similarity` |
+| `n_shared_resolved` | INT | Residues resolved in both A and B |
+| `delta_order_valid` | TEXT | `True` when resolved-residue changes are comparable (same method, not both NMR, overlapping models) |
+| `order_invalid_reason` | TEXT | `valid`, `cross_method`, `nmr`, `no_shared_residues` or `missing_data` |
+| `n_ordered` | INT | Residues resolved in B but not in A (ordered on going A → B) |
+| `n_disordered` | INT | Residues resolved in A but not in B |
+| `ordered_ranges` | TEXT | SEQRES positions of the ordered residues, e.g. `115-123,187-189` |
+| `disordered_ranges` | TEXT | SEQRES positions of the disordered residues |
+| `longest_ordered_segment` | INT | Longest contiguous ordered stretch |
+| `longest_disordered_segment` | INT | Longest contiguous disordered stretch |
+| `n_terminal_ordered` | INT | Ordered residues in segments touching either terminus |
+| `n_internal_ordered` | INT | Ordered residues in internal segments |
+| `order_evidence` | TEXT | Evidence grade for the ordering: `high`, `medium`, `low` or `not_applicable` (see below) |
+| `ordering_with_ligand_change` | TEXT | `True` when the ordering co-occurs with a change in bound ligands |
+| `sequence_id` | TEXT | Sequence shared by A and B |
+
+When A and B share no resolved residues, `tm_aln`, `pair_similarity` and `pair_fidelity` are empty and `RMSD` / `coverage` are stored as `0.0`.
+
+### Order / disorder labels
+
+These columns describe the *observed* resolved state (residues with or without modelled coordinates), not intrinsic disorder: a residue can lack density because it is flexible, or because of crystal contacts, occupancy or modelling choices. They are only computed when both structures use the same experimental method and at least one is not NMR (NMR models build every residue); otherwise `delta_order_valid` is `False` and the counts are empty.
+
+`order_evidence` grades an ordering event from its length, position and the resolution of both structures:
+
+| Grade | Rule |
+|---|---|
+| `high` | an internal ordered segment of ≥ 8 residues, both structures better than 2.5 Å |
+| `medium` | otherwise, if not `low` |
+| `low` | longest ordered segment ≤ 2 residues, purely terminal, or either structure worse than 3.5 Å |
+| `not_applicable` | nothing was ordered |
+
+### Knowledge graph
+
+MuSProt is organised as a hierarchical graph. In the **outer layer**, each sequence is a node, and two sequences are linked when their chains carry the same set of ECOD homology groups (`x.h` of `ecod_fid`; 88.1% of sequences have an assignment). In the **inner layer**, every observation of a sequence is connected to every other by an `edge` row; contracting each state cluster to one node gives the quotient graph over states, whose edges carry `state_similarity`.
+
+### Indexes
+
+Both tables are indexed for per-chain lookup: `node(pdb_id COLLATE NOCASE, auth_asym_id)` and `edge(pdb_id_A COLLATE NOCASE, auth_asym_id_A)`. Use the same collation in queries to hit the index:
+
+```sql
+SELECT * FROM edge WHERE pdb_id_A = '3vgk' COLLATE NOCASE AND auth_asym_id_A = 'A';
+```
 
 ---
 
 ## Usage Examples
 
-### Python (sqlite3)
+### Python (sqlite3 + pandas)
 
 ```python
 import sqlite3
@@ -93,59 +194,55 @@ import pandas as pd
 
 conn = sqlite3.connect("MuSProt.db")
 
-# Load all chains for a UniProt entry
-df_nodes = pd.read_sql(
-    "SELECT * FROM node WHERE uniprot_id = 'P00533'",
-    conn
+# One observation
+node = pd.read_sql(
+    "SELECT * FROM node WHERE pdb_id = ? COLLATE NOCASE AND auth_asym_id = ?",
+    conn, params=("3vgk", "A"),
 )
 
-# Find all structural neighbours of a given chain
-df_edges = pd.read_sql(
-    "SELECT * FROM edge WHERE pdb_id_A = '1ivo' AND auth_asym_id_A = 'A'",
-    conn
+# Every transition from that observation
+edges = pd.read_sql(
+    "SELECT * FROM edge WHERE pdb_id_A = ? COLLATE NOCASE AND auth_asym_id_A = ?",
+    conn, params=("3vgk", "A"),
 )
-
-conn.close()
 ```
 
-### Filter by structural similarity
+### Transitions between distinct states with a large change
 
 ```python
-# Retrieve pairs with high TM-score and low RMSD
 df = pd.read_sql("""
-    SELECT *
+    SELECT pdb_id_A, auth_asym_id_A, pdb_id_B, auth_asym_id_B,
+           CAST(pair_similarity AS REAL) AS similarity,
+           CAST(RMSD AS REAL)            AS rmsd,
+           CAST(delta_Rosetta AS REAL)   AS d_rosetta
     FROM edge
-    WHERE CAST(TM1 AS REAL) > 0.8
-      AND CAST(RMSD AS REAL) < 2.0
-    LIMIT 1000
-""", conn)
+    WHERE pdb_id_A = ? COLLATE NOCASE AND auth_asym_id_A = ?
+      AND state_id_A <> state_id_B
+      AND pair_fidelity IN ('medium', 'high')
+    ORDER BY similarity
+""", conn, params=("1anf", "A"))
 ```
 
-### Join nodes and edges
+### Apo / holo pairs for one UniProt accession
 
 ```python
-# Get full info for both chains in each pair
 df = pd.read_sql("""
-    SELECT
-        e.pdb_id_A, e.auth_asym_id_A,
-        e.pdb_id_B, e.auth_asym_id_B,
-        e.TM1, e.RMSD,
-        nA.sequence_length AS len_A,
-        nB.sequence_length AS len_B,
-        nA.cath_superfamily
-    FROM edge e
-    JOIN node nA ON e.pdb_id_A = nA.pdb_id AND e.auth_asym_id_A = nA.auth_asym_id
-    JOIN node nB ON e.pdb_id_B = nB.pdb_id AND e.auth_asym_id_B = nB.auth_asym_id
-    WHERE nA.uniprot_id = 'P00533'
-    LIMIT 500
+    SELECT e.pdb_id_A, e.auth_asym_id_A, e.pdb_id_B, e.auth_asym_id_B,
+           e.pair_similarity, e.pair_fidelity, nB.binders
+    FROM node nA
+    JOIN edge e  ON e.pdb_id_A = nA.pdb_id COLLATE NOCASE AND e.auth_asym_id_A = nA.auth_asym_id
+    JOIN node nB ON nB.pdb_id = e.pdb_id_B COLLATE NOCASE AND nB.auth_asym_id = e.auth_asym_id_B
+    WHERE nA.uniprot_id = 'P0AEX9'
+      AND nA.binding_status = 'apo' AND nB.binding_status = 'holo'
 """, conn)
 ```
 
+Scanning `node` by `uniprot_id` or `sequence_id` reads the whole table; for repeated queries create an index first (`CREATE INDEX idx_node_seq ON node(sequence_id)`).
+
 ---
 
 ## Notes
 
-- All numeric fields (energies, TM-score, RMSD, lengths) are stored as `TEXT`; cast them with `CAST(col AS REAL)` or `CAST(col AS INTEGER)` as needed.
-- `ranked_functions` in the `node` table is a JSON string. Parse it with `json.loads()`.
-- The `edge` table is directional: (A→B) and (B→A) are separate rows and may differ slightly in TM-score.
-- Energy delta values represent B − A; a negative delta means chain B is lower energy than chain A.
+- All columns are stored as `TEXT`; cast numeric fields with `CAST(col AS REAL)` / `CAST(col AS INTEGER)`.
+- `ranked_functions` and `matching_scores` are JSON strings; parse with `json.loads()`.
+- `edge` is directional: A → B and B → A are separate rows with identical structural fields and opposite energy deltas.

backend/assets/musprot_summary.json

@@ -1,31 +1,31 @@
 {
-  "total_records": 27586348,
-  "unique_chains": 325320,
-  "avg_rmsd": 0.6675476253688963,
-  "avg_tm_score": 0.9602746188440746,
-  "avg_sequence_length": 235.7717984028132,
+  "total_records": 113582934,
+  "unique_chains": 793278,
+  "avg_rmsd": 1.021488560772695,
+  "avg_tm_score": 0.9077313277727972,
+  "avg_sequence_length": 304.6724704328117,
   "rmsd_distribution": {
-    "0-0.5": 11970560,
-    "0.5-1.0": 10422936,
-    "1.0-1.5": 3551996,
-    "1.5-2.0": 905068,
-    "2.0-5.0": 730332,
-    ">5.0": 5456
+    "0-0.5": 34431100,
+    "0.5-1.0": 39665526,
+    "1.0-1.5": 17562924,
+    "1.5-2.0": 6594622,
+    "2.0-5.0": 15208444,
+    ">5.0": 120318
   },
   "tm_score_distribution": {
-    "0-0.5": 144940,
-    "0.5-0.7": 319272,
-    "0.7-0.85": 917410,
-    "0.85-0.95": 4632994,
-    "0.95-1.0": 21571732
+    "0-0.5": 4580963,
+    "0.5-0.7": 4431774,
+    "0.7-0.85": 12281664,
+    "0.85-0.95": 20890577,
+    "0.95-1.0": 71397956
   },
   "length_distribution": {
-    "300-500": 57390,
-    "500-1000": 19801,
-    "100-200": 101177,
-    "0-100": 76718,
-    "200-300": 65315,
-    ">1000": 4921
+    "300-500": 193657,
+    "500-1000": 86502,
+    "200-300": 162341,
+    ">1000": 20178,
+    "0-100": 110685,
+    "100-200": 219915
   },
   "tm_score_range": {
     "min": 0.0,
@@ -33,10 +33,10 @@
   },
   "rmsd_range": {
     "min": 0.0,
-    "max": 9.83
+    "max": 12.44
   },
   "length_range": {
-    "min": 1,
-    "max": 4542
+    "min": 3,
+    "max": 5247
   }
 }

backend/scripts/build_index.py

@@ -0,0 +1,656 @@
+#!/usr/bin/env python3
+"""
+Build the website sidecars from MuSProt.db.
+
+Outputs (into --out-dir):
+  MuSProt-index.db   compact, indexed lookup tables the website queries directly
+      sequence       one row per sequence_id (catalog: counts, representative, function)
+      member         one row per chain observation (light columns only)
+      state          one row per (sequence_id, state_id)
+      state_pair     mean similarity / fidelity between two states of a sequence
+      function_fts   FTS5 over UniProt / CATH / ECOD / Pfam / top ranked functions per sequence
+      ecod_h, ecod_f ECOD homology / family names (from ecod.latest.domains.txt)
+      ecod_group     outer-graph groups: sequences sharing the same set of ECOD H-groups
+  overview.json      dataset-level counts and histograms for the home page
+
+ECOD names (homology / family) come from ECOD's own domain list via --ecod.
+
+The main DB is only read. Everything is derived in a few SQL scans, so the
+edge table (100M+ rows) is aggregated inside SQLite rather than in Python.
+
+Usage:
+  python backend/scripts/build_index.py /path/MuSProt.db --out-dir /tmp/musprot-bucket \
+      --ecod /path/ecod.latest.domains.txt
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sqlite3
+import time
+from collections import Counter, defaultdict
+from pathlib import Path
+
+FUNCTION_TEXT_TOP_N = 3
+FUNCTION_TEXT_MAX_CHARS = 600
+MAX_PAIR_STATES = 40  # state_pair rows are kept only among a sequence's largest states
+
+
+def log(msg: str) -> None:
+    print(f"[{time.strftime('%H:%M:%S')}] {msg}", flush=True)
+
+
+def to_float(v):
+    try:
+        f = float(v)
+        return None if math.isnan(f) else f
+    except (TypeError, ValueError):
+        return None
+
+
+def to_int(v):
+    f = to_float(v)
+    return None if f is None else int(f)
+
+
+def parse_list(raw):
+    raw = (raw or "").strip()
+    if not raw:
+        return []
+    try:
+        val = json.loads(raw)
+        return val if isinstance(val, list) else []
+    except ValueError:
+        import ast
+        try:
+            val = ast.literal_eval(raw)
+            return val if isinstance(val, list) else []
+        except (ValueError, SyntaxError):
+            return []
+
+
+def hist(values, edges):
+    """Counts of values in [edges[i], edges[i+1]); last bin is closed."""
+    counts = [0] * (len(edges) - 1)
+    for v in values:
+        if v is None:
+            continue
+        for i in range(len(edges) - 1):
+            if v < edges[i + 1] or i == len(edges) - 2:
+                if v >= edges[i]:
+                    counts[i] += 1
+                break
+    return counts
+
+
+# ─────────────────────────────────────────────────────────────── domain inputs
+def split_ids(raw) -> list[str]:
+    return [x for x in (raw or "").split(";") if x]
+
+
+def ecod_hset(fids: str) -> tuple:
+    """ECOD F-ids ('292.2.1.1;11.1.1.3') -> sorted homology-level set ('11.1', '292.2')."""
+    return tuple(sorted({".".join(f.split(".")[:2]) for f in split_ids(fids)}))
+
+
+def load_ecod_names(path: Path | None) -> tuple[dict, dict]:
+    """f_id -> (t_name, f_name) and h_id -> (architecture, x_name, h_name)."""
+    fam, hom = {}, {}
+    if path is None:
+        return fam, hom
+    header = None
+    with open(path, encoding="utf-8") as fh:
+        for line in fh:
+            if line.startswith("#"):
+                cols = line.lstrip("#").rstrip("\n").split("\t")
+                if "f_id" in cols:
+                    header = cols
+                continue
+            parts = line.rstrip("\n").split("\t")
+            if header is None:
+                if "f_id" in parts:
+                    header = parts
+                continue
+            r = dict(zip(header, parts))
+            f_id = r.get("f_id", "")
+            if not f_id or f_id in fam:
+                continue
+            clean = lambda v: (v or "").strip('"') if (v or "").strip('"') not in ("NO_X_NAME", "NO_H_NAME", "NO_T_NAME", "F_UNCLASSIFIED") else ""
+            fam[f_id] = (clean(r.get("t_name")), clean(r.get("f_name")))
+            h_id = ".".join(f_id.split(".")[:2])
+            if h_id not in hom:
+                hom[h_id] = (clean(r.get("architecture_name")), clean(r.get("x_name")), clean(r.get("h_name")))
+    return fam, hom
+
+
+# ─────────────────────────────────────────────────────────────── node pass
+NODE_SQL = """
+SELECT sequence_id, uniprot_id, pdb_id, auth_asym_id, sequence_length,
+       n_resolved_aa, resolved_coverage, binders, binding_status,
+       experimental_method, resolution, pH, temp_K, chain_composition,
+       non_protein_polymer_binding, initial_release_date, cath_superfamily,
+       state_id, ranked_functions, cath_id, pfam_id, ecod_id, ecod_fid
+FROM node
+"""
+
+
+def build_members(src: sqlite3.Connection, dst: sqlite3.Connection, limit: int | None):
+    dst.executescript(
+        """
+        DROP TABLE IF EXISTS member;
+        CREATE TABLE member (
+            sequence_id TEXT NOT NULL,
+            state_id INTEGER,
+            pdb_id TEXT NOT NULL,
+            auth_asym_id TEXT NOT NULL,
+            uniprot_id TEXT,
+            experimental_method TEXT,
+            resolution REAL,
+            binding_status TEXT,
+            chain_composition TEXT,
+            binders TEXT,
+            release_date TEXT,
+            resolved_coverage REAL,
+            n_resolved_aa INTEGER,
+            pH REAL,
+            temp_K REAL,
+            cath_id TEXT,
+            pfam_id TEXT,
+            ecod_id TEXT,
+            ecod_fid TEXT
+        );
+        """
+    )
+    seqs: dict[str, dict] = {}
+    functions: dict[str, list[str]] = {}
+    ov = {
+        "method": Counter(), "binding": Counter(), "composition": Counter(),
+        "npp": Counter(), "year": Counter(), "cath": Counter(),
+        "resolution": [], "length": {}, "uniprot": set(), "entries": set(),
+    }
+    sql = NODE_SQL + (f" LIMIT {int(limit)}" if limit else "")
+    batch = []
+    n = 0
+    for row in src.execute(sql):
+        (seq_id, uniprot, pdb, chain, seq_len, n_res, res_cov, binders, binding,
+         method, resolution, ph, temp, comp, npp, date, cath_sf, state, funcs, cath_id,
+         pfam, ecod_ids, ecod_fid) = row
+        state_i = to_int(state)
+        res_f = to_float(resolution)
+        batch.append((
+            seq_id, state_i, pdb, chain, uniprot or None, method or None, res_f,
+            binding or None, comp or None, binders or None, date or None,
+            to_float(res_cov), to_int(n_res), to_float(ph), to_float(temp),
+            cath_id or None, pfam or None, ecod_ids or None, ecod_fid or None,
+        ))
+        s = seqs.get(seq_id)
+        if s is None:
+            s = seqs[seq_id] = {
+                "uniprot": Counter(), "length": to_int(seq_len), "n_obs": 0,
+                "states": Counter(), "n_holo": 0, "entries": set(), "methods": Counter(),
+                "cath": Counter(), "dates": [], "rep": None,
+                "ecod": Counter(), "pfam": Counter(),
+            }
+        s["n_obs"] += 1
+        if uniprot:
+            s["uniprot"][uniprot] += 1
+        s["states"][state_i] += 1
+        s["n_holo"] += binding == "holo"
+        s["entries"].add(pdb)
+        if method:
+            s["methods"][method] += 1
+        if cath_sf:
+            s["cath"][cath_sf] += 1
+        hs = ecod_hset(ecod_fid)
+        if hs:
+            s["ecod"][hs] += 1
+        pf = tuple(sorted(set(split_ids(pfam))))
+        if pf:
+            s["pfam"][pf] += 1
+        if date:
+            s["dates"].append(date)
+        # representative: best (lowest) resolution among well-resolved chains
+        key = ((to_float(res_cov) or 0) < 0.9, res_f if res_f is not None else 99.0)
+        if s["rep"] is None or key < s["rep"][0]:
+            s["rep"] = (key, pdb, chain)
+        if seq_id not in functions and funcs:
+            fl = [str(f).strip() for f in parse_list(funcs) if len(str(f).strip()) > 10]
+            if fl:
+                functions[seq_id] = fl[:FUNCTION_TEXT_TOP_N]
+
+        ov["method"][method or "Unknown"] += 1
+        ov["binding"][binding or "Unknown"] += 1
+        ov["composition"][comp or "Unknown"] += 1
+        ov["npp"][npp or "None"] += 1
+        if date:
+            ov["year"][date[:4]] += 1
+        if res_f is not None:
+            ov["resolution"].append(res_f)
+        if uniprot:
+            ov["uniprot"].add(uniprot)
+        ov["entries"].add(pdb.lower())
+        ov["length"][seq_id] = to_int(seq_len)
+
+        n += 1
+        if len(batch) >= 50000:
+            dst.executemany(f"INSERT INTO member VALUES ({','.join('?' * 19)})", batch)
+            batch.clear()
+            log(f"  node rows: {n:,}")
+    if batch:
+        dst.executemany(f"INSERT INTO member VALUES ({','.join('?' * 19)})", batch)
+    log(f"  node rows total: {n:,}; sequences: {len(seqs):,}")
+    dst.executescript(
+        """
+        CREATE INDEX idx_member_seq ON member(sequence_id, state_id);
+        CREATE INDEX idx_member_pdb ON member(pdb_id COLLATE NOCASE, auth_asym_id);
+        CREATE INDEX idx_member_uniprot ON member(uniprot_id COLLATE NOCASE);
+        """
+    )
+    return seqs, functions, ov, n
+
+
+def consensus(counter: Counter) -> tuple:
+    """Most common non-empty assignment set across a sequence's chains (ties: larger set)."""
+    if not counter:
+        return ()
+    return max(counter.items(), key=lambda kv: (kv[1], len(kv[0]), kv[0]))[0]
+
+
+def write_sequences(dst: sqlite3.Connection, seqs: dict, functions: dict, ecod_names: tuple):
+    dst.executescript(
+        """
+        DROP TABLE IF EXISTS sequence;
+        CREATE TABLE sequence (
+            sequence_id TEXT PRIMARY KEY,
+            uniprot_id TEXT,
+            length INTEGER,
+            n_obs INTEGER,
+            n_states INTEGER,
+            n_entries INTEGER,
+            n_holo INTEGER,
+            n_apo INTEGER,
+            n_cross_pairs INTEGER,
+            largest_state INTEGER,
+            rep_pdb TEXT,
+            rep_chain TEXT,
+            cath_superfamily TEXT,
+            methods TEXT,
+            first_release TEXT,
+            last_release TEXT,
+            top_function TEXT,
+            ecod_hset TEXT,
+            pfam_ids TEXT
+        );
+        DROP TABLE IF EXISTS state;
+        CREATE TABLE state (
+            sequence_id TEXT NOT NULL,
+            state_id INTEGER NOT NULL,
+            n_members INTEGER,
+            PRIMARY KEY (sequence_id, state_id)
+        );
+        """
+    )
+    rows, state_rows = [], []
+    for seq_id, s in seqs.items():
+        sizes = list(s["states"].values())
+        n_obs = s["n_obs"]
+        cross = n_obs * n_obs - sum(x * x for x in sizes)  # directed cross-state pairs
+        dates = sorted(s["dates"])
+        rows.append((
+            seq_id,
+            s["uniprot"].most_common(1)[0][0] if s["uniprot"] else None,
+            s["length"], n_obs, len(sizes), len(s["entries"]), s["n_holo"], n_obs - s["n_holo"],
+            cross, max(sizes),
+            s["rep"][1], s["rep"][2],
+            s["cath"].most_common(1)[0][0] if s["cath"] else None,
+            ";".join(m for m, _ in s["methods"].most_common()),
+            dates[0] if dates else None, dates[-1] if dates else None,
+            (functions.get(seq_id) or [None])[0],
+            ";".join(consensus(s["ecod"])) or None,
+            ";".join(consensus(s["pfam"])) or None,
+        ))
+        for st, cnt in s["states"].items():
+            state_rows.append((seq_id, st, cnt))
+    dst.executemany(f"INSERT INTO sequence VALUES ({','.join('?' * 19)})", rows)
+    dst.executemany("INSERT INTO state VALUES (?,?,?)", state_rows)
+    dst.executescript(
+        """
+        CREATE INDEX idx_seq_states ON sequence(n_states DESC, n_obs DESC);
+        CREATE INDEX idx_seq_obs ON sequence(n_obs DESC);
+        CREATE INDEX idx_seq_uniprot ON sequence(uniprot_id COLLATE NOCASE);
+        CREATE INDEX idx_seq_cath ON sequence(cath_superfamily);
+        CREATE INDEX idx_seq_ecod ON sequence(ecod_hset, n_obs DESC);
+        """
+    )
+
+    fam, hom = ecod_names
+    dst.executescript(
+        """
+        DROP TABLE IF EXISTS ecod_h;
+        CREATE TABLE ecod_h (h_id TEXT PRIMARY KEY, architecture TEXT, x_name TEXT, h_name TEXT);
+        DROP TABLE IF EXISTS ecod_f;
+        CREATE TABLE ecod_f (f_id TEXT PRIMARY KEY, t_name TEXT, f_name TEXT);
+        DROP TABLE IF EXISTS ecod_group;
+        CREATE TABLE ecod_group (
+            hset TEXT PRIMARY KEY,
+            label TEXT,
+            n_sequences INTEGER,
+            n_obs INTEGER,
+            n_multistate INTEGER,
+            n_states INTEGER
+        );
+        """
+    )
+    dst.executemany("INSERT INTO ecod_h VALUES (?,?,?,?)", [(k, *v) for k, v in hom.items()])
+    dst.executemany("INSERT INTO ecod_f VALUES (?,?,?)", [(k, *v) for k, v in fam.items()])
+    groups: dict[tuple, list] = {}
+    for s in seqs.values():
+        hs = consensus(s["ecod"])
+        if hs:
+            g = groups.setdefault(hs, [0, 0, 0, 0])
+            g[0] += 1
+            g[1] += s["n_obs"]
+            g[2] += len(s["states"]) > 1
+            g[3] += len(s["states"])
+    dst.executemany(
+        "INSERT INTO ecod_group VALUES (?,?,?,?,?,?)",
+        [
+            (";".join(hs), " + ".join(hom.get(h, ("", "", ""))[2] or h for h in hs), *v)
+            for hs, v in groups.items()
+        ],
+    )
+    dst.execute("CREATE INDEX idx_group_size ON ecod_group(n_sequences DESC)")
+
+    dst.executescript(
+        """
+        DROP TABLE IF EXISTS function_fts;
+        CREATE VIRTUAL TABLE function_fts USING fts5(
+            sequence_id UNINDEXED, uniprot_id, cath_superfamily, domains, text,
+            tokenize = 'porter unicode61'
+        );
+        """
+    )
+    fts_rows = []
+    for seq_id, s in seqs.items():
+        text = " ".join(functions.get(seq_id, []))[:FUNCTION_TEXT_MAX_CHARS * FUNCTION_TEXT_TOP_N]
+        uni = " ".join(s["uniprot"].keys())
+        cath = " ".join(s["cath"].keys()).replace(";", " ")
+        hs = consensus(s["ecod"])
+        dom = " ".join(
+            [*(h.replace(".", "_") for h in hs), *(hom.get(h, ("", "", ""))[2] for h in hs),
+             *consensus(s["pfam"])]
+        )
+        fts_rows.append((seq_id, uni, cath, dom, text))
+    dst.executemany("INSERT INTO function_fts VALUES (?,?,?,?,?)", fts_rows)
+
+
+# ─────────────────────────────────────────────────────────────── edge passes
+def build_state_pairs(src: sqlite3.Connection, dst: sqlite3.Connection, seqs: dict,
+                      limit: int | None) -> dict:
+    """Store state-pair similarities (top states only); return fidelity counts over all pairs."""
+    keep = {
+        seq_id: {st for st, _ in s["states"].most_common(MAX_PAIR_STATES)}
+        for seq_id, s in seqs.items() if len(s["states"]) > MAX_PAIR_STATES
+    }
+    fid_counts: dict = defaultdict(lambda: {"state_pairs": 0, "observation_pairs": 0})
+    dst.executescript(
+        """
+        DROP TABLE IF EXISTS state_pair;
+        CREATE TABLE state_pair (
+            sequence_id TEXT NOT NULL,
+            state_a INTEGER NOT NULL,
+            state_b INTEGER NOT NULL,
+            similarity REAL,
+            fidelity TEXT,
+            n_pairs INTEGER,
+            PRIMARY KEY (sequence_id, state_a, state_b)
+        );
+        """
+    )
+    src_tbl = f"(SELECT * FROM edge LIMIT {int(limit)})" if limit else "edge"
+    # directed edges -> keep one direction (A <= B) and count undirected pairs
+    sql = f"""
+        SELECT sequence_id, CAST(state_id_A AS INTEGER) a, CAST(state_id_B AS INTEGER) b,
+               MIN(CAST(state_similarity AS REAL)), MIN(state_fidelity), COUNT(*)
+        FROM {src_tbl}
+        WHERE CAST(state_id_A AS INTEGER) <= CAST(state_id_B AS INTEGER)
+        GROUP BY sequence_id, a, b
+    """
+    cur = src.execute(sql)
+    n = 0
+    while True:
+        rows = cur.fetchmany(100000)
+        if not rows:
+            break
+        out = []
+        for s, a, b, sim, fid, c in rows:
+            # within-state rows appear in both directions with A==B -> halve the count
+            c = c // 2 if a == b else c
+            if a != b:
+                fc = fid_counts[fid or "NA"]
+                fc["state_pairs"] += 1
+                fc["observation_pairs"] += c
+            allowed = keep.get(s)
+            if allowed is None or (a in allowed and b in allowed):
+                out.append((s, a, b, sim, fid, c))
+        dst.executemany("INSERT INTO state_pair VALUES (?,?,?,?,?,?)", out)
+        n += len(rows)
+        log(f"  state pairs: {n:,}")
+    return dict(fid_counts)
+
+
+def edge_histograms(src: sqlite3.Connection, limit: int | None) -> dict:
+    src_tbl = f"(SELECT * FROM edge LIMIT {int(limit)})" if limit else "edge"
+    sql = f"""
+        SELECT state_id_A = state_id_B AS same_state,
+               COALESCE(NULLIF(pair_fidelity, ''), 'NA') AS fid,
+               -- pairs without shared residues store '' similarity and 0.0 RMSD/coverage: keep them
+               -- out of every histogram (they are counted under fidelity 'NA')
+               CASE WHEN pair_similarity = '' THEN NULL
+                    ELSE MIN(CAST(CAST(pair_similarity AS REAL) * 50 AS INTEGER), 49) END AS sim_bin,
+               CASE WHEN pair_similarity = '' THEN NULL
+                    ELSE MIN(CAST(CAST(RMSD AS REAL) * 2 AS INTEGER), 40) END AS rmsd_bin,
+               CASE WHEN pair_similarity = '' THEN NULL
+                    ELSE MIN(CAST(CAST(coverage AS REAL) * 20 AS INTEGER), 19) END AS cov_bin,
+               CASE WHEN tm_aln = '' THEN NULL
+                    ELSE MIN(CAST(CAST(tm_aln AS REAL) * 50 AS INTEGER), 49) END AS tm_bin,
+               COUNT(*)
+        FROM {src_tbl}
+        GROUP BY 1, 2, 3, 4, 5, 6
+    """
+    out = {
+        "total": 0, "cross_state": 0,
+        "pair_fidelity": Counter(), "pair_fidelity_cross": Counter(),
+        "similarity": [0] * 50, "similarity_cross": [0] * 50,
+        "tm_aln": [0] * 50, "rmsd": [0] * 41, "coverage": [0] * 20,
+    }
+    for same, fid, sim_b, rmsd_b, cov_b, tm_b, c in src.execute(sql):
+        out["total"] += c
+        out["pair_fidelity"][fid] += c
+        if not same:
+            out["cross_state"] += c
+            out["pair_fidelity_cross"][fid] += c
+        if sim_b is not None and sim_b >= 0:
+            out["similarity"][sim_b] += c
+            if not same:
+                out["similarity_cross"][sim_b] += c
+        if tm_b is not None and tm_b >= 0:
+            out["tm_aln"][tm_b] += c
+        if rmsd_b is not None and rmsd_b >= 0:
+            out["rmsd"][rmsd_b] += c
+        if cov_b is not None and cov_b >= 0:
+            out["coverage"][cov_b] += c
+    return out
+
+
+def order_stats(src: sqlite3.Connection, limit: int | None) -> dict:
+    """Counts of the observed order/disorder labels over all directed transitions."""
+    src_tbl = f"(SELECT * FROM edge LIMIT {int(limit)})" if limit else "edge"
+    rows = src.execute(f"""
+        SELECT order_invalid_reason, order_evidence, ordering_with_ligand_change,
+               state_id_A = state_id_B, COUNT(*)
+        FROM {src_tbl} GROUP BY 1, 2, 3, 4
+    """).fetchall()
+    reason, evidence, evidence_cross, ligand = Counter(), Counter(), Counter(), Counter()
+    for r, ev, lig, same, c in rows:
+        reason[r or "NA"] += c
+        if r == "valid":
+            evidence[ev or "NA"] += c
+            if not same:
+                evidence_cross[ev or "NA"] += c
+            if ev in ("low", "medium", "high"):
+                ligand[(ev, lig == "True")] += c
+    order = ["high", "medium", "low", "not_applicable"]
+    return {
+        "validity": [{"label": k, "value": v} for k, v in reason.most_common()],
+        "evidence": [{"label": k, "value": evidence.get(k, 0), "cross_state": evidence_cross.get(k, 0)} for k in order],
+        "with_ligand_change": [
+            {"label": k, "with": ligand.get((k, True), 0), "without": ligand.get((k, False), 0)}
+            for k in order[:3]
+        ],
+    }
+
+
+# ─────────────────────────────────────────────────────────────── overview
+def outer_graph_stats(dst: sqlite3.Connection, n_sequences: int) -> dict:
+    rows = dst.execute(
+        "SELECT hset, label, n_sequences, n_obs, n_multistate FROM ecod_group ORDER BY n_sequences DESC"
+    ).fetchall()
+    covered = sum(r[2] for r in rows)
+    size_bins = Counter()
+    for r in rows:
+        n = r[2]
+        size_bins["1" if n == 1 else "2–5" if n <= 5 else "6–20" if n <= 20 else "21–100" if n <= 100 else ">100"] += 1
+    return {
+        "level": "ECOD homology (H)",
+        "groups": len(rows),
+        "covered_sequences": covered,
+        "coverage": covered / n_sequences if n_sequences else 0,
+        "edges": sum(r[2] * (r[2] - 1) // 2 for r in rows),
+        "group_sizes": [{"label": k, "value": size_bins[k]} for k in ["1", "2–5", "6–20", "21–100", ">100"]],
+        "largest": [
+            {"hset": r[0], "label": r[1], "n_sequences": r[2], "n_obs": r[3], "n_multistate": r[4]}
+            for r in rows[:12]
+        ],
+    }
+
+
+def build_overview(seqs, ov, n_nodes, edges, state_fid) -> dict:
+    states_per_seq = Counter(len(s["states"]) for s in seqs.values())
+    obs_per_seq = [s["n_obs"] for s in seqs.values()]
+    n_states_total = sum(len(s["states"]) for s in seqs.values())
+    multi_state = sum(1 for s in seqs.values() if len(s["states"]) > 1)
+    lengths = [v for v in ov["length"].values() if v]
+
+    def capped(counter, cap):
+        out = Counter()
+        for k, v in counter.items():
+            out[k if k < cap else cap] += v
+        return [{"label": (f"{k}+" if k == cap else str(k)), "value": out[k]} for k in sorted(out)]
+
+    obs_edges = [2, 3, 4, 5, 6, 11, 21, 51, 101, 1_000_000]
+    obs_labels = ["2", "3", "4", "5", "6–10", "11–20", "21–50", "51–100", ">100"]
+    len_edges = [0, 100, 200, 300, 400, 500, 750, 1000, 1_000_000]
+    len_labels = ["<100", "100–199", "200–299", "300–399", "400–499", "500–749", "750–999", "≥1000"]
+    res_edges = [0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 5.0, 1000]
+    res_labels = ["<1.5", "1.5–2.0", "2.0–2.5", "2.5–3.0", "3.0–3.5", "3.5–4.0", "4.0–5.0", "≥5.0"]
+    fid_order = ["identical", "low", "medium", "high", "no_shared_residues", "NA"]
+
+    return {
+        "generated": time.strftime("%Y-%m-%d"),
+        "counts": {
+            "observations": n_nodes,
+            "sequences": len(seqs),
+            "multi_state_sequences": multi_state,
+            "state_clusters": n_states_total,
+            "pdb_entries": len(ov["entries"]),
+            "uniprot_accessions": len(ov["uniprot"]),
+            "transitions": edges["total"],
+            "cross_state_transitions": edges["cross_state"],
+        },
+        "states_per_sequence": capped(states_per_seq, 10),
+        "observations_per_sequence": [
+            {"label": l, "value": v} for l, v in zip(obs_labels, hist(obs_per_seq, obs_edges))
+        ],
+        "sequence_length": [
+            {"label": l, "value": v} for l, v in zip(len_labels, hist(lengths, len_edges))
+        ],
+        "resolution": [
+            {"label": l, "value": v} for l, v in zip(res_labels, hist(ov["resolution"], res_edges))
+        ],
+        "experimental_method": [{"label": k, "value": v} for k, v in ov["method"].most_common()],
+        "binding_status": [{"label": k, "value": v} for k, v in ov["binding"].most_common()],
+        "chain_composition": [{"label": k, "value": v} for k, v in ov["composition"].most_common()],
+        "nucleic_acid_binding": [{"label": k, "value": v} for k, v in ov["npp"].most_common()],
+        "release_year": [{"label": k, "value": ov["year"][k]} for k in sorted(ov["year"])],
+        "pair_fidelity": [
+            {"label": k, "value": edges["pair_fidelity"].get(k, 0),
+             "cross_state": edges["pair_fidelity_cross"].get(k, 0)}
+            for k in fid_order if edges["pair_fidelity"].get(k)
+        ],
+        "state_fidelity": [
+            {"label": k, **state_fid[k]} for k in fid_order if k in state_fid
+        ],
+        "pair_similarity": {
+            "bin_width": 0.02, "all": edges["similarity"], "cross_state": edges["similarity_cross"],
+        },
+        "tm_aln": {"bin_width": 0.02, "all": edges["tm_aln"]},
+        "rmsd": {"bin_width": 0.5, "all": edges["rmsd"], "last_bin_open": True},
+        "coverage": {"bin_width": 0.05, "all": edges["coverage"]},
+    }
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("db", type=Path)
+    ap.add_argument("--out-dir", type=Path, required=True)
+    ap.add_argument("--limit", type=int, default=None, help="debug: only read the first N rows")
+    ap.add_argument("--ecod", type=Path, default=None, help="ecod.latest.domains.txt (for ECOD names)")
+    args = ap.parse_args()
+
+    args.out_dir.mkdir(parents=True, exist_ok=True)
+    index_path = args.out_dir / "MuSProt-index.db"
+    tmp_path = index_path.with_suffix(".db.tmp")
+    tmp_path.unlink(missing_ok=True)
+
+    src = sqlite3.connect(f"file:{args.db}?mode=ro", uri=True)
+    src.execute("PRAGMA temp_store = FILE")
+    src.execute("PRAGMA cache_size = -2000000")
+    dst = sqlite3.connect(tmp_path)
+    dst.execute("PRAGMA journal_mode = OFF")
+    dst.execute("PRAGMA synchronous = OFF")
+
+    ecod_names = load_ecod_names(args.ecod)
+    log(f"ECOD names: {len(ecod_names[0]):,} families, {len(ecod_names[1]):,} homology groups")
+
+    log("pass 1/4: node table")
+    seqs, functions, ov, n_nodes = build_members(src, dst, args.limit)
+    write_sequences(dst, seqs, functions, ecod_names)
+    dst.commit()
+
+    log("pass 2/4: state pairs (edge GROUP BY)")
+    state_fid = build_state_pairs(src, dst, seqs, args.limit)
+    dst.commit()
+
+    log("pass 3/4: edge histograms")
+    edges = edge_histograms(src, args.limit)
+    log("pass 4/4: order / disorder labels")
+    order = order_stats(src, args.limit)
+
+    overview = build_overview(seqs, ov, n_nodes, edges, state_fid)
+    overview["outer_graph"] = outer_graph_stats(dst, len(seqs))
+    overview["order"] = order
+    dst.execute("CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT)")
+    dst.execute("INSERT INTO meta VALUES ('overview', ?)", (json.dumps(overview),))
+    dst.commit()
+    dst.execute("VACUUM")
+    dst.close()
+    tmp_path.replace(index_path)
+    (args.out_dir / "overview.json").write_text(json.dumps(overview, indent=1))
+    log(f"done → {index_path} ({index_path.stat().st_size / 1e6:.1f} MB)")
+    log(json.dumps(overview["counts"], indent=1))
+
+
+if __name__ == "__main__":
+    main()

backend/scripts/generate_node_lookup.py

@@ -1,68 +0,0 @@
-"""Generate an indexed read-only node lookup sidecar from MuSProt.db."""
-from __future__ import annotations
-
-import argparse
-import sqlite3
-import zlib
-from pathlib import Path
-
-
-NODE_COLUMNS = (
-    "pdb_id", "auth_asym_id", "binding_status", "sequence", "sequence_length",
-    "cath_id", "cath_superfamily", "Rosetta", "FoldX", "EvoEF2", "RW", "RW+",
-    "ranked_functions", "state_id", "experimental_method", "pH", "temp_K",
-    "chain_composition", "matching_scores",
-)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("source", type=Path)
-    parser.add_argument("-o", "--output", type=Path, default=Path("MuSProt-node-lookup.db"))
-    args = parser.parse_args()
-
-    output = args.output.resolve()
-    output.unlink(missing_ok=True)
-
-    conn = sqlite3.connect(output)
-    try:
-        conn.execute("PRAGMA journal_mode = OFF")
-        conn.execute("PRAGMA synchronous = OFF")
-        conn.execute(
-            'CREATE TABLE node (pdb_id, auth_asym_id, binding_status, sequence BLOB,'
-            ' sequence_length, cath_id, cath_superfamily, Rosetta, FoldX, EvoEF2,'
-            ' RW, "RW+", ranked_functions BLOB, state_id, experimental_method, pH, temp_K,'
-            ' chain_composition, matching_scores BLOB)'
-        )
-        source = sqlite3.connect(f"file:{args.source.resolve()}?mode=ro", uri=True)
-        try:
-            select_columns = ", ".join(f'"{column}"' for column in NODE_COLUMNS)
-            rows = source.execute(f"SELECT {select_columns} FROM node")
-            placeholders = ", ".join("?" for _ in NODE_COLUMNS)
-            batch = []
-            for row in rows:
-                row = list(row)
-                for index in (3, 12, 18):  # sequence, ranked_functions, matching_scores
-                    row[index] = zlib.compress((row[index] or "").encode("utf-8"), 1)
-                batch.append(row)
-                if len(batch) == 1000:
-                    conn.executemany(f"INSERT INTO node VALUES ({placeholders})", batch)
-                    batch.clear()
-            if batch:
-                conn.executemany(f"INSERT INTO node VALUES ({placeholders})", batch)
-        finally:
-            source.close()
-        conn.execute(
-            "CREATE INDEX idx_node_chain "
-            "ON node(LOWER(pdb_id), UPPER(auth_asym_id))"
-        )
-        conn.execute("ANALYZE")
-        conn.commit()
-    finally:
-        conn.close()
-
-    print(f"Created {output} ({output.stat().st_size:,} bytes)")
-
-
-if __name__ == "__main__":
-    main()

backend/space_app.py

@@ -7,11 +7,13 @@ from contextlib import asynccontextmanager
 from pathlib import Path
 
 from fastapi import FastAPI, HTTPException
+from fastapi.middleware.gzip import GZipMiddleware
 from fastapi.responses import FileResponse, PlainTextResponse, RedirectResponse
 from fastapi.staticfiles import StaticFiles
 
 from app.protein.api.routes.protein import router as protein_router
 from app.protein.api.routes.protein import set_data_manager
+from app.protein.api.routes.explore import router as explore_router
 from app.protein.config import get_database_path, get_docs_path, get_plots_dir
 from app.protein.data_loader import DataManager
 from app.protein import tsv_loader
@@ -52,7 +54,9 @@ app = FastAPI(
     redoc_url="/api/redoc",
     openapi_url="/api/openapi.json",
 )
+app.add_middleware(GZipMiddleware, minimum_size=2048)
 app.include_router(protein_router, prefix="/api/protein", tags=["MuSProt"])
+app.include_router(explore_router, prefix="/api/protein", tags=["MuSProt explorer"])
 
 
 @app.get("/health")

frontend/index.html

@@ -1,16 +1,21 @@
-
-  <!DOCTYPE html>
-  <html lang="en">
-    <head>
-      <meta charset="UTF-8" />
-      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-      <title>MuSProt: Multistate Protein Structure Database</title>
-      <meta name="description" content="Explore multistate protein structures, pairwise comparisons, energy scores, and functional annotations." />
-    </head>
-
-    <body>
-      <div id="root"></div>
-      <script type="module" src="/src/main.tsx"></script>
-    </body>
-  </html>
-  
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <title>MuSProt — Multistate Protein Database</title>
+    <meta name="description" content="Search and download experimentally observed conformational states of proteins, clustered into states with annotated state transitions." />
+    <meta name="theme-color" content="#0b1524" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      rel="stylesheet"
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap"
+    />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package-lock.json

@@ -10,6 +10,7 @@
                   "license": "MIT",
                   "dependencies": {
                         "axios": "^1.13.4",
+                        "d3-force": "^3.0.0",
                         "lucide-react": "^0.487.0",
                         "react": "^18.3.1",
                         "react-dom": "^18.3.1",
@@ -19,6 +20,7 @@
                         "remark-gfm": "^4.0.1"
                   },
                   "devDependencies": {
+                        "@types/d3-force": "^3.0.10",
                         "@types/node": "^20.10.0",
                         "@types/react": "^19.2.9",
                         "@types/react-dom": "^19.2.3",
@@ -1636,6 +1638,13 @@
                         "@swc/counter": "^0.1.3"
                   }
             },
+            "node_modules/@types/d3-force": {
+                  "version": "3.0.10",
+                  "resolved": "https://registry.npmjs.org/@types/d3-force/-/d3-force-3.0.10.tgz",
+                  "integrity": "sha512-ZYeSaCF3p73RdOKcjj+swRlZfnYpK1EbaDiYICEEp5Q6sUiqFaFQ9qgoshp5CzIyyb/yD09kD9o2zEltCexlgw==",
+                  "dev": true,
+                  "license": "MIT"
+            },
             "node_modules/@types/debug": {
                   "version": "4.1.13",
                   "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.13.tgz",
@@ -2385,6 +2394,47 @@
                   "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
                   "license": "MIT"
             },
+            "node_modules/d3-dispatch": {
+                  "version": "3.0.1",
+                  "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz",
+                  "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==",
+                  "license": "ISC",
+                  "engines": {
+                        "node": ">=12"
+                  }
+            },
+            "node_modules/d3-force": {
+                  "version": "3.0.0",
+                  "resolved": "https://registry.npmjs.org/d3-force/-/d3-force-3.0.0.tgz",
+                  "integrity": "sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==",
+                  "license": "ISC",
+                  "dependencies": {
+                        "d3-dispatch": "1 - 3",
+                        "d3-quadtree": "1 - 3",
+                        "d3-timer": "1 - 3"
+                  },
+                  "engines": {
+                        "node": ">=12"
+                  }
+            },
+            "node_modules/d3-quadtree": {
+                  "version": "3.0.1",
+                  "resolved": "https://registry.npmjs.org/d3-quadtree/-/d3-quadtree-3.0.1.tgz",
+                  "integrity": "sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==",
+                  "license": "ISC",
+                  "engines": {
+                        "node": ">=12"
+                  }
+            },
+            "node_modules/d3-timer": {
+                  "version": "3.0.1",
+                  "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz",
+                  "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==",
+                  "license": "ISC",
+                  "engines": {
+                        "node": ">=12"
+                  }
+            },
             "node_modules/debug": {
                   "version": "4.4.3",
                   "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",

frontend/package.json

@@ -7,6 +7,7 @@
       "homepage": "https://huggingface.co/spaces/omaib/MuSProt",
       "dependencies": {
             "axios": "^1.13.4",
+            "d3-force": "^3.0.0",
             "lucide-react": "^0.487.0",
             "react": "^18.3.1",
             "react-dom": "^18.3.1",
@@ -16,6 +17,7 @@
             "remark-gfm": "^4.0.1"
       },
       "devDependencies": {
+            "@types/d3-force": "^3.0.10",
             "@types/node": "^20.10.0",
             "@types/react": "^19.2.9",
             "@types/react-dom": "^19.2.3",

frontend/public/sitemap.xml

@@ -5,6 +5,16 @@
     <changefreq>monthly</changefreq>
     <priority>1.0</priority>
   </url>
+  <url>
+    <loc>https://omaib-musprot.hf.space/browse</loc>
+    <changefreq>monthly</changefreq>
+    <priority>0.9</priority>
+  </url>
+  <url>
+    <loc>https://omaib-musprot.hf.space/statistics</loc>
+    <changefreq>monthly</changefreq>
+    <priority>0.7</priority>
+  </url>
   <url>
     <loc>https://omaib-musprot.hf.space/docs</loc>
     <changefreq>monthly</changefreq>

frontend/scripts/prerender.mjs

@@ -8,14 +8,24 @@ const template = readFileSync(join(BUILD_DIR, 'index.html'), 'utf-8');
 const routes = [
   {
     path: '',
-    title: 'MuSProt: Multistate Protein Structure Database',
+    title: 'MuSProt — Multistate Protein Database',
     description:
-      'Explore multistate protein structures, pairwise comparisons, energy scores, and functional annotations.',
+      'Search and download 863,643 experimentally observed conformations of 102,790 protein sequences, clustered into 162,601 states with 113.7 million annotated state transitions.',
+  },
+  {
+    path: 'browse',
+    title: 'Browse sequences — MuSProt',
+    description: 'Browse protein sequences with multiple experimentally observed conformations, sorted by number of conformational states.',
+  },
+  {
+    path: 'statistics',
+    title: 'Statistics — MuSProt',
+    description: 'Distributions of conformational states, transitions, structural similarity, fidelity and experimental metadata across MuSProt.',
   },
   {
     path: 'docs',
-    title: 'MuSProt Documentation',
-    description: 'MuSProt dataset format, SQLite schema, and usage examples.',
+    title: 'Documentation — MuSProt',
+    description: 'MuSProt SQLite schema, field definitions and usage examples.',
   },
 ];
 

frontend/src/App.tsx

@@ -1,20 +1,62 @@
-import { Navigate, Route, Routes } from 'react-router-dom';
-import { Header } from './components/layout/Header';
-import { Footer } from './components/layout/Footer';
-import { ProteinDashboard } from './components/datasets/protein/ProteinDashboard';
-import { ProteinDocsPage } from './pages/datasets/ProteinDocsPage';
+import { useEffect } from 'react';
+import { Link, Navigate, Route, Routes, useLocation, useParams } from 'react-router-dom';
+import { Footer, Header } from './components/Layout';
+import { DatasetJsonLd, PageMeta } from './components/PageMeta';
+import { HomePage } from './pages/HomePage';
+import { BrowsePage } from './pages/BrowsePage';
+import { SearchPage } from './pages/SearchPage';
+import { SequencePage } from './pages/SequencePage';
+import { ChainPage } from './pages/ChainPage';
+import { StatisticsPage } from './pages/StatisticsPage';
+import { DocsPage } from './pages/DocsPage';
+
+function ScrollToTop() {
+  const { pathname } = useLocation();
+  useEffect(() => {
+    window.scrollTo(0, 0);
+  }, [pathname]);
+  return null;
+}
+
+/** /chain/3vgk.A → /chain/3vgk/A */
+function ChainShorthand() {
+  const { id = '' } = useParams();
+  const m = /^([0-9][A-Za-z0-9]{3})[.:_-](.+)$/.exec(id);
+  return m ? <Navigate to={`/chain/${m[1].toLowerCase()}/${m[2]}`} replace /> : <Navigate to={`/search?q=${id}`} replace />;
+}
+
+function NotFound() {
+  return (
+    <div className="page page--narrow not-found">
+      <PageMeta title="Not found — MuSProt" path="/404" />
+      <p className="eyebrow">404</p>
+      <h1>This page is in an unobserved state.</h1>
+      <p>
+        Try the <Link to="/browse">sequence browser</Link> or search from the header.
+      </p>
+    </div>
+  );
+}
 
 export default function App() {
   return (
-    <div className="min-h-screen bg-white">
+    <div className="app">
+      <DatasetJsonLd />
+      <ScrollToTop />
       <Header />
-      <main>
+      <main id="main">
         <Routes>
-          <Route path="/" element={<ProteinDashboard />} />
-          <Route path="/docs" element={<ProteinDocsPage />} />
+          <Route path="/" element={<HomePage />} />
+          <Route path="/browse" element={<BrowsePage />} />
+          <Route path="/search" element={<SearchPage />} />
+          <Route path="/statistics" element={<StatisticsPage />} />
+          <Route path="/docs" element={<DocsPage />} />
+          <Route path="/sequence/:id" element={<SequencePage />} />
+          <Route path="/chain/:pdb/:chain" element={<ChainPage />} />
+          <Route path="/chain/:id" element={<ChainShorthand />} />
           <Route path="/datasets/musprot" element={<Navigate to="/" replace />} />
           <Route path="/datasets/musprot/docs" element={<Navigate to="/docs" replace />} />
-          <Route path="*" element={<Navigate to="/" replace />} />
+          <Route path="*" element={<NotFound />} />
         </Routes>
       </main>
       <Footer />

frontend/src/api/protein.ts

@@ -1,122 +0,0 @@
-/**
- * API client for protein visualization backend
- * Connects to FastAPI backend (default: http://localhost:8000)
- */
-import axios from 'axios';
-import type { FilterParams, FilterOptions, DataResponse, SummaryStats, ChainMetadata, RankedFunction } from '../types/protein';
-
-// API base URL - uses Vite proxy in development
-const API_BASE_URL = import.meta.env.VITE_PROTEIN_API_BASE || '/api';
-
-const api = axios.create({
-  baseURL: API_BASE_URL,
-  headers: {
-    'Content-Type': 'application/json',
-  },
-});
-
-// Enhanced error handling with diagnostics
-api.interceptors.response.use(
-  (response) => response,
-  async (error) => {
-    const url = error.config?.url || 'unknown';
-    const method = error.config?.method?.toUpperCase() || 'REQUEST';
-    const status = error.response?.status || 'NO_RESPONSE';
-    const statusText = error.response?.statusText || 'Connection failed';
-    
-    // Try to get response body
-    let responseBody = '';
-    if (error.response?.data) {
-      if (typeof error.response.data === 'string') {
-        responseBody = error.response.data;
-      } else {
-        responseBody = JSON.stringify(error.response.data);
-      }
-    }
-    
-    const diagnosticMessage = `API Error: ${method} ${url} → ${status} ${statusText}${responseBody ? '\nResponse: ' + responseBody : ''}`;
-    console.error(diagnosticMessage);
-    
-    // Re-throw with enhanced message
-    error.message = diagnosticMessage;
-    return Promise.reject(error);
-  }
-);
-
-export const proteinApi = {
-  /**
-   * Get available filter options
-   */
-  async getFilters(): Promise<FilterOptions> {
-    const response = await api.get<FilterOptions>('/protein/filters');
-    return response.data;
-  },
-
-  /**
-   * Get filtered protein data
-   */
-  async getData(filters: FilterParams): Promise<DataResponse> {
-    const response = await api.post<DataResponse>('/protein/data', filters);
-    return response.data;
-  },
-
-  /**
-   * Get summary statistics
-   */
-  async getSummary(params?: Partial<FilterParams>): Promise<SummaryStats> {
-    const response = await api.get<SummaryStats>('/protein/summary', { params });
-    return response.data;
-  },
-
-  /**
-   * Resolve chain metadata from RCSB web API
-   * @param signal - AbortSignal for request cancellation
-   */
-  async resolveChain(
-    pdb_id: string, 
-    auth_asym_id: string, 
-    options?: { use_cache?: boolean; signal?: AbortSignal }
-  ): Promise<ChainMetadata> {
-    const { use_cache = true, signal } = options || {};
-    try {
-      const response = await api.get<ChainMetadata>('/protein/chain/resolve', {
-        params: { pdb_id, auth_asym_id, use_cache },
-        signal
-      });
-      return response.data;
-    } catch (error: any) {
-      // Normalize 404 errors
-      if (error.response?.status === 404) {
-        const notFoundError: any = new Error('Chain not found');
-        notFoundError.code = 'NOT_FOUND';
-        notFoundError.status = 404;
-        notFoundError.detail = error.response?.data?.detail || 'Chain not found in PDB';
-        throw notFoundError;
-      }
-      throw error;
-    }
-  },
-
-  /**
-   * Batch resolve multiple chains
-   */
-  async batchResolveChains(chains: Array<{ pdb_id: string; auth_asym_id: string }>, use_cache: boolean = true): Promise<Record<string, ChainMetadata>> {
-    const response = await api.post<Record<string, ChainMetadata>>('/protein/chain/batch-resolve', chains, {
-      params: { use_cache }
-    });
-    return response.data;
-  },
-
-  /**
-   * Get ranked functional annotations for a chain from local TSV
-   */
-  async getChainFunctions(
-    pdb_id: string,
-    auth_asym_id: string,
-  ): Promise<RankedFunction[]> {
-    const response = await api.get<{ functions: RankedFunction[] }>('/protein/chain/functions', {
-      params: { pdb_id, auth_asym_id },
-    });
-    return response.data.functions;
-  },
-};

frontend/src/components/Domains.tsx

@@ -0,0 +1,151 @@
+import type { ReactNode } from 'react';
+import { Link } from 'react-router-dom';
+import { pfamName, type EcodNames } from '../lib/api';
+import { usePromise } from '../lib/hooks';
+import { ExternalLink } from './ui';
+
+/* ECOD's site is served over plain http; https does not resolve. */
+const ECOD = 'http://prodata.swmed.edu/ecod/complete';
+
+export const links = {
+  uniprot: (id: string) => `https://www.uniprot.org/uniprotkb/${id}`,
+  rcsb: (pdb: string) => `https://www.rcsb.org/structure/${pdb.toUpperCase()}`,
+  pdbe: (pdb: string) => `https://www.ebi.ac.uk/pdbe/entry/pdb/${pdb.toLowerCase()}`,
+  cathDomain: (id: string) => `https://www.cathdb.info/version/latest/domain/${id}`,
+  cathSuperfamily: (id: string) => `https://www.cathdb.info/version/latest/superfamily/${id}`,
+  ecodDomain: (id: string) => `${ECOD}/domain/${id}`,
+  ecodTree: (id: string) => `${ECOD}/tree?id=${id}`,
+  pfam: (id: string) => `https://www.ebi.ac.uk/interpro/entry/pfam/${id}/`,
+};
+
+function PfamChip({ id }: { id: string }) {
+  const name = usePromise(() => pfamName(id), [id]);
+  return (
+    <span className="idchip">
+      <ExternalLink href={links.pfam(id)}>
+        <span className="mono">{id}</span>
+      </ExternalLink>
+      {name && <span className="idchip__name">{name}</span>}
+    </span>
+  );
+}
+
+function Row({ label, hint, children }: { label: string; hint?: string; children: ReactNode }) {
+  return (
+    <div className="idlist__row">
+      <dt title={hint}>{label}</dt>
+      <dd>{children}</dd>
+    </div>
+  );
+}
+
+const None = () => <span className="muted">Not assigned</span>;
+
+export function DomainList({
+  uniprot,
+  pdb,
+  cathDomains = [],
+  cathSuperfamilies = [],
+  ecodDomains = [],
+  ecodFids = [],
+  ecodHset = [],
+  ecodNames,
+  pfamIds = [],
+  sequenceId,
+}: {
+  uniprot?: string | null;
+  pdb?: string;
+  cathDomains?: string[];
+  cathSuperfamilies?: string[];
+  ecodDomains?: string[];
+  ecodFids?: string[];
+  ecodHset?: string[];
+  ecodNames?: EcodNames;
+  pfamIds?: string[];
+  sequenceId?: string;
+}) {
+  const homs = ecodNames?.homologies ?? {};
+  const fams = ecodNames?.families ?? {};
+  const hIds = ecodHset.length ? ecodHset : [...new Set(ecodFids.map((f) => f.split('.').slice(0, 2).join('.')))];
+  const uniprots = (uniprot ?? '').split(';').filter(Boolean);
+
+  return (
+    <dl className="idlist">
+      <Row label="UniProt">
+        {uniprots.length ? uniprots.map((u) => <ExternalLink key={u} href={links.uniprot(u)}><span className="mono">{u}</span></ExternalLink>) : <None />}
+      </Row>
+      {pdb && (
+        <Row label="PDB entry">
+          <ExternalLink href={links.rcsb(pdb)}>
+            <span className="mono">{pdb.toUpperCase()}</span> · RCSB
+          </ExternalLink>
+          <ExternalLink href={links.pdbe(pdb)}>PDBe</ExternalLink>
+        </Row>
+      )}
+      {sequenceId && (
+        <Row label="Sequence">
+          <Link to={`/sequence/${sequenceId}`} className="mono">
+            {sequenceId}
+          </Link>
+        </Row>
+      )}
+      {(cathDomains.length > 0 || pdb) && (
+        <Row label="CATH domains">
+          {cathDomains.length ? cathDomains.map((d) => <ExternalLink key={d} href={links.cathDomain(d)}><span className="mono">{d}</span></ExternalLink>) : <None />}
+        </Row>
+      )}
+      <Row label="CATH superfamily">
+        {cathSuperfamilies.length ? cathSuperfamilies.map((d) => <ExternalLink key={d} href={links.cathSuperfamily(d)}><span className="mono">{d}</span></ExternalLink>) : <None />}
+      </Row>
+      {(ecodDomains.length > 0 || pdb) && (
+        <Row label="ECOD domains">
+          {ecodDomains.length ? ecodDomains.map((d) => <ExternalLink key={d} href={links.ecodDomain(d)}><span className="mono">{d}</span></ExternalLink>) : <None />}
+        </Row>
+      )}
+      {ecodFids.length > 0 && (
+        <Row label="ECOD family" hint="Family id x.h.t.f; homology (x.h) and family names from ECOD">
+          <span className="idstack">
+            {ecodFids.map((f) => (
+              <span key={f} className="idchip">
+                <ExternalLink href={links.ecodTree(f)}>
+                  <span className="mono">{f}</span>
+                </ExternalLink>
+                {fams[f]?.f_name && <span className="idchip__name">{fams[f].f_name}</span>}
+              </span>
+            ))}
+          </span>
+        </Row>
+      )}
+      <Row label="ECOD homology" hint="H-level groups; sequences with the same set are linked in the outer graph">
+        {hIds.length ? (
+          <span className="idstack">
+            {hIds.map((h) => (
+              <span key={h} className="idchip">
+                <ExternalLink href={links.ecodTree(h)}>
+                  <span className="mono">{h}</span>
+                </ExternalLink>
+                {homs[h]?.h_name && <span className="idchip__name">{homs[h].h_name}</span>}
+                <Link to={`/browse?ecod=${h}`} className="idchip__more">
+                  sequences →
+                </Link>
+              </span>
+            ))}
+          </span>
+        ) : (
+          <None />
+        )}
+      </Row>
+      <Row label="Pfam">
+        {pfamIds.length ? (
+          <span className="idstack">
+            {pfamIds.map((p) => (
+              <PfamChip key={p} id={p} />
+            ))}
+          </span>
+        ) : (
+          <None />
+        )}
+      </Row>
+    </dl>
+  );
+}

frontend/src/components/ForceGraph.tsx

@@ -0,0 +1,357 @@
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import {
+  forceCollide,
+  forceLink,
+  forceManyBody,
+  forceSimulation,
+  forceX,
+  forceY,
+  type Simulation,
+  type SimulationLinkDatum,
+  type SimulationNodeDatum,
+} from 'd3-force';
+import { Tooltip, useWidth, type TipState } from './charts';
+
+export interface FGNode {
+  id: string;
+  r: number;
+  fill: string;
+  /** nodes sharing a group are enclosed by a shaded circle */
+  group?: string | number;
+  ring?: boolean;
+}
+
+export interface FGLink {
+  source: string;
+  target: string;
+  distance: number;
+  color: string;
+  width?: number;
+  opacity?: number;
+  /** drawn only while one of its endpoints is hovered */
+  hidden?: boolean;
+}
+
+export interface FGGroup {
+  key: string | number;
+  color: string;
+  label?: string;
+}
+
+type SimNode = FGNode & SimulationNodeDatum & { phase: number };
+type SimLink = SimulationLinkDatum<SimNode> & FGLink;
+
+const reducedMotion = () =>
+  typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+
+/**
+ * Live force-directed graph: nodes keep drifting gently and can be dragged.
+ * Positions are written to the DOM on every tick (no React re-render per frame).
+ */
+export function ForceGraph({
+  nodes,
+  links,
+  groups = [],
+  height = 460,
+  charge = -40,
+  linkStrength,
+  onNodeClick,
+  nodeTip,
+  ariaLabel,
+}: {
+  nodes: FGNode[];
+  links: FGLink[];
+  groups?: FGGroup[];
+  height?: number;
+  charge?: number;
+  linkStrength?: number;
+  onNodeClick?: (id: string) => void;
+  nodeTip?: (id: string) => ReactNode;
+  ariaLabel: string;
+}) {
+  const [wrapRef, width] = useWidth<HTMLDivElement>();
+  const svgRef = useRef<SVGSVGElement>(null);
+  const nodeEls = useRef(new Map<string, SVGCircleElement>());
+  const linkEls = useRef<Array<SVGLineElement | null>>([]);
+  const hullEls = useRef(new Map<string | number, SVGGElement>());
+  const simRef = useRef<Simulation<SimNode, SimLink> | null>(null);
+  const simNodes = useRef<SimNode[]>([]);
+  const positions = useRef(new Map<string, { x: number; y: number }>());
+  const [hover, setHover] = useState<string | null>(null);
+  const [tip, setTip] = useState<TipState | null>(null);
+  const drag = useRef<{ id: string; moved: boolean; x0: number; y0: number } | null>(null);
+  const W = Math.max(280, width);
+  const H = height;
+
+  useEffect(() => {
+    if (!width) return;
+    const keep = positions.current;
+    const sn: SimNode[] = nodes.map((n, i) => {
+      const p = keep.get(n.id);
+      const a = (i / Math.max(1, nodes.length)) * Math.PI * 2;
+      return { ...n, phase: Math.random() * Math.PI * 2, x: p?.x ?? W / 2 + Math.cos(a) * 80, y: p?.y ?? H / 2 + Math.sin(a) * 80 };
+    });
+    simNodes.current = sn;
+    const sl: SimLink[] = links.map((l) => ({ ...l }));
+    const still = reducedMotion();
+    let t = 0;
+    // slow, per-node sinusoidal nudge keeps the layout alive
+    const wander = () => {
+      if (still) return;
+      t += 1;
+      for (const n of sn) {
+        if (n.fx != null) continue;
+        n.vx = (n.vx ?? 0) + Math.cos(n.phase + t * 0.013) * 0.035;
+        n.vy = (n.vy ?? 0) + Math.sin(n.phase * 1.3 + t * 0.011) * 0.035;
+      }
+    };
+    // keep each group compact and push overlapping group circles apart
+    const hasGroups = groups.length > 0;
+    const hullR = new Map<string | number, number>();
+    const cohesion = () => {
+      if (!hasGroups) return;
+      const acc = new Map<string | number, { x: number; y: number; n: number; members: SimNode[] }>();
+      for (const n of sn) {
+        if (n.group == null) continue;
+        const a = acc.get(n.group) ?? { x: 0, y: 0, n: 0, members: [] };
+        a.x += n.x!;
+        a.y += n.y!;
+        a.n += 1;
+        a.members.push(n);
+        acc.set(n.group, a);
+      }
+      const cs = [...acc.entries()].map(([k, a]) => ({ k, x: a.x / a.n, y: a.y / a.n, members: a.members }));
+      for (const c of cs) {
+        for (const n of c.members) {
+          if (n.fx != null) continue;
+          n.vx = (n.vx ?? 0) + (c.x - n.x!) * 0.035;
+          n.vy = (n.vy ?? 0) + (c.y - n.y!) * 0.035;
+        }
+      }
+      for (let i = 0; i < cs.length; i++) {
+        for (let j = i + 1; j < cs.length; j++) {
+          const a = cs[i];
+          const b = cs[j];
+          const dx = b.x - a.x;
+          const dy = b.y - a.y;
+          const d = Math.hypot(dx, dy) || 1;
+          const overlap = (hullR.get(a.k) ?? 10) + (hullR.get(b.k) ?? 10) + 10 - d;
+          if (overlap <= 0) continue;
+          const push = Math.min(overlap, 30) * 0.02;
+          const ux = (dx / d) * push;
+          const uy = (dy / d) * push;
+          for (const n of a.members) {
+            if (n.fx != null) continue;
+            n.vx = (n.vx ?? 0) - ux;
+            n.vy = (n.vy ?? 0) - uy;
+          }
+          for (const n of b.members) {
+            if (n.fx != null) continue;
+            n.vx = (n.vx ?? 0) + ux;
+            n.vy = (n.vy ?? 0) + uy;
+          }
+        }
+      }
+    };
+    const strength = linkStrength ?? 0.7 / Math.max(1, Math.sqrt(sn.length));
+    const sim = forceSimulation<SimNode, SimLink>(sn)
+      .force('link', forceLink<SimNode, SimLink>(sl).id((d) => d.id).distance((l) => l.distance).strength(strength))
+      .force('charge', forceManyBody<SimNode>().strength(charge))
+      .force('x', forceX<SimNode>(W / 2).strength(0.035))
+      .force('y', forceY<SimNode>(H / 2).strength(0.055))
+      .force('collide', forceCollide<SimNode>((d) => d.r + 2.5))
+      .force('wander', wander)
+      .force('cohesion', cohesion)
+      .velocityDecay(0.32)
+      .alphaTarget(still ? 0 : 0.02);
+
+    const draw = () => {
+      for (const n of sn) {
+        n.x = Math.max(n.r + 4, Math.min(W - n.r - 4, n.x!));
+        n.y = Math.max(n.r + 4, Math.min(H - n.r - 4, n.y!));
+        keep.set(n.id, { x: n.x, y: n.y });
+        const el = nodeEls.current.get(n.id);
+        if (el) {
+          el.setAttribute('cx', n.x.toFixed(1));
+          el.setAttribute('cy', n.y.toFixed(1));
+        }
+      }
+      sl.forEach((l, i) => {
+        const el = linkEls.current[i];
+        if (!el) return;
+        const s = l.source as SimNode;
+        const d = l.target as SimNode;
+        el.setAttribute('x1', s.x!.toFixed(1));
+        el.setAttribute('y1', s.y!.toFixed(1));
+        el.setAttribute('x2', d.x!.toFixed(1));
+        el.setAttribute('y2', d.y!.toFixed(1));
+      });
+      if (hullEls.current.size) {
+        const byGroup = new Map<string | number, SimNode[]>();
+        for (const n of sn) {
+          if (n.group == null) continue;
+          const arr = byGroup.get(n.group) ?? [];
+          arr.push(n);
+          byGroup.set(n.group, arr);
+        }
+        for (const [key, members] of byGroup) {
+          const g = hullEls.current.get(key);
+          if (!g) continue;
+          const cx = members.reduce((s, n) => s + n.x!, 0) / members.length;
+          const cy = members.reduce((s, n) => s + n.y!, 0) / members.length;
+          const r = Math.max(...members.map((n) => Math.hypot(n.x! - cx, n.y! - cy) + n.r)) + 9;
+          hullR.set(key, r);
+          const c = g.firstElementChild as SVGCircleElement;
+          c.setAttribute('cx', cx.toFixed(1));
+          c.setAttribute('cy', cy.toFixed(1));
+          c.setAttribute('r', r.toFixed(1));
+          const label = g.lastElementChild as SVGTextElement | null;
+          if (label && label.tagName === 'text') {
+            label.setAttribute('x', cx.toFixed(1));
+            label.setAttribute('y', (cy - r - 4).toFixed(1));
+          }
+        }
+      }
+    };
+    sim.on('tick', draw);
+    if (still) sim.tick(200);
+    draw();
+    simRef.current = sim;
+    return () => {
+      sim.stop();
+      simRef.current = null;
+    };
+  }, [nodes, links, groups, W, H, width, charge, linkStrength]);
+
+  const toLocal = (e: React.PointerEvent) => {
+    const r = svgRef.current!.getBoundingClientRect();
+    return { x: e.clientX - r.left, y: e.clientY - r.top };
+  };
+
+  const onPointerDown = (id: string) => (e: React.PointerEvent<SVGCircleElement>) => {
+    const n = simNodes.current.find((m) => m.id === id);
+    if (!n) return;
+    (e.target as Element).setPointerCapture(e.pointerId);
+    const p = toLocal(e);
+    drag.current = { id, moved: false, x0: p.x, y0: p.y };
+    n.fx = n.x;
+    n.fy = n.y;
+    simRef.current?.alphaTarget(0.25).restart();
+    setTip(null);
+  };
+
+  const onPointerMove = (e: React.PointerEvent<SVGSVGElement>) => {
+    const d = drag.current;
+    if (!d) return;
+    const p = toLocal(e);
+    if (Math.hypot(p.x - d.x0, p.y - d.y0) > 3) d.moved = true;
+    const n = simNodes.current.find((m) => m.id === d.id);
+    if (n) {
+      n.fx = Math.max(n.r, Math.min(W - n.r, p.x));
+      n.fy = Math.max(n.r, Math.min(H - n.r, p.y));
+    }
+  };
+
+  const onPointerUp = () => {
+    const d = drag.current;
+    if (!d) return;
+    const n = simNodes.current.find((m) => m.id === d.id);
+    if (n) {
+      n.fx = null;
+      n.fy = null;
+    }
+    simRef.current?.alphaTarget(reducedMotion() ? 0 : 0.02);
+    drag.current = null;
+    if (!d.moved) onNodeClick?.(d.id);
+  };
+
+  const showTip = (id: string, e: React.PointerEvent | React.MouseEvent) => {
+    if (drag.current || !nodeTip) return;
+    const r = svgRef.current!.getBoundingClientRect();
+    setTip({ x: e.clientX - r.left, y: e.clientY - r.top, content: nodeTip(id) });
+  };
+
+  return (
+    <div className="fg" ref={wrapRef}>
+      {width > 0 && (
+        <svg
+          ref={svgRef}
+          width={W}
+          height={H}
+          role="img"
+          aria-label={ariaLabel}
+          onPointerMove={onPointerMove}
+          onPointerUp={onPointerUp}
+          onPointerLeave={onPointerUp}
+        >
+          {groups.length > 0 && (
+            <g className="fg__hulls">
+              {groups.map((g) => (
+                <g
+                  key={g.key}
+                  ref={(el) => {
+                    if (el) hullEls.current.set(g.key, el);
+                    else hullEls.current.delete(g.key);
+                  }}
+                >
+                  <circle
+                    className="fg__hull"
+                    style={{ fill: g.color, stroke: g.color }}
+                    r={0}
+                  />
+                  {g.label && (
+                    <text className="fg__hull-label" textAnchor="middle">
+                      {g.label}
+                    </text>
+                  )}
+                </g>
+              ))}
+            </g>
+          )}
+          <g className="fg__links">
+            {links.map((l, i) => {
+              const hot = hover != null && (l.source === hover || l.target === hover);
+              const visible = !l.hidden || hot;
+              return (
+                <line
+                  key={`${l.source}-${l.target}`}
+                  ref={(el) => {
+                    linkEls.current[i] = el;
+                  }}
+                  stroke={l.color}
+                  strokeWidth={hot ? (l.width ?? 1) + 0.8 : l.width ?? 1}
+                  strokeOpacity={!visible ? 0 : hover == null ? l.opacity ?? 0.4 : hot ? 0.95 : 0.05}
+                />
+              );
+            })}
+          </g>
+          <g className="fg__nodes">
+            {nodes.map((n) => (
+              <circle
+                key={n.id}
+                ref={(el) => {
+                  if (el) nodeEls.current.set(n.id, el);
+                  else nodeEls.current.delete(n.id);
+                }}
+                r={hover === n.id ? n.r + 2 : n.r}
+                fill={n.fill}
+                className={`fg__node ${n.ring ? 'is-ring' : ''}`}
+                onPointerDown={onPointerDown(n.id)}
+                onPointerEnter={(e) => {
+                  setHover(n.id);
+                  showTip(n.id, e);
+                }}
+                onPointerMove={(e) => showTip(n.id, e)}
+                onPointerLeave={() => {
+                  setHover(null);
+                  setTip(null);
+                }}
+              />
+            ))}
+          </g>
+        </svg>
+      )}
+      <Tooltip tip={tip} />
+    </div>
+  );
+}

frontend/src/components/HeroArt.tsx

@@ -0,0 +1,62 @@
+import { useMemo } from 'react';
+import { rng } from './StateGlyph';
+
+/**
+ * Background illustration for the hero: a field of observation clusters
+ * (states) connected by faint transition lines. Decorative only.
+ */
+export function HeroArt() {
+  const art = useMemo(() => {
+    const r = rng('musprot-hero');
+    const clusters = Array.from({ length: 14 }, () => ({
+      x: 560 + r() * 640,
+      y: 40 + r() * 440,
+      n: 4 + Math.floor(r() * 14),
+      s: 10 + r() * 22,
+    }));
+    const dots = clusters.flatMap((c, ci) =>
+      Array.from({ length: c.n }, () => {
+        const a = r() * Math.PI * 2;
+        const d = Math.sqrt(r()) * c.s;
+        return { x: c.x + Math.cos(a) * d, y: c.y + Math.sin(a) * d, ci, big: r() > 0.85 };
+      }),
+    );
+    const edges: Array<[number, number]> = [];
+    clusters.forEach((a, i) => {
+      const near = clusters
+        .map((b, j) => ({ j, d: Math.hypot(a.x - b.x, a.y - b.y) }))
+        .filter((o) => o.j !== i)
+        .sort((p, q) => p.d - q.d)
+        .slice(0, 2);
+      near.forEach((o) => {
+        if (i < o.j) edges.push([i, o.j]);
+      });
+    });
+    return { clusters, dots, edges };
+  }, []);
+
+  return (
+    <svg className="hero__art" viewBox="0 0 1200 520" preserveAspectRatio="xMaxYMid slice" aria-hidden>
+      <defs>
+        <radialGradient id="hero-glow" cx="75%" cy="45%" r="55%">
+          <stop offset="0%" stopColor="#2a78d6" stopOpacity="0.28" />
+          <stop offset="100%" stopColor="#2a78d6" stopOpacity="0" />
+        </radialGradient>
+      </defs>
+      <rect width="1200" height="520" fill="url(#hero-glow)" />
+      {art.edges.map(([i, j]) => {
+        const a = art.clusters[i];
+        const b = art.clusters[j];
+        const mx = (a.x + b.x) / 2;
+        const my = (a.y + b.y) / 2 - 30;
+        return <path key={`${i}-${j}`} d={`M${a.x},${a.y} Q${mx},${my} ${b.x},${b.y}`} className="hero__edge" />;
+      })}
+      {art.clusters.map((c, i) => (
+        <circle key={i} cx={c.x} cy={c.y} r={c.s + 8} className="hero__halo" />
+      ))}
+      {art.dots.map((d, i) => (
+        <circle key={i} cx={d.x} cy={d.y} r={d.big ? 3.2 : 2} className={`hero__dot hero__dot--${d.ci % 4}`} />
+      ))}
+    </svg>
+  );
+}

frontend/src/components/KnowledgeGraph.tsx

@@ -0,0 +1,322 @@
+import { useMemo, useState } from 'react';
+import { Link, useNavigate } from 'react-router-dom';
+import { ArrowRight } from 'lucide-react';
+import { api, type InnerGraph, type OuterGraph } from '../lib/api';
+import { useApi } from '../lib/hooks';
+import { FIDELITY_INFO, fidelityColor } from '../lib/fidelity';
+import { chainLabel, chainPath, cleanFunction, fmtInt, fmtNum, methodShort, sequencePath } from '../lib/format';
+import { ForceGraph, type FGGroup, type FGLink, type FGNode } from './ForceGraph';
+import { Spinner, Swatch } from './ui';
+
+/* Categorical slots (validated order) for the largest states; the rest fold into "other". */
+const STATE_COLORS = ['#2a78d6', '#eb6834', '#1baf7a', '#eda100', '#e87ba4', '#008300', '#4a3aa7'];
+const OTHER = '#98a2b3';
+
+/* Ordinal ramp for "number of states" on outer-graph nodes. */
+const STATE_BINS: Array<{ max: number; label: string; color: string }> = [
+  { max: 1, label: '1 state', color: 'var(--nst-1)' },
+  { max: 2, label: '2', color: 'var(--nst-2)' },
+  { max: 5, label: '3–5', color: 'var(--nst-3)' },
+  { max: 20, label: '6–20', color: 'var(--nst-4)' },
+  { max: Infinity, label: '> 20', color: 'var(--nst-5)' },
+];
+const statesColor = (n: number) => STATE_BINS.find((b) => n <= b.max)!.color;
+
+/**
+ * Thin a dense complete graph without hiding transitions: keep each node's k most
+ * similar same-state partners, and the `perPair` most similar edges between every
+ * pair of states (so every state pair stays visibly connected).
+ */
+function backbone(edges: InnerGraph['edges'], state: number[], k = 2, perPair = 3): Set<number> {
+  const within = new Map<number, number[]>();
+  const across = new Map<string, number[]>();
+  edges.forEach((e, i) => {
+    const a = state[e.s];
+    const b = state[e.t];
+    if (a === b) {
+      for (const n of [e.s, e.t]) {
+        const arr = within.get(n) ?? [];
+        arr.push(i);
+        within.set(n, arr);
+      }
+    } else {
+      const key = a < b ? `${a}|${b}` : `${b}|${a}`;
+      const arr = across.get(key) ?? [];
+      arr.push(i);
+      across.set(key, arr);
+    }
+  });
+  const bySim = (x: number, y: number) => (edges[y].sim ?? -1) - (edges[x].sim ?? -1);
+  const keep = new Set<number>();
+  for (const arr of within.values()) arr.sort(bySim).slice(0, k).forEach((i) => keep.add(i));
+  for (const arr of across.values()) arr.sort(bySim).slice(0, perPair).forEach((i) => keep.add(i));
+  return keep;
+}
+
+/* ───────────────────────────── outer layer: one ECOD homology group */
+
+function OuterGraphView({
+  data,
+  selected,
+  onSelect,
+  names,
+}: {
+  data: OuterGraph;
+  selected: string;
+  onSelect: (id: string) => void;
+  names: Record<string, string>;
+}) {
+  const group = data.groups[0];
+  const { nodes, links } = useMemo(() => {
+    const seqs = group?.sequences ?? [];
+    const nodes: FGNode[] = seqs.map((s) => ({
+      id: s.sequence_id,
+      r: 5 + 2.1 * Math.log2(1 + s.n_obs),
+      fill: statesColor(s.n_states),
+    }));
+    const links: FGLink[] = [];
+    for (let i = 0; i < seqs.length; i++)
+      for (let j = i + 1; j < seqs.length; j++)
+        links.push({ source: seqs[i].sequence_id, target: seqs[j].sequence_id, distance: 140, color: 'var(--faint)', opacity: 0.3 });
+    return { nodes, links };
+  }, [group]);
+  const withRing = useMemo(() => nodes.map((n) => ({ ...n, ring: n.id === selected })), [nodes, selected]);
+  const bySeq = useMemo(() => new Map((group?.sequences ?? []).map((s) => [s.sequence_id, s])), [group]);
+  if (!group) return <p className="muted">This sequence has no ECOD homology assignment.</p>;
+
+  return (
+    <ForceGraph
+      ariaLabel={`Outer graph: ${group.label}`}
+      nodes={withRing}
+      links={links}
+      charge={-220}
+      linkStrength={0.035}
+      onNodeClick={onSelect}
+      nodeTip={(id) => {
+        const s = bySeq.get(id)!;
+        return (
+          <>
+            <div className="chart-tip__title">
+              {names[id] ?? <span className="mono">{id}</span>}
+              {names[id] && <span className="muted mono"> · {id}</span>}
+            </div>
+            {s.top_function && <div className="chart-tip__wrap">{cleanFunction(s.top_function).slice(0, 90)}</div>}
+            <div className="chart-tip__row">
+              <span>Observations</span>
+              <b className="tabular">{fmtInt(s.n_obs)}</b>
+            </div>
+            <div className="chart-tip__row">
+              <span>States</span>
+              <b className="tabular">{fmtInt(s.n_states)}</b>
+            </div>
+            {s.uniprot_id && (
+              <div className="chart-tip__row">
+                <span>UniProt</span>
+                <b className="mono">{s.uniprot_id}</b>
+              </div>
+            )}
+            <div className="chart-tip__foot">Click to open its inner graph · drag to move</div>
+          </>
+        );
+      }}
+    />
+  );
+}
+
+/* ───────────────────────────── inner layer: observations, states as shaded circles */
+
+function InnerGraphView({ g }: { g: InnerGraph }) {
+  const navigate = useNavigate();
+  const { nodes, links, groups, colorOf } = useMemo(() => {
+    const top = g.states.slice(0, STATE_COLORS.length);
+    const colorMap = new Map(top.map((s, i) => [s.state_id, STATE_COLORS[i]]));
+    const colorOf = (st: number) => colorMap.get(st) ?? OTHER;
+    const nodes: FGNode[] = g.nodes.map((n, i) => ({
+      id: String(i),
+      r: 6,
+      fill: colorOf(n.state_id),
+      group: n.state_id,
+    }));
+    const keep = g.nodes.length > 40 ? backbone(g.edges, g.nodes.map((n) => n.state_id)) : null;
+    const links: FGLink[] = g.edges.map((e, i) => {
+      const same = g.nodes[e.s].state_id === g.nodes[e.t].state_id;
+      return {
+        source: String(e.s),
+        target: String(e.t),
+        // spring length grows with structural dissimilarity
+        distance: Math.min(230, 22 + 560 * (1 - (e.sim ?? 0.3))),
+        color: same ? 'var(--line-strong)' : fidelityColor(e.fid),
+        opacity: same ? 0.45 : keep ? 0.75 : 0.3,
+        width: same ? 0.9 : keep ? 1.4 : 0.9,
+        hidden: keep ? !keep.has(i) : false,
+      };
+    });
+    const present = new Set(g.nodes.map((n) => n.state_id));
+    const groups: FGGroup[] = g.states
+      .filter((s) => present.has(s.state_id))
+      .map((s) => ({
+        key: s.state_id,
+        color: colorOf(s.state_id),
+        label: g.nodes.filter((n) => n.state_id === s.state_id).length > 1 ? `State ${s.state_id}` : undefined,
+      }));
+    return { nodes, links, groups, colorOf };
+  }, [g]);
+
+  return (
+    <>
+      <ForceGraph
+        ariaLabel="Inner graph: observations of one sequence grouped by conformational state"
+        nodes={nodes}
+        links={links}
+        groups={groups}
+        charge={-55}
+        linkStrength={0.03}
+        onNodeClick={(id) => {
+          const n = g.nodes[Number(id)];
+          navigate(chainPath(n.pdb_id, n.auth_asym_id));
+        }}
+        nodeTip={(id) => {
+          const n = g.nodes[Number(id)];
+          return (
+            <>
+              <div className="chart-tip__title mono">{chainLabel(n.pdb_id, n.auth_asym_id)}</div>
+              <div className="chart-tip__row">
+                <Swatch color={colorOf(n.state_id)} shape="dot" />
+                <span>State</span>
+                <b>{n.state_id}</b>
+              </div>
+              <div className="chart-tip__row">
+                <span>Method</span>
+                <b>
+                  {methodShort(n.experimental_method)}
+                  {n.resolution != null ? ` · ${fmtNum(n.resolution, 2)} Å` : ''}
+                </b>
+              </div>
+              <div className="chart-tip__row">
+                <span>Ligand</span>
+                <b>{n.binding_status ?? '—'}</b>
+              </div>
+              <div className="chart-tip__foot">Click to open this chain · drag to move</div>
+            </>
+          );
+        }}
+      />
+      <ul className="legend">
+        {g.states.slice(0, STATE_COLORS.length).map((s) => (
+          <li key={s.state_id}>
+            <Swatch color={colorOf(s.state_id)} shape="dot" /> State {s.state_id}
+            <span className="muted">({fmtInt(s.n_members)})</span>
+          </li>
+        ))}
+
+      </ul>
+      <ul className="legend">
+        <li>
+          <span className="legend-line" style={{ background: 'var(--line-strong)' }} /> Same state
+        </li>
+        {['low', 'medium', 'high'].map((f) => (
+          <li key={f}>
+            <span className="legend-line" style={{ background: fidelityColor(f) }} /> {FIDELITY_INFO[f].label} fidelity
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+}
+
+/* ───────────────────────────── container */
+
+export function KnowledgeGraph({ featured }: { featured: Array<{ id: string; name: string }> }) {
+  const names = Object.fromEntries(featured.map((f) => [f.id, f.name]));
+  const [example, setExample] = useState(featured[0].id);
+  const [selected, setSelected] = useState(featured[0].id);
+  const outer = useApi(`outer1:${example}`, (sig) => api.outerGraph([example], sig));
+  const inner = useApi(`inner:${selected}`, (sig) => api.innerGraph(selected, 60, sig));
+  const group = outer.data?.groups[0];
+  const g = inner.data;
+  const selectedSeq = group?.sequences.find((s) => s.sequence_id === selected) ?? g?.sequence;
+
+  return (
+    <div className="kg">
+      <div className="kg__picks" role="group" aria-label="Examples">
+        <span className="muted small">Example</span>
+        {featured.map((f) => (
+          <button
+            key={f.id}
+            type="button"
+            className={`chip ${f.id === example ? 'is-on' : ''}`}
+            onClick={() => {
+              setExample(f.id);
+              setSelected(f.id);
+            }}
+          >
+            {f.name}
+          </button>
+        ))}
+      </div>
+      <div className="kg__panels">
+        <div className="card kg__panel">
+          <header className="kg__head">
+            <p className="eyebrow">Outer layer · sequences</p>
+            <h3 className="card__title">{group ? group.label || group.hset.join(' + ') : 'ECOD homology group'}</h3>
+            <p className="card__kicker">
+              {group
+                ? `${fmtInt(group.n_sequences)} sequences share this set of ECOD homology groups and form one clique; the ${group.sequences.length} most multistate are shown.`
+                : 'Sequences sharing the same ECOD homology groups are linked.'}{' '}
+              Node size: observations · colour: states.
+            </p>
+          </header>
+          {outer.loading && <Spinner />}
+          {outer.data && <OuterGraphView data={outer.data} selected={selected} onSelect={setSelected} names={names} />}
+          <ul className="legend">
+            {STATE_BINS.map((b) => (
+              <li key={b.label}>
+                <Swatch color={b.color} shape="dot" /> {b.label}
+              </li>
+            ))}
+            <li>
+              <span className="swatch swatch--dot swatch--sel" /> Selected
+            </li>
+          </ul>
+          {group && (
+            <div className="kg__foot">
+              <Link to={`/browse?ecod=${encodeURIComponent(group.hset.join(';'))}`} className="btn btn--ghost btn--sm">
+                All {fmtInt(group.n_sequences)} sequences <ArrowRight aria-hidden />
+              </Link>
+            </div>
+          )}
+        </div>
+
+        <div className="card kg__panel">
+          <header className="kg__head">
+            <p className="eyebrow">Inner layer · observations</p>
+            <h3 className="card__title">
+              {names[selected] ?? (g?.sequence.uniprot_id ? `UniProt ${g.sequence.uniprot_id}` : 'Sequence')}{' '}
+              <span className="muted mono">{selected}</span>
+            </h3>
+            <p className="card__kicker">
+              Every observation is linked to every other; spring length follows structural dissimilarity. Shaded circles
+              are conformational states; cross-state edges are coloured by fidelity.
+            </p>
+          </header>
+          {inner.loading && <Spinner label="Loading inner graph…" />}
+          {g && <InnerGraphView g={g} />}
+          {g && (
+            <div className="kg__foot">
+              <span className="muted small">
+                {g.nodes.length} of {fmtInt(g.n_total)} observations
+                {g.states.length > STATE_COLORS.length
+                  ? ` · ${STATE_COLORS.length} largest of ${fmtInt(g.states.length)} states`
+                  : ` · ${fmtInt(g.states.length)} states`}
+                {g.nodes.length > 40 && ' · showing the 3 closest links between each pair of states; hover a node for all its triplets'}
+              </span>
+              <Link to={sequencePath(selected)} className="btn btn--ghost btn--sm">
+                Open {selectedSeq ? `${fmtInt(selectedSeq.n_obs)} observations` : 'sequence'} <ArrowRight aria-hidden />
+              </Link>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

frontend/src/components/Layout.tsx

@@ -0,0 +1,134 @@
+import { useEffect, useState } from 'react';
+import { Link, NavLink, useLocation } from 'react-router-dom';
+import { Download, Menu, X } from 'lucide-react';
+import { api } from '../lib/api';
+import { SearchBox } from './SearchBox';
+
+export function Logo({ size = 28 }: { size?: number }) {
+  // Three conformational "states" joined by transitions.
+  return (
+    <svg width={size} height={size} viewBox="0 0 32 32" aria-hidden className="logo-mark">
+      <rect width="32" height="32" rx="8" className="logo-mark__bg" />
+      <path d="M9 21.5 L16 10 L23 21.5" className="logo-mark__edge" />
+      <path d="M9 21.5 H23" className="logo-mark__edge logo-mark__edge--soft" />
+      <circle cx="16" cy="10" r="3.4" className="logo-mark__n1" />
+      <circle cx="9" cy="21.5" r="3.4" className="logo-mark__n2" />
+      <circle cx="23" cy="21.5" r="3.4" className="logo-mark__n3" />
+    </svg>
+  );
+}
+
+const NAV = [
+  { to: '/browse', label: 'Browse' },
+  { to: '/statistics', label: 'Statistics' },
+  { to: '/docs', label: 'Docs' },
+];
+
+export function Header() {
+  const location = useLocation();
+  const [open, setOpen] = useState(false);
+  const isHome = location.pathname === '/';
+
+  useEffect(() => setOpen(false), [location.pathname, location.search]);
+
+  return (
+    <header className={`site-header ${isHome ? 'site-header--home' : ''}`}>
+      <div className="site-header__inner">
+        <Link to="/" className="brand" aria-label="MuSProt home">
+          <Logo />
+          <span className="brand__name">MuSProt</span>
+        </Link>
+        {!isHome && (
+          <div className="site-header__search">
+            <SearchBox placeholder="Search chain, entry, UniProt, function…" />
+          </div>
+        )}
+        <nav className="site-nav" aria-label="Main">
+          {NAV.map((n) => (
+            <NavLink key={n.to} to={n.to} className={({ isActive }) => `site-nav__link ${isActive ? 'is-active' : ''}`}>
+              {n.label}
+            </NavLink>
+          ))}
+          <a href={api.downloadUrl} className="btn btn--primary btn--sm">
+            <Download aria-hidden /> Download
+          </a>
+        </nav>
+        <button
+          type="button"
+          className="menu-toggle"
+          aria-label="Menu"
+          aria-expanded={open}
+          onClick={() => setOpen((o) => !o)}
+        >
+          {open ? <X aria-hidden /> : <Menu aria-hidden />}
+        </button>
+      </div>
+      {open && (
+        <div className="mobile-nav">
+          {!isHome && <SearchBox placeholder="Search MuSProt…" />}
+          {NAV.map((n) => (
+            <NavLink key={n.to} to={n.to} className="mobile-nav__link">
+              {n.label}
+            </NavLink>
+          ))}
+          <a href={api.downloadUrl} className="btn btn--primary">
+            <Download aria-hidden /> Download MuSProt.db
+          </a>
+        </div>
+      )}
+    </header>
+  );
+}
+
+export function Footer() {
+  return (
+    <footer className="site-footer">
+      <div className="site-footer__inner">
+        <div className="site-footer__brand">
+          <Link to="/" className="brand">
+            <Logo size={24} />
+            <span className="brand__name">MuSProt</span>
+          </Link>
+          <p>
+            A million-scale database of experimentally observed conformational states and state transitions of proteins,
+            built from the Protein Data Bank.
+          </p>
+        </div>
+        <div className="site-footer__cols">
+          <div>
+            <h3>Explore</h3>
+            <Link to="/browse">Browse sequences</Link>
+            <Link to="/browse?min_states=5">Highly multistate</Link>
+            <Link to="/chain/3vgk/A">Example chain</Link>
+          </div>
+          <div>
+            <h3>Data</h3>
+            <Link to="/docs">Documentation</Link>
+            <a href={api.downloadUrl}>Download SQLite</a>
+            <a href="/api/docs" target="_blank" rel="noopener noreferrer">
+              REST API
+            </a>
+          </div>
+          <div>
+            <h3>Sources</h3>
+            <a href="https://www.rcsb.org" target="_blank" rel="noopener noreferrer">
+              RCSB PDB
+            </a>
+            <a href="https://www.uniprot.org" target="_blank" rel="noopener noreferrer">
+              UniProt
+            </a>
+            <a href="https://www.cathdb.info" target="_blank" rel="noopener noreferrer">
+              CATH
+            </a>
+          </div>
+        </div>
+      </div>
+      <div className="site-footer__base">
+        <span>MuSProt · Multistate Protein Database</span>
+        <a href="https://huggingface.co/spaces/omaib/MuSProt" target="_blank" rel="noopener noreferrer">
+          Hosted on Hugging Face
+        </a>
+      </div>
+    </footer>
+  );
+}

frontend/src/components/PageMeta.tsx

@@ -0,0 +1,58 @@
+import { Helmet } from 'react-helmet-async';
+
+const BASE = 'https://omaib-musprot.hf.space';
+
+export function PageMeta({ title, description, path }: { title: string; description?: string; path: string }) {
+  const url = `${BASE}${path}`;
+  return (
+    <Helmet>
+      <title>{title}</title>
+      {description && <meta name="description" content={description} />}
+      <link rel="canonical" href={url} />
+      <meta property="og:type" content="website" />
+      <meta property="og:title" content={title} />
+      {description && <meta property="og:description" content={description} />}
+      <meta property="og:url" content={url} />
+      <meta property="og:site_name" content="MuSProt" />
+      <meta name="twitter:card" content="summary" />
+    </Helmet>
+  );
+}
+
+const DATASET_LD = {
+  '@context': 'https://schema.org',
+  '@type': 'Dataset',
+  name: 'MuSProt: Multistate Protein Database',
+  description:
+    'A million-scale database of experimentally observed protein conformational states from the Protein Data Bank: 863,643 chain observations of 102,790 sequences, clustered into 162,601 conformational states, with 113.7 million pairwise transitions annotated with structural similarity (TM-score, RMSD, coverage), energy differences (Rosetta, FoldX, EvoEF2, RW, RW+), fidelity labels and ranked functional annotations.',
+  url: `${BASE}/`,
+  creator: { '@type': 'Organization', name: 'MuSProt', url: `${BASE}/` },
+  license: 'https://creativecommons.org/licenses/by/4.0/',
+  keywords: [
+    'protein structure',
+    'conformational states',
+    'multistate proteins',
+    'Protein Data Bank',
+    'structural biology',
+    'protein design',
+    'TM-score',
+    'energy scoring',
+  ],
+  distribution: [
+    {
+      '@type': 'DataDownload',
+      encodingFormat: 'application/x-sqlite3',
+      contentUrl: `${BASE}/api/protein/download/db`,
+      name: 'MuSProt.db (SQLite, ~37 GB)',
+    },
+  ],
+  measurementTechnique: 'X-ray crystallography, cryo-EM, NMR',
+};
+
+export function DatasetJsonLd() {
+  return (
+    <Helmet>
+      <script type="application/ld+json">{JSON.stringify(DATASET_LD)}</script>
+    </Helmet>
+  );
+}

frontend/src/components/Panels.tsx

@@ -0,0 +1,142 @@
+import { useState } from 'react';
+import { Download } from 'lucide-react';
+import type { RankedFunction } from '../lib/api';
+import { cleanFunction, fmtNum } from '../lib/format';
+import { CopyButton, EmptyState } from './ui';
+
+/** Ranked functional annotations with their matching scores as bars. */
+export function FunctionList({ functions, initial = 6 }: { functions: RankedFunction[]; initial?: number }) {
+  const [all, setAll] = useState(false);
+  if (!functions.length) return <EmptyState title="No functional annotation" />;
+  const max = Math.max(...functions.map((f) => f.score ?? 0), 1e-9);
+  const shown = all ? functions : functions.slice(0, initial);
+  return (
+    <>
+      <ol className="fnlist">
+        {shown.map((f, i) => (
+          <li key={i} className="fnlist__item">
+            <span className="fnlist__rank tabular">{i + 1}</span>
+            <span className="fnlist__text">{cleanFunction(f.function)}</span>
+            <span className="fnlist__score" title="Matching score">
+              <span className="fnlist__bar">
+                <span style={{ width: `${((f.score ?? 0) / max) * 100}%` }} />
+              </span>
+              <span className="tabular">{fmtNum(f.score, 2)}</span>
+            </span>
+          </li>
+        ))}
+      </ol>
+      {functions.length > initial && (
+        <button type="button" className="btn btn--ghost btn--sm btn--block" onClick={() => setAll((a) => !a)}>
+          {all ? 'Show fewer' : `Show all ${functions.length} annotations`}
+        </button>
+      )}
+    </>
+  );
+}
+
+/**
+ * Sequence in blocks of 10; residues outside the resolved ranges are dimmed.
+ * A coverage track above shows modelled segments at a glance.
+ */
+export function SequenceTrack({
+  sequence,
+  ranges,
+  fastaHeader,
+  fileName,
+}: {
+  sequence: string;
+  ranges?: Array<[number, number]>;
+  fastaHeader: string;
+  fileName: string;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  if (!sequence) return <EmptyState title="No sequence available" />;
+  const L = sequence.length;
+  const resolved = new Uint8Array(L);
+  for (const [a, b] of ranges ?? []) for (let i = Math.max(1, a); i <= Math.min(L, b); i++) resolved[i - 1] = 1;
+  const hasRanges = !!ranges?.length;
+  const perLine = 50;
+  const lines = Math.ceil(L / perLine);
+  const shownLines = expanded ? lines : Math.min(lines, 8);
+
+  const download = () => {
+    const body = sequence.match(/.{1,60}/g)?.join('\n') ?? sequence;
+    const blob = new Blob([`>${fastaHeader}\n${body}\n`], { type: 'text/plain' });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = fileName;
+    a.click();
+    URL.revokeObjectURL(url);
+  };
+
+  return (
+    <div className="seqtrack">
+      <div className="seqtrack__bar">
+        <div className="seqtrack__actions">
+          <CopyButton text={sequence} label="Copy" />
+          <button type="button" className="btn btn--ghost btn--sm" onClick={download}>
+            <Download aria-hidden /> FASTA
+          </button>
+        </div>
+      </div>
+      {hasRanges && (
+        <div className="coverage-track" aria-label="Resolved residues">
+          {(ranges ?? []).map(([a, b]) => (
+            <span
+              key={`${a}-${b}`}
+              className="coverage-track__seg"
+              style={{ left: `${((a - 1) / L) * 100}%`, width: `${((b - a + 1) / L) * 100}%` }}
+              title={`Resolved ${a}–${b}`}
+            />
+          ))}
+          <span className="coverage-track__labels">
+            <span>1</span>
+            <span>{L}</span>
+          </span>
+        </div>
+      )}
+      <div className="seqtrack__body mono">
+        {Array.from({ length: shownLines }, (_, li) => {
+          const start = li * perLine;
+          const blocks = [];
+          for (let b = 0; b < perLine && start + b < L; b += 10) {
+            const chars = [];
+            for (let k = 0; k < 10 && start + b + k < L; k++) {
+              const i = start + b + k;
+              chars.push(
+                <span key={i} className={hasRanges && !resolved[i] ? 'res-off' : undefined}>
+                  {sequence[i]}
+                </span>,
+              );
+            }
+            blocks.push(
+              <span key={b} className="seqtrack__block">
+                {chars}
+              </span>,
+            );
+          }
+          return (
+            <div key={li} className="seqtrack__line">
+              <span className="seqtrack__num tabular">{start + 1}</span>
+              <span className="seqtrack__res">{blocks}</span>
+            </div>
+          );
+        })}
+      </div>
+      <div className="seqtrack__foot">
+        {hasRanges && (
+          <span className="muted">
+            <span className="res-key" /> dimmed residues are not modelled in this structure
+          </span>
+        )}
+        {lines > 8 && (
+          <button type="button" className="btn btn--ghost btn--sm" onClick={() => setExpanded((e) => !e)}>
+            {expanded ? 'Collapse' : `Show all ${L} residues`}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

frontend/src/components/SearchBox.tsx

@@ -0,0 +1,189 @@
+import { useEffect, useId, useRef, useState } from 'react';
+import { useNavigate } from 'react-router-dom';
+import { Search, X, CornerDownLeft, Layers, Box, FileText } from 'lucide-react';
+import { api, type SearchResponse } from '../lib/api';
+import { useDebounced } from '../lib/hooks';
+import { chainLabel, chainPath, cleanFunction, sequencePath } from '../lib/format';
+
+const CHAIN_RE = /^([0-9][A-Za-z0-9]{3})\s*[.:_\s/-]\s*([A-Za-z0-9]{1,4})$/;
+
+interface Suggestion {
+  key: string;
+  to: string;
+  icon: 'chain' | 'sequence' | 'text';
+  primary: string;
+  secondary?: string;
+}
+
+function toSuggestions(r: SearchResponse): Suggestion[] {
+  const out: Suggestion[] = [];
+  for (const c of r.chains.slice(0, 8)) {
+    out.push({
+      key: `c-${c.pdb_id}-${c.auth_asym_id}`,
+      to: chainPath(c.pdb_id, c.auth_asym_id),
+      icon: 'chain',
+      primary: chainLabel(c.pdb_id, c.auth_asym_id),
+      secondary: [c.uniprot_id, c.sequence_id, c.state_id != null ? `state ${c.state_id}` : null].filter(Boolean).join(' · '),
+    });
+  }
+  for (const s of r.sequences.slice(0, 8)) {
+    out.push({
+      key: `s-${s.sequence_id}`,
+      to: sequencePath(s.sequence_id),
+      icon: 'sequence',
+      primary: `${s.sequence_id}${s.uniprot_id ? ` · ${s.uniprot_id}` : ''}`,
+      secondary: `${s.n_obs.toLocaleString()} observations · ${s.n_states.toLocaleString()} states${
+        s.top_function ? ` — ${cleanFunction(s.top_function)}` : ''
+      }`,
+    });
+  }
+  return out;
+}
+
+export function SearchBox({
+  size = 'md',
+  autoFocus = false,
+  placeholder = 'Search a chain (3vgk.A), PDB entry, UniProt, SEQ ID or function…',
+}: {
+  size?: 'md' | 'lg';
+  autoFocus?: boolean;
+  placeholder?: string;
+}) {
+  const navigate = useNavigate();
+  const [value, setValue] = useState('');
+  const [open, setOpen] = useState(false);
+  const [active, setActive] = useState(-1);
+  const [items, setItems] = useState<Suggestion[]>([]);
+  const [loading, setLoading] = useState(false);
+  const debounced = useDebounced(value.trim(), 220);
+  const listId = useId();
+  const wrapRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (debounced.length < 2) {
+      setItems([]);
+      return;
+    }
+    const controller = new AbortController();
+    setLoading(true);
+    api
+      .search(debounced, controller.signal)
+      .then((r) => {
+        setItems(toSuggestions(r));
+        setActive(-1);
+      })
+      .catch(() => {
+        if (!controller.signal.aborted) setItems([]);
+      })
+      .finally(() => {
+        if (!controller.signal.aborted) setLoading(false);
+      });
+    return () => controller.abort();
+  }, [debounced]);
+
+  useEffect(() => {
+    const onDoc = (e: MouseEvent) => {
+      if (!wrapRef.current?.contains(e.target as Node)) setOpen(false);
+    };
+    document.addEventListener('mousedown', onDoc);
+    return () => document.removeEventListener('mousedown', onDoc);
+  }, []);
+
+  const go = (to: string) => {
+    setOpen(false);
+    setValue('');
+    navigate(to);
+  };
+
+  const submit = () => {
+    if (active >= 0 && items[active]) return go(items[active].to);
+    const q = value.trim();
+    if (!q) return;
+    const m = CHAIN_RE.exec(q);
+    if (m) return go(chainPath(m[1], m[2]));
+    go(`/search?q=${encodeURIComponent(q)}`);
+  };
+
+  const showList = open && value.trim().length >= 2;
+
+  return (
+    <div className={`search search--${size}`} ref={wrapRef}>
+      <form
+        role="search"
+        onSubmit={(e) => {
+          e.preventDefault();
+          submit();
+        }}
+      >
+        <Search className="search__icon" aria-hidden />
+        <input
+          type="search"
+          value={value}
+          autoFocus={autoFocus}
+          placeholder={placeholder}
+          aria-label="Search MuSProt"
+          aria-expanded={showList}
+          aria-controls={listId}
+          aria-autocomplete="list"
+          role="combobox"
+          autoComplete="off"
+          spellCheck={false}
+          onFocus={() => setOpen(true)}
+          onChange={(e) => {
+            setValue(e.target.value);
+            setOpen(true);
+          }}
+          onKeyDown={(e) => {
+            if (e.key === 'ArrowDown') {
+              e.preventDefault();
+              setActive((a) => Math.min(items.length - 1, a + 1));
+            } else if (e.key === 'ArrowUp') {
+              e.preventDefault();
+              setActive((a) => Math.max(-1, a - 1));
+            } else if (e.key === 'Escape') {
+              setOpen(false);
+            }
+          }}
+        />
+        {value && (
+          <button type="button" className="search__clear" aria-label="Clear" onClick={() => setValue('')}>
+            <X aria-hidden />
+          </button>
+        )}
+        <button type="submit" className="search__submit">
+          Search
+        </button>
+      </form>
+      {showList && (
+        <div className="search__pop" id={listId} role="listbox">
+          {loading && items.length === 0 && <div className="search__hint">Searching…</div>}
+          {!loading && items.length === 0 && (
+            <div className="search__hint">
+              Press <kbd>Enter</kbd> to search all fields for “{value.trim()}”
+            </div>
+          )}
+          {items.map((it, i) => (
+            <button
+              key={it.key}
+              type="button"
+              role="option"
+              aria-selected={i === active}
+              className={`search__item ${i === active ? 'is-active' : ''}`}
+              onMouseEnter={() => setActive(i)}
+              onClick={() => go(it.to)}
+            >
+              <span className={`search__kind search__kind--${it.icon}`}>
+                {it.icon === 'chain' ? <Box aria-hidden /> : it.icon === 'sequence' ? <Layers aria-hidden /> : <FileText aria-hidden />}
+              </span>
+              <span className="search__text">
+                <span className="search__primary mono">{it.primary}</span>
+                {it.secondary && <span className="search__secondary">{it.secondary}</span>}
+              </span>
+              {i === active && <CornerDownLeft className="search__enter" aria-hidden />}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

frontend/src/components/SequenceTable.tsx

@@ -0,0 +1,113 @@
+import { useNavigate } from 'react-router-dom';
+import type { SequenceSummary } from '../lib/api';
+import { cleanFunction, fmtInt, methodShort, sequencePath, year } from '../lib/format';
+import { MiniSplit } from './charts';
+
+export type SortKey = 'sequence' | 'length' | 'observations' | 'states' | 'entries' | 'released';
+
+function Th({
+  k,
+  label,
+  sort,
+  order,
+  onSort,
+  num,
+}: {
+  k: SortKey;
+  label: string;
+  sort?: SortKey;
+  order?: 'asc' | 'desc';
+  onSort?: (k: SortKey) => void;
+  num?: boolean;
+}) {
+  const active = sort === k;
+  if (!onSort) return <th className={num ? 'num' : ''}>{label}</th>;
+  return (
+    <th className={num ? 'num' : ''} aria-sort={active ? (order === 'asc' ? 'ascending' : 'descending') : 'none'}>
+      <button type="button" className={`th-sort ${active ? 'is-active' : ''}`} onClick={() => onSort(k)}>
+        {label}
+        <span className="th-sort__arrow" aria-hidden>
+          {active ? (order === 'asc' ? '↑' : '↓') : '↕'}
+        </span>
+      </button>
+    </th>
+  );
+}
+
+export function SequenceTable({
+  items,
+  sort,
+  order,
+  onSort,
+}: {
+  items: SequenceSummary[];
+  sort?: SortKey;
+  order?: 'asc' | 'desc';
+  onSort?: (k: SortKey) => void;
+}) {
+  const navigate = useNavigate();
+  const p = { sort, order, onSort };
+  return (
+    <div className="table-wrap">
+      <table className="table table--rows">
+        <thead>
+          <tr>
+            <Th k="sequence" label="Sequence" {...p} />
+            <th>Function</th>
+            <Th k="length" label="Length" num {...p} />
+            <Th k="observations" label="Obs." num {...p} />
+            <Th k="states" label="States" num {...p} />
+            <Th k="entries" label="Entries" num {...p} />
+            <th>Apo / holo</th>
+            <th>Methods</th>
+            <Th k="released" label="Latest" num {...p} />
+          </tr>
+        </thead>
+        <tbody>
+          {items.map((s) => (
+            <tr
+              key={s.sequence_id}
+              className="is-clickable"
+              onClick={(e) => {
+                if ((e.target as HTMLElement).closest('a')) return;
+                navigate(sequencePath(s.sequence_id));
+              }}
+            >
+              <td>
+                <a
+                  href={sequencePath(s.sequence_id)}
+                  className="mono strong"
+                  onClick={(e) => {
+                    e.preventDefault();
+                    navigate(sequencePath(s.sequence_id));
+                  }}
+                >
+                  {s.sequence_id}
+                </a>
+                <div className="sub mono">{s.uniprot_id ?? 'no UniProt'}</div>
+              </td>
+              <td className="fn-cell">
+                <span title={s.top_function ?? undefined}>{s.top_function ? cleanFunction(s.top_function) : '—'}</span>
+              </td>
+              <td className="num tabular">{fmtInt(s.length)}</td>
+              <td className="num tabular">{fmtInt(s.n_obs)}</td>
+              <td className="num tabular strong">{fmtInt(s.n_states)}</td>
+              <td className="num tabular">{fmtInt(s.n_entries)}</td>
+              <td>
+                <MiniSplit
+                  a={s.n_apo}
+                  b={s.n_holo}
+                  colorA="var(--apo)"
+                  colorB="var(--holo)"
+                  title={`${s.n_apo} apo · ${s.n_holo} holo`}
+                />
+              </td>
+              <td className="methods-cell">{s.methods.slice(0, 2).map(methodShort).join(', ')}</td>
+              <td className="num tabular">{year(s.last_release)}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  );
+}

frontend/src/components/StateGlyph.tsx

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+/** Deterministic PRNG so glyphs are stable across renders. */
+export function rng(seed: string) {
+  let h = 2166136261;
+  for (let i = 0; i < seed.length; i++) h = Math.imul(h ^ seed.charCodeAt(i), 16777619);
+  return () => {
+    h += 0x6d2b79f5;
+    let t = h;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/**
+ * A small abstract "state map": a few clusters of observations joined by
+ * transition arcs. Purely illustrative — used on cards.
+ */
+export function StateGlyph({ seed, states, size = 88 }: { seed: string; states: number; size?: number }) {
+  const g = useMemo(() => {
+    const r = rng(seed);
+    const k = Math.max(2, Math.min(5, states));
+    const cx = 50;
+    const cy = 50;
+    const centers = Array.from({ length: k }, (_, i) => {
+      const a = (i / k) * Math.PI * 2 + r() * 0.8;
+      const rad = 22 + r() * 8;
+      return { x: cx + Math.cos(a) * rad, y: cy + Math.sin(a) * rad, n: 3 + Math.floor(r() * 5) };
+    });
+    const dots = centers.flatMap((c, ci) =>
+      Array.from({ length: c.n }, () => {
+        const a = r() * Math.PI * 2;
+        const d = r() * 7;
+        return { x: c.x + Math.cos(a) * d, y: c.y + Math.sin(a) * d, ci };
+      }),
+    );
+    return { centers, dots };
+  }, [seed, states]);
+
+  return (
+    <svg width={size} height={size} viewBox="0 0 100 100" aria-hidden className="glyph">
+      {g.centers.map((a, i) =>
+        g.centers.slice(i + 1).map((b, j) => (
+          <line key={`${i}-${j}`} x1={a.x} y1={a.y} x2={b.x} y2={b.y} className="glyph__edge" />
+        )),
+      )}
+      {g.centers.map((c, i) => (
+        <circle key={i} cx={c.x} cy={c.y} r={12} className="glyph__halo" />
+      ))}
+      {g.dots.map((d, i) => (
+        <circle key={i} cx={d.x} cy={d.y} r={2.4} className={`glyph__dot glyph__dot--${d.ci % 3}`} />
+      ))}
+    </svg>
+  );
+}

frontend/src/components/StateViews.tsx

@@ -0,0 +1,229 @@
+import { useMemo, useState } from 'react';
+import type { Member, StateInfo, StatePair } from '../lib/api';
+import { FIDELITY_INFO, fidelityKey, similarityColor } from '../lib/fidelity';
+import { chainLabel, fmtNum } from '../lib/format';
+import { Tooltip, useWidth, type TipState } from './charts';
+import { Swatch } from './ui';
+
+const MAX_TILES = 40;
+const MAX_DOTS = 120;
+
+/**
+ * One tile per conformational state; each dot is one observation, coloured
+ * by ligand state. Clicking a tile selects the state.
+ */
+export function StateLandscape({
+  states,
+  members,
+  selected,
+  onSelect,
+  highlight,
+}: {
+  states: StateInfo[];
+  members: Member[];
+  selected: number | null;
+  onSelect: (s: number | null) => void;
+  highlight?: { pdb_id: string; auth_asym_id: string } | null;
+}) {
+  const byState = useMemo(() => {
+    const m = new Map<number, Member[]>();
+    for (const mem of members) {
+      const arr = m.get(mem.state_id) ?? [];
+      arr.push(mem);
+      m.set(mem.state_id, arr);
+    }
+    return m;
+  }, [members]);
+  const shown = states.slice(0, MAX_TILES);
+  const rest = states.slice(MAX_TILES);
+  const restObs = rest.reduce((s, x) => s + x.n_members, 0);
+
+  return (
+    <div className="landscape">
+      <div className="landscape__grid">
+        {shown.map((st) => {
+          const mem = byState.get(st.state_id) ?? [];
+          const holo = mem.filter((m) => m.binding_status === 'holo').length;
+          const isSel = selected === st.state_id;
+          const hasHi = highlight && mem.some((m) => m.pdb_id === highlight.pdb_id && m.auth_asym_id === highlight.auth_asym_id);
+          return (
+            <button
+              key={st.state_id}
+              type="button"
+              className={`state-tile ${isSel ? 'is-selected' : ''} ${hasHi ? 'is-home' : ''}`}
+              onClick={() => onSelect(isSel ? null : st.state_id)}
+              aria-pressed={isSel}
+              title={`State ${st.state_id}: ${st.n_members} observations (${holo} holo)`}
+            >
+              <span className="state-tile__head">
+                <span className="state-tile__name">State {st.state_id}</span>
+                <span className="state-tile__n tabular">{st.n_members.toLocaleString()}</span>
+              </span>
+              <span className="state-tile__dots">
+                {mem.slice(0, MAX_DOTS).map((m) => {
+                  const isHi = highlight && m.pdb_id === highlight.pdb_id && m.auth_asym_id === highlight.auth_asym_id;
+                  return (
+                    <span
+                      key={`${m.pdb_id}.${m.auth_asym_id}`}
+                      className={`state-dot ${m.binding_status === 'holo' ? 'is-holo' : ''} ${isHi ? 'is-hi' : ''}`}
+                    />
+                  );
+                })}
+                {mem.length > MAX_DOTS && <span className="state-tile__more">+{mem.length - MAX_DOTS}</span>}
+              </span>
+            </button>
+          );
+        })}
+      </div>
+      <div className="landscape__foot">
+        <ul className="legend">
+          <li>
+            <Swatch color="var(--apo)" shape="dot" /> Apo observation
+          </li>
+          <li>
+            <Swatch color="var(--holo)" shape="dot" /> Holo observation
+          </li>
+          {highlight && (
+            <li>
+              <span className="state-dot is-hi legend-dot" /> This chain
+            </li>
+          )}
+        </ul>
+        {rest.length > 0 && (
+          <span className="muted">
+            + {rest.length.toLocaleString()} smaller states ({restObs.toLocaleString()} observations) not shown
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/** Mean pair similarity between states (diagonal = within-state). */
+export function StateHeatmap({
+  states,
+  pairs,
+  selected,
+  onSelect,
+}: {
+  states: StateInfo[];
+  pairs: StatePair[];
+  selected: number | null;
+  onSelect: (s: number | null) => void;
+}) {
+  const [ref, width] = useWidth<HTMLDivElement>();
+  const [tip, setTip] = useState<TipState | null>(null);
+  const [hover, setHover] = useState<[number, number] | null>(null);
+  const order = states.slice(0, MAX_TILES).map((s) => s.state_id);
+  const lookup = useMemo(() => {
+    const m = new Map<string, StatePair>();
+    for (const p of pairs) {
+      m.set(`${p.a}|${p.b}`, p);
+      m.set(`${p.b}|${p.a}`, p);
+    }
+    return m;
+  }, [pairs]);
+
+  const n = order.length;
+  const label = 34;
+  const cell = n ? Math.max(8, Math.min(34, Math.floor((Math.min(width, 560) - label - 4) / n))) : 0;
+  const size = label + n * cell;
+  const showLabels = cell >= 14;
+
+  if (n < 2) return null;
+  return (
+    <div className="heatmap" ref={ref}>
+      {width > 0 && (
+        <svg width={size} height={size} role="img" aria-label="State similarity matrix">
+          {order.map((s, i) => (
+            <g key={s}>
+              {(showLabels || i % 5 === 0) && (
+                <>
+                  <text x={label - 6} y={label + i * cell + cell / 2} dy="0.32em" textAnchor="end" className="tick">
+                    {s}
+                  </text>
+                  <text x={label + i * cell + cell / 2} y={label - 8} textAnchor="middle" className="tick">
+                    {s}
+                  </text>
+                </>
+              )}
+            </g>
+          ))}
+          {order.map((a, i) =>
+            order.map((b, j) => {
+              const p = lookup.get(`${a}|${b}`);
+              const dim =
+                (selected != null && a !== selected && b !== selected) ||
+                (hover && hover[0] !== i && hover[1] !== j);
+              return (
+                <rect
+                  key={`${a}-${b}`}
+                  x={label + j * cell + 1}
+                  y={label + i * cell + 1}
+                  width={cell - 2}
+                  height={cell - 2}
+                  rx={Math.min(3, cell / 6)}
+                  fill={similarityColor(p?.similarity)}
+                  opacity={dim ? 0.35 : 1}
+                  className="heatmap__cell"
+                  onClick={() => onSelect(selected === b ? null : b)}
+                  onMouseMove={(e) => {
+                    const r = (e.currentTarget.ownerSVGElement as SVGSVGElement).getBoundingClientRect();
+                    setHover([i, j]);
+                    setTip({
+                      x: e.clientX - r.left,
+                      y: e.clientY - r.top,
+                      content: (
+                        <>
+                          <div className="chart-tip__title">
+                            {a === b ? `Within state ${a}` : `State ${a} ↔ state ${b}`}
+                          </div>
+                          <div className="chart-tip__row">
+                            <span>Mean similarity</span>
+                            <b className="tabular">{fmtNum(p?.similarity, 3)}</b>
+                          </div>
+                          {a !== b && p && (
+                            <div className="chart-tip__row">
+                              <span>Fidelity</span>
+                              <b>{FIDELITY_INFO[fidelityKey(p.fidelity)].label}</b>
+                            </div>
+                          )}
+                          <div className="chart-tip__foot">{p ? `${p.n_pairs.toLocaleString()} observation pairs` : 'No pairs'}</div>
+                        </>
+                      ),
+                    });
+                  }}
+                  onMouseLeave={() => {
+                    setTip(null);
+                    setHover(null);
+                  }}
+                />
+              );
+            }),
+          )}
+        </svg>
+      )}
+      <Tooltip tip={tip} />
+      <div className="heatmap__scale">
+        <span>Mean similarity</span>
+        {[
+          ['< 0.50', 0.4],
+          ['0.50', 0.6],
+          ['0.70', 0.8],
+          ['0.85', 0.9],
+          ['0.95', 0.96],
+          ['0.98+', 0.99],
+        ].map(([l, v]) => (
+          <span key={l as string} className="heatmap__step">
+            <Swatch color={similarityColor(v as number)} />
+            {l}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+export function memberKey(m: { pdb_id: string; auth_asym_id: string }) {
+  return chainLabel(m.pdb_id, m.auth_asym_id);
+}

frontend/src/components/StructureViewer.tsx

@@ -0,0 +1,136 @@
+import { useEffect, useRef, useState } from 'react';
+import { Box } from 'lucide-react';
+
+/* PDBe Mol* is ~6 MB, so it is loaded from the CDN only when a viewer is opened. */
+const MOLSTAR_VERSION = '3.12.0';
+const BASE = `https://cdn.jsdelivr.net/npm/pdbe-molstar@${MOLSTAR_VERSION}/build`;
+
+interface MolstarInstance {
+  render: (el: HTMLElement, options: Record<string, unknown>) => Promise<void> | void;
+  visual: { select: (params: Record<string, unknown>) => Promise<void> | void };
+  events: { loadComplete: { subscribe: (cb: (ok: boolean) => void) => { unsubscribe?: () => void } } };
+  plugin?: { dispose?: () => void };
+}
+
+declare global {
+  interface Window {
+    PDBeMolstarPlugin?: new () => MolstarInstance;
+  }
+}
+
+let loader: Promise<void> | null = null;
+function loadMolstar(): Promise<void> {
+  if (window.PDBeMolstarPlugin) return Promise.resolve();
+  if (!loader) {
+    loader = new Promise<void>((resolve, reject) => {
+      const css = document.createElement('link');
+      css.rel = 'stylesheet';
+      css.href = `${BASE}/pdbe-molstar-light.css`;
+      document.head.appendChild(css);
+      const s = document.createElement('script');
+      s.src = `${BASE}/pdbe-molstar-plugin.js`;
+      s.async = true;
+      s.onload = () => resolve();
+      s.onerror = () => {
+        loader = null;
+        reject(new Error('Could not load the Mol* viewer'));
+      };
+      document.head.appendChild(s);
+    });
+  }
+  return loader;
+}
+
+function hexToRgb(hex: string) {
+  const n = parseInt(hex.replace('#', ''), 16);
+  return { r: (n >> 16) & 255, g: (n >> 8) & 255, b: n & 255 };
+}
+
+function isDark() {
+  const t = document.documentElement.dataset.theme;
+  if (t) return t === 'dark';
+  return window.matchMedia?.('(prefers-color-scheme: dark)').matches ?? false;
+}
+
+export function StructureViewer({
+  pdbId,
+  chain,
+  color = '#2a78d6',
+  height = 380,
+  label,
+}: {
+  pdbId: string;
+  chain: string;
+  color?: string;
+  height?: number;
+  label?: string;
+}) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
+
+  useEffect(() => {
+    let alive = true;
+    let sub: { unsubscribe?: () => void } | undefined;
+    let instance: MolstarInstance | undefined;
+    const el = ref.current;
+    setStatus('loading');
+    // Mol* reports nothing when WebGL is unavailable; don't spin forever
+    const timeout = setTimeout(() => alive && setStatus((st) => (st === 'loading' ? 'error' : st)), 90000);
+    loadMolstar()
+      .then(() => {
+        if (!alive || !el || !window.PDBeMolstarPlugin) return;
+        instance = new window.PDBeMolstarPlugin();
+        sub = instance.events.loadComplete.subscribe((ok) => {
+          if (!alive) return;
+          if (ok === false) {
+            setStatus('error');
+            return;
+          }
+          setStatus('ready');
+          instance?.visual.select({
+            data: [{ auth_asym_id: chain, color: hexToRgb(color), focus: true }],
+            nonSelectedColor: isDark() ? { r: 70, g: 78, b: 92 } : { r: 214, g: 219, b: 226 },
+          });
+        });
+        const bg = isDark() ? { r: 18, g: 24, b: 33 } : { r: 255, g: 255, b: 255 };
+        instance.render(el, {
+          moleculeId: pdbId.toLowerCase(),
+          bgColor: bg,
+          hideControls: true,
+          sequencePanel: false,
+          landscape: true,
+          visualStyle: 'cartoon',
+          hideCanvasControls: ['expand', 'selection', 'animation', 'controlToggle', 'controlInfo'],
+          loadingOverlay: true,
+        });
+      })
+      .catch(() => alive && setStatus('error'));
+    return () => {
+      alive = false;
+      clearTimeout(timeout);
+      sub?.unsubscribe?.();
+      instance?.plugin?.dispose?.();
+      if (el) el.innerHTML = '';
+    };
+  }, [pdbId, chain, color]);
+
+  return (
+    <figure className="viewer" style={{ height }}>
+      <div ref={ref} className="viewer__canvas" />
+      {status !== 'ready' && (
+        <div className="viewer__overlay">
+          {status === 'loading' ? (
+            <>
+              <span className="spinner" aria-hidden /> Loading {pdbId.toUpperCase()}…
+            </>
+          ) : (
+            <>
+              <Box aria-hidden /> 3D view unavailable for {pdbId.toUpperCase()}
+            </>
+          )}
+        </div>
+      )}
+      {label && <figcaption className="viewer__label">{label}</figcaption>}
+    </figure>
+  );
+}

frontend/src/components/Transitions.tsx

@@ -0,0 +1,489 @@
+import { useMemo, useState } from 'react';
+import { ENERGY_TERMS, type EnergyTerm, type OrderChange, type Transition } from '../lib/api';
+import { FIDELITY_INFO, FIDELITY_ORDER, fidelityColor, fidelityKey } from '../lib/fidelity';
+import { chainLabel, fmtNum, fmtSigned, methodShort } from '../lib/format';
+import { niceTicks, Tooltip, useWidth, type TipState } from './charts';
+import { ChainLink, EmptyState, FidelityBadge, LigandBadge, Pagination, Segmented, Swatch } from './ui';
+
+export type Scope = 'cross' | 'same' | 'all';
+
+/* ───────────────────────────── neighbourhood scatter */
+
+export function TransitionScatter({
+  items,
+  homeState,
+  selected,
+  onSelect,
+}: {
+  items: Transition[];
+  homeState: number | null;
+  selected: string | null;
+  onSelect: (t: Transition) => void;
+}) {
+  const [ref, width] = useWidth<HTMLDivElement>();
+  const [tip, setTip] = useState<TipState | null>(null);
+  const pts = items.filter((t) => t.similarity != null && t.rmsd != null);
+  const height = 300;
+  const m = { top: 16, right: 16, bottom: 44, left: 52 };
+  const iw = Math.max(0, width - m.left - m.right);
+  const ih = height - m.top - m.bottom;
+  const xMin = Math.min(0.3, ...pts.map((p) => p.similarity!)) - 0.02;
+  const xMax = 1;
+  const yTicks = niceTicks(Math.max(2, ...pts.map((p) => p.rmsd!)));
+  const yMax = yTicks[yTicks.length - 1];
+  const x = (v: number) => ((v - xMin) / (xMax - xMin)) * iw;
+  const y = (v: number) => ih - (v / yMax) * ih;
+  const xTicks = [0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1].filter((t) => t >= xMin);
+  // draw larger changes last so they sit on top
+  const ordered = [...pts].sort((a, b) => (b.similarity ?? 0) - (a.similarity ?? 0));
+
+  return (
+    <div className="chart scatter" ref={ref}>
+      {width > 0 && (
+        <svg width={width} height={height} role="img" aria-label="Similarity versus RMSD for every partner observation">
+          <g transform={`translate(${m.left},${m.top})`}>
+            {[0.5, 0.7, 0.95].filter((t) => t > xMin).map((t) => (
+              <g key={t}>
+                <line x1={x(t)} x2={x(t)} y1={0} y2={ih} className="threshold" />
+              </g>
+            ))}
+            {yTicks.map((t) => (
+              <g key={t}>
+                <line x1={0} x2={iw} y1={y(t)} y2={y(t)} className={t === 0 ? 'axis-line' : 'grid-line'} />
+                <text x={-8} y={y(t)} dy="0.32em" textAnchor="end" className="tick">
+                  {Number.isInteger(t) ? t : t.toFixed(1)}
+                </text>
+              </g>
+            ))}
+            {xTicks.map((t) => (
+              <text key={t} x={x(t)} y={ih + 16} textAnchor="middle" className="tick">
+                {t.toFixed(1)}
+              </text>
+            ))}
+            <text x={iw / 2} y={ih + 36} textAnchor="middle" className="axis-title">
+              Pair similarity (aligned core) →  more similar
+            </text>
+            <text transform={`translate(${-38},${ih / 2}) rotate(-90)`} textAnchor="middle" className="axis-title">
+              RMSD (Å)
+            </text>
+            {ordered.map((p) => {
+              const key = chainLabel(p.pdb_id, p.auth_asym_id);
+              const same = p.state_id === homeState;
+              const isSel = key === selected;
+              return (
+                <circle
+                  key={key}
+                  cx={x(p.similarity!)}
+                  cy={y(p.rmsd!)}
+                  r={isSel ? 7 : 4.5}
+                  fill={same ? 'var(--surface)' : fidelityColor(p.fidelity)}
+                  stroke={same ? 'var(--faint)' : 'var(--surface)'}
+                  strokeWidth={same ? 1.5 : 1.5}
+                  className={`scatter__pt ${isSel ? 'is-sel' : ''}`}
+                  onClick={() => onSelect(p)}
+                  onMouseMove={(e) => {
+                    const r = (e.currentTarget.ownerSVGElement as SVGSVGElement).getBoundingClientRect();
+                    setTip({
+                      x: e.clientX - r.left,
+                      y: e.clientY - r.top,
+                      content: (
+                        <>
+                          <div className="chart-tip__title mono">{key}</div>
+                          <div className="chart-tip__row">
+                            <span>State</span>
+                            <b>{p.state_id ?? '—'}{same ? ' (same)' : ''}</b>
+                          </div>
+                          <div className="chart-tip__row">
+                            <span>Similarity</span>
+                            <b className="tabular">{fmtNum(p.similarity, 3)}</b>
+                          </div>
+                          <div className="chart-tip__row">
+                            <span>RMSD</span>
+                            <b className="tabular">{fmtNum(p.rmsd, 2)} Å</b>
+                          </div>
+                          <div className="chart-tip__row">
+                            <span>Fidelity</span>
+                            <b>{FIDELITY_INFO[fidelityKey(p.fidelity)].label}</b>
+                          </div>
+                          <div className="chart-tip__foot">Click to compare</div>
+                        </>
+                      ),
+                    });
+                  }}
+                  onMouseLeave={() => setTip(null)}
+                />
+              );
+            })}
+          </g>
+        </svg>
+      )}
+      <Tooltip tip={tip} />
+      <ul className="legend">
+        <li>
+          <span className="swatch swatch--dot swatch--ring" /> Same state
+        </li>
+        {FIDELITY_ORDER.filter((f) => f !== 'identical').map((f) => (
+          <li key={f}>
+            <Swatch color={fidelityColor(f)} shape="dot" /> {FIDELITY_INFO[f].label} fidelity
+          </li>
+        ))}
+        <li className="muted">Lines at 0.50 / 0.70 / 0.95 mark the fidelity bins</li>
+      </ul>
+    </div>
+  );
+}
+
+/* ───────────────────────────── table */
+
+type SortKey = 'similarity' | 'tm_aln' | 'rmsd' | 'coverage' | 'state' | 'resolution' | 'date' | 'order' | EnergyTerm;
+const PAGE = 25;
+
+function sortValue(t: Transition, k: SortKey): number | string | null {
+  switch (k) {
+    case 'similarity':
+      return t.similarity;
+    case 'tm_aln':
+      return t.tm_aln;
+    case 'rmsd':
+      return t.rmsd;
+    case 'coverage':
+      return t.coverage;
+    case 'state':
+      return t.state_id;
+    case 'resolution':
+      return t.resolution ?? null;
+    case 'date':
+      return t.release_date ?? null;
+    case 'order':
+      return t.order.valid ? (t.order.n_ordered ?? 0) + (t.order.n_disordered ?? 0) : null;
+    default:
+      return t.delta[k];
+  }
+}
+
+export function TransitionsTable({
+  items,
+  homeState,
+  selected,
+  onSelect,
+  scope,
+  onScope,
+}: {
+  items: Transition[];
+  homeState: number | null;
+  selected: string | null;
+  onSelect: (t: Transition) => void;
+  scope: Scope;
+  onScope: (s: Scope) => void;
+}) {
+  const [fid, setFid] = useState<string>('all');
+  const [sort, setSort] = useState<{ k: SortKey; dir: 1 | -1 }>({ k: 'similarity', dir: 1 });
+  const [page, setPage] = useState(0);
+
+  const nSame = items.filter((t) => t.state_id === homeState).length;
+  const scoped = useMemo(
+    () =>
+      items.filter((t) =>
+        scope === 'all' ? true : scope === 'same' ? t.state_id === homeState : t.state_id !== homeState,
+      ),
+    [items, scope, homeState],
+  );
+  const rows = useMemo(() => {
+    const r = fid === 'all' ? scoped : scoped.filter((t) => fidelityKey(t.fidelity) === fid);
+    return [...r].sort((a, b) => {
+      const va = sortValue(a, sort.k);
+      const vb = sortValue(b, sort.k);
+      if (va == null) return 1;
+      if (vb == null) return -1;
+      return (va < vb ? -1 : va > vb ? 1 : 0) * sort.dir;
+    });
+  }, [scoped, fid, sort]);
+  const fidCounts = useMemo(() => {
+    const c: Record<string, number> = {};
+    for (const t of scoped) c[fidelityKey(t.fidelity)] = (c[fidelityKey(t.fidelity)] ?? 0) + 1;
+    return c;
+  }, [scoped]);
+
+  const th = (k: SortKey, label: string, num = true) => (
+    <th className={num ? 'num' : ''} aria-sort={sort.k === k ? (sort.dir === 1 ? 'ascending' : 'descending') : 'none'}>
+      <button
+        type="button"
+        className={`th-sort ${sort.k === k ? 'is-active' : ''}`}
+        onClick={() => {
+          setSort((s) => ({ k, dir: s.k === k ? ((-s.dir) as 1 | -1) : 1 }));
+          setPage(0);
+        }}
+      >
+        {label}
+        <span className="th-sort__arrow" aria-hidden>
+          {sort.k === k ? (sort.dir === 1 ? '↑' : '↓') : '↕'}
+        </span>
+      </button>
+    </th>
+  );
+
+  const fidOptions = [
+    { value: 'all', label: 'Any fidelity', count: scoped.length },
+    ...[...FIDELITY_ORDER, 'NA']
+      .filter((f) => fidCounts[f])
+      .map((f) => ({ value: f, label: FIDELITY_INFO[f].label, count: fidCounts[f] })),
+  ];
+
+  return (
+    <>
+      <div className="table-toolbar table-toolbar--wrap">
+        <Segmented
+          label="Partner scope"
+          value={scope}
+          onChange={(v) => {
+            onScope(v);
+            setFid('all');
+            setPage(0);
+          }}
+          options={[
+            { value: 'cross', label: 'Other states', count: items.length - nSame },
+            { value: 'same', label: 'Same state', count: nSame },
+            { value: 'all', label: 'All', count: items.length },
+          ]}
+        />
+        <Segmented
+          label="Fidelity"
+          value={fid}
+          onChange={(v) => {
+            setFid(v);
+            setPage(0);
+          }}
+          options={fidOptions}
+        />
+      </div>
+      {rows.length === 0 ? (
+        <EmptyState title="No partner observations in this view" />
+      ) : (
+        <div className="table-wrap">
+          <table className="table table--dense table--rows">
+            <thead>
+              <tr>
+                <th>Partner</th>
+                {th('state', 'State')}
+                <th>Fidelity</th>
+                {th('similarity', 'Similarity')}
+                {th('tm_aln', 'TM (aln)')}
+                {th('rmsd', 'RMSD Å')}
+                {th('coverage', 'Coverage')}
+                {th('order', 'Order Δ')}
+                {ENERGY_TERMS.map((e) => th(e, `Δ${e}`))}
+                <th>Method</th>
+                {th('resolution', 'Res. Å')}
+                <th>Ligand</th>
+                {th('date', 'Released')}
+              </tr>
+            </thead>
+            <tbody>
+              {rows.slice(page * PAGE, (page + 1) * PAGE).map((t) => {
+                const key = chainLabel(t.pdb_id, t.auth_asym_id);
+                return (
+                  <tr
+                    key={key}
+                    className={`is-clickable ${key === selected ? 'is-selected' : ''}`}
+                    onClick={(e) => {
+                      if ((e.target as HTMLElement).closest('a')) return;
+                      onSelect(t);
+                    }}
+                  >
+                    <td>
+                      <ChainLink pdb={t.pdb_id} chain={t.auth_asym_id} strong />
+                    </td>
+                    <td className="num tabular">{t.state_id ?? '—'}</td>
+                    <td>
+                      <FidelityBadge value={t.fidelity} />
+                    </td>
+                    <td className="num tabular strong">{fmtNum(t.similarity, 3)}</td>
+                    <td className="num tabular">{fmtNum(t.tm_aln, 3)}</td>
+                    <td className="num tabular">{fmtNum(t.rmsd, 2)}</td>
+                    <td className="num tabular">{fmtNum(t.coverage, 2)}</td>
+                    <td className="num">
+                      <OrderCell order={t.order} />
+                    </td>
+                    {ENERGY_TERMS.map((e) => {
+                      const v = t.delta[e];
+                      return (
+                        <td key={e} className={`num tabular delta ${v == null ? '' : v > 0 ? 'delta--up' : v < 0 ? 'delta--down' : ''}`}>
+                          {fmtSigned(v, 1)}
+                        </td>
+                      );
+                    })}
+                    <td>{methodShort(t.experimental_method)}</td>
+                    <td className="num tabular">{fmtNum(t.resolution, 2)}</td>
+                    <td>
+                      <LigandBadge status={t.binding_status} />
+                    </td>
+                    <td className="num tabular">{t.release_date ?? '—'}</td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        </div>
+      )}
+      <Pagination page={page} pageSize={PAGE} total={rows.length} pageCount={Math.ceil(rows.length / PAGE)} onPage={setPage} />
+    </>
+  );
+}
+
+/* ───────────────────────────── energy deltas (diverging bars) */
+
+export function DeltaBars({ delta }: { delta: Record<EnergyTerm, number | null> }) {
+  const vals = ENERGY_TERMS.map((e) => delta[e]).filter((v): v is number => v != null);
+  const max = Math.max(1, ...vals.map(Math.abs));
+  return (
+    <ul className="deltas">
+      {ENERGY_TERMS.map((e) => {
+        const v = delta[e];
+        const w = v == null ? 0 : (Math.abs(v) / max) * 50;
+        return (
+          <li key={e}>
+            <span className="deltas__label">Δ{e}</span>
+            <span className="deltas__track">
+              <span className="deltas__mid" />
+              {v != null && (
+                <span
+                  className={`deltas__bar ${v > 0 ? 'is-up' : 'is-down'}`}
+                  style={v > 0 ? { left: '50%', width: `${w}%` } : { right: '50%', width: `${w}%` }}
+                />
+              )}
+            </span>
+            <span className={`deltas__val tabular ${v == null ? '' : v > 0 ? 'delta--up' : 'delta--down'}`}>
+              {fmtSigned(v, 1)}
+            </span>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+
+/* ───────────────────────────── observed order / disorder */
+
+export const ORDER_REASON: Record<string, string> = {
+  cross_method: 'different experimental methods',
+  nmr: 'both are NMR ensembles',
+  no_shared_residues: 'no shared resolved residues',
+  missing_data: 'missing data',
+};
+
+export const EVIDENCE_LABEL: Record<string, string> = {
+  high: 'High evidence',
+  medium: 'Medium evidence',
+  low: 'Low evidence',
+  not_applicable: 'No ordering',
+};
+
+function OrderCell({ order }: { order: OrderChange }) {
+  if (!order.valid) {
+    return (
+      <span className="muted small" title={`Not comparable: ${ORDER_REASON[order.reason ?? ''] ?? order.reason ?? 'n/a'}`}>
+        n/a
+      </span>
+    );
+  }
+  const plus = order.n_ordered ?? 0;
+  const minus = order.n_disordered ?? 0;
+  if (!plus && !minus) return <span className="muted">0</span>;
+  return (
+    <span className="order-cell" title={EVIDENCE_LABEL[order.evidence ?? ''] ?? ''}>
+      {plus > 0 && <span className="order-cell__plus tabular">+{plus}</span>}
+      {minus > 0 && <span className="order-cell__minus tabular">−{minus}</span>}
+      {order.evidence && order.evidence !== 'not_applicable' && (
+        <span className={`evid evid--${order.evidence}`}>{order.evidence}</span>
+      )}
+    </span>
+  );
+}
+
+function fmtRanges(r: Array<[number, number]>, max = 8): string {
+  const parts = r.map(([a, b]) => (a === b ? `${a}` : `${a}–${b}`));
+  return parts.length > max ? `${parts.slice(0, max).join(', ')} … (+${parts.length - max})` : parts.join(', ');
+}
+
+/**
+ * Residues resolved in the partner but not in this chain ("ordered") and the reverse
+ * ("disordered"), on the SEQRES axis. Resolved-state sense, not intrinsic disorder.
+ */
+export function OrderChangeView({ order, length, from, to }: { order: OrderChange; length: number; from: string; to: string }) {
+  const L = Math.max(1, length);
+  return (
+    <div className="orderview">
+      <h3 className="compare__sub">Order ↔ disorder (resolved residues)</h3>
+      {!order.valid ? (
+        <p className="muted small">
+          Not comparable for this pair: {ORDER_REASON[order.reason ?? ''] ?? order.reason ?? 'unknown'}. Resolved-residue
+          changes are only reported between structures solved with the same method.
+        </p>
+      ) : !order.n_ordered && !order.n_disordered ? (
+        <p className="muted small">
+          Both structures resolve the same residues ({order.n_shared_resolved?.toLocaleString() ?? '—'} shared).
+        </p>
+      ) : (
+        <>
+          <div className="orderview__stats">
+            <span>
+              <span className="swatch" style={{ background: 'var(--ord)' }} /> <b className="tabular">{order.n_ordered ?? 0}</b> residues
+              ordered in {to}
+              {order.longest_ordered ? <span className="muted"> (longest {order.longest_ordered})</span> : null}
+            </span>
+            <span>
+              <span className="swatch" style={{ background: 'var(--disord)' }} /> <b className="tabular">{order.n_disordered ?? 0}</b>{' '}
+              residues resolved only in {from}
+              {order.longest_disordered ? <span className="muted"> (longest {order.longest_disordered})</span> : null}
+            </span>
+            {order.evidence && order.evidence !== 'not_applicable' && (
+              <span>
+                <span className={`evid evid--${order.evidence}`}>{EVIDENCE_LABEL[order.evidence]}</span>
+                <span className="muted">
+                  {' '}
+                  {order.n_internal_ordered ?? 0} internal · {order.n_terminal_ordered ?? 0} terminal
+                </span>
+              </span>
+            )}
+            {order.with_ligand_change && <span className="badge badge--outline">Co-occurs with a ligand change</span>}
+          </div>
+          <div className="order-track" aria-label="Order changes along the sequence">
+            {order.ordered_ranges.map(([a, b]) => (
+              <span
+                key={`o${a}`}
+                className="order-track__seg order-track__seg--ord"
+                style={{ left: `${((a - 1) / L) * 100}%`, width: `${Math.max(0.4, ((b - a + 1) / L) * 100)}%` }}
+                title={`Ordered in ${to}: ${a}–${b}`}
+              />
+            ))}
+            {order.disordered_ranges.map(([a, b]) => (
+              <span
+                key={`d${a}`}
+                className="order-track__seg order-track__seg--dis"
+                style={{ left: `${((a - 1) / L) * 100}%`, width: `${Math.max(0.4, ((b - a + 1) / L) * 100)}%` }}
+                title={`Resolved only in ${from}: ${a}–${b}`}
+              />
+            ))}
+            <span className="order-track__labels">
+              <span>1</span>
+              <span>{L}</span>
+            </span>
+          </div>
+          <p className="muted small orderview__ranges">
+            {order.ordered_ranges.length > 0 && (
+              <>
+                Ordered: <span className="mono">{fmtRanges(order.ordered_ranges)}</span>
+              </>
+            )}
+            {order.ordered_ranges.length > 0 && order.disordered_ranges.length > 0 && ' · '}
+            {order.disordered_ranges.length > 0 && (
+              <>
+                Only in {from}: <span className="mono">{fmtRanges(order.disordered_ranges)}</span>
+              </>
+            )}
+          </p>
+        </>
+      )}
+    </div>
+  );
+}

frontend/src/components/charts.tsx

@@ -0,0 +1,349 @@
+import { useLayoutEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { fmtCompact, fmtShare } from '../lib/format';
+import { Swatch } from './ui';
+
+/* ───────────────────────────── helpers */
+
+function useWidth<T extends HTMLElement>(): [React.RefObject<T>, number] {
+  const ref = useRef<T>(null);
+  const [w, setW] = useState(0);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    setW(el.clientWidth);
+    const ro = new ResizeObserver(([entry]) => setW(Math.floor(entry.contentRect.width)));
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  return [ref, w];
+}
+
+/** Round tick step ≈ v/4 (1, 2, 2.5, 5 × 10ⁿ) and the axis max it implies. */
+function niceTicks(v: number, target = 4): number[] {
+  if (v <= 0) return [0, 1];
+  const raw = v / target;
+  const exp = Math.pow(10, Math.floor(Math.log10(raw)));
+  const f = raw / exp;
+  const step = (f <= 1 ? 1 : f <= 2 ? 2 : f <= 2.5 ? 2.5 : f <= 5 ? 5 : 10) * exp;
+  const n = Math.ceil(v / step - 1e-9);
+  return Array.from({ length: n + 1 }, (_, i) => i * step);
+}
+
+function niceMax(v: number): number {
+  if (v <= 0) return 1;
+  const exp = Math.pow(10, Math.floor(Math.log10(v)));
+  const f = v / exp;
+  const nf = f <= 1 ? 1 : f <= 2 ? 2 : f <= 2.5 ? 2.5 : f <= 5 ? 5 : 10;
+  return nf * exp;
+}
+
+/** Bar path: square at the baseline, 4px rounded data-end. */
+function colPath(x: number, y: number, w: number, h: number, r = 4): string {
+  if (h <= 0) return '';
+  const rr = Math.min(r, w / 2, h);
+  return `M${x},${y + h}V${y + rr}Q${x},${y} ${x + rr},${y}H${x + w - rr}Q${x + w},${y} ${x + w},${y + rr}V${y + h}Z`;
+}
+
+function barPath(x: number, y: number, w: number, h: number, r = 4): string {
+  if (w <= 0) return '';
+  const rr = Math.min(r, h / 2, w);
+  return `M${x},${y}H${x + w - rr}Q${x + w},${y} ${x + w},${y + rr}V${y + h - rr}Q${x + w},${y + h} ${x + w - rr},${y + h}H${x}Z`;
+}
+
+interface TipState {
+  x: number;
+  y: number;
+  content: ReactNode;
+}
+
+function Tooltip({ tip }: { tip: TipState | null }) {
+  if (!tip) return null;
+  return (
+    <div className="chart-tip" style={{ left: tip.x, top: tip.y }} role="tooltip">
+      {tip.content}
+    </div>
+  );
+}
+
+export interface Series {
+  key: string;
+  label: string;
+  color: string;
+  values: number[];
+}
+
+/* ───────────────────────────── column chart (optionally stacked) */
+
+export function ColumnChart({
+  labels,
+  series,
+  height = 220,
+  xTitle,
+  yTitle,
+  tickEvery,
+  format = fmtCompact,
+  tipLabel,
+}: {
+  labels: string[];
+  series: Series[];
+  height?: number;
+  xTitle?: string;
+  yTitle?: string;
+  tickEvery?: number;
+  format?: (n: number) => string;
+  tipLabel?: (i: number) => string;
+}) {
+  const [ref, width] = useWidth<HTMLDivElement>();
+  const [tip, setTip] = useState<TipState | null>(null);
+  const [hover, setHover] = useState<number | null>(null);
+
+  const totals = useMemo(
+    () => labels.map((_, i) => series.reduce((s, se) => s + (se.values[i] || 0), 0)),
+    [labels, series],
+  );
+  const grand = totals.reduce((a, b) => a + b, 0);
+  const yTicks = niceTicks(Math.max(...totals, 0));
+  const max = yTicks[yTicks.length - 1];
+  const m = { top: 12, right: 8, bottom: xTitle ? 44 : 28, left: 48 };
+  const iw = Math.max(0, width - m.left - m.right);
+  const ih = height - m.top - m.bottom;
+  const band = labels.length ? iw / labels.length : 0;
+  const bw = Math.max(2, Math.min(24, band - 2));
+  const every = tickEvery ?? Math.max(1, Math.ceil(labels.length / Math.max(1, Math.floor(iw / 44))));
+
+  return (
+    <div className="chart" ref={ref}>
+      {width > 0 && (
+        <svg width={width} height={height} role="img" aria-label={yTitle ?? 'Column chart'}>
+          <g transform={`translate(${m.left},${m.top})`}>
+            {yTicks.map((t) => {
+              const y = ih - (t / max) * ih;
+              return (
+                <g key={t}>
+                  <line x1={0} x2={iw} y1={y} y2={y} className={t === 0 ? 'axis-line' : 'grid-line'} />
+                  <text x={-8} y={y} dy="0.32em" textAnchor="end" className="tick">
+                    {format(t)}
+                  </text>
+                </g>
+              );
+            })}
+            {labels.map((lab, i) => {
+              let acc = 0;
+              const x = i * band + (band - bw) / 2;
+              const segs = series.map((se, si) => {
+                const v = se.values[i] || 0;
+                const h = (v / max) * ih;
+                const y = ih - ((acc + v) / max) * ih;
+                acc += v;
+                const isTop = series.slice(si + 1).every((s2) => !(s2.values[i] > 0));
+                const gap = si > 0 && h > 2 ? 2 : 0;
+                return (
+                  <path
+                    key={se.key}
+                    d={isTop ? colPath(x, y, bw, Math.max(0, h - gap)) : `M${x},${y}h${bw}v${Math.max(0, h - gap)}h${-bw}Z`}
+                    fill={se.color}
+                    opacity={hover === null || hover === i ? 1 : 0.55}
+                  />
+                );
+              });
+              return (
+                <g key={lab + i}>
+                  {segs}
+                  {i % every === 0 && (
+                    <text x={i * band + band / 2} y={ih + 16} textAnchor="middle" className="tick">
+                      {lab}
+                    </text>
+                  )}
+                  <rect
+                    x={i * band}
+                    y={0}
+                    width={band}
+                    height={ih}
+                    fill="transparent"
+                    onMouseMove={(e) => {
+                      const r = (e.currentTarget.ownerSVGElement as SVGSVGElement).getBoundingClientRect();
+                      setHover(i);
+                      setTip({
+                        x: e.clientX - r.left,
+                        y: e.clientY - r.top,
+                        content: (
+                          <>
+                            <div className="chart-tip__title">{tipLabel ? tipLabel(i) : lab}</div>
+                            {series.map((se) => (
+                              <div key={se.key} className="chart-tip__row">
+                                {series.length > 1 && <Swatch color={se.color} />}
+                                <span>{series.length > 1 ? se.label : 'Count'}</span>
+                                <b className="tabular">{(se.values[i] || 0).toLocaleString()}</b>
+                              </div>
+                            ))}
+                            <div className="chart-tip__foot">{fmtShare(totals[i], grand)} of total</div>
+                          </>
+                        ),
+                      });
+                    }}
+                    onMouseLeave={() => {
+                      setHover(null);
+                      setTip(null);
+                    }}
+                  />
+                </g>
+              );
+            })}
+            {xTitle && (
+              <text x={iw / 2} y={ih + 38} textAnchor="middle" className="axis-title">
+                {xTitle}
+              </text>
+            )}
+          </g>
+        </svg>
+      )}
+      <Tooltip tip={tip} />
+    </div>
+  );
+}
+
+/* ───────────────────────────── histogram over numeric bins */
+
+export function Histogram({
+  counts,
+  binWidth,
+  start = 0,
+  series,
+  xTitle,
+  height,
+  digits = 2,
+  openLast = false,
+}: {
+  counts?: number[];
+  series?: Series[];
+  binWidth: number;
+  start?: number;
+  xTitle?: string;
+  height?: number;
+  digits?: number;
+  openLast?: boolean;
+}) {
+  const n = series ? series[0].values.length : counts!.length;
+  const labels = Array.from({ length: n }, (_, i) => (start + i * binWidth).toFixed(digits).replace(/\.?0+$/, '') || '0');
+  const s = series ?? [{ key: 'count', label: 'Count', color: 'var(--accent)', values: counts! }];
+  const tickEvery = Math.max(1, Math.round(n / 5));
+  return (
+    <ColumnChart
+      labels={labels}
+      series={s}
+      xTitle={xTitle}
+      height={height}
+      tickEvery={tickEvery}
+      tipLabel={(i) => {
+        const lo = start + i * binWidth;
+        return openLast && i === n - 1 ? `≥ ${lo.toFixed(digits)}` : `${lo.toFixed(digits)} – ${(lo + binWidth).toFixed(digits)}`;
+      }}
+    />
+  );
+}
+
+/* ───────────────────────────── horizontal bar list */
+
+export function BarList({
+  items,
+  color = 'var(--accent)',
+  format = (n: number) => n.toLocaleString(),
+  max,
+}: {
+  items: Array<{ label: ReactNode; value: number; key?: string }>;
+  color?: string;
+  format?: (n: number) => string;
+  max?: number;
+}) {
+  const top = max ?? Math.max(...items.map((i) => i.value), 1);
+  const total = items.reduce((s, i) => s + i.value, 0);
+  return (
+    <ul className="barlist">
+      {items.map((it, idx) => (
+        <li key={it.key ?? idx} className="barlist__row" title={`${fmtShare(it.value, total)} of total`}>
+          <span className="barlist__label">{it.label}</span>
+          <span className="barlist__track">
+            <svg width="100%" height="10" preserveAspectRatio="none" viewBox="0 0 100 10" aria-hidden>
+              <path d={barPath(0, 0, Math.max(0.6, (it.value / top) * 100), 10, 2)} fill={color} />
+            </svg>
+          </span>
+          <span className="barlist__value tabular">{format(it.value)}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/* ───────────────────────────── 100% stacked bar with legend */
+
+export function StackedBar({
+  parts,
+  height = 14,
+  showLegend = true,
+}: {
+  parts: Array<{ key: string; label: ReactNode; value: number; color: string; note?: string }>;
+  height?: number;
+  showLegend?: boolean;
+}) {
+  const total = parts.reduce((s, p) => s + p.value, 0) || 1;
+  const [tip, setTip] = useState<TipState | null>(null);
+  return (
+    <div className="stacked">
+      <div className="stacked__bar" style={{ height }} onMouseLeave={() => setTip(null)}>
+        {parts
+          .filter((p) => p.value > 0)
+          .map((p) => (
+            <span
+              key={p.key}
+              className="stacked__seg"
+              style={{ flexGrow: p.value, background: p.color }}
+              onMouseMove={(e) => {
+                const r = (e.currentTarget.parentElement as HTMLElement).getBoundingClientRect();
+                setTip({
+                  x: e.clientX - r.left,
+                  y: e.clientY - r.top,
+                  content: (
+                    <>
+                      <div className="chart-tip__title">{p.label}</div>
+                      <div className="chart-tip__row">
+                        <b className="tabular">{p.value.toLocaleString()}</b>
+                        <span>{fmtShare(p.value, total)}</span>
+                      </div>
+                      {p.note && <div className="chart-tip__foot">{p.note}</div>}
+                    </>
+                  ),
+                });
+              }}
+            />
+          ))}
+        <Tooltip tip={tip} />
+      </div>
+      {showLegend && (
+        <ul className="legend">
+          {parts.map((p) => (
+            <li key={p.key}>
+              <Swatch color={p.color} />
+              <span>{p.label}</span>
+              <b className="tabular">{fmtShare(p.value, total)}</b>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+/* ───────────────────────────── sparkline-sized bar strip (tables) */
+
+export function MiniSplit({ a, b, colorA, colorB, title }: { a: number; b: number; colorA: string; colorB: string; title?: string }) {
+  const t = a + b || 1;
+  return (
+    <span className="minisplit" title={title}>
+      <span style={{ width: `${(a / t) * 100}%`, background: colorA }} />
+      <span style={{ width: `${(b / t) * 100}%`, background: colorB }} />
+    </span>
+  );
+}
+
+export { Tooltip, useWidth, niceMax, niceTicks };
+export type { TipState };

frontend/src/components/datasets/protein/BindersPanel.tsx

@@ -1,108 +0,0 @@
-/**
- * Binders panel for a selected chain
- * Displays nonpolymer entities (ligands/binders) with name and SMILES
- */
-import React, { useState } from 'react';
-import { ChainMetadata } from '../../../types/protein';
-import { formatText, truncateText } from '../../../utils/format';
-
-interface BindersPanelProps {
-  metadata: ChainMetadata | null;
-  isLoading?: boolean;
-}
-
-const BindersPanel: React.FC<BindersPanelProps> = ({ metadata, isLoading }) => {
-  const [copiedIndex, setCopiedIndex] = useState<number | null>(null);
-
-  const binders = metadata?.nonpolymer_entities || [];
-
-  const handleCopySmiles = async (smiles: string | null | undefined, index: number) => {
-    if (!smiles) return;
-    
-    try {
-      await navigator.clipboard.writeText(smiles);
-      setCopiedIndex(index);
-      setTimeout(() => setCopiedIndex(null), 2000);
-    } catch (err) {
-      console.error('Failed to copy SMILES:', err);
-    }
-  };
-
-  if (isLoading) {
-    return (
-      <section className="space-y-4">
-        <h3 className="text-xl font-semibold text-slate-900">Binders</h3>
-        <div className="text-center py-10 text-slate-600">Loading binders...</div>
-      </section>
-    );
-  }
-
-  if (binders.length === 0) {
-    return (
-      <section className="space-y-4">
-        <h3 className="text-xl font-semibold text-slate-900">Binders</h3>
-        <div className="text-center py-10 text-slate-600">No binder annotations available</div>
-      </section>
-    );
-  }
-
-  return (
-    <section className="space-y-4">
-      {/* Title + Count Chip */}
-      <div className="flex items-start justify-between">
-        <h3 className="text-xl font-semibold text-slate-900">Binders</h3>
-        <span className="px-3 py-1.5 bg-amber-50 text-amber-700 text-xs font-medium rounded-full border border-amber-200">
-          {binders.length} {binders.length === 1 ? 'binder' : 'binders'}
-        </span>
-      </div>
-      
-      {/* Table */}
-      <div className="overflow-x-auto rounded-lg border border-slate-200">
-        <table className="w-full text-sm">
-          <thead className="bg-slate-50 border-b border-slate-200">
-            <tr>
-              <th className="px-4 py-3 text-left text-xs font-semibold text-slate-700 uppercase tracking-wider">Name</th>
-              <th className="px-4 py-3 text-left text-xs font-semibold text-slate-700 uppercase tracking-wider">SMILES</th>
-              <th className="px-4 py-3 text-center text-xs font-semibold text-slate-700 uppercase tracking-wider w-20">Copy</th>
-            </tr>
-          </thead>
-          <tbody>
-            {binders.map((binder, idx) => {
-              const name = formatText(binder.name);
-              const smiles = formatText(binder.smiles, '');
-              const truncatedSmiles = smiles ? truncateText(smiles, 50) : '—';
-              
-              return (
-                <tr key={idx} className="border-b border-slate-100 hover:bg-slate-50 transition-colors last:border-b-0">
-                  <td className="px-4 py-3 text-slate-900 font-medium">{name}</td>
-                  <td className="px-4 py-3 text-slate-900">
-                    {smiles ? (
-                      <code className="bg-slate-100 px-2 py-1 rounded font-mono text-xs inline-block max-w-md overflow-hidden text-ellipsis whitespace-nowrap border border-slate-200" title={smiles}>
-                        {truncatedSmiles}
-                      </code>
-                    ) : (
-                      <span className="text-slate-400">—</span>
-                    )}
-                  </td>
-                  <td className="px-4 py-3 text-center">
-                    {smiles && (
-                      <button
-                        className="inline-flex items-center justify-center w-8 h-8 border border-gray-300 text-slate-700 rounded-lg hover:bg-slate-50 hover:border-slate-400 transition-colors text-sm"
-                        onClick={() => handleCopySmiles(smiles, idx)}
-                        title="Copy SMILES"
-                      >
-                        {copiedIndex === idx ? '✓' : '📋'}
-                      </button>
-                    )}
-                  </td>
-                </tr>
-              );
-            })}
-          </tbody>
-        </table>
-      </div>
-    </section>
-  );
-};
-
-export default BindersPanel;

frontend/src/components/datasets/protein/ChainBasicInfoCards.tsx

@@ -1,146 +0,0 @@
-/**
- * Basic information card for a selected chain
- * Displays: PDB ID, Protein name, Chain ID, UniProt ID in a single well-designed card
- */
-import { ChainMetadata } from '../../../types/protein';
-
-interface ChainBasicInfoCardsProps {
-  metadata: ChainMetadata | null;
-  isLoading?: boolean;
-}
-
-const ChainBasicInfoCards: React.FC<ChainBasicInfoCardsProps> = ({ metadata, isLoading }) => {
-  const getUniProtId = () => {
-    if (!metadata?.polymer_entity?.reference_sequences) return '—';
-    
-    const refSeqs = metadata.polymer_entity.reference_sequences;
-    const uniprotRefs = refSeqs.filter((ref: any) => ref.database_name === 'UniProt');
-    
-    if (uniprotRefs.length > 0) {
-      const first = uniprotRefs[0].database_accession;
-      if (uniprotRefs.length > 1) {
-        return (
-          <span title={uniprotRefs.map((r: any) => r.database_accession).join(', ')}>
-            {first} <span className="text-gray-500 text-xs">+{uniprotRefs.length - 1} more</span>
-          </span>
-        );
-      }
-      return first;
-    }
-    
-    // Fallback to first reference sequence
-    if (refSeqs.length > 0) {
-      return refSeqs[0].database_accession || '—';
-    }
-    
-    return '—';
-  };
-
-  if (isLoading) {
-    return (
-      <div className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm">
-        <div className="flex items-center gap-3">
-          <div className="w-8 h-8 border-4 border-slate-200 border-t-slate-900 rounded-full animate-spin"></div>
-          <span className="text-slate-600 text-sm">Loading chain metadata...</span>
-        </div>
-      </div>
-    );
-  }
-
-  const pdbId = metadata?.entry?.rcsb_id || metadata?.pdb_id;
-  const chainId = metadata?.chain_id || metadata?.polymer_entity_instance?.auth_asym_id;
-
-  return (
-    <div className="h-full w-full border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
-      <div className="flex items-start justify-between mb-4">
-        <h3 className="text-xl font-semibold text-slate-900">Chain Metadata</h3>
-        <div className="flex flex-wrap gap-2">
-          <span className="px-3 py-1.5 bg-blue-50 text-blue-700 text-xs font-medium rounded-full border border-blue-200">
-            {pdbId || 'N/A'}
-          </span>
-          {chainId && (
-            <span className="px-3 py-1.5 bg-purple-50 text-purple-700 text-xs font-medium rounded-full border border-purple-200">
-              Chain {chainId}
-            </span>
-          )}
-        </div>
-      </div>
-
-      {/* Chips Row */}
-
-      {/* Compact three-column metadata flow */}
-      <div className="gap-4" style={{ columnCount: 3, columnGap: '1rem' }}>
-        <div className="break-inside-avoid mb-3" style={{ breakInside: 'avoid' }}>
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Protein Name</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono" title={metadata?.entry?.title || ''}>
-            {metadata?.entry?.title || '—'}
-          </div>
-        </div>
-
-        <div className="break-inside-avoid mb-3" style={{ breakInside: 'avoid' }}>
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">PDB ID</div>
-          <div className="text-sm font-semibold text-slate-900">
-            <a 
-              href={`https://www.rcsb.org/structure/${pdbId}`}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="text-blue-600 hover:text-blue-800 font-mono hover:underline inline-flex items-center gap-1 transition-colors"
-            >
-              {pdbId || '—'}
-              <span className="text-xs">↗</span>
-            </a>
-          </div>
-        </div>
-
-        <div className="break-inside-avoid mb-3" style={{ breakInside: 'avoid' }}>
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Chain ID</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">{chainId || '—'}</div>
-        </div>
-
-        <div className="break-inside-avoid mb-3" style={{ breakInside: 'avoid' }}>
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">UniProt ID</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">{getUniProtId()}</div>
-        </div>
-
-        <div className="break-inside-avoid mb-3" style={{ breakInside: 'avoid' }}>
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Binding Status</div>
-          <div className="text-sm font-semibold text-slate-900 capitalize">{metadata?.binding_status || '—'}</div>
-        </div>
-
-        <div className="break-inside-avoid mb-3" style={{ breakInside: 'avoid' }}>
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">Chain Composition</div>
-          <div className="text-sm font-semibold text-slate-900 capitalize">{metadata?.chain_composition || '—'}</div>
-        </div>
-
-        <div className="break-inside-avoid mb-3" style={{ breakInside: 'avoid' }}>
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">CATH ID</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">{metadata?.cath_id || 'uncategorized'}</div>
-        </div>
-
-        <div className="break-inside-avoid mb-3" style={{ breakInside: 'avoid' }}>
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">CATH Domain</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">
-            {metadata?.cath_superfamily ? (
-              <a
-                href={`https://www.cathdb.info/version/latest/superfamily/${metadata.cath_superfamily}`}
-                target="_blank"
-                rel="noopener noreferrer"
-                className="text-blue-600 hover:text-blue-800 hover:underline inline-flex items-center gap-1 transition-colors"
-              >
-                {metadata.cath_superfamily}
-                <span className="text-xs">↗</span>
-              </a>
-            ) : '—'}
-          </div>
-        </div>
-
-        <div className="break-inside-avoid mb-3" style={{ breakInside: 'avoid' }}>
-          <div className="text-xs font-medium text-slate-500 uppercase tracking-wider mb-1">State ID</div>
-          <div className="text-sm font-semibold text-slate-900 font-mono">{metadata?.state_id || '—'}</div>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-export default ChainBasicInfoCards;

frontend/src/components/datasets/protein/ChainSearchInput.tsx

@@ -1,204 +0,0 @@
-import React, { useState, useEffect, useRef } from 'react';
-import type { ChainMetadata } from '../../../types/protein';
-
-type SearchStatus = 'idle' | 'typing' | 'loading' | 'success' | 'not_found' | 'error';
-
-interface ChainSearchInputProps {
-  value: string;
-  onValueChange: (value: string) => void;
-  onChainSelect: (pdb_id: string, auth_asym_id: string) => void;
-  onMetadataLoaded: (metadata: ChainMetadata) => void;
-  onClear: () => void;
-  resolveChain: (pdb_id: string, auth_asym_id: string) => Promise<ChainMetadata>;
-  searchStatus: SearchStatus;
-  resolvedLabel?: string;
-  errorMessage?: string;
-  disabled?: boolean;
-}
-
-interface ParsedChain {
-  pdb_id: string;
-  auth_asym_id: string;
-  valid: boolean;
-  error?: string;
-}
-
-export const ChainSearchInput: React.FC<ChainSearchInputProps> = ({
-  value,
-  onValueChange,
-  onChainSelect,
-  onMetadataLoaded,
-  onClear,
-  resolveChain,
-  searchStatus,
-  resolvedLabel,
-  errorMessage,
-  disabled
-}) => {
-  const [parsed, setParsed] = useState<ParsedChain | null>(null);
-  const [debouncedValue, setDebouncedValue] = useState('');
-  const lastResolvedKey = useRef<string | null>(null);
-
-  // Debounce input (500ms)
-  useEffect(() => {
-    const timer = setTimeout(() => {
-      setDebouncedValue(value);
-    }, 500);
-
-    return () => clearTimeout(timer);
-  }, [value]);
-
-  // Parse chain identifier
-  const parseChainId = (value: string): ParsedChain => {
-    const trimmed = value.trim();
-    if (!trimmed) {
-      return { pdb_id: '', auth_asym_id: '', valid: false };
-    }
-
-    // Accept formats: "3vgk.A", "3VGK:A", "3VGK_A", "3vgk A"
-    const separatorRegex = /[.\s:_]+/;
-    const parts = trimmed.split(separatorRegex);
-
-    if (parts.length < 2) {
-      return {
-        pdb_id: '',
-        auth_asym_id: '',
-        valid: false,
-        error: 'Format: PDB_ID + Chain (e.g., "3vgk.A", "3VGK:A", "3VGK_A")'
-      };
-    }
-
-    const pdb_id = parts[0].trim();
-    const auth_asym_id = parts.slice(1).join('').trim(); // Handle multi-char chain IDs
-
-    // Validate PDB ID (4 characters)
-    if (pdb_id.length !== 4) {
-      return {
-        pdb_id,
-        auth_asym_id,
-        valid: false,
-        error: 'PDB ID must be exactly 4 characters'
-      };
-    }
-
-    // Validate chain ID (at least 1 character)
-    if (auth_asym_id.length === 0) {
-      return {
-        pdb_id,
-        auth_asym_id,
-        valid: false,
-        error: 'Chain ID is required (e.g., "A", "B", "AA")'
-      };
-    }
-
-    return {
-      pdb_id: pdb_id.toLowerCase(),
-      auth_asym_id: auth_asym_id.toUpperCase(),
-      valid: true
-    };
-  };
-
-  // Parse and validate when debounced value changes
-  useEffect(() => {
-    if (!debouncedValue) {
-      setParsed(null);
-      lastResolvedKey.current = null;
-      return;
-    }
-
-    const result = parseChainId(debouncedValue);
-    setParsed(result);
-
-    if (!result.valid) {
-      return;
-    }
-
-    // Create key for this chain
-    const currentKey = `${result.pdb_id}|${result.auth_asym_id}`;
-    
-    // Only resolve if key changed (prevent duplicate requests)
-    if (currentKey === lastResolvedKey.current) {
-      return;
-    }
-    
-    lastResolvedKey.current = currentKey;
-
-    // Valid - trigger resolution (parent manages loading/error state)
-    resolveChain(result.pdb_id, result.auth_asym_id)
-      .then(metadata => {
-        onChainSelect(result.pdb_id, result.auth_asym_id);
-        onMetadataLoaded(metadata);
-      })
-      .catch(() => {
-        // Parent handles error state
-      });
-  }, [debouncedValue, resolveChain, onChainSelect, onMetadataLoaded]);
-
-  const handleClear = () => {
-    setParsed(null);
-    setDebouncedValue('');
-    lastResolvedKey.current = null;
-    onClear();
-  };
-
-  const getBorderColor = () => {
-    if (searchStatus === 'loading') return 'border-blue-400';
-    if (searchStatus === 'error' || searchStatus === 'not_found' || (parsed && !parsed.valid)) return 'border-red-400';
-    if (searchStatus === 'success') return 'border-green-400';
-    return 'border-gray-300';
-  };
-
-  const showError = searchStatus === 'error' || searchStatus === 'not_found' || (parsed && !parsed.valid && value);
-  const displayError = errorMessage || parsed?.error || 'Invalid chain identifier';
-
-  return (
-    <div className="space-y-3">
-      <label className="block">
-        <span className="text-sm font-medium text-slate-900">Chain Identifier</span>
-        <span className="block text-xs text-slate-500 mt-1">
-          Format: PDB ID + Chain (e.g., 3vgk.A, 3VGK:A, 3VGK_A, 3vgk A)
-        </span>
-      </label>
-      
-      <div className={`relative flex items-center border-2 ${getBorderColor()} rounded-lg transition-all duration-200 focus-within:ring-2 focus-within:ring-slate-900 focus-within:ring-offset-2 bg-white`}>
-        <input
-          type="text"
-          className="flex-1 px-4 py-3 text-sm text-slate-900 bg-transparent rounded-lg outline-none placeholder:text-slate-400 disabled:bg-slate-50 disabled:cursor-not-allowed"
-          value={value}
-          onChange={(e) => onValueChange(e.target.value)}
-          placeholder="e.g., 3vgk.A"
-          disabled={disabled}
-        />
-        
-        {value && searchStatus !== 'loading' && (
-          <button
-            className="absolute right-3 w-7 h-7 flex items-center justify-center text-slate-400 hover:text-slate-600 hover:bg-slate-100 rounded-md transition-colors disabled:cursor-not-allowed"
-            onClick={handleClear}
-            disabled={disabled}
-            title="Clear"
-          >
-            ✕
-          </button>
-        )}
-
-        {searchStatus === 'loading' && (
-          <div className="absolute right-3 w-5 h-5 border-2 border-slate-200 border-t-slate-900 rounded-full animate-spin" title="Resolving chain..."></div>
-        )}
-      </div>
-
-      {searchStatus === 'success' && resolvedLabel && (
-        <div className="flex items-center gap-2 text-sm text-green-700 bg-green-50 px-3 py-2 rounded-lg border border-green-200">
-          <span className="text-base">✓</span>
-          <span className="font-medium">{resolvedLabel}</span>
-        </div>
-      )}
-
-      {showError && (
-        <div className="flex items-center gap-2 text-sm text-red-700 bg-red-50 px-3 py-2 rounded-lg border border-red-200">
-          <span className="text-base">✗</span>
-          <span>{displayError}</span>
-        </div>
-      )}
-    </div>
-  );
-};

frontend/src/components/datasets/protein/DataTable.css

@@ -1,177 +0,0 @@
-.data-table-container {
-  background: white;
-  border-radius: 8px;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-  overflow: hidden;
-  display: flex;
-  flex-direction: column;
-}
-
-.table-header {
-  padding: 15px 20px;
-  border-bottom: 2px solid #e0e0e0;
-  display: flex;
-  justify-content: space-between;
-  align-items: center;
-}
-
-.table-header h3 {
-  margin: 0;
-}
-
-.table-stats {
-  display: flex;
-  gap: 10px;
-  align-items: center;
-  color: #666;
-  font-size: 0.9rem;
-}
-
-.separator {
-  color: #ccc;
-}
-
-.table-wrapper {
-  flex: 1;
-  overflow: auto;
-}
-
-.data-table {
-  width: 100%;
-  border-collapse: collapse;
-  font-size: 0.9rem;
-}
-
-.data-table thead {
-  position: sticky;
-  top: 0;
-  background: #f5f5f5;
-  z-index: 10;
-}
-
-.data-table th {
-  padding: 12px 15px;
-  text-align: left;
-  font-weight: 600;
-  color: #555;
-  border-bottom: 2px solid #e0e0e0;
-  cursor: pointer;
-  user-select: none;
-  white-space: nowrap;
-}
-
-.data-table th:hover {
-  background: #e8e8e8;
-}
-
-.data-table td {
-  padding: 10px 15px;
-  border-bottom: 1px solid #f0f0f0;
-}
-
-.data-table tbody tr:hover {
-  background: #fafafa;
-}
-
-.chain-id {
-  font-weight: 600;
-  color: #2196f3;
-}
-
-.asym-id {
-  color: #666;
-  font-size: 0.85rem;
-}
-
-.numeric {
-  text-align: right;
-  font-family: 'Courier New', monospace;
-}
-
-.cluster {
-  font-size: 0.85rem;
-  color: #666;
-  text-transform: capitalize;
-}
-
-.pagination {
-  padding: 15px 20px;
-  border-top: 1px solid #e0e0e0;
-  display: flex;
-  justify-content: center;
-  align-items: center;
-  gap: 15px;
-}
-
-.pagination button {
-  padding: 8px 16px;
-  background: #2196f3;
-  color: white;
-  border: none;
-  border-radius: 4px;
-  cursor: pointer;
-  font-size: 0.9rem;
-  transition: background 0.3s;
-}
-
-.pagination button:hover:not(:disabled) {
-  background: #1976d2;
-}
-
-.pagination button:disabled {
-  background: #ccc;
-  cursor: not-allowed;
-}
-
-.page-info {
-  color: #666;
-  font-size: 0.9rem;
-}
-
-.table-loading,
-.table-empty {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  height: 100%;
-  color: #888;
-  font-size: 1.1rem;
-  background: white;
-  border-radius: 8px;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-}
-
-.table-empty {
-  color: #999;
-}
-
-.table-hint {
-  font-size: 0.8em;
-  font-weight: normal;
-  color: #888;
-}
-
-.placeholder {
-  color: #999;
-  font-style: italic;
-}
-
-.experimental-method {
-  max-width: 200px;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.delta-cell {
-  font-family: 'Courier New', monospace;
-  text-align: right;
-}
-
-.delta-pos {
-  color: #d32f2f;
-}
-
-.delta-neg {
-  color: #2e7d32;
-}

frontend/src/components/datasets/protein/DataTable.tsx

@@ -1,214 +0,0 @@
-import React, { useState } from 'react';
-import type { DataRecord } from '../../../types/protein';
-import { formatTemperature, formatPH } from '../../../utils/format';
-import './DataTable.css';
-
-interface DataTableProps {
-  data: DataRecord[];
-  loading: boolean;
-  total: number;
-  filtered: number;
-}
-
-type SortField = keyof DataRecord;
-type SortDirection = 'asc' | 'desc';
-
-export const DataTable: React.FC<DataTableProps> = ({ data, loading, total, filtered }) => {
-  const [sortField, setSortField] = useState<SortField>('rmsd');
-  const [sortDirection, setSortDirection] = useState<SortDirection>('asc');
-  const [currentPage, setCurrentPage] = useState(1);
-  const itemsPerPage = 50;
-
-  if (loading) {
-    return <div className="table-loading">Loading data...</div>;
-  }
-
-  if (data.length === 0) {
-    return <div className="table-empty">No data to display. Adjust filters to see results.</div>;
-  }
-
-  // Sorting
-  const sortedData = [...data].sort((a, b) => {
-    const aValue = a[sortField];
-    const bValue = b[sortField];
-    
-    if (typeof aValue === 'number' && typeof bValue === 'number') {
-      return sortDirection === 'asc' ? aValue - bValue : bValue - aValue;
-    }
-    
-    if (typeof aValue === 'string' && typeof bValue === 'string') {
-      return sortDirection === 'asc' 
-        ? aValue.localeCompare(bValue)
-        : bValue.localeCompare(aValue);
-    }
-    
-    return 0;
-  });
-
-  // Pagination
-  const totalPages = Math.ceil(sortedData.length / itemsPerPage);
-  const startIndex = (currentPage - 1) * itemsPerPage;
-  const endIndex = startIndex + itemsPerPage;
-  const paginatedData = sortedData.slice(startIndex, endIndex);
-
-  const handleSort = (field: SortField) => {
-    if (sortField === field) {
-      setSortDirection(sortDirection === 'asc' ? 'desc' : 'asc');
-    } else {
-      setSortField(field);
-      setSortDirection('asc');
-    }
-    setCurrentPage(1);
-  };
-
-  const getSortIcon = (field: SortField) => {
-    if (sortField !== field) return '↕';
-    return sortDirection === 'asc' ? '↑' : '↓';
-  };
-
-  return (
-    <div className="data-table-container">
-      <div className="table-header">
-        <h3 className="text-xl font-semibold text-slate-900">Alternative observations</h3>
-        <div className="table-stats">
-          <span>Showing {paginatedData.length} of {filtered.toLocaleString()} filtered</span>
-          <span className="separator">|</span>
-          <span>Total: {total.toLocaleString()}</span>
-        </div>
-      </div>
-
-      <div className="table-wrapper">
-        <table className="data-table">
-          <thead>
-            <tr>
-              <th onClick={() => handleSort('pdb_id_b')}>
-                PDB ID {getSortIcon('pdb_id_b')}
-              </th>
-              <th onClick={() => handleSort('auth_asym_id_b')}>
-                Chain ID {getSortIcon('auth_asym_id_b')}
-              </th>
-              <th onClick={() => handleSort('tm_score')}>
-                TM-score {getSortIcon('tm_score')}
-              </th>
-              <th onClick={() => handleSort('rmsd')}>
-                RMSD (Å) {getSortIcon('rmsd')}
-              </th>
-              <th>
-                Experimental Method
-              </th>
-              <th>
-                Temp (K)
-              </th>
-              <th>
-                pH
-              </th>
-              <th onClick={() => handleSort('binding_status')}>
-                Binding status {getSortIcon('binding_status')}
-              </th>
-              <th onClick={() => handleSort('chain_composition')}>
-                Chain composition {getSortIcon('chain_composition')}
-              </th>
-              <th onClick={() => handleSort('delta_rosetta')}>
-                ΔRosetta {getSortIcon('delta_rosetta')}
-              </th>
-              <th onClick={() => handleSort('delta_foldx')}>
-                ΔFoldX {getSortIcon('delta_foldx')}
-              </th>
-              <th onClick={() => handleSort('delta_evoef2')}>
-                ΔEvoEF2 {getSortIcon('delta_evoef2')}
-              </th>
-              <th onClick={() => handleSort('delta_rw')}>
-                ΔRW {getSortIcon('delta_rw')}
-              </th>
-              <th onClick={() => handleSort('delta_rw_plus')}>
-                ΔRW+ {getSortIcon('delta_rw_plus')}
-              </th>
-              <th onClick={() => handleSort('state_id_b')}>
-                State ID {getSortIcon('state_id_b')}
-              </th>
-              <th onClick={() => handleSort('state_fidelity')}>
-                State fidelity {getSortIcon('state_fidelity')}
-              </th>
-              <th onClick={() => handleSort('avg_sim')}>
-                State avg. similarity {getSortIcon('avg_sim')}
-              </th>
-              <th onClick={() => handleSort('observation_fidelity')}>
-                Observation fidelity {getSortIcon('observation_fidelity')}
-              </th>
-              <th onClick={() => handleSort('structure_sim')}>
-                Observation similarity {getSortIcon('structure_sim')}
-              </th>
-            </tr>
-          </thead>
-          <tbody>
-            {paginatedData.map((record, index) => (
-              <tr key={`${record.pdb_id_a}-${record.auth_asym_id_a}-${record.pdb_id_b}-${record.auth_asym_id_b}-${index}`}>
-                <td>
-                  <span className="chain-id">{record.pdb_id_b.toUpperCase()}</span>
-                </td>
-                <td>
-                  <span className="asym-id">{record.auth_asym_id_b}</span>
-                </td>
-                <td className="numeric">{record.tm_score.toFixed(3)}</td>
-                <td className="numeric">{record.rmsd.toFixed(2)}</td>
-                <td className="experimental-method">
-                  {record.exptl_method || <span className="placeholder">—</span>}
-                </td>
-                <td className="numeric">
-                  {formatTemperature(record.temp)}
-                </td>
-                <td className="numeric">
-                  {formatPH(record.pH)}
-                </td>
-                <td className="capitalize">
-                  {record.binding_status || <span className="placeholder">—</span>}
-                </td>
-                <td className="capitalize">
-                  {record.chain_composition || <span className="placeholder">—</span>}
-                </td>
-                {(['delta_rosetta', 'delta_foldx', 'delta_evoef2', 'delta_rw', 'delta_rw_plus'] as const).map(field => {
-                  const val = record[field];
-                  return (
-                    <td key={field} className={`numeric delta-cell${val == null ? '' : val > 0 ? ' delta-pos' : val < 0 ? ' delta-neg' : ''}`}>
-                      {val == null ? <span className="placeholder">—</span> : `${val > 0 ? '+' : ''}${val.toFixed(2)}`}
-                    </td>
-                  );
-                })}
-                <td className="font-mono">{record.state_id_b ?? <span className="placeholder">—</span>}</td>
-                <td>{record.state_fidelity ?? <span className="placeholder">—</span>}</td>
-                <td className="numeric">
-                  {(() => {
-                    const n = record.avg_sim != null && record.avg_sim !== '' ? Number(record.avg_sim) : NaN;
-                    return Number.isFinite(n) ? n.toFixed(3) : (record.avg_sim || <span className="placeholder">—</span>);
-                  })()}
-                </td>
-                <td>{record.observation_fidelity ?? <span className="placeholder">—</span>}</td>
-                <td className="numeric">{record.structure_sim != null ? record.structure_sim.toFixed(3) : <span className="placeholder">—</span>}</td>
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      </div>
-
-      {totalPages > 1 && (
-        <div className="pagination">
-          <button
-            onClick={() => setCurrentPage(Math.max(1, currentPage - 1))}
-            disabled={currentPage === 1}
-          >
-            Previous
-          </button>
-          <span className="page-info">
-            Page {currentPage} of {totalPages}
-          </span>
-          <button
-            onClick={() => setCurrentPage(Math.min(totalPages, currentPage + 1))}
-            disabled={currentPage === totalPages}
-          >
-            Next
-          </button>
-        </div>
-      )}
-    </div>
-  );
-};

frontend/src/components/datasets/protein/ErrorBoundary.css

@@ -1,93 +0,0 @@
-/* Error Boundary Fallback Styling */
-
-.error-boundary-fallback {
-  background: #fff;
-  border: 2px solid #fecaca;
-  border-radius: 12px;
-  padding: 32px;
-  text-align: center;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
-}
-
-.error-boundary-icon {
-  font-size: 48px;
-  margin-bottom: 16px;
-}
-
-.error-boundary-fallback h3 {
-  margin: 0 0 8px 0;
-  font-size: 18px;
-  font-weight: 600;
-  color: #991b1b;
-}
-
-.error-boundary-fallback p {
-  margin: 0 0 24px 0;
-  font-size: 14px;
-  color: #6b7280;
-}
-
-.error-boundary-actions {
-  display: flex;
-  gap: 12px;
-  justify-content: center;
-  margin-bottom: 16px;
-}
-
-.error-boundary-btn {
-  padding: 10px 20px;
-  border-radius: 8px;
-  font-size: 14px;
-  font-weight: 500;
-  cursor: pointer;
-  transition: all 0.2s ease;
-  border: none;
-}
-
-.error-boundary-btn.primary {
-  background: #667eea;
-  color: white;
-}
-
-.error-boundary-btn.primary:hover {
-  background: #5568d3;
-}
-
-.error-boundary-btn.secondary {
-  background: #e5e7eb;
-  color: #374151;
-}
-
-.error-boundary-btn.secondary:hover {
-  background: #d1d5db;
-}
-
-.error-boundary-details {
-  margin-top: 16px;
-  text-align: left;
-  background: #f9fafb;
-  border: 1px solid #e5e7eb;
-  border-radius: 8px;
-  padding: 12px;
-}
-
-.error-boundary-details summary {
-  cursor: pointer;
-  font-weight: 600;
-  font-size: 13px;
-  color: #6b7280;
-  margin-bottom: 8px;
-}
-
-.error-boundary-stack {
-  margin: 8px 0 0 0;
-  padding: 12px;
-  background: #1f2937;
-  color: #f9fafb;
-  border-radius: 6px;
-  font-size: 12px;
-  font-family: 'Courier New', monospace;
-  overflow-x: auto;
-  white-space: pre-wrap;
-  word-break: break-word;
-}

frontend/src/components/datasets/protein/ErrorBoundary.tsx

@@ -1,105 +0,0 @@
-/**
- * Error Boundary component to catch React render errors
- * Prevents a single component crash from taking down the entire app
- */
-import React, { Component, ErrorInfo, ReactNode } from 'react';
-import './ErrorBoundary.css';
-
-interface Props {
-  children: ReactNode;
-  fallback?: ReactNode;
-  componentName?: string;
-}
-
-interface State {
-  hasError: boolean;
-  error: Error | null;
-  errorInfo: ErrorInfo | null;
-}
-
-class ErrorBoundary extends Component<Props, State> {
-  constructor(props: Props) {
-    super(props);
-    this.state = {
-      hasError: false,
-      error: null,
-      errorInfo: null,
-    };
-  }
-
-  static getDerivedStateFromError(error: Error): State {
-    return {
-      hasError: true,
-      error,
-      errorInfo: null,
-    };
-  }
-
-  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
-    console.error('ErrorBoundary caught an error:', error, errorInfo);
-    this.setState({
-      error,
-      errorInfo,
-    });
-  }
-
-  handleReset = () => {
-    this.setState({
-      hasError: false,
-      error: null,
-      errorInfo: null,
-    });
-  };
-
-  handleCopyError = () => {
-    const { error, errorInfo } = this.state;
-    const errorText = `Error: ${error?.toString()}\n\nStack: ${errorInfo?.componentStack}`;
-    navigator.clipboard.writeText(errorText).then(() => {
-      alert('Error details copied to clipboard');
-    });
-  };
-
-  render() {
-    if (this.state.hasError) {
-      // Custom fallback if provided
-      if (this.props.fallback) {
-        return this.props.fallback;
-      }
-
-      // Default fallback UI
-      const componentName = this.props.componentName || 'this component';
-      const isDev = import.meta.env?.DEV || process.env.NODE_ENV === 'development';
-
-      return (
-        <div className="error-boundary-fallback">
-          <div className="error-boundary-icon">⚠️</div>
-          <h3>Unable to render {componentName}</h3>
-          <p>Something went wrong while displaying this section.</p>
-          <div className="error-boundary-actions">
-            <button onClick={this.handleReset} className="error-boundary-btn primary">
-              Try Again
-            </button>
-            {isDev && this.state.error && (
-              <button onClick={this.handleCopyError} className="error-boundary-btn secondary">
-                Copy Error Details
-              </button>
-            )}
-          </div>
-          {isDev && this.state.error && (
-            <details className="error-boundary-details">
-              <summary>Error Details (dev only)</summary>
-              <pre className="error-boundary-stack">
-                {this.state.error.toString()}
-                {this.state.errorInfo?.componentStack}
-              </pre>
-            </details>
-          )}
-        </div>
-      );
-    }
-
-    return this.props.children;
-  }
-}
-
-export default ErrorBoundary;

frontend/src/components/datasets/protein/ExperimentalConditionsPanel.tsx

@@ -1,117 +0,0 @@
-/**
- * Experimental conditions panel for a selected chain
- * Displays method, resolution, pH, temperature, details, and RCSB link
- */
-import React, { useState } from 'react';
-import { ChainMetadata } from '../../../types/protein';
-import { formatText, formatPH, formatTemperature, truncateText } from '../../../utils/format';
-
-interface ExperimentalConditionsPanelProps {
-  metadata: ChainMetadata | null;
-  isLoading?: boolean;
-}
-
-const ExperimentalConditionsPanel: React.FC<ExperimentalConditionsPanelProps> = ({ metadata, isLoading }) => {
-  const [showFullDetails, setShowFullDetails] = useState(false);
-
-  if (isLoading) {
-    return (
-      <section className="space-y-4">
-        <h3 className="text-xl font-semibold text-slate-900">Experimental Conditions</h3>
-        <div className="text-center py-10 text-slate-600">Loading conditions...</div>
-      </section>
-    );
-  }
-
-  if (!metadata) {
-    return (
-      <section className="space-y-4">
-        <h3 className="text-xl font-semibold text-slate-900">Experimental Conditions</h3>
-        <div className="text-center py-10 text-slate-600">No experimental data available</div>
-      </section>
-    );
-  }
-
-  // Safe extraction with optional chaining and nullish coalescing
-  const pdbId = metadata.pdb_id || metadata.entry?.rcsb_id;
-  const website = pdbId ? `https://www.rcsb.org/structure/${String(pdbId).toUpperCase()}` : null;
-  const exptlMethod = metadata.entry?.exptl_method;
-  const pH = metadata.entry?.crystal_grow?.pH;
-  const temp = metadata.entry?.crystal_grow?.temp;
-  const details = metadata.entry?.crystal_grow?.pdbx_details;
-
-  // Safe formatting
-  const formattedMethod = formatText(exptlMethod);
-  const formattedPH = formatPH(pH);
-  const formattedTemp = formatTemperature(temp);
-  const formattedDetails = formatText(details, '');
-
-  const detailsPreview = formattedDetails ? truncateText(formattedDetails, 120) : '';
-  const hasLongDetails = formattedDetails && formattedDetails.length > 120;
-
-  return (
-    <section className="space-y-4">
-      {/* Title + Method Chip */}
-      <div className="flex items-start justify-between">
-        <h3 className="text-xl font-semibold text-slate-900">Experimental Conditions</h3>
-        {formattedMethod !== '—' && (
-          <span className="px-3 py-1.5 bg-green-50 text-green-700 text-xs font-medium rounded-full border border-green-200">
-            {formattedMethod}
-          </span>
-        )}
-      </div>
-      
-      {/* Definition List */}
-      <dl className="space-y-3 pt-2">
-        {website && (
-          <div className="flex justify-between items-center py-2 border-b border-slate-100">
-            <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">Website</dt>
-            <dd>
-              <a href={website} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-1 text-sm text-blue-600 hover:text-blue-800 font-medium hover:underline transition-colors">
-                RCSB PDB <span className="text-xs">↗</span>
-              </a>
-            </dd>
-          </div>
-        )}
-
-        <div className="flex justify-between items-center py-2 border-b border-slate-100">
-          <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">Method</dt>
-          <dd className="text-sm font-semibold text-slate-900">{formattedMethod}</dd>
-        </div>
-
-<div className="flex justify-between items-center py-2 border-b border-slate-100">
-          <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">pH</dt>
-          <dd className="text-sm font-semibold text-slate-900">{formattedPH}</dd>
-        </div>
-
-        <div className="flex justify-between items-center py-2 border-b border-slate-100">
-          <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">Temperature</dt>
-          <dd className="text-sm font-semibold text-slate-900">{formattedTemp}</dd>
-        </div>
-
-        <div className="py-2 border-b border-slate-100">
-          {formattedDetails && (
-            <div className="experimental-item experimental-details min-w-0">
-          <dt className="text-xs font-medium text-slate-500 uppercase tracking-wider">Details</dt>
-          <dd className="text-sm font-semibold text-slate-900">
-                <div className="details-content wrap-anywhere mt-1">
-                  {showFullDetails ? formattedDetails : detailsPreview}
-                </div>
-                {hasLongDetails && (
-                  <button
-                    className="details-toggle"
-                    onClick={() => setShowFullDetails(!showFullDetails)}
-                  >
-                    {showFullDetails ? '▲ Show less' : '▼ Show more'}
-                  </button>
-                )}
-              </dd>
-            </div>
-          )}
-        </div>
-      </dl>
-    </section>
-  );
-};
-
-export default ExperimentalConditionsPanel;

frontend/src/components/datasets/protein/FilterPanel.tsx

@@ -1,75 +0,0 @@
-import React from 'react';
-import type { FilterParams, FilterOptions, ChainMetadata } from '../../../types/protein';
-import { ChainSearchInput } from './ChainSearchInput';
-
-interface FilterPanelProps {
-  filterOptions: FilterOptions | null;
-  filters: FilterParams;
-  searchInputValue: string;
-  onSearchInputChange: (value: string) => void;
-  onSearchClear: () => void;
-  searchStatus: 'idle' | 'typing' | 'loading' | 'success' | 'not_found' | 'error';
-  searchError: string | null;
-  resolvedLabel?: string;
-  onFiltersChange: (filters: FilterParams) => void;
-  onChainMetadataLoaded: (metadata: ChainMetadata) => void;
-  resolveChain: (pdb_id: string, auth_asym_id: string) => Promise<ChainMetadata>;
-  loading: boolean;
-  showResetButton?: boolean;
-}
-
-export const FilterPanel: React.FC<FilterPanelProps> = ({
-  filterOptions,
-  searchInputValue,
-  onSearchInputChange,
-  onSearchClear,
-  searchStatus,
-  searchError,
-  resolvedLabel,
-  onFiltersChange,
-  onChainMetadataLoaded,
-  resolveChain,
-  loading,
-  showResetButton = false,
-}) => {
-  const handleChainSelect = (pdb_id: string, auth_asym_id: string) => {
-    onFiltersChange({ pdb_id, auth_asym_id });
-  };
-
-  if (!filterOptions) {
-    return (
-      <div className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm">
-        <div className="flex items-center justify-center min-h-[100px] text-slate-500">
-          Loading...
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <div className="space-y-4">
-      <div className="flex flex-col gap-4">
-        <ChainSearchInput
-          value={searchInputValue}
-          onValueChange={onSearchInputChange}
-          onChainSelect={handleChainSelect}
-          onMetadataLoaded={onChainMetadataLoaded}
-          onClear={onSearchClear}
-          resolveChain={resolveChain}
-          searchStatus={searchStatus}
-          resolvedLabel={resolvedLabel}
-          errorMessage={searchError || undefined}
-          disabled={loading}
-        />
-        {showResetButton && (
-          <button 
-            onClick={onSearchClear} 
-            className="inline-flex items-center justify-center px-5 py-2.5 border border-gray-300 text-slate-900 font-medium rounded-lg hover:bg-slate-50 transition-colors duration-200 text-sm"
-          >
-            Reset Search
-          </button>
-        )}
-      </div>
-    </div>
-  );
-};

frontend/src/components/datasets/protein/FunctionPanel.tsx

@@ -1,80 +0,0 @@
-import React, { useEffect, useState } from 'react';
-import { proteinApi } from '../../../api/protein';
-import type { RankedFunction } from '../../../types/protein';
-
-interface FunctionPanelProps {
-  pdbId: string;
-  chainId: string;
-}
-
-const FunctionPanel: React.FC<FunctionPanelProps> = ({ pdbId, chainId }) => {
-  const [functions, setFunctions] = useState<RankedFunction[] | null>(null);
-  const [loading, setLoading] = useState(true);
-  const [notFound, setNotFound] = useState(false);
-
-  useEffect(() => {
-    let cancelled = false;
-    setLoading(true);
-    setNotFound(false);
-    setFunctions(null);
-
-    proteinApi.getChainFunctions(pdbId, chainId)
-      .then(fns => { if (!cancelled) setFunctions(fns); })
-      .catch(() => { if (!cancelled) setNotFound(true); })
-      .finally(() => { if (!cancelled) setLoading(false); });
-
-    return () => { cancelled = true; };
-  }, [pdbId, chainId]);
-
-  return (
-    <div className="border border-gray-200 rounded-2xl bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
-      {/* Header */}
-      <div className="flex items-center justify-between px-6 py-4 border-b border-gray-100">
-        <h3 className="text-xl font-semibold text-slate-900">Ranked Functions</h3>
-        {functions && (
-          <span className="text-sm text-slate-500">
-            {functions.length} annotation{functions.length !== 1 ? 's' : ''}
-          </span>
-        )}
-      </div>
-
-      {/* Column header */}
-      {!loading && functions && functions.length > 0 && (
-        <div className="flex items-center gap-3 px-6 pt-3 text-[11px] font-semibold uppercase tracking-wider text-slate-400">
-          <span className="shrink-0 w-5" />
-          <span style={{ flex: 1, minWidth: 0 }}>Function</span>
-          <span className="shrink-0 w-20 text-right">Score</span>
-        </div>
-      )}
-
-      {/* Scrollable body */}
-      <div className="px-6 py-4" style={{ overflowY: 'auto', overflowX: 'hidden', maxHeight: '14rem' }}>
-        {loading && (
-          <p className="text-sm text-slate-500 text-center py-4">Loading functions…</p>
-        )}
-
-        {!loading && (notFound || (functions && functions.length === 0)) && (
-          <p className="text-sm text-slate-500 text-center py-4">No functional annotation available</p>
-        )}
-
-        {!loading && functions && functions.length > 0 && (
-          <ol className="space-y-3">
-            {functions.map((fn, idx) => (
-              <li key={idx} className="flex items-start gap-3 text-sm text-slate-700" style={{ minWidth: 0 }}>
-                <span className="shrink-0 mt-0.5 w-5 h-5 rounded-full bg-slate-100 text-slate-500 text-[10px] font-semibold flex items-center justify-center">
-                  {idx + 1}
-                </span>
-                <span style={{ flex: 1, minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }} title={fn.function}>{fn.function}</span>
-                <span className="shrink-0 w-20 text-right font-mono text-slate-500">
-                  {fn.matching_score != null ? fn.matching_score.toFixed(3) : '—'}
-                </span>
-              </li>
-            ))}
-          </ol>
-        )}
-      </div>
-    </div>
-  );
-};
-
-export default FunctionPanel;

frontend/src/components/datasets/protein/ProteinDashboard.tsx

@@ -1,391 +0,0 @@
-import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
-import { FilterPanel } from './FilterPanel';
-import { StaticDistributionPlots } from './StaticDistributionPlots';
-import { DataTable } from './DataTable';
-import { StatsPanel } from './StatsPanel';
-import ChainBasicInfoCards from './ChainBasicInfoCards';
-import SequencePanel from './SequencePanel';
-import ExperimentalConditionsPanel from './ExperimentalConditionsPanel';
-import BindersPanel from './BindersPanel';
-import FunctionPanel from './FunctionPanel';
-import ErrorBoundary from './ErrorBoundary';
-import { proteinApi } from '../../../api/protein';
-import type { FilterParams, FilterOptions, DataResponse, ChainMetadata } from '../../../types/protein';
-import { PageSEO } from '../../seo/PageSEO';
-import { MuSProtJsonLd } from '../../seo/MuSProtJsonLd';
-
-interface CacheEntry {
-  status: 'success' | 'not_found' | 'error';
-  timestamp: number;
-  message?: string;
-  metadata?: ChainMetadata;
-}
-
-const NEGATIVE_CACHE_TTL = 10 * 60 * 1000; // 10 minutes
-
-export function ProteinDashboard() {
-  // State management
-  const [filterOptions, setFilterOptions] = useState<FilterOptions | null>(null);
-  const [filters, setFilters] = useState<FilterParams>({});
-  const [dataResponse, setDataResponse] = useState<DataResponse | null>(null);
-
-  // Search input state (controlled)
-  const [searchInputValue, setSearchInputValue] = useState('');
-  const [searchStatus, setSearchStatus] = useState<'idle' | 'typing' | 'loading' | 'success' | 'not_found' | 'error'>('idle');
-  const [searchError, setSearchError] = useState<string | null>(null);
-  
-  // Chain metadata cache (client-side) — used for the searched chain's detail panels
-  const [chainMetadataCache, setChainMetadataCache] = useState<Record<string, ChainMetadata>>({});
-
-  // Request control refs
-  const negativeCache = useRef<Map<string, CacheEntry>>(new Map());
-  const inFlightResolve = useRef<{ key: string; controller: AbortController } | null>(null);
-  const lastAttemptedKey = useRef<string | null>(null);
-  
-  const [, setLoadingFilters] = useState(true);
-  const [loadingData, setLoadingData] = useState(false);
-
-  const [error, setError] = useState<string | null>(null);
-
-  // Load filter options on mount
-  useEffect(() => {
-    const loadFilters = async () => {
-      try {
-        setLoadingFilters(true);
-        const options = await proteinApi.getFilters();
-        setFilterOptions(options);
-      } catch (err) {
-        setError('Failed to load filter options. The MuSProt database may still be initializing.');
-        console.error('Error loading filters:', err);
-      } finally {
-        setLoadingFilters(false);
-      }
-    };
-
-    loadFilters();
-  }, []);
-
-  const fetchData = useCallback(async () => {
-    try {
-      setLoadingData(true);
-      setError(null);
-      const response = await proteinApi.getData(filters);
-      setDataResponse(response);
-    } catch (err) {
-      setError('Failed to fetch data. Please check your filters and try again.');
-      console.error('Error fetching data:', err);
-    } finally {
-      setLoadingData(false);
-    }
-  }, [filters]);
-
-  // Debounced data fetching — skip fetchData when there's no active chain search
-  useEffect(() => {
-    const timeoutId = setTimeout(() => {
-      if (filters.pdb_id && filters.auth_asym_id) {
-        fetchData();
-      }
-    }, 500);
-
-    return () => clearTimeout(timeoutId);
-  }, [fetchData, filters.pdb_id, filters.auth_asym_id]);
-
-  const handleFiltersChange = (newFilters: FilterParams) => {
-    setFilters(newFilters);
-  };
-
-  const handleSearchInputChange = useCallback((value: string) => {
-    setSearchInputValue(value);
-    if (value && searchStatus !== 'loading') {
-      setSearchStatus('typing');
-      // Clear last attempted key when user starts typing new value
-      lastAttemptedKey.current = null;
-    } else if (!value) {
-      setSearchStatus('idle');
-      setSearchError(null);
-    }
-  }, [searchStatus]);
-
-  const handleSearchClear = useCallback(() => {
-    setSearchInputValue('');
-    setSearchStatus('idle');
-    setSearchError(null);
-    setFilters({});
-    lastAttemptedKey.current = null;
-    // Abort any in-flight request
-    if (inFlightResolve.current) {
-      inFlightResolve.current.controller.abort();
-      inFlightResolve.current = null;
-    }
-  }, []);
-  
-  // Cleanup on unmount
-  useEffect(() => {
-    return () => {
-      // Abort any in-flight requests
-      if (inFlightResolve.current) {
-        inFlightResolve.current.controller.abort();
-      }
-    };
-  }, []);
-
-  const handleChainMetadataLoaded = useCallback((metadata: ChainMetadata) => {
-    const key = `${metadata.pdb_id.toLowerCase()}|${metadata.chain_id.toUpperCase()}`;
-    setChainMetadataCache(prev => ({ ...prev, [key]: metadata }));
-    setSearchStatus('success');
-    setSearchError(null);
-    
-    negativeCache.current.set(key, {
-      status: 'success',
-      timestamp: Date.now(),
-      metadata
-    });
-  }, []);
-
-  const resolveChainWrapper = useCallback(async (pdb_id: string, auth_asym_id: string): Promise<ChainMetadata> => {
-    const key = `${pdb_id.toLowerCase()}|${auth_asym_id.toUpperCase()}`;
-    
-    // Check if same key as last attempt (prevent duplicate requests)
-    if (key === lastAttemptedKey.current && inFlightResolve.current?.key === key) {
-      throw new Error('Request already in flight');
-    }
-    
-    // Check positive cache first
-    if (chainMetadataCache[key]) {
-      setSearchStatus('success');
-      return chainMetadataCache[key];
-    }
-    
-    // Check negative cache
-    const cachedEntry = negativeCache.current.get(key);
-    if (cachedEntry) {
-      const age = Date.now() - cachedEntry.timestamp;
-      if (age < NEGATIVE_CACHE_TTL) {
-        if (cachedEntry.status === 'not_found') {
-          setSearchStatus('not_found');
-          setSearchError(cachedEntry.message || `No chain '${auth_asym_id}' found in PDB ${pdb_id.toUpperCase()}. Check the chain ID or entry.`);
-          const error: any = new Error('Chain not found');
-          error.code = 'NOT_FOUND';
-          throw error;
-        } else if (cachedEntry.status === 'error') {
-          setSearchStatus('error');
-          setSearchError(cachedEntry.message || 'Failed to resolve chain');
-          throw new Error(cachedEntry.message || 'Failed to resolve chain');
-        }
-      } else {
-        // TTL expired, remove from cache
-        negativeCache.current.delete(key);
-      }
-    }
-    
-    // Abort previous request if different key
-    if (inFlightResolve.current && inFlightResolve.current.key !== key) {
-      inFlightResolve.current.controller.abort();
-      inFlightResolve.current = null;
-    }
-    
-    // Start new request
-    lastAttemptedKey.current = key;
-    const controller = new AbortController();
-    inFlightResolve.current = { key, controller };
-    
-    setSearchStatus('loading');
-    setSearchError(null);
-    
-    try {
-      const metadata = await proteinApi.resolveChain(pdb_id, auth_asym_id, { signal: controller.signal });
-      
-      // Only update state if not aborted
-      if (inFlightResolve.current?.key === key) {
-        inFlightResolve.current = null;
-      }
-      
-      return metadata;
-    } catch (err: any) {
-      // Ignore aborted requests
-      if (err.name === 'AbortError' || err.name === 'CanceledError') {
-        return Promise.reject(err);
-      }
-      
-      // Clear in-flight if this was our request
-      if (inFlightResolve.current?.key === key) {
-        inFlightResolve.current = null;
-      }
-      
-      // Handle 404 not found
-      if (err.code === 'NOT_FOUND' || err.status === 404) {
-        const message = err.detail || `No chain '${auth_asym_id}' found in PDB ${pdb_id.toUpperCase()}. Check the chain ID or entry.`;
-        negativeCache.current.set(key, {
-          status: 'not_found',
-          timestamp: Date.now(),
-          message
-        });
-        setSearchStatus('not_found');
-        setSearchError(message);
-      } else {
-        // Other errors
-        const message = err.response?.data?.detail || err.message || 'Failed to resolve chain';
-        negativeCache.current.set(key, {
-          status: 'error',
-          timestamp: Date.now(),
-          message
-        });
-        setSearchStatus('error');
-        setSearchError(message);
-      }
-      
-      throw err;
-    }
-  }, [chainMetadataCache]);
-
-  // exptl_method, temp, pH are now included directly in each record from the DB
-  const enrichedData = useMemo(() => dataResponse?.data ?? [], [dataResponse?.data]);
-
-  // Determine if we have an active chain search
-  const hasActiveChainSearch = filters.pdb_id && filters.auth_asym_id;
-  const activeChainKey = hasActiveChainSearch 
-    ? `${filters.pdb_id!.toLowerCase()}|${filters.auth_asym_id!.toUpperCase()}`
-    : null;
-  const activeChainMetadata = activeChainKey ? chainMetadataCache[activeChainKey] : null;
-
-  // Generate resolved label for success message
-  const resolvedLabel = hasActiveChainSearch 
-    ? `Found ${filters.pdb_id!.toUpperCase()} Chain ${filters.auth_asym_id!.toUpperCase()}`
-    : undefined;
-
-  return (
-    <div className="protein-dashboard min-h-screen bg-white">
-      <PageSEO
-        title="MuSProt: Multistate Protein Structure Database"
-        description="Explore 355,731 protein chains from 121,584 PDB entries with pairwise structural comparisons, energy scoring, and CATH functional annotations. Download the full SQLite database."
-        path="/"
-      />
-      <MuSProtJsonLd />
-
-      {error && (
-        <div className="max-w-7xl mx-auto px-6 mt-4">
-          <div className="protein-error-banner">
-            <span>⚠️ {error}</span>
-            <button onClick={() => setError(null)}>×</button>
-          </div>
-        </div>
-      )}
-
-      <div className="max-w-7xl mx-auto px-6 py-6">
-        <main className="space-y-6">
-          {hasActiveChainSearch && activeChainMetadata ? (
-            <>
-              {/* First Row: Search + Chain Information (3:7 in landscape, stacked in portrait) */}
-              <div className="grid gap-6 items-stretch chain-detail-grid">
-                <section className="min-w-0 h-full border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
-                  <FilterPanel
-                    filterOptions={filterOptions}
-                    filters={filters}
-                    searchInputValue={searchInputValue}
-                    onSearchInputChange={handleSearchInputChange}
-                    onSearchClear={handleSearchClear}
-                    searchStatus={searchStatus}
-                    searchError={searchError}
-                    resolvedLabel={resolvedLabel}
-                    onFiltersChange={handleFiltersChange}
-                    onChainMetadataLoaded={handleChainMetadataLoaded}
-                    resolveChain={resolveChainWrapper}
-                    loading={loadingData}
-                    showResetButton={true}
-                  />
-                </section>
-
-                <section className="min-w-0 h-full flex">
-                  <ErrorBoundary componentName="Chain Information">
-                    <ChainBasicInfoCards metadata={activeChainMetadata} />
-                  </ErrorBoundary>
-                </section>
-              </div>
-
-              {/* Second Row: Sequence, Experimental Conditions, Binders (3 columns, equal height) */}
-              <div className="grid md:grid-cols-2 lg:grid-cols-3 gap-6">
-                <div className="min-w-0 border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
-                  <ErrorBoundary componentName="Sequence Panel">
-                    <SequencePanel metadata={activeChainMetadata} />
-                  </ErrorBoundary>
-                </div>
-                <div className="min-w-0 border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
-                  <ErrorBoundary componentName="Experimental Conditions">
-                    <ExperimentalConditionsPanel metadata={activeChainMetadata} />
-                  </ErrorBoundary>
-                </div>
-                {activeChainMetadata.nonpolymer_entities && activeChainMetadata.nonpolymer_entities.length > 0 && (
-                  <div className="min-w-0 border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
-                    <ErrorBoundary componentName="Binders Panel">
-                      <BindersPanel metadata={activeChainMetadata} />
-                    </ErrorBoundary>
-                  </div>
-                )}
-              </div>
-
-              {/* Functions block — full width, between panels and Results */}
-              <ErrorBoundary componentName="Function Panel">
-                <FunctionPanel pdbId={filters.pdb_id!} chainId={filters.auth_asym_id!} />
-              </ErrorBoundary>
-            </>
-          ) : (
-            <>
-              {/* Brief database introduction — borderless, no frame */}
-              <section className="px-1">
-                <h1 className="text-2xl font-semibold text-slate-900">MuSProt — Multistate Protein Database</h1>
-                <p className="mt-2 text-slate-600 leading-relaxed">
-                  <span className="font-semibold text-slate-900">MuSProt</span> (Multistate Protein Database) is a
-                  million-scale multimodal database for multistate proteins, designed to support programmable protein
-                  design and AI model development. It links experimentally observed conformational states of identical
-                  protein sequences from the PDB, organizes them into state clusters and transition relationships, and
-                  enriches each record with structural similarity, experimental context, state-specific function
-                  rankings and transition fidelity labels. Users can search, browse and download MuSProt records to
-                  study conformational diversity, state-dependent functions and feasible protein state transitions.
-                </p>
-              </section>
-
-              {/* Search Panel Full Width */}
-              <section className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
-                <FilterPanel
-                  filterOptions={filterOptions}
-                  filters={filters}
-                  searchInputValue={searchInputValue}
-                  onSearchInputChange={handleSearchInputChange}
-                  onSearchClear={handleSearchClear}
-                  searchStatus={searchStatus}
-                  searchError={searchError}
-                  resolvedLabel={resolvedLabel}
-                  onFiltersChange={handleFiltersChange}
-                  onChainMetadataLoaded={handleChainMetadataLoaded}
-                  resolveChain={resolveChainWrapper}
-                  loading={loadingData}
-                  showResetButton={false}
-                />
-              </section>
-
-              {/* Default Dataset Summary View */}
-              <section className="border border-gray-200 rounded-2xl p-6 bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300">
-                <StatsPanel />
-              </section>
-
-              <section>
-                <StaticDistributionPlots />
-              </section>
-            </>
-          )}
-
-          {hasActiveChainSearch && (
-            <section className="protein-table-section">
-              <DataTable
-                data={enrichedData}
-                loading={loadingData}
-                total={dataResponse?.total || 0}
-                filtered={dataResponse?.filtered || 0}
-              />
-            </section>
-          )}
-        </main>
-      </div>
-    </div>
-  );
-}

frontend/src/components/datasets/protein/SequencePanel.tsx

@@ -1,137 +0,0 @@
-/**
- * Sequence display panel for a selected chain
- * Shows sequence length and sequence with copy/download features
- */
-import React, { useState } from 'react';
-import { ChainMetadata } from '../../../types/protein';
-import { formatText, formatNumber } from '../../../utils/format';
-
-interface SequencePanelProps {
-  metadata: ChainMetadata | null;
-  isLoading?: boolean;
-}
-
-const SequencePanel: React.FC<SequencePanelProps> = ({ metadata, isLoading }) => {
-  const [copied, setCopied] = useState(false);
-  const [showAll, setShowAll] = useState(false);
-
-  const sequence = metadata?.polymer_entity?.seq_can;
-  const sequenceLength = metadata?.polymer_entity?.sequence_length;
-
-  // Format sequence with line breaks every 60 chars
-  const formatSequence = (seq: string): string[] => {
-    if (!seq) return [];
-    const lines = [];
-    for (let i = 0; i < seq.length; i += 60) {
-      lines.push(seq.substring(i, i + 60));
-    }
-    return lines;
-  };
-
-  const handleCopy = async () => {
-    if (sequence) {
-      try {
-        await navigator.clipboard.writeText(sequence);
-        setCopied(true);
-        setTimeout(() => setCopied(false), 2000);
-      } catch (err) {
-        console.error('Failed to copy:', err);
-      }
-    }
-  };
-
-  const handleDownload = () => {
-    if (!sequence || !metadata) return;
-
-    const pdbId = formatText(metadata.pdb_id || metadata.entry?.rcsb_id, 'unknown');
-    const chainId = formatText(metadata.chain_id || metadata.polymer_entity_instance?.auth_asym_id, 'X');
-    const title = formatText(metadata.entry?.title, 'Unknown protein');
-    
-    const fasta = `>${pdbId}:${chainId} ${title}\n${sequence}`;
-    const blob = new Blob([fasta], { type: 'text/plain' });
-    const url = URL.createObjectURL(blob);
-    const a = document.createElement('a');
-    a.href = url;
-    a.download = `${pdbId}_${chainId}.fasta`;
-    a.click();
-    URL.revokeObjectURL(url);
-  };
-
-  if (isLoading) {
-    return (
-      <section className="space-y-4">
-        <h3 className="text-xl font-semibold text-slate-900">Amino Acid Sequence</h3>
-        <div className="text-center py-10 text-slate-600">Loading sequence...</div>
-      </section>
-    );
-  }
-
-  if (!sequence) {
-    return (
-      <section className="space-y-4">
-        <h3 className="text-xl font-semibold text-slate-900">Amino Acid Sequence</h3>
-        <div className="text-center py-10 text-slate-600">No sequence data available</div>
-      </section>
-    );
-  }
-
-  const lines = formatSequence(sequence);
-  const displayLines = showAll ? lines : lines.slice(0, 10);
-  const hasMore = lines.length > 10;
-  const formattedLength = formatNumber(sequenceLength, { decimals: 0 });
-
-  return (
-    <section className="space-y-4">
-      {/* Header + Actions */}
-      <div className="flex justify-between items-start">
-        <div>
-          <h3 className="text-xl font-semibold text-slate-900 mb-1">Amino Acid Sequence</h3>
-          {formattedLength !== '—' && (
-            <div className="text-sm text-slate-600">
-              <span className="font-medium">{formattedLength}</span> residues
-            </div>
-          )}
-        </div>
-        <div className="flex gap-2">
-          <button
-            className="inline-flex items-center gap-1.5 px-3 py-1.5 border border-gray-300 text-slate-900 font-medium rounded-lg hover:bg-slate-50 transition-colors text-xs"
-            onClick={handleCopy}
-            title="Copy to clipboard"
-          >
-            {copied ? '✓' : '📋'}
-          </button>
-          <button
-            className="inline-flex items-center gap-1.5 px-3 py-1.5 bg-slate-900 text-white font-medium rounded-lg hover:bg-slate-800 transition-colors text-xs"
-            onClick={handleDownload}
-            title="Download FASTA"
-          >
-            ⬇ FASTA
-          </button>
-        </div>
-      </div>
-      
-      {/* Sequence Display */}
-      <div className="bg-slate-50 border border-slate-200 rounded-lg p-4 font-mono text-xs max-h-80 overflow-y-auto overflow-x-hidden">
-        {displayLines.map((line, idx) => (
-          <div key={idx} className="flex mb-1 leading-relaxed">
-            <span className="text-gray-400 mr-4 min-w-[50px] shrink-0 text-right select-none">{idx * 60 + 1}</span>
-            <span className="text-gray-800 tracking-wide wrap-anywhere">{line}</span>
-          </div>
-        ))}
-      </div>
-
-      {hasMore && (
-        <div className="text-center">
-          <button
-            className="inline-flex items-center gap-2 px-4 py-2 border border-gray-300 text-slate-900 font-medium rounded-lg hover:bg-slate-50 transition-colors text-sm"
-            onClick={() => setShowAll(!showAll)}
-          >
-            {showAll ? '▲ Show less' : `▼ Show all (${lines.length - 10} more lines)`}
-          </button>
-        </div>
-      )}
-    </section>
-  );
-};
-
-export default SequencePanel;

frontend/src/components/datasets/protein/StaticDistributionPlots.tsx

@@ -1,34 +0,0 @@
-import React from 'react';
-
-const IMG_BASE = '/api/protein/plots';
-const CACHE_BUST = '?v=20260625';
-
-const plots = [
-  { name: 'Structure Similarity', file: 'Structure-similarity.png' },
-  { name: 'Function Rank Correlation vs. Structure Similarity', file: 'Function-rank-correlation.png' },
-  { name: 'Fidelity Distribution', file: 'Fidelity-distribution.png' },
-  { name: 'Unique State Cluster Distribution', file: 'Unique-state-cluster-distribution.png' },
-];
-
-export const StaticDistributionPlots: React.FC = () => {
-  return (
-    <div style={{ columns: '400px', columnGap: '1.5rem' }}>
-      {plots.map(({ name, file }) => (
-        <div
-          key={file}
-          style={{ breakInside: 'avoid', marginBottom: '1.5rem' }}
-          className="border border-gray-200 rounded-2xl bg-white shadow-sm hover:border-slate-900 hover:shadow-lg hover:-translate-y-0.5 transition-all duration-300 overflow-hidden"
-        >
-          <div className="px-4 pt-5 pb-2 text-xl font-semibold text-slate-900">{name}</div>
-          <div className="px-4 pb-4">
-            <img
-              src={`${IMG_BASE}/${file}${CACHE_BUST}`}
-              alt={name}
-              style={{ width: '100%', height: 'auto', display: 'block' }}
-            />
-          </div>
-        </div>
-      ))}
-    </div>
-  );
-};

frontend/src/components/datasets/protein/StatsPanel.css

@@ -1,52 +0,0 @@
-.stats-panel {
-  display: grid;
-  grid-template-columns: repeat(2, 1fr);
-  gap: 15px;
-  padding: 0;
-}
-
-.stat-card {
-  background: white;
-  padding: 10px 20px;
-  border-radius: 8px;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-  text-align: center;
-  transition: transform 0.2s, box-shadow 0.2s;
-}
-
-.stat-card:hover {
-  transform: translateY(-2px);
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
-}
-
-.stat-value {
-  font-size: 1.6rem;
-  font-weight: 700;
-  color: #2196f3;
-  margin-bottom: 2px;
-}
-
-.stat-label {
-  font-size: 0.9rem;
-  color: #666;
-  text-transform: uppercase;
-  letter-spacing: 0.5px;
-}
-
-.stats-loading {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  height: 100px;
-  color: #888;
-  font-size: 1.1rem;
-  background: white;
-  border-radius: 8px;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-}
-
-@media (max-width: 768px) {
-  .stats-panel {
-    grid-template-columns: repeat(2, 1fr);
-  }
-}

frontend/src/components/datasets/protein/StatsPanel.tsx

@@ -1,38 +0,0 @@
-import React from 'react';
-import './StatsPanel.css';
-
-export const StatsPanel: React.FC = () => {
-  return (
-    <div className="stats-panel">
-      <div className="stat-card">
-        <div className="stat-value">102,790</div>
-        <div className="stat-label">Sequences with multiple conformational observations</div>
-      </div>
-
-      <div className="stat-card">
-        <div className="stat-value">24,796</div>
-        <div className="stat-label">Sequences with multiple state clusters</div>
-      </div>
-
-      <div className="stat-card">
-        <div className="stat-value">863,643</div>
-        <div className="stat-label">Conformational observations</div>
-      </div>
-
-      <div className="stat-card">
-        <div className="stat-value">163,869</div>
-        <div className="stat-label">Unique state clusters</div>
-      </div>
-
-      <div className="stat-card">
-        <div className="stat-value">113.6 million</div>
-        <div className="stat-label">Transition triplets between conformational observations</div>
-      </div>
-
-      <div className="stat-card">
-        <div className="stat-value">24.95 million</div>
-        <div className="stat-label">Transition triplets between distinct states</div>
-      </div>
-    </div>
-  );
-};