Add browser chrome, packaging pipeline, and fix UTF-8 crash in calibration

Browser chrome: top toolbar (back/forward/reload/home/address bar) and left
sidebar (Calibrate/Validate/Start Session) replace the old status pill, so
the window reads as a normal browser. Page content is pushed below/right of
the chrome via forced body padding instead of being hidden underneath it.
Session overlays now re-inject on navigation so a tracking session survives
back/forward. Added an in-app "update available" notice backed by
version.json.

Packaging: calibrate.py refactored into main() so it can run as
`--mode calibrate` inside a frozen build instead of shelling out to a
missing .py file; RESOURCE_DIR/DATA_DIR split (bundled assets vs. per-user
writable data) added to all three entry points. New packaging/ with a
PyInstaller onedir spec and an Inno Setup installer script (per-user install,
fixed AppId for in-place upgrades).

Fix: Windows consoles default to cp1252, so a single unicode character in a
print() (calibrate.py's low-sample "⚠" warning) crashed the whole
calibration run with UnicodeEncodeError — hit for real mid-session. All
three entry points now force UTF-8 stdout/stderr with errors="replace".

.gitattributes

@@ -1,3 +1,4 @@
 *.onnx.data filter=lfs diff=lfs merge=lfs -text
 *.pt filter=lfs diff=lfs merge=lfs -text
 *.onnx filter=lfs diff=lfs merge=lfs -text
+*.exe filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -16,6 +16,7 @@
 !.gitattributes
 !README.md
 !requirements.txt
+!version.json
 
 !calibrate.py
 !validate.py
@@ -24,6 +25,10 @@
 !inference_pipeline.py
 !session_logger.py
 
+!packaging/InsightUX.spec
+!packaging/installer.iss
+!packaging/README.md
+
 !preprocessing/__init__.py
 !preprocessing/preprocessing_pipeline.py
 

README.md

@@ -52,6 +52,9 @@ venv\Scripts\activate
 pip install -r requirements.txt
 ```
 
+This includes `onnx`, which `calibrate.py` needs when it exports the
+fine-tuned model after training.
+
 **Do not `pip install --upgrade` pywebview or pythonnet.** `requirements.txt`
 pins `pywebview==4.4.1` and `pythonnet==3.0.3` deliberately — newer versions
 have a bug in their Windows backend that freezes the app window and floods

browser_session.py

@@ -24,9 +24,20 @@ import json
 import time
 import math
 import threading
+import subprocess
 from dataclasses import replace
 from datetime import datetime
 
+# Windows consoles default to a non-UTF-8 codepage (cp1252) — a stray
+# unicode character in any print() (ours, or one of calibrate.py/validate.py's
+# once relaunched as a subprocess sharing this process's stdout handle) would
+# otherwise crash the whole process with UnicodeEncodeError. Confirmed this
+# happened for real during a calibration run mid-session.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
 import cv2
 import numpy as np
 import webview
@@ -56,8 +67,25 @@ from analysis import generate_report
 # CONFIG — kept identical to run_session.py so calibration.pkl stays valid
 # =============================================================================
 
-ONNX_PATH        = "models/gaze_cnn_v4.onnx"
-CALIBRATION_PATH = "calibration.pkl"
+# Bundled read-only assets (models/checkpoints) vs. per-user writable data
+# (calibration.pkl, sessions/, the generated landing page) need different
+# roots once frozen by PyInstaller — onedir nests bundled data under
+# _internal/, alongside a persistent folder holding InsightUX.exe itself.
+if getattr(sys, "frozen", False):
+    RESOURCE_DIR = sys._MEIPASS
+    DATA_DIR     = os.path.dirname(sys.executable)
+else:
+    RESOURCE_DIR = os.path.dirname(os.path.abspath(__file__))
+    DATA_DIR     = RESOURCE_DIR
+BASE_DIR         = DATA_DIR   # kept as an alias: subprocess cwd for calibrate/validate relaunches
+
+# Bump alongside packaging/installer.iss's AppVersion on every release, and
+# update version.json in the same commit — see packaging/README.md.
+VERSION = "1.0.0"
+VERSION_CHECK_URL = "https://huggingface.co/arpitasethiii/insightux/resolve/main/version.json"
+
+ONNX_PATH        = os.path.join(RESOURCE_DIR, "models", "gaze_cnn_v4.onnx")
+CALIBRATION_PATH = os.path.join(DATA_DIR, "calibration.pkl")
 SCREEN_W, SCREEN_H = pyautogui.size()
 
 PATCH_SOURCE   = "blended"
@@ -78,7 +106,7 @@ POSE_NORM_SCALE         = 30.0
 HEAD_PITCH_COMPENSATION = 0.0  # reverted — 0.35 made accuracy worse, not better
 HEAD_YAW_COMPENSATION   = 0.0
 
-SESSIONS_ROOT = "sessions"
+SESSIONS_ROOT = os.path.join(DATA_DIR, "sessions")
 
 # The window opens on this local, fully InsightUX-branded page instead of
 # raw google.com. What you type here still hits REAL Google — no fake
@@ -154,7 +182,7 @@ _LANDING_HTML = r"""<!DOCTYPE html>
 
 
 def _write_landing_page():
-    path = os.path.abspath("insightux_landing.html")
+    path = os.path.join(DATA_DIR, "insightux_landing.html")
     with open(path, "w", encoding="utf-8") as f:
         f.write(_LANDING_HTML)
     return "file://" + path.replace(os.sep, "/")
@@ -219,52 +247,184 @@ class OneEuroFilter:
 
 
 # =============================================================================
-# JS: control widget (always present) — search hint + S/Esc keybindings
+# JS: browser chrome (always present) — top toolbar (back/forward/reload/
+# home/address bar) + left sidebar (Calibrate/Validate/Start Session), so the
+# window reads as a normal browser instead of a bare content pane. Purely an
+# HTML/CSS/JS overlay drawn on top of whatever page is loaded — pywebview
+# 4.4.1 has no native toolbar API, so this is the only way to add persistent
+# chrome without switching GUI frameworks.
+#
+# The page itself is pushed down/right by exactly the toolbar height and
+# sidebar width (via forced <body> padding, not just floating the chrome on
+# top of it) so real page content is never hidden underneath — the chrome
+# and the website occupy clearly separate regions instead of overlapping.
+# overflow-x is force-hidden as a safety net against the small width
+# reduction ever introducing a horizontal scrollbar. The one edge case this
+# can't fully solve: a small minority of sites use position:fixed elements
+# of their own pinned to the true viewport edges (independent of body
+# padding) — those can still end up visually behind our chrome.
 # =============================================================================
 
-CONTROL_JS = r"""
+CHROME_JS = r"""
 (function(){
   if (window.__insightuxControl) { return; }
   window.__insightuxControl = true;
 
   // S/E (start/stop tracking) only make sense on an actual website — not on
   // the InsightUX landing/search page and not on a generated insights
-  // report page. X (quit the app) always works, on every page.
+  // report page. The toolbar/sidebar, and X (quit), always work everywhere.
   const isLanding   = !!document.querySelector('meta[name="insightux-landing"]');
   const isReport    = !!document.querySelector('meta[name="insightux-report"]');
   const isTrackable = !isLanding && !isReport;
 
-  if (isTrackable) {
-    const banner = document.createElement('div');
-    banner.id = '__insightux_pill';
-    banner.style.cssText = `
-      position:fixed; top:0; left:0; right:0; z-index:2147483647;
-      display:flex; align-items:center; justify-content:space-between;
-      padding:7px 16px; font:12px -apple-system,Arial;
-      background:linear-gradient(90deg, rgba(20,18,26,0.95), rgba(30,20,40,0.95));
+  const style = document.createElement('style');
+  style.textContent = `
+    html {
+      overflow-x: hidden !important;
+    }
+    body {
+      box-sizing: border-box !important;
+      width: 100vw !important;
+      margin: 0 !important;
+      padding-top: 46px !important;
+      padding-left: 84px !important;
+      overflow-x: hidden !important;
+    }
+    #__insightux_toolbar {
+      position:fixed; top:0; left:0; right:0; height:46px; z-index:2147483647;
+      display:flex; align-items:center; gap:10px; padding:0 12px; box-sizing:border-box;
+      background:linear-gradient(90deg, rgba(20,18,26,0.97), rgba(30,20,40,0.97));
       border-bottom:2px solid; border-image:linear-gradient(90deg,#7B2FBE,#FF2DF0) 1;
-      box-shadow:0 3px 14px rgba(0,0,0,0.35); pointer-events:none;
-    `;
-    banner.innerHTML = `
-      <span style="display:flex;align-items:center;gap:7px;">
-        <span style="width:8px;height:8px;border-radius:50%;background:linear-gradient(135deg,#7B2FBE,#FF2DF0);display:inline-block;"></span>
-        <b style="color:#f0ecf7;letter-spacing:0.02em;">InsightUX</b>
-        <span style="color:#7a7288;">Eye + Mouse Research Browser</span>
-      </span>
-      <span id="__insightux_status" style="color:#c9a6f5;">Press S to start tracking &middot; E to stop &middot; H heatmap &middot; M mouse panel &middot; X quit</span>
-    `;
-    document.documentElement.appendChild(banner);
-
-    setInterval(function(){
-      if (!document.documentElement.contains(banner)) document.documentElement.appendChild(banner);
-    }, 1000);
-  }
+      box-shadow:0 3px 14px rgba(0,0,0,0.35);
+      font:12px -apple-system,'Segoe UI',Arial; color:#f0ecf7;
+    }
+    #__insightux_toolbar button {
+      flex:0 0 auto; width:30px; height:30px; border-radius:8px; cursor:pointer;
+      background:#241f2e; border:1px solid #3a3348; color:#f0ecf7; font-size:15px;
+      display:flex; align-items:center; justify-content:center;
+    }
+    #__insightux_toolbar button:hover { background:#302a3d; }
+    #__iux_addr_form { flex:1 1 auto; min-width:0; }
+    #__iux_addr {
+      width:100%; box-sizing:border-box; padding:7px 14px; border-radius:16px;
+      border:1.5px solid #3a3348; background:#1c1826; color:#f0ecf7; outline:none;
+      font-size:12.5px;
+    }
+    #__iux_addr:focus { border-color:#9B59FF; }
+    #__insightux_status {
+      flex:0 0 auto; color:#c9a6f5; white-space:nowrap; max-width:30vw;
+      overflow:hidden; text-overflow:ellipsis;
+    }
+    #__insightux_sidebar {
+      position:fixed; top:46px; left:0; bottom:0; width:84px; z-index:2147483647;
+      display:flex; flex-direction:column; align-items:stretch; gap:8px; padding:10px 8px;
+      box-sizing:border-box; font:11px -apple-system,'Segoe UI',Arial;
+      background:linear-gradient(180deg, rgba(24,20,32,0.97), rgba(16,14,22,0.97));
+      border-right:2px solid; border-image:linear-gradient(180deg,#7B2FBE,#FF2DF0) 1;
+      box-shadow:3px 0 14px rgba(0,0,0,0.35);
+    }
+    #__insightux_sidebar button {
+      background:#241f2e; border:1px solid #3a3348; color:#f0ecf7; border-radius:10px;
+      padding:10px 4px; cursor:pointer; line-height:1.5; font-size:11px; text-align:center;
+    }
+    #__insightux_sidebar button:hover { background:#302a3d; }
+    #__iux_session.active { background:linear-gradient(135deg,#7B2FBE,#FF2DF0); border-color:transparent; }
+    #__insightux_sidebar .__iux_hints {
+      margin-top:auto; color:#7a7288; font-size:9.5px; line-height:1.6; text-align:center;
+    }
+    #__insightux_update {
+      display:none; cursor:pointer; flex:0 0 auto; white-space:nowrap;
+      padding:5px 12px; border-radius:12px; font-weight:600; font-size:11px;
+      background:linear-gradient(135deg,#7B2FBE,#FF2DF0); color:#fff;
+    }
+    #__insightux_update:hover { filter:brightness(1.12); }
+  `;
+  document.head.appendChild(style);
+
+  const toolbar = document.createElement('div');
+  toolbar.id = '__insightux_toolbar';
+  toolbar.innerHTML = `
+    <button type="button" id="__iux_back" title="Back">&#8592;</button>
+    <button type="button" id="__iux_fwd" title="Forward">&#8594;</button>
+    <button type="button" id="__iux_reload" title="Reload">&#8635;</button>
+    <button type="button" id="__iux_home" title="Home">&#8962;</button>
+    <form id="__iux_addr_form"><input id="__iux_addr" type="text" autocomplete="off"
+      placeholder="Search or enter address"></form>
+    <span id="__insightux_update" title="Click to open the download page"></span>
+    <span id="__insightux_status">Press S to start tracking &middot; E to stop &middot; H heatmap &middot; M mouse panel &middot; X quit</span>
+  `;
+  document.documentElement.appendChild(toolbar);
+
+  const sidebar = document.createElement('div');
+  sidebar.id = '__insightux_sidebar';
+  sidebar.innerHTML = `
+    <button type="button" id="__iux_calibrate">&#128065;<br>Calibrate</button>
+    <button type="button" id="__iux_validate">&#127919;<br>Validate</button>
+    <button type="button" id="__iux_session">&#9654;<br>Start<br>Session</button>
+    <div class="__iux_hints">S/E start&#47;stop<br>H heatmap<br>M panel<br>X quit</div>
+  `;
+  document.documentElement.appendChild(sidebar);
+
+  setInterval(function(){
+    if (!document.documentElement.contains(toolbar)) document.documentElement.appendChild(toolbar);
+    if (!document.documentElement.contains(sidebar)) document.documentElement.appendChild(sidebar);
+  }, 1000);
 
   const statusEl = () => document.getElementById('__insightux_status');
   window.insightuxSetStatus = function(text){
     const el = statusEl();
     if (el) el.textContent = text;
   };
+  window.insightuxSetSessionUI = function(isTracking){
+    const btn = document.getElementById('__iux_session');
+    if (!btn) return;
+    btn.innerHTML = isTracking ? '&#9632;<br>Stop<br>Session' : '&#9654;<br>Start<br>Session';
+    btn.classList.toggle('active', isTracking);
+  };
+  window.insightuxShowUpdate = function(version, url){
+    const el = document.getElementById('__insightux_update');
+    if (!el) return;
+    el.textContent = 'Update available (v' + version + ')';
+    el.style.display = 'inline-block';
+    el.onclick = function(){
+      if (window.pywebview && window.pywebview.api && window.pywebview.api.open_update_page) {
+        window.pywebview.api.open_update_page(url);
+      }
+    };
+  };
+
+  // -- address bar / navigation (pure DOM history/location, no Python round-trip) --
+  const addrInput = document.getElementById('__iux_addr');
+  addrInput.value = isLanding ? '' : location.href;
+  document.getElementById('__iux_addr_form').addEventListener('submit', function(e){
+    e.preventDefault();
+    const raw = addrInput.value.trim();
+    if (!raw) return;
+    const looksLikeUrl = /^https?:\/\//i.test(raw) ||
+                          (/^[\w-]+(\.[\w-]+)+([/?#].*)?$/i.test(raw) && !raw.includes(' '));
+    if (looksLikeUrl) {
+      location.href = raw.startsWith('http') ? raw : ('https://' + raw);
+    } else {
+      location.href = 'https://www.google.com/search?q=' + encodeURIComponent(raw);
+    }
+  });
+  document.getElementById('__iux_back').addEventListener('click', function(){ history.back(); });
+  document.getElementById('__iux_fwd').addEventListener('click', function(){ history.forward(); });
+  document.getElementById('__iux_reload').addEventListener('click', function(){ location.reload(); });
+  document.getElementById('__iux_home').addEventListener('click', function(){
+    location.href = __INSIGHTUX_LANDING_URL__;
+  });
+
+  // -- sidebar actions (Python decides validity — camera/session conflicts,
+  // wrong page — and reports back through the status text) --
+  function callApi(method){
+    if (window.pywebview && window.pywebview.api && window.pywebview.api[method]) {
+      window.pywebview.api[method]();
+    }
+  }
+  document.getElementById('__iux_calibrate').addEventListener('click', function(){ callApi('start_calibration'); });
+  document.getElementById('__iux_validate').addEventListener('click', function(){ callApi('run_validation'); });
+  document.getElementById('__iux_session').addEventListener('click', function(){ callApi('toggle_session'); });
 
   function isTypingTarget(el){
     if (!el) return false;
@@ -302,12 +462,15 @@ CONTROL_JS = r"""
   }, true);  // capture phase — fires before page scripts can intercept/stop the event
 })();
 """
+CHROME_JS = CHROME_JS.replace("__INSIGHTUX_LANDING_URL__", json.dumps(LANDING_URL))
 
 # JS: tracking overlay (gaze dot + AOI highlighting) — injected only once
 # tracking actually starts. Ported directly from run_session.py's JS_SETUP.
 TRACKING_JS = r"""
 (function(){
   if (window.__insightux) { return; }
+  const OWN_UI_IDS = new Set(['__insightux_toolbar', '__insightux_sidebar', '__insightux_pill', '__insightux_canvas', '__insightux_mouse_panel']);
+  const OWN_UI_SELECTOR = '#__insightux_toolbar, #__insightux_sidebar, #__insightux_pill, #__insightux_canvas, #__insightux_mouse_panel';
   const state = { aois: [] };
   const dwell = { pendLabel: null, pendSince: 0, activeLabel: null, emptySince: 0 };
   const DWELL_MS = 420;
@@ -382,10 +545,10 @@ TRACKING_JS = r"""
 
     function consider(el){
       if (full) return;
-      // Never track InsightUX's own injected UI (the "press S/E" pill,
-      // the gaze-dot canvas, the mouse tracker panel) as if it were page content.
-      if (el.id === '__insightux_pill' || el.id === '__insightux_canvas' || el.id === '__insightux_mouse_panel') return;
-      if (el.closest && el.closest('#__insightux_pill, #__insightux_canvas, #__insightux_mouse_panel')) return;
+      // Never track InsightUX's own injected UI (toolbar, sidebar, the
+      // gaze-dot canvas, the mouse tracker panel) as if it were page content.
+      if (OWN_UI_IDS.has(el.id)) return;
+      if (el.closest && el.closest(OWN_UI_SELECTOR)) return;
       const tag = el.tagName.toLowerCase();
       const explicit = !!(el.dataset && el.dataset.aoi);
       if (!explicit){
@@ -662,12 +825,14 @@ MOUSE_JS = r"""
   }, 2000);
 
   // ---- exclude InsightUX's own injected UI from every measurement ----
-  // (the status pill, the mouse-tracker panel, the heatmap canvas) — only
+  // (the toolbar, sidebar, mouse-tracker panel, heatmap canvas) — only
   // real website elements should ever show up in trail/heatmap/dwell/clicks.
+  const OWN_UI_IDS = new Set(['__insightux_toolbar', '__insightux_sidebar', '__insightux_pill', '__insightux_canvas', '__insightux_mouse_panel']);
+  const OWN_UI_SELECTOR = '#__insightux_toolbar, #__insightux_sidebar, #__insightux_pill, #__insightux_canvas, #__insightux_mouse_panel';
   function isOwnUI(el){
     if (!el) return false;
-    if (el.id === '__insightux_pill' || el.id === '__insightux_canvas' || el.id === '__insightux_mouse_panel') return true;
-    return !!(el.closest && el.closest('#__insightux_pill, #__insightux_canvas, #__insightux_mouse_panel'));
+    if (OWN_UI_IDS.has(el.id)) return true;
+    return !!(el.closest && el.closest(OWN_UI_SELECTOR));
   }
 
   // ---- mouse position + hover tracking ----
@@ -992,11 +1157,22 @@ MOUSE_JS = r"""
 # =============================================================================
 
 # Pages tracking must never start on, checked against window.get_current_url()
-# as a Python-side backstop to CONTROL_JS's isTrackable check (belt and
+# as a Python-side backstop to CHROME_JS's isTrackable check (belt and
 # suspenders — the JS guard can't run before the JS bridge is up).
 _NON_TRACKABLE_URL_MARKERS = ("insightux_landing.html", "analysis_report.html")
 
 
+def _relaunch_args(mode):
+    """Command to spawn calibrate.py/validate.py's logic in a fresh process.
+    Frozen (PyInstaller) builds have no bundled interpreter to hand a .py
+    file to, and sys.executable IS the frozen exe itself — so a frozen build
+    relaunches itself with --mode instead. Unpackaged/dev mode still runs
+    from the venv exactly as before."""
+    if getattr(sys, "frozen", False):
+        return [sys.executable, "--mode", mode]
+    return [sys.executable, os.path.abspath(__file__), "--mode", mode]
+
+
 class Api:
     def __init__(self):
         self.window = None
@@ -1005,6 +1181,33 @@ class Api:
         self.thread = None
         self.mouse_log_f = None
         self.mouse_close_timer = None
+        self.calib_proc = None
+        self.validate_proc = None
+        self.update_info = None
+
+    def _notify_update(self, version, url):
+        try:
+            self.window.evaluate_js(
+                f"window.insightuxShowUpdate && window.insightuxShowUpdate("
+                f"{json.dumps(version)}, {json.dumps(url)})"
+            )
+        except Exception:
+            pass
+
+    def open_update_page(self, url):
+        print(f"[browser_session] open_update_page() called from JS: {url}")
+        import webbrowser
+        try:
+            webbrowser.open(url)
+        except Exception as e:
+            print(f"[browser_session] failed to open update url: {e}")
+        return True
+
+    def toggle_session(self):
+        """Single entry point for the sidebar's Start/Stop Session button —
+        lets the JS button stay dumb (always call the same thing) while
+        Python decides which action makes sense from current state."""
+        return self.stop_tracking() if self.tracking else self.start_tracking()
 
     def start_tracking(self):
         print("[browser_session] start_tracking() called from JS")
@@ -1019,6 +1222,10 @@ class Api:
             print(f"[browser_session]   refusing to start on non-website page: {current_url}")
             self._set_status("Start tracking only works on a website — search or open a page first.")
             return False
+        if self._external_proc_running():
+            print("[browser_session]   refusing to start, calibration/validation still running")
+            self._set_status("Wait for calibration/validation to finish before starting a session.")
+            return False
         if not os.path.exists(CALIBRATION_PATH):
             print(f"[browser_session]   no {CALIBRATION_PATH} found — run calibrate.py first")
             self._set_status("No calibration.pkl found — run calibrate.py first.")
@@ -1034,6 +1241,7 @@ class Api:
         self._inject_mouse_overlay()
         self._open_mouse_log(session_dir)
         self._set_mouse_tracking(True)
+        self._set_session_ui(True)
         self._set_status("Recording gaze + mouse... Press E to stop, H for heatmap, M for mouse panel")
 
         self.thread = threading.Thread(
@@ -1050,6 +1258,7 @@ class Api:
             return False
         self._set_status("Wrapping up your session...")
         self._set_mouse_tracking(False)
+        self._set_session_ui(False)
         self.stop_event.set()
 
         # Give the page a moment to flush its last batch of mouse data over
@@ -1067,6 +1276,77 @@ class Api:
         print("[browser_session] quit_app() called from JS -- terminating process")
         os._exit(0)
 
+    # -- calibration / validation ------------------------------------------
+    # calibrate.py and validate.py are unmodified, standalone OpenCV/pyautogui
+    # scripts (their own fullscreen window, their own event loop) — they were
+    # never meant to share a process with pywebview's GUI loop. Launching them
+    # as a subprocess reuses them exactly as-is instead of rewriting their
+    # display logic into the browser.
+
+    def _external_proc_running(self):
+        running = lambda p: p is not None and p.poll() is None
+        return running(self.calib_proc) or running(self.validate_proc)
+
+    def start_calibration(self):
+        print("[browser_session] start_calibration() called from JS")
+        if self.tracking:
+            self._set_status("Stop the current session (E) before calibrating.")
+            return False
+        if self._external_proc_running():
+            self._set_status("Calibration/validation is already running in another window.")
+            return False
+        try:
+            self.calib_proc = subprocess.Popen(_relaunch_args("calibrate"), cwd=BASE_DIR)
+        except Exception as e:
+            print(f"[browser_session] failed to launch calibrate.py: {e}")
+            self._set_status("Could not launch calibration — see terminal for details.")
+            return False
+        self._set_status("Calibration launched in a separate window — follow the dots there.")
+        threading.Thread(
+            target=self._watch_external_proc, args=(self.calib_proc, "Calibration"), daemon=True
+        ).start()
+        return True
+
+    def run_validation(self):
+        print("[browser_session] run_validation() called from JS")
+        if self.tracking:
+            self._set_status("Stop the current session (E) before validating.")
+            return False
+        if self._external_proc_running():
+            self._set_status("Calibration/validation is already running in another window.")
+            return False
+        if not os.path.exists(CALIBRATION_PATH):
+            self._set_status("No calibration.pkl found — run Calibrate first.")
+            return False
+        try:
+            self.validate_proc = subprocess.Popen(_relaunch_args("validate"), cwd=BASE_DIR)
+        except Exception as e:
+            print(f"[browser_session] failed to launch validate.py: {e}")
+            self._set_status("Could not launch validation — see terminal for details.")
+            return False
+        self._set_status("Validation launched in a separate window — look at each dot.")
+        threading.Thread(
+            target=self._watch_external_proc, args=(self.validate_proc, "Validation"), daemon=True
+        ).start()
+        return True
+
+    def _watch_external_proc(self, proc, label):
+        proc.wait()
+        print(f"[browser_session] {label} process exited (code {proc.returncode})")
+        if label == "Calibration":
+            self._set_status("Calibration finished — check the terminal for the quality readout, then press S or Start Session.")
+        else:
+            self._set_status("Validation finished — check the terminal for the accuracy numbers.")
+
+    def _set_session_ui(self, is_tracking):
+        try:
+            flag = "true" if is_tracking else "false"
+            self.window.evaluate_js(
+                f"window.insightuxSetSessionUI && window.insightuxSetSessionUI({flag})"
+            )
+        except Exception:
+            pass
+
     def _inject_tracking_overlay(self):
         try:
             self.window.evaluate_js(TRACKING_JS)
@@ -1134,11 +1414,51 @@ class Api:
 api = Api()
 
 
-def inject_control(window):
+def _version_tuple(v):
+    return tuple(int(p) for p in v.split(".") if p.isdigit())
+
+
+def check_for_update():
+    """Runs once in a background thread at startup. Publishing a new release
+    is still fully manual (bump VERSION here + AppVersion in installer.iss +
+    version.json, rebuild, push) — this only automates the *checking* side,
+    per the confirmed scope. No internet / any failure here is silent:
+    the user just doesn't see an update banner, never an error."""
+    import urllib.request
     try:
-        window.evaluate_js(CONTROL_JS)
+        with urllib.request.urlopen(VERSION_CHECK_URL, timeout=4) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+        latest = data.get("latest", "")
+        url = data.get("url", "")
+        if latest and url and _version_tuple(latest) > _version_tuple(VERSION):
+            api.update_info = {"version": latest, "url": url}
+            api._notify_update(latest, url)
+            print(f"[browser_session] update available: {VERSION} -> {latest}")
     except Exception as e:
-        print(f"[browser_session] control inject failed (will retry): {e}")
+        print(f"[browser_session] update check skipped: {e}")
+
+
+def on_page_loaded(window):
+    """Fires on every page load (navigation, back/forward, reload — not just
+    the first page). The chrome must be re-injected every time since each
+    navigation is a fresh document. If a session is already running, the
+    gaze/mouse overlays need the same treatment or navigating mid-session
+    would silently kill the dot and the mouse tracker on the new page."""
+    try:
+        window.evaluate_js(CHROME_JS)
+    except Exception as e:
+        print(f"[browser_session] chrome inject failed (will retry): {e}")
+
+    if api.tracking:
+        api._inject_tracking_overlay()
+        api._inject_mouse_overlay()
+        api._set_mouse_tracking(True)
+        api._set_session_ui(True)
+
+    # CHROME_JS was just re-injected fresh on this page and has no memory of
+    # an update found on a previous page — re-tell it if one was found.
+    if api.update_info:
+        api._notify_update(api.update_info["version"], api.update_info["url"])
 
 
 # =============================================================================
@@ -1343,20 +1663,36 @@ def _go_fullscreen(window):
 
 
 if __name__ == "__main__":
-    os.makedirs(SESSIONS_ROOT, exist_ok=True)
-
-    window = webview.create_window(
-        "InsightUX — Eye-Tracking Research Browser", LANDING_URL,
-        width=SCREEN_W, height=SCREEN_H, js_api=api
-    )
-    api.window = window
-    window.events.loaded += lambda: inject_control(window)
-    window.events.shown += lambda: threading.Thread(
-        target=_go_fullscreen, args=(window,), daemon=True
-    ).start()
-
-    # debug=True enables right-click > Inspect (DevTools) so you can see
-    # the [insightux] console.log diagnostics from CONTROL_JS directly —
-    # keyboard handling runs entirely in the browser, so JS-side issues
-    # never show up in this terminal, only in DevTools' Console tab.
-    webview.start(debug=True)
+    # A packaged build is one exe with no separate calibrate.py/validate.py
+    # files to shell out to — --mode makes it a single self-dispatching
+    # entry point instead. See _relaunch_args() above for the launch side.
+    import argparse
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--mode", choices=["browser", "calibrate", "validate"], default="browser")
+    args = parser.parse_args()
+
+    if args.mode == "calibrate":
+        import calibrate
+        calibrate.main()
+    elif args.mode == "validate":
+        import validate
+        validate.main()
+    else:
+        os.makedirs(SESSIONS_ROOT, exist_ok=True)
+
+        window = webview.create_window(
+            "InsightUX — Eye-Tracking Research Browser", LANDING_URL,
+            width=SCREEN_W, height=SCREEN_H, js_api=api
+        )
+        api.window = window
+        window.events.loaded += lambda: on_page_loaded(window)
+        window.events.shown += lambda: threading.Thread(
+            target=_go_fullscreen, args=(window,), daemon=True
+        ).start()
+        threading.Thread(target=check_for_update, daemon=True).start()
+
+        # debug=True enables right-click > Inspect (DevTools) so you can see
+        # the [insightux] console.log diagnostics from CHROME_JS directly —
+        # keyboard handling runs entirely in the browser, so JS-side issues
+        # never show up in this terminal, only in DevTools' Console tab.
+        webview.start(debug=True)

calibrate.py

@@ -4,10 +4,32 @@ import time
 import os
 import random
 import pyautogui
+import sys
+
+# Windows consoles default to a non-UTF-8 codepage (cp1252). A single
+# unicode character in a print() (the "⚠" warning glyph below, for example)
+# then crashes the whole calibration run with UnicodeEncodeError — this is
+# not hypothetical, it happened mid-session. errors="replace" means an
+# unencodable glyph degrades to "?" instead of killing the process.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
 
 import warnings
 warnings.filterwarnings("ignore", category=DeprecationWarning)
 
+# Bundled read-only assets (models/checkpoints) vs. per-user writable data
+# (calibration.pkl, baseline_pose.pkl) need different roots once frozen by
+# PyInstaller (onedir nests bundled data under _internal/, alongside a
+# persistent folder holding the actual InsightUX.exe).
+if getattr(sys, "frozen", False):
+    RESOURCE_DIR = sys._MEIPASS
+    DATA_DIR     = os.path.dirname(sys.executable)
+else:
+    RESOURCE_DIR = os.path.dirname(os.path.abspath(__file__))
+    DATA_DIR     = RESOURCE_DIR
+
 from preprocessing.preprocessing_pipeline import (
     create_face_mesh,
     estimate_camera_matrix,
@@ -420,8 +442,8 @@ def filter_unreliable_points(gaze_vectors, screen_points, head_pitches_deg,
 # CONFIG
 # =============================================================================
 
-ONNX_PATH = "models/gaze_cnn_v4.onnx"
-CKPT_PATH = "checkpoints/best_model_v4.pt"
+ONNX_PATH = os.path.join(RESOURCE_DIR, "models", "gaze_cnn_v4.onnx")
+CKPT_PATH = os.path.join(RESOURCE_DIR, "checkpoints", "best_model_v4.pt")
 
 # --- Fine-tune target geometry -------------------------------------------
 # USE_MEASURED_GEOMETRY=False keeps the original hand-picked constants
@@ -481,530 +503,535 @@ FRAMES_KEPT_PER_POINT = 12
 FINETUNE_ENABLED = True
 
 
-# =============================================================================
-# MAIN CALIBRATION
-# =============================================================================
-
-pipeline  = InsightUXPipeline(ONNX_PATH)
-face_mesh = create_face_mesh(static_image_mode=False)
-cap       = cv2.VideoCapture(0)
-
-cam_matrix = None
-
-gaze_vectors     = []   # per-point median [pitch, yaw] (pre-fine-tune)
-screen_points    = []   # per-point [sx, sy]
-head_pitches_deg = []   # per-point median head pitch (deg)
-point_dispersion = []   # per-point [mad_pitch, mad_yaw]  <- the noise floor
-point_frames     = []   # per-point dict of REAL diverse frames (see below)
-point_ear        = []   # per-point median eye-aperture (candidate vertical cue)
-
-# Session-wide diagnostics, so we can warn about systemic issues at the end
-# rather than just per-point.
-session_brightness   = []
-session_distance_mm  = []   # viewing distance from solvePnP — real geometry, not a guess
-session_blink_skips  = 0
-session_light_skips  = 0
-points_with_low_yield = []
-
-cam_matrix_ref = [None]
-face_orientation_gate(face_mesh, cap, cam_matrix_ref)
-if cam_matrix_ref[0] is not None:
-    cam_matrix = cam_matrix_ref[0]
-
-cv2.namedWindow("Calibration", cv2.WINDOW_NORMAL)
-cv2.setWindowProperty("Calibration", cv2.WND_PROP_FULLSCREEN, cv2.WINDOW_FULLSCREEN)
-
-total = len(points)
-print(f"Calibration started - {total} points")
-
-for idx, (px, py) in enumerate(points):
-    sx, sy   = int(px * SCREEN_W), int(py * SCREEN_H)
-    duration = get_duration(py)
-
-    settle_s = 1.5 if idx == 0 else 0.4
-    settle_start = time.time()
-    while time.time() - settle_start < settle_s:
-        ret, frame = cap.read()
-        if not ret:
-            continue
-        screen = np.zeros((SCREEN_H, SCREEN_W, 3), dtype=np.uint8)
-        cv2.circle(screen, (sx, sy), 18, (80, 80, 80), -1)
-        msg = "Get ready..." if idx == 0 else "Settling..."
-        cv2.putText(screen, msg, (50, 50),
-                    cv2.FONT_HERSHEY_SIMPLEX, 1, (180, 180, 180), 2)
-        cv2.imshow("Calibration", screen)
-        cv2.waitKey(1)
-
-    samples    = []
-    ear_list   = []
-    l_list     = []
-    r_list     = []
-    p_list     = []
-    hp_list    = []
-
-    point_blink_skips = 0
-    point_light_skips = 0
-
-    start = time.time()
-
-    while time.time() - start < duration:
-        ret, frame = cap.read()
-        if not ret:
-            continue
-
-        if cam_matrix is None:
-            cam_matrix = estimate_camera_matrix(frame.shape)
-
-        # LIVE LIGHTING CHECK — skip this frame and tell the person, instead
-        # of silently feeding a too-dark/too-bright frame into the model.
-        light_ok, light_msg = check_lighting(frame)
-        gray_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
-        session_brightness.append(float(np.mean(gray_frame)))
-        if not light_ok:
-            point_light_skips += 1
-            screen  = np.zeros((SCREEN_H, SCREEN_W, 3), dtype=np.uint8)
-            cv2.circle(screen, (sx, sy), 18, (0, 140, 255), 2)
-            cv2.putText(screen, f"Point {idx+1}/{total} - {light_msg}",
-                        (50, 50), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 140, 255), 2)
+def main():
+    # =============================================================================
+    # MAIN CALIBRATION
+    # =============================================================================
+
+    pipeline  = InsightUXPipeline(ONNX_PATH)
+    face_mesh = create_face_mesh(static_image_mode=False)
+    cap       = cv2.VideoCapture(0)
+
+    cam_matrix = None
+
+    gaze_vectors     = []   # per-point median [pitch, yaw] (pre-fine-tune)
+    screen_points    = []   # per-point [sx, sy]
+    head_pitches_deg = []   # per-point median head pitch (deg)
+    point_dispersion = []   # per-point [mad_pitch, mad_yaw]  <- the noise floor
+    point_frames     = []   # per-point dict of REAL diverse frames (see below)
+    point_ear        = []   # per-point median eye-aperture (candidate vertical cue)
+
+    # Session-wide diagnostics, so we can warn about systemic issues at the end
+    # rather than just per-point.
+    session_brightness   = []
+    session_distance_mm  = []   # viewing distance from solvePnP — real geometry, not a guess
+    session_blink_skips  = 0
+    session_light_skips  = 0
+    points_with_low_yield = []
+
+    cam_matrix_ref = [None]
+    face_orientation_gate(face_mesh, cap, cam_matrix_ref)
+    if cam_matrix_ref[0] is not None:
+        cam_matrix = cam_matrix_ref[0]
+
+    cv2.namedWindow("Calibration", cv2.WINDOW_NORMAL)
+    cv2.setWindowProperty("Calibration", cv2.WND_PROP_FULLSCREEN, cv2.WINDOW_FULLSCREEN)
+
+    total = len(points)
+    print(f"Calibration started - {total} points")
+
+    for idx, (px, py) in enumerate(points):
+        sx, sy   = int(px * SCREEN_W), int(py * SCREEN_H)
+        duration = get_duration(py)
+
+        settle_s = 1.5 if idx == 0 else 0.4
+        settle_start = time.time()
+        while time.time() - settle_start < settle_s:
+            ret, frame = cap.read()
+            if not ret:
+                continue
+            screen = np.zeros((SCREEN_H, SCREEN_W, 3), dtype=np.uint8)
+            cv2.circle(screen, (sx, sy), 18, (80, 80, 80), -1)
+            msg = "Get ready..." if idx == 0 else "Settling..."
+            cv2.putText(screen, msg, (50, 50),
+                        cv2.FONT_HERSHEY_SIMPLEX, 1, (180, 180, 180), 2)
             cv2.imshow("Calibration", screen)
             cv2.waitKey(1)
-            continue
 
-        rgb     = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
-        results = face_mesh.process(rgb)
+        samples    = []
+        ear_list   = []
+        l_list     = []
+        r_list     = []
+        p_list     = []
+        hp_list    = []
+
+        point_blink_skips = 0
+        point_light_skips = 0
+
+        start = time.time()
+
+        while time.time() - start < duration:
+            ret, frame = cap.read()
+            if not ret:
+                continue
+
+            if cam_matrix is None:
+                cam_matrix = estimate_camera_matrix(frame.shape)
+
+            # LIVE LIGHTING CHECK — skip this frame and tell the person, instead
+            # of silently feeding a too-dark/too-bright frame into the model.
+            light_ok, light_msg = check_lighting(frame)
+            gray_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
+            session_brightness.append(float(np.mean(gray_frame)))
+            if not light_ok:
+                point_light_skips += 1
+                screen  = np.zeros((SCREEN_H, SCREEN_W, 3), dtype=np.uint8)
+                cv2.circle(screen, (sx, sy), 18, (0, 140, 255), 2)
+                cv2.putText(screen, f"Point {idx+1}/{total} - {light_msg}",
+                            (50, 50), cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 140, 255), 2)
+                cv2.imshow("Calibration", screen)
+                cv2.waitKey(1)
+                continue
+
+            rgb     = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+            results = face_mesh.process(rgb)
+
+            if not results.multi_face_landmarks:
+                continue
 
-        if not results.multi_face_landmarks:
-            continue
-
-        lms       = results.multi_face_landmarks[0].landmark
-        head_pose = estimate_head_pose(lms, frame.shape, cam_matrix)
-        if head_pose is None:
-            continue
-
-        # LIVE BLINK CHECK — average EAR across both eyes. Below threshold
-        # means eyes are closed/closing; that frame's eye patches carry no
-        # real gaze signal and would just add noise to this point's median.
-        ear_l = compute_ear(lms, LEFT_EAR_INDICES, frame.shape)
-        ear_r = compute_ear(lms, RIGHT_EAR_INDICES, frame.shape)
-        avg_ear = (ear_l + ear_r) / 2.0
-        if avg_ear < BLINK_EAR_THRESHOLD:
-            point_blink_skips += 1
+            lms       = results.multi_face_landmarks[0].landmark
+            head_pose = estimate_head_pose(lms, frame.shape, cam_matrix)
+            if head_pose is None:
+                continue
+
+            # LIVE BLINK CHECK — average EAR across both eyes. Below threshold
+            # means eyes are closed/closing; that frame's eye patches carry no
+            # real gaze signal and would just add noise to this point's median.
+            ear_l = compute_ear(lms, LEFT_EAR_INDICES, frame.shape)
+            ear_r = compute_ear(lms, RIGHT_EAR_INDICES, frame.shape)
+            avg_ear = (ear_l + ear_r) / 2.0
+            if avg_ear < BLINK_EAR_THRESHOLD:
+                point_blink_skips += 1
+                screen  = np.zeros((SCREEN_H, SCREEN_W, 3), dtype=np.uint8)
+                cv2.circle(screen, (sx, sy), 18, (180, 180, 0), 2)
+                cv2.putText(screen, f"Point {idx+1}/{total} - Blink detected, skipping frame",
+                            (50, 50), cv2.FONT_HERSHEY_SIMPLEX, 0.9, (180, 180, 0), 2)
+                cv2.imshow("Calibration", screen)
+                cv2.waitKey(1)
+                continue
+
+            # FIX A: normalize pose to [-1, +1] before CNN
+            pose_vec = normalize_pose(head_pose)
+
+            def process_eye(eye_idx, ear_idx, iris_idx):
+                s1 = step1_normalize(frame, lms, head_pose, eye_idx, ear_idx, iris_idx)
+                if not s1.is_open:
+                    return None
+                ir = compute_iris_radius(lms, iris_idx, frame.shape)
+                s2 = step2_illumination(s1, ir)
+                return s2.blended if s2.is_usable else None
+
+            l = process_eye(LEFT_EYE_INDICES,  LEFT_EAR_INDICES,  LEFT_IRIS_INDICES)
+            r = process_eye(RIGHT_EYE_INDICES, RIGHT_EAR_INDICES, RIGHT_IRIS_INDICES)
+
+            if l is None and r is None:
+                continue
+            if l is None: l = r
+            if r is None: r = l
+
+            _, _, raw_pitch, raw_yaw = pipeline.predict_gaze_vector(l, pose_vec, r)
+
+            pitch = compensate_pitch(raw_pitch, head_pose.pitch)
+            yaw   = compensate_yaw(raw_yaw, head_pose.yaw)
+
+            samples.append([pitch, yaw])
+            ear_list.append(avg_ear)
+            # solvePnP's tvec is in the same units as FACE_3D_MODEL (mm), so
+            # tvec[2] is a genuine measurement of how far your face is from the
+            # camera. We were computing this every frame and throwing it away.
+            try:
+                session_distance_mm.append(float(head_pose.tvec[2]))
+            except Exception:
+                pass
+            l_list.append(l)
+            r_list.append(r)
+            p_list.append(pose_vec)
+            hp_list.append(head_pose.pitch)
+
+            elapsed = time.time() - start
             screen  = np.zeros((SCREEN_H, SCREEN_W, 3), dtype=np.uint8)
-            cv2.circle(screen, (sx, sy), 18, (180, 180, 0), 2)
-            cv2.putText(screen, f"Point {idx+1}/{total} - Blink detected, skipping frame",
-                        (50, 50), cv2.FONT_HERSHEY_SIMPLEX, 0.9, (180, 180, 0), 2)
+            angle   = int(360 * elapsed / duration)
+            cv2.ellipse(screen, (sx, sy), (28, 28), -90, 0, angle, (0, 180, 0), 3)
+            cv2.circle(screen, (sx, sy), 18, (0, 255, 0), -1)
+            cv2.putText(screen, f"Point {idx+1}/{total} - Look at the dot",
+                        (50, 50), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
+            if point_blink_skips or point_light_skips:
+                cv2.putText(screen, f"skipped: {point_blink_skips} blink, {point_light_skips} lighting",
+                            (50, 85), cv2.FONT_HERSHEY_SIMPLEX, 0.55, (140, 140, 140), 1)
             cv2.imshow("Calibration", screen)
-            cv2.waitKey(1)
-            continue
-
-        # FIX A: normalize pose to [-1, +1] before CNN
-        pose_vec = normalize_pose(head_pose)
 
-        def process_eye(eye_idx, ear_idx, iris_idx):
-            s1 = step1_normalize(frame, lms, head_pose, eye_idx, ear_idx, iris_idx)
-            if not s1.is_open:
-                return None
-            ir = compute_iris_radius(lms, iris_idx, frame.shape)
-            s2 = step2_illumination(s1, ir)
-            return s2.blended if s2.is_usable else None
+            if cv2.waitKey(1) & 0xFF == 27:
+                break
 
-        l = process_eye(LEFT_EYE_INDICES,  LEFT_EAR_INDICES,  LEFT_IRIS_INDICES)
-        r = process_eye(RIGHT_EYE_INDICES, RIGHT_EAR_INDICES, RIGHT_IRIS_INDICES)
+        session_blink_skips += point_blink_skips
+        session_light_skips += point_light_skips
 
-        if l is None and r is None:
+        if not samples:
+            print(f"Point {idx+1}: no samples, skipping.")
+            points_with_low_yield.append(idx + 1)
             continue
-        if l is None: l = r
-        if r is None: r = l
-
-        _, _, raw_pitch, raw_yaw = pipeline.predict_gaze_vector(l, pose_vec, r)
-
-        pitch = compensate_pitch(raw_pitch, head_pose.pitch)
-        yaw   = compensate_yaw(raw_yaw, head_pose.yaw)
-
-        samples.append([pitch, yaw])
-        ear_list.append(avg_ear)
-        # solvePnP's tvec is in the same units as FACE_3D_MODEL (mm), so
-        # tvec[2] is a genuine measurement of how far your face is from the
-        # camera. We were computing this every frame and throwing it away.
-        try:
-            session_distance_mm.append(float(head_pose.tvec[2]))
-        except Exception:
-            pass
-        l_list.append(l)
-        r_list.append(r)
-        p_list.append(pose_vec)
-        hp_list.append(head_pose.pitch)
-
-        elapsed = time.time() - start
-        screen  = np.zeros((SCREEN_H, SCREEN_W, 3), dtype=np.uint8)
-        angle   = int(360 * elapsed / duration)
-        cv2.ellipse(screen, (sx, sy), (28, 28), -90, 0, angle, (0, 180, 0), 3)
-        cv2.circle(screen, (sx, sy), 18, (0, 255, 0), -1)
-        cv2.putText(screen, f"Point {idx+1}/{total} - Look at the dot",
-                    (50, 50), cv2.FONT_HERSHEY_SIMPLEX, 1, (255, 255, 255), 2)
-        if point_blink_skips or point_light_skips:
-            cv2.putText(screen, f"skipped: {point_blink_skips} blink, {point_light_skips} lighting",
-                        (50, 85), cv2.FONT_HERSHEY_SIMPLEX, 0.55, (140, 140, 140), 1)
-        cv2.imshow("Calibration", screen)
-
-        if cv2.waitKey(1) & 0xFF == 27:
-            break
-
-    session_blink_skips += point_blink_skips
-    session_light_skips += point_light_skips
-
-    if not samples:
-        print(f"Point {idx+1}: no samples, skipping.")
-        points_with_low_yield.append(idx + 1)
-        continue
-
-    if len(samples) < MIN_SAMPLES_OK:
-        print(f"  ⚠ Point {idx+1}: only {len(samples)} valid samples "
-              f"({point_blink_skips} blink-skipped, {point_light_skips} light-skipped) — may be unreliable")
-        points_with_low_yield.append(idx + 1)
-
-    samples_arr = np.array(samples)
-    avg         = np.median(samples_arr, axis=0)
-    avg_hp_deg  = float(np.median(hp_list))
-
-    # WITHIN-POINT DISPERSION = the noise floor. While you stared at ONE
-    # fixed dot, how much did the model's predicted pitch/yaw wobble
-    # frame-to-frame? This is the single most important number in the whole
-    # calibration and it was never being measured. Compare it against the
-    # BETWEEN-point spread (the actual signal) at the end of the run: if
-    # noise >= signal on an axis, that axis is unrecoverable by any
-    # calibration math, and no amount of RBF tuning will fix it.
-    # MAD (median absolute deviation) rather than std, so one blink-tail
-    # frame can't inflate it.
-    mad_pitch = float(np.median(np.abs(samples_arr[:, 0] - avg[0])))
-    mad_yaw   = float(np.median(np.abs(samples_arr[:, 1] - avg[1])))
-
-    gaze_vectors.append(list(avg))
-    screen_points.append([sx, sy])
-    head_pitches_deg.append(avg_hp_deg)
-    point_dispersion.append([mad_pitch, mad_yaw])
-    # Eye aperture for this point. Looking DOWN lowers the eyelid, so this is
-    # a physically independent vertical cue — and the CNN's pitch output has
-    # proven nearly blind vertically (r~0.41). calibrate() will measure both
-    # and pick whichever actually tracks screen-Y.
-    point_ear.append(float(np.median(ear_list)))
-
-    # Keep a BUNDLE of genuinely different frames for this point — not one
-    # "representative" frame. Both the fine-tune and the post-fine-tune RBF
-    # refit read from this bundle, so both get real frame diversity and real
-    # noise averaging instead of anchoring on a single arbitrary frame.
-    n_avail = len(l_list)
-    n_take  = min(FRAMES_KEPT_PER_POINT, n_avail)
-    indices = np.linspace(0, n_avail - 1, n_take, dtype=int)
-    point_frames.append({
-        "lefts":  [l_list[i]  for i in indices],
-        "rights": [r_list[i]  for i in indices],
-        "poses":  [p_list[i]  for i in indices],
-        "hps":    [hp_list[i] for i in indices],
-    })
-
-    print(f"Point {idx+1:2d}/{total} | pitch={avg[0]:+.4f} yaw={avg[1]:+.4f} "
-          f"| jitter(pitch)={mad_pitch:.4f} jitter(yaw)={mad_yaw:.4f} "
-          f"| {len(indices)} frames kept "
-          f"| skipped: {point_blink_skips} blink, {point_light_skips} lighting")
-
-cap.release()
-cv2.destroyAllWindows()
-
-if len(gaze_vectors) < 4:
-    print(f"ERROR: only {len(gaze_vectors)} points collected, need at least 4.")
-    exit(1)
 
-# =============================================================================
-# OUTLIER FILTER
-# =============================================================================
-(gaze_vectors, screen_points, head_pitches_deg,
- point_dispersion, point_frames, point_ear) = filter_unreliable_points(
-    gaze_vectors, screen_points, head_pitches_deg,
-    point_dispersion, point_frames, point_ear, factor=3.0
-)
+        if len(samples) < MIN_SAMPLES_OK:
+            print(f"  ⚠ Point {idx+1}: only {len(samples)} valid samples "
+                  f"({point_blink_skips} blink-skipped, {point_light_skips} light-skipped) — may be unreliable")
+            points_with_low_yield.append(idx + 1)
+
+        samples_arr = np.array(samples)
+        avg         = np.median(samples_arr, axis=0)
+        avg_hp_deg  = float(np.median(hp_list))
+
+        # WITHIN-POINT DISPERSION = the noise floor. While you stared at ONE
+        # fixed dot, how much did the model's predicted pitch/yaw wobble
+        # frame-to-frame? This is the single most important number in the whole
+        # calibration and it was never being measured. Compare it against the
+        # BETWEEN-point spread (the actual signal) at the end of the run: if
+        # noise >= signal on an axis, that axis is unrecoverable by any
+        # calibration math, and no amount of RBF tuning will fix it.
+        # MAD (median absolute deviation) rather than std, so one blink-tail
+        # frame can't inflate it.
+        mad_pitch = float(np.median(np.abs(samples_arr[:, 0] - avg[0])))
+        mad_yaw   = float(np.median(np.abs(samples_arr[:, 1] - avg[1])))
+
+        gaze_vectors.append(list(avg))
+        screen_points.append([sx, sy])
+        head_pitches_deg.append(avg_hp_deg)
+        point_dispersion.append([mad_pitch, mad_yaw])
+        # Eye aperture for this point. Looking DOWN lowers the eyelid, so this is
+        # a physically independent vertical cue — and the CNN's pitch output has
+        # proven nearly blind vertically (r~0.41). calibrate() will measure both
+        # and pick whichever actually tracks screen-Y.
+        point_ear.append(float(np.median(ear_list)))
+
+        # Keep a BUNDLE of genuinely different frames for this point — not one
+        # "representative" frame. Both the fine-tune and the post-fine-tune RBF
+        # refit read from this bundle, so both get real frame diversity and real
+        # noise averaging instead of anchoring on a single arbitrary frame.
+        n_avail = len(l_list)
+        n_take  = min(FRAMES_KEPT_PER_POINT, n_avail)
+        indices = np.linspace(0, n_avail - 1, n_take, dtype=int)
+        point_frames.append({
+            "lefts":  [l_list[i]  for i in indices],
+            "rights": [r_list[i]  for i in indices],
+            "poses":  [p_list[i]  for i in indices],
+            "hps":    [hp_list[i] for i in indices],
+        })
+
+        print(f"Point {idx+1:2d}/{total} | pitch={avg[0]:+.4f} yaw={avg[1]:+.4f} "
+              f"| jitter(pitch)={mad_pitch:.4f} jitter(yaw)={mad_yaw:.4f} "
+              f"| {len(indices)} frames kept "
+              f"| skipped: {point_blink_skips} blink, {point_light_skips} lighting")
+
+    cap.release()
+    cv2.destroyAllWindows()
+
+    if len(gaze_vectors) < 4:
+        print(f"ERROR: only {len(gaze_vectors)} points collected, need at least 4.")
+        exit(1)
+
+    # =============================================================================
+    # OUTLIER FILTER
+    # =============================================================================
+    (gaze_vectors, screen_points, head_pitches_deg,
+     point_dispersion, point_frames, point_ear) = filter_unreliable_points(
+        gaze_vectors, screen_points, head_pitches_deg,
+        point_dispersion, point_frames, point_ear, factor=3.0
+    )
 
-n_pts = len(screen_points)
-if n_pts < 4:
-    print("ERROR: too many points removed, need at least 4 reliable points.")
-    exit(1)
+    n_pts = len(screen_points)
+    if n_pts < 4:
+        print("ERROR: too many points removed, need at least 4 reliable points.")
+        exit(1)
+
+    # =============================================================================
+    # FINE-TUNE (optional — see FINETUNE_ENABLED comment for why it defaults OFF)
+    # Now fed the REAL diverse frames from each point's bundle. Previously this
+    # received the same single frame duplicated 5x per point, so it trained on
+    # 16 unique images while reporting 80.
+    # =============================================================================
+    finetuned = False
+    if FINETUNE_ENABLED:
+        ft_lefts, ft_rights, ft_poses, ft_sp = [], [], [], []
+        for i in range(n_pts):
+            pf = point_frames[i]
+            for k in range(len(pf["lefts"])):
+                ft_lefts.append(pf["lefts"][k])
+                ft_rights.append(pf["rights"][k])
+                ft_poses.append(pf["poses"][k])
+                ft_sp.append(screen_points[i])
+
+        n_unique = len(ft_lefts)
+
+        # Derive the fine-tune target geometry from REAL numbers instead of the
+        # fabricated 0.6/0.4 constants.
+        _diag_mm  = SCREEN_DIAGONAL_INCHES * 25.4
+        _aspect   = SCREEN_W / float(SCREEN_H)
+        _scr_h_mm = _diag_mm / np.sqrt(_aspect ** 2 + 1.0)
+        _scr_w_mm = _aspect * _scr_h_mm
+        if session_distance_mm:
+            _dist_mm = float(np.median(session_distance_mm))
+        else:
+            _dist_mm = 500.0
+        # Guard against a wild solvePnP outlier producing nonsense geometry.
+        _dist_mm = float(np.clip(_dist_mm, 300.0, 900.0))
 
-# =============================================================================
-# FINE-TUNE (optional — see FINETUNE_ENABLED comment for why it defaults OFF)
-# Now fed the REAL diverse frames from each point's bundle. Previously this
-# received the same single frame duplicated 5x per point, so it trained on
-# 16 unique images while reporting 80.
-# =============================================================================
-finetuned = False
-if FINETUNE_ENABLED:
-    ft_lefts, ft_rights, ft_poses, ft_sp = [], [], [], []
+        if USE_MEASURED_GEOMETRY:
+            K_H = (_scr_w_mm / 2.0) / _dist_mm
+            K_V = (_scr_h_mm / 2.0) / _dist_mm
+        else:
+            K_H, K_V = 0.6, 0.4   # original constants — currently working
+
+        print(f"\n--- Fine-tuning CNN on your eyes ({n_unique} REAL frames, "
+              f"{n_pts} points) ---")
+        print(f"[Geometry] screen {SCREEN_DIAGONAL_INCHES}\" -> "
+              f"{_scr_w_mm:.0f}x{_scr_h_mm:.0f}mm | measured viewing distance "
+              f"{_dist_mm:.0f}mm")
+        print(f"[Geometry] fine-tune targets: k_h={K_H:.3f}  k_v={K_V:.3f}  "
+              f"(ratio {K_H/max(K_V,1e-6):.2f})  "
+              f"[{'measured' if USE_MEASURED_GEOMETRY else 'original constants'}]")
+        finetuned = finetune_on_calibration_v4(
+            onnx_path     = ONNX_PATH,
+            left_patches  = ft_lefts,
+            right_patches = ft_rights,
+            head_poses    = ft_poses,
+            screen_points = ft_sp,
+            screen_w      = SCREEN_W,
+            screen_h      = SCREEN_H,
+            ckpt_path     = CKPT_PATH,
+            out_onnx_path = ONNX_PATH,
+            steps         = 200,
+            lr            = 1e-4,
+            k_h           = K_H,
+            k_v           = K_V,
+        )
+    else:
+        print("\n--- Fine-tuning SKIPPED (FINETUNE_ENABLED = False) ---")
+        print("    Using the base model as-is. The RBF maps its output to screen")
+        print("    coordinates, so the model's absolute scale does not need to be")
+        print("    'correct' — only monotonic. See the FINETUNE_ENABLED comment.")
+
+    # =============================================================================
+    # FIT RBF CALIBRATION
+    #
+    # CRITICAL FIX: re-predict across EVERY kept frame for each point and take the
+    # MEDIAN, instead of predicting from one arbitrary "representative" frame.
+    #
+    # The old code computed a careful median over 50-150 frames during collection,
+    # then threw it away and refit the RBF from a single frame per point. That
+    # discarded all noise averaging and anchored the entire calibration on 16
+    # single, possibly-noisy frames — which is exactly the kind of thing that
+    # makes edges and corners unstable.
+    # =============================================================================
+    print("\n--- Fitting RBF calibration ---")
+    pipeline = InsightUXPipeline(ONNX_PATH)
+
+    adapted_gaze_vectors = []
+    adapted_dispersion   = []
     for i in range(n_pts):
         pf = point_frames[i]
+        per_frame = []
         for k in range(len(pf["lefts"])):
-            ft_lefts.append(pf["lefts"][k])
-            ft_rights.append(pf["rights"][k])
-            ft_poses.append(pf["poses"][k])
-            ft_sp.append(screen_points[i])
-
-    n_unique = len(ft_lefts)
-
-    # Derive the fine-tune target geometry from REAL numbers instead of the
-    # fabricated 0.6/0.4 constants.
-    _diag_mm  = SCREEN_DIAGONAL_INCHES * 25.4
-    _aspect   = SCREEN_W / float(SCREEN_H)
-    _scr_h_mm = _diag_mm / np.sqrt(_aspect ** 2 + 1.0)
-    _scr_w_mm = _aspect * _scr_h_mm
-    if session_distance_mm:
-        _dist_mm = float(np.median(session_distance_mm))
+            l    = pf["lefts"][k]
+            r    = pf["rights"][k]
+            pose = pf["poses"][k]
+            hp   = pf["hps"][k]
+            hy   = float(pose[1]) * POSE_NORM_SCALE   # recover raw head yaw (deg)
+
+            _, _, raw_pitch, raw_yaw = pipeline.predict_gaze_vector(l, pose, r)
+            pitch = compensate_pitch(raw_pitch, hp)
+            yaw   = compensate_yaw(raw_yaw, hy)
+            per_frame.append([pitch, yaw])
+
+        per_frame = np.array(per_frame)
+        med = np.median(per_frame, axis=0)
+        adapted_gaze_vectors.append(list(med))
+        adapted_dispersion.append([
+            float(np.median(np.abs(per_frame[:, 0] - med[0]))),
+            float(np.median(np.abs(per_frame[:, 1] - med[1]))),
+        ])
+
+    assert len(adapted_gaze_vectors) == len(screen_points), \
+        f"Length mismatch: {len(adapted_gaze_vectors)} gaze vs {len(screen_points)} screen"
+
+    pipeline.calibration.calibrate(
+        np.array(adapted_gaze_vectors),
+        np.array(screen_points),
+        ear=np.array(point_ear),
+        screen_size=(SCREEN_W, SCREEN_H)   # <-- fixes the 1493x933 clamp bug
+    )
+    pipeline.calibration.save(os.path.join(DATA_DIR, "calibration.pkl"))
+
+    import pickle
+    _all_hp   = [hp for pf in point_frames for hp in pf["hps"]]
+    _all_pose = [p  for pf in point_frames for p  in pf["poses"]]
+    baseline_pitch = float(np.median(_all_hp)) if _all_hp else 0.0
+    baseline_yaw = float(np.median([float(p[1]) * POSE_NORM_SCALE for p in _all_pose])) if _all_pose else 0.0
+    baseline_roll = float(np.median([float(p[2]) * POSE_NORM_SCALE for p in _all_pose])) if _all_pose else 0.0
+    with open(os.path.join(DATA_DIR, "baseline_pose.pkl"), "wb") as f:
+        pickle.dump({"pitch": baseline_pitch, "yaw": baseline_yaw, "roll": baseline_roll}, f)
+    print(f"Saved baseline_pose.pkl: pitch={baseline_pitch:+.2f}, yaw={baseline_yaw:+.2f}, roll={baseline_roll:+.2f}")
+
+    print(f"\nCalibration complete! {n_pts}/{total} points used.")
+    if finetuned:
+        print("CNN fine-tuned on your eyes + RBF calibration fitted.")
     else:
-        _dist_mm = 500.0
-    # Guard against a wild solvePnP outlier producing nonsense geometry.
-    _dist_mm = float(np.clip(_dist_mm, 300.0, 900.0))
-
-    if USE_MEASURED_GEOMETRY:
-        K_H = (_scr_w_mm / 2.0) / _dist_mm
-        K_V = (_scr_h_mm / 2.0) / _dist_mm
+        print("RBF calibration fitted (CNN fine-tuning skipped).")
+
+    # =============================================================================
+    # SESSION DIAGNOSTIC SUMMARY — the "tell the person if something's off" ask.
+    # Printed once, in plain language, instead of them having to interpret
+    # per-point numbers themselves.
+    # =============================================================================
+    # =============================================================================
+    # SIGNAL-TO-NOISE — THE VERDICT
+    #
+    # This is the number that decides whether an axis is fixable at all.
+    #
+    #   SIGNAL = how much the model's output changes between DIFFERENT screen
+    #            positions (spread of the per-point medians). This is the real
+    #            information the RBF has to work with.
+    #   NOISE  = how much the model's output wobbles frame-to-frame while you
+    #            stare at ONE fixed dot (median within-point jitter).
+    #
+    # If NOISE >= SIGNAL on an axis, the model cannot tell "you looked lower"
+    # apart from "the same look, one frame later". No RBF, no gain correction,
+    # no clamp tuning can recover information that was never there. That axis
+    # needs a better MODEL, not better calibration math.
+    # =============================================================================
+    gv_arr = np.array(adapted_gaze_vectors)
+    disp_arr = np.array(adapted_dispersion)
+    sp_arr = np.array(screen_points)
+
+    signal_pitch = float(np.std(gv_arr[:, 0]))
+    signal_yaw   = float(np.std(gv_arr[:, 1]))
+    noise_pitch  = float(np.median(disp_arr[:, 0]))
+    noise_yaw    = float(np.median(disp_arr[:, 1]))
+
+    snr_pitch = signal_pitch / noise_pitch if noise_pitch > 1e-9 else float("inf")
+    snr_yaw   = signal_yaw   / noise_yaw   if noise_yaw   > 1e-9 else float("inf")
+
+    # CORRELATION — the metric that actually decides usability.
+    #
+    # An earlier version of this block reported only SNR (spread vs jitter). That
+    # was MISLEADING and nearly sent us chasing the wrong fix: a signal can have
+    # plenty of spread and still be useless if that spread is not ORDERED by the
+    # thing you're predicting. Pitch once reported SNR 1.76 ("marginal") while its
+    # per-row averages went down, up, up — i.e. no monotonic relationship with
+    # screen row at all. Spread was real; ordering was not.
+    #
+    # Pearson r between model output and true screen coordinate is the honest
+    # test. r near +/-1 means the model tracks that axis. r near 0 means it does
+    # not, no matter how much spread there is.
+    def _pearson(a, b):
+        a = np.asarray(a, dtype=float); b = np.asarray(b, dtype=float)
+        if a.std() < 1e-12 or b.std() < 1e-12:
+            return 0.0
+        return float(np.corrcoef(a, b)[0, 1])
+
+    r_yaw   = _pearson(gv_arr[:, 1], sp_arr[:, 0])   # yaw   vs screen X
+    r_pitch = _pearson(gv_arr[:, 0], sp_arr[:, 1])   # pitch vs screen Y
+    r_ear   = _pearson(np.array(point_ear), sp_arr[:, 1])   # eye aperture vs screen Y
+
+    def _corr_verdict(r):
+        ar = abs(r)
+        if ar >= 0.90:
+            return "EXCELLENT — model tracks this axis cleanly"
+        if ar >= 0.70:
+            return "GOOD — usable, some slop"
+        if ar >= 0.50:
+            return "WEAK — expect significant error on this axis"
+        return "BROKEN — model output barely relates to this axis at all"
+
+    print("\n========== DOES THE MODEL TRACK THE SCREEN? (the real test) ==========")
+    print(f"HORIZONTAL  yaw vs screen-X : r = {r_yaw:+.3f}   (SNR {snr_yaw:.2f})")
+    print(f"                             -> {_corr_verdict(r_yaw)}")
+    print(f"VERTICAL    pitch vs screen-Y: r = {r_pitch:+.3f}   (SNR {snr_pitch:.2f})")
+    print(f"                             -> {_corr_verdict(r_pitch)}")
+    print(f"VERTICAL    EYE APERTURE vs screen-Y: r = {r_ear:+.3f}")
+    print(f"                             -> {_corr_verdict(r_ear)}")
+    print()
+    _best_vert = max(abs(r_pitch), abs(r_ear))
+    print(f"Best available vertical cue: "
+          f"{'EYE APERTURE' if abs(r_ear) > abs(r_pitch) else 'CNN PITCH'} "
+          f"(r={_best_vert:+.3f})")
+    print()
+    if _best_vert < 0.5:
+        print("VERDICT: the model's PITCH output does not meaningfully track where you")
+        print("look vertically. This is NOT a calibration problem — the RBF cannot map")
+        print("an input that carries no ordered information about screen height. No")
+        print("amount of clamp/smoothing/gain tuning will fix it. The fix is the MODEL:")
+        print("its pitch head needs retraining, or vertical gaze needs a different")
+        print("feature (e.g. eyelid aperture / iris-centre offset within the socket),")
+        print("which the current eye-patch CNN is evidently not learning.")
+    elif _best_vert < abs(r_yaw) - 0.15:
+        print("VERDICT: vertical tracks the screen, but noticeably worse than")
+        print("horizontal. Calibration is doing its job; expect up/down to stay the")
+        print("looser axis until the model improves.")
     else:
-        K_H, K_V = 0.6, 0.4   # original constants — currently working
-
-    print(f"\n--- Fine-tuning CNN on your eyes ({n_unique} REAL frames, "
-          f"{n_pts} points) ---")
-    print(f"[Geometry] screen {SCREEN_DIAGONAL_INCHES}\" -> "
-          f"{_scr_w_mm:.0f}x{_scr_h_mm:.0f}mm | measured viewing distance "
-          f"{_dist_mm:.0f}mm")
-    print(f"[Geometry] fine-tune targets: k_h={K_H:.3f}  k_v={K_V:.3f}  "
-          f"(ratio {K_H/max(K_V,1e-6):.2f})  "
-          f"[{'measured' if USE_MEASURED_GEOMETRY else 'original constants'}]")
-    finetuned = finetune_on_calibration_v4(
-        onnx_path     = ONNX_PATH,
-        left_patches  = ft_lefts,
-        right_patches = ft_rights,
-        head_poses    = ft_poses,
-        screen_points = ft_sp,
-        screen_w      = SCREEN_W,
-        screen_h      = SCREEN_H,
-        ckpt_path     = CKPT_PATH,
-        out_onnx_path = ONNX_PATH,
-        steps         = 200,
-        lr            = 1e-4,
-        k_h           = K_H,
-        k_v           = K_V,
-    )
-else:
-    print("\n--- Fine-tuning SKIPPED (FINETUNE_ENABLED = False) ---")
-    print("    Using the base model as-is. The RBF maps its output to screen")
-    print("    coordinates, so the model's absolute scale does not need to be")
-    print("    'correct' — only monotonic. See the FINETUNE_ENABLED comment.")
-
-# =============================================================================
-# FIT RBF CALIBRATION
-#
-# CRITICAL FIX: re-predict across EVERY kept frame for each point and take the
-# MEDIAN, instead of predicting from one arbitrary "representative" frame.
-#
-# The old code computed a careful median over 50-150 frames during collection,
-# then threw it away and refit the RBF from a single frame per point. That
-# discarded all noise averaging and anchored the entire calibration on 16
-# single, possibly-noisy frames — which is exactly the kind of thing that
-# makes edges and corners unstable.
-# =============================================================================
-print("\n--- Fitting RBF calibration ---")
-pipeline = InsightUXPipeline(ONNX_PATH)
-
-adapted_gaze_vectors = []
-adapted_dispersion   = []
-for i in range(n_pts):
-    pf = point_frames[i]
-    per_frame = []
-    for k in range(len(pf["lefts"])):
-        l    = pf["lefts"][k]
-        r    = pf["rights"][k]
-        pose = pf["poses"][k]
-        hp   = pf["hps"][k]
-        hy   = float(pose[1]) * POSE_NORM_SCALE   # recover raw head yaw (deg)
-
-        _, _, raw_pitch, raw_yaw = pipeline.predict_gaze_vector(l, pose, r)
-        pitch = compensate_pitch(raw_pitch, hp)
-        yaw   = compensate_yaw(raw_yaw, hy)
-        per_frame.append([pitch, yaw])
-
-    per_frame = np.array(per_frame)
-    med = np.median(per_frame, axis=0)
-    adapted_gaze_vectors.append(list(med))
-    adapted_dispersion.append([
-        float(np.median(np.abs(per_frame[:, 0] - med[0]))),
-        float(np.median(np.abs(per_frame[:, 1] - med[1]))),
-    ])
-
-assert len(adapted_gaze_vectors) == len(screen_points), \
-    f"Length mismatch: {len(adapted_gaze_vectors)} gaze vs {len(screen_points)} screen"
-
-pipeline.calibration.calibrate(
-    np.array(adapted_gaze_vectors),
-    np.array(screen_points),
-    ear=np.array(point_ear),
-    screen_size=(SCREEN_W, SCREEN_H)   # <-- fixes the 1493x933 clamp bug
-)
-pipeline.calibration.save("calibration.pkl")
-
-import pickle
-_all_hp   = [hp for pf in point_frames for hp in pf["hps"]]
-_all_pose = [p  for pf in point_frames for p  in pf["poses"]]
-baseline_pitch = float(np.median(_all_hp)) if _all_hp else 0.0
-baseline_yaw = float(np.median([float(p[1]) * POSE_NORM_SCALE for p in _all_pose])) if _all_pose else 0.0
-baseline_roll = float(np.median([float(p[2]) * POSE_NORM_SCALE for p in _all_pose])) if _all_pose else 0.0
-with open("baseline_pose.pkl", "wb") as f:
-    pickle.dump({"pitch": baseline_pitch, "yaw": baseline_yaw, "roll": baseline_roll}, f)
-print(f"Saved baseline_pose.pkl: pitch={baseline_pitch:+.2f}, yaw={baseline_yaw:+.2f}, roll={baseline_roll:+.2f}")
-
-print(f"\nCalibration complete! {n_pts}/{total} points used.")
-if finetuned:
-    print("CNN fine-tuned on your eyes + RBF calibration fitted.")
-else:
-    print("RBF calibration fitted (CNN fine-tuning skipped).")
-
-# =============================================================================
-# SESSION DIAGNOSTIC SUMMARY — the "tell the person if something's off" ask.
-# Printed once, in plain language, instead of them having to interpret
-# per-point numbers themselves.
-# =============================================================================
-# =============================================================================
-# SIGNAL-TO-NOISE — THE VERDICT
-#
-# This is the number that decides whether an axis is fixable at all.
-#
-#   SIGNAL = how much the model's output changes between DIFFERENT screen
-#            positions (spread of the per-point medians). This is the real
-#            information the RBF has to work with.
-#   NOISE  = how much the model's output wobbles frame-to-frame while you
-#            stare at ONE fixed dot (median within-point jitter).
-#
-# If NOISE >= SIGNAL on an axis, the model cannot tell "you looked lower"
-# apart from "the same look, one frame later". No RBF, no gain correction,
-# no clamp tuning can recover information that was never there. That axis
-# needs a better MODEL, not better calibration math.
-# =============================================================================
-gv_arr = np.array(adapted_gaze_vectors)
-disp_arr = np.array(adapted_dispersion)
-sp_arr = np.array(screen_points)
-
-signal_pitch = float(np.std(gv_arr[:, 0]))
-signal_yaw   = float(np.std(gv_arr[:, 1]))
-noise_pitch  = float(np.median(disp_arr[:, 0]))
-noise_yaw    = float(np.median(disp_arr[:, 1]))
-
-snr_pitch = signal_pitch / noise_pitch if noise_pitch > 1e-9 else float("inf")
-snr_yaw   = signal_yaw   / noise_yaw   if noise_yaw   > 1e-9 else float("inf")
-
-# CORRELATION — the metric that actually decides usability.
-#
-# An earlier version of this block reported only SNR (spread vs jitter). That
-# was MISLEADING and nearly sent us chasing the wrong fix: a signal can have
-# plenty of spread and still be useless if that spread is not ORDERED by the
-# thing you're predicting. Pitch once reported SNR 1.76 ("marginal") while its
-# per-row averages went down, up, up — i.e. no monotonic relationship with
-# screen row at all. Spread was real; ordering was not.
-#
-# Pearson r between model output and true screen coordinate is the honest
-# test. r near +/-1 means the model tracks that axis. r near 0 means it does
-# not, no matter how much spread there is.
-def _pearson(a, b):
-    a = np.asarray(a, dtype=float); b = np.asarray(b, dtype=float)
-    if a.std() < 1e-12 or b.std() < 1e-12:
-        return 0.0
-    return float(np.corrcoef(a, b)[0, 1])
-
-r_yaw   = _pearson(gv_arr[:, 1], sp_arr[:, 0])   # yaw   vs screen X
-r_pitch = _pearson(gv_arr[:, 0], sp_arr[:, 1])   # pitch vs screen Y
-r_ear   = _pearson(np.array(point_ear), sp_arr[:, 1])   # eye aperture vs screen Y
-
-def _corr_verdict(r):
-    ar = abs(r)
-    if ar >= 0.90:
-        return "EXCELLENT — model tracks this axis cleanly"
-    if ar >= 0.70:
-        return "GOOD — usable, some slop"
-    if ar >= 0.50:
-        return "WEAK — expect significant error on this axis"
-    return "BROKEN — model output barely relates to this axis at all"
-
-print("\n========== DOES THE MODEL TRACK THE SCREEN? (the real test) ==========")
-print(f"HORIZONTAL  yaw vs screen-X : r = {r_yaw:+.3f}   (SNR {snr_yaw:.2f})")
-print(f"                             -> {_corr_verdict(r_yaw)}")
-print(f"VERTICAL    pitch vs screen-Y: r = {r_pitch:+.3f}   (SNR {snr_pitch:.2f})")
-print(f"                             -> {_corr_verdict(r_pitch)}")
-print(f"VERTICAL    EYE APERTURE vs screen-Y: r = {r_ear:+.3f}")
-print(f"                             -> {_corr_verdict(r_ear)}")
-print()
-_best_vert = max(abs(r_pitch), abs(r_ear))
-print(f"Best available vertical cue: "
-      f"{'EYE APERTURE' if abs(r_ear) > abs(r_pitch) else 'CNN PITCH'} "
-      f"(r={_best_vert:+.3f})")
-print()
-if _best_vert < 0.5:
-    print("VERDICT: the model's PITCH output does not meaningfully track where you")
-    print("look vertically. This is NOT a calibration problem — the RBF cannot map")
-    print("an input that carries no ordered information about screen height. No")
-    print("amount of clamp/smoothing/gain tuning will fix it. The fix is the MODEL:")
-    print("its pitch head needs retraining, or vertical gaze needs a different")
-    print("feature (e.g. eyelid aperture / iris-centre offset within the socket),")
-    print("which the current eye-patch CNN is evidently not learning.")
-elif _best_vert < abs(r_yaw) - 0.15:
-    print("VERDICT: vertical tracks the screen, but noticeably worse than")
-    print("horizontal. Calibration is doing its job; expect up/down to stay the")
-    print("looser axis until the model improves.")
-else:
-    print("VERDICT: both axes track the screen. Any remaining error is in the")
-    print("calibration mapping or the noise floor, not in the model's ability")
-    print("to see where you're looking.")
-print("=====================================================================")
-
-print("\n================ CALIBRATION QUALITY SUMMARY ================")
-if session_brightness:
-    avg_bright = float(np.mean(session_brightness))
-    pct_dark  = 100 * sum(1 for b in session_brightness if b < LIGHT_MIN_BRIGHTNESS) / len(session_brightness)
-    pct_bright = 100 * sum(1 for b in session_brightness if b > LIGHT_MAX_BRIGHTNESS) / len(session_brightness)
-    print(f"Average brightness: {avg_bright:.0f} (comfortable range: {LIGHT_MIN_BRIGHTNESS}-{LIGHT_MAX_BRIGHTNESS})")
-    if pct_dark > 10:
-        print(f"⚠ Lighting was too DARK for {pct_dark:.0f}% of frames. "
-              f"Add a light source facing your face, or face a window, before recalibrating.")
-    if pct_bright > 10:
-        print(f"⚠ Lighting was too BRIGHT for {pct_bright:.0f}% of frames "
-              f"(backlight or a light directly behind you?). Try facing away from strong light sources.")
-    if pct_dark <= 10 and pct_bright <= 10:
-        print("Lighting was consistently good throughout.")
-
-if session_blink_skips > 0:
-    print(f"Blinking accounted for {session_blink_skips} skipped frames across the session "
-          f"— normal, this is expected and was handled automatically.")
-
-if points_with_low_yield:
-    print(f"⚠ These points had low sample counts and may be less accurate: "
-          f"{', '.join(str(p) for p in points_with_low_yield)}. "
-          f"If tracking feels off in that part of the screen, consider recalibrating.")
-else:
-    print("All points collected a healthy number of samples.")
-print("===============================================================")
-
-# --- Diagnostic: verify vertical pitch separation ---
-print("\n--- Pitch by screen row (should increase top -> bottom) ---")
-gv_arr = np.array(adapted_gaze_vectors)
-sp_arr = np.array(screen_points)
-thresholds = [(0,          SCREEN_H*0.25, "Top    (y<25%)  "),
-              (SCREEN_H*0.25, SCREEN_H*0.5,  "Mid-hi (25-50%) "),
-              (SCREEN_H*0.5,  SCREEN_H*0.75, "Mid-lo (50-75%) "),
-              (SCREEN_H*0.75, SCREEN_H+1,    "Bottom (y>75%)  ")]
-for lo, hi, label in thresholds:
-    mask = (sp_arr[:, 1] >= lo) & (sp_arr[:, 1] < hi)
-    if mask.any():
-        print(f"  {label}: avg pitch = {gv_arr[mask, 0].mean():.4f}")
-
-print("\n--- Yaw by screen column (should increase left -> right) ---")
-col_thresholds = [(0,            SCREEN_W*0.25, "Left   (x<25%)  "),
-                   (SCREEN_W*0.25, SCREEN_W*0.5,  "Mid-lf (25-50%) "),
-                   (SCREEN_W*0.5,  SCREEN_W*0.75, "Mid-rt (50-75%) "),
-                   (SCREEN_W*0.75, SCREEN_W+1,    "Right  (x>75%)  ")]
-for lo, hi, label in col_thresholds:
-    mask = (sp_arr[:, 0] >= lo) & (sp_arr[:, 0] < hi)
-    if mask.any():
-        print(f"  {label}: avg yaw = {gv_arr[mask, 1].mean():.4f}")
+        print("VERDICT: both axes track the screen. Any remaining error is in the")
+        print("calibration mapping or the noise floor, not in the model's ability")
+        print("to see where you're looking.")
+    print("=====================================================================")
+
+    print("\n================ CALIBRATION QUALITY SUMMARY ================")
+    if session_brightness:
+        avg_bright = float(np.mean(session_brightness))
+        pct_dark  = 100 * sum(1 for b in session_brightness if b < LIGHT_MIN_BRIGHTNESS) / len(session_brightness)
+        pct_bright = 100 * sum(1 for b in session_brightness if b > LIGHT_MAX_BRIGHTNESS) / len(session_brightness)
+        print(f"Average brightness: {avg_bright:.0f} (comfortable range: {LIGHT_MIN_BRIGHTNESS}-{LIGHT_MAX_BRIGHTNESS})")
+        if pct_dark > 10:
+            print(f"⚠ Lighting was too DARK for {pct_dark:.0f}% of frames. "
+                  f"Add a light source facing your face, or face a window, before recalibrating.")
+        if pct_bright > 10:
+            print(f"⚠ Lighting was too BRIGHT for {pct_bright:.0f}% of frames "
+                  f"(backlight or a light directly behind you?). Try facing away from strong light sources.")
+        if pct_dark <= 10 and pct_bright <= 10:
+            print("Lighting was consistently good throughout.")
+
+    if session_blink_skips > 0:
+        print(f"Blinking accounted for {session_blink_skips} skipped frames across the session "
+              f"— normal, this is expected and was handled automatically.")
+
+    if points_with_low_yield:
+        print(f"⚠ These points had low sample counts and may be less accurate: "
+              f"{', '.join(str(p) for p in points_with_low_yield)}. "
+              f"If tracking feels off in that part of the screen, consider recalibrating.")
+    else:
+        print("All points collected a healthy number of samples.")
+    print("===============================================================")
+
+    # --- Diagnostic: verify vertical pitch separation ---
+    print("\n--- Pitch by screen row (should increase top -> bottom) ---")
+    gv_arr = np.array(adapted_gaze_vectors)
+    sp_arr = np.array(screen_points)
+    thresholds = [(0,          SCREEN_H*0.25, "Top    (y<25%)  "),
+                  (SCREEN_H*0.25, SCREEN_H*0.5,  "Mid-hi (25-50%) "),
+                  (SCREEN_H*0.5,  SCREEN_H*0.75, "Mid-lo (50-75%) "),
+                  (SCREEN_H*0.75, SCREEN_H+1,    "Bottom (y>75%)  ")]
+    for lo, hi, label in thresholds:
+        mask = (sp_arr[:, 1] >= lo) & (sp_arr[:, 1] < hi)
+        if mask.any():
+            print(f"  {label}: avg pitch = {gv_arr[mask, 0].mean():.4f}")
+
+    print("\n--- Yaw by screen column (should increase left -> right) ---")
+    col_thresholds = [(0,            SCREEN_W*0.25, "Left   (x<25%)  "),
+                       (SCREEN_W*0.25, SCREEN_W*0.5,  "Mid-lf (25-50%) "),
+                       (SCREEN_W*0.5,  SCREEN_W*0.75, "Mid-rt (50-75%) "),
+                       (SCREEN_W*0.75, SCREEN_W+1,    "Right  (x>75%)  ")]
+    for lo, hi, label in col_thresholds:
+        mask = (sp_arr[:, 0] >= lo) & (sp_arr[:, 0] < hi)
+        if mask.any():
+            print(f"  {label}: avg yaw = {gv_arr[mask, 1].mean():.4f}")
+
+
+if __name__ == "__main__":
+    main()

packaging/InsightUX.spec

@@ -0,0 +1,131 @@
+# -*- mode: python ; coding: utf-8 -*-
+#
+# InsightUX PyInstaller build spec — onedir, not onefile.
+#
+# Onefile re-extracts the whole bundle (torch alone is ~1.2GB) to a temp
+# directory on EVERY launch, which is a bad startup-time tradeoff on top of
+# an already-heavy ML stack. Onedir installs once as a persistent folder
+# (InsightUX.exe + _internal/), which is also just what installer.iss wants
+# to package anyway.
+#
+# Build (from the repo root, inside the project venv — this project's venv
+# uses Python 3.10, which is the proven-working interpreter; PyInstaller
+# must be installed into that same venv first: `pip install pyinstaller`):
+#     pyinstaller packaging/InsightUX.spec --noconfirm
+#
+# Output lands in dist/InsightUX/ — that whole folder is what
+# packaging/installer.iss packages into the installer.
+#
+# Known risk areas likely to need iteration on the FIRST real build (this is
+# normal for this dependency stack, not a sign anything here is wrong):
+#   - mediapipe ships its own .tflite/.binarypb data files as package data;
+#     collect_all() below should catch them, but if face_mesh fails to load
+#     at runtime with a "file not found", that's the first place to check.
+#   - onnxruntime/torch/torchvision ship native DLLs; "DLL load failed" at
+#     startup means collect_all() missed one — check dist/InsightUX/_internal
+#     for what's actually present vs. what the traceback wants.
+#   - pywebview + pythonnet's `clr` bridge needs the Microsoft Edge WebView2
+#     Runtime on the TARGET machine. Usually preinstalled on modern Windows
+#     10/11, but installer.iss bundles + silently runs Microsoft's WebView2
+#     bootstrapper as a safety net for older/locked-down machines.
+
+import os
+import dis
+from PyInstaller.utils.hooks import collect_all
+import PyInstaller.lib.modulegraph.util as _mg_util
+
+# A handful of very large single-file modules in this dependency tree
+# (bottle.py, matplotlib/pyplot.py, and possibly others not yet hit) trip a
+# real dis.get_instructions() bug on this Python 3.10.0 build — an IndexError
+# walking co_consts for certain EXTENDED_ARG-heavy bytecode in big modules.
+# Confirmed this is purely a build-time INTROSPECTION bug, not a real problem:
+# `import bottle` / `import matplotlib.pyplot` both work completely normally
+# at actual runtime; only PyInstaller's static bytecode scan of them (used to
+# discover further hidden imports) crashes.
+#
+# Patched once here instead of excluding modules one at a time as each is
+# discovered (there's no way to know in advance how many more of these exist
+# inside torch's ~1.2GB of dependencies). Worst case if this ever masks a
+# real import PyInstaller would otherwise have auto-discovered: the
+# hiddenimports/collect_all() list below already covers every package this
+# app actually needs bundled, so a skipped scan on one giant module isn't
+# depended on for correctness.
+_orig_iterate_instructions = _mg_util.iterate_instructions
+
+def _safe_iterate_instructions(code_object):
+    try:
+        yield from _orig_iterate_instructions(code_object)
+    except Exception as e:
+        print(f"[InsightUX.spec] bytecode scan skipped on a module "
+              f"(dis bug workaround): {type(e).__name__}: {e}")
+        return
+
+_mg_util.iterate_instructions = _safe_iterate_instructions
+
+PACKAGING_DIR = os.path.abspath(os.path.dirname(os.path.abspath(SPEC)))
+REPO_ROOT = os.path.dirname(PACKAGING_DIR)
+
+datas = [
+    (os.path.join(REPO_ROOT, "models", "gaze_cnn_v4.onnx"), "models"),
+    (os.path.join(REPO_ROOT, "models", "gaze_cnn_v4.onnx.data"), "models"),
+    (os.path.join(REPO_ROOT, "checkpoints", "best_model_v4.pt"), "checkpoints"),
+]
+binaries = []
+# models.model_v4 is only reached via a try/except-guarded dynamic import
+# inside calibrate.py's fine-tune function — spell it out explicitly rather
+# than trust static analysis to follow it through the try/except.
+hiddenimports = ["models.model_v4"]
+
+# The blunt-but-reliable safety net for packages that ship native binaries
+# and/or non-.py package data PyInstaller's built-in hooks don't fully catch.
+for pkg in ("mediapipe", "onnxruntime", "torch", "torchvision", "cv2"):
+    pkg_datas, pkg_binaries, pkg_hiddenimports = collect_all(pkg)
+    datas += pkg_datas
+    binaries += pkg_binaries
+    hiddenimports += pkg_hiddenimports
+
+a = Analysis(
+    [os.path.join(REPO_ROOT, "browser_session.py")],
+    pathex=[REPO_ROOT],
+    binaries=binaries,
+    datas=datas,
+    hiddenimports=hiddenimports,
+    hookspath=[],
+    hooksconfig={},
+    runtime_hooks=[],
+    excludes=[],
+    noarchive=False,
+)
+pyz = PYZ(a.pure)
+
+exe = EXE(
+    pyz,
+    a.scripts,
+    [],
+    exclude_binaries=True,
+    name="InsightUX",
+    debug=False,
+    bootloader_ignore_signals=False,
+    strip=False,
+    upx=False,
+    # Keep the console. calibrate.py's live lighting/blink/quality readouts
+    # and the correlation "VERDICT" summary are the primary calibration
+    # feedback today — hiding the console would silently drop the one thing
+    # a user needs to read after every calibration run.
+    console=True,
+    disable_windowed_traceback=False,
+    target_arch=None,
+    codesign_identity=None,
+    entitlements_file=None,
+)
+
+coll = COLLECT(
+    exe,
+    a.binaries,
+    a.zipfiles,
+    a.datas,
+    strip=False,
+    upx=False,
+    upx_exclude=[],
+    name="InsightUX",
+)

packaging/README.md

@@ -0,0 +1,87 @@
+# Packaging InsightUX as a downloadable installer
+
+Turns the cloned-repo-plus-venv workflow into a single Windows installer
+(`InsightUX-Setup-<version>.exe`) that bundles Python, torch, mediapipe,
+onnxruntime, opencv, and pywebview — end users need nothing pre-installed.
+
+## One-time setup (per machine you build from)
+
+1. In the project venv: `pip install pyinstaller`
+2. Install [Inno Setup 6](https://jrsoftware.org/isdl.php) (free) — provides
+   `ISCC.exe`, the command-line compiler `installer.iss` needs. Not required
+   just to build the app itself, only to build the final installer.
+3. (Optional but recommended) Download Microsoft's WebView2 bootstrapper
+   (`MicrosoftEdgeWebview2Setup.exe`) from
+   [Microsoft's evergreen bootstrapper page](https://developer.microsoft.com/microsoft-edge/webview2/)
+   and place it in this `packaging/` folder before compiling the installer —
+   `installer.iss` bundles and silently runs it if present, as a safety net
+   for machines missing the WebView2 Runtime (usually already present on
+   modern Windows 10/11, but not guaranteed on older/locked-down machines).
+   If you skip this, the installer still builds fine, just without that
+   safety net.
+
+## Build
+
+From the repo root:
+
+```powershell
+pyinstaller packaging\InsightUX.spec --noconfirm
+```
+
+Output: `dist\InsightUX\` (a folder — `InsightUX.exe` + `_internal\`). Run
+`dist\InsightUX\InsightUX.exe` directly first to confirm it actually starts
+before building the installer — much faster to debug a missing-DLL/missing-
+data-file error at this stage than after wrapping it in an installer.
+
+**Expect to iterate on the first build.** mediapipe, torch, and onnxruntime
+all ship native binaries and non-`.py` data files that PyInstaller's default
+hooks don't always fully catch — see the comments at the top of
+`InsightUX.spec` for what's already collected and where to look if the
+frozen exe fails to start.
+
+Then build the installer:
+
+```powershell
+iscc packaging\installer.iss
+```
+
+Output: `packaging\dist_installer\InsightUX-Setup-<version>.exe`.
+
+## Release checklist
+
+Every time you ship a code change as an update:
+
+1. Bump `VERSION` in [browser_session.py](../browser_session.py).
+2. Bump `AppVersion`/`MyAppVersion` in [installer.iss](installer.iss) to match.
+3. Rebuild (`pyinstaller ...` then `iscc ...`).
+4. Update [version.json](../version.json) at the repo root — `"latest"` to
+   the new version, `"url"` to the new installer's HF download URL.
+5. `git lfs` tracks `*.exe` already (see `.gitattributes`) — add and push the
+   new installer + `version.json` to the `origin` (Hugging Face) remote.
+
+That's it — nothing about *publishing* a release is automated. What's
+automated is the *checking*: every running copy of InsightUX pings
+`version.json` once at startup (`check_for_update()` in browser_session.py)
+and shows a clickable "Update available" pill in the toolbar if `"latest"`
+is newer than its own `VERSION`. Clicking it opens `"url"` in the user's
+default browser — still a manual download+run, just automated the "is there
+something new" question. No internet, or any failure fetching the file, is
+silent (no banner, never an error).
+
+## Why these choices
+
+- **Onedir, not onefile** — onefile re-extracts the whole ~1.5-2.5GB bundle
+  to a temp directory on every launch. With torch/mediapipe already this
+  heavy, that's a genuinely bad startup-time hit. Onedir just runs directly
+  from the installed folder.
+- **Per-user install (`{localappdata}`), not Program Files** — no
+  admin/UAC prompt, and avoids Program Files' write-permission restrictions
+  for `calibration.pkl`/`sessions/`, which the running app writes directly
+  into its own folder (see `RESOURCE_DIR`/`DATA_DIR` in browser_session.py).
+- **Fixed `AppId` GUID in installer.iss** — this is what makes a new
+  installer upgrade the existing install in place instead of creating a
+  second copy. Never regenerate it.
+- **torch is bundled** (not excluded) — its fine-tuning step measurably
+  improves calibration accuracy (169-204px mean error vs. 275px without it,
+  per calibrate.py's own numbers). Confirmed with the project owner as
+  worth the larger download.

packaging/installer.iss

@@ -0,0 +1,87 @@
+; InsightUX Windows installer — Inno Setup script.
+;
+; Build (requires Inno Setup / ISCC installed locally, and dist/InsightUX/
+; already built via `pyinstaller packaging/InsightUX.spec` first):
+;     iscc packaging/installer.iss
+; Output lands in packaging/dist_installer/InsightUX-Setup-<version>.exe.
+;
+; AppId is a FIXED GUID, generated once and never changed. It's the whole
+; mechanism behind "push updates through the installer": every future build
+; keeps this same AppId + a higher AppVersion, so re-running a new installer
+; upgrades the existing install in place (same folder, same shortcuts)
+; instead of creating a second copy. Do not regenerate this GUID.
+;
+; Installs per-user (PrivilegesRequired=lowest) to %LocalAppData%\InsightUX —
+; no admin/UAC prompt, and critically, no Program Files write-permission
+; problems for calibration.pkl/sessions/, which the running app writes
+; directly into its own install folder (see browser_session.py's DATA_DIR).
+;
+; calibration.pkl, baseline_pose.pkl, and sessions/ are deliberately NOT
+; listed under [Files] below. Inno Setup only ever touches files it tracked
+; as having installed — so upgrades overwrite app files without touching
+; those, and a normal uninstall leaves them behind too (the [Code] section
+; below tells the user this explicitly on uninstall, rather than silently).
+
+#define MyAppName "InsightUX"
+#define MyAppVersion "1.0.0"
+#define MyAppPublisher "InsightUX"
+#define MyAppExeName "InsightUX.exe"
+#define MyBuildDir "..\dist\InsightUX"
+
+[Setup]
+AppId={{6DE35CE2-05CB-4375-BFFE-D63E9181F1B9}
+AppName={#MyAppName}
+AppVersion={#MyAppVersion}
+AppPublisher={#MyAppPublisher}
+DefaultDirName={localappdata}\InsightUX
+DefaultGroupName=InsightUX
+DisableProgramGroupPage=yes
+PrivilegesRequired=lowest
+ArchitecturesInstallIn64BitMode=x64compatible
+OutputDir=dist_installer
+OutputBaseFilename=InsightUX-Setup-{#MyAppVersion}
+Compression=lzma2
+SolidCompression=yes
+WizardStyle=modern
+; A ~1.5-2.5GB installer (torch is bundled deliberately, see README) needs
+; the larger internal chunk size or ISCC can fail to build at all.
+DiskSpanning=no
+
+[Tasks]
+Name: "desktopicon"; Description: "Create a &desktop icon"; GroupDescription: "Additional icons:"
+
+[Files]
+Source: "{#MyBuildDir}\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs
+; Microsoft's WebView2 bootstrapper is NOT part of this repo (an external
+; download — see packaging/README.md for the official link). If you've
+; placed it next to this .iss before compiling, it gets bundled and
+; silently run below as a safety net for machines missing the runtime.
+; Harmless to (re-)run even if WebView2 is already installed.
+#ifexist "MicrosoftEdgeWebview2Setup.exe"
+Source: "MicrosoftEdgeWebview2Setup.exe"; DestDir: "{tmp}"; Flags: deleteafterinstall
+#endif
+
+[Icons]
+Name: "{group}\InsightUX"; Filename: "{app}\{#MyAppExeName}"; WorkingDir: "{app}"
+Name: "{group}\Uninstall InsightUX"; Filename: "{uninstallexe}"
+Name: "{commondesktop}\InsightUX"; Filename: "{app}\{#MyAppExeName}"; WorkingDir: "{app}"; Tasks: desktopicon
+
+[Run]
+#ifexist "MicrosoftEdgeWebview2Setup.exe"
+Filename: "{tmp}\MicrosoftEdgeWebview2Setup.exe"; Parameters: "/silent /install"; StatusMsg: "Checking Microsoft Edge WebView2 Runtime..."; Flags: waituntilterminated
+#endif
+Filename: "{app}\{#MyAppExeName}"; Description: "Launch InsightUX"; Flags: nowait postinstall skipifsilent
+
+[Code]
+procedure CurUninstallStepChanged(CurUninstallStep: TUninstallStep);
+begin
+  if CurUninstallStep = usPostUninstall then
+  begin
+    if FileExists(ExpandConstant('{app}\calibration.pkl')) or
+       DirExists(ExpandConstant('{app}\sessions')) then
+      MsgBox('Your calibration profile and saved sessions were kept in:' + #13#10 +
+             ExpandConstant('{app}') + #13#10 +
+             'Delete that folder yourself if you want a completely clean removal.',
+             mbInformation, MB_OK);
+  end;
+end;

requirements.txt

@@ -12,6 +12,7 @@
 # --- Core CV / inference ---
 opencv-python==4.10.0.84
 mediapipe==0.10.18
+onnx==1.16.2
 onnxruntime==1.19.2
 numpy==1.26.4
 scipy==1.13.1

validate.py

@@ -19,11 +19,29 @@ Prints:
 PATCH_SOURCE must match calibrate.py and run_session.py.
 """
 
+import os
+import sys
 import cv2
 import numpy as np
 import time
 import pyautogui
 
+# Windows consoles default to a non-UTF-8 codepage (cp1252) — a stray
+# unicode character in any print() would otherwise crash the whole process
+# with UnicodeEncodeError. See calibrate.py for where this was hit for real.
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+# Same RESOURCE_DIR/DATA_DIR split as calibrate.py and browser_session.py —
+# bundled read-only assets vs. per-user writable data, once frozen.
+if getattr(sys, "frozen", False):
+    RESOURCE_DIR = sys._MEIPASS
+    DATA_DIR     = os.path.dirname(sys.executable)
+else:
+    RESOURCE_DIR = os.path.dirname(os.path.abspath(__file__))
+    DATA_DIR     = RESOURCE_DIR
 
 from preprocessing.preprocessing_pipeline import (
     create_face_mesh,
@@ -43,8 +61,8 @@ from preprocessing.preprocessing_pipeline import (
 from inference_pipeline import InsightUXPipeline, GazeAngleSmoother
 
 
-ONNX_PATH        = "models/gaze_cnn_v4.onnx"
-CALIBRATION_PATH = "calibration.pkl"
+ONNX_PATH        = os.path.join(RESOURCE_DIR, "models", "gaze_cnn_v4.onnx")
+CALIBRATION_PATH = os.path.join(DATA_DIR, "calibration.pkl")
 
 SCREEN_W, SCREEN_H = pyautogui.size()
 PATCH_SOURCE     = "blended"   # MUST match calibrate.py and main_webcam_pipeline.py

version.json

@@ -0,0 +1,5 @@
+{
+  "latest": "1.0.0",
+  "url": "https://huggingface.co/arpitasethiii/insightux/resolve/main/InsightUX-Setup-1.0.0.exe",
+  "notes": "Initial downloadable installer release."
+}