SubMiner/backlog/tasks/task-40 - Add-vocab-heatmap-and-comprehension-dashboard-for-immersion-sessions.md

id, title, status, assignee, created_date, labels, dependencies, priority

id	title	status	assignee	created_date	labels	dependencies	priority
TASK-40	Add vocab heatmap and comprehension dashboard for immersion sessions	To Do		2026-02-14 02:06	feature analytics immersion visualization	TASK-28	medium

Description

Build a visual comprehension dashboard that renders per-video "comprehension heatmaps" showing which segments had high lookup density versus segments where the user understood everything without lookups.

Motivation

Immersion tracking data (TASK-28) captures lookup counts, words seen, and cards mined per time segment. Visualizing this data gives learners a powerful way to see their progress: early episodes of a show will be "hot" (many lookups), while later episodes should cool down as vocabulary grows.

Features

1. Per-video heatmap: A timeline bar colored by lookup density (green = understood, yellow = some lookups, red = many lookups)
2. Cross-video trends: Show comprehension improvement across episodes of the same series
3. Session summary cards: After each session, show a summary with key metrics (time watched, words seen, cards mined, comprehension estimate)
4. Historical comparison: Compare the same video rewatched at different dates
5. Export: Generate a shareable image or markdown summary

Data sources

• imm_session_telemetry (lookup_count, words_seen per sample interval)
• imm_session_events (individual lookup events with timestamps)
• imm_daily_rollups / imm_monthly_rollups for trend data

Implementation notes

• Could be rendered in a dedicated Electron window or an overlay modal
• Use canvas or SVG for the heatmap visualization
• Consider a simple HTML report that can be opened in a browser for sharing
• Heatmap granularity should match telemetry sample interval

Acceptance Criteria

• #1 Per-video heatmap renders a timeline colored by lookup density.
• #2 Cross-video trend view shows comprehension change across episodes.
• #3 Session summary displays time watched, words seen, cards mined, and comprehension estimate.
• #4 Dashboard data is sourced from TASK-28 immersion tracking tables.
• #5 Visualization is exportable as an image or shareable format.
• #6 Dashboard does not block or slow down active mining sessions.