Grade Trends & History Snapshots

IC Insight maintains a history of your grade over time for every course. These snapshots power the sparklines on Dashboard cards and the full history chart in the Details View.

---

What is a Snapshot?

A snapshot is a timestamped record of a course's overall grade percentage at a point in time. Snapshot format (version 3):

{
  "id": "snapshot_1699999999_abc123xyz",
  "capturedAtISO": "2024-11-15T10:30:00.000Z",
  "courseTitle": "AP CALCULUS BC",
  "userInitiated": true,
  "version": 3,
  "summary": {
    "overallPercent": 94.28
  },
  "quarters": [...],
  "categories": [...]
}

---

How Snapshots Are Captured

Manual Capture (via Cache button)

When you click Cache on the overlay panel, IC Insight:

1. Re-computes the course grade from the live page DOM.
2. Saves the grade snapshot to chrome.storage.local as a cache entry.
3. Captures a manual history snapshot (marked userInitiated: true).
4. Manual snapshots are always preserved - they are never deduplicated or removed.

Automatic Capture (via Dashboard)

Every time the Dashboard page loads and renders course cards, it automatically captures a snapshot for every course using the grade already computed for the card. These are marked userInitiated: false.

Auto-snapshots are deduplicated to avoid filling storage with identical entries:

• Consecutive auto-snapshots with the same grade signature (courseTitle:XX.XX) are collapsed - only the first occurrence and the transition point are kept.
• A manual snapshot always resets the deduplication chain, so the next auto-snapshot is always kept regardless of whether the grade changed.

---

Deduplication Algorithm

Input: all snapshots sorted chronologically
Output: deduplicated snapshot list

result = [snapshots[0]]  // always keep first

for i = 1 to length-1:
  curr = snapshots[i]
  prev = snapshots[i-1]

  if curr.userInitiated:
    keep  // always keep manual snapshots
  else if signature(curr) != signature(prev) OR prev.userInitiated:
    keep  // grade changed, or previous was a reset point
  else:
    discard  // consecutive duplicate auto-snapshot

The signature is "courseTitle:XX.XX" where the percentage is rounded to 2 decimal places.

---

Storage

All snapshots for all courses are stored under a single key:

ICI_HISTORY_SNAPSHOTS → {
  "course:12345": [ snapshot, snapshot, ... ],
  "course:67890": [ snapshot, snapshot, ... ],
  ...
}

Snapshots within each course array are sorted ascending by capturedAtISO. There is no size limit - unlimited history is stored.

---

Sparklines (Dashboard)

Each course card on the Dashboard shows a 32 px-tall <canvas> sparkline if the course has history snapshots. The sparkline is a simplified line chart showing the overall grade trend. It is rendered by charts.js using shaped data from TrendsEngine.shapeTimeSeriesData().

---

Full Chart (Details View)

The Details View renders a full-size time-series chart for the course. Hovering over data points shows the exact date and grade percentage for that snapshot.

---

Deleting Snapshots

In the Details View, individual snapshots can be deleted. Deleting all snapshots for a course removes its sparkline and chart. The HistorySnapshots.deleteAllSnapshotsForCourse(courseKey) function is called when a course is fully deleted from the Dashboard.