Upload 3 files

backend.py

@@ -0,0 +1,861 @@
+"""
+EEG Mental Imagery Classification Backend
+Full-stack server: OpenBCI Cyton+Daisy (16ch), LSL markers, neurofeedback, websocket API
+"""
+
+import asyncio
+import json
+import logging
+import math
+import os
+import queue
+import threading
+import time
+from collections import deque
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import numpy as np
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse, JSONResponse
+import uvicorn
+
+# ─── Optional heavy imports (graceful degradation) ───────────────────────────
+try:
+    from brainflow.board_shim import BoardShim, BrainFlowInputParams, BoardIds, BrainFlowError
+    from brainflow.data_filter import DataFilter, FilterTypes, DetrendOperations, WindowOperations
+    BRAINFLOW_AVAILABLE = True
+except ImportError:
+    BRAINFLOW_AVAILABLE = False
+    logging.warning("BrainFlow not installed – running in SIMULATION mode")
+
+try:
+    from pylsl import StreamInfo, StreamOutlet, StreamInlet, resolve_streams, cf_string, cf_float32
+    LSL_AVAILABLE = True
+except ImportError:
+    LSL_AVAILABLE = False
+    logging.warning("pylsl not installed – LSL streaming disabled")
+
+try:
+    import scipy.signal as signal
+    from scipy.signal import welch, butter, filtfilt
+    SCIPY_AVAILABLE = True
+except ImportError:
+    SCIPY_AVAILABLE = False
+
+try:
+    from sklearn.discriminant_analysis import LinearDiscriminantAnalysis
+    from sklearn.preprocessing import StandardScaler
+    from sklearn.pipeline import Pipeline
+    SKLEARN_AVAILABLE = True
+except ImportError:
+    SKLEARN_AVAILABLE = False
+
+# ─── Logging ─────────────────────────────────────────────────────────────────
+logging.basicConfig(level=logging.INFO, format="%(asctime)s │ %(levelname)s │ %(message)s")
+logger = logging.getLogger("EEG-Backend")
+
+# ─── Constants ────────────────────────────────────────────────────────────────
+SAMPLE_RATE = 250          # Hz – Cyton+Daisy
+N_CHANNELS = 16
+EPOCH_DURATION = 4.0       # seconds
+BASELINE_DURATION = 1.0    # seconds pre-stimulus
+BUFFER_SECONDS = 30
+ALPHA_BAND = (8, 13)
+BETA_BAND  = (13, 30)
+THETA_BAND = (4, 8)
+GAMMA_BAND = (30, 45)
+
+# Standard 10-20 positions for 16-ch parieto-occipital cap
+ELECTRODE_POSITIONS_16CH = {
+    "P3":  (-0.30,  0.50), "Pz":  (0.00,  0.58), "P4":  (0.30,  0.50),
+    "P7":  (-0.55,  0.42), "P8":  (0.55,  0.42),
+    "PO3": (-0.22,  0.38), "POz": (0.00,  0.38), "PO4": (0.22,  0.38),
+    "PO7": (-0.40,  0.28), "PO8": (0.40,  0.28),
+    "O1":  (-0.20,  0.18), "Oz":  (0.00,  0.18), "O2":  (0.20,  0.18),
+    "CP3": (-0.25,  0.68), "CPz": (0.00,  0.72), "CP4": (0.25,  0.68),
+}
+CHANNEL_NAMES = list(ELECTRODE_POSITIONS_16CH.keys())
+
+# ─── Data Structures ──────────────────────────────────────────────────────────
+
+class SessionPhase(str, Enum):
+    IDLE = "IDLE"
+    BASELINE = "BASELINE"
+    ACQUISITION = "ACQUISITION"
+    FEEDBACK = "FEEDBACK"
+    CONVERGENCE = "CONVERGENCE"
+    LIBRARY = "LIBRARY"
+
+@dataclass
+class Trial:
+    trial_id: int
+    class_label: str
+    onset_time: float
+    quality_score: Optional[int] = None          # 1-5 self-report
+    eeg_epoch: Optional[np.ndarray] = None        # (n_channels, n_samples)
+    features: Optional[np.ndarray] = None
+    nf_score: Optional[float] = None             # neurofeedback distance [0,1]
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+
+    def to_dict(self) -> dict:
+        return {
+            "trial_id": self.trial_id,
+            "class_label": self.class_label,
+            "onset_time": self.onset_time,
+            "quality_score": self.quality_score,
+            "nf_score": self.nf_score,
+            "timestamp": self.timestamp,
+        }
+
+@dataclass
+class NeuralState:
+    """Stable neural state = cluster centroid in feature space"""
+    class_label: str
+    centroid: np.ndarray
+    covariance: np.ndarray
+    n_trials: int
+    convergence_score: float   # how tight the cluster is [0,1]
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat())
+
+@dataclass
+class SessionConfig:
+    subject_id: str = "S001"
+    session_id: str = field(default_factory=lambda: datetime.now().strftime("%Y%m%d_%H%M%S"))
+    class_a: str = "Class_A"
+    class_b: str = "Class_B"
+    n_trials_per_class: int = 20
+    min_quality_for_model: int = 4        # only use trials rated ≥ 4
+    feedback_threshold: float = 0.65      # similarity to converge
+    port: str = "/dev/ttyUSB0"
+    board_id: int = 2                     # 2=Cyton+Daisy
+    simulate: bool = not BRAINFLOW_AVAILABLE
+
+# ─── Signal Processing ────────────────────────────────────────────────────────
+
+class SignalProcessor:
+    def __init__(self, srate: int = SAMPLE_RATE, n_channels: int = N_CHANNELS):
+        self.srate = srate
+        self.n_channels = n_channels
+        self._design_filters()
+
+    def _design_filters(self):
+        """Pre-compute Butterworth filters"""
+        nyq = self.srate / 2
+        self.bp_coefs = {}
+        for name, (lo, hi) in [("broad", (1, 45)), ("alpha", ALPHA_BAND),
+                                 ("beta", BETA_BAND), ("theta", THETA_BAND)]:
+            b, a = butter(4, [lo/nyq, hi/nyq], btype="band")
+            self.bp_coefs[name] = (b, a)
+        # Notch 50/60 Hz
+        b60, a60 = butter(4, [58/nyq, 62/nyq], btype="bandstop")
+        b50, a50 = butter(4, [48/nyq, 52/nyq], btype="bandstop")
+        self.notch_60 = (b60, a60)
+        self.notch_50 = (b50, a50)
+
+    def preprocess(self, epoch: np.ndarray) -> np.ndarray:
+        """Band-pass + notch filter. epoch: (n_ch, n_samples)"""
+        out = epoch.copy().astype(float)
+        b, a = self.bp_coefs["broad"]
+        bn60, an60 = self.notch_60
+        for ch in range(out.shape[0]):
+            out[ch] = filtfilt(b, a, out[ch])
+            out[ch] = filtfilt(bn60, an60, out[ch])
+            # Remove DC
+            out[ch] -= out[ch].mean()
+        return out
+
+    def compute_psd(self, epoch: np.ndarray, fmax: float = 50.0) -> Tuple[np.ndarray, np.ndarray]:
+        """Welch PSD per channel. Returns (freqs, psd): psd shape (n_ch, n_freqs)"""
+        nperseg = min(self.srate, epoch.shape[1])
+        freqs, psd = welch(epoch, fs=self.srate, nperseg=nperseg, axis=1)
+        mask = freqs <= fmax
+        return freqs[mask], psd[:, mask]
+
+    def band_power(self, epoch: np.ndarray) -> Dict[str, np.ndarray]:
+        """Band power per channel per band. Returns dict of (n_ch,) arrays"""
+        freqs, psd = self.compute_psd(epoch)
+        powers = {}
+        for name, (lo, hi) in [("alpha", ALPHA_BAND), ("beta", BETA_BAND),
+                                 ("theta", THETA_BAND), ("gamma", GAMMA_BAND)]:
+            idx = np.logical_and(freqs >= lo, freqs <= hi)
+            powers[name] = np.trapz(psd[:, idx], freqs[idx], axis=1)
+        return powers
+
+    def extract_features(self, epoch: np.ndarray) -> np.ndarray:
+        """
+        Feature vector: band-power ratios + log-band-powers + covariance diagonal
+        Returns 1D numpy array
+        """
+        clean = self.preprocess(epoch)
+        bp = self.band_power(clean)
+        alpha = bp["alpha"] + 1e-10
+        beta  = bp["beta"]  + 1e-10
+        theta = bp["theta"] + 1e-10
+        gamma = bp["gamma"] + 1e-10
+
+        feats = []
+        feats.extend(np.log(alpha))                 # 16 log-alpha
+        feats.extend(np.log(beta))                  # 16 log-beta
+        feats.extend(np.log(theta))                 # 16 log-theta
+        feats.extend(beta / alpha)                  # 16 beta/alpha
+        feats.extend(theta / alpha)                 # 16 theta/alpha
+        # Covariance diagonal (channel variances)
+        cov = np.cov(clean)
+        feats.extend(np.log(np.diag(cov) + 1e-10))  # 16 log-var
+
+        # Frontal asymmetry (not applicable for occipital, skip ratio index)
+        return np.array(feats, dtype=float)
+
+    def compute_topomap(self, epoch: np.ndarray) -> Dict[str, float]:
+        """Return per-channel alpha power for topomap display"""
+        clean = self.preprocess(epoch)
+        bp = self.band_power(clean)
+        return {name: float(val) for name, val in zip(CHANNEL_NAMES, bp["alpha"])}
+
+    def artifact_rejection(self, epoch: np.ndarray, threshold_uv: float = 100.0) -> bool:
+        """Returns True if epoch is clean"""
+        peak_to_peak = epoch.max(axis=1) - epoch.min(axis=1)
+        return bool(np.all(peak_to_peak < threshold_uv * 1e-6))  # BrainFlow in Volts
+
+# ─── Neurofeedback Engine ─────────────────────────────────────────────────────
+
+class NeurofeedbackEngine:
+    """
+    Computes similarity between current epoch features and stored neural state centroids.
+    Score ∈ [0,1] where 1 = perfectly matching the target state.
+    """
+    def __init__(self):
+        self.states: Dict[str, NeuralState] = {}
+
+    def update_state(self, class_label: str, features_list: List[np.ndarray]):
+        """Build/update stable state from a list of high-quality feature vectors"""
+        if len(features_list) < 3:
+            return
+        mat = np.stack(features_list)
+        centroid = mat.mean(axis=0)
+        cov = np.cov(mat.T) + np.eye(mat.shape[1]) * 1e-6
+        # Convergence = 1 - normalised mean intra-cluster distance
+        dists = [np.linalg.norm(f - centroid) for f in features_list]
+        convergence = max(0.0, 1.0 - np.mean(dists) / (np.std(dists) + 1.0))
+        self.states[class_label] = NeuralState(
+            class_label=class_label,
+            centroid=centroid,
+            covariance=cov,
+            n_trials=len(features_list),
+            convergence_score=float(convergence),
+        )
+        logger.info(f"Neural state updated for {class_label}: convergence={convergence:.3f}")
+
+    def compute_similarity(self, features: np.ndarray, class_label: str) -> float:
+        """Mahalanobis-based similarity to target state"""
+        if class_label not in self.states:
+            return 0.0
+        state = self.states[class_label]
+        diff = features - state.centroid
+        try:
+            inv_cov = np.linalg.pinv(state.covariance)
+            dist = float(np.sqrt(diff @ inv_cov @ diff))
+            # Sigmoid mapping: dist=0 → score=1, dist=5 → score≈0.5
+            score = 1.0 / (1.0 + dist / 3.0)
+        except Exception:
+            score = 0.0
+        return float(np.clip(score, 0.0, 1.0))
+
+    def get_feedback_audio_params(self, score: float) -> dict:
+        """Returns audio synthesis params based on NF score"""
+        freq_hz = 200 + score * 600      # 200–800 Hz
+        volume  = 0.3 + score * 0.7      # 0.3–1.0
+        tone    = "positive" if score > 0.65 else ("neutral" if score > 0.35 else "negative")
+        return {"freq_hz": round(freq_hz, 1), "volume": round(volume, 3), "tone": tone}
+
+# ─── LDA Classifier ───────────────────────────────────────────────────────────
+
+class EEGClassifier:
+    def __init__(self):
+        if SKLEARN_AVAILABLE:
+            self.model = Pipeline([
+                ("scaler", StandardScaler()),
+                ("lda", LinearDiscriminantAnalysis(solver="svd")),
+            ])
+        self.is_trained = False
+        self.classes_: List[str] = []
+
+    def fit(self, X: np.ndarray, y: List[str]):
+        if not SKLEARN_AVAILABLE or len(X) < 6:
+            return False
+        self.model.fit(X, y)
+        self.is_trained = True
+        self.classes_ = list(np.unique(y))
+        logger.info(f"LDA trained on {len(X)} epochs, classes={self.classes_}")
+        return True
+
+    def predict_proba(self, features: np.ndarray) -> Dict[str, float]:
+        if not self.is_trained:
+            return {}
+        proba = self.model.predict_proba(features.reshape(1, -1))[0]
+        return {cls: float(p) for cls, p in zip(self.classes_, proba)}
+
+# ─── LSL Manager ──────────────────────────────────────────────────────────────
+
+class LSLManager:
+    def __init__(self, stream_name: str = "EEGMarkers"):
+        self.outlet = None
+        self.eeg_outlet = None
+        if LSL_AVAILABLE:
+            self._init_marker_stream(stream_name)
+            self._init_eeg_stream()
+
+    def _init_marker_stream(self, name: str):
+        info = StreamInfo(name, "Markers", 1, 0, cf_string, f"markers-{name}")
+        info.desc().append_child_value("manufacturer", "EEG-MI-Backend")
+        self.outlet = StreamOutlet(info)
+        logger.info(f"LSL marker stream '{name}' opened")
+
+    def _init_eeg_stream(self):
+        info = StreamInfo("EEG-MI", "EEG", N_CHANNELS, SAMPLE_RATE, cf_float32, "eeg-mi")
+        chns = info.desc().append_child("channels")
+        for name in CHANNEL_NAMES:
+            ch = chns.append_child("channel")
+            ch.append_child_value("label", name)
+            ch.append_child_value("unit", "microvolts")
+            ch.append_child_value("type", "EEG")
+        self.eeg_outlet = StreamOutlet(info, 32, 360)
+        logger.info("LSL EEG stream opened")
+
+    def push_marker(self, marker: str):
+        if self.outlet:
+            self.outlet.push_sample([marker])
+            logger.debug(f"LSL marker: {marker}")
+
+    def push_eeg_chunk(self, chunk: np.ndarray):
+        """chunk: (n_samples, n_channels)"""
+        if self.eeg_outlet and chunk.size > 0:
+            self.eeg_outlet.push_chunk(chunk.tolist())
+
+# ─── Board Manager ────────────────────────────────────────────────────────────
+
+class BoardManager:
+    """Handles Cyton+Daisy board or simulation"""
+
+    def __init__(self, config: SessionConfig):
+        self.config = config
+        self.board = None
+        self.board_id = config.board_id
+        self.srate = SAMPLE_RATE
+        self._running = False
+        self._thread: Optional[threading.Thread] = None
+        self._buffer = deque(maxlen=BUFFER_SECONDS * SAMPLE_RATE)
+        self._lock = threading.Lock()
+        self.connected = False
+
+        # Simulation state
+        self._sim_t = 0.0
+        self._sim_phase = 0.0
+
+    def connect(self) -> bool:
+        if self.config.simulate:
+            logger.info("Board: SIMULATION mode active")
+            self.connected = True
+            return True
+
+        if not BRAINFLOW_AVAILABLE:
+            logger.error("BrainFlow not available; cannot connect to hardware")
+            return False
+
+        params = BrainFlowInputParams()
+        params.serial_port = self.config.port
+        try:
+            BoardShim.enable_dev_board_logger()
+            self.board = BoardShim(self.board_id, params)
+            self.board.prepare_session()
+            self.board.start_stream(45000)
+            self.srate = BoardShim.get_sampling_rate(self.board_id)
+            self.connected = True
+            logger.info(f"Cyton+Daisy connected: {self.config.port} @ {self.srate} Hz")
+            return True
+        except BrainFlowError as e:
+            logger.error(f"Board connection failed: {e}")
+            return False
+
+    def disconnect(self):
+        self._running = False
+        if self.board and BRAINFLOW_AVAILABLE:
+            try:
+                self.board.stop_stream()
+                self.board.release_session()
+            except Exception:
+                pass
+        self.connected = False
+
+    def start_acquisition(self):
+        self._running = True
+        self._thread = threading.Thread(target=self._acquisition_loop, daemon=True)
+        self._thread.start()
+
+    def stop_acquisition(self):
+        self._running = False
+
+    def _acquisition_loop(self):
+        while self._running:
+            if self.config.simulate:
+                chunk = self._generate_sim_chunk(50)  # 50 samples at a time
+            else:
+                chunk = self._read_board_chunk()
+
+            if chunk is not None and chunk.shape[1] > 0:
+                with self._lock:
+                    for s in range(chunk.shape[1]):
+                        self._buffer.append(chunk[:, s])
+            time.sleep(0.05)
+
+    def _read_board_chunk(self) -> Optional[np.ndarray]:
+        try:
+            data = self.board.get_board_data()
+            eeg_channels = BoardShim.get_eeg_channels(self.board_id)
+            if data.shape[1] == 0:
+                return None
+            return data[eeg_channels[:N_CHANNELS], :]  # (16, n_samples)
+        except Exception as e:
+            logger.warning(f"Board read error: {e}")
+            return None
+
+    def _generate_sim_chunk(self, n_samples: int) -> np.ndarray:
+        """Realistic EEG simulation: alpha rhythm + noise + ocular artifacts"""
+        chunk = np.zeros((N_CHANNELS, n_samples))
+        t = np.linspace(self._sim_t, self._sim_t + n_samples/SAMPLE_RATE, n_samples)
+        self._sim_t += n_samples / SAMPLE_RATE
+
+        for ch in range(N_CHANNELS):
+            # Alpha (8-12 Hz) with spatial gradient
+            alpha_amp = (0.5 + 0.5 * math.sin(ch * 0.4)) * 15e-6
+            alpha = alpha_amp * np.sin(2 * np.pi * 10 * t + ch * 0.3)
+            # Beta (13-25 Hz)
+            beta = 5e-6 * np.sin(2 * np.pi * 20 * t + ch * 0.6)
+            # Theta (4-8 Hz) – stronger in frontal (not this cap, but simulated)
+            theta = 8e-6 * np.sin(2 * np.pi * 6 * t)
+            # White noise
+            noise = np.random.randn(n_samples) * 3e-6
+            chunk[ch] = alpha + beta + theta + noise
+
+        # Occasional blink artifact on ch 0-1
+        if np.random.rand() < 0.02:
+            idx = np.random.randint(0, max(1, n_samples - 20))
+            pulse = np.hanning(20) * 150e-6
+            end = min(idx + 20, n_samples)
+            chunk[0, idx:end] += pulse[:end-idx]
+            chunk[1, idx:end] += pulse[:end-idx] * 0.5
+
+        return chunk
+
+    def get_epoch(self, duration: float, offset: float = 0.0) -> Optional[np.ndarray]:
+        """Extract latest epoch of `duration` seconds. Returns (n_ch, n_samples)"""
+        n_wanted = int((duration + offset) * SAMPLE_RATE)
+        with self._lock:
+            buf = list(self._buffer)
+        if len(buf) < n_wanted:
+            return None
+        arr = np.array(buf[-n_wanted:]).T  # (n_ch, n_samples)
+        # Return only the epoch portion (skip offset)
+        n_offset = int(offset * SAMPLE_RATE)
+        return arr[:, n_offset:]
+
+    def get_psd_snapshot(self) -> Optional[np.ndarray]:
+        """Latest 2-second window for live display (n_ch, n_samples)"""
+        return self.get_epoch(2.0)
+
+# ─── Session Manager ──────────────────────────────────────────────────────────
+
+class SessionManager:
+    def __init__(self):
+        self.config = SessionConfig()
+        self.phase = SessionPhase.IDLE
+        self.trials: List[Trial] = []
+        self.trial_counter = 0
+        self.current_class: Optional[str] = None
+        self.target_class: Optional[str] = None
+
+        self.processor  = SignalProcessor()
+        self.nf_engine  = NeurofeedbackEngine()
+        self.classifier = EEGClassifier()
+        self.lsl        = LSLManager()
+        self.board      = BoardManager(self.config)
+
+        self._ws_clients: List[WebSocket] = []
+        self._event_queue: asyncio.Queue = asyncio.Queue()
+        self._current_loop: Optional[asyncio.AbstractEventLoop] = None
+
+    # ── Connection Management ──────────────────────────────────────────────
+
+    def connect_board(self) -> dict:
+        ok = self.board.connect()
+        if ok:
+            self.board.start_acquisition()
+            self.lsl.push_marker("SESSION_START")
+        return {"status": "connected" if ok else "error", "simulate": self.config.simulate}
+
+    def disconnect_board(self):
+        self.board.disconnect()
+        self.lsl.push_marker("SESSION_END")
+
+    # ── Trial Management ───────────────────────────────────────────────────
+
+    def start_trial(self, class_label: str) -> Trial:
+        self.trial_counter += 1
+        onset = time.time()
+        trial = Trial(
+            trial_id=self.trial_counter,
+            class_label=class_label,
+            onset_time=onset,
+        )
+        self.trials.append(trial)
+        self.current_class = class_label
+        self.phase = SessionPhase.ACQUISITION
+
+        marker = f"TRIAL_START;class={class_label};id={self.trial_counter}"
+        self.lsl.push_marker(marker)
+        logger.info(f"Trial {self.trial_counter} started: {class_label}")
+        return trial
+
+    def end_trial(self, quality: int) -> dict:
+        """Called after subject rates the trial 1-5"""
+        active = self._get_active_trial()
+        if not active:
+            return {"error": "no active trial"}
+
+        active.quality_score = quality
+        self.lsl.push_marker(f"TRIAL_END;id={active.trial_id};quality={quality}")
+
+        # Extract epoch (4s before now, skip first 0.5s baseline)
+        epoch = self.board.get_epoch(EPOCH_DURATION, offset=0.5)
+        if epoch is not None:
+            # Artifact check
+            clean = self.processor.artifact_rejection(epoch)
+            if clean:
+                active.eeg_epoch = epoch
+                active.features = self.processor.extract_features(epoch)
+                logger.info(f"Trial {active.trial_id}: clean epoch extracted, quality={quality}")
+            else:
+                logger.warning(f"Trial {active.trial_id}: artifact detected – epoch discarded")
+                self.lsl.push_marker(f"ARTIFACT;id={active.trial_id}")
+
+        # Update model if quality ≥ threshold
+        self._maybe_update_model(active.class_label)
+
+        # Compute NF score if model exists
+        nf = 0.0
+        if active.features is not None:
+            nf = self.nf_engine.compute_similarity(active.features, active.class_label)
+            active.nf_score = nf
+
+        return {
+            "trial_id": active.trial_id,
+            "quality": quality,
+            "nf_score": round(nf, 4),
+            "feedback": self.nf_engine.get_feedback_audio_params(nf),
+            "model_updated": active.class_label in self.nf_engine.states,
+        }
+
+    def _get_active_trial(self) -> Optional[Trial]:
+        for t in reversed(self.trials):
+            if t.quality_score is None:
+                return t
+        return None
+
+    def _maybe_update_model(self, class_label: str):
+        """Rebuild neural state from high-quality trials"""
+        good_features = [
+            t.features for t in self.trials
+            if t.class_label == class_label
+            and t.quality_score is not None
+            and t.quality_score >= self.config.min_quality_for_model
+            and t.features is not None
+        ]
+        if len(good_features) >= 3:
+            self.nf_engine.update_state(class_label, good_features)
+            # Retrain classifier if both classes have data
+            self._retrain_classifier()
+
+    def _retrain_classifier(self):
+        X, y = [], []
+        for t in self.trials:
+            if t.features is not None and t.quality_score is not None \
+               and t.quality_score >= self.config.min_quality_for_model:
+                X.append(t.features)
+                y.append(t.class_label)
+        if len(set(y)) >= 2:
+            self.classifier.fit(np.array(X), y)
+
+    # ── Live Signals ───────────────────────────────────────────────────────
+
+    def get_live_signals(self) -> dict:
+        epoch = self.board.get_psd_snapshot()
+        if epoch is None:
+            # Return synthetic zeros
+            return {
+                "channels": CHANNEL_NAMES,
+                "alpha_power": [0.0] * N_CHANNELS,
+                "beta_power":  [0.0] * N_CHANNELS,
+                "theta_power": [0.0] * N_CHANNELS,
+                "raw_samples": [[0.0] * 50] * 4,  # 4 channels preview
+                "topomap": {n: 0.0 for n in CHANNEL_NAMES},
+                "signal_quality": [0.0] * N_CHANNELS,
+            }
+
+        try:
+            clean = self.processor.preprocess(epoch)
+            bp = self.processor.band_power(clean)
+            topo = self.processor.compute_topomap(epoch)
+
+            # Signal quality: inverse of variance relative to expected range
+            peak2peak = (epoch.max(axis=1) - epoch.min(axis=1)) * 1e6  # µV
+            quality = [float(np.clip(1.0 - (pp - 10) / 90.0, 0.0, 1.0)) for pp in peak2peak]
+
+            # Raw traces for 4 selected channels (µV)
+            sel = [0, 4, 8, 12]
+            raw = (clean[sel, -50:] * 1e6).tolist()  # last 200ms
+
+            return {
+                "channels": CHANNEL_NAMES,
+                "alpha_power": [float(v * 1e12) for v in bp["alpha"]],
+                "beta_power":  [float(v * 1e12) for v in bp["beta"]],
+                "theta_power": [float(v * 1e12) for v in bp["theta"]],
+                "raw_samples": raw,
+                "topomap": {k: float(v * 1e12) for k, v in topo.items()},
+                "signal_quality": quality,
+            }
+        except Exception as e:
+            logger.warning(f"Live signal error: {e}")
+            return {}
+
+    # ── Session State ──────────────────────────────────────────────────────
+
+    def get_state(self) -> dict:
+        class_a_trials = [t.to_dict() for t in self.trials if t.class_label == self.config.class_a]
+        class_b_trials = [t.to_dict() for t in self.trials if t.class_label == self.config.class_b]
+
+        states = {}
+        for label, state in self.nf_engine.states.items():
+            states[label] = {
+                "n_trials": state.n_trials,
+                "convergence_score": round(state.convergence_score, 4),
+                "created_at": state.created_at,
+            }
+
+        return {
+            "phase": self.phase.value,
+            "config": {
+                "subject_id": self.config.subject_id,
+                "session_id": self.config.session_id,
+                "class_a": self.config.class_a,
+                "class_b": self.config.class_b,
+                "simulate": self.config.simulate,
+                "min_quality_for_model": self.config.min_quality_for_model,
+            },
+            "class_a_trials": class_a_trials,
+            "class_b_trials": class_b_trials,
+            "neural_states": states,
+            "classifier_trained": self.classifier.is_trained,
+            "board_connected": self.board.connected,
+            "total_trials": len(self.trials),
+        }
+
+    # ── WebSocket Broadcast ────────────────────────────────────────────────
+
+    def add_ws_client(self, ws: WebSocket):
+        self._ws_clients.append(ws)
+
+    def remove_ws_client(self, ws: WebSocket):
+        if ws in self._ws_clients:
+            self._ws_clients.remove(ws)
+
+    async def broadcast(self, data: dict):
+        dead = []
+        for ws in self._ws_clients:
+            try:
+                await ws.send_json(data)
+            except Exception:
+                dead.append(ws)
+        for ws in dead:
+            self.remove_ws_client(ws)
+
+    async def live_broadcast_loop(self):
+        """Continuously push live EEG data to all connected WS clients"""
+        while True:
+            await asyncio.sleep(0.1)  # 10 Hz update
+            if self._ws_clients and self.board.connected:
+                live = self.get_live_signals()
+                if live:
+                    live["type"] = "live_eeg"
+                    live["timestamp"] = time.time()
+                    await self.broadcast(live)
+
+# ─── FastAPI App ──────────────────────────────────────────────────────────────
+
+ROOT_DIR = Path(__file__).resolve().parent
+SITE_HTML = ROOT_DIR / "site.html"
+
+app = FastAPI(title="EEG Mental Imagery Backend", version="2.0.0")
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+session = SessionManager()
+
+
+@app.get("/")
+def serve_ui():
+    """Serve the project UI (site.html) from the same origin as the API / WebSocket."""
+    if not SITE_HTML.is_file():
+        return JSONResponse(
+            status_code=404,
+            content={"error": "site.html not found", "path": str(SITE_HTML)},
+        )
+    return FileResponse(SITE_HTML, media_type="text/html; charset=utf-8")
+
+@app.on_event("startup")
+async def startup():
+    asyncio.create_task(session.live_broadcast_loop())
+    logger.info("EEG Backend started")
+
+# ── REST Endpoints ─────────────────────────────────────────────────────────
+
+@app.get("/health")
+def health():
+    return {"status": "ok", "brainflow": BRAINFLOW_AVAILABLE, "lsl": LSL_AVAILABLE,
+            "sklearn": SKLEARN_AVAILABLE, "scipy": SCIPY_AVAILABLE}
+
+@app.post("/board/connect")
+def connect_board(port: str = "/dev/ttyUSB0", simulate: bool = False):
+    session.config.port = port
+    session.config.simulate = simulate or not BRAINFLOW_AVAILABLE
+    return session.connect_board()
+
+@app.post("/board/disconnect")
+def disconnect_board():
+    session.disconnect_board()
+    return {"status": "disconnected"}
+
+@app.post("/session/configure")
+def configure_session(
+    subject_id: str = "S001",
+    class_a: str = "Apple",
+    class_b: str = "House",
+    min_quality: int = 4
+):
+    session.config.subject_id = subject_id
+    session.config.class_a = class_a
+    session.config.class_b = class_b
+    session.config.min_quality_for_model = min_quality
+    session.config.session_id = datetime.now().strftime("%Y%m%d_%H%M%S")
+    return {"status": "configured", "config": asdict(session.config)}
+
+@app.post("/trial/start")
+def start_trial(class_label: str):
+    trial = session.start_trial(class_label)
+    return trial.to_dict()
+
+@app.post("/trial/end")
+def end_trial(quality: int):
+    return session.end_trial(quality)
+
+@app.get("/state")
+def get_state():
+    return session.get_state()
+
+@app.get("/signals/live")
+def live_signals():
+    return session.get_live_signals()
+
+@app.get("/channels/info")
+def channel_info():
+    return {
+        "n_channels": N_CHANNELS,
+        "channel_names": CHANNEL_NAMES,
+        "positions": ELECTRODE_POSITIONS_16CH,
+        "sample_rate": SAMPLE_RATE,
+    }
+
+@app.post("/lsl/marker")
+def push_marker(marker: str):
+    session.lsl.push_marker(marker)
+    return {"pushed": marker, "timestamp": time.time()}
+
+@app.get("/classifier/predict")
+def predict_current():
+    epoch = session.board.get_epoch(EPOCH_DURATION)
+    if epoch is None:
+        return {"error": "no data"}
+    feats = session.processor.extract_features(epoch)
+    proba = session.classifier.predict_proba(feats)
+    nf_a = session.nf_engine.compute_similarity(feats, session.config.class_a)
+    nf_b = session.nf_engine.compute_similarity(feats, session.config.class_b)
+    return {
+        "probabilities": proba,
+        "nf_similarity": {session.config.class_a: nf_a, session.config.class_b: nf_b},
+        "timestamp": time.time(),
+    }
+
+@app.post("/session/reset")
+def reset_session():
+    session.trials.clear()
+    session.trial_counter = 0
+    session.nf_engine.states.clear()
+    session.classifier.is_trained = False
+    session.phase = SessionPhase.IDLE
+    return {"status": "reset"}
+
+# ── WebSocket ──────────────────────────────────────────────────────────────
+
+@app.websocket("/ws")
+async def websocket_endpoint(ws: WebSocket):
+    await ws.accept()
+    session.add_ws_client(ws)
+    logger.info(f"WebSocket client connected. Total: {len(session._ws_clients)}")
+    try:
+        while True:
+            msg = await ws.receive_json()
+            msg_type = msg.get("type", "")
+
+            if msg_type == "ping":
+                await ws.send_json({"type": "pong", "timestamp": time.time()})
+
+            elif msg_type == "state":
+                await ws.send_json({"type": "state", **session.get_state()})
+
+            elif msg_type == "start_trial":
+                trial = session.start_trial(msg["class_label"])
+                await ws.send_json({"type": "trial_started", **trial.to_dict()})
+
+            elif msg_type == "end_trial":
+                result = session.end_trial(msg["quality"])
+                await ws.send_json({"type": "trial_ended", **result})
+                # Broadcast state update to all clients
+                await session.broadcast({"type": "state_update", **session.get_state()})
+
+            elif msg_type == "configure":
+                session.config.subject_id = msg.get("subject_id", session.config.subject_id)
+                session.config.class_a = msg.get("class_a", session.config.class_a)
+                session.config.class_b = msg.get("class_b", session.config.class_b)
+                mq = msg.get("min_quality")
+                if mq is not None:
+                    session.config.min_quality_for_model = int(mq)
+                await ws.send_json({"type": "configured"})
+
+            elif msg_type == "connect_board":
+                session.config.simulate = msg.get("simulate", True)
+                if msg.get("port"):
+                    session.config.port = str(msg["port"])
+                result = session.connect_board()
+                await ws.send_json({"type": "board_status", **result})
+
+    except WebSocketDisconnect:
+        session.remove_ws_client(ws)
+        logger.info(f"WebSocket client disconnected. Remaining: {len(session._ws_clients)}")
+
+# ─── Entry Point ──────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    uvicorn.run("backend:app", host="0.0.0.0", port=8765, reload=False, log_level="info")

requirements.txt

@@ -0,0 +1,10 @@
+fastapi>=0.110.0
+uvicorn[standard]>=0.29.0
+numpy>=1.26.0
+scipy>=1.12.0
+scikit-learn>=1.4.0
+brainflow>=5.12.0
+pylsl>=1.16.0
+websockets>=12.0
+python-multipart>=0.0.9
+ 

site.html

@@ -0,0 +1,2235 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Neural State Classifier · EEG Mental Imagery</title>
+<style>
+@import url('https://fonts.googleapis.com/css2?family=DM+Mono:wght@300;400;500&family=DM+Sans:wght@200;300;400;500&display=swap');
+
+:root {
+  /* Semantic tokens (referenced throughout) */
+  --color-background-primary: #FAFAF8;
+  --color-background-secondary: #F3F2EE;
+  --color-background-tertiary: #EAE8E3;
+  --color-text-primary: #1C1B19;
+  --color-text-secondary: #4D4C47;
+  --color-text-tertiary: #8E8C86;
+  --color-border-tertiary: #DAD7D1;
+  --color-border-secondary: #C5C2BB;
+  --font-sans: 'DM Sans', system-ui, -apple-system, 'Segoe UI', sans-serif;
+  --border-radius-lg: 10px;
+  --border-radius-md: 8px;
+  --shadow-sm: 0 1px 2px rgba(24, 22, 18, 0.06);
+  --shadow-md: 0 8px 32px rgba(24, 22, 18, 0.08);
+  --focus-ring: 0 0 0 2px var(--bg), 0 0 0 4px var(--accent);
+
+  --bg: var(--color-background-primary);
+  --bg2: var(--color-background-secondary);
+  --bg3: var(--color-background-tertiary);
+  --txt: var(--color-text-primary);
+  --txt2: var(--color-text-secondary);
+  --txt3: var(--color-text-tertiary);
+  --border: var(--color-border-tertiary);
+  --border2: var(--color-border-secondary);
+  --accent: #185FA5;
+  --accent-light: #E6F1FB;
+  --teal: #0F6E56;
+  --teal-light: #E1F5EE;
+  --amber: #854F0B;
+  --amber-light: #FAEEDA;
+  --coral: #993C1D;
+  --coral-light: #FAECE7;
+  --purple: #3C3489;
+  --purple-light: #EEEDFE;
+  --mono: 'DM Mono', ui-monospace, 'Cascadia Mono', monospace;
+  --sans: var(--font-sans);
+}
+
+* { box-sizing: border-box; margin: 0; padding: 0; }
+
+html {
+  height: 100%;
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  font-family: var(--sans);
+  min-height: 100%;
+  background: linear-gradient(165deg, var(--color-background-secondary) 0%, var(--color-background-primary) 45%, #EFECE6 100%);
+  background-attachment: fixed;
+  color: var(--txt);
+  font-size: 13px;
+  line-height: 1.45;
+  -webkit-font-smoothing: antialiased;
+}
+
+::selection {
+  background: var(--accent-light);
+  color: var(--txt);
+}
+
+.app {
+  display: grid;
+  grid-template-columns: minmax(180px, 220px) 1fr;
+  grid-template-rows: auto 1fr;
+  min-height: min(720px, 100vh);
+  max-width: 1400px;
+  margin: 12px auto;
+  padding: 0 12px 12px;
+  border: 0.5px solid var(--border);
+  border-radius: var(--border-radius-lg);
+  overflow: hidden;
+  background: var(--bg);
+  box-shadow: var(--shadow-md);
+}
+
+/* HEADER */
+.header {
+  grid-column: 1 / -1;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 20px;
+  border-bottom: 0.5px solid var(--border);
+  background: var(--bg);
+}
+
+.header-left {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.logo-mark {
+  width: 28px;
+  height: 28px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.header-title {
+  font-size: 12px;
+  font-weight: 500;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: var(--txt2);
+}
+
+.header-sub {
+  font-size: 11px;
+  color: var(--txt3);
+  font-family: var(--mono);
+  margin-top: 1px;
+}
+
+.status-row {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.status-pill {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 11px;
+  font-family: var(--mono);
+  color: var(--txt3);
+}
+
+.dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--color-border-secondary);
+}
+
+.dot.active {
+  background: #1D9E75;
+  animation: pulse 2s ease-in-out infinite;
+}
+
+.dot.warn {
+  background: #BA7517;
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.4; }
+}
+
+/* SIDEBAR */
+.sidebar {
+  border-right: 0.5px solid var(--border);
+  background: var(--bg2);
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.sidebar-section {
+  padding: 14px 14px 8px;
+  border-bottom: 0.5px solid var(--border);
+}
+
+.sidebar-label {
+  font-size: 10px;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--txt3);
+  font-family: var(--mono);
+  margin-bottom: 8px;
+}
+
+.phase-item {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 8px;
+  border-radius: 6px;
+  cursor: pointer;
+  margin-bottom: 2px;
+  transition: background 0.15s;
+}
+
+.phase-item:hover { background: var(--bg3); }
+.phase-item.active { background: var(--accent-light); }
+
+.phase-num {
+  width: 18px;
+  height: 18px;
+  border-radius: 4px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 10px;
+  font-family: var(--mono);
+  font-weight: 500;
+  background: var(--border);
+  color: var(--txt2);
+  flex-shrink: 0;
+}
+
+.phase-item.active .phase-num {
+  background: var(--accent);
+  color: white;
+}
+
+.phase-item.done .phase-num {
+  background: #1D9E75;
+  color: white;
+}
+
+.phase-text {
+  font-size: 11px;
+  color: var(--txt2);
+  line-height: 1.3;
+}
+
+.phase-item.active .phase-text { color: var(--accent); font-weight: 500; }
+
+.class-pair {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  margin-bottom: 8px;
+}
+
+.class-tag {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 5px 8px;
+  border-radius: 6px;
+  border: 0.5px solid var(--border2);
+  background: var(--bg);
+  cursor: pointer;
+}
+
+.class-tag.a { border-color: #B5D4F4; background: #E6F1FB; }
+.class-tag.b { border-color: #9FE1CB; background: #E1F5EE; }
+
+.class-name {
+  font-size: 11px;
+  font-weight: 500;
+  color: var(--txt);
+}
+
+.class-tag.a .class-name { color: #0C447C; }
+.class-tag.b .class-name { color: #085041; }
+
+.class-trials {
+  font-size: 10px;
+  font-family: var(--mono);
+  color: var(--txt3);
+}
+
+.class-tag.a .class-trials { color: #185FA5; }
+.class-tag.b .class-trials { color: #0F6E56; }
+
+.metric-mini {
+  display: flex;
+  flex-direction: column;
+  padding: 6px 8px;
+  border-radius: 6px;
+  background: var(--bg);
+  border: 0.5px solid var(--border);
+  margin-bottom: 4px;
+}
+
+.metric-mini-label { font-size: 10px; color: var(--txt3); font-family: var(--mono); }
+.metric-mini-value { font-size: 15px; font-weight: 500; color: var(--txt); margin-top: 1px; }
+
+.lib-entry {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 6px;
+  border-radius: 4px;
+  margin-bottom: 2px;
+  cursor: pointer;
+}
+
+.lib-entry:hover { background: var(--bg3); }
+
+.lib-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  flex-shrink: 0;
+}
+
+.lib-text { font-size: 11px; color: var(--txt2); }
+.lib-score { font-size: 10px; font-family: var(--mono); color: var(--txt3); margin-left: auto; }
+
+/* MAIN CONTENT */
+.main {
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+/* TAB BAR */
+.tabbar {
+  display: flex;
+  border-bottom: 0.5px solid var(--border);
+  background: var(--bg);
+  padding: 0 16px;
+  gap: 0;
+}
+
+.tab {
+  padding: 10px 14px;
+  font-size: 12px;
+  color: var(--txt3);
+  cursor: pointer;
+  border-bottom: 2px solid transparent;
+  margin-bottom: -0.5px;
+  transition: color 0.15s;
+  white-space: nowrap;
+}
+
+.tab:hover { color: var(--txt2); }
+.tab.active { color: var(--txt); border-bottom-color: var(--txt); font-weight: 500; }
+
+/* PANELS */
+.panel { display: none; flex: 1; overflow-y: auto; }
+.panel.active { display: flex; flex-direction: column; }
+
+/* ACQUISITION PANEL */
+.acq-layout {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+  padding: 16px;
+  flex: 1;
+}
+
+.card {
+  border: 0.5px solid var(--border);
+  border-radius: var(--border-radius-lg);
+  background: var(--bg);
+  overflow: hidden;
+}
+
+.card-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 14px;
+  border-bottom: 0.5px solid var(--border);
+  background: var(--bg2);
+}
+
+.card-title {
+  font-size: 11px;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.07em;
+  color: var(--txt2);
+  font-family: var(--mono);
+}
+
+.card-badge {
+  font-size: 10px;
+  font-family: var(--mono);
+  padding: 2px 6px;
+  border-radius: 4px;
+  background: var(--accent-light);
+  color: var(--accent);
+}
+
+.card-body { padding: 14px; }
+
+/* EEG topography */
+.topo-container {
+  display: flex;
+  justify-content: center;
+  padding: 8px 0;
+}
+
+/* Trial timeline */
+.trial-row {
+  display: grid;
+  grid-template-columns: 28px 1fr auto auto;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 0;
+  border-bottom: 0.5px solid var(--border);
+}
+
+.trial-row:last-child { border-bottom: none; }
+
+.trial-num {
+  font-size: 11px;
+  font-family: var(--mono);
+  color: var(--txt3);
+  text-align: right;
+}
+
+.trial-bar-wrap {
+  position: relative;
+  height: 8px;
+  border-radius: 4px;
+  background: var(--bg3);
+  overflow: hidden;
+}
+
+.trial-bar {
+  height: 100%;
+  border-radius: 4px;
+  transition: width 0.4s ease;
+}
+
+.trial-score {
+  font-size: 11px;
+  font-family: var(--mono);
+  font-weight: 500;
+  min-width: 16px;
+  text-align: center;
+}
+
+.trial-badge {
+  font-size: 9px;
+  font-family: var(--mono);
+  padding: 1px 5px;
+  border-radius: 3px;
+  min-width: 28px;
+  text-align: center;
+}
+
+.trial-badge.keep { background: #E1F5EE; color: #085041; }
+.trial-badge.drop { background: #F1EFE8; color: #5F5E5A; }
+
+/* Rating stars */
+.rating-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin: 10px 0;
+}
+
+.star-group {
+  display: flex;
+  gap: 6px;
+}
+
+.star {
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 6px;
+  border: 0.5px solid var(--border2);
+  cursor: pointer;
+  font-size: 16px;
+  transition: all 0.15s;
+  background: var(--bg);
+}
+
+.star:hover, .star.sel { 
+  background: #FAEEDA; 
+  border-color: #FAC775;
+  transform: scale(1.05);
+}
+
+.current-trial-info {
+  background: var(--bg2);
+  border-radius: 8px;
+  padding: 12px;
+  margin-bottom: 12px;
+}
+
+.trial-class-label {
+  font-size: 10px;
+  font-family: var(--mono);
+  color: var(--txt3);
+  margin-bottom: 4px;
+}
+
+.trial-object {
+  font-size: 20px;
+  font-weight: 300;
+  color: var(--txt);
+  letter-spacing: 0.02em;
+}
+
+.trial-timer {
+  font-size: 11px;
+  font-family: var(--mono);
+  color: var(--txt3);
+  margin-top: 4px;
+}
+
+/* Progress bar */
+.progress-wrap {
+  height: 3px;
+  background: var(--bg3);
+  border-radius: 2px;
+  margin: 10px 0;
+  overflow: hidden;
+}
+
+.progress-bar {
+  height: 100%;
+  background: var(--accent);
+  border-radius: 2px;
+  transition: width 0.3s;
+}
+
+/* Neurofeedback panel */
+.nf-layout {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 12px;
+  padding: 16px;
+}
+
+.nf-full { grid-column: 1 / -1; }
+
+.convergence-track {
+  position: relative;
+  height: 60px;
+  border: 0.5px solid var(--border);
+  border-radius: 8px;
+  overflow: hidden;
+  background: var(--bg2);
+}
+
+.conv-fill {
+  position: absolute;
+  top: 0; left: 0; bottom: 0;
+  border-radius: 8px 0 0 8px;
+  transition: width 1s ease;
+  opacity: 0.6;
+}
+
+.conv-label {
+  position: absolute;
+  top: 50%;
+  transform: translateY(-50%);
+  right: 10px;
+  font-size: 11px;
+  font-family: var(--mono);
+  color: var(--txt2);
+  z-index: 2;
+}
+
+.conv-pct {
+  position: absolute;
+  top: 50%;
+  transform: translateY(-50%);
+  left: 10px;
+  font-size: 13px;
+  font-weight: 500;
+  font-family: var(--mono);
+  color: var(--txt);
+  z-index: 2;
+}
+
+.audio-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px;
+  border-radius: 6px;
+  background: var(--bg2);
+  margin-bottom: 6px;
+}
+
+.audio-icon {
+  width: 24px;
+  height: 24px;
+  border-radius: 5px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+
+.audio-icon.pos { background: #E1F5EE; }
+.audio-icon.neg { background: #FAECE7; }
+
+.audio-text {
+  flex: 1;
+  font-size: 11px;
+  color: var(--txt2);
+}
+
+.audio-freq {
+  font-size: 10px;
+  font-family: var(--mono);
+  color: var(--txt3);
+}
+
+/* Library panel */
+.lib-layout {
+  padding: 16px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.lib-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 8px;
+}
+
+.lib-card {
+  border: 0.5px solid var(--border);
+  border-radius: var(--border-radius-lg);
+  padding: 12px;
+  background: var(--bg);
+  cursor: pointer;
+  transition: border-color 0.15s, background 0.15s;
+}
+
+.lib-card:hover { background: var(--bg2); border-color: var(--border2); }
+
+.lib-card-name {
+  font-size: 13px;
+  font-weight: 500;
+  margin-bottom: 6px;
+  color: var(--txt);
+}
+
+.lib-card-meta {
+  font-size: 10px;
+  font-family: var(--mono);
+  color: var(--txt3);
+  margin-bottom: 8px;
+  line-height: 1.6;
+}
+
+.lib-card-bar {
+  height: 3px;
+  border-radius: 2px;
+  background: var(--bg3);
+  overflow: hidden;
+}
+
+.lib-card-fill {
+  height: 100%;
+  border-radius: 2px;
+}
+
+.subject-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 8px 10px;
+  border-radius: 6px;
+  background: var(--bg2);
+  margin-bottom: 4px;
+}
+
+.subject-avatar {
+  width: 24px;
+  height: 24px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 10px;
+  font-weight: 500;
+  flex-shrink: 0;
+}
+
+.subject-info { flex: 1; }
+.subject-name { font-size: 12px; font-weight: 500; color: var(--txt); }
+.subject-meta { font-size: 10px; font-family: var(--mono); color: var(--txt3); }
+
+.subject-acc {
+  font-size: 12px;
+  font-family: var(--mono);
+  font-weight: 500;
+}
+
+/* Action buttons */
+.btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 7px 14px;
+  border-radius: 6px;
+  border: 0.5px solid var(--border2);
+  background: var(--bg);
+  color: var(--txt);
+  font-size: 12px;
+  cursor: pointer;
+  transition: background 0.15s;
+  font-family: var(--sans);
+}
+
+.btn:hover { background: var(--bg2); }
+.btn.primary { background: var(--accent); color: white; border-color: var(--accent); }
+.btn.primary:hover { opacity: 0.9; }
+
+/* Bottom actions */
+.panel-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 10px 16px;
+  border-top: 0.5px solid var(--border);
+  background: var(--bg2);
+}
+
+/* Waveform */
+.waveform-wrap {
+  height: 80px;
+  position: relative;
+  overflow: hidden;
+}
+
+canvas.waveform {
+  width: 100%;
+  height: 80px;
+}
+
+/* General info */
+.info-row {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  padding: 5px 0;
+  border-bottom: 0.5px solid var(--border);
+  font-size: 12px;
+}
+
+.info-row:last-child { border-bottom: none; }
+.info-key { color: var(--txt3); font-family: var(--mono); }
+.info-val { color: var(--txt); font-weight: 500; }
+
+.section-title {
+  font-size: 11px;
+  font-weight: 500;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--txt3);
+  font-family: var(--mono);
+  margin-bottom: 8px;
+}
+
+/* ─── Forms & inputs ─── */
+input[type="text"],
+input[type="number"],
+select,
+textarea {
+  font-family: var(--sans);
+  font-size: 12px;
+  padding: 7px 10px;
+  border-radius: 6px;
+  border: 0.5px solid var(--border2);
+  background: var(--bg);
+  color: var(--txt);
+  width: 100%;
+  max-width: 100%;
+  transition: border-color 0.15s, box-shadow 0.15s;
+}
+
+input:focus-visible,
+select:focus-visible,
+textarea:focus-visible {
+  outline: none;
+  border-color: var(--accent);
+  box-shadow: var(--focus-ring);
+}
+
+label.field-label {
+  display: block;
+  font-size: 10px;
+  font-family: var(--mono);
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--txt3);
+  margin-bottom: 4px;
+}
+
+.field-group {
+  margin-bottom: 10px;
+}
+
+/* ─── Sidebar scroll & flex ─── */
+.sidebar-section:last-child {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  scrollbar-width: thin;
+  scrollbar-color: var(--border2) transparent;
+}
+
+.sidebar-section:last-child::-webkit-scrollbar {
+  width: 6px;
+}
+
+.sidebar-section:last-child::-webkit-scrollbar-thumb {
+  background: var(--border2);
+  border-radius: 4px;
+}
+
+/* ─── Panels scroll ─── */
+.panel {
+  scrollbar-width: thin;
+  scrollbar-color: var(--border2) transparent;
+}
+
+.panel::-webkit-scrollbar {
+  width: 8px;
+}
+
+.panel::-webkit-scrollbar-thumb {
+  background: var(--border2);
+  border-radius: 4px;
+}
+
+/* ─── Buttons ─── */
+button.btn {
+  appearance: none;
+  border: 0.5px solid var(--border2);
+}
+
+button.btn:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}
+
+button.btn:disabled {
+  opacity: 0.45;
+  cursor: not-allowed;
+}
+
+.btn.danger {
+  border-color: #E8B4A8;
+  background: var(--coral-light);
+  color: var(--coral);
+}
+
+.btn.danger:hover {
+  background: #F5DCD4;
+}
+
+.btn.ghost {
+  background: transparent;
+  border-color: transparent;
+}
+
+.btn.ghost:hover {
+  background: var(--bg2);
+  border-color: var(--border);
+}
+
+.btn.sm {
+  padding: 5px 10px;
+  font-size: 11px;
+}
+
+/* ─── Tabs accessibility ─── */
+.tab:focus-visible {
+  outline: none;
+  box-shadow: inset 0 -2px 0 var(--accent);
+  color: var(--txt);
+}
+
+.phase-item:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px var(--accent-light);
+}
+
+/* ─── Cards & canvases ─── */
+.card-body canvas {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+#distCanvas {
+  width: 100%;
+  max-width: 100%;
+  height: auto;
+  min-height: 80px;
+}
+
+/* ─── Links ─── */
+a {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}
+
+/* ─── Utility ─── */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.muted { color: var(--txt3); }
+.mono { font-family: var(--mono); }
+.stack { display: flex; flex-direction: column; gap: 8px; }
+
+/* ─── Responsive ─── */
+@media (max-width: 900px) {
+  .app {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto auto 1fr;
+    margin: 0;
+    padding: 0;
+    border-radius: 0;
+    border-left: none;
+    border-right: none;
+    min-height: 100vh;
+    max-width: none;
+  }
+
+  .header {
+    flex-wrap: wrap;
+    gap: 10px;
+  }
+
+  .sidebar {
+    border-right: none;
+    border-bottom: 0.5px solid var(--border);
+    flex-direction: row;
+    flex-wrap: wrap;
+    max-height: none;
+  }
+
+  .sidebar-section {
+    flex: 1 1 140px;
+    border-bottom: 0.5px solid var(--border);
+  }
+
+  .sidebar-section:last-child {
+    flex: 1 1 100%;
+    max-height: 160px;
+  }
+
+  .acq-layout,
+  .nf-layout {
+    grid-template-columns: 1fr;
+  }
+
+  .lib-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+
+  .tabbar {
+    overflow-x: auto;
+    -webkit-overflow-scrolling: touch;
+  }
+}
+
+@media (max-width: 520px) {
+  .lib-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .status-row {
+    flex-wrap: wrap;
+    gap: 8px;
+  }
+
+  .star {
+    width: 28px;
+    height: 28px;
+    font-size: 14px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+
+  .dot.active {
+    animation: none;
+  }
+}
+
+/* ─── Print ─── */
+@media print {
+  body {
+    background: white;
+  }
+
+  .app {
+    box-shadow: none;
+    margin: 0;
+    max-width: none;
+    min-height: auto;
+  }
+
+  .panel-footer,
+  .tabbar .tab:not(.active),
+  .btn {
+    display: none !important;
+  }
+
+  .panel {
+    display: flex !important;
+    overflow: visible;
+  }
+}
+
+</style>
+</head>
+<body>
+
+<h2 class="sr-only">EEG mental-imagery classification paradigm — acquisition, neurofeedback, and object library dashboard</h2>
+
+<div class="app">
+
+  <!-- HEADER -->
+  <div class="header">
+    <div class="header-left">
+      <div class="logo-mark">
+        <svg width="28" height="28" viewBox="0 0 28 28" fill="none">
+          <circle cx="14" cy="14" r="13" stroke="var(--border2)" stroke-width="0.5"/>
+          <circle cx="14" cy="14" r="9" stroke="var(--accent)" stroke-width="0.5" stroke-dasharray="2 2"/>
+          <circle cx="14" cy="14" r="3" fill="var(--accent)"/>
+          <circle cx="14" cy="6" r="1.5" fill="var(--txt3)"/>
+          <circle cx="22" cy="10" r="1.5" fill="var(--txt3)"/>
+          <circle cx="22" cy="18" r="1.5" fill="var(--txt3)"/>
+          <circle cx="14" cy="22" r="1.5" fill="var(--txt3)"/>
+          <circle cx="6" cy="18" r="1.5" fill="var(--txt3)"/>
+          <circle cx="6" cy="10" r="1.5" fill="var(--txt3)"/>
+        </svg>
+      </div>
+      <div>
+        <div class="header-title">Neural State Classifier</div>
+        <div class="header-sub">EEG Mental Imagery Paradigm · 16ch Parieto-Occipital</div>
+      </div>
+    </div>
+    <div class="status-row">
+      <div class="status-pill"><span class="dot" id="dot-phase"></span> <span id="txt-phase">IDLE</span></div>
+      <div class="status-pill"><span class="dot" id="dot-session"></span> <span id="txt-session">— · —</span></div>
+      <div class="status-pill"><span class="dot" id="dot-board"></span> <span id="txt-hz">250 Hz · 16 ch</span></div>
+    </div>
+  </div>
+
+  <!-- SIDEBAR -->
+  <div class="sidebar">
+
+    <div class="sidebar-section">
+      <div class="sidebar-label">Backend</div>
+      <div id="backend-status" style="font-size:10px;font-family:var(--mono);color:var(--txt3);line-height:1.5;margin-bottom:10px">REST: … · WS: … · Board: …</div>
+      <label class="field-label" for="cfg-subject">Subject ID</label>
+      <input id="cfg-subject" type="text" value="S001" autocomplete="off">
+      <label class="field-label" for="cfg-class-a">Class A label</label>
+      <input id="cfg-class-a" type="text" value="Chair" autocomplete="off">
+      <label class="field-label" for="cfg-class-b">Class B label</label>
+      <input id="cfg-class-b" type="text" value="Spiral" autocomplete="off">
+      <label class="field-label" for="cfg-min-q">Min quality (1–5)</label>
+      <input id="cfg-min-q" type="number" min="1" max="5" value="4">
+      <label class="field-label" for="cfg-port">Serial port (hardware)</label>
+      <input id="cfg-port" type="text" placeholder="/dev/ttyUSB0 or COM3" autocomplete="off">
+      <div style="display:flex;flex-direction:column;gap:6px;margin-top:10px">
+        <button type="button" class="btn primary sm" onclick="applyConfiguration()">Apply configuration</button>
+        <button type="button" class="btn sm" onclick="connectBoard(true)">Connect · simulate</button>
+        <button type="button" class="btn sm" onclick="connectBoard(false)">Connect · hardware</button>
+        <button type="button" class="btn sm" onclick="disconnectBoard()">Disconnect board</button>
+        <button type="button" class="btn ghost sm" onclick="resetSession()">Reset session</button>
+      </div>
+    </div>
+
+    <div class="sidebar-section">
+      <div class="sidebar-label">Phases</div>
+      <div class="phase-item done" onclick="showTab('acq')">
+        <div class="phase-num">1</div>
+        <div class="phase-text">Acquisition + self-rating</div>
+      </div>
+      <div class="phase-item done" onclick="showTab('acq')">
+        <div class="phase-num">2</div>
+        <div class="phase-text">Filtering · stable state</div>
+      </div>
+      <div class="phase-item active" onclick="showTab('nf')">
+        <div class="phase-num">3</div>
+        <div class="phase-text">Real-time neurofeedback</div>
+      </div>
+      <div class="phase-item" onclick="showTab('lib')">
+        <div class="phase-num">4</div>
+        <div class="phase-text">Multi-class object library</div>
+      </div>
+      <div class="phase-item" onclick="showTab('lib')">
+        <div class="phase-num">5</div>
+        <div class="phase-text">Cross-subject generalization</div>
+      </div>
+    </div>
+
+    <div class="sidebar-section">
+      <div class="sidebar-label">Current session</div>
+      <div class="class-pair">
+        <div class="class-tag a">
+          <span class="class-name" id="ui-class-a-name">Chair</span>
+          <span class="class-trials" id="ui-class-a-n">0 trials</span>
+        </div>
+        <div class="class-tag b">
+          <span class="class-name" id="ui-class-b-name">Spiral</span>
+          <span class="class-trials" id="ui-class-b-n">0 trials</span>
+        </div>
+      </div>
+    </div>
+
+    <div class="sidebar-section">
+      <div class="sidebar-label">Metrics</div>
+      <div class="metric-mini">
+        <span class="metric-mini-label">Convergence (mean)</span>
+        <span class="metric-mini-value" id="metric-conv">—</span>
+      </div>
+      <div class="metric-mini">
+        <span class="metric-mini-label">Trials kept</span>
+        <span class="metric-mini-value" id="metric-kept">—</span>
+      </div>
+      <div class="metric-mini">
+        <span class="metric-mini-label">Mean score</span>
+        <span class="metric-mini-value" id="metric-mean">—</span>
+      </div>
+      <div class="metric-mini">
+        <span class="metric-mini-label">Classifier</span>
+        <span class="metric-mini-value" id="metric-lda">—</span>
+      </div>
+    </div>
+
+    <div class="sidebar-section" style="flex:1; overflow-y:auto;">
+      <div class="sidebar-label">Neural states</div>
+      <div id="sidebar-library-list"></div>
+    </div>
+
+  </div><!-- /sidebar -->
+
+  <!-- MAIN -->
+  <div class="main">
+
+    <!-- TABBAR -->
+    <div class="tabbar">
+      <div class="tab active" id="tab-acq" onclick="showTab('acq')">Acquisition</div>
+      <div class="tab" id="tab-nf" onclick="showTab('nf')">Neurofeedback</div>
+      <div class="tab" id="tab-model" onclick="showTab('model')">Model</div>
+      <div class="tab" id="tab-lib" onclick="showTab('lib')">Library</div>
+    </div>
+
+    <!-- ======== PANEL: ACQUISITION ======== -->
+    <div class="panel active" id="panel-acq">
+      <div class="acq-layout">
+
+        <!-- Current trial -->
+        <div class="card">
+          <div class="card-header">
+            <span class="card-title">Current trial</span>
+            <span class="card-badge" id="badge-trial-id">—</span>
+          </div>
+          <div class="card-body">
+            <div style="display:flex;gap:8px;flex-wrap:wrap;margin-bottom:12px">
+              <button type="button" class="btn sm primary" onclick="startTrialClass('a')">Start · Class A</button>
+              <button type="button" class="btn sm primary" onclick="startTrialClass('b')">Start · Class B</button>
+            </div>
+            <div class="current-trial-info">
+              <div class="trial-class-label" id="trial-class-heading">—</div>
+              <div class="trial-object" id="trial-object-name">—</div>
+              <div class="trial-timer" id="timer-display">No active trial — start Class A or B</div>
+            </div>
+            <div class="progress-wrap">
+              <div class="progress-bar" id="trial-progress" style="width:0%"></div>
+            </div>
+            <div class="section-title" style="margin-top:12px">Self-rating</div>
+            <div class="rating-row">
+              <div class="star-group" id="stars">
+                <div class="star" data-v="1" onclick="rateTrial(1)">1</div>
+                <div class="star" data-v="2" onclick="rateTrial(2)">2</div>
+                <div class="star" data-v="3" onclick="rateTrial(3)">3</div>
+                <div class="star" data-v="4" onclick="rateTrial(4)">4</div>
+                <div class="star sel" data-v="5" onclick="rateTrial(5)">5</div>
+              </div>
+              <span id="rate-label" style="font-size:11px;font-family:var(--mono);color:var(--txt3)">Excellent</span>
+            </div>
+            <div style="display:flex;gap:8px;margin-top:10px">
+              <button class="btn" onclick="sendPrompt('How can I improve EEG trial quality in a mental-imagery paradigm?')">↗ Help</button>
+              <button class="btn primary" onclick="confirmTrial()">Confirm trial →</button>
+            </div>
+          </div>
+        </div>
+
+        <!-- Topographie EEG -->
+        <div class="card">
+          <div class="card-header">
+            <span class="card-title">EEG topomap</span>
+            <span class="card-badge">Live</span>
+          </div>
+          <div class="card-body">
+            <div class="topo-container">
+              <canvas id="topoCanvas" width="160" height="160" style="border-radius:50%"></canvas>
+            </div>
+            <div style="display:grid;grid-template-columns:1fr 1fr;gap:6px;margin-top:10px">
+              <div class="info-row"><span class="info-key">Alpha</span><span class="info-val" id="live-alpha" style="color:#185FA5">—</span></div>
+              <div class="info-row"><span class="info-key">Beta</span><span class="info-val" id="live-beta" style="color:#0F6E56">—</span></div>
+              <div class="info-row"><span class="info-key">Theta</span><span class="info-val" id="live-theta">—</span></div>
+              <div class="info-row"><span class="info-key">Gamma</span><span class="info-val" id="live-gamma">—</span></div>
+            </div>
+          </div>
+        </div>
+
+        <!-- Trial history -->
+        <div class="card" style="grid-column:1/-1">
+          <div class="card-header">
+            <span class="card-title" id="history-card-title">History · Class A</span>
+            <span class="card-badge" id="history-card-badge">0 trials · 0 kept</span>
+          </div>
+          <div class="card-body">
+            <div id="trial-history"></div>
+          </div>
+        </div>
+
+      </div>
+      <div class="panel-footer">
+        <span style="font-size:11px;font-family:var(--mono);color:var(--txt3)">Phases 1–2 active · Auto filter score ≥ 4</span>
+        <div style="display:flex;gap:8px">
+          <button class="btn" onclick="showTab('nf')">→ Neurofeedback</button>
+        </div>
+      </div>
+    </div>
+
+    <!-- ======== PANEL: NEUROFEEDBACK ======== -->
+    <div class="panel" id="panel-nf">
+      <div class="nf-layout">
+
+        <!-- Convergence tracking -->
+        <div class="card nf-full">
+          <div class="card-header">
+            <span class="card-title">Convergence to stable state</span>
+            <span class="card-badge">Phase 3 · Active</span>
+          </div>
+          <div class="card-body">
+            <div style="margin-bottom:10px">
+              <div style="display:flex;justify-content:space-between;align-items:baseline;margin-bottom:6px">
+                <span class="section-title" id="nf-a-title">Class A</span>
+                <span id="nf-a-pct" style="font-size:11px;font-family:var(--mono);color:#185FA5">—</span>
+              </div>
+              <div class="convergence-track">
+                <div class="conv-fill" id="nf-a-fill" style="width:0%;background:linear-gradient(to right,#E6F1FB,#B5D4F4)"></div>
+                <div class="conv-pct" id="nf-a-pct-bar">0%</div>
+                <div class="conv-label">Target</div>
+              </div>
+            </div>
+            <div>
+              <div style="display:flex;justify-content:space-between;align-items:baseline;margin-bottom:6px">
+                <span class="section-title" id="nf-b-title">Class B</span>
+                <span id="nf-b-pct" style="font-size:11px;font-family:var(--mono);color:#0F6E56">—</span>
+              </div>
+              <div class="convergence-track">
+                <div class="conv-fill" id="nf-b-fill" style="width:0%;background:linear-gradient(to right,#E1F5EE,#9FE1CB)"></div>
+                <div class="conv-pct" id="nf-b-pct-bar">0%</div>
+                <div class="conv-label">Target</div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <!-- Signal waveform -->
+        <div class="card">
+          <div class="card-header">
+            <span class="card-title" id="wave-card-title">Raw signal · preview</span>
+            <span class="card-badge">250 Hz</span>
+          </div>
+          <div class="card-body" style="padding:8px">
+            <div class="waveform-wrap">
+              <canvas id="waveCanvas" width="300" height="80"></canvas>
+            </div>
+          </div>
+        </div>
+
+        <!-- Audio feedback -->
+        <div class="card">
+          <div class="card-header">
+            <span class="card-title">Audio feedback (NF)</span>
+          </div>
+          <div class="card-body">
+            <div class="audio-row">
+              <div class="audio-icon pos">
+                <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+                  <path d="M3 7h8M7 3l4 4-4 4" stroke="#0F6E56" stroke-width="1.2" stroke-linecap="round" stroke-linejoin="round"/>
+                </svg>
+              </div>
+              <div>
+                <div class="audio-text" id="nf-audio-target-title" style="color:#085041;font-weight:500">On target</div>
+                <div class="audio-freq" id="nf-audio-target-detail">—</div>
+              </div>
+            </div>
+            <div class="audio-row">
+              <div class="audio-icon neg">
+                <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+                  <path d="M11 7H3M7 3L3 7l4 4" stroke="#993C1D" stroke-width="1.2" stroke-linecap="round" stroke-linejoin="round"/>
+                </svg>
+              </div>
+              <div>
+                <div class="audio-text" id="nf-audio-neg-title" style="color:#712B13;font-weight:500">Divergence detected</div>
+                <div class="audio-freq" id="nf-audio-neg-detail">—</div>
+              </div>
+            </div>
+            <div class="audio-row">
+              <div class="audio-icon" style="background:#EEEDFE">
+                <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+                  <circle cx="7" cy="7" r="4" stroke="#534AB7" stroke-width="1.2"/>
+                  <circle cx="7" cy="7" r="1.5" fill="#534AB7"/>
+                </svg>
+              </div>
+              <div>
+                <div class="audio-text" id="nf-audio-neutral-title" style="color:#3C3489;font-weight:500">Neutral band</div>
+                <div class="audio-freq" id="nf-audio-neutral-detail">Last trial NF · —</div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <!-- Similarity score history -->
+        <div class="card nf-full">
+          <div class="card-header">
+            <span class="card-title">Distance to reference model · history</span>
+          </div>
+          <div class="card-body" style="padding:8px">
+            <canvas id="distCanvas" width="580" height="80"></canvas>
+          </div>
+        </div>
+
+      </div>
+      <div class="panel-footer">
+        <span style="font-size:11px;font-family:var(--mono);color:var(--txt3)">Metric: cosine distance · 8D CSP space</span>
+        <button class="btn primary" onclick="sendPrompt('Which algorithms do you recommend for EEG neurofeedback in mental imagery?')">↗ NF algorithm notes</button>
+      </div>
+    </div>
+
+    <!-- ======== PANEL: MODEL ======== -->
+    <div class="panel" id="panel-model">
+      <div style="padding:16px;display:flex;flex-direction:column;gap:12px;flex:1">
+
+        <div class="card">
+          <div class="card-header">
+            <span class="card-title">Feature extraction pipeline</span>
+          </div>
+          <div class="card-body">
+            <div style="display:flex;align-items:center;gap:0;overflow-x:auto;padding-bottom:4px">
+              <div style="text-align:center;min-width:90px">
+                <div style="width:60px;height:44px;border-radius:8px;background:var(--accent-light);border:0.5px solid #B5D4F4;display:flex;align-items:center;justify-content:center;margin:0 auto 5px;font-size:10px;font-family:var(--mono);color:#185FA5;text-align:center;padding:4px">EEG raw<br>16 ch</div>
+              </div>
+              <div style="flex:0 0 20px;text-align:center;color:var(--txt3);font-size:12px">→</div>
+              <div style="text-align:center;min-width:90px">
+                <div style="width:60px;height:44px;border-radius:8px;background:#E1F5EE;border:0.5px solid #9FE1CB;display:flex;align-items:center;justify-content:center;margin:0 auto 5px;font-size:10px;font-family:var(--mono);color:#085041;text-align:center;padding:4px">Filter<br>1–40 Hz</div>
+              </div>
+              <div style="flex:0 0 20px;text-align:center;color:var(--txt3);font-size:12px">→</div>
+              <div style="text-align:center;min-width:90px">
+                <div style="width:60px;height:44px;border-radius:8px;background:#EEEDFE;border:0.5px solid #CECBF6;display:flex;align-items:center;justify-content:center;margin:0 auto 5px;font-size:10px;font-family:var(--mono);color:#3C3489;text-align:center;padding:4px">CSP<br>8 comp.</div>
+              </div>
+              <div style="flex:0 0 20px;text-align:center;color:var(--txt3);font-size:12px">→</div>
+              <div style="text-align:center;min-width:90px">
+                <div style="width:60px;height:44px;border-radius:8px;background:#FAEEDA;border:0.5px solid #FAC775;display:flex;align-items:center;justify-content:center;margin:0 auto 5px;font-size:10px;font-family:var(--mono);color:#633806;text-align:center;padding:4px">Log-var<br>features</div>
+              </div>
+              <div style="flex:0 0 20px;text-align:center;color:var(--txt3);font-size:12px">→</div>
+              <div style="text-align:center;min-width:90px">
+                <div style="width:60px;height:44px;border-radius:8px;background:#FAECE7;border:0.5px solid #F5C4B3;display:flex;align-items:center;justify-content:center;margin:0 auto 5px;font-size:10px;font-family:var(--mono);color:#712B13;text-align:center;padding:4px">LDA<br>classifier</div>
+              </div>
+              <div style="flex:0 0 20px;text-align:center;color:var(--txt3);font-size:12px">→</div>
+              <div style="text-align:center;min-width:90px">
+                <div style="width:60px;height:44px;border-radius:8px;background:#EAF3DE;border:0.5px solid #C0DD97;display:flex;align-items:center;justify-content:center;margin:0 auto 5px;font-size:10px;font-family:var(--mono);color:#27500A;text-align:center;padding:4px">Stable<br>state</div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div style="display:grid;grid-template-columns:1fr 1fr;gap:12px">
+          <div class="card">
+            <div class="card-header"><span class="card-title">CSP parameters</span></div>
+            <div class="card-body">
+              <div class="info-row"><span class="info-key">n_components</span><span class="info-val">8</span></div>
+              <div class="info-row"><span class="info-key">reg</span><span class="info-val">0.05 (Ledoit-Wolf)</span></div>
+              <div class="info-row"><span class="info-key">log</span><span class="info-val">True</span></div>
+              <div class="info-row"><span class="info-key">norm_trace</span><span class="info-val">False</span></div>
+              <div class="info-row"><span class="info-key">epoch window</span><span class="info-val">2–8 s</span></div>
+            </div>
+          </div>
+          <div class="card">
+            <div class="card-header"><span class="card-title">Convergence criterion</span></div>
+            <div class="card-body">
+              <div class="info-row"><span class="info-key">Metric</span><span class="info-val">Cosine distance</span></div>
+              <div class="info-row"><span class="info-key">Convergence threshold</span><span class="info-val">d &lt; 0.12</span></div>
+              <div class="info-row"><span class="info-key">Rolling window</span><span class="info-val">5 trials</span></div>
+              <div class="info-row"><span class="info-key">Min. trials kept</span><span class="info-val">8</span></div>
+              <div class="info-row"><span class="info-key">Min. score</span><span class="info-val">≥ 4 / 5</span></div>
+            </div>
+          </div>
+        </div>
+
+        <button class="btn" style="align-self:flex-start" onclick="sendPrompt('Beyond CSP+LDA, which EEG mental-imagery classifiers work well with few channels?')">↗ Algorithm alternatives</button>
+
+      </div>
+    </div>
+
+    <!-- ======== PANEL: LIBRARY ======== -->
+    <div class="panel" id="panel-lib">
+      <div class="lib-layout">
+
+        <div class="section-title" id="lib-section-title">Library · session</div>
+        <div class="lib-grid">
+          <div class="lib-card" onclick="sendPrompt('How do you compare stable mental states for two imagined objects in a BCI?')">
+            <div class="lib-card-name">Apple</div>
+            <div class="lib-card-meta">Session 1 · 23 trials<br>11 kept · 3 NF sessions</div>
+            <div class="lib-card-bar"><div class="lib-card-fill" style="width:94%;background:#1D9E75"></div></div>
+          </div>
+          <div class="lib-card">
+            <div class="lib-card-name">Cube</div>
+            <div class="lib-card-meta">Session 1 · 20 trials<br>9 kept · 2 NF sessions</div>
+            <div class="lib-card-bar"><div class="lib-card-fill" style="width:88%;background:#185FA5"></div></div>
+          </div>
+          <div class="lib-card">
+            <div class="lib-card-name">Flame</div>
+            <div class="lib-card-meta">Session 2 · 25 trials<br>13 kept · 4 NF sessions</div>
+            <div class="lib-card-bar"><div class="lib-card-fill" style="width:91%;background:#534AB7"></div></div>
+          </div>
+          <div class="lib-card" style="border-color:#FAC775;background:#FAEEDA">
+            <div class="lib-card-name" style="color:#633806">Chair</div>
+            <div class="lib-card-meta" style="color:#854F0B">Session 3 · in progress<br>18 trials · NF active</div>
+            <div class="lib-card-bar"><div class="lib-card-fill" style="width:76%;background:#BA7517"></div></div>
+          </div>
+          <div class="lib-card" style="opacity:0.5;cursor:default">
+            <div class="lib-card-name">Spiral</div>
+            <div class="lib-card-meta">Session 3 · in progress<br>17 trials · phase 2</div>
+            <div class="lib-card-bar"><div class="lib-card-fill" style="width:31%;background:#888"></div></div>
+          </div>
+          <div class="lib-card" style="border-style:dashed;cursor:pointer;display:flex;align-items:center;justify-content:center;min-height:80px" onclick="sendPrompt('Which visual objects work best for a mental-imagery BCI paradigm?')">
+            <div style="text-align:center;color:var(--txt3)">
+              <div style="font-size:20px;margin-bottom:4px">+</div>
+              <div style="font-size:11px">New class</div>
+            </div>
+          </div>
+        </div>
+
+        <div class="section-title" style="margin-top:4px">Cross-subject generalization</div>
+        <div>
+          <div class="subject-row">
+            <div class="subject-avatar" style="background:#E6F1FB;color:#0C447C">S01</div>
+            <div class="subject-info">
+              <div class="subject-name">Subject 01</div>
+              <div class="subject-meta">4 classes · 86 trials · Ref</div>
+            </div>
+            <span class="subject-acc" style="color:#185FA5">91%</span>
+          </div>
+          <div class="subject-row">
+            <div class="subject-avatar" style="background:#E1F5EE;color:#085041">S02</div>
+            <div class="subject-info">
+              <div class="subject-name">Subject 02</div>
+              <div class="subject-meta">4 classes · 72 trials · Transfer</div>
+            </div>
+            <span class="subject-acc" style="color:#0F6E56">78%</span>
+          </div>
+          <div class="subject-row" style="opacity:0.5">
+            <div class="subject-avatar" style="background:#F1EFE8;color:#5F5E5A">S03</div>
+            <div class="subject-info">
+              <div class="subject-name">Subject 03</div>
+              <div class="subject-meta">In progress · session 1</div>
+            </div>
+            <span class="subject-acc" style="color:#888">—</span>
+          </div>
+        </div>
+
+        <button class="btn" style="align-self:flex-start" onclick="sendPrompt('How should I implement transfer learning for cross-subject EEG BCI generalization?')">↗ Cross-subject transfer learning</button>
+
+      </div>
+    </div>
+
+  </div><!-- /main -->
+
+</div><!-- /app -->
+
+<script>
+(function () {
+  'use strict';
+
+  const API = '';
+  const EPOCH_SEC = 4;
+
+  let channelInfo = null;
+  let lastLive = null;
+  let lastState = null;
+  let ws = null;
+  let wsConnected = false;
+  let restOk = false;
+  let selectedQuality = 5;
+  let nfHistory = [];
+  let lastTrialFeedback = null;
+  let lastNfScore = null;
+
+  function sendPrompt(text) {
+    console.info('[Help]', text);
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).catch(function () {});
+    }
+  }
+
+  async function api(path, opts) {
+    var r = await fetch(API + path, Object.assign({ headers: { 'Content-Type': 'application/json' } }, opts || {}));
+    var ct = r.headers.get('content-type') || '';
+    var j = {};
+    if (ct.indexOf('application/json') !== -1) {
+      try { j = await r.json(); } catch (e) { j = {}; }
+    }
+    if (!r.ok) {
+      var msg = (j.detail && (typeof j.detail === 'string' ? j.detail : JSON.stringify(j.detail))) || j.error || r.statusText;
+      throw new Error(msg);
+    }
+    if (j.error) throw new Error(j.error);
+    return j;
+  }
+
+  async function loadChannelInfo() {
+    try {
+      channelInfo = await api('/channels/info', { method: 'GET' });
+    } catch (e) {
+      console.warn('channels/info', e);
+    }
+  }
+
+  function wsUrl() {
+    var p = location.protocol === 'https:' ? 'wss:' : 'ws:';
+    return p + '//' + location.host + '/ws';
+  }
+
+  function connectWS() {
+    if (ws && ws.readyState === WebSocket.OPEN) return;
+    try {
+      ws = new WebSocket(wsUrl());
+    } catch (e) {
+      console.warn(e);
+      return;
+    }
+    ws.onopen = function () {
+      wsConnected = true;
+      updateBackendStatus();
+      try { ws.send(JSON.stringify({ type: 'ping' })); } catch (e) {}
+    };
+    ws.onmessage = function (ev) {
+      var d = JSON.parse(ev.data);
+      if (d.type === 'live_eeg') {
+        lastLive = d;
+        drawTopoFromLive();
+        drawWaveFromLive();
+        updateBandDisplays(d);
+      } else if (d.type === 'state' || d.type === 'state_update') {
+        var copy = Object.assign({}, d);
+        delete copy.type;
+        renderState(copy);
+      } else if (d.type === 'trial_ended') {
+        if (typeof d.nf_score === 'number') {
+          nfHistory.push(d.nf_score);
+          if (nfHistory.length > 80) nfHistory.shift();
+          lastNfScore = d.nf_score;
+          lastTrialFeedback = d.feedback || null;
+          updateAudioFeedbackUI();
+        }
+        refreshState();
+        drawDistCanvas();
+      } else if (d.type === 'pong') {
+        /* ignore */
+      }
+    };
+    ws.onclose = function () {
+      wsConnected = false;
+      updateBackendStatus();
+      setTimeout(connectWS, 2500);
+    };
+    ws.onerror = function () {};
+  }
+
+  function updateBackendStatus() {
+    var el = document.getElementById('backend-status');
+    if (!el) return;
+    var board = lastState && lastState.board_connected;
+    el.textContent =
+      'REST: ' + (restOk ? 'OK' : '…') +
+      ' · WS: ' + (wsConnected ? 'live' : '…') +
+      ' · Board: ' + (board ? 'on' : 'off');
+  }
+
+  async function refreshState() {
+    try {
+      var st = await api('/state', { method: 'GET' });
+      restOk = true;
+      renderState(st);
+    } catch (e) {
+      restOk = false;
+      console.warn('/state', e);
+    }
+    updateBackendStatus();
+  }
+
+  function findActiveTrial(st) {
+    var all = (st.class_a_trials || []).concat(st.class_b_trials || []);
+    var pending = all.filter(function (t) { return t.quality_score == null; });
+    if (!pending.length) return null;
+    return pending.reduce(function (a, b) { return a.trial_id > b.trial_id ? a : b; });
+  }
+
+  function meanBand(arr) {
+    if (!arr || !arr.length) return 0;
+    var s = 0;
+    for (var i = 0; i < arr.length; i++) s += arr[i];
+    return s / arr.length;
+  }
+
+  function fmtUvSq(v) {
+    if (!isFinite(v) || v === 0) return '—';
+    return v.toExponential(2) + ' (arb.)';
+  }
+
+  function renderState(st) {
+    lastState = st;
+    var cfg = st.config || {};
+    var phase = st.phase || 'IDLE';
+    var dotPhase = document.getElementById('dot-phase');
+    if (dotPhase) {
+      dotPhase.className = 'dot' + (phase !== 'IDLE' ? ' active' : '');
+    }
+    var txtPhase = document.getElementById('txt-phase');
+    if (txtPhase) txtPhase.textContent = phase;
+
+    var sid = cfg.subject_id || '—';
+    var sess = (cfg.session_id || '').split('_').pop() || '—';
+    var txtSession = document.getElementById('txt-session');
+    if (txtSession) txtSession.textContent = sid + ' · ' + sess;
+
+    var dotBoard = document.getElementById('dot-board');
+    if (dotBoard) dotBoard.className = 'dot' + (st.board_connected ? ' active' : '');
+
+    var dotSession = document.getElementById('dot-session');
+    if (dotSession) dotSession.className = 'dot' + (st.total_trials > 0 ? ' warn' : '');
+
+    document.getElementById('ui-class-a-name').textContent = cfg.class_a || 'A';
+    document.getElementById('ui-class-b-name').textContent = cfg.class_b || 'B';
+    var aTrials = st.class_a_trials || [];
+    var bTrials = st.class_b_trials || [];
+    document.getElementById('ui-class-a-n').textContent = aTrials.length + ' trials';
+    document.getElementById('ui-class-b-n').textContent = bTrials.length + ' trials';
+
+    var ns = st.neural_states || {};
+    var keys = Object.keys(ns);
+    var convSum = 0;
+    var convN = 0;
+    keys.forEach(function (k) {
+      convSum += ns[k].convergence_score || 0;
+      convN++;
+    });
+    document.getElementById('metric-conv').textContent =
+      convN ? Math.round((convSum / convN) * 100) + '%' : '—';
+
+    var minQ = cfg.min_quality_for_model != null ? cfg.min_quality_for_model : 4;
+    var allRated = aTrials.concat(bTrials).filter(function (t) { return t.quality_score != null; });
+    var kept = allRated.filter(function (t) { return t.quality_score >= minQ; }).length;
+    document.getElementById('metric-kept').textContent = kept + ' / ' + allRated.length;
+
+    var scN = 0;
+    var totalSc = 0;
+    allRated.forEach(function (t) {
+      totalSc += t.quality_score;
+      scN++;
+    });
+    document.getElementById('metric-mean').textContent =
+      scN ? (totalSc / scN).toFixed(1) + ' / 5' : '—';
+
+    document.getElementById('metric-lda').textContent = st.classifier_trained ? 'trained' : 'not trained';
+
+    var libList = document.getElementById('sidebar-library-list');
+    if (libList) {
+      libList.innerHTML = '';
+      keys.forEach(function (label) {
+        var info = ns[label];
+        var row = document.createElement('div');
+        row.className = 'lib-entry';
+        row.innerHTML =
+          '<span class="lib-dot" style="background:#185FA5"></span>' +
+          '<span class="lib-text">' +
+          label +
+          '</span>' +
+          '<span class="lib-score">' +
+          Math.round((info.convergence_score || 0) * 100) +
+          '% · n=' +
+          info.n_trials +
+          '</span>';
+        libList.appendChild(row);
+      });
+      if (!keys.length) {
+        libList.innerHTML = '<div class="muted" style="font-size:11px;padding:4px">No stable states yet</div>';
+      }
+    }
+
+    var ca = cfg.class_a || 'Class A';
+    var cb = cfg.class_b || 'Class B';
+    var pctA = ns[ca] ? Math.round((ns[ca].convergence_score || 0) * 100) : 0;
+    var pctB = ns[cb] ? Math.round((ns[cb].convergence_score || 0) * 100) : 0;
+
+    var nfAT = document.getElementById('nf-a-title');
+    var nfBT = document.getElementById('nf-b-title');
+    if (nfAT) nfAT.textContent = ca + ' (Class A)';
+    if (nfBT) nfBT.textContent = cb + ' (Class B)';
+
+    var elAp = document.getElementById('nf-a-pct');
+    var elBp = document.getElementById('nf-b-pct');
+    if (elAp) elAp.textContent = ns[ca] ? pctA + '% converged' : '—';
+    if (elBp) elBp.textContent = ns[cb] ? pctB + '% converged' : '—';
+
+    var fillA = document.getElementById('nf-a-fill');
+    var fillB = document.getElementById('nf-b-fill');
+    var barA = document.getElementById('nf-a-pct-bar');
+    var barB = document.getElementById('nf-b-pct-bar');
+    if (fillA) fillA.style.width = pctA + '%';
+    if (fillB) fillB.style.width = pctB + '%';
+    if (barA) barA.textContent = pctA + '%';
+    if (barB) barB.textContent = pctB + '%';
+
+    var active = findActiveTrial(st);
+    var badge = document.getElementById('badge-trial-id');
+    var obj = document.getElementById('trial-object-name');
+    var head = document.getElementById('trial-class-heading');
+    if (badge) badge.textContent = active ? 'Trial ' + active.trial_id : '—';
+    if (obj) obj.textContent = active ? active.class_label : '—';
+    if (head) {
+      if (!active) head.textContent = '—';
+      else if (active.class_label === ca) head.textContent = 'CLASS A · Imagine';
+      else if (active.class_label === cb) head.textContent = 'CLASS B · Imagine';
+      else head.textContent = active.class_label;
+    }
+
+    var ht = document.getElementById('history-card-title');
+    var hb = document.getElementById('history-card-badge');
+    if (ht) ht.textContent = 'History · Class A (' + ca + ')';
+    var ratedA = aTrials.filter(function (t) { return t.quality_score != null; });
+    var keptA = ratedA.filter(function (t) { return t.quality_score >= minQ; }).length;
+    if (hb) hb.textContent = ratedA.length + ' trials · ' + keptA + ' kept';
+
+    renderHistoryClassA(st, minQ, ca);
+
+    var libTitle = document.getElementById('lib-section-title');
+    if (libTitle) libTitle.textContent = 'Library · ' + sid;
+
+    updateBackendStatus();
+    updateTrialTimer(st);
+    updateAudioFeedbackUI();
+  }
+
+  function updateAudioFeedbackUI() {
+    var fb = lastTrialFeedback;
+    var t1 = document.getElementById('nf-audio-target-detail');
+    var t2 = document.getElementById('nf-audio-neg-detail');
+    var t3 = document.getElementById('nf-audio-neutral-detail');
+    if (fb && t1) {
+      t1.textContent = fb.freq_hz + ' Hz · vol ' + fb.volume + ' · ' + fb.tone;
+    } else if (t1) t1.textContent = '—';
+    if (t2) t2.textContent = lastNfScore != null && lastNfScore < 0.35 ? 'Low NF score' : '—';
+    if (t3) {
+      t3.textContent =
+        'Last trial NF · ' + (lastNfScore != null ? lastNfScore.toFixed(3) : '—');
+    }
+  }
+
+  function updateTrialTimer(st) {
+    var active = findActiveTrial(st);
+    var el = document.getElementById('timer-display');
+    var prog = document.getElementById('trial-progress');
+    if (!active) {
+      if (el) el.textContent = 'No active trial — start Class A or B';
+      if (prog) prog.style.width = '0%';
+      return;
+    }
+    var onsetMs = active.onset_time * 1000;
+    var elapsed = (Date.now() - onsetMs) / 1000;
+    var left = Math.max(0, EPOCH_SEC - elapsed);
+    if (el) {
+      el.textContent =
+        left.toFixed(1) +
+        ' s left · Trial #' +
+        active.trial_id +
+        ' · ' +
+        active.class_label;
+    }
+    if (prog) prog.style.width = Math.min(100, (elapsed / EPOCH_SEC) * 100) + '%';
+  }
+
+  function renderHistoryClassA(st, minQ, classAName) {
+    var h = document.getElementById('trial-history');
+    if (!h) return;
+    h.innerHTML = '';
+    var trials = (st.class_a_trials || []).filter(function (t) {
+      return t.quality_score != null;
+    });
+    var colors = ['', '#E24B4A', '#EF9F27', '#888', '#1D9E75', '#185FA5'];
+    trials.forEach(function (t, i) {
+      var r = t.quality_score;
+      var keep = r >= minQ;
+      var barW = (r / 5) * 100;
+      var row = document.createElement('div');
+      row.className = 'trial-row';
+      row.innerHTML =
+        '<div class="trial-num">' +
+        t.trial_id +
+        '</div>' +
+        '<div class="trial-bar-wrap"><div class="trial-bar" style="width:' +
+        barW +
+        '%;background:' +
+        colors[r] +
+        '"></div></div>' +
+        '<div class="trial-score" style="color:' +
+        colors[r] +
+        '">' +
+        r +
+        '</div>' +
+        '<div class="trial-badge ' +
+        (keep ? 'keep' : 'drop') +
+        '">' +
+        (keep ? '✓ keep' : '✗ drop') +
+        '</div>';
+      h.appendChild(row);
+    });
+    if (!trials.length) {
+      h.innerHTML =
+        '<div class="muted" style="font-size:11px;padding:8px">No Class A trials rated yet (' +
+        classAName +
+        ').</div>';
+    }
+  }
+
+  function channelPositionsForTopo() {
+    if (!channelInfo || !channelInfo.channel_names) return null;
+    var pos = channelInfo.positions || {};
+    var list = [];
+    channelInfo.channel_names.forEach(function (name) {
+      var xy = pos[name];
+      if (!xy) return;
+      var px = Array.isArray(xy) ? xy[0] : xy.x;
+      var py = Array.isArray(xy) ? xy[1] : xy.y;
+      list.push({ name: name, x: 80 + px * 100, y: 80 - py * 100 });
+    });
+    return list.length ? list : null;
+  }
+
+  function drawTopoFromLive() {
+    var c = document.getElementById('topoCanvas');
+    if (!c) return;
+    var ctx = c.getContext('2d');
+    var W = 160;
+    var H = 160;
+    var cx = 80;
+    var cy = 80;
+    var R = 72;
+
+    var topo = lastLive && lastLive.topomap;
+    var base = channelPositionsForTopo();
+    var channels;
+    if (base && topo) {
+      var vals = base.map(function (ch) {
+        return topo[ch.name] != null ? topo[ch.name] : 0;
+      });
+      var vmin = Math.min.apply(null, vals);
+      var vmax = Math.max.apply(null, vals);
+      var span = vmax - vmin || 1;
+      channels = base.map(function (ch, i) {
+        return {
+          x: ch.x,
+          y: ch.y,
+          v: (vals[i] - vmin) / span,
+        };
+      });
+    } else {
+      channels = [
+        { x: 80, y: 20, v: 0.35 },
+        { x: 120, y: 35, v: 0.5 },
+        { x: 140, y: 70, v: 0.55 },
+        { x: 140, y: 110, v: 0.6 },
+        { x: 120, y: 135, v: 0.5 },
+        { x: 80, y: 148, v: 0.45 },
+        { x: 40, y: 135, v: 0.5 },
+        { x: 20, y: 110, v: 0.55 },
+        { x: 20, y: 70, v: 0.58 },
+        { x: 40, y: 35, v: 0.4 },
+        { x: 80, y: 60, v: 0.3 },
+        { x: 110, y: 75, v: 0.48 },
+        { x: 110, y: 105, v: 0.52 },
+        { x: 80, y: 118, v: 0.5 },
+        { x: 50, y: 105, v: 0.53 },
+        { x: 50, y: 75, v: 0.47 },
+      ];
+    }
+
+    var imgData = ctx.createImageData(W, H);
+    for (var px = 0; px < W; px++) {
+      for (var py = 0; py < H; py++) {
+        var dx = px - cx;
+        var dy = py - cy;
+        if (dx * dx + dy * dy > R * R) continue;
+        var wSum = 0;
+        var vSum = 0;
+        channels.forEach(function (ch) {
+          var d2 = (px - ch.x) * (px - ch.x) + (py - ch.y) * (py - ch.y) + 0.001;
+          var w = 1 / d2;
+          wSum += w;
+          vSum += w * ch.v;
+        });
+        var v = vSum / wSum;
+        var r;
+        var g;
+        var b;
+        if (v < 0.5) {
+          var t = v * 2;
+          r = Math.round(t * 100);
+          g = Math.round(t * 150);
+          b = Math.round(180 + t * 50);
+        } else {
+          var t2 = (v - 0.5) * 2;
+          r = Math.round(100 + t2 * 155);
+          g = Math.round(150 - t2 * 100);
+          b = Math.round(230 - t2 * 210);
+        }
+        var idx = (py * W + px) * 4;
+        imgData.data[idx] = r;
+        imgData.data[idx + 1] = g;
+        imgData.data[idx + 2] = b;
+        imgData.data[idx + 3] = 200;
+      }
+    }
+    ctx.clearRect(0, 0, W, H);
+    ctx.save();
+    ctx.beginPath();
+    ctx.arc(cx, cy, R, 0, Math.PI * 2);
+    ctx.clip();
+    ctx.putImageData(imgData, 0, 0);
+    ctx.restore();
+    ctx.beginPath();
+    ctx.arc(cx, cy, R, 0, Math.PI * 2);
+    ctx.strokeStyle = 'rgba(128,128,128,0.3)';
+    ctx.lineWidth = 0.5;
+    ctx.stroke();
+    ctx.beginPath();
+    ctx.arc(4, 80, 4, 0, Math.PI * 2);
+    ctx.fillStyle = 'rgba(128,128,128,0.3)';
+    ctx.fill();
+    ctx.beginPath();
+    ctx.arc(156, 80, 4, 0, Math.PI * 2);
+    ctx.fill();
+    channels.forEach(function (ch) {
+      ctx.beginPath();
+      ctx.arc(ch.x, ch.y, 3, 0, Math.PI * 2);
+      ctx.fillStyle = 'rgba(255,255,255,0.7)';
+      ctx.fill();
+      ctx.strokeStyle = 'rgba(0,0,0,0.3)';
+      ctx.lineWidth = 0.5;
+      ctx.stroke();
+    });
+  }
+
+  function drawWaveFromLive() {
+    var c = document.getElementById('waveCanvas');
+    if (!c) return;
+    var parent = c.parentElement;
+    var rect = parent ? parent.getBoundingClientRect() : { width: 300 };
+    var dpr = window.devicePixelRatio || 1;
+    var W = Math.floor(rect.width * dpr) || 300;
+    var H = Math.floor(80 * dpr);
+    if (c.width !== W) c.width = W;
+    if (c.height !== H) c.height = H;
+    c.style.width = W / dpr + 'px';
+    c.style.height = H / dpr + 'px';
+
+    var ctx = c.getContext('2d');
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.clearRect(0, 0, W, H);
+    ctx.scale(dpr, dpr);
+    var drawW = W / dpr;
+    var drawH = H / dpr;
+
+    var raw = lastLive && lastLive.raw_samples;
+    if (!raw || !raw.length) {
+      ctx.strokeStyle = 'rgba(24,95,165,0.25)';
+      ctx.beginPath();
+      ctx.moveTo(0, drawH / 2);
+      ctx.lineTo(drawW, drawH / 2);
+      ctx.stroke();
+      return;
+    }
+
+    var colors = ['#185FA5', '#0F6E56', '#3C3489', '#BA7517'];
+    for (var ch = 0; ch < raw.length; ch++) {
+      var samp = raw[ch];
+      if (!samp || !samp.length) continue;
+      ctx.beginPath();
+      var minV = samp[0];
+      var maxV = samp[0];
+      for (var i = 1; i < samp.length; i++) {
+        if (samp[i] < minV) minV = samp[i];
+        if (samp[i] > maxV) maxV = samp[i];
+      }
+      var span = maxV - minV || 1;
+      for (var x = 0; x < samp.length; x++) {
+        var nx = (x / (samp.length - 1)) * drawW;
+        var ny = drawH * 0.15 + (1 - (samp[x] - minV) / span) * (drawH * 0.7) + ch * 4;
+        if (x === 0) ctx.moveTo(nx, ny);
+        else ctx.lineTo(nx, ny);
+      }
+      ctx.strokeStyle = colors[ch % colors.length];
+      ctx.lineWidth = 1;
+      ctx.stroke();
+    }
+  }
+
+  function updateBandDisplays(d) {
+    if (!d) return;
+    var a = document.getElementById('live-alpha');
+    var b = document.getElementById('live-beta');
+    var t = document.getElementById('live-theta');
+    var g = document.getElementById('live-gamma');
+    if (a) a.textContent = d.alpha_power ? fmtUvSq(meanBand(d.alpha_power)) : '—';
+    if (b) b.textContent = d.beta_power ? fmtUvSq(meanBand(d.beta_power)) : '—';
+    if (t) t.textContent = d.theta_power ? fmtUvSq(meanBand(d.theta_power)) : '—';
+    if (g) g.textContent = d.gamma_power ? fmtUvSq(meanBand(d.gamma_power)) : '—';
+
+    var names = d.channels || (channelInfo && channelInfo.channel_names);
+    var wtitle = document.getElementById('wave-card-title');
+    if (wtitle && names && names.length >= 4) {
+      wtitle.textContent =
+        'Raw signal · ' + names[0] + ' · ' + names[4] + ' · ' + names[8] + ' · ' + names[12];
+    }
+  }
+
+  function drawDistCanvas() {
+    var c = document.getElementById('distCanvas');
+    if (!c) return;
+    var ctx = c.getContext('2d');
+    var rect = c.parentElement ? c.parentElement.getBoundingClientRect() : { width: 580 };
+    var W = Math.floor(rect.width) || 580;
+    var H = 80;
+    if (c.width !== W) c.width = W;
+    c.height = H;
+
+    var data = nfHistory.slice();
+    ctx.clearRect(0, 0, W, H);
+    var pad = 20;
+    var maxD = 1;
+    ctx.beginPath();
+    ctx.setLineDash([3, 3]);
+    var ty = H - pad - (0.35 / maxD) * (H - 2 * pad);
+    ctx.moveTo(pad, ty);
+    ctx.lineTo(W - pad, ty);
+    ctx.strokeStyle = 'rgba(128,128,128,0.4)';
+    ctx.lineWidth = 0.5;
+    ctx.stroke();
+    ctx.setLineDash([]);
+    if (data.length < 2) {
+      ctx.font = '11px monospace';
+      ctx.fillStyle = 'rgba(128,128,128,0.7)';
+      ctx.fillText('NF scores appear after rated trials', pad, H / 2);
+      return;
+    }
+    ctx.beginPath();
+    data.forEach(function (d, i) {
+      var x = pad + (i * (W - 2 * pad)) / (data.length - 1);
+      var y = H - pad - (d / maxD) * (H - 2 * pad);
+      if (i === 0) ctx.moveTo(x, y);
+      else ctx.lineTo(x, y);
+    });
+    ctx.strokeStyle = '#185FA5';
+    ctx.lineWidth = 1.2;
+    ctx.stroke();
+    data.forEach(function (d, i) {
+      var x = pad + (i * (W - 2 * pad)) / (data.length - 1);
+      var y = H - pad - (d / maxD) * (H - 2 * pad);
+      ctx.beginPath();
+      ctx.arc(x, y, 3, 0, Math.PI * 2);
+      ctx.fillStyle = d >= 0.65 ? '#1D9E75' : '#185FA5';
+      ctx.fill();
+    });
+    ctx.font = '10px monospace';
+    ctx.fillStyle = 'rgba(128,128,128,0.7)';
+    ctx.fillText('NF similarity (higher is better)', pad, 12);
+  }
+
+  window.showTab = function (t) {
+    document.querySelectorAll('.tab').forEach(function (x) {
+      x.classList.remove('active');
+    });
+    document.querySelectorAll('.panel').forEach(function (x) {
+      x.classList.remove('active');
+    });
+    document.getElementById('tab-' + t).classList.add('active');
+    document.getElementById('panel-' + t).classList.add('active');
+    if (t === 'nf') drawDistCanvas();
+    if (t === 'acq') drawTopoFromLive();
+    if (t === 'nf') drawWaveFromLive();
+  };
+
+  window.rateTrial = function (v) {
+    selectedQuality = v;
+    document.querySelectorAll('.star').forEach(function (s) {
+      s.classList.toggle('sel', parseInt(s.dataset.v, 10) === v);
+    });
+    var labels = ['', 'Poor', 'Fair', 'Average', 'Good', 'Excellent'];
+    document.getElementById('rate-label').textContent = labels[v];
+  };
+
+  window.applyConfiguration = async function () {
+    var subject_id = document.getElementById('cfg-subject').value.trim();
+    var class_a = document.getElementById('cfg-class-a').value.trim();
+    var class_b = document.getElementById('cfg-class-b').value.trim();
+    var min_quality = parseInt(document.getElementById('cfg-min-q').value, 10) || 4;
+    var q =
+      '/session/configure?subject_id=' +
+      encodeURIComponent(subject_id) +
+      '&class_a=' +
+      encodeURIComponent(class_a) +
+      '&class_b=' +
+      encodeURIComponent(class_b) +
+      '&min_quality=' +
+      min_quality;
+    await api(q, { method: 'POST' });
+    await refreshState();
+  };
+
+  window.connectBoard = async function (simulate) {
+    var port =
+      document.getElementById('cfg-port').value.trim() || '/dev/ttyUSB0';
+    var q =
+      '/board/connect?port=' +
+      encodeURIComponent(port) +
+      '&simulate=' +
+      (!!simulate);
+    await api(q, { method: 'POST' });
+    connectWS();
+    await refreshState();
+  };
+
+  window.disconnectBoard = async function () {
+    await api('/board/disconnect', { method: 'POST' });
+    await refreshState();
+  };
+
+  window.resetSession = async function () {
+    await api('/session/reset', { method: 'POST' });
+    nfHistory = [];
+    lastNfScore = null;
+    lastTrialFeedback = null;
+    await refreshState();
+    drawDistCanvas();
+  };
+
+  window.startTrialClass = async function (ab) {
+    var ca = document.getElementById('cfg-class-a').value.trim();
+    var cb = document.getElementById('cfg-class-b').value.trim();
+    var label = ab === 'a' ? ca : cb;
+    if (!label) return;
+    await api('/trial/start?class_label=' + encodeURIComponent(label), { method: 'POST' });
+    await refreshState();
+  };
+
+  window.confirmTrial = async function () {
+    try {
+      var res = await api('/trial/end?quality=' + selectedQuality, { method: 'POST' });
+      if (typeof res.nf_score === 'number') {
+        nfHistory.push(res.nf_score);
+        if (nfHistory.length > 80) nfHistory.shift();
+        lastNfScore = res.nf_score;
+        lastTrialFeedback = res.feedback || null;
+        updateAudioFeedbackUI();
+      }
+      await refreshState();
+      drawDistCanvas();
+    } catch (e) {
+      alert(e.message || String(e));
+    }
+  };
+
+  function tickLoop() {
+    if (lastState) updateTrialTimer(lastState);
+  }
+
+  window.addEventListener('load', async function () {
+    await loadChannelInfo();
+    try {
+      await api('/health', { method: 'GET' });
+      restOk = true;
+    } catch (e) {
+      restOk = false;
+    }
+    connectWS();
+    await refreshState();
+    setInterval(refreshState, 4000);
+    setInterval(tickLoop, 100);
+    setInterval(function () {
+      if (lastLive && document.getElementById('panel-acq').classList.contains('active')) {
+        drawTopoFromLive();
+      }
+    }, 200);
+    drawTopoFromLive();
+    drawDistCanvas();
+  });
+
+  window.addEventListener('resize', function () {
+    drawWaveFromLive();
+    drawDistCanvas();
+  });
+})();
+</script>
+
+</body>
+</html>