Initial Commit

openspec/changes/enterprise-react-consent-overlay/proposal.md

@@ -0,0 +1,73 @@
+# OpenSpec Change: enterprise-react-consent-overlay
+
+- **Change ID**: enterprise-react-consent-overlay
+- **Package**: `@suaveplan/react-consent-overlay`
+- **Category**: react
+- **Target path**: `react/auth/react-consent-overlay`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-consent-overlay.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-consent-overlay` on genesis from scratch at enterprise quality. GDPR/cookie/terms/age-gate consent framework for React 19: v2 gate-based pipeline (`AgeGate`, `CookieGate`, `TermsGate`, `CustomGate`, `GateManager`), v1 `ConsentProvider`/`ConsentBanner`/`ConsentOverlay` for back-compat, pluggable storage (cookie/localStorage/memory), Zustand stores (consent/audio/gate), plugin system (GTM, Analytics, ScrollValidation, AgeVerification), industry presets, policy components, multi-layer audio-permission system, and i18n bundles (EN, CY, ZH). Genesis adds Playwright E2E coverage, Storybook stories for every gate and audio component, and 100% test coverage.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `ConsentError` |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n foundation |
+| `zod` (`catalog:forms`) | Gate + config schemas |
+| `@opentelemetry/api` (`catalog:observability`) | `consent.accept` / `consent.decline` spans |
+
+External: `zustand catalog:state`, `tslib catalog:build`. React 18/19 peer.
+
+---
+
+## Preserved public API surface (v2 Core)
+
+`ConsentContext`, `ConsentProviderV2`, `DEFAULT_CONFIG`, `useConsent`, `useConsentCategory`, `useConsentStatus`, `useConsentGate`, `useEnabledCategories`, `useIsWhitelisted`, `useTermsAccepted`, `useAgeVerified`, `AgeGate`, `CookieGate`, `TermsGate`, `CustomGate`, `GateManager`, `ConsentOverlayV2`, `FocusTrap`, plus all policy + audio + plugin exports.
+
+**v1 Back-compat exports preserved**: `ConsentProvider`, `ConsentBanner`, `ConsentOverlay`.
+
+---
+
+## New additions for genesis
+
+1. **`ConsentError`** — codes: `CONSENT_CONTEXT_MISSING`, `CONSENT_GATE_FAILED`, `CONSENT_STORAGE_FAILED`.
+2. **Storybook for every gate and audio component** — default, accepted, declined, loading, playground.
+3. **Playwright E2E** — `CookieGate` accept/decline flow, `AgeGate` age verification, audio permission flow.
+4. **OTel spans** — `consent.accept`, `consent.decline`, `consent.gate_passed`.
+
+---
+
+## File layout
+
+```text
+react/auth/react-consent-overlay/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    v2/
+      context/ gates/ overlay/ stores/ plugins/ presets/ policy/ audio/
+    v1/ (back-compat)
+    i18n/ (en, cy, zh translations)
+    utils/ (storage adapters)
+    types/
+  e2e/
+    consent.spec.ts
+    audio-permission.spec.ts
+```