feat: add timeline heatmap with detection highlights for Tab 2 video player

Add a visual progress bar beneath the video in Track & Monitor tab that
shows which frames have detected objects. Backend summary endpoint returns
per-frame detection counts in one call, frontend renders a color-coded
heatmap (amber for few tracks, red for 5+) with a scrubable playhead.

- Backend: GET /detect/tracks/{job_id}/summary endpoint + JobStorage.get_track_summary()
- Frontend: timeline.js canvas bar with heatmap render + click-to-seek
- Frontend: loadSummary() fetches heatmap data when job completes
- CLAUDE.md: document parallel execution with team mode pattern

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

CLAUDE.md

@@ -220,6 +220,32 @@ _schedule_cleanup(background_tasks, input_path)
 _schedule_cleanup(background_tasks, output_path)
 ```
 
+## Parallel Execution with Team Mode
+
+When implementing features that touch independent subsystems, **use team mode (parallel agents with worktree isolation)** for maximum efficiency.
+
+### When to Parallelize
+- Backend (Python) + Frontend (JS) changes — always parallelizable
+- Independent API endpoints or UI components
+- Test writing + implementation when in different files
+- Any 2+ tasks that don't modify the same files
+
+### How to Parallelize
+1. Identify independent task domains (e.g., backend vs frontend)
+2. Dispatch one agent per domain using `isolation: "worktree"`
+3. Each agent works in its own git worktree — no conflicts
+4. Merge results back: `git checkout <worktree-branch> -- <files>`
+5. Clean up worktrees after merge
+
+### Example
+```
+Agent 1 (worktree): Backend — app.py, jobs/storage.py
+Agent 2 (worktree): Frontend — timeline.js, client.js
+→ Both run simultaneously, merge when done
+```
+
+**Default to parallel** when tasks are independent. Sequential only when one task's output is the other's input.
+
 ## Performance Notes
 
 - **Detector Caching**: Models are loaded once and cached via `@lru_cache`

app.py

@@ -593,6 +593,38 @@ async def detect_status(job_id: str):
     }
 
 
+@app.get("/detect/tracks/{job_id}/summary")
+async def get_track_summary_endpoint(job_id: str):
+    """Return per-frame detection counts for timeline heatmap."""
+    from jobs.storage import get_track_summary, get_job_storage
+    import cv2
+
+    job = get_job_storage().get(job_id)
+    if not job:
+        raise HTTPException(status_code=404, detail="Job not found")
+
+    summary = get_track_summary(job_id)
+
+    total_frames = 0
+    fps = 30.0
+    video_path = job.output_video_path
+    if video_path:
+        cap = cv2.VideoCapture(video_path)
+        if cap.isOpened():
+            total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+            fps = cap.get(cv2.CAP_PROP_FPS) or 30.0
+            cap.release()
+
+    if total_frames == 0 and summary:
+        total_frames = max(summary.keys()) + 1
+
+    return {
+        "total_frames": total_frames,
+        "fps": fps,
+        "frames": summary,
+    }
+
+
 @app.get("/detect/tracks/{job_id}/{frame_idx}")
 async def get_frame_tracks(job_id: str, frame_idx: int):
     """Retrieve detections (with tracking info) for a specific frame."""

frontend/index.html

@@ -222,6 +222,10 @@
                 </div>
               </div>
 
+              <div id="timelineWrap" class="timeline-wrap">
+                <canvas id="timelineBar"></canvas>
+              </div>
+
               <div class="btnrow mt-md">
                 <button id="btnEngage" class="btn">Track</button>
                 <button id="btnPause" class="btn secondary">Pause</button>
@@ -287,6 +291,7 @@
   <script src="./js/ui/logging.js"></script>
   <script src="./js/core/gptMapping.js"></script>
   <script src="./js/core/tracker.js"></script>
+  <script src="./js/core/timeline.js"></script>
   <script src="./js/api/client.js"></script>
   <script src="./js/ui/overlays.js"></script>
   <script src="./js/ui/cards.js"></script>

frontend/js/api/client.js

@@ -199,6 +199,8 @@ APP.api.client.pollAsyncJob = async function () {
 
                         clearInterval(state.hf.asyncPollInterval);
                         state.hf.completedJobId = state.hf.asyncJobId;  // preserve for post-completion sync
+                        // Fetch timeline summary for heatmap
+                        APP.core.timeline.loadSummary();
                         state.hf.asyncJobId = null;
                         setHfStatus("ready");
                         resolve();

frontend/js/core/state.js

@@ -59,7 +59,8 @@ APP.core.state = {
         lastFrameTime: 0,
         frameCount: 0,
         _lastCardRenderFrame: 0,    // Frame count at last card render
-        _gptBusy: false             // Prevent overlapping GPT calls
+        _gptBusy: false,            // Prevent overlapping GPT calls
+        heatmap: {}                 // { frameIdx: trackCount } for timeline heatmap
     },
 
     frame: {

frontend/js/core/timeline.js

@@ -0,0 +1,165 @@
+/**
+ * timeline.js — Lazy heatmap timeline bar for Tab 2 (Track & Monitor).
+ *
+ * Renders a thin canvas bar showing:
+ *   - Detection density heatmap (colored by track count per frame)
+ *   - White playhead at current video position
+ *   - Click-to-seek interaction
+ *
+ * Heatmap data is populated lazily by tracker.syncWithBackend() writing
+ * track counts into state.tracker.heatmap[frameIdx].
+ */
+APP.core.timeline = {};
+
+(function () {
+    const COLORS = {
+        bg:       "#1a1a2e",   // unvisited
+        empty:    "#2a2a3e",   // visited, 0 tracks
+        low:      "rgba(245, 158, 11, 0.4)",  // 1-2 tracks
+        mid:      "rgba(245, 158, 11, 0.7)",  // 3-4 tracks
+        high:     "rgba(239, 68, 68, 0.9)",   // 5+ tracks
+        playhead: "#ffffff",
+    };
+
+    function colorForCount(count) {
+        if (count === undefined) return COLORS.bg;
+        if (count === 0) return COLORS.empty;
+        if (count <= 2) return COLORS.low;
+        if (count <= 4) return COLORS.mid;
+        return COLORS.high;
+    }
+
+    /** Render the timeline heatmap + playhead. Called every RAF frame. */
+    APP.core.timeline.render = function () {
+        const { state } = APP.core;
+        const { $ } = APP.core.utils;
+        const canvas = $("#timelineBar");
+        const video = $("#videoEngage");
+        if (!canvas || !video) return;
+
+        // Cache duration once metadata loads (video.duration is NaN before that)
+        if (video.duration && isFinite(video.duration)) {
+            APP.core.timeline._cachedDuration = video.duration;
+        }
+        const duration = APP.core.timeline._cachedDuration;
+        if (!duration) return;
+
+        const wrap = canvas.parentElement;
+        const rect = wrap.getBoundingClientRect();
+        const dpr = window.devicePixelRatio || 1;
+        const w = Math.floor(rect.width);
+        const h = 14;
+
+        if (canvas.width !== w * dpr || canvas.height !== h * dpr) {
+            canvas.width = w * dpr;
+            canvas.height = h * dpr;
+            canvas.style.width = w + "px";
+            canvas.style.height = h + "px";
+        }
+
+        const ctx = canvas.getContext("2d");
+        ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+
+        const fps = 30;
+        const totalFrames = Math.ceil(duration * fps);
+        if (totalFrames <= 0) return;
+
+        const heatmap = state.tracker.heatmap;
+
+        // Draw heatmap segments
+        // Group consecutive pixels mapping to same color to reduce draw calls
+        const pxPerFrame = w / totalFrames;
+
+        if (pxPerFrame >= 1) {
+            // Enough room to draw per-frame
+            for (let f = 0; f < totalFrames; f++) {
+                const x = Math.floor(f * pxPerFrame);
+                const nx = Math.floor((f + 1) * pxPerFrame);
+                ctx.fillStyle = colorForCount(heatmap[f]);
+                ctx.fillRect(x, 0, Math.max(nx - x, 1), h);
+            }
+        } else {
+            // More frames than pixels — bucket frames per pixel
+            for (let px = 0; px < w; px++) {
+                const fStart = Math.floor((px / w) * totalFrames);
+                const fEnd = Math.floor(((px + 1) / w) * totalFrames);
+                let maxCount;
+                for (let f = fStart; f < fEnd; f++) {
+                    const c = heatmap[f];
+                    if (c !== undefined && (maxCount === undefined || c > maxCount)) {
+                        maxCount = c;
+                    }
+                }
+                ctx.fillStyle = colorForCount(maxCount);
+                ctx.fillRect(px, 0, 1, h);
+            }
+        }
+
+        // Draw playhead
+        const progress = video.currentTime / duration;
+        const px = Math.round(progress * w);
+        ctx.fillStyle = COLORS.playhead;
+        ctx.fillRect(px - 1, 0, 2, h);
+    };
+
+    /** Initialize click-to-seek on the timeline canvas. */
+    APP.core.timeline.init = function () {
+        const { $ } = APP.core.utils;
+        const canvas = $("#timelineBar");
+        const video = $("#videoEngage");
+        if (!canvas || !video) return;
+
+        let dragging = false;
+
+        function seek(e) {
+            const rect = canvas.getBoundingClientRect();
+            const x = Math.max(0, Math.min(e.clientX - rect.left, rect.width));
+            const ratio = x / rect.width;
+            const dur = APP.core.timeline._cachedDuration || video.duration;
+            if (dur && isFinite(dur)) {
+                video.currentTime = ratio * dur;
+            }
+        }
+
+        canvas.addEventListener("mousedown", function (e) {
+            dragging = true;
+            seek(e);
+        });
+        window.addEventListener("mousemove", function (e) {
+            if (dragging) seek(e);
+        });
+        window.addEventListener("mouseup", function () {
+            dragging = false;
+        });
+    };
+
+    /** Fetch track summary from backend and populate heatmap + duration. */
+    APP.core.timeline.loadSummary = async function () {
+        const { state } = APP.core;
+        const jobId = state.hf.asyncJobId || state.hf.completedJobId;
+        if (!jobId || !state.hf.baseUrl) return;
+
+        try {
+            const resp = await fetch(`${state.hf.baseUrl}/detect/tracks/${jobId}/summary`);
+            if (!resp.ok) return;
+
+            const data = await resp.json();
+            const frames = data.frames || {};
+
+            // Populate heatmap — keys come as strings from JSON, convert to int
+            state.tracker.heatmap = {};
+            for (const [idx, count] of Object.entries(frames)) {
+                state.tracker.heatmap[parseInt(idx, 10)] = count;
+            }
+
+            // Cache duration from backend metadata (bypass video.duration dependency)
+            if (data.total_frames > 0 && data.fps > 0) {
+                APP.core.timeline._cachedDuration = data.total_frames / data.fps;
+            }
+
+            console.log(`[timeline] Loaded summary: ${Object.keys(frames).length} frames, duration=${APP.core.timeline._cachedDuration}s`);
+        } catch (e) {
+            console.warn("[timeline] Failed to load summary", e);
+        }
+    };
+})();

frontend/js/core/tracker.js

@@ -250,6 +250,9 @@ APP.core.tracker.syncWithBackend = async function (frameIdx) {
             APP.ui.logging.log(`New objects: ${brandNew.map(t => t.id).join(", ")}`, "t");
         }
 
+        // Cache track count for timeline heatmap
+        state.tracker.heatmap[frameIdx] = newTracks.length;
+
         // Update state
         state.tracker.tracks = newTracks;
         state.detections = newTracks; // Keep synced

frontend/js/main.js

@@ -63,6 +63,9 @@ document.addEventListener("DOMContentLoaded", () => {
         // Enable click-to-select on engage overlay
         initClickHandler();
 
+        // Initialize timeline seek interaction
+        APP.core.timeline.init();
+
         // Start main loop
         requestAnimationFrame(loop);
 
@@ -192,6 +195,8 @@ document.addEventListener("DOMContentLoaded", () => {
                 state.tracker.tracks = [];
                 state.tracker.running = false;
                 state.tracker.nextId = 1;
+                state.tracker.heatmap = {};
+                APP.core.timeline._cachedDuration = null;
                 renderFrameTrackList();
                 log("Tracking reset.", "t");
             });
@@ -725,7 +730,9 @@ document.addEventListener("DOMContentLoaded", () => {
                 const jobId = state.hf.asyncJobId || state.hf.completedJobId;
                 if (jobId && (t - state.tracker.lastHFSync > 333)) {
                     const frameIdx = Math.floor(videoEngage.currentTime * 30);
-                    APP.core.tracker.syncWithBackend(frameIdx);
+                    if (isFinite(frameIdx) && frameIdx >= 0) {
+                        APP.core.tracker.syncWithBackend(frameIdx);
+                    }
                     state.tracker.lastHFSync = t;
                 }
             }
@@ -773,6 +780,7 @@ document.addEventListener("DOMContentLoaded", () => {
         if (renderFrameOverlay) renderFrameOverlay();
         if (renderEngageOverlay) renderEngageOverlay();
         if (tickAgentCursor) tickAgentCursor();
+        APP.core.timeline.render();
 
         requestAnimationFrame(loop);
     }

frontend/style.css

@@ -545,6 +545,25 @@ input[type="number"]:focus {
     line-height: 1.4;
 }
 
+/* =========================================
+   Timeline Heatmap Bar
+   ========================================= */
+
+.timeline-wrap {
+    width: 100%;
+    margin-top: 6px;
+    border-radius: 4px;
+    overflow: hidden;
+    background: #1a1a2e;
+    cursor: pointer;
+}
+
+.timeline-wrap canvas {
+    display: block;
+    width: 100%;
+    height: 14px;
+}
+
 /* =========================================
    Lists & Tables
    ========================================= */

jobs/storage.py

@@ -55,6 +55,12 @@ class JobStorage:
         with self._lock:
             return self._tracks.get(job_id, {}).get(frame_idx, [])
 
+    def get_track_summary(self, job_id: str) -> dict:
+        """Return {frame_idx: track_count} for all stored frames."""
+        with self._lock:
+            frames = self._tracks.get(job_id, {})
+            return {idx: len(tracks) for idx, tracks in frames.items()}
+
     def get(self, job_id: str) -> Optional[JobInfo]:
         with self._lock:
             return self._jobs.get(job_id)
@@ -98,3 +104,6 @@ def get_track_data(job_id: str, frame_idx: int) -> list:
 
 def set_track_data(job_id: str, frame_idx: int, tracks: list) -> None:
     get_job_storage().set_track_data(job_id, frame_idx, tracks)
+
+def get_track_summary(job_id: str) -> dict:
+    return get_job_storage().get_track_summary(job_id)