feat(pixel): add scroll depth auto-capture (SDK-136)

[bkbooth]

Summary

• Adds automatic scroll depth milestone tracking (25%, 50%, 75%, 90%, 100%) to the pixel's autocapture system
• Fires scroll_depth TrackMessage events, throttled via requestAnimationFrame with a passive scroll listener for zero performance impact
• For above-the-fold pages (no scroll possible), fires depth: 100 with aboveFold: true after a 2-second dwell to filter out immediate bounces
• Controlled by autocapture.scroll toggle (default: true), consistent with existing forms and clicks options
• Bundle size: 5.7 KB gzipped (was ~5.3 KB) — well within the 10 KB budget

Event schema

{
  type: 'track',
  eventName: 'scroll_depth',
  properties: {
    depth: 50,            // 25 | 50 | 75 | 90 | 100
    aboveFold: true,      // only present on above-the-fold pages
    sessionId: '...'
  }
}

Design decisions

Decision	Rationale
5 milestones (25/50/75/90/100)	Industry standard thresholds for scroll depth tracking
requestAnimationFrame throttle	~60fps cap, passive listener, zero layout impact
2s dwell for above-fold	Filters immediate bounces while capturing genuine engagement
aboveFold: true flag	Lets downstream analytics distinguish "scrolled to bottom" from "all content visible"
Single depth: 100 for above-fold	No intermediate milestones — user didn't scroll, content was just short

Linear

• SDK-135 — Parent: Automatic scroll depth tracking for Tracking Pixel
• SDK-136 — This PR: Implement scroll depth auto-capture
• SDK-137 — Follow-up: Documentation updates (Confluence + docs site)

Test plan

• All existing 73 autocapture tests pass (no regressions)
• 16 new scroll depth tests covering:
  • Milestone firing at 25/50/75/90/100%
  • Multiple milestones in a single scroll jump
  • No re-firing of already-reached milestones
  • Above-the-fold: fires after 2s dwell, not before
  • Above-the-fold: consent check at dwell timer fire time
  • Teardown cleans up scroll listener and dwell timer
  • autocapture.scroll: false disables tracking
  • Default-on behavior verified via direct setupAutocapture({}) call
  • requestAnimationFrame throttle verified
  • Initial scroll position check on setup
• Lint passes (zero warnings)
• Bundle: 5.7 KB gzipped (under 8 KB warning, under 10 KB limit)

🤖 Generated with Claude Code

[nx-cloud]

View your CI Pipeline Execution ↗ for commit ed36a1f

Command	Status	Duration	Result
nx run-many -p @imtbl/sdk,@imtbl/checkout-widge...	✅ Succeeded	3s	View ↗
nx affected -t build,lint,test	✅ Succeeded	7s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-04-16 02:59:31 UTC

[github-actions]

✅ Pixel Bundle Size — @imtbl/pixel

Metric	Size	Delta vs main
Gzipped	5782 bytes (5.64 KB)	+370 bytes
Raw (minified)	15523 bytes	+782 bytes

Budget: 10.00 KB gzipped (warn at 8.00 KB)