Add passive page-load beacon

The worker previously only wrote analytics rows on user-triggered
actions (chat, council, summary, playback). There was no event
between page render and the first interaction, so a "landed and
bounced" session was indistinguishable from "never reached the
page at all".

- New /v1/page endpoint on agora-cosmica-llm: anonymous, no auth,
  IP rate-limited (100/h), validates path against a tight regex,
  writes a row with index1='page' to agora_llm.
- New client beacon at utils/pageBeacon.ts mirrors playbackBeacon:
  fires once at module load from index.tsx, right after captureGclid().
- Path is the only added blob slot. Slots 4-7 stay aligned with the
  existing schema (language, status, marketing_source, country) so
  dashboard queries can aggregate page rows the same way.
- MEASUREMENT.md updated to disclose the new endpoint + path field.

Author: michael-chipmates

client/src/index.tsx

@@ -12,12 +12,19 @@ import { useDomainStore } from './stores/domainStore';
 import { initializeSeedsCache } from './services/seedCacheInitializer';
 import { LocalStorageAdapter } from './storage/localAdapter';
 import { captureGclid } from './utils/public/gclidCapture';
+import { sendPageBeacon } from './utils/pageBeacon';
 
 // Capture utm_source / gclid from the landing URL before any router redirect
 // can strip them. Must run synchronously at module load — running inside a
 // React effect is too late, because the catch-all <Navigate> in App.tsx
 // rewrites the URL before App's effect fires.
 captureGclid();
+
+// Page-load beacon: count this arrival in analytics with the marketing source
+// captureGclid just resolved. Anonymous, fire-and-forget. Closes the gap
+// between landing-page render and the existing engagement events (chat,
+// playback) so we can measure true bounce rate per channel.
+sendPageBeacon();
 // Service Worker registration (DISABLED until Q1 2026 - Offline Mode implementation)
 // Currently causes 404 errors since service-worker.js doesn't exist yet
 // Roadmap: CLAUDE.md Q1 2026 - Offline Mode with service worker

client/src/utils/pageBeacon.ts

@@ -0,0 +1,63 @@
+// Anonymous page-load beacon
+// Fires once at App module load (from index.tsx) so we count arrivals,
+// not just post-engagement events. Same fire-and-forget posture as the
+// playback beacon — see utils/playbackBeacon.ts.
+//
+// Privacy: aggregate counter only. No user dimension. No IP retention.
+// Disclosed in docs/MEASUREMENT.md alongside the other event counters.
+
+import { getMarketingSource } from './public/gclidCapture';
+
+const API_BASE = import.meta.env.VITE_FREE_TIER_API_URL || '';
+
+/**
+ * Detect the current UI language from the document or localStorage. Mirrors
+ * the playbackBeacon helper so language labels stay consistent across event
+ * types. Falls back to 'en' if nothing is set.
+ */
+function detectLanguage(): 'en' | 'de' {
+  try {
+    const docLang = typeof document !== 'undefined' ? document.documentElement.lang : '';
+    if (docLang && docLang.toLowerCase().startsWith('de')) return 'de';
+    const stored = typeof localStorage !== 'undefined' ? localStorage.getItem('language') : null;
+    if (stored && stored.toLowerCase().startsWith('de')) return 'de';
+    if (typeof navigator !== 'undefined' && navigator.language && navigator.language.toLowerCase().startsWith('de')) return 'de';
+  } catch {
+    // Ignore — fall through to 'en'
+  }
+  return 'en';
+}
+
+/**
+ * Send a page-load beacon. Fire-and-forget — never throws, never blocks the
+ * caller, never breaks app boot on network failure. Captures only:
+ *   - path (no query string, validated server-side against a regex)
+ *   - language (en/de)
+ *   - marketing source (X-Marketing-Source header, closed allowlist)
+ *   - country (CF-edge two-letter code, server-side)
+ *
+ * No user dimension, no message content, no fingerprint.
+ */
+export function sendPageBeacon(): void {
+  try {
+    const path = typeof window !== 'undefined' ? window.location.pathname : '';
+    const body = JSON.stringify({
+      path,
+      language: detectLanguage(),
+    });
+
+    fetch(`${API_BASE}/v1/page`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Marketing-Source': getMarketingSource(),
+      },
+      body,
+      keepalive: true,
+    }).catch(() => {
+      // Silent fail — beacons must never surface to the user.
+    });
+  } catch {
+    // Silent fail
+  }
+}

docs/MEASUREMENT.md

@@ -10,7 +10,8 @@ Per anonymous request, written to Cloudflare Analytics Engine:
 
 | Counter | Example values | Why |
 |---|---|---|
-| Endpoint | `chat`, `council`, `summary`, `session`, `speech`, `transcriptions`, `playback` | See which features are used |
+| Endpoint | `chat`, `council`, `summary`, `session`, `speech`, `transcriptions`, `playback`, `page` | See which features are used |
+| Path | Sanitized landing path on `page` events (`/`, `/de/`, `/figures/<slug>`, ...) | Distinguish home arrivals from deep-link arrivals |
 | Figure | `aurelius`, `kahlo`, `rumi`, ... | See which figures resonate |
 | Mode | `story`, `wisdom`, `prism`, `quest`, `freetalk`, `council` | See which chapters land |
 | Language | `en` or `de` | See bilingual reach |

workers/llm-proxy/src/index.ts

@@ -9,6 +9,7 @@ import { handleQuota } from './routes/quota';
 import { handleSummary } from './routes/summary';
 import { handleConversions, handleConversionStats } from './routes/conversions';
 import { handlePlayback } from './routes/playback';
+import { handlePage } from './routes/page';
 import type { Env } from './utils/types';
 
 function getCorsHeaders(request: Request, env: Env): Record<string, string> {
@@ -91,6 +92,8 @@ export default {
         response = await handleConversionStats(request, env);
       } else if (path === '/v1/playback' && request.method === 'POST') {
         response = await handlePlayback(request, env);
+      } else if (path === '/v1/page' && request.method === 'POST') {
+        response = await handlePage(request, env);
       } else {
         response = new Response(
           JSON.stringify({ error: 'Not found' }),

workers/llm-proxy/src/routes/page.ts

@@ -0,0 +1,65 @@
+// Anonymous page-load beacon
+// Fires from the client at App module load, before any user interaction.
+// Counts arrivals (vs. the existing playback/chat events which only fire
+// post-engagement), so we can measure true bounce rate per channel.
+//
+// Privacy: aggregate counter only. No user dimension. No IP retention.
+// Same legal posture as the rest of analytics — see docs/MEASUREMENT.md.
+
+import { trackPageView, readMarketingSource, readCountry } from '../utils/analytics';
+import type { Env } from '../utils/types';
+
+interface PagePayload {
+  path?: string;
+  language?: string;
+}
+
+// Path is sanitized server-side to a safe shape. Anything else becomes empty
+// in blob2 so the row is still recorded but the path slot stays clean.
+const PATH_RE = /^\/[A-Za-z0-9/_-]{0,60}$/;
+const VALID_LANGS = new Set(['en', 'de']);
+
+// Rate limit: 100 page beacons per IP per hour. A real user generates 1-10
+// hard page loads per session; this caps abuse without blocking real use.
+const RATE_LIMIT_WINDOW = 3600;
+const RATE_LIMIT_MAX = 100;
+
+export async function handlePage(request: Request, env: Env): Promise<Response> {
+  if (request.method !== 'POST') {
+    return new Response('Method not allowed', { status: 405 });
+  }
+
+  let payload: PagePayload;
+  try {
+    payload = await request.json();
+  } catch {
+    // Be quiet on malformed beacons — the client doesn't get to know.
+    return new Response(null, { status: 204 });
+  }
+
+  // Rate limit per IP. The IP itself is hashed via KV key namespace and
+  // never retained beyond the 1-hour window.
+  const ip = request.headers.get('CF-Connecting-IP') || 'unknown';
+  const rateLimitKey = `page_rl:${ip}`;
+  const currentCount = parseInt(await env.RATE_LIMITS.get(rateLimitKey) || '0', 10);
+  if (currentCount >= RATE_LIMIT_MAX) {
+    return new Response(null, { status: 204 });
+  }
+  await env.RATE_LIMITS.put(rateLimitKey, String(currentCount + 1), { expirationTtl: RATE_LIMIT_WINDOW });
+
+  const path = (typeof payload.path === 'string' && PATH_RE.test(payload.path))
+    ? payload.path
+    : '';
+  const lang = (typeof payload.language === 'string') && VALID_LANGS.has(payload.language.slice(0, 2).toLowerCase())
+    ? payload.language.slice(0, 2).toLowerCase()
+    : '';
+
+  trackPageView(env, {
+    path,
+    language: lang,
+    marketingSource: readMarketingSource(request),
+    country: readCountry(request),
+  });
+
+  return new Response(null, { status: 204 });
+}

workers/llm-proxy/src/utils/analytics.ts

@@ -146,6 +146,34 @@ export function trackPlayback(
   }
 }
 
+/**
+ * Track a page-load beacon. Fires once on App mount in the client, before any
+ * user interaction. Lets the dashboard show arrivals per channel, not just
+ * post-engagement events.
+ * dataset: agora_llm
+ * blobs: ['page', path, '', language, '200', marketing_source, country]
+ * indexes: ['page']
+ */
+export function trackPageView(
+  env: Env,
+  data: {
+    path: string;
+    language: string;
+    marketingSource: string;
+    country: string;
+  }
+): void {
+  try {
+    env.ANALYTICS.writeDataPoint({
+      blobs: ['page', data.path, '', data.language, '200', data.marketingSource, data.country],
+      doubles: [0],
+      indexes: ['page'],
+    });
+  } catch {
+    // Analytics must never break the request path
+  }
+}
+
 /**
  * Track a rate limit hit (429).
  * dataset: agora_llm