feat: Add bot detection and enhanced engagement tracking

- Detect bot-like behavior (webdriver, missing language, etc.)
- Track scroll depth (25%, 50%, 75%)
- Track time on page (10+ seconds threshold)
- Track all meaningful clicks
- Add user properties (screen res, timezone, bot flag)
- Filter real users from bots in GA4 reports
- Add comprehensive documentation

This enables:
✓ Distinguishing real users from automated traffic
✓ Measuring meaningful engagement vs vanity metrics
✓ Identifying calculator abandonment points
✓ Tracking user journey through the site
✓ Better ROI measurement for marketing efforts

See GA4_ENHANCEMENTS.md for full details.

GA4_ENHANCEMENTS.md

@@ -0,0 +1,152 @@
+# GA4 Enhancements - Bot Detection & Engagement Tracking
+
+## Overview
+This PR adds comprehensive GA4 event tracking with bot detection to distinguish real users from automated traffic and measure meaningful engagement.
+
+## What's Added
+
+### 1. ROI Calculator Tracking
+- **`calculator_open`** - User opens the calculator modal
+- **`calculator_submit`** - User submits the form (with anonymized homesites/reserve data)
+- **`calculator_success`** - Results successfully displayed
+- **`calculator_error`** - API or validation error occurred
+
+### 2. Bot Detection
+Automatically flags likely bot traffic based on:
+- `navigator.webdriver` detection (Selenium, Puppeteer, etc.)
+- Missing language settings
+- Invalid screen dimensions
+- Automated browsing patterns
+
+**Custom Dimension:** `is_likely_bot` (true/false)
+
+### 3. Engagement Tracking
+- **Scroll Depth:** 25%, 50%, 75% milestones
+- **Time on Page:** Tracks if user stays 10+ seconds
+- **Click Tracking:** All meaningful button/link clicks
+- **Screen Resolution:** Captured as user property
+- **Timezone:** Captured as user property
+
+## How to Identify Real Users in GA4
+
+### Method 1: Filter by Bot Flag
+```
+Filter: user_properties.is_likely_bot == 'false'
+```
+
+### Method 2: Engagement Thresholds
+Real users typically:
+- ✅ Scroll at least 25% of the page
+- ✅ Stay on page 10+ seconds
+- ✅ Click at least one element
+- ✅ Have valid screen resolution
+- ✅ Open calculator AND submit form
+
+### Method 3: Event Sequence
+Real user pattern:
+```
+page_view → scroll_25 → calculator_open → calculator_submit → calculator_success
+```
+
+Bot pattern:
+```
+page_view → (no further events) OR page_view → calculator_submit (instant)
+```
+
+## GA4 Reports Location
+
+### Real-Time Testing
+- **Reports** → Realtime → Event count
+- Watch events as they happen
+- Filter by `event_name` to see specific events
+
+### Historical Data
+- **Reports** → Engagement → Events
+- **Reports** → Engagement → Pages (filter by calculator page)
+- **Explore** → Create custom exploration with:
+  - Dimensions: Event name, User properties, Engagement metrics
+  - Metrics: Event count, Total users, Engagement rate
+
+### Bot Filtering in GA4
+Create audience:
+```
+Include: user_properties.is_likely_bot == 'false'
+AND
+Include: scroll_25 OR scroll_50 OR scroll_75
+AND
+Include: time_on_page >= 10
+```
+
+## Data Privacy
+- ✅ No PII tracked (no email, name, IP addresses)
+- ✅ Form values anonymized (only numeric ranges)
+- ✅ Compliant with GA4 data retention policies
+- ✅ Bot detection uses only browser-provided properties
+
+## Testing Instructions
+
+### 1. Verify Bot Detection
+Open homepage and check browser console:
+```
+✓ Enhanced GA4 tracking active
+```
+
+### 2. Test Calculator Events
+1. Open calculator modal → Console: `✓ GA4: calculator_open event sent`
+2. Submit form → Console: `✓ GA4: calculator_submit event sent`
+3. View results → Console: `✓ GA4: calculator_success event sent`
+
+### 3. Test Engagement Tracking
+1. Scroll page → Console: `✓ GA4: scroll_25/50/75 event sent`
+2. Click buttons → Console: `✓ GA4: click event sent`
+3. Wait 10+ seconds, then leave → Console: `✓ GA4: time_on_page event sent`
+
+### 4. Verify in GA4
+1. Go to GA4 → Realtime
+2. You should see events appearing within 30 seconds
+3. Check "User properties" for `is_likely_bot` dimension
+
+## Expected Results
+
+### Before Enhancement
+- Total sessions: 146 (30 days)
+- Bot vs Real: Unknown
+- Calculator usage: Unknown
+- Engagement: Unknown
+
+### After Enhancement
+- Total sessions: [same]
+- Bot sessions: Filtered out
+- Real user sessions: Clear count
+- Calculator opens: Exact count
+- Calculator submissions: Exact count
+- Submission rate: Calculated
+- Engagement rate: Calculated
+
+## Troubleshooting
+
+### Events Not Appearing
+1. Check browser console for errors
+2. Verify GA4 property ID is correct (G-RTWNVXPMRF)
+3. Check if ad blockers are blocking gtag
+4. Wait up to 24 hours for data to appear in reports
+
+### Bot Detection False Positives
+Some privacy-focused users may be flagged:
+- Users with JavaScript disabled
+- Users with Tor/VPN
+- Users with unusual screen setups
+
+These can be filtered manually in GA4 explorations.
+
+## Future Enhancements
+- [ ] Add conversion tracking (calculator → contact form)
+- [ ] Track calculator abandonment rate
+- [ ] Add funnel visualization in GA4
+- [ ] Create automated alerts for low engagement
+- [ ] Integrate with CRM to track lead quality
+
+---
+**PR Branch:** feature/add-ga4-calculator-tracking  
+**Author:** AI Assistant  
+**Date:** 2026-03-29