keystone-design-bootstrap 1.0.68 → 1.0.70

package/src/design_system/portal/PortalPage.tsx

@@ -267,7 +267,7 @@ function ServicesPanel({
 
   return (
     <>
-      <PortalTabTracker event="ViewContent" params={{ contentName: 'Services', contentCategory: 'Services' }} />
+      <PortalTabTracker event="ViewContent" params={{ contentName: 'Services', contentCategory: 'Services' }} tab="services" />
       <div className="divide-y divide-tertiary rounded-component border border-secondary bg-primary overflow-hidden">
         {activeServices.map((service) => (
           <details key={service.id} className="group">
@@ -321,7 +321,7 @@ function PackagesPanel({
 
   return (
     <>
-      <PortalTabTracker event="ViewContent" params={{ contentName: 'Packages', contentCategory: 'Packages' }} />
+      <PortalTabTracker event="ViewContent" params={{ contentName: 'Packages', contentCategory: 'Packages' }} tab="packages" />
       <div className="grid gap-4 sm:grid-cols-2">
         {packages.map((pkg) => {
           const activeOffers = (pkg.offers ?? []).filter((o) => o.active !== false && !o.expired);
@@ -406,7 +406,7 @@ function SpecialsPanel({ specials }: { specials: SpecialItem[] }) {
 
   return (
     <>
-      <PortalTabTracker event="ViewContent" params={{ contentName: 'Specials', contentCategory: 'Specials' }} />
+      <PortalTabTracker event="ViewContent" params={{ contentName: 'Specials', contentCategory: 'Specials' }} tab="specials" />
       <div className="space-y-3">
         {specials.map((special) => (
           <div key={special.id} className="group flex items-start gap-3 rounded-component border border-secondary bg-primary px-4 py-4">
@@ -524,7 +524,7 @@ function BookPanel({
   if (bookingAllowsIframe) {
     return (
       <>
-        <PortalTabTracker event="InitiateCheckout" />
+        <PortalTabTracker event="InitiateCheckout" tab="booking" />
         <BookIframePanel bookingHref={bookingHref} businessName={businessName} />
       </>
     );
@@ -532,7 +532,7 @@ function BookPanel({
 
   return (
     <>
-      <PortalTabTracker event="InitiateCheckout" />
+      <PortalTabTracker event="InitiateCheckout" tab="booking" />
       <div className="flex flex-col items-center justify-center py-20 text-center">
         <div className="mb-4 flex h-12 w-12 items-center justify-center rounded-full bg-secondary">
           <svg className="size-5 text-quaternary" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={1.5}>

package/src/design_system/portal/PortalTabTracker.tsx

@@ -2,21 +2,29 @@
 
 import { useEffect } from 'react';
 import { firePixelEvent } from '../../tracking/firePixelEvent';
+import { captureEvent } from '../../tracking/captureEvent';
 import type { PixelEvent, PixelEventParams } from '../../tracking/firePixelEvent';
 
 interface Props {
   event: PixelEvent;
   params?: PixelEventParams;
+  /** Human-readable tab name for PostHog (e.g. 'booking', 'appointments', 'membership'). */
+  tab: string;
 }
 
 /**
- * Fires a pixel event once when a portal tab mounts.
+ * Fires tracking events once when a portal tab mounts.
  * Placed at the root of each tab panel so it fires on both direct navigation
  * and post-login redirect to that tab.
+ *
+ * Fires:
+ * - Meta Pixel: the provided `event` (e.g. ViewContent, InitiateCheckout)
+ * - PostHog: portal_tab_viewed with the tab name
  */
-export function PortalTabTracker({ event, params }: Props) {
+export function PortalTabTracker({ event, params, tab }: Props) {
   useEffect(() => {
     firePixelEvent(event, params);
+    captureEvent('portal_tab_viewed', { tab });
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 

package/src/design_system/sections/contact-section-form.aman.tsx

@@ -4,6 +4,7 @@ import React, { useRef, useState } from 'react';
 import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import { firePixelEvent, setPixelUserData } from '../../tracking/firePixelEvent';
+import { captureEvent } from '../../tracking/captureEvent';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
 
@@ -63,14 +64,18 @@ export const ContactSectionForm = ({
                 onSuccess?.();
                 await setPixelUserData({ email: data.email, phone: data.phone });
                 firePixelEvent('Lead', undefined, result.eventId);
+                captureEvent('form_submitted', { form_type: 'lead', ...(result.eventId && { event_id: result.eventId }) });
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'lead', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again later.');
+            captureEvent('form_failed', { form_type: 'lead', error: 'network_error' });
         }
         setIsSubmitting(false);
     };

package/src/design_system/sections/contact-section-form.balance.tsx

@@ -4,6 +4,7 @@ import React, { useRef, useState } from 'react';
 import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import { firePixelEvent, setPixelUserData } from '../../tracking/firePixelEvent';
+import { captureEvent } from '../../tracking/captureEvent';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
 
@@ -63,14 +64,18 @@ export const ContactSectionForm = ({
                 onSuccess?.();
                 await setPixelUserData({ email: data.email, phone: data.phone });
                 firePixelEvent('Lead', undefined, result.eventId);
+                captureEvent('form_submitted', { form_type: 'lead', ...(result.eventId && { event_id: result.eventId }) });
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'lead', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again later.');
+            captureEvent('form_failed', { form_type: 'lead', error: 'network_error' });
         }
         setIsSubmitting(false);
     };

package/src/design_system/sections/contact-section-form.barelux.tsx

@@ -4,6 +4,7 @@ import React, { useRef, useState } from 'react';
 import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import { firePixelEvent, setPixelUserData } from '../../tracking/firePixelEvent';
+import { captureEvent } from '../../tracking/captureEvent';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
 
@@ -63,14 +64,18 @@ export const ContactSectionForm = ({
                 onSuccess?.();
                 await setPixelUserData({ email: data.email, phone: data.phone });
                 firePixelEvent('Lead', undefined, result.eventId);
+                captureEvent('form_submitted', { form_type: 'lead', ...(result.eventId && { event_id: result.eventId }) });
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'lead', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again later.');
+            captureEvent('form_failed', { form_type: 'lead', error: 'network_error' });
         }
         setIsSubmitting(false);
     };

package/src/design_system/sections/contact-section-form.tsx

@@ -4,6 +4,7 @@ import React, { useRef, useState } from 'react';
 import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import { firePixelEvent, setPixelUserData } from '../../tracking/firePixelEvent';
+import { captureEvent } from '../../tracking/captureEvent';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
 
@@ -71,14 +72,18 @@ export const ContactSectionForm = ({
                 onSuccess?.();
                 await setPixelUserData({ email: data.email, phone: data.phone });
                 firePixelEvent('Lead', undefined, result.eventId);
+                captureEvent('form_submitted', { form_type: 'lead', ...(result.eventId && { event_id: result.eventId }) });
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'lead', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again later.');
+            captureEvent('form_failed', { form_type: 'lead', error: 'network_error' });
         }
         setIsSubmitting(false);
     };

package/src/design_system/sections/email-signup-section.tsx

@@ -5,6 +5,7 @@ import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
+import { captureEvent } from '../../tracking/captureEvent';
 
 export interface EmailSignupSectionProps {
     title?: string;
@@ -54,14 +55,18 @@ export const EmailSignupSection = ({
                 setSubmitStatus('success');
                 setStatusMessage(result.message || successMessage);
                 formRef.current?.reset();
+                captureEvent('form_submitted', { form_type: 'marketing_list_signup' });
                 setTimeout(() => setSubmitStatus('idle'), 6000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'marketing_list_signup', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again later.');
+            captureEvent('form_failed', { form_type: 'marketing_list_signup', error: 'network_error' });
         }
 
         setIsSubmitting(false);

package/src/design_system/sections/header-navigation.aman.tsx

@@ -57,7 +57,12 @@ export function HeaderNavigation({
   
   // Use navigation from config or override
   const navigation = navigationOverride || config?.navigation?.header || [];
-  const ctaUrls = resolveCtaUrls(companyInformation);
+  const resolvedCtaUrls = resolveCtaUrls(companyInformation);
+  const ctaUrls = {
+    primaryHref: props?.cta_button?.secondary_href ?? resolvedCtaUrls.primaryHref,
+    secondaryHref: props?.cta_button?.href ?? resolvedCtaUrls.secondaryHref,
+    hasSecondary: props?.cta_button?.secondary_href != null || resolvedCtaUrls.hasSecondary,
+  };
 
   // Hide the sticky bottom bar when the user is already on the portal page —
   // the portal has its own Book Now tab so the bar is redundant and confusing.

package/src/design_system/sections/header-navigation.balance.tsx

@@ -36,7 +36,12 @@ export function HeaderNavigation({
   const companyName = logoTextOverride || companyInformation?.company_name || props?.logo?.text || '';
   
   const navigation = navigationOverride || config?.navigation?.header || [];
-  const ctaUrls = resolveCtaUrls(companyInformation);
+  const resolvedCtaUrls = resolveCtaUrls(companyInformation);
+  const ctaUrls = {
+    primaryHref: props?.cta_button?.secondary_href ?? resolvedCtaUrls.primaryHref,
+    secondaryHref: props?.cta_button?.href ?? resolvedCtaUrls.secondaryHref,
+    hasSecondary: props?.cta_button?.secondary_href != null || resolvedCtaUrls.hasSecondary,
+  };
 
   // Hide the sticky bottom bar when the user is already on the portal page —
   // the portal has its own Book Now tab so the bar is redundant and confusing.

package/src/design_system/sections/header-navigation.barelux.tsx

@@ -42,7 +42,12 @@ export function HeaderNavigation({
     
     // Use navigation from config or override
     const navigation = navigationOverride || config?.navigation?.header || [];
-    const ctaUrls = resolveCtaUrls(companyInformation);
+    const resolvedCtaUrls = resolveCtaUrls(companyInformation);
+    const ctaUrls = {
+        primaryHref: props?.cta_button?.secondary_href ?? resolvedCtaUrls.primaryHref,
+        secondaryHref: props?.cta_button?.href ?? resolvedCtaUrls.secondaryHref,
+        hasSecondary: props?.cta_button?.secondary_href != null || resolvedCtaUrls.hasSecondary,
+    };
 
     // Hide the sticky bottom bar when the user is already on the portal page —
     // the portal has its own Book Now tab so the bar is redundant and confusing.

package/src/design_system/sections/header-navigation.tsx

@@ -99,7 +99,12 @@ export function HeaderNavigation({
   const logoImage = logoImageOverride || getLogoUrl(websitePhotos) || props?.logo?.image;
   const logoText = logoTextOverride || companyInformation?.company_name || props?.logo?.text || '';
   const cta_button = props?.cta_button;
-  const ctaUrls = resolveCtaUrls(companyInformation);
+  const resolvedCtaUrls = resolveCtaUrls(companyInformation);
+  const ctaUrls = {
+    primaryHref: cta_button?.secondary_href ?? resolvedCtaUrls.primaryHref,
+    secondaryHref: cta_button?.href ?? resolvedCtaUrls.secondaryHref,
+    hasSecondary: cta_button?.secondary_href != null || resolvedCtaUrls.hasSecondary,
+  };
   
   const logo = {
     text: logoText || '',

package/src/design_system/sections/job-application-form.aman.tsx

@@ -5,6 +5,7 @@ import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
+import { captureEvent } from '../../tracking/captureEvent';
 
 interface JobApplicationFormAmanProps {
     jobSlug: string;
@@ -47,14 +48,18 @@ export const JobApplicationForm = ({ jobSlug, formDefinition, inline = false }:
                 setSubmitStatus('success');
                 setStatusMessage(result.message || "Thank you for applying! We'll be in touch soon.");
                 formRef.current?.reset();
+                captureEvent('form_submitted', { form_type: 'job_application' });
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'job_application', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again.');
+            captureEvent('form_failed', { form_type: 'job_application', error: 'network_error' });
         }
         setIsSubmitting(false);
     };

package/src/design_system/sections/job-application-form.barelux.tsx

@@ -5,6 +5,7 @@ import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
+import { captureEvent } from '../../tracking/captureEvent';
 
 interface JobApplicationFormBareluxProps {
     jobSlug: string;
@@ -47,14 +48,18 @@ export const JobApplicationForm = ({ jobSlug, formDefinition, inline = false }:
                 setSubmitStatus('success');
                 setStatusMessage(result.message || "Thank you for applying! We'll be in touch soon.");
                 formRef.current?.reset();
+                captureEvent('form_submitted', { form_type: 'job_application' });
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'job_application', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again.');
+            captureEvent('form_failed', { form_type: 'job_application', error: 'network_error' });
         }
         setIsSubmitting(false);
     };

package/src/design_system/sections/job-application-form.tsx

@@ -5,6 +5,7 @@ import { Form, Button } from '../elements';
 import { DynamicFormFields } from '../components/DynamicFormFields';
 import type { FormDefinition } from '../../types/api/form';
 import { useFormDefinitions } from '../../next/contexts/form-definitions';
+import { captureEvent } from '../../tracking/captureEvent';
 
 interface JobApplicationFormProps {
     jobSlug: string;
@@ -50,14 +51,18 @@ export const JobApplicationForm = ({ jobSlug, formDefinition, inline = false }:
                 setSubmitStatus('success');
                 setStatusMessage(result.message || "Thank you for applying! We'll be in touch soon.");
                 formRef.current?.reset();
+                captureEvent('form_submitted', { form_type: 'job_application' });
                 setTimeout(() => setSubmitStatus('idle'), 5000);
             } else {
+                const errorMsg = result.error || 'Something went wrong. Please try again.';
                 setSubmitStatus('error');
-                setStatusMessage(result.error || 'Something went wrong. Please try again.');
+                setStatusMessage(errorMsg);
+                captureEvent('form_failed', { form_type: 'job_application', error: errorMsg });
             }
         } catch {
             setSubmitStatus('error');
             setStatusMessage('Network error. Please try again.');
+            captureEvent('form_failed', { form_type: 'job_application', error: 'network_error' });
         }
         setIsSubmitting(false);
     };

package/src/lib/server-api.ts

@@ -78,6 +78,24 @@ export function getMetaPixelId(adsConfig: { meta_pixel_id?: string } | null | un
   return str !== '' && str !== 'null' && /^\d+$/.test(str) ? str : null;
 }
 
+export type AnalyticsConfig = {
+  /** PostHog project API key — platform-wide, from POSTHOG_API_KEY env var on the Rails server. */
+  posthog_api_key?: string;
+};
+
+/** Analytics config for customer sites. Returns platform-wide analytics keys (e.g. PostHog). */
+export async function getAnalyticsConfig(): Promise<AnalyticsConfig | null> {
+  const data = await serverFetch<AnalyticsConfig>('/public/analytics_config', defaultOptions);
+  return data ?? null;
+}
+
+/** Extract PostHog API key from analytics config for use with <PostHogProvider apiKey={...} />. */
+export function getPostHogApiKey(analyticsConfig: AnalyticsConfig | null | undefined): string | null {
+  const key = analyticsConfig?.posthog_api_key;
+  const str = key != null && key !== '' ? String(key).trim() : '';
+  return str !== '' && str !== 'null' ? str : null;
+}
+
 export async function getServices(): Promise<Service[] | null> {
   return serverFetch<Service[]>('/public/services', defaultOptions);
 }

package/src/next/layouts/root-layout.tsx

@@ -3,7 +3,7 @@ import type { Metadata } from 'next';
 
 import { HeaderNavigation, FooterHome } from '../../design_system/sections';
 import { ThemeProvider } from '../../contexts';
-import { MetaPixel, MetaPixelTracker } from '../../tracking';
+import { MetaPixel, MetaPixelTracker, PostHogProvider, KeystoneAnalyticsTracker } from '../../tracking';
 import { ChatWidget } from '../../design_system/components/ChatWidget';
 import { FormDefinitionsProvider } from '../contexts/form-definitions';
 import { KeystoneSSRProvider } from '../providers/ssr-provider';
@@ -16,6 +16,8 @@ import {
   getForm,
   getAdsConfig,
   getMetaPixelId,
+  getAnalyticsConfig,
+  getPostHogApiKey,
 } from '../../lib/server-api';
 
 import type { CompanyInformation, Location, NavItem, Service, SiteConfig } from '../../types';
@@ -26,8 +28,18 @@ export type KeystoneRootLayoutHeaderOverrides = {
   logoText?: string;
   /** Overrides the primary CTA button label (default: "Contact Us") */
   ctaLabel?: string;
+  /**
+   * Overrides the href for the left ("Contact Us") header button.
+   * Defaults to `/contact`. Only relevant when two CTA buttons are shown.
+   */
+  ctaHref?: string;
   /** Overrides the secondary CTA button label (default: "Book Now" when a booking/portal URL is configured) */
   secondaryLabel?: string;
+  /**
+   * Overrides the href for the right ("Book Now") header button.
+   * When set, forces both CTA buttons to appear even if no external booking/portal URL is configured.
+   */
+  secondaryHref?: string;
 };
 
 export type KeystoneRootLayoutOptions = {
@@ -35,6 +47,13 @@ export type KeystoneRootLayoutOptions = {
   headerOverrides?: KeystoneRootLayoutHeaderOverrides;
   /** Chat widget position */
   chatPosition?: 'bottom-right' | 'bottom-left';
+  /**
+   * PostHog ingest host. Defaults to `https://us.i.posthog.com`.
+   * Override when self-hosting or using the EU cloud (`https://eu.i.posthog.com`).
+   * The API key is fetched automatically from the Rails analytics_config endpoint
+   * (set POSTHOG_API_KEY on the Rails server — no client-side env var needed).
+   */
+  posthogHost?: string;
 };
 
 function buildNavigationWithDynamicData(
@@ -91,7 +110,7 @@ function buildNavigationWithDynamicData(
  * Note: Next's `export const metadata` must remain in the site/app.
  * This component focuses on:
  * - fetching shared data
- * - injecting Meta Pixel
+ * - injecting Meta Pixel (from ads_config) and PostHog (from analytics_config)
  * - applying theme
  * - rendering Header + Footer
  * - rendering ChatWidget gated by `companyInformation.chat_enabled`
@@ -113,6 +132,7 @@ export async function KeystoneRootLayout(props: {
     jobApplicationFormDefinition,
     marketingListSignupFormDefinition,
     adsConfig,
+    analyticsConfig,
   ] =
     await Promise.all([
       getCompanyInformation(),
@@ -124,9 +144,11 @@ export async function KeystoneRootLayout(props: {
       getForm('job_application'),
       getForm('marketing_list_signup'),
       getAdsConfig(),
+      getAnalyticsConfig(),
     ]);
 
   const metaPixelId = getMetaPixelId(adsConfig);
+  const posthogApiKey = getPostHogApiKey(analyticsConfig);
 
   const services = Array.isArray(servicesData) ? servicesData : [];
   const locations = Array.isArray(locationsData) ? locationsData : [];
@@ -137,12 +159,15 @@ export async function KeystoneRootLayout(props: {
   const theme = config.site.theme;
 
   const ci = companyInformation as CompanyInformation | null;
+  const accountId = ci?.id ?? undefined;
+  const accountName = ci?.company_name ?? undefined;
   const externalManagementUrl = ci?.external_management_url?.trim() || null;
   const portalUrl = ci?.portal_url?.trim() || null;
   const bookingHref = portalUrl ?? externalManagementUrl ?? null;
   const chatEnabled = Boolean(ci?.chat_enabled);
 
   const headerOverrides = options?.headerOverrides;
+  const posthogHost = options?.posthogHost?.trim() || undefined;
   const headerProps = {
     logo: {
       href: headerOverrides?.logoHref || '/',
@@ -150,44 +175,64 @@ export async function KeystoneRootLayout(props: {
     },
     cta_button: {
       label: headerOverrides?.ctaLabel || 'Contact Us',
+      ...(headerOverrides?.ctaHref != null && { href: headerOverrides.ctaHref }),
       secondary_label: headerOverrides?.secondaryLabel ?? (bookingHref ? 'Book Now' : undefined),
+      ...(headerOverrides?.secondaryHref != null && { secondary_href: headerOverrides.secondaryHref }),
     },
   };
 
+  const bodyContent = (
+    <>
+      {metaPixelId ? <MetaPixel pixelId={metaPixelId} /> : null}
+      {metaPixelId ? <MetaPixelTracker bookingUrl={externalManagementUrl} /> : null}
+      <ThemeProvider theme={theme}>
+        <KeystoneSSRProvider>
+          <FormDefinitionsProvider
+            leadFormDefinition={leadFormDefinition ?? null}
+            jobApplicationFormDefinition={jobApplicationFormDefinition ?? null}
+            marketingListSignupFormDefinition={marketingListSignupFormDefinition ?? null}
+          >
+            <HeaderNavigation
+              config={dynamicConfig}
+              companyInformation={companyInformation}
+              websitePhotos={websitePhotos}
+              props={headerProps}
+              logoText={headerOverrides?.logoText}
+            />
+            {children}
+            <FooterHome
+              config={dynamicConfig}
+              companyInformation={companyInformation}
+              websitePhotos={websitePhotos}
+            />
+            {chatEnabled ? (
+              <ChatWidget
+                position={options?.chatPosition || 'bottom-right'}
+                teamMembers={teamMembers}
+              />
+            ) : null}
+          </FormDefinitionsProvider>
+        </KeystoneSSRProvider>
+      </ThemeProvider>
+    </>
+  );
+
   return (
     <html lang="en" data-theme={theme}>
       <body>
-        {metaPixelId ? <MetaPixel pixelId={metaPixelId} /> : null}
-        {metaPixelId ? <MetaPixelTracker bookingUrl={externalManagementUrl} /> : null}
-        <ThemeProvider theme={theme}>
-          <KeystoneSSRProvider>
-            <FormDefinitionsProvider
-              leadFormDefinition={leadFormDefinition ?? null}
-              jobApplicationFormDefinition={jobApplicationFormDefinition ?? null}
-              marketingListSignupFormDefinition={marketingListSignupFormDefinition ?? null}
-            >
-              <HeaderNavigation
-                config={dynamicConfig}
-                companyInformation={companyInformation}
-                websitePhotos={websitePhotos}
-                props={headerProps}
-                logoText={headerOverrides?.logoText}
-              />
-              {children}
-              <FooterHome
-                config={dynamicConfig}
-                companyInformation={companyInformation}
-                websitePhotos={websitePhotos}
-              />
-              {chatEnabled ? (
-                <ChatWidget
-                  position={options?.chatPosition || 'bottom-right'}
-                  teamMembers={teamMembers}
-                />
-              ) : null}
-            </FormDefinitionsProvider>
-          </KeystoneSSRProvider>
-        </ThemeProvider>
+        {posthogApiKey ? (
+          <PostHogProvider
+            apiKey={posthogApiKey}
+            apiHost={posthogHost}
+            accountId={accountId}
+            accountName={accountName}
+          >
+            <KeystoneAnalyticsTracker bookingUrl={bookingHref} />
+            {bodyContent}
+          </PostHogProvider>
+        ) : (
+          bodyContent
+        )}
       </body>
     </html>
   );

package/src/tracking/KeystoneAnalyticsTracker.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { captureEvent } from './captureEvent';
+
+type Props = {
+  /** External booking / portal URL. When set, fires booking_cta_clicked on any click to that URL. */
+  bookingUrl?: string | null;
+};
+
+/**
+ * Page-level PostHog event tracker. Mount once inside PostHogProvider in
+ * KeystoneRootLayout alongside MetaPixelTracker.
+ *
+ * Responsibilities:
+ * - booking_cta_clicked: fires when any link to the booking URL is clicked,
+ *   capturing the page the visitor was on when they clicked.
+ */
+export function KeystoneAnalyticsTracker({ bookingUrl }: Props) {
+  const pathname = usePathname();
+
+  useEffect(() => {
+    if (!bookingUrl) return;
+
+    const handleClick = (e: MouseEvent) => {
+      const anchor = (e.target as Element).closest('a');
+      if (anchor?.href?.startsWith(bookingUrl)) {
+        captureEvent('booking_cta_clicked', {
+          source_path: pathname,
+          booking_url: bookingUrl,
+        });
+      }
+    };
+
+    document.addEventListener('click', handleClick);
+    return () => document.removeEventListener('click', handleClick);
+  }, [bookingUrl, pathname]);
+
+  return null;
+}