# 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
```