interface ConsentState {
  version: number;          // bump to force re-prompt when adding a category
  categories: {
    analytics: boolean;
    session_replay: boolean;
    error_monitoring: boolean;
    // add categories as needed; each gets its own opt-in
  };
  timestamp: string;        // ISO; used for 12-month re-prompt
}

// lib/consent/store.ts
export const CONSENT_VERSION = 1;
export const CONSENT_STORAGE_KEY = 'site_consent_v1';
export const CONSENT_COOKIE_NAME = 'site_consent';
export const CONSENT_REPROMPT_MS = 365 * 24 * 60 * 60 * 1000;

function writeCookie(state: ConsentState | null) {
  const maxAge = Math.floor(CONSENT_REPROMPT_MS / 1000);
  const secure = location.protocol === 'https:' ? '; Secure' : '';
  if (!state) {
    document.cookie = `${CONSENT_COOKIE_NAME}=; Path=/; Max-Age=0; SameSite=Lax${secure}`;
    return;
  }
  const value = state.categories.analytics ? '1' : '0';
  document.cookie = `${CONSENT_COOKIE_NAME}=${value}; Path=/; Max-Age=${maxAge}; SameSite=Lax${secure}`;
}

export const SSR_SENTINEL: ConsentState = Object.freeze({
  version: -1,
  categories: ALL_CATEGORIES_OFF,
  timestamp: '1970-01-01T00:00:00.000Z',
});

// In the provider:
const rawState = useSyncExternalStore(
  consentStore.subscribe,
  consentStore.getSnapshot,
  consentStore.getServerSnapshot,  // returns SSR_SENTINEL
);
const isHydrated = rawState !== SSR_SENTINEL;
const state = isHydrated ? rawState : null;

const needsPrompt = isHydrated && state === null;

function onStorageEvent(e: StorageEvent) {
  if (e.key === null || e.key === CONSENT_STORAGE_KEY) notify();
}
// Attach in subscribe() when first listener is added, detach when last leaves.

// ESC handler inside the banner component
useEffect(() => {
  if (!promptOpen) return;
  function onKey(e: KeyboardEvent) {
    if (e.key === 'Escape') rejectAll();
  }
  window.addEventListener('keydown', onKey);
  return () => window.removeEventListener('keydown', onKey);
}, [promptOpen, rejectAll]);

<div className="grid grid-cols-3 gap-2">
  <Button size="sm" variant="outline" onClick={rejectAll}>{dict.rejectAll}</Button>
  <Button size="sm" variant="outline" onClick={openPreferences}>{dict.customize}</Button>
  <Button size="sm" onClick={acceptAll}>{dict.acceptAll}</Button>
</div>

// components/consent/consent-gated-trackers.tsx
export function ConsentGatedTrackers() {
  const { isAllowed } = useConsent();
  return (
    <>
      {isAllowed('analytics') && <Analytics />}
      {isAllowed('analytics') && <SpeedInsights />}
      {isAllowed('session_replay') && <ClarityScript />}
    </>
  );
}

const ESSENTIAL_EVENTS = new Set([
  'consent_banner_shown', 'consent_accepted', 'consent_rejected',
  'consent_customized', 'consent_reopened', 'auth_sign_in',
]);

export function trackEvent(event: string, data?: Record<string, unknown>) {
  if (!ESSENTIAL_EVENTS.has(event) && !window.__consent?.analytics) return;
  // ...send to analytics backend
}

// instrumentation-client.ts
import { hydrateWindowFromStorage } from '@/lib/consent/store';

hydrateWindowFromStorage();  // sets window.__consent from localStorage

Sentry.init({
  dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
  integrations: window.__consent?.session_replay ? [Sentry.replayIntegration()] : [],
  beforeSend(event) {
    return window.__consent?.error_monitoring ? event : null;
  },
});

// lib/consent/sentry-gate.ts
import * as Sentry from '@sentry/nextjs';

export function enableSentryReplay() {
  const client = Sentry.getClient();
  if (!client) return;
  if (client.getIntegrationByName?.('Replay')) return;  // idempotent
  Sentry.addIntegration(Sentry.replayIntegration());
}

useEffect(() => {
  if (state?.categories.session_replay) {
    import('./sentry-gate').then((m) => m.enableSentryReplay());
  }
}, [state?.categories.session_replay]);

// lib/consent/server.ts
import { cookies } from 'next/headers';
import { CONSENT_COOKIE_NAME } from './store';

export async function isAnalyticsAllowedServerSide(): Promise<boolean> {
  const store = await cookies();
  return store.get(CONSENT_COOKIE_NAME)?.value === '1';
}

if (await isAnalyticsAllowedServerSide()) {
  after(() => incrementBundleViews(slug));
}