feat: add baseline drift history and trending

[tom-bot-for-rana]

Problem

Teams have no visibility into drift trends over time. Is drift increasing? Did a particular component become more unstable? SnapDrift tells you about the current state but not the trajectory.

Proposal

Store a drift history file (default: `.snapdrift/history.json`) that tracks per-route mismatch ratios across runs. Expose as a simple trend chart in the HTML report.

Data Model

{
  "version": 1,
  "runs": [
    {
      "timestamp": "2026-04-17T10:00:00.000Z",
      "sha": "abc1234",
      "routes": {
        "home-desktop": { "mismatchRatio": 0.002, "status": "clean" },
        "dashboard": { "mismatchRatio": 0.008, "status": "changed" }
      }
    }
  ]
}

HTML Report Addition

Each route in the drift signals table gets a small trend indicator:

• 📈 increasing drift (last 3 runs going up)
• 📉 decreasing drift (last 3 runs going down)
• ➡️ stable (flat)

Config

Optional history config:

{
  "history": {
    "enabled": true,
    "path": ".snapdrift/history.json",
    "maxRuns": 100
  }
}

Default: `enabled: true`, path: `.snapdrift/history.json` (local CLI), no default for GitHub Actions (opt-in).

Implementation Plan

1. History module (lib/drift-history.mjs) — new file

• `loadHistory(path)`: read and parse history file, return data or empty structure
• `saveHistory(path, run)`: append a run entry, trim to `maxRuns`
• `getTrend(routeId, runs)`: compute trend (increasing/decreasing/stable) from last N runs
• `getTrendColor(trend)`: return emoji string

2. Comparison flow updates

• In `generateDriftReport`, after computing the summary, record a history entry if `history.enabled`
• In GitHub Actions, write to a configurable path (e.g., `qa-artifacts/snapdrift/history.json`)
• In local CLI, write to `.snapdrift/history.json`

3. HTML report updates (lib/report.mjs)

• Add trend indicators to the drift signals table
• Add a "Drift trend" section with a simple ASCII/emoji trend chart for each changed route
• Show the last 5 runs per route with mismatch ratios

4. PR comment updates (lib/pr-comment.mjs)

• Add trend arrow per changed route in the drift signals table
• Example: `| home-desktop | desktop | 📈 0.012 | 2.47% |`

5. Type definitions

• Add `HistoryRun` and `DriftHistory` interfaces to `types/visual-diff-types.d.ts`
• Add `history?: { enabled?: boolean; path?: string; maxRuns?: number }` to config

6. Tests

• `drift-history.test.js`: test load/save/trend computation
• `compare-results.test.js`: test that history entry is recorded
• `report.test.js`: test trend indicators in HTML output
• `pr-comment.test.js`: test trend arrows in PR comment

7. Documentation

• `docs/contracts.md`: add `history` config section
• `docs/integration-guide.md`: add history example
• `docs/local-cli.md`: explain `.snapdrift/history.json`
• `CHANGELOG.md`: add entry under Unreleased

Acceptance Criteria

• History file loads and saves correctly
• Trend computation (increasing/decreasing/stable) is correct
• Trend indicators appear in HTML report
• Trend arrows appear in PR comment
• Configurable path and max runs
• GitHub Actions writes to configurable path (opt-in)
• Types updated
• Tests added and passing
• Docs updated
• `npm run ci` passes on the branch