fix(pixel): use ResizeObserver to detect above-fold scroll state (SDK-275)

[bkbooth]

Summary

Fixes SDK-275 — the pixel tracker was firing a false scroll_depth { depth: 100, aboveFold: true } event on long pages when installed on third-party sites.

Root cause: the above-fold determination in autocapture.ts was a synchronous snapshot taken at tracker init time. If the pixel initialised before images or JS-rendered content had expanded the page, scrollHeight could equal innerHeight at that moment — locking in isAboveFold = true and firing the synthetic event ~2s later regardless of how large the page had grown by then.

Fix: replace the one-shot check with a ResizeObserver on document.documentElement that manages the dwell timer reactively. Starts the timer when the page is above-fold, cancels it if the page later grows beyond the viewport, fires once the page has been stably above-fold for the dwell window. Feature-detected so the ~3% of browsers without ResizeObserver skip the synthetic event rather than crashing the rest of autocapture.

See the Linear ticket for the competitive analysis (PostHog, GTM, Segment, robflaherty/scroll-depth) and the option-by-option assessment behind the chosen approach.

Also included

• AGENTS.md for packages/audience/pixel and packages/audience/core flagging the inline-bundling relationship (core is bundled into the pixel CDN snippet via tsup.config.ts alias) and pointing at the CI-enforced size budget. core changes silently affect the pixel's bundle size and there was no way for an agent or new contributor to discover that without reading the build config.

Test plan

• Existing scroll-depth tests pass unchanged
• New test: dwell timer is cancelled when page grows beyond viewport mid-dwell
• New test: setupAutocapture does not throw when ResizeObserver is undefined (graceful degradation)
• Lint clean
• Manual verification on a third-party-style page with images that load post-init (reviewer to confirm in staging if desired)

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes production analytics emission logic for scroll_depth on above-the-fold pages and adds a new dependency on ResizeObserver behavior (with a fallback when unavailable), which could affect event firing timing/volume in the pixel snippet.

Overview
Fixes false scroll_depth { depth: 100, aboveFold: true } events by replacing the one-time “above fold” snapshot with a ResizeObserver-driven check that starts the dwell timer only while the document remains within the viewport and cancels it if the page grows.

Updates tests to stub/mimic ResizeObserver, adds coverage for cancelling the dwell timer on late content expansion, and verifies graceful behavior when ResizeObserver is missing. Also bumps @imtbl/pixel to 0.1.1 and adds AGENTS.md notes documenting the pixel bundle-size budget and that @imtbl/audience-core is bundled inline into the pixel.

^{Reviewed by Cursor Bugbot for commit d6c497f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

✅ Pixel Bundle Size — @imtbl/pixel

Metric	Size	Delta vs main
Gzipped	5884 bytes (5.74 KB)	+89 bytes
Raw (minified)	15885 bytes	+327 bytes

Budget: 10.00 KB gzipped (warn at 8.00 KB)

[nx-cloud]

View your CI Pipeline Execution ↗ for commit d6c497f

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

---

☁️ Nx Cloud last updated this comment at 2026-05-01 02:03:02 UTC

[github-actions]

✅ Audience Bundle Size — @imtbl/audience

Metric	Size	Delta vs main (756ce14)
Gzipped	18249 bytes (17.82 KB)	0 bytes
Raw (minified)	53041 bytes	0 bytes

Budget: 24.00 KB gzipped (warn at 20.00 KB)