Fix hybird bug, center timeline, glasses warning in intro pop-up, eye gaze warning pop-up, help page update.

src/App.css

@@ -337,6 +337,34 @@ body {
     line-height: 1.6;
 }
 
+.focus-flow-glasses-note {
+    background: #fffbea;
+    border: 1px solid #f5c518;
+    border-radius: 10px;
+    padding: 12px 16px;
+    font-size: 0.9rem;
+    color: #5a4a00;
+    line-height: 1.55;
+    margin-top: 4px;
+    margin-bottom: 4px;
+}
+
+.focus-flow-panel-warn {
+    border-left: 3px solid #f5a623;
+    background: #fff9f0;
+}
+
+.eye-gaze-modal-checkbox {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    margin-top: 16px;
+    font-size: 0.9rem;
+    color: #667281;
+    cursor: pointer;
+    user-select: none;
+}
+
 .focus-flow-button,
 .focus-flow-secondary {
     border: none;
@@ -748,6 +776,17 @@ body {
     display: flex;
     flex-direction: column;
     justify-content: flex-end;
+    align-self: center;
+    margin: 0 auto;
+}
+
+#timeline-visuals {
+    display: flex;
+    justify-content: center;
+    flex-wrap: wrap;
+    align-items: flex-end;
+    gap: 2px;
+    width: 100%;
 }
 
 .timeline-label {

src/components/FocusPageLocal.jsx

@@ -109,6 +109,10 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
   const [calibration, setCalibration] = useState(null);
   const [l2csBoost, setL2csBoost] = useState(false);
   const [l2csBoostAvailable, setL2csBoostAvailable] = useState(false);
+  const [showEyeGazeModal, setShowEyeGazeModal] = useState(false);
+  const [eyeGazeDontShow, setEyeGazeDontShow] = useState(
+    () => localStorage.getItem('focusguard_eyegaze_noshowalert') === 'true'
+  );
 
   const localVideoRef = useRef(null);
   const displayCanvasRef = useRef(null);
@@ -305,22 +309,19 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
     }
   };
 
-  const handleEyeGazeToggle = async () => {
-    const next = !l2csBoost;
+  const applyEyeGazeChange = async (enable, withCalibration = true) => {
     try {
       const res = await fetch('/api/settings', {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ l2cs_boost: next })
+        body: JSON.stringify({ l2cs_boost: enable })
       });
       if (!res.ok) return;
-      setL2csBoost(next);
+      setL2csBoost(enable);
 
-      if (next && videoManager && videoManager.isStreaming) {
-        // Turning ON → auto-start calibration
+      if (enable && withCalibration && videoManager && videoManager.isStreaming) {
         videoManager.startCalibration();
-      } else if (!next && videoManager) {
-        // Turning OFF → cancel any active calibration
+      } else if (!enable && videoManager) {
         videoManager.cancelCalibration();
       }
     } catch (err) {
@@ -328,6 +329,24 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
     }
   };
 
+  const handleEyeGazeToggle = async () => {
+    const next = !l2csBoost;
+    if (next && !eyeGazeDontShow) {
+      // Show the warning/calibration modal before enabling
+      setShowEyeGazeModal(true);
+      return;
+    }
+    await applyEyeGazeChange(next, true);
+  };
+
+  const handleEyeGazeModalAction = async (withCalibration) => {
+    if (eyeGazeDontShow) {
+      localStorage.setItem('focusguard_eyegaze_noshowalert', 'true');
+    }
+    setShowEyeGazeModal(false);
+    await applyEyeGazeChange(true, withCalibration);
+  };
+
   const handleStart = async () => {
     try {
       setIsStarting(true);
@@ -611,6 +630,10 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
               ))}
             </div>
 
+            <div className="focus-flow-glasses-note">
+              <strong>Wearing glasses?</strong> Glasses may reduce detection accuracy on some models. If results seem inaccurate, try switching to a different model (e.g. Geometric or MLP).
+            </div>
+
             <div className="focus-flow-footer">
               <div className="focus-flow-note">
                 You can still change frame rate and available model options after the preview loads.
@@ -677,9 +700,91 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
     return null;
   };
 
+  const renderEyeGazeModal = () => {
+    if (!showEyeGazeModal) return null;
+    return (
+      <div className="focus-flow-overlay" style={{ zIndex: 2000 }}>
+        <div className="focus-flow-card">
+          <div className="focus-flow-header">
+            <div>
+              <div className="focus-flow-eyebrow">Eye Gaze Tracking</div>
+              <h2>Before you enable</h2>
+            </div>
+            <div className="focus-flow-icon">
+              <svg width="96" height="96" viewBox="0 0 96 96" aria-hidden="true">
+                <ellipse cx="48" cy="48" rx="38" ry="24" fill="none" stroke="#007BFF" strokeWidth="5" />
+                <circle cx="48" cy="48" r="13" fill="none" stroke="#007BFF" strokeWidth="5" />
+                <circle cx="48" cy="48" r="5" fill="#007BFF" />
+              </svg>
+            </div>
+          </div>
+
+          <p className="focus-flow-lead">
+            Eye gaze tracking runs an additional deep neural network (L2CS-Net) alongside your current model.
+            Please read the notes below before proceeding.
+          </p>
+
+          <div className="focus-flow-grid">
+            <article className="focus-flow-panel focus-flow-panel-warn">
+              <h3>Performance impact</h3>
+              <p>Enabling eye gaze tracking increases CPU usage and may reduce frame rate. If the system feels sluggish, consider disabling it.</p>
+            </article>
+            <article className="focus-flow-panel">
+              <h3>Calibration (recommended)</h3>
+              <p>For best accuracy, calibrate by looking at 9 screen positions one at a time, followed by 1 validation point. The whole process takes about 30 seconds.</p>
+            </article>
+          </div>
+
+          <div className="focus-flow-steps">
+            <div className="focus-flow-step">
+              <div className="focus-flow-step-number">1</div>
+              <div className="focus-flow-step-copy">
+                <h3>Click "Start Calibration"</h3>
+                <p>A dot will appear on screen. Look directly at it and keep your gaze steady. It will cycle through 9 positions then show a final validation dot.</p>
+              </div>
+            </div>
+            <div className="focus-flow-step">
+              <div className="focus-flow-step-number">2</div>
+              <div className="focus-flow-step-copy">
+                <h3>Or skip for now</h3>
+                <p>Click "Skip" to enable eye gaze tracking without calibrating. You can recalibrate at any time using the "Recalibrate" button during a session.</p>
+              </div>
+            </div>
+          </div>
+
+          <label className="eye-gaze-modal-checkbox">
+            <input
+              type="checkbox"
+              checked={eyeGazeDontShow}
+              onChange={(e) => setEyeGazeDontShow(e.target.checked)}
+            />
+            Don't show this again
+          </label>
+
+          <div className="focus-flow-footer">
+            <button
+              type="button"
+              className="focus-flow-secondary"
+              onClick={() => handleEyeGazeModalAction(false)}
+            >
+              Skip
+            </button>
+            <button
+              className="focus-flow-button"
+              onClick={() => handleEyeGazeModalAction(true)}
+            >
+              Start Calibration
+            </button>
+          </div>
+        </div>
+      </div>
+    );
+  };
+
   return (
     <main id="page-b" className="page" style={pageStyle}>
       {renderIntroCard()}
+      {renderEyeGazeModal()}
 
       <section id="display-area" className="focus-display-shell">
         <video
@@ -827,9 +932,8 @@ function FocusPageLocal({ videoManager, sessionResult, setSessionResult, isActiv
                     backgroundColor: event.isFocused ? '#28a745' : '#dc3545',
                     width: '10px',
                     height: '20px',
-                    display: 'inline-block',
-                    marginRight: '2px',
-                    borderRadius: '2px'
+                    borderRadius: '2px',
+                    flexShrink: 0
                   }}
                   title={event.isFocused ? 'Focused' : 'Distracted'}
                 />

src/components/Help.jsx

@@ -28,11 +28,12 @@ function Help() {
           <h2>How to Use Focus Guard</h2>
           <ol>
             <li>Navigate to the Focus page from the menu</li>
-            <li>Allow camera access when prompted</li>
+            <li>Read the setup notes in the intro screen, then allow camera access when prompted</li>
             <li>Click the green "Start" button to begin monitoring</li>
-            <li>Position yourself in front of the camera</li>
+            <li>Position yourself in front of the camera with good lighting</li>
             <li>The system will track your focus in real-time using face mesh analysis</li>
-            <li>Use the model selector to switch between detection models (MLP, XGBoost, Geometric, Hybrid)</li>
+            <li>Use the model selector to switch between detection models (Hybrid, XGBoost, MLP, Geometric)</li>
+            <li>Optionally enable <strong>Eye Gaze</strong> tracking for additional gaze-based focus signals</li>
             <li>Click "Stop" when you're done to save the session</li>
           </ol>
         </section>
@@ -51,20 +52,38 @@ function Help() {
 
         <section className="help-section">
           <h2>Available Models</h2>
-          <p><strong>MLP:</strong> Neural network trained on extracted facial features. Good balance of speed and accuracy.</p>
-          <p><strong>XGBoost:</strong> Gradient-boosted tree model using 10 selected features. Strong on tabular data with fast inference.</p>
-          <p><strong>Geometric:</strong> Rule-based scoring using head pose and eye openness. No ML model needed, lightweight.</p>
-          <p><strong>Hybrid:</strong> Combines MLP predictions with geometric scoring for robust results.</p>
+          <p><strong>Hybrid</strong> <em>(Recommended)</em>: Combines XGBoost predictions with geometric face/eye scoring using a trained logistic regression combiner. Most robust across different people. LOPO F1: 0.8409.</p>
+          <p><strong>XGBoost:</strong> Gradient-boosted tree model using 10 selected features. Highest raw accuracy (95.87% pooled, LOPO AUC 0.8695). Strong on tabular data with fast inference.</p>
+          <p><strong>MLP:</strong> Two-layer neural network (10→64→32 neurons) trained with PyTorch. Good balance of speed and accuracy (92.92% pooled, LOPO AUC 0.8624). Fastest inference.</p>
+          <p><strong>Geometric:</strong> Rule-based scoring using head pose and eye openness. No ML model needed — lightweight fallback when model checkpoints are unavailable. LOPO F1: 0.8195.</p>
+          <p style={{ marginTop: '10px', color: '#667281', fontSize: '0.9rem' }}>
+            <strong>Tip:</strong> If you wear glasses or have unusual lighting, try different models to find the one that works best for your setup.
+          </p>
+        </section>
+
+        <section className="help-section">
+          <h2>Eye Gaze Tracking</h2>
+          <p>The <strong>Eye Gaze</strong> button enables L2CS-Net, a deep neural network that estimates your gaze direction from the eye region. It runs alongside your selected base model and can improve focus detection accuracy.</p>
+          <p style={{ marginTop: '8px' }}><strong>Performance note:</strong> Eye gaze tracking increases CPU usage and may reduce frame rate. If the system feels sluggish, disable it.</p>
+          <h3 style={{ marginTop: '14px', fontSize: '1rem' }}>Calibration</h3>
+          <p>For best accuracy, calibrate when prompted:</p>
+          <ol>
+            <li>Click "Start Calibration" in the warning dialog (or use the "Recalibrate" button during a session)</li>
+            <li>Look directly at each dot as it appears on screen — there are <strong>9 calibration points</strong> across the screen</li>
+            <li>A final <strong>validation point</strong> confirms accuracy before calibration is applied</li>
+          </ol>
+          <p>You can skip calibration and recalibrate at any time using the "Recalibrate" button, which appears in the model strip when Eye Gaze is on and a session is running.</p>
         </section>
 
         <section className="help-section">
           <h2>Adjusting Settings</h2>
-          <p><strong>Frame Rate:</strong> Controls how many frames per second are sent for analysis. Recommended: 15-30 FPS. Minimum is 10 FPS to ensure temporal features (blink rate, PERCLOS) remain accurate.</p>
-          <p><strong>Model Selection:</strong> Switch models in real-time using the pill buttons above the timeline. Different models may perform better depending on your lighting and setup.</p>
+          <p><strong>Frame Rate:</strong> Controls how many frames per second are sent for analysis. Range: 10–30 FPS. A minimum of 10 FPS is enforced to keep temporal features (blink rate, PERCLOS) accurate.</p>
+          <p><strong>Model Selection:</strong> Switch models in real-time using the pill buttons above the timeline. The active model is highlighted. Different models may perform better depending on your lighting, setup, and whether you wear glasses.</p>
+          <p><strong>Floating Window:</strong> Opens a Picture-in-Picture window with your camera feed so you can keep the video visible while working in other apps.</p>
         </section>
 
         <section className="help-section">
-          <h2>Privacy & Data</h2>
+          <h2>Privacy &amp; Data</h2>
           <p>Video frames are processed in real-time on the server and are never stored. Only focus status metadata (timestamps, confidence scores) is saved to the session database. View past runs under <strong>My Records</strong>; stats and badges live under <strong>My Achievement</strong>.</p>
           <p style={{ marginTop: '12px' }}>
             <button
@@ -94,13 +113,17 @@ function Help() {
             <summary>Why is my focus score low?</summary>
             <p>Ensure good lighting so the face mesh can detect your landmarks clearly. Face the camera directly and avoid large head movements. Try switching to a different model if one isn't working well for your setup.</p>
           </details>
+          <details>
+            <summary>Does wearing glasses affect accuracy?</summary>
+            <p>Yes, glasses can reduce accuracy — especially for eye-based features like EAR and gaze offset — because the lenses may distort landmark positions or cause reflections. If you wear glasses, try different models (e.g. Geometric or MLP may handle glasses better than XGBoost for some users). Avoid using Eye Gaze tracking with glasses as it may significantly degrade results.</p>
+          </details>
           <details>
             <summary>Can I use this without a camera?</summary>
             <p>No, camera access is required. The system relies on real-time face landmark detection to determine focus.</p>
           </details>
           <details>
             <summary>Does this work on mobile?</summary>
-            <p>Yes, it works on mobile browsers that support camera access and WebSocket connections. Performance depends on your device and network speed.</p>
+            <p>Yes, it works on mobile browsers that support camera access and WebSocket connections. Performance depends on your device and network speed. Eye Gaze tracking is not recommended on mobile due to performance constraints.</p>
           </details>
           <details>
             <summary>Is my data private?</summary>
@@ -108,17 +131,23 @@ function Help() {
           </details>
           <details>
             <summary>Why does the face mesh lag behind my movements?</summary>
-            <p>The face mesh overlay updates each time the server returns a detection result. The camera feed itself renders at 60fps locally. Any visible lag depends on network latency and server processing time.</p>
+            <p>The face mesh overlay updates each time the server returns a detection result. The camera feed itself renders locally. Any visible lag depends on network latency and server processing time. Reducing the frame rate slider can help if lag is noticeable.</p>
+          </details>
+          <details>
+            <summary>The Hybrid model doesn't seem to work differently from XGBoost — why?</summary>
+            <p>The Hybrid model uses a trained logistic regression combiner on top of XGBoost and geometric scores. If the combiner file wasn't available at startup, it falls back to a simple weighted average which behaves similarly to XGBoost. Check the server logs for "[HYBRID]" messages to confirm the combiner loaded correctly.</p>
           </details>
         </section>
 
         <section className="help-section">
           <h2>Technical Info</h2>
           <p><strong>Face Detection:</strong> MediaPipe Face Mesh (478 landmarks)</p>
-          <p><strong>Feature Extraction:</strong> Head pose (yaw/pitch/roll), EAR, MAR, gaze offset, PERCLOS, blink rate</p>
-          <p><strong>ML Models:</strong> MLP (scikit-learn), XGBoost, Geometric, Hybrid</p>
-          <p><strong>Storage:</strong> SQLite database</p>
+          <p><strong>Feature Extraction:</strong> Head pose (yaw/pitch/roll), EAR, MAR, gaze offset, PERCLOS, blink rate — 10 features selected via LOFO analysis</p>
+          <p><strong>ML Models:</strong> PyTorch MLP (10→64→32→2), XGBoost (600 trees), Geometric (rule-based), Hybrid (LR combiner over XGBoost+Geo)</p>
+          <p><strong>Eye Gaze:</strong> L2CS-Net (ResNet50 backbone, trained on Gaze360) with 9-point polynomial calibration</p>
+          <p><strong>Storage:</strong> SQLite database (sessions, events, settings)</p>
           <p><strong>Framework:</strong> FastAPI + React (Vite) + WebSocket</p>
+          <p><strong>Evaluation:</strong> Leave-One-Person-Out (LOPO) cross-validation on 9 participants, 144K frames</p>
         </section>
       </div>
     </main>

ui/pipeline.py

@@ -442,11 +442,14 @@ class HybridFocusPipeline:
             if not os.path.isfile(resolved_combiner):
                 resolved_combiner = os.path.join(_PROJECT_ROOT, combiner_path)
             if os.path.isfile(resolved_combiner):
-                blob = joblib.load(resolved_combiner)
-                self._combiner = blob.get("combiner")
-                if self._combiner is None:
-                    self._combiner = blob
-                print(f"[HYBRID] LR combiner loaded from {resolved_combiner}")
+                try:
+                    blob = joblib.load(resolved_combiner)
+                    self._combiner = blob.get("combiner")
+                    if self._combiner is None:
+                        self._combiner = blob
+                    print(f"[HYBRID] LR combiner loaded from {resolved_combiner}")
+                except Exception as e:
+                    print(f"[HYBRID] Failed to load combiner ({e}); using heuristic weights")
             else:
                 print(f"[HYBRID] combiner_path not found: {resolved_combiner}, using heuristic weights")
         if self._use_xgb: