Add mouse tracking, ported feature-for-feature from the Mouse Chrome extension

Injects a trail/heatmap/click/dwell tracking overlay alongside the gaze
overlay so a session captures both eye and mouse attention together, with
an in-page panel (timer, most-viewed element, click log, H/M hotkeys)
replacing the extension's popup, and the report now includes mouse
interest and click-log sections next to the gaze heatmap.

Files changed (2) hide show

analysis.py +91 -0
browser_session.py +519 -3

analysis.py CHANGED Viewed

@@ -52,6 +52,53 @@ def load_session(session_dir):
     return gaze, dom
 # =============================================================================
 # HUMAN-READABLE LABELS
 # Raw AOI labels come straight out of the DOM (tag names, CSS classes,
@@ -320,6 +367,14 @@ _TEMPLATE = r"""<!DOCTYPE html>
     <h2>Attention Timeline</h2>
     <canvas id="timeline" width="1240" height="320"></canvas>
   </div>
 </div>
 <script>
@@ -327,6 +382,39 @@ const RANKING  = __RANKING_JSON__;
 const TIMELINE = __TIMELINE_JSON__;
 const SEGMENTS = __SEGMENTS_JSON__;
 const DURATION = __DURATION_JSON__;
 // ---------- Ranked table ----------
 (function(){
@@ -491,6 +579,7 @@ def generate_report(session_dir):
     timeline = compute_timeline(attributed)
     segments = build_screenshot_segments(gaze, dom)
     summary = session_summary(gaze, dom)
     top_label = ranking[0]["label"] if ranking else "—"
@@ -504,6 +593,8 @@ def generate_report(session_dir):
     html = html.replace("__TIMELINE_JSON__", json.dumps(timeline))
     html = html.replace("__SEGMENTS_JSON__", json.dumps(segments))
     html = html.replace("__DURATION_JSON__", json.dumps(summary["duration"]))
     out_path = os.path.join(session_dir, "analysis_report.html")
     with open(out_path, "w", encoding="utf-8") as f:

     return gaze, dom
+# =============================================================================
+# MOUSE ACTIVITY (from mouse_log.jsonl — batches pushed by the in-page Mouse
+# Tracker overlay, same trail/heatmap/click/dwell shape as the standalone
+# "Mouse Tracker & Heatmap" Chrome extension this was ported from)
+# =============================================================================
+def load_mouse_batches(session_dir):
+    return [r for r in _load_jsonl(os.path.join(session_dir, "mouse_log.jsonl"))
+            if r.get("type") == "mouse_batch"]
+def summarize_mouse(session_dir):
+    batches = load_mouse_batches(session_dir)
+    dwell_totals = {}
+    clicks = []
+    trail_points = 0
+    heatmap_points = 0
+    for b in batches:
+        for item in (b.get("dwell") or []):
+            element = item.get("element")
+            duration = item.get("duration", 0)
+            if not element:
+                continue
+            dwell_totals[element] = dwell_totals.get(element, 0) + duration
+        for c in (b.get("click") or []):
+            clicks.append(c)
+        trail_points += len(b.get("trail") or [])
+        heatmap_points += len(b.get("heatmap") or [])
+    interests = sorted(
+        ({"element": k, "seconds": round(v / 1000.0, 1)} for k, v in dwell_totals.items()),
+        key=lambda r: -r["seconds"]
+    )[:10]
+    clicks.sort(key=lambda c: c.get("timestamp", ""))
+    return {
+        "interests": interests,
+        "clicks": clicks[-50:],
+        "click_count": len(clicks),
+        "trail_points": trail_points,
+        "heatmap_points": heatmap_points,
+    }
 # =============================================================================
 # HUMAN-READABLE LABELS
 # Raw AOI labels come straight out of the DOM (tag names, CSS classes,
     <h2>Attention Timeline</h2>
     <canvas id="timeline" width="1240" height="320"></canvas>
   </div>
+  <div class="panel">
+    <h2>Mouse — Most Interacted Elements</h2>
+    <div id="mouseInterests"></div>
+  </div>
+  <div class="panel">
+    <h2>Mouse — Click Log</h2>
+    <div id="mouseClicks" style="max-height:260px;overflow-y:auto;"></div>
+  </div>
 </div>
 <script>
 const TIMELINE = __TIMELINE_JSON__;
 const SEGMENTS = __SEGMENTS_JSON__;
 const DURATION = __DURATION_JSON__;
+const MOUSE_INTERESTS = __MOUSE_INTERESTS_JSON__;
+const MOUSE_CLICKS = __MOUSE_CLICKS_JSON__;
+// ---------- Mouse interests / clicks (from the in-page Mouse Tracker) ----------
+(function(){
+  const el = document.getElementById('mouseInterests');
+  if (!MOUSE_INTERESTS.length) {
+    el.innerHTML = '<div class="empty">No mouse dwell data recorded for this session.</div>';
+  } else {
+    let html = '<table><tr><th>#</th><th>Element</th><th>Time</th></tr>';
+    MOUSE_INTERESTS.forEach((r, i) => {
+      html += `<tr><td>${i+1}</td><td>${r.element}</td><td>${r.seconds}s</td></tr>`;
+    });
+    html += '</table>';
+    el.innerHTML = html;
+  }
+  const clickEl = document.getElementById('mouseClicks');
+  if (!MOUSE_CLICKS.length) {
+    clickEl.innerHTML = '<div class="empty">No clicks recorded for this session.</div>';
+  } else {
+    let html = '<ul style="padding-left:0;margin:0;list-style:none;">';
+    MOUSE_CLICKS.slice().reverse().forEach(c => {
+      html += `<li style="margin-bottom:8px;border-bottom:1px solid #302a3d;padding-bottom:6px;">
+                 <span style="color:var(--dim);font-size:11px;">${c.timestamp || ''}</span><br>
+                 <b>${c.element || ''}</b><br>
+                 <span style="color:var(--text);font-size:12px;">"${(c.text || '').replace(/</g,'&lt;')}"</span>
+               </li>`;
+    });
+    html += '</ul>';
+    clickEl.innerHTML = html;
+  }
+})();
 // ---------- Ranked table ----------
 (function(){
     timeline = compute_timeline(attributed)
     segments = build_screenshot_segments(gaze, dom)
     summary = session_summary(gaze, dom)
+    mouse = summarize_mouse(session_dir)
     top_label = ranking[0]["label"] if ranking else "—"
     html = html.replace("__TIMELINE_JSON__", json.dumps(timeline))
     html = html.replace("__SEGMENTS_JSON__", json.dumps(segments))
     html = html.replace("__DURATION_JSON__", json.dumps(summary["duration"]))
+    html = html.replace("__MOUSE_INTERESTS_JSON__", json.dumps(mouse["interests"]))
+    html = html.replace("__MOUSE_CLICKS_JSON__", json.dumps(mouse["clicks"]))
     out_path = os.path.join(session_dir, "analysis_report.html")
     with open(out_path, "w", encoding="utf-8") as f:

browser_session.py CHANGED Viewed

@@ -244,9 +244,9 @@ CONTROL_JS = r"""
     <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-Tracking Research Browser</span>
     </span>
-    <span id="__insightux_status" style="color:#c9a6f5;">Press S to start eye-tracking on this page</span>
   `;
   document.documentElement.appendChild(banner);
@@ -510,6 +510,457 @@ TRACKING_JS = r"""
 """
 # =============================================================================
 # API exposed to JS — start/stop are the only two entry points
 # =============================================================================
@@ -520,6 +971,8 @@ class Api:
         self.tracking = False
         self.stop_event = threading.Event()
         self.thread = None
     def start_tracking(self):
         print("[browser_session] start_tracking() called from JS")
@@ -538,7 +991,10 @@ class Api:
         print(f"[browser_session]   starting tracking thread -> {session_dir}")
         self._inject_tracking_overlay()
-        self._set_status("Recording... Press E to stop")
         self.thread = threading.Thread(
             target=gaze_worker, args=(self.window, self.stop_event, session_dir, self),
@@ -553,7 +1009,16 @@ class Api:
             print("[browser_session]   not currently tracking, ignoring")
             return False
         self._set_status("Wrapping up your session...")
         self.stop_event.set()
         return True
     def _inject_tracking_overlay(self):
@@ -562,6 +1027,57 @@ class Api:
         except Exception as e:
             print(f"[browser_session] overlay inject failed: {e}")
     def _set_status(self, text):
         try:
             self.window.evaluate_js(f"window.insightuxSetStatus && window.insightuxSetStatus({json.dumps(text)})")

     <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</span>
   `;
   document.documentElement.appendChild(banner);
 """
+# JS: mouse tracking overlay — ported feature-for-feature from the
+# "Mouse Tracker & Heatmap" Chrome extension (Mouse/content.js + background.js
+# + popup.js), adapted to run as a single injected script instead of a
+# content-script/background/popup trio (pywebview has no extension host).
+# Same trail/heatmap/dwell sampling loop, same click interest labeling, same
+# heatmap render, plus an in-page panel that replaces the extension's popup
+# (Start/Stop/Clear/Toggle Heatmap/View Logs, timer, "Most Viewed Element").
+# =============================================================================
+MOUSE_JS = r"""
+(function(){
+  if (window.__insightuxMouse) { return; }
+  window.__insightuxMouse = true;
+  let isTracking = true;
+  let canvas = null;
+  let panelOpen = false;
+  let logsOpen = false;
+  // Per-sync buffers (flushed to Python every 2s for on-disk persistence)
+  let trailBuffer = [];
+  let heatmapBuffer = [];
+  let clickBuffer = [];
+  let dwellBuffer = [];
+  // Cumulative in-page state (mirrors the extension's background.js state)
+  let allTrail = [];
+  let allHeatmap = [];
+  let allClicks = [];
+  let dwellTotals = {};
+  let sessionStart = Date.now();
+  let sessionStop = null;
+  let lastClientX = 0, lastClientY = 0;
+  let lastPageX = 0, lastPageY = 0;
+  let lastSampleTime = 0;
+  const sampleRate = 50;
+  const DWELL_THRESHOLD = 5000;
+  let stationaryStart = 0;
+  let isStationary = false;
+  window.insightuxMouseSetTracking = function(on){
+    isTracking = !!on;
+    if (isTracking) {
+      sessionStart = Date.now();
+      sessionStop = null;
+    } else {
+      sessionStop = Date.now();
+      flushDwell();
+    }
+    updatePanel();
+  };
+  // ---- sampling loop (trail while moving, heatmap dwell points while still) ----
+  setInterval(function(){
+    if (!isTracking) return;
+    const currentScrollX = window.scrollX, currentScrollY = window.scrollY;
+    if (lastPageX === 0 && lastPageY === 0 && lastClientX !== 0) {
+      lastPageX = lastClientX + currentScrollX;
+      lastPageY = lastClientY + currentScrollY;
+    }
+    const currentPageX = (lastClientX !== 0) ? (lastClientX + currentScrollX) : lastPageX;
+    const currentPageY = (lastClientY !== 0) ? (lastClientY + currentScrollY) : lastPageY;
+    if (currentPageX === 0 && currentPageY === 0) return;
+    const now = Date.now();
+    const dt = now - lastSampleTime;
+    if (dt > 1000) { lastSampleTime = now; return; }
+    const dx = currentPageX - lastPageX, dy = currentPageY - lastPageY;
+    const distance = Math.sqrt(dx * dx + dy * dy);
+    if (distance > 2) {
+      const pt = { x: currentPageX, y: currentPageY };
+      trailBuffer.push(pt); allTrail.push(pt);
+      lastPageX = currentPageX; lastPageY = currentPageY;
+      isStationary = false; stationaryStart = 0;
+    } else {
+      if (!isStationary) { isStationary = true; stationaryStart = now; }
+      else {
+        const dwellDuration = now - stationaryStart;
+        if (dwellDuration > DWELL_THRESHOLD) {
+          const pt = { x: currentPageX, y: currentPageY };
+          heatmapBuffer.push(pt); allHeatmap.push(pt);
+        }
+      }
+    }
+    lastSampleTime = now;
+  }, sampleRate);
+  // ---- dwell / element-interest tracking ----
+  let currentHoverLabel = null, currentHoverStartTime = 0;
+  function handleHoverChange(newLabel){
+    if (!isTracking) return;
+    if (newLabel !== currentHoverLabel) {
+      const now = Date.now();
+      if (currentHoverLabel && currentHoverStartTime > 0) {
+        const duration = now - currentHoverStartTime;
+        if (duration > 10) recordDwell(currentHoverLabel, duration);
+      }
+      currentHoverLabel = newLabel;
+      currentHoverStartTime = newLabel ? now : 0;
+    }
+  }
+  function recordDwell(element, duration){
+    dwellBuffer.push({ element: element, duration: duration });
+    dwellTotals[element] = (dwellTotals[element] || 0) + duration;
+  }
+  function flushDwell(){
+    if (currentHoverLabel && currentHoverStartTime > 0) {
+      const now = Date.now();
+      const duration = now - currentHoverStartTime;
+      if (duration > 50) recordDwell(currentHoverLabel, duration);
+      currentHoverStartTime = now;
+    }
+  }
+  // ---- sync to Python every 2s -> mouse_log.jsonl in the session folder ----
+  setInterval(function(){
+    flushDwell();
+    if (trailBuffer.length || heatmapBuffer.length || clickBuffer.length || dwellBuffer.length) {
+      const payload = {
+        trail: trailBuffer.length ? trailBuffer : null,
+        heatmap: heatmapBuffer.length ? heatmapBuffer : null,
+        click: clickBuffer.length ? clickBuffer : null,
+        dwell: dwellBuffer.length ? dwellBuffer : null,
+      };
+      trailBuffer = []; heatmapBuffer = []; clickBuffer = []; dwellBuffer = [];
+      if (window.pywebview && window.pywebview.api && window.pywebview.api.log_mouse_data) {
+        try { window.pywebview.api.log_mouse_data(payload).catch(function(){}); } catch (e) {}
+      }
+    }
+    updatePanel();
+  }, 2000);
+  // ---- mouse position + hover tracking ----
+  function updateMousePos(e){
+    lastClientX = e.clientX; lastClientY = e.clientY;
+    if (lastPageX === 0) lastPageX = e.pageX;
+    if (lastPageY === 0) lastPageY = e.pageY;
+    if (isTracking) handleHoverChange(getSmartLabel(e.target));
+  }
+  document.addEventListener('mousemove', updateMousePos, true);
+  document.addEventListener('mouseenter', updateMousePos, true);
+  document.addEventListener('mouseover', updateMousePos, true);
+  document.addEventListener('click', updateMousePos, true);
+  document.addEventListener('mouseleave', function(){
+    lastClientX = 0; lastClientY = 0;
+    handleHoverChange(null);
+  }, true);
+  document.addEventListener('click', function(e){
+    if (!isTracking) return;
+    if (e.target === canvas) return;
+    if (!isInteractable(e.target)) return;
+    const x = e.pageX, y = e.pageY;
+    const label = getSmartLabel(e.target) || e.target.tagName;
+    if (['BODY', 'HTML', 'DIV', 'SPAN'].includes(label) && !e.target.innerText.trim()) return;
+    const logEntry = {
+      timestamp: new Date().toLocaleTimeString(),
+      x: x, y: y, element: label,
+      text: e.target.innerText ? e.target.innerText.substring(0, 30).replace(/(\r\n|\n|\r)/gm, ' ').trim() : '',
+      url: window.location.href
+    };
+    clickBuffer.push(logEntry); allClicks.push(logEntry);
+    if (canvas) drawClick(x, y);
+    updatePanel();
+  }, true);
+  function isInteractable(el){
+    if (!el) return false;
+    const tag = el.tagName.toLowerCase();
+    if (['a', 'button', 'input', 'select', 'textarea', 'details', 'summary', 'label'].includes(tag)) return true;
+    const role = el.getAttribute('role');
+    if (role === 'button' || role === 'link' || role === 'menuitem' || role === 'tab') return true;
+    try { if (window.getComputedStyle(el).cursor === 'pointer') return true; } catch (e) {}
+    let parent = el.parentElement, depth = 0;
+    while (parent && depth < 3) {
+      const pTag = parent.tagName.toLowerCase();
+      if (['a', 'button'].includes(pTag)) return true;
+      if (parent.getAttribute('role') === 'button') return true;
+      parent = parent.parentElement; depth++;
+    }
+    if (tag === 'code' || tag === 'pre' || el.classList.contains('code') || el.closest('pre')) return true;
+    return false;
+  }
+  function getSmartLabel(el){
+    if (!el) return null;
+    const tag = el.tagName.toLowerCase();
+    if (['body', 'html', 'main', 'div', 'span', 'section', 'article'].includes(tag)) {
+      if (el.id && (el.id.includes('logo') || el.id.includes('wrapper') || el.id.includes('container'))) return null;
+      if (el.className && typeof el.className === 'string' &&
+          (el.className.toLowerCase().includes('logo') || el.className.toLowerCase().includes('brand'))) return null;
+      const aria = el.getAttribute('aria-label');
+      if (aria) return 'Element: ' + aria;
+      if (el.children.length === 0) {
+        const txt = el.innerText.trim();
+        if (txt.length > 2 && txt.length < 50 && /[a-zA-Z0-9]/.test(txt)) return 'Element: ' + txt;
+      }
+      return null;
+    }
+    if (tag === 'a') return 'Link: ' + (el.innerText.trim().substring(0, 30) || 'Link');
+    if (tag === 'button') return 'Button: ' + (el.innerText.trim().substring(0, 30) || 'Button');
+    if (tag === 'input') return 'Input: ' + (el.placeholder || el.name || el.id || 'Input');
+    if (tag === 'textarea') return 'Input: Text Area';
+    if (tag === 'img') return 'Image: ' + (el.alt || 'Image');
+    if (['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(tag)) return tag.toUpperCase() + ': ' + el.innerText.trim().substring(0, 40);
+    if (tag === 'code' || tag === 'pre') return 'Code: ' + el.innerText.trim().substring(0, 30);
+    const text = el.innerText.trim();
+    if (text && text.length > 2) {
+      if (el.classList.contains('code') || el.closest('pre')) return 'Code: ' + text.substring(0, 30);
+      if (text.toLowerCase().includes('no message found')) return null;
+      const isHex = /^#[0-9A-F]{6}$/i.test(text) || /^#[0-9A-F]{3}$/i.test(text);
+      const isColorName = ['red', 'blue', 'green', 'yellow', 'black', 'white', 'orange', 'purple', 'gray', 'grey', 'pink', 'brown', 'cyan', 'magenta'].includes(text.toLowerCase());
+      if (isHex || isColorName) return null;
+      if (text.length > 50) return 'Text: ' + text.substring(0, 47) + '...';
+      return 'Text: ' + text;
+    }
+    return null;
+  }
+  // ---- heatmap overlay canvas (ported 1:1 from the extension) ----
+  window.insightuxMouseToggleHeatmap = function(){
+    if (canvas) { document.body.removeChild(canvas); canvas = null; return; }
+    canvas = document.createElement('canvas');
+    canvas.style.position = 'absolute';
+    canvas.style.top = '0'; canvas.style.left = '0';
+    canvas.style.zIndex = '2147483645';
+    canvas.style.pointerEvents = 'none';
+    canvas.width = Math.max(document.documentElement.scrollWidth, document.body.scrollWidth, document.documentElement.offsetWidth);
+    canvas.height = Math.max(document.documentElement.scrollHeight, document.body.scrollHeight, document.documentElement.offsetHeight);
+    document.body.appendChild(canvas);
+    drawHeatmapHighQuality(allHeatmap, allTrail, allClicks);
+  };
+  function drawClick(x, y){
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    ctx.save();
+    ctx.beginPath();
+    ctx.strokeStyle = '#00FF00'; ctx.lineWidth = 3;
+    ctx.shadowColor = 'black'; ctx.shadowBlur = 2;
+    const size = 10;
+    ctx.moveTo(x - size, y - size); ctx.lineTo(x + size, y + size);
+    ctx.moveTo(x + size, y - size); ctx.lineTo(x - size, y + size);
+    ctx.stroke();
+    ctx.beginPath(); ctx.arc(x, y, size + 5, 0, Math.PI * 2); ctx.stroke();
+    ctx.restore();
+  }
+  function drawHeatmapHighQuality(heatmapData, trailData, clickData){
+    if (!canvas) return;
+    const ctx = canvas.getContext('2d');
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    let allHeatPoints = [];
+    if (heatmapData && heatmapData.length) allHeatPoints = allHeatPoints.concat(heatmapData);
+    if (trailData && trailData.length) allHeatPoints = allHeatPoints.concat(trailData);
+    if (clickData && clickData.length) {
+      clickData.forEach(function(c){ for (let i = 0; i < 5; i++) allHeatPoints.push({ x: c.x, y: c.y }); });
+    }
+    if (!allHeatPoints.length) return;
+    const radius = 60;
+    const brushCanvas = document.createElement('canvas');
+    brushCanvas.width = radius * 2; brushCanvas.height = radius * 2;
+    const brushCtx = brushCanvas.getContext('2d');
+    const g = brushCtx.createRadialGradient(radius, radius, 0, radius, radius, radius);
+    g.addColorStop(0, 'rgba(0, 0, 0, 0.05)'); g.addColorStop(1, 'rgba(0, 0, 0, 0)');
+    brushCtx.fillStyle = g; brushCtx.fillRect(0, 0, radius * 2, radius * 2);
+    allHeatPoints.forEach(function(point){ ctx.drawImage(brushCanvas, point.x - radius, point.y - radius); });
+    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    const data = imageData.data;
+    const gradientMap = createGradientMap();
+    for (let i = 0; i < data.length; i += 4) {
+      const alpha = data[i + 3];
+      if (alpha > 0) {
+        let mapIndex = Math.floor(alpha * 1.5);
+        if (mapIndex > 255) mapIndex = 255;
+        const cIndex = mapIndex * 4;
+        data[i] = gradientMap[cIndex]; data[i + 1] = gradientMap[cIndex + 1]; data[i + 2] = gradientMap[cIndex + 2];
+        data[i + 3] = Math.min(255, 150 + alpha);
+      }
+    }
+    ctx.putImageData(imageData, 0, 0);
+  }
+  function createGradientMap(){
+    const c = document.createElement('canvas'); c.width = 256; c.height = 1;
+    const ctx = c.getContext('2d');
+    const g = ctx.createLinearGradient(0, 0, 256, 0);
+    g.addColorStop(0.0, 'rgba(0, 0, 255, 0)');
+    g.addColorStop(0.1, 'rgba(0, 0, 255, 1)');
+    g.addColorStop(0.4, 'rgba(0, 255, 255, 1)');
+    g.addColorStop(0.6, 'rgba(0, 255, 0, 1)');
+    g.addColorStop(0.8, 'rgba(255, 255, 0, 1)');
+    g.addColorStop(1.0, 'rgba(255, 0, 0, 1)');
+    ctx.fillStyle = g; ctx.fillRect(0, 0, 256, 1);
+    return ctx.getImageData(0, 0, 256, 1).data;
+  }
+  window.addEventListener('resize', function(){
+    if (canvas) {
+      canvas.width = Math.max(document.documentElement.scrollWidth, document.body.scrollWidth, document.documentElement.offsetWidth);
+      canvas.height = Math.max(document.documentElement.scrollHeight, document.body.scrollHeight, document.documentElement.offsetHeight);
+    }
+  });
+  // ---- insights panel: in-page port of the extension's popup.html/popup.js ----
+  const style = document.createElement('style');
+  style.textContent = `
+    #__insightux_mouse_panel {
+      position: fixed; top: 44px; right: 16px; width: 260px; z-index: 2147483647;
+      background: linear-gradient(180deg, rgba(28,24,38,0.97), rgba(20,18,26,0.97));
+      border: 1px solid #3a3348; border-radius: 12px; box-shadow: 0 8px 28px rgba(0,0,0,0.45);
+      font: 12px -apple-system, 'Segoe UI', Arial; color: #f0ecf7; padding: 14px;
+      pointer-events: auto; display: none;
+    }
+    #__insightux_mouse_panel.open { display: block; }
+    #__insightux_mouse_panel h3 { margin: 0 0 8px 0; font-size: 13px; color: #f0ecf7;
+      display:flex; align-items:center; justify-content:space-between; }
+    #__insightux_mouse_panel .muted { color: #9a92ad; font-size: 11px; }
+    #__insightux_mouse_panel .row { display: flex; gap: 6px; margin-bottom: 8px; flex-wrap: wrap; }
+    #__insightux_mouse_panel button {
+      flex: 1 1 auto; padding: 6px 8px; font-size: 11px; border-radius: 6px; border: 1px solid #3a3348;
+      background: #241f2e; color: #f0ecf7; cursor: pointer;
+    }
+    #__insightux_mouse_panel button:hover { background: #302a3d; }
+    #__insightux_mouse_panel .timer { font-weight: 600; margin-bottom: 6px; }
+    #__insightux_mouse_panel .hero {
+      background: rgba(123,47,190,0.15); border: 1px solid #7B2FBE; border-radius: 8px;
+      padding: 8px; text-align: center; margin-bottom: 8px;
+    }
+    #__insightux_mouse_panel .hero .lbl { font-size: 9px; text-transform: uppercase; color: #c9a6f5; letter-spacing: 0.05em; }
+    #__insightux_mouse_panel .hero .el { font-weight: 600; margin: 3px 0; color: #FF2DF0; }
+    #__insightux_mouse_panel .interest-item, #__insightux_mouse_panel .log-item {
+      background: #241f2e; border-radius: 6px; padding: 5px 7px; margin-bottom: 4px; font-size: 11px;
+    }
+    #__insightux_mouse_panel .list { max-height: 160px; overflow-y: auto; }
+  `;
+  document.head.appendChild(style);
+  const panel = document.createElement('div');
+  panel.id = '__insightux_mouse_panel';
+  panel.innerHTML = `
+    <h3>Mouse Tracker <span class="muted" id="__mt_status">idle</span></h3>
+    <div class="timer" id="__mt_timer">Session Time: 00:00</div>
+    <div class="row">
+      <button id="__mt_clear">Clear</button>
+      <button id="__mt_heatmap">Heatmap</button>
+      <button id="__mt_logs">Logs</button>
+    </div>
+    <div id="__mt_hero" class="hero" style="display:none;">
+      <div class="lbl">Most Viewed Element</div>
+      <div class="el" id="__mt_hero_el">-</div>
+      <div id="__mt_hero_time">0s</div>
+    </div>
+    <div id="__mt_interests" class="list"></div>
+    <div id="__mt_logs_list" class="list" style="display:none;"></div>
+  `;
+  document.documentElement.appendChild(panel);
+  document.getElementById('__mt_clear').addEventListener('click', function(){
+    trailBuffer = []; heatmapBuffer = []; clickBuffer = []; dwellBuffer = [];
+    allTrail = []; allHeatmap = []; allClicks = []; dwellTotals = {};
+    sessionStart = Date.now(); sessionStop = null;
+    if (canvas) { document.body.removeChild(canvas); canvas = null; }
+    updatePanel();
+  });
+  document.getElementById('__mt_heatmap').addEventListener('click', function(){ window.insightuxMouseToggleHeatmap(); });
+  document.getElementById('__mt_logs').addEventListener('click', function(){
+    logsOpen = !logsOpen;
+    document.getElementById('__mt_logs_list').style.display = logsOpen ? 'block' : 'none';
+    document.getElementById('__mt_interests').style.display = logsOpen ? 'none' : 'block';
+    updatePanel();
+  });
+  window.insightuxMouseTogglePanel = function(){
+    panelOpen = !panelOpen;
+    panel.classList.toggle('open', panelOpen);
+    if (panelOpen) updatePanel();
+  };
+  function formatTime(ms){ return Math.round(ms / 1000) + 's'; }
+  function updatePanel(){
+    if (!panelOpen) return;
+    document.getElementById('__mt_status').textContent = isTracking ? 'tracking' : 'stopped';
+    const startTs = sessionStart;
+    const diff = isTracking ? Math.floor((Date.now() - startTs) / 1000)
+                             : (sessionStop ? Math.floor((sessionStop - startTs) / 1000) : 0);
+    const mins = Math.floor(diff / 60).toString().padStart(2, '0');
+    const secs = (diff % 60).toString().padStart(2, '0');
+    document.getElementById('__mt_timer').textContent = 'Session Time: ' + mins + ':' + secs;
+    const interests = Object.entries(dwellTotals).map(function(e){ return { element: e[0], duration: e[1] }; })
+      .sort(function(a, b){ return b.duration - a.duration; }).slice(0, 6);
+    const hero = document.getElementById('__mt_hero');
+    if (interests.length) {
+      hero.style.display = 'block';
+      document.getElementById('__mt_hero_el').textContent = interests[0].element;
+      document.getElementById('__mt_hero_time').textContent = formatTime(interests[0].duration);
+    } else {
+      hero.style.display = 'none';
+    }
+    const interestsEl = document.getElementById('__mt_interests');
+    if (!logsOpen) {
+      if (interests.length > 1) {
+        interestsEl.innerHTML = interests.slice(1).map(function(it, i){
+          return '<div class="interest-item">' + (i + 2) + '. <b>' + it.element + '</b> — ' + formatTime(it.duration) + '</div>';
+        }).join('');
+      } else {
+        interestsEl.innerHTML = '<div class="muted">No other interests yet.</div>';
+      }
+    }
+    const logsEl = document.getElementById('__mt_logs_list');
+    if (logsOpen) {
+      if (allClicks.length) {
+        logsEl.innerHTML = allClicks.slice().reverse().slice(0, 20).map(function(l){
+          return '<div class="log-item"><span class="muted">' + l.timestamp + '</span><br><b>' + l.element + '</b><br>"' + l.text + '"</div>';
+        }).join('');
+      } else {
+        logsEl.innerHTML = '<div class="muted">No clicks recorded.</div>';
+      }
+    }
+  }
+  setInterval(updatePanel, 1000);
+  // ---- hotkeys: H = toggle heatmap, M = toggle insights panel ----
+  function isTypingTarget(el){
+    if (!el) return false;
+    const tag = el.tagName ? el.tagName.toLowerCase() : '';
+    return tag === 'input' || tag === 'textarea' || tag === 'select' || el.isContentEditable === true;
+  }
+  document.addEventListener('keydown', function(e){
+    const typingBlocked = isTypingTarget(e.target) || isTypingTarget(document.activeElement);
+    if (typingBlocked) return;
+    if (e.key === 'h' || e.key === 'H') window.insightuxMouseToggleHeatmap();
+    else if (e.key === 'm' || e.key === 'M') window.insightuxMouseTogglePanel();
+  }, true);
+  updatePanel();
+})();
+"""
 # =============================================================================
 # API exposed to JS — start/stop are the only two entry points
 # =============================================================================
         self.tracking = False
         self.stop_event = threading.Event()
         self.thread = None
+        self.mouse_log_f = None
+        self.mouse_close_timer = None
     def start_tracking(self):
         print("[browser_session] start_tracking() called from JS")
         print(f"[browser_session]   starting tracking thread -> {session_dir}")
         self._inject_tracking_overlay()
+        self._inject_mouse_overlay()
+        self._open_mouse_log(session_dir)
+        self._set_mouse_tracking(True)
+        self._set_status("Recording gaze + mouse... Press E to stop, H for heatmap, M for mouse panel")
         self.thread = threading.Thread(
             target=gaze_worker, args=(self.window, self.stop_event, session_dir, self),
             print("[browser_session]   not currently tracking, ignoring")
             return False
         self._set_status("Wrapping up your session...")
+        self._set_mouse_tracking(False)
         self.stop_event.set()
+        # Give the page a moment to flush its last batch of mouse data over
+        # log_mouse_data() before the file handle is closed.
+        if self.mouse_close_timer:
+            self.mouse_close_timer.cancel()
+        self.mouse_close_timer = threading.Timer(2.5, self._close_mouse_log)
+        self.mouse_close_timer.daemon = True
+        self.mouse_close_timer.start()
         return True
     def _inject_tracking_overlay(self):
         except Exception as e:
             print(f"[browser_session] overlay inject failed: {e}")
+    def _inject_mouse_overlay(self):
+        try:
+            self.window.evaluate_js(MOUSE_JS)
+        except Exception as e:
+            print(f"[browser_session] mouse overlay inject failed: {e}")
+    def _set_mouse_tracking(self, on):
+        try:
+            flag = "true" if on else "false"
+            self.window.evaluate_js(
+                f"window.insightuxMouseSetTracking && window.insightuxMouseSetTracking({flag})"
+            )
+        except Exception:
+            pass
+    def _open_mouse_log(self, session_dir):
+        self._close_mouse_log()
+        path = os.path.join(session_dir, "mouse_log.jsonl")
+        try:
+            self.mouse_log_f = open(path, "w", buffering=1)
+            self.mouse_log_f.write(json.dumps({"type": "meta", "t": round(time.time(), 4)}) + "\n")
+            print(f"[browser_session] writing mouse stream to {path}")
+        except Exception as e:
+            print(f"[browser_session] could not open mouse log: {e}")
+            self.mouse_log_f = None
+    def _close_mouse_log(self):
+        if self.mouse_log_f:
+            try:
+                self.mouse_log_f.close()
+                print("[browser_session] mouse log closed")
+            except Exception:
+                pass
+            self.mouse_log_f = None
+    def log_mouse_data(self, payload):
+        """Called from the injected Mouse Tracker overlay (MOUSE_JS) roughly
+        every 2s while tracking, with a batch of trail / heatmap / click /
+        dwell records — same cadence as the extension's background.js sync
+        loop, just persisted to mouse_log.jsonl instead of chrome.storage."""
+        if not self.mouse_log_f:
+            return False
+        try:
+            rec = dict(payload) if isinstance(payload, dict) else {}
+            rec["type"] = "mouse_batch"
+            rec["t"] = round(time.time(), 4)
+            self.mouse_log_f.write(json.dumps(rec) + "\n")
+        except Exception as e:
+            print(f"[browser_session] mouse log write failed: {e}")
+        return True
     def _set_status(self, text):
         try:
             self.window.evaluate_js(f"window.insightuxSetStatus && window.insightuxSetStatus({json.dumps(text)})")