suaveplan/openspec/changes/enterprise-react-consent-overlay/tasks.md

Tasks: enterprise-react-consent-overlay

Change ID: enterprise-react-consent-overlay Package: @suaveplan/react-consent-overlay Target path: react/auth/react-consent-overlay Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/react-translate

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree per proposal layout.
• Write package.json at 0.1.0 with "sideEffects": false, exports map (top-level + per-capability subpaths).
• Dependencies: @suaveplan/error workspace:^, @suaveplan/react-translate workspace:^, zustand catalog:state, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build.
• Write tsconfig.json, vitest.config.ts, scripts.

---

2. Error codes and types

• Define ConsentError extending SuaveplanError; codes: CONSENT_CONTEXT_MISSING, CONSENT_GATE_FAILED, CONSENT_STORAGE_FAILED.
• Define all public types: consent categories, gate states, audio permission states, plugin interfaces, preset config shapes.

---

3. Storage adapters

• createStorageAdapter(type: 'cookie' | 'localStorage' | 'memory') — get(key), set(key, value, options?), remove(key). Cookie adapter respects sameSite/secure. Throws ConsentError(CONSENT_STORAGE_FAILED) on failure.
• Write tests + md.

---

4. v2 Core (context + stores + gates)

Zustand stores (consent-store, audio-store, gate-store)

• Implement each with Zustand; persist consent-store via storage adapter.
• Write tests + md for each.

ConsentContext + ConsentProviderV2

• Wraps stores; provides all use* hooks.
• useConsent() throws ConsentError(CONSENT_CONTEXT_MISSING) outside provider.
• OTel consent.accept span on accept, consent.decline on decline.
• Write test + md.

Gates (AgeGate, CookieGate, TermsGate, CustomGate)

• Each gate renders children only after user consents; shows gate UI otherwise.
• OTel consent.gate_passed span on pass.
• Write test + stories (default, accepted, declined, loading, playground) + md for each.

GateManager

• Composes multiple gates in sequence.
• Write test + stories + md.

---

5. v2 Overlay + FocusTrap + Policy components

• ConsentOverlayV2, FocusTrap, PolicyPopupModal.
• Policy components: CookiePolicy, PrivacyPolicy, TermsOfService, PolicyLayout.
• Write tests + stories + md for each.

---

6. Plugin system

• BaseConsentPlugin interface + GTMPlugin, AnalyticsPlugin, ScrollValidationPlugin, AgeVerificationPlugin.
• Write tests + md for each plugin.

---

7. Industry presets (7)

• ecommerce, saas, blog, healthcare, finance, education, social — each returns a ConsentConfig preset.
• Write test (preset produces valid config) + md.

---

8. Audio permission system

• AudioPermissionGate, AmbientSound, MusicSound, NarrationSound, EffectSound, UISound, AudioControlBar, AudioControlPanel.
• Write tests + stories + md for each.

---

9. i18n bundles

• src/i18n/en.ts, cy.ts, zh.ts — all consent-related strings.
• Export createTranslationFn(locale).
• Write test (all keys present in all locales).

---

10. v1 Back-compat

• ConsentProvider, ConsentBanner, ConsentOverlay — legacy API preserved; internally delegates to v2.
• Write tests + md.

---

11. E2E

• e2e/consent.spec.ts — Playwright:
  • Render CookieGate, click "Accept all" → gate passes, children visible.
  • Render CookieGate, click "Decline" → gate remains, children hidden.
  • Render AgeGate, enter age ≥ 18 → passes.
• e2e/audio-permission.spec.ts — render AudioPermissionGate, grant permission → audio plays.

---

12. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-consent-overlay — green.
• bunx turbo test:coverage --filter=@suaveplan/react-consent-overlay — 100%.
• bun scripts/publish.ts --package @suaveplan/react-consent-overlay.
• Archive change folder.