keystone-design-bootstrap 1.0.68 → 1.0.69

package/README.md

@@ -1,175 +1,117 @@
 # Keystone Design Bootstrap
 
-A comprehensive design system for Keystone customer websites. Provides themed sections, elements, and utilities for building consistent, server-rendered Next.js sites.
+The shared design system and runtime package powering all Keystone customer websites. Provides themed sections, UI elements, the member portal, server-side API helpers, form handling, Meta Pixel tracking, and the Next.js app shell.
 
-## Quick Start
+---
 
-1. **Set your theme** in `config/index.ts`:
-```typescript
-export const config = {
-  site: { theme: "barelux" } // or "aman", "classic"
-}
-```
+## Documentation
 
-2. **Import theme CSS** in your `app/globals.css`:
-```css
-@import "keystone-design-bootstrap/styles/fonts.css";
-@import "keystone-design-bootstrap/styles/theme.css";
-@import "keystone-design-bootstrap/styles/typography.css";
-@import "keystone-design-bootstrap/styles/style-overrides.barelux.css"; /* Change to match your theme */
-```
+| Doc | Description |
+|---|---|
+| [`docs/architecture.md`](./docs/architecture.md) | Package structure, rendering model, theme system, publishing workflow |
+| [`docs/server-api.md`](./docs/server-api.md) | All data-fetching functions, caching strategy, environment variables |
+| [`docs/navigation-and-layout.md`](./docs/navigation-and-layout.md) | `KeystoneRootLayout`, `SiteConfig`, CTA URL resolution, dynamic nav, mobile sticky footer |
+| [`docs/member-portal.md`](./docs/member-portal.md) | Member portal setup, tabs, auth flow, iframe booking, messaging |
+| [`docs/forms.md`](./docs/forms.md) | Dynamic forms, `ContactSection`, form route, custom form pattern |
+| [`docs/meta-tracking.md`](./docs/meta-tracking.md) | Meta Pixel initialization, automatic events, custom form tracking |
+| [`docs/site-customization.md`](./docs/site-customization.md) | Per-site config, style overrides, component customization hierarchy |
+| [`docs/theme-system.md`](./docs/theme-system.md) | Creating and registering themes, CSS tokens, component variants |
 
-3. **Run** `npm run dev` and you're ready!
+---
 
-## Installation
+## Quick start (new customer site)
+
+### 1. Environment variables
 
 ```bash
-npm install @keystone-pzjr/design-bootstrap
+# .env.local
+API_URL=http://localhost:3000/api/v1
+API_KEY=your-api-key-here
 ```
 
-## Using the Design System
-
-### Elements
-Reusable UI components:
+### 2. Config
 
 ```typescript
-import { Button, Input, Carousel } from '@keystone-pzjr/design-bootstrap/elements'
+// config/index.ts
+import type { SiteConfig } from 'keystone-design-bootstrap/types';
 
-<Button color="primary" size="md">Click Me</Button>
-<Input label="Email" type="email" />
-<Carousel items={photos} />
+export const config: SiteConfig = {
+  site: { title: "Business Name", description: "…", theme: "aman" },
+  navigation: { header: […], footer: [[…], […], […], […]] },
+};
 ```
 
-### Server API
-Async functions for fetching data server-side:
+### 3. Root layout
 
 ```typescript
-import { getServices, getTestimonials, getBlogPosts } from '@keystone-pzjr/design-bootstrap/lib/server-api'
+// app/layout.tsx
+import { KeystoneRootLayout } from 'keystone-design-bootstrap/next/layouts/root-layout';
+import { config } from '@/config';
 
-const services = await getServices()
-const testimonials = await getTestimonials()
-```
-
-### Sections
-Pre-built page components that accept data via props:
-
-```typescript
-import { HeroHome, TestimonialsHome } from '@keystone-pzjr/design-bootstrap/sections'
-import { getTestimonials } from '@keystone-pzjr/design-bootstrap/lib/server-api'
-
-export default async function HomePage() {
-  const testimonials = await getTestimonials()
-  return (
-    <main>
-      <HeroHome />
-      <TestimonialsHome testimonials={testimonials} />
-    </main>
-  )
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <KeystoneRootLayout config={config}>{children}</KeystoneRootLayout>;
 }
 ```
 
-**Available:** `HeroHome`, `ServicesHome`, `TestimonialsHome`, `BlogSection`, `ContactSection`, `HeaderNavigation`, `FooterHome`, and more.
-
-## Package Exports
-
-```typescript
-// Sections (hero, footer, header, testimonials, etc.)
-import { HeroHome, FooterHome, TestimonialsHome } from '@keystone-pzjr/design-bootstrap/sections'
-
-// Elements (buttons, inputs, carousels, etc.)
-import { Button, Input, Carousel } from '@keystone-pzjr/design-bootstrap/elements'
-
-// Hooks
-import { useBreakpoint } from '@keystone-pzjr/design-bootstrap/hooks'
-
-// Theme context
-import { ThemeProvider } from '@keystone-pzjr/design-bootstrap/contexts'
+### 4. CSS imports
 
-// Server API utilities
-import { getServices, getTestimonials } from '@keystone-pzjr/design-bootstrap/lib/server-api'
-
-// Types
-import type { Service, Testimonial } from '@keystone-pzjr/design-bootstrap/types'
-
-// Themes
-import { themes } from '@keystone-pzjr/design-bootstrap/themes'
+```css
+/* app/globals.css */
+@import "keystone-design-bootstrap/styles/fonts.css";
+@import "keystone-design-bootstrap/styles/theme.css";
+@import "keystone-design-bootstrap/styles/typography.css";
+@import "keystone-design-bootstrap/styles/style-overrides.aman.css"; /* match your theme */
+@import "../styles/custom-overrides.css";
 ```
 
-## Meta Pixel Tracking
+---
 
-Meta Pixel is initialised automatically in `KeystoneRootLayout` when the account has a connected Meta integration with a pixel configured. Most events fire without any extra work. The one place you need to add tracking manually is **custom form submissions**.
+## Package exports reference
 
-### What fires automatically
-
-| Event | Trigger |
+| Import path | Contents |
 |---|---|
-| `PageView` | Every page load |
-| `ViewContent` | Route changes to `/services`, `/services/:slug`, `/locations`, `/locations/:slug`, `/portal`, `/service-menu`, `/faq`, `/contact` |
-| `InitiateCheckout` | Click on any link to the account's external booking URL |
-| Portal tab events | Opening Services, Packages, Specials, or Booking tabs in the member portal |
-
-### Adding tracking to a custom form
-
-On successful submission, add two calls:
+| `keystone-design-bootstrap/sections` | All section components |
+| `keystone-design-bootstrap/elements` | UI element components |
+| `keystone-design-bootstrap/portal` | `PortalPage` and portal sub-components |
+| `keystone-design-bootstrap/next/layouts/root-layout` | `KeystoneRootLayout` |
+| `keystone-design-bootstrap/next/routes/consumer-auth` | `createConsumerAuthHandlers` |
+| `keystone-design-bootstrap/next/routes/form` | `createFormRouteHandlers` (re-exported as `POST`) |
+| `keystone-design-bootstrap/lib/server-api` | Server-side data fetching functions |
+| `keystone-design-bootstrap/lib/cta-urls` | `resolveCtaUrls`, `resolvePortalPath`, `isExternalCtaUrl` |
+| `keystone-design-bootstrap/tracking` | `firePixelEvent`, `setPixelUserData` |
+| `keystone-design-bootstrap/types` | TypeScript types |
+| `keystone-design-bootstrap/hooks` | Client-side hooks |
+| `keystone-design-bootstrap/styles/*` | CSS files |
 
-```tsx
-import { firePixelEvent, setPixelUserData } from 'keystone-design-bootstrap/tracking';
-
-// inside your success handler, after a confirmed API response:
-await setPixelUserData({ email: data.email, phone: data.phone });
-firePixelEvent('Lead');
-```
+---
 
-Also submit with `formType: 'lead'` in the POST body — this triggers the server-side CAPI `Lead` event automatically with no extra backend work.
+## Local development
 
-Both calls are silent no-ops when no Meta Pixel is configured for the site.
+Use `yalc` to test local builds in a customer site:
 
-See `components/sections/VipReferralForm.tsx` in any customer site for a complete working example.
-
-## Architecture
-
-- **Server-first**: Data fetching happens server-side, components render as Server Components where possible
-- **Theme variants**: Components automatically select variants based on active theme
-- **Tailwind-first**: Use semantic utility classes (`bg-primary`, `text-fg-primary`, `font-display`)
-- **Type-safe**: Full TypeScript support throughout
-- **CSS variables**: Themes customize via CSS custom properties
-- **Self-hosted fonts**: Uses Fontsource for optimized, bundled font loading
-
-## Theme System
-
-**Available themes:** `classic`, `aman`, `barelux`
-
-### Themes
+```bash
+# In this package
+npm run build && yalc publish
 
-- **classic**: Default professional theme, Inter font, neutral colors
-- **aman**: Luxury theme with Playfair Display serifs, warm beige, bronze accents
-- **barelux**: Modern minimal theme with Poppins, clean lines
+# In the customer site
+yalc update keystone-design-bootstrap
 
-### Creating a Theme
+# To restore the published npm version
+yalc remove keystone-design-bootstrap && npm install
+```
 
-See [`docs/theme-system.md`](./docs/theme-system.md) for complete instructions.
+---
 
-**With AI assistance:**
-```
-I am creating a new theme. Here is a link to an example: https://www.example.com
-[Attach screenshots of various pages]
+## Creating a new theme
 
-Please follow the prompt in /docs/ai-prompt-template.md
-```
+See [`docs/theme-system.md`](./docs/theme-system.md) for the full guide.
 
-**Manual steps:**
+Quick checklist:
 1. Register in `src/themes/index.ts`
 2. Install fonts via Fontsource
 3. Create `src/styles/style-overrides.{theme}.css`
 4. Create component variants (optional)
-5. Add to design gallery app
-6. Pass lint, typecheck, and build
-
-**Critical rules:**
-- Never modify base components or foundation CSS
-- Use semantic variables/classes only
-- Set BOTH `--color-*` and `--background-*` prefixes
-- Match base component props exactly
-- Ensure `npm run lint`, `npm run typecheck`, `npm run build` pass with zero errors/warnings
+5. Add to design gallery
+6. `npm run lint && npm run typecheck && npm run build` — must all pass
 
-See [`.cursor/rules/theme-creation.mdc`](./.cursor/rules/theme-creation.mdc) for detailed rules
+**Available themes:** `classic`, `aman`, `barelux`, `balance`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keystone-design-bootstrap",
-  "version": "1.0.68",
+  "version": "1.0.69",
   "description": "Keystone Design Bootstrap - Sections, Elements, and Theme System for customer websites",
   "type": "module",
   "main": "./src/index.ts",
@@ -69,6 +69,7 @@
     "clsx": "^2.1.1",
     "embla-carousel-react": "^8.6.0",
     "motion": "^12.23.12",
+    "posthog-js": "^1.367.0",
     "react-aria": "^3.42.0",
     "react-aria-components": "^1.15.1",
     "react-markdown": "^10.1.0",

package/src/design_system/components/ChatWidget.tsx

@@ -4,6 +4,7 @@ import React, { useState, useEffect, useRef, useCallback } from 'react';
 import { X, MessageChatSquare } from '@untitledui/icons';
 import { Avatar } from '../elements/avatar/avatar';
 import { cx } from '../../utils/cx';
+import { captureEvent } from '../../tracking/captureEvent';
 
 interface Message {
   id: string;
@@ -197,27 +198,25 @@ export function ChatWidget({
 
       if (response.ok) {
         const result = await response.json();
-        
-        // Message sent successfully
+        captureEvent('chat_message_sent', { is_authenticated: Boolean(contactId) });
+
         if (result.data?.job_id) {
-          // Job is processing - poll for the reply
           pollForAgentReply();
         } else if (result.data?.status === 'agent_unavailable' || result.data?.status === 'no_auto_reply') {
-          // No agent reply expected
           setIsLoading(false);
         } else {
-          // Reload messages to get the actual stored message
           await loadMessages();
           setIsLoading(false);
         }
       } else {
-        // Remove temp message on error
         setMessages(prev => prev.filter(m => m.id !== tempMessage.id));
+        captureEvent('chat_message_failed', { error: 'send_failed' });
         console.error('Failed to send message');
         setIsLoading(false);
       }
     } catch (error) {
       setMessages(prev => prev.filter(m => m.id !== tempMessage.id));
+      captureEvent('chat_message_failed', { error: 'network_error' });
       console.error('Failed to send message:', error);
       setIsLoading(false);
     }
@@ -250,7 +249,7 @@ export function ChatWidget({
       {/* Chat button */}
       {!isOpen && (
         <button
-          onClick={() => setIsOpen(true)}
+          onClick={() => { setIsOpen(true); captureEvent('chat_opened'); }}
           className={cx(
             "flex size-15 items-center justify-center rounded-full border-none text-white shadow-xl transition-transform duration-200 hover:scale-105 focus:outline-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-brand",
             widgetBrandClass

package/src/design_system/portal/LoginForm.tsx

@@ -1,10 +1,11 @@
 'use client';
 
-import React, { useState, useMemo } from 'react';
+import React, { useState, useMemo, useEffect } from 'react';
 import { useRouter } from 'next/navigation';
 import { countries } from '../../utils/countries';
 import { getNationalMask, formatDigitsToMask } from '../../utils/phone-helpers';
 import { firePixelEvent, setPixelUserData } from '../../tracking/firePixelEvent';
+import { captureEvent } from '../../tracking/captureEvent';
 type Step = 'identifier' | 'returning' | 'new';
 
 interface LoginFormProps {
@@ -25,6 +26,10 @@ export function LoginForm({ onSuccess, onClose }: LoginFormProps) {
   const router = useRouter();
   const [step, setStep] = useState<Step>('identifier');
 
+  useEffect(() => {
+    captureEvent('portal_login_started');
+  }, []);
+
   // Identifier step state
   const [email, setEmail] = useState('');
   const [phoneValue, setPhoneValue] = useState(''); // formatted national number
@@ -73,19 +78,24 @@ export function LoginForm({ onSuccess, onClose }: LoginFormProps) {
         body: JSON.stringify({ email: emailVal, phone: fullPhone }),
       });
       const result = await res.json().catch(() => ({ exists: null }));
+      const method = emailVal && fullPhone ? 'email_and_phone' : emailVal ? 'email' : 'phone';
       if (result.exists === true) {
         await setPixelUserData({ email: emailVal, phone: fullPhone });
         firePixelEvent('Lead');
+        captureEvent('portal_login_identified', { method, user_exists: true });
         setWelcomeName(result.firstName ?? null);
         setStep(result.hasPassword === false ? 'new' : 'returning');
       } else if (result.exists === false) {
         await setPixelUserData({ email: emailVal, phone: fullPhone });
         firePixelEvent('Lead');
+        captureEvent('portal_login_identified', { method, user_exists: false });
         setStep('new');
       } else {
+        captureEvent('portal_login_failed', { step: 'identifier', reason: 'unknown_error' });
         setError('Something went wrong. Please check your connection and try again.');
       }
     } catch {
+      captureEvent('portal_login_failed', { step: 'identifier', reason: 'network_error' });
       setError('Something went wrong. Please check your connection and try again.');
     } finally {
       setLoading(false);
@@ -109,11 +119,14 @@ export function LoginForm({ onSuccess, onClose }: LoginFormProps) {
           setError(null);
           return;
         }
+        captureEvent('portal_login_failed', { step: 'signin', reason: result.code || 'invalid_credentials' });
         setError(result.error || 'Login failed. Please try again.');
         return;
       }
+      captureEvent('portal_login_completed', { flow: 'signin' });
       if (onSuccess) onSuccess(); else router.refresh();
     } catch {
+      captureEvent('portal_login_failed', { step: 'signin', reason: 'network_error' });
       setError('Something went wrong. Please check your connection and try again.');
     } finally {
       setLoading(false);
@@ -139,9 +152,15 @@ export function LoginForm({ onSuccess, onClose }: LoginFormProps) {
         }),
       });
       const result = await res.json().catch(() => ({}));
-      if (!res.ok) { setError(result.error || 'Signup failed. Please try again.'); return; }
+      if (!res.ok) {
+        captureEvent('portal_login_failed', { step: 'signup', reason: result.error || 'signup_failed' });
+        setError(result.error || 'Signup failed. Please try again.');
+        return;
+      }
+      captureEvent('portal_login_completed', { flow: 'signup' });
       if (onSuccess) onSuccess(); else router.refresh();
     } catch {
+      captureEvent('portal_login_failed', { step: 'signup', reason: 'network_error' });
       setError('Something went wrong. Please check your connection and try again.');
     } finally {
       setLoading(false);

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/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';
@@ -35,6 +37,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 +100,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 +122,7 @@ export async function KeystoneRootLayout(props: {
     jobApplicationFormDefinition,
     marketingListSignupFormDefinition,
     adsConfig,
+    analyticsConfig,
   ] =
     await Promise.all([
       getCompanyInformation(),
@@ -124,9 +134,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 +149,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 || '/',
@@ -154,40 +169,58 @@ export async function KeystoneRootLayout(props: {
     },
   };
 
+  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;
+}

package/src/tracking/PostHogProvider.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import posthog from 'posthog-js';
+import { PostHogProvider as PHProvider } from 'posthog-js/react';
+import { useEffect, Suspense } from 'react';
+import { usePathname, useSearchParams } from 'next/navigation';
+
+const DEFAULT_HOST = 'https://us.i.posthog.com';
+
+export type PostHogProviderProps = {
+  apiKey: string;
+  apiHost?: string;
+  /** Keystone account ID — attached to every event as a super property. */
+  accountId?: number;
+  /** Keystone account name (company_name) — attached to every event as a super property. */
+  accountName?: string;
+  children: React.ReactNode;
+};
+
+// ---------------------------------------------------------------------------
+// Page name resolution
+// ---------------------------------------------------------------------------
+
+type PageInfo = { page_name: string; page_slug?: string };
+
+function resolvePageInfo(pathname: string): PageInfo {
+  if (pathname === '/') return { page_name: 'home' };
+
+  const patterns: Array<[RegExp, (m: RegExpMatchArray) => PageInfo]> = [
+    [/^\/services\/(.+)$/, ([, slug]) => ({ page_name: 'service_detail', page_slug: slug })],
+    [/^\/locations\/(.+)$/, ([, slug]) => ({ page_name: 'location_detail', page_slug: slug })],
+    [/^\/blog\/(.+)$/, ([, slug]) => ({ page_name: 'blog_post', page_slug: slug })],
+    [/^\/jobs\/(.+)$/, ([, slug]) => ({ page_name: 'job_detail', page_slug: slug })],
+    [/^\/packages\/(.+)$/, ([, slug]) => ({ page_name: 'package_detail', page_slug: slug })],
+  ];
+
+  for (const [pattern, resolve] of patterns) {
+    const match = pathname.match(pattern);
+    if (match) return resolve(match);
+  }
+
+  const staticNames: Record<string, string> = {
+    '/services': 'services',
+    '/locations': 'locations',
+    '/contact': 'contact',
+    '/about': 'about',
+    '/blog': 'blog',
+    '/portal': 'portal',
+    '/gallery': 'gallery',
+    '/team': 'team',
+    '/faq': 'faq',
+    '/reviews': 'reviews',
+    '/jobs': 'jobs',
+    '/packages': 'packages',
+    '/service-menu': 'service_menu',
+    '/privacy-policy': 'privacy_policy',
+    '/terms': 'terms_of_service',
+  };
+
+  return { page_name: staticNames[pathname] ?? 'unknown' };
+}
+
+// ---------------------------------------------------------------------------
+// Pageview tracker — must be wrapped in <Suspense> (useSearchParams)
+// ---------------------------------------------------------------------------
+
+function PostHogPageviewTracker() {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  useEffect(() => {
+    if (!pathname) return;
+
+    const search = searchParams?.toString();
+    const url = window.location.origin + pathname + (search ? `?${search}` : '');
+    const { page_name, page_slug } = resolvePageInfo(pathname);
+
+    posthog.capture('$pageview', {
+      $current_url: url,
+      page_name,
+      page_path: pathname,
+      ...(page_slug && { page_slug }),
+    });
+  }, [pathname, searchParams]);
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialises PostHog, registers account-level super properties, and fires
+ * an enriched `$pageview` on every App Router navigation.
+ *
+ * Super properties attached to every event automatically:
+ *   - account_id    (Keystone account ID)
+ *   - account_name  (company_name)
+ *   - site_domain   (window.location.hostname)
+ *
+ * Mount once in the root layout body. One project key covers all customer
+ * sites — filter by account_name or site_domain in the PostHog dashboard.
+ */
+export function PostHogProvider({ apiKey, apiHost, accountId, accountName, children }: PostHogProviderProps) {
+  useEffect(() => {
+    posthog.init(apiKey, {
+      api_host: apiHost ?? DEFAULT_HOST,
+      person_profiles: 'identified_only',
+      capture_pageview: false,
+    });
+
+    posthog.register({
+      ...(accountId !== undefined && { account_id: accountId }),
+      ...(accountName && { account_name: accountName }),
+      site_domain: window.location.hostname,
+    });
+  }, [apiKey, apiHost, accountId, accountName]);
+
+  return (
+    <PHProvider client={posthog}>
+      <Suspense fallback={null}>
+        <PostHogPageviewTracker />
+      </Suspense>
+      {children}
+    </PHProvider>
+  );
+}

package/src/tracking/captureEvent.ts

@@ -0,0 +1,140 @@
+/**
+ * PostHog event capture — Keystone customer sites.
+ *
+ * ## Naming convention
+ * All events use snake_case `object_action` format.
+ * Properties use snake_case as well.
+ *
+ * ## Event taxonomy
+ * Add new events here: define the name in `KsEventName` and its required
+ * properties in `KsEventProperties`. Every callsite is then type-checked.
+ *
+ * ## Usage
+ *
+ *   import { captureEvent } from 'keystone-design-bootstrap/tracking';
+ *
+ *   captureEvent('form_submitted', { form_type: 'lead' });
+ *   captureEvent('booking_cta_clicked', { source_path: '/services/massage', booking_url: url });
+ *
+ * All calls are safe no-ops when PostHog has not been initialised (e.g. no
+ * POSTHOG_API_KEY configured on the server).
+ *
+ * ## Super properties
+ * account_id, account_name, and site_domain are registered as super properties
+ * by PostHogProvider and are automatically attached to every event — you do not
+ * need to include them in individual captureEvent calls.
+ */
+
+import posthog from 'posthog-js';
+
+// ---------------------------------------------------------------------------
+// Event taxonomy
+// ---------------------------------------------------------------------------
+
+export type KsEventName =
+  // Navigation
+  | 'page_viewed'
+  // Booking / conversion
+  | 'booking_cta_clicked'
+  // Forms
+  | 'form_submitted'
+  | 'form_failed'
+  // Chat widget
+  | 'chat_opened'
+  | 'chat_message_sent'
+  | 'chat_message_failed'
+  // Member portal — tab navigation
+  | 'portal_tab_viewed'
+  // Member portal — authentication flow
+  | 'portal_login_started'
+  | 'portal_login_identified'
+  | 'portal_login_completed'
+  | 'portal_login_failed';
+
+export type KsEventProperties = {
+  /** Fired on every page navigation. $pageview is also fired for PostHog web analytics. */
+  page_viewed: {
+    page_name: string;
+    page_path: string;
+    page_slug?: string;
+  };
+
+  /** Fired when a visitor clicks any CTA that links to the external booking URL. */
+  booking_cta_clicked: {
+    source_path: string;
+    booking_url: string;
+  };
+
+  /** Fired when a Keystone form is successfully submitted. */
+  form_submitted: {
+    /** One of: lead | job_application | marketing_list_signup */
+    form_type: string;
+    /** Server-generated event ID for CAPI deduplication (when present). */
+    event_id?: string;
+  };
+
+  /** Fired when a form submission fails (validation error or network error). */
+  form_failed: {
+    form_type: string;
+    error: string;
+  };
+
+  /** Fired when the chat widget is first opened by the visitor. */
+  chat_opened: Record<string, never>;
+
+  /** Fired when a chat message is successfully sent. */
+  chat_message_sent: {
+    /** Whether the visitor is authenticated (contactId present). */
+    is_authenticated: boolean;
+  };
+
+  /** Fired when a chat message fails to send. */
+  chat_message_failed: {
+    error: string;
+  };
+
+  /** Fired when a member portal tab is opened. */
+  portal_tab_viewed: {
+    tab: string;
+  };
+
+  /** Fired when the portal login modal is opened / login flow starts. */
+  portal_login_started: Record<string, never>;
+
+  /**
+   * Fired after the identifier step resolves — we know whether the user
+   * already has an account.
+   */
+  portal_login_identified: {
+    method: 'email' | 'phone' | 'email_and_phone';
+    user_exists: boolean;
+  };
+
+  /** Fired after the user successfully signs in or creates an account. */
+  portal_login_completed: {
+    flow: 'signin' | 'signup';
+  };
+
+  /** Fired when any step of the login flow returns an error. */
+  portal_login_failed: {
+    step: 'identifier' | 'signin' | 'signup';
+    reason: string;
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Capture helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Captures a typed Keystone analytics event via PostHog.
+ * Safe no-op when PostHog has not been initialised.
+ */
+export function captureEvent<E extends KsEventName>(
+  event: E,
+  ...args: KsEventProperties[E] extends Record<string, never>
+    ? []
+    : [properties: KsEventProperties[E]]
+): void {
+  posthog.capture(event, args[0] as Record<string, unknown>);
+}

package/src/tracking/index.ts

@@ -23,3 +23,8 @@ export type { MetaPixelProps } from './MetaPixel';
 export { MetaPixelTracker } from './MetaPixelTracker';
 export { firePixelEvent, setPixelUserData } from './firePixelEvent';
 export type { PixelEvent, PixelEventParams, PixelUserData } from './firePixelEvent';
+export { PostHogProvider } from './PostHogProvider';
+export type { PostHogProviderProps } from './PostHogProvider';
+export { KeystoneAnalyticsTracker } from './KeystoneAnalyticsTracker';
+export { captureEvent } from './captureEvent';
+export type { KsEventName, KsEventProperties } from './captureEvent';