@consenti/ui 0.1.0 → 0.3.0

package/README.md

@@ -8,12 +8,13 @@ Zero-dependency, GDPR-compliant cookie consent widget for any web framework.
 
 ---
 
-## Why this package?
+## Why Consenti?
 
 - **Zero runtime dependencies** — browser built-ins only (`fetch`, `crypto.subtle`, `BroadcastChannel`, `CustomEvent`, `document.cookie`, `localStorage`)
-- **Fully standalone or API-connected** — works offline with a local profile, or connects to `@consenti/api` for dashboard-managed profiles
-- **Multi-regulation** — GDPR, UK-GDPR, CCPA, CPRA, LGPD, DPDPA, PIPEDA, POPIA, PDPA-TH, APPI, KVKK
-- **GPC aware** — Global Privacy Control signal detection with `true` / `'strict'` modes
+- **Fully standalone or API-connected** — works offline with pre-built profiles, or connects to `@consenti/api` for dashboard-managed profiles
+- **Multi-regulation** — GDPR, CCPA, CPRA, LGPD, DPDPA, PIPL, and more via 8 built-in compliance groups
+- **Automatic geo-resolution** — detects visitor jurisdiction client-side (timezone + language) or server-side (`/resolve-profile`)
+- **GPC aware** — Global Privacy Control signal detection with `'honor'` / `'strict'` / `'ignore'` modes per profile
 - **GTM / Google Consent Mode v2** — built-in `dataLayer` integration
 - **SSR-safe** — all browser API access is guarded; `new ConsentiSetup()` during SSR is a silent no-op
 - **Fully typed** — ships TypeScript definitions; no `@types` needed
@@ -48,7 +49,7 @@ import '@consenti/ui/dist/index.css'
 <script src="https://cdn.jsdelivr.net/npm/@consenti/ui/dist/index.umd.js"></script>
 <script>
   const { ConsentiSetup } = ConsentiUI
-  new ConsentiSetup({ core: { regulation: 'gdpr' } })
+  new ConsentiSetup({ compliance: { type: 'opt-in' } })
 </script>
 ```
 
@@ -57,7 +58,7 @@ import '@consenti/ui/dist/index.css'
 ```html
 <script type="module">
   import { ConsentiSetup } from 'https://esm.sh/@consenti/ui'
-  new ConsentiSetup({ core: { regulation: 'gdpr' } })
+  new ConsentiSetup({ compliance: { type: 'opt-in' } })
 </script>
 ```
 
@@ -74,8 +75,16 @@ import '@consenti/ui/dist/index.css'
 ## Quick Start
 
 ```ts
-// Simplest possible — built-in GDPR profile, no backend required
-new ConsentiSetup({ core: { regulation: 'gdpr' } })
+// Simplest possible — auto-detects jurisdiction from browser timezone + language
+new ConsentiSetup({})
+
+// Fixed GDPR (EU opt-in) profile, no backend required
+new ConsentiSetup({ compliance: { type: 'opt-in' } })
+
+// API-backed — server geo-resolves the right profile per visitor
+new ConsentiSetup({
+  api: { enabled: true, baseUrl: 'https://your-backend.com' },
+})
 ```
 
 A consent banner appears on first visit. Everything below is optional.
@@ -101,20 +110,27 @@ import { ConsentiSetup } from '@consenti/ui'
 import '@consenti/ui/dist/index.css'
 
 const widget = new ConsentiSetup({
-  // ── Required ────────────────────────────────────────────────────────────────
+  // ── Core (optional) ──────────────────────────────────────────────────────────
   core: {
-    profileId: 1,                // 0 = built-in default; >0 = local or API profile
-    regulation: 'gdpr',          // controls opt-in / opt-out behaviour
-    locale: 'en',                // BCP 47; falls back to language prefix, then 'en'
-    autoHonorGPC: true,          // false | true | 'strict'
-    storage: 'cookie',           // 'cookie' | 'localStorage'
-    cookieDomains: '.example.com',
-    privacyPolicyUrl: '/privacy',
-    signCookies: true,
-    cookieSigningKey: 'min-32-char-secret', // client-only mode; use API mode in production
-    allowReceipt: true,
-    disableCssTemplate: false,
+    tenantId: 'acme',              // identifies your tenant's profiles; default: 'default'
+    locale: 'en',                  // BCP 47; 'auto' = navigator.language; default: 'auto'
+    dir: 'auto',                   // 'ltr' | 'rtl' | 'auto'; 'auto' derives from locale
+                                   // (ar/he/fa/ur/ps/sd/ug/yi → rtl); default: 'auto'
+    storage: 'cookie',             // 'cookie' | 'localStorage'; default: 'cookie'
+    cookieDomains: '.example.com', // comma-separated; first entry used as Domain attribute
+    cookieSigningKey: 'min-32-char-secret', // HMAC-SHA256 signing; implicit from presence
+    allowReceipt: true,            // allow consent receipt download; default: false
+    disableCssTemplate: false,     // skip all style injection; default: false
     userId: 'server-assigned-uuid', // authenticated users — enables cross-device sync
+
+    // Pre-built profile fallback
+    usePrebuiltProfiles: 'all',    // 'all' (default) | ['opt-in', 'opt-out', ...] (non-empty)
+                                   // controls which of the 8 built-in profiles are available
+                                   // as fallbacks when the API is unavailable
+    cacheResolvedProfiles: true,   // cache /resolve-profile response in sessionStorage; default: true
+    console: ['error'],            // log levels emitted: 'info' | 'log' | 'warning' | 'error'
+                                   // default: ['error'] only — no noise in production
+
     theme: {
       bgColor: '#ffffff',
       textColor: '#1a1a1a',
@@ -136,6 +152,35 @@ const widget = new ConsentiSetup({
     },
   },
 
+  // ── Compliance routing (optional) ─────────────────────────────────────────
+  compliance: {
+    // 'auto'              → geo-resolve per visitor (default)
+    //                       api.enabled=true  → server resolves via /resolve-profile
+    //                       api.enabled=false → resolves client-side from timezone + language
+    // ComplianceGroupId   → fixed group for all visitors (skip geo)
+    // localProfileType    → use a locally registered ConsentiProfile
+    type: 'auto',
+
+    // Client-side geo resolver (used only when api.enabled = false)
+    // 'default' → browser timezone + navigator.language heuristic (built-in, zero deps)
+    // WidgetCountryResolverFn → custom async function: () => Promise<{ country, region, confidence }>
+    geoDataProvider: 'default',
+
+    // Age gate (optional) — see "Age Gate" section below
+    ageGate: {
+      enabled: false,
+      minimumAge: 13,
+      requireParentalConsent: false,
+    },
+
+    // TCF (IAB Transparency & Consent Framework) client stub (optional) — see "TCF" section below
+    tcf: {
+      enabled: false,
+      cmpId: 0,       // must match the cmpId configured on the backend (TcfConfig)
+      cmpVersion: 1,
+    },
+  },
+
   // ── Mount point (optional) ────────────────────────────────────────────────
   rootEl: '#my-consent-wrapper',  // CSS selector or HTMLElement; default: appends to body
 
@@ -147,6 +192,9 @@ const widget = new ConsentiSetup({
     enabled: true,
     baseUrl: 'https://your-site.com',  // default: window.location.origin
     authToken: '',                      // sent as Authorization: Bearer <token>
+    tenantId: 'acme',                   // overrides core.tenantId for API calls
+    complianceGroup: 'opt-in',          // pin a specific group on the API side (Scenario 2B)
+    trustDomain: false,                 // true = bypass allowedOrigins check (use in dev only)
   },
 
   // ── GTM / Google Consent Mode v2 (optional) ───────────────────────────────
@@ -170,47 +218,190 @@ const widget = new ConsentiSetup({
 })
 ```
 
+### `profileOverride` — deep-merge and delete semantics
+
+`profileOverride` (and `widget.setProfile()` at runtime) is deep-merged onto the resolved profile
+— server-fetched, pre-built, or locally registered — before anything renders. Merge rules:
+
+- Omitting a key (or setting it to `undefined`) leaves the resolved profile's value untouched.
+- An object value merges recursively, key by key — you only need to specify what differs.
+- An array value replaces/merges by index against the base array.
+- Setting a key to `null` **deletes it** from the merged result (JSON Merge Patch / RFC 7396
+  semantics). This is the way to remove a single entry from a keyed map — a cookie category, a
+  parameter — without having to know or repeat the rest of that map's contents:
+
+```ts
+profileOverride: {
+  preferenceModal: {
+    categories: { marketing: null },   // removes the 'marketing' category entirely
+  },
+},
+```
+
+`{ marketing: undefined }` or `{ marketing: {} }` do **not** delete the entry — the former is a
+no-op (same as omitting the key), the latter merges an empty object onto the existing category,
+changing nothing. Only an explicit `null` removes it.
+
 ---
 
-## Regulations
-
-| Value        | Region              | Model               | Notes                                                                  |
-|--------------|---------------------|---------------------|------------------------------------------------------------------------|
-| `'gdpr'`     | EU / EEA            | Opt-in              | Default. Banner on first visit; all non-mandatory cookies denied until granted. |
-| `'uk-gdpr'`  | UK                  | Opt-in              | Same model as GDPR; ICO-enforced; age gate at 13.                      |
-| `'ccpa'`     | California (US)     | Opt-out             | All cookies default to `'granted'`; consent written silently; no banner. |
-| `'cpra'`     | California (US)     | Opt-out / Opt-in    | Supersedes CCPA. Opt-out for sale/sharing; opt-in for sensitive data. GPC triggers Do Not Sell + Do Not Share. |
-| `'lgpd'`     | Brazil              | Opt-in              | 10 lawful bases; ANPD-enforced; parental consent gate under-12.        |
-| `'dpdpa'`    | India               | Opt-in              | Fiduciary name + grievance officer in modal; GPC ignored.              |
-| `'pipeda'`   | Canada              | Opt-in              | PIPEDA + Quebec Law 25 (GDPR-aligned).                                 |
-| `'popia'`    | South Africa        | Opt-in              | 8 processing conditions; Information Regulator-enforced.               |
-| `'pdpa-th'`  | Thailand            | Opt-in              | Cross-border transfer rules; PDPC-enforced.                            |
-| `'appi'`     | Japan               | Opt-in / Opt-out    | Opt-in for sensitive data and overseas transfers; opt-out for general third-party sharing. |
-| `'kvkk'`     | Turkey              | Opt-in              | Explicit consent for sensitive personal data; KVK Board-enforced.      |
+## Compliance Groups
+
+Consenti ships 8 pre-built English profiles, one per compliance group. The active group is resolved automatically per visitor (API or client-side) or fixed globally via `compliance.type`.
+
+| Group                      | Region / Law                  | Model      | GPC Default |
+|----------------------------|-------------------------------|------------|-------------|
+| `'opt-in'`                 | EU / EEA — GDPR               | Opt-in     | `'honor'`   |
+| `'opt-out'`                | California — CCPA             | Opt-out    | `'honor'`   |
+| `'opt-out-strict'`         | California — CPRA             | Strict opt-out | `'strict'` |
+| `'opt-in-dpdpa'`           | India — DPDPA                 | Opt-in     | `'honor'`   |
+| `'opt-in-china'`           | China — PIPL                  | Opt-in     | `'ignore'`  |
+| `'opt-in-brazil'`          | Brazil — LGPD                 | Opt-in     | `'honor'`   |
+| `'general-privacy-consent'`| Global / general              | Opt-in     | `'honor'`   |
+| `'notice-only'`            | Informational                 | Notice     | `'ignore'`  |
+
+### Fixed group (no geo-routing)
+
+```ts
+// All visitors see the GDPR opt-in banner
+new ConsentiSetup({ compliance: { type: 'opt-in' } })
+
+// All visitors see the CCPA opt-out notice
+new ConsentiSetup({ compliance: { type: 'opt-out' } })
+```
+
+### Auto geo-routing (default)
+
+```ts
+// Client-side: timezone + navigator.language → compliance group
+new ConsentiSetup({ compliance: { type: 'auto' } })
+
+// Server-side: /resolve-profile → right profile per visitor country
+new ConsentiSetup({
+  api: { enabled: true, baseUrl: 'https://consent.example.com' },
+  compliance: { type: 'auto' },
+})
+```
+
+---
+
+## Profile Resolution Scenarios
+
+| Scenario | When | How |
+|---|---|---|
+| **1A** | `api.enabled = false`, `compliance.type = 'auto'` | Timezone + language → group → pre-built profile |
+| **1B** | `api.enabled = false`, `compliance.type = ComplianceGroupId` | Direct pre-built profile load |
+| **2A** | `api.enabled = true`, `compliance.type = 'auto'` | `GET /resolve-profile?tz&lang&locale&tenantId` → `filePath` → static JSON |
+| **2B** | `api.enabled = true`, `compliance.type = ComplianceGroupId` | `GET /profiles/:tenantId/:group/:locale` |
+| **Local** | `compliance.type = localKey` + registered `ConsentiProfile` | Locally registered profile |
+| **Fallback** | Any fetch failure | Pre-built profile → `DEFAULT_PROFILE` |
+
+The `/resolve-profile` response URL is cached in `sessionStorage` for 1 hour per tab (`core.cacheResolvedProfiles`). The profile JSON itself is HTTP-cached via `Cache-Control: public, max-age=3600` on the server.
+
+### Domain allowlist
+
+If a profile's `allowedOrigins` list is configured on the server, the widget checks `window.location.origin` against it before using the profile. A mismatch falls back to the pre-built profile for that group.
+
+Set `api.trustDomain: true` to bypass this check (useful for localhost / dev environments where `allowedOrigins` contains only production domains).
 
 ---
 
 ## GPC — Global Privacy Control
 
+GPC mode is set per-profile on the server (`gpcMode: 'honor' | 'strict' | 'ignore'`). Widget config profileOverrides overrides the profile value when explicitly set.
+
+---
+
+## Age Gate
+
+Set `compliance.ageGate.enabled: true` to require age confirmation before the visitor sees any
+other consent UI (banner, GPC, CCPA opt-out — all of it waits behind the age gate on first visit):
+
 ```ts
 new ConsentiSetup({
-  core: {
-    regulation: 'gdpr',
-    autoHonorGPC: true,    // pre-deny 'listenGpc' cookies and show GPC banner variant
-    // autoHonorGPC: 'strict'  // pre-deny silently — no banner shown at all
+  compliance: {
+    ageGate: { enabled: true, minimumAge: 16, requireParentalConsent: true },
+  },
+})
+```
+
+- **Confirmed** (visitor is old enough) → the normal banner/GPC/CCPA flow proceeds exactly as if
+  the age gate didn't exist, and every consent submission from then on carries `ageVerified: true`.
+- **Declined, `requireParentalConsent: false`** → a deny-all consent is submitted immediately
+  (mandatory/strictly-necessary cookies still granted), no banner shown, `ageVerified: false`.
+- **Declined, `requireParentalConsent: true`** → same deny-all submission, plus a
+  `parentalConsentToken` is generated and a `consenti:parentalConsentRequired` event fires
+  carrying it. There's no email-verification pipeline built into this package — the event is the
+  hook for wiring your own out-of-band parental-consent process (once verified externally, call
+  `PUT /consent/:visitorId` yourself to update the record).
+
+The prompt only asks once per visitor per profile — it doesn't re-appear once any consent record
+exists (same "already decided" check the banner itself uses).
+
+---
+
+## TCF — IAB Transparency & Consent Framework
+
+Set `compliance.tcf.enabled: true` to install `window.__tcfapi`, the standard IAB entry point
+third-party ad-tech scripts call to read consent (`ping`, `getTCData`, `addEventListener`,
+`removeEventListener`):
+
+```ts
+new ConsentiSetup({
+  compliance: {
+    tcf: { enabled: true, cmpId: 280, cmpVersion: 1 }, // cmpId must match the backend's TcfConfig
   },
 })
 ```
 
-Cookies with `listenGpc: true` in the profile are automatically denied when the signal is detected.
+The stub follows the standard queue-command convention, so it's safe regardless of load order
+relative to third-party scripts that call `__tcfapi` before Consenti has initialized. Only one CMP
+may own `window.__tcfapi` per page — if it's already set (a real CMP, or another `ConsentiSetup`
+instance on a multi-profile page), this stub does not overwrite it.
+
+This is a simplified implementation: `tcString` is a base64url-encoded JSON payload (the same
+format the backend's `tcfString` uses), not the full IAB binary bitfield encoding, and vendor-list
+metadata (`gvlVersion`, `publisherCC`) is a placeholder since the widget doesn't fetch the GVL
+client-side. For full IAB TCF v2.2 compliance, use the `iabtcf-core` npm package instead.
+
+---
+
+## RTL / Text Direction
+
+`core.dir` controls the banner/modal's reading direction:
+
+```ts
+new ConsentiSetup({ core: { locale: 'ar', dir: 'auto' } }) // → rtl, derived from locale
+new ConsentiSetup({ core: { dir: 'rtl' } })                 // explicit, independent of locale
+```
+
+`'auto'` (the default) maps a known RTL-language prefix (`ar`, `he`, `fa`, `ur`, `ps`, `sd`, `ug`,
+`yi`) to `rtl`; anything else is `ltr`. The `dir` attribute is set on the widget's root element, so
+browser-native mirroring (flex layout, `text-align: start/end`) and the widget's own `[dir="rtl"]`
+CSS overrides (toggle switches, locale switcher, close button) apply automatically — no separate
+RTL stylesheet needed. Explicit banner/modal position variants (`left-bottom`, `right-bottom`,
+modal `left`/`right` slide-in) are **not** mirrored — those are screen positions you chose
+deliberately, independent of text direction.
 
 ---
 
 ## Profiles
 
-### Built-in default profile
+### Pre-built profiles (no backend)
+
+The widget includes 8 pre-built English profiles as dynamic-import chunks. Only the matched chunk downloads at runtime.
+
+```ts
+// GDPR banner — no server needed
+new ConsentiSetup({ compliance: { type: 'opt-in' } })
 
-When `core.profileId` is `0` or omitted, the widget uses a built-in English GDPR profile covering the five Google Consent Mode v2 purposes. No configuration needed.
+// CCPA notice — no server needed
+new ConsentiSetup({ compliance: { type: 'opt-out' } })
+
+// Restrict which pre-built profiles are available as fallbacks
+new ConsentiSetup({
+  core: { usePrebuiltProfiles: ['opt-in', 'opt-out'] },
+})
+```
 
 ### Local profile (no backend)
 
@@ -221,12 +412,13 @@ import { ConsentiProfile, ConsentiSetup } from '@consenti/ui'
 
 const profile = new ConsentiProfile({
   defaultLocale: 'en',
-  cookies: [
-    { id: 'necessary',  mandatory: true,  expiry: 365 },
-    { id: 'analytics',  listenGpc: true,  expiry: 365 },
-    { id: 'marketing',  listenGpc: true,  expiry: 365,  cpraCategory: 'sale' },
-    // cpraCategory: 'sale' | 'sharing' | 'sensitive' — used when regulation: 'cpra'
-  ],
+  complianceGroup: 'opt-in',
+  cookies: {
+    necessary: { purpose: 'necessary', listenGpc: false },
+    analytics: { purpose: 'analytics', listenGpc: true },
+    marketing: { purpose: 'marketing', listenGpc: true, cpraCategory: 'sale' },
+    // cpraCategory: 'sale' | 'sharing' | 'sensitive' — used by CPRA group
+  },
   translations: {
     en: {
       mainBanner: {
@@ -237,14 +429,14 @@ const profile = new ConsentiProfile({
         heading: 'We value your privacy',
         headingTag: 'h2',        // HTML tag for the heading; default 'h2'
         htmlText: 'We use cookies to improve your experience.',
-        buttons: [
-          { text: 'Accept All',         style: 'primary',   action: 'custom', cookies: '*' },
+        buttons: {
+          // key = machine id, rendered as the button's DOM id: `consenti-btn-{id}`, for targeting a specific button
           // cookies: '*' = grant all | '!' = deny all | ['id1','id2'] = grant specific
-          { text: 'Reject All',         style: 'secondary', action: 'custom', cookies: '!' },
-          { text: 'Manage Preferences', style: 'secondary', action: 'manage' },
-          { text: 'Privacy Policy',     style: 'text',      action: 'link',   url: '/privacy' },
-          // action: 'link' + url — renders as a text link below the banner
-        ],
+          'accept-all': { text: 'Accept All', style: 'primary', action: 'custom', cookies: '*' },
+          'reject-optional': { text: 'Reject Optional', style: 'secondary', action: 'custom', cookies: '!' },
+          customize: { text: 'Customize', style: 'secondary', action: 'manage' },
+          'privacy-policy': { text: 'Privacy Policy', style: 'text', action: 'link', url: '/privacy' },
+        },
       },
       gpcBanner: {               // shown instead of mainBanner when GPC detected
         position: 'bottom',
@@ -252,14 +444,14 @@ const profile = new ConsentiProfile({
         headingTag: 'h2',
         showLocaleSwitcher: false,
         htmlText: "Your browser's GPC signal was detected. Ad cookies have been pre-denied.",
-        buttons: [
-          { text: 'Understood',           style: 'primary',   action: 'custom', cookies: '!' },
-          { text: 'Manage Preferences',   style: 'secondary', action: 'manage' },
-        ],
+        buttons: {
+          understood: { text: 'Understood', style: 'primary', action: 'custom', cookies: '!' },
+          customize: { text: 'Customize', style: 'secondary', action: 'manage' },
+        },
       },
       preferenceModal: {
         heading: 'Cookie Preferences',
-        headingTag: 'h2',        // HTML tag for the modal heading; default 'h2'
+        headingTag: 'h2',
         subheading: 'Choose which cookies you allow.',
         htmlText: 'We use different types of cookies. You can enable or disable each category below.',
         position: 'center',       // 'left' | 'right' | 'center'
@@ -267,35 +459,33 @@ const profile = new ConsentiProfile({
         showLocaleSwitcher: false,
         persistent: false,        // true = cannot dismiss by clicking outside
         overlayOpacity: 50,
-        buttons: [
-          { text: 'Accept All',       style: 'primary', action: 'custom', cookies: '*' },
-          { text: 'Save Preferences', style: 'primary', action: 'submit' },
-          { text: 'Reject All',       style: 'text',    action: 'custom', cookies: '!' },
-        ],
-        categories: [
-          {
-            id: 'cat-necessary',
+        mobileFullScreenBreakpoint: 576,
+        buttons: {
+          'accept-all': { text: 'Accept All', style: 'primary', action: 'custom', cookies: '*' },
+          'save-preferences': { text: 'Save Preferences', style: 'primary', action: 'submit' },
+          'reject-optional': { text: 'Reject Optional', style: 'text', action: 'custom', cookies: '!' },
+        },
+        categories: {
+          necessary: {
             heading: 'Strictly Necessary',
-            headingTag: 'h3',    // HTML tag for the category heading; default 'h3'
+            headingTag: 'h3',
             htmlText: 'Required for the site to function. <strong>Cannot be disabled.</strong>',
-            mandatory: true,
+            legalBasis: 'mandatory',
             cookies: ['necessary'],
           },
-          {
-            id: 'cat-analytics',
+          analytics: {
             heading: 'Analytics',
             htmlText: 'Helps us understand how visitors use the site.',
-            type: 'consent',     // 'consent' | 'legitimate_interest'
-            // type: 'legitimate_interest' — refusal stored as 'objected' instead of 'denied'
+            legalBasis: 'consent',     // 'mandatory' | 'consent' | 'legitimate_interest'
             cookies: ['analytics'],
           },
-          {
-            id: 'cat-marketing',
+          marketing: {
             heading: 'Marketing',
             htmlText: 'Used to personalise ads and measure campaign performance.',
+            legalBasis: 'consent',
             cookies: ['marketing'],
           },
-        ],
+        },
       },
     },
     fr: {
@@ -307,57 +497,137 @@ const profile = new ConsentiProfile({
 })
 
 new ConsentiSetup({
-  core: {
-    profileId: profile.getId(), // always use .getId() — never hardcode the ID
-    regulation: 'gdpr',
-    locale: 'fr',
-  },
+  compliance: { type: profile.getComplianceGroup() },
 })
 ```
 
-> **Note:** Local profile IDs are auto-assigned starting from `1000` to avoid collisions with API profile IDs (which start from `1`). Always call `profile.getId()`.
-
 ### API profile (with backend)
 
 ```ts
 new ConsentiSetup({
-  core: { profileId: 3, regulation: 'gdpr', locale: 'de' },
   api: {
     enabled: true,
     baseUrl: 'https://consent.example.com',
+    tenantId: 'acme',
   },
+  // compliance.type: 'auto' resolves the right profile per visitor country
 })
 ```
 
-The widget fetches the profile from the API and falls back to a local profile (or the built-in default) if the request fails.
+The widget calls `GET /resolve-profile?tz&lang&locale&tenantId`, receives the profile file path, then fetches that static JSON directly. Falls back to pre-built profile if the API is unavailable.
 
 ---
 
 ## Cookie Format
 
-Consent is persisted as a single cookie named `consenti_{profileId}`.
+Consent is persisted as a single cookie named `consenti_data` with a compact JSON value:
 
+```json
+{"s":1,"v":2,"i":"5huf-…","u":"","t":1751692400,"g":0,"p":0,"c":{"analytics_storage":"g","ad_storage":"d"}}
 ```
-t:{unixTimestamp}::{cookieId}:{status}|{cookieId}:{status}|…[::sig:{hmac}]
+
+| Field | Type | Meaning |
+|---|---|---|
+| `s` | number | Profile ID |
+| `v` | number | Profile version |
+| `i` | string | Per-submission UUID (consent receipt ID) |
+| `u` | string | Logged-in user ID (`""` for anonymous) |
+| `t` | number | Unix timestamp of consent |
+| `g` | 0 \| 1 | GPC signal detected |
+| `p` | number | Consent source: 0 = user click, 1 = widget method |
+| `c` | object | Consent map: cookie ID → `"g"` (granted), `"o"` (objected), `"d"` (denied) |
+
+When the widget is upgraded from an older version, any existing `consenti_{profileId}` cookie is automatically read, migrated to the new format, and deleted — no consent loss occurs.
+
+The consent cookie lifetime equals the shortest `cookie.expiry` value across all profile cookies (in days, converted to `max-age` seconds). When that cookie expires the browser deletes it, the widget sees no consent, and re-shows the banner.
+
+---
+
+## Display Features
+
+### Footer Metadata
+
+When `showFooterMetadata: true` is set in the resolved profile, a metadata strip is injected inside the banner and modal after the main content. It shows the visitor's Consent ID (truncated UUID), Consent Date, Profile Version, and a "Privacy Settings" button that opens the preference modal.
+
+Configured in the dashboard (ProfileEditor → Step 1) or via `profileOverride`:
+
+```ts
+new ConsentiSetup({
+  compliance: { type: 'opt-in' },
+  profileOverride: { showFooterMetadata: true },
+})
 ```
 
-Example:
+### Enhanced Accessibility
+
+When `enhanceAccessibility: true` is set in the resolved profile, the class `.consenti--enhanced-a11y` is added to the root element. This applies:
+
+- Minimum 44 × 44 px hit area on all buttons (WCAG 2.1 SC 2.5.5)
+- 3 px solid focus ring (`outline-offset: 2px`) on all focusable elements
+- No impact on default styling — opt-in only
+
+```ts
+profileOverride: { enhanceAccessibility: true }
 ```
-t:1782133054::analytics:granted|marketing:denied|necessary:granted::sig:abc123
+
+### Responsive Button Stacking (`stackButtonsOnBreakpoint`)
+
+Set `mainBanner.stackButtonsOnBreakpoint` (and/or `gpcBanner.stackButtonsOnBreakpoint`) to a pixel width. Below that breakpoint the banner's buttons stack vertically and stretch to full width — useful for narrow mobile screens where 3+ buttons overflow.
+
+```ts
+profileOverride: {
+  mainBanner: { stackButtonsOnBreakpoint: 576 },  // px; 0 or undefined = disabled
+}
+```
+
+A scoped `<style>` element containing a single `@media (max-width: Npx)` rule is injected into the root element — no external stylesheet required, and it's removed on `destroy()`.
+
+### Modal Focus Trap (`trapFocus`)
+
+When `preferenceModal.trapFocus: true`, keyboard Tab / Shift+Tab navigation is confined within the consent modal while it is open. `Escape` closes the modal and returns focus to the triggering element.
+
+```ts
+profileOverride: {
+  preferenceModal: { trapFocus: true },
+}
 ```
 
 ---
 
+## Debugging
+
+```ts
+new ConsentiSetup({
+  core: {
+    console: ['error', 'warning', 'info'],  // add 'log' for verbose output
+  },
+})
+```
+
+The default is `['error']` only — no noise in production. Add levels when investigating profile resolution, GPC behavior, or domain allowlist failures. All Consenti log lines are prefixed `[Consenti]`.
+
+---
+
 ## Widget API Methods
 
 ```ts
-const widget = new ConsentiSetup({ core: { regulation: 'gdpr' } })
+const widget = new ConsentiSetup({ compliance: { type: 'opt-in' } })
 
 // Consent state
-widget.hasConsent()              // boolean — true if valid consent record exists
-widget.getConsent()              // Record<string, 'granted'|'denied'|'objected'> | null
-widget.getGTMConsent()           // consent in GTM / Google Consent Mode v2 format
-widget.getConsentDate()          // Date | false — time of last submission
+widget.hasConsent()                      // boolean — true if valid consent record exists
+widget.getConsent()                      // Record<string, 'granted'|'denied'|'objected'> | null
+widget.getConsent('google-gtm')          // Google Consent Mode v2 format
+widget.getConsent('category')            // { necessary, functional, preferences, analytics, marketing }
+widget.getConsent('adobe')               // { analytics, target, manager, optimizer }
+widget.getConsent('meta')                // { pixel, api, plugins, facebookLogin }
+widget.getConsent('microsoft-clarity')   // { session, heatmaps, performance }
+widget.getConsent('twilio-segment')      // { identify, page, track, group, alias }
+widget.getGTMConsent()                   // @deprecated — use getConsent('google-gtm')
+widget.getConsentDate()                  // Date | false — time of last submission
+widget.isCookieGranted('analytics')      // boolean — true if that cookie is 'granted'
+widget.isCookieGranted('analytics', true)// 'granted' | 'denied' | 'objected' | false
+widget.isCategoryGranted('cat-analytics')          // boolean — true if ALL cookies in category are granted
+widget.isCategoryGranted('cat-analytics', true)    // [{ analytics: 'granted' }, { pixel: 'denied' }]
 
 // Visibility
 widget.showBanner(gpc?)          // show main banner (or GPC variant)
@@ -367,6 +637,12 @@ widget.hideModal()               // close preference modal
 widget.bannerVisibility()        // 'main' | 'gpc' | false
 widget.modalVisibility()         // 'preference' | false
 
+// Bulk consent actions
+widget.grantAll()                // grant all cookies and dismiss banner
+widget.grantAll(true)            // grant only mandatory; deny everything else
+widget.denyAll()                 // deny non-mandatory; mandatory stay 'granted'
+widget.denyAll(true)             // deny all including mandatory (logs a warning)
+
 // Actions
 widget.init()                    // manually start init (when autoInit: false)
 widget.onReady(callback)         // called once widget is fully initialised
@@ -374,15 +650,61 @@ widget.switchLocale(locale)      // switch locale and re-render (e.g. 'fr', 'de-
 widget.submitConsent(consent)    // programmatically submit consent values
 widget.deleteConsent()           // delete consent record (cookie + backend if enabled)
 widget.reConsent()               // delete consent and re-show banner
-widget.downloadReceipt()         // trigger JSON consent receipt download
 widget.destroy()                 // unmount DOM elements and remove all event listeners
+
+// Runtime configuration
+widget.setDarkMode()             // toggle dark mode
+widget.setDarkMode(true)         // force dark on
+widget.setDarkMode(false)        // force light
+widget.setTheme({ primaryColor: '#ff0000' })  // hot-swap CSS tokens (merges into current theme)
+widget.setConfig({ darkMode: true })          // deep-merge partial config (no re-init)
+widget.setProfile({ mainBanner: { heading: 'Updated' } })  // re-render UI with new profile data
+
+// Diagnostics
+widget.version()                 // { package: '1.0.0', profileVersion: 2, consentVersion: 1 }
+```
+
+### Consent checks
+
+```ts
+// Gate analytics code on a single cookie
+if (widget.isCookieGranted('analytics_storage')) {
+  initAnalytics()
+}
+
+// Read the raw status string when you need it
+const status = widget.isCookieGranted('marketing', true) // 'granted' | 'denied' | 'objected' | false
+
+// Gate a feature on an entire category (all cookies in category must be granted)
+if (widget.isCategoryGranted('cat-analytics')) {
+  loadHeatmaps()
+}
+
+// Inspect each cookie's status in a category
+const statuses = widget.isCategoryGranted('cat-marketing', true)
+// [{ ad_storage: 'granted' }, { ad_personalization: 'denied' }]
+```
+
+### Typed event subscriptions
+
+```ts
+// Both forms are accepted — 'consenti:' prefix is optional
+const handler = (data) => console.log('Consent saved:', data.consent)
+widget.on('consentSubmitted', handler)
+
+// Remove later (must pass the same function reference)
+widget.off('consentSubmitted', handler)
+
+// Available event names:
+// 'bannerInitialized' | 'bannerVisibility' | 'modalVisibility'
+// 'consentBeingSubmitted' | 'consentSubmitted'
 ```
 
 ### Manual init
 
 ```ts
 const widget = new ConsentiSetup({
-  core: {},
+  compliance: { type: 'opt-in' },
   rootEl: '#consent-mount',
   autoInit: false,
 })
@@ -400,32 +722,40 @@ await widget.submitConsent({
   marketing: 'denied',
   necessary: 'granted',  // mandatory cookies are always 'granted' regardless
 })
+
+// Or use the convenience methods:
+await widget.grantAll()   // accept all
+await widget.denyAll()    // Reject Optional non-mandatory
 ```
 
 ---
 
 ## Events
 
-Custom DOM events fire on `document` at every lifecycle step. All are prefixed `consenti:`.
-
-| Event                          | Fired when                                               | Detail type                    |
-|--------------------------------|----------------------------------------------------------|--------------------------------|
-| `consenti:bannerInitialized`   | Widget initialises and determines banner visibility      | `BannerInitializedDetail`      |
-| `consenti:bannerVisibility`    | Banner shows or hides                                    | `BannerVisibilityDetail`       |
-| `consenti:modalVisibility`     | Preference modal shows or hides                          | `ModalVisibilityDetail`        |
-| `consenti:consentBeingSubmitted` | User clicked a consent button (before API call)        | `ConsentBeingSubmittedDetail`  |
-| `consenti:consentSubmitted`    | Consent saved (cookie written + API call if configured)  | `ConsentSubmittedDetail`       |
-
-```ts
-document.addEventListener('consenti:consentSubmitted', (e: Event) => {
-  const detail = (e as CustomEvent<ConsentSubmittedDetail>).detail
-  // detail.consentAction — 'accept_all' | 'reject_all' | 'custom' | 'update'
-  // detail.consentJson   — { analytics: 'granted', marketing: 'denied', ... }
-  // detail.visitorId     — stable UUID
-  // detail.pageUrl       — window.location.href at submission time
-  // detail.gpcDetected   — boolean
-  // detail.timestamp     — ISO 8601
-  // detail.apiResponse   — backend response (if api.enabled: true)
+Custom DOM events fire on `window` at every lifecycle step. All are prefixed `consenti:`.
+
+| Event                          | Fired when                                               |
+|--------------------------------|----------------------------------------------------------|
+| `consenti:bannerInitialized`   | Widget initialises and determines banner visibility      |
+| `consenti:bannerVisibility`    | Banner shows or hides                                    |
+| `consenti:modalVisibility`     | Preference modal shows or hides                          |
+| `consenti:consentBeingSubmitted` | User clicked a consent button (before API call)        |
+| `consenti:consentSubmitted`    | Consent saved (cookie written + API call if configured)  |
+| `consenti:parentalConsentRequired` | Age gate declined with `requireParentalConsent: true` — carries `parentalConsentToken` |
+
+**Recommended:** use `widget.on()` / `widget.off()` for typed subscriptions (the `consenti:` prefix is optional):
+
+```ts
+const handler = (data: ConsentEvent) => console.log(data.consent)
+widget.on('consentSubmitted', handler)
+widget.off('consentSubmitted', handler)  // same reference to unsubscribe
+```
+
+**Raw DOM listeners** (equivalent):
+
+```ts
+window.addEventListener('consenti:consentSubmitted', (e: Event) => {
+  const detail = (e as CustomEvent<ConsentEvent>).detail
 })
 ```
 
@@ -433,39 +763,64 @@ document.addEventListener('consenti:consentSubmitted', (e: Event) => {
 
 ## GTM / Google Consent Mode v2
 
+Setting `utils.gtm` to any object (even `{}`) turns on real Consent Mode signalling — no gtag.js
+needs to already be on the page, Consenti defines the standard stub itself.
+
 ```ts
 new ConsentiSetup({
-  core: { regulation: 'gdpr' },
+  compliance: { type: 'opt-in' },
   utils: {
     gtm: {
-      containerId: 'GTM-XXXXXX',
-      urlPassthrough: true,    // cookieless conversion modelling
-      adsDataRedaction: true,  // redact ad pings when consent denied
+      containerId: 'GTM-XXXXXX', // omit if you load GTM/gtag.js yourself
+      urlPassthrough: true,      // cookieless conversion modelling
+      adsDataRedaction: true,    // redact ad pings when consent denied
     },
   },
 })
 ```
 
-Consenti pushes to `window.dataLayer` in the standard Google Consent Mode v2 format:
+**`GtmConfig` options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `containerId` | `string` | `undefined` | GTM container ID, e.g. `'GTM-XXXXXX'`. When set, Consenti injects the GTM library itself — omit if you already load GTM/gtag.js separately (Consent Mode signalling works either way). |
+| `dataLayer` | `string` | `'dataLayer'` | Name of the dataLayer array on `window`. Override only for a custom variable name. |
+| `verbose` | `boolean` | `false` | When `true`, additionally mirrors every `consenti:*` event onto the dataLayer as a generic `{ event, content }` push — for custom, non-Consent-Mode GTM triggers. |
+| `events` | `string[]` | `[]` | Only relevant when `verbose: true` — narrows which event names get mirrored. Empty means all. Has no effect on the core `gtag('consent', …)` calls, which always fire. |
+| `urlPassthrough` | `boolean` | `false` | Calls `gtag('set', 'url_passthrough', true)` alongside every consent update. |
+| `adsDataRedaction` | `boolean` | `false` | Calls `gtag('set', 'ads_data_redaction', true)` when `ad_storage` is denied. |
+
+Consenti calls the real `gtag()` consent API — via the standard stub-queue pattern, so it works
+whether your own gtag.js/GTM snippet loads before or after Consenti:
 
 ```js
 // On initialisation (default denied state)
-dataLayer.push({ 'event': 'consent_default', 'analytics_storage': 'denied', ... })
+gtag('consent', 'default', { analytics_storage: 'denied', ... })
 
 // On submission
-dataLayer.push({ 'event': 'consent_update', 'analytics_storage': 'granted', 'ad_storage': 'denied', ... })
+gtag('consent', 'update', { analytics_storage: 'granted', ad_storage: 'denied', ... })
+
+// Plus, when configured:
+gtag('set', 'url_passthrough', true)
+gtag('set', 'ads_data_redaction', true) // true when ad_storage is denied
 ```
 
-`getGTMConsent()` returns consent in GTM format:
+Set `utils.gtm.verbose: true` to additionally mirror every `consenti:*` event onto the dataLayer
+as a generic `{ event, content }` push — off by default.
+
+`getConsent('google-gtm')` returns consent in Google Consent Mode v2 format. `getGTMConsent()` is a deprecated alias for the same call.
 
 ```ts
-widget.getGTMConsent()
+widget.getConsent('google-gtm')
 // {
 //   analytics_storage: 'granted',
 //   ad_storage: 'denied',
 //   ad_user_data: 'denied',
 //   ad_personalization: 'denied',
 //   functionality_storage: 'granted',
+//   security_storage: 'granted',
+//   ads_data_redaction: 'true',
+//   url_passthrough: 'false',
 // }
 ```
 
@@ -483,6 +838,8 @@ new ConsentScript({
   src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXX',
   onLoad: () => console.log('Analytics loaded'),
   onRevoke: () => console.log('Analytics removed'),
+  // bind: true (default) — auto-removes script on consent revoke, re-injects on re-grant
+  // bind: false          — check consent once at construction; never auto-remove
 })
 ```
 
@@ -555,8 +912,8 @@ Override any token in your own stylesheet:
 
 ```ts
 new ConsentiSetup({
+  compliance: { type: 'opt-in' },
   core: {
-    regulation: 'gdpr',
     theme: {
       primaryColor: '#7c3aed',       // purple brand
       primaryTextColor: '#ffffff',
@@ -572,7 +929,7 @@ new ConsentiSetup({
 
 ```ts
 new ConsentiSetup({
-  core: { profileId: 1 },
+  compliance: { type: 'opt-in' },
   darkMode: true,  // or: window.matchMedia('(prefers-color-scheme: dark)').matches
 })
 ```
@@ -631,7 +988,8 @@ import '@consenti/ui/dist/index.css'
 export function ConsentSetup() {
   useEffect(() => {
     const widget = new ConsentiSetup({
-      core: { regulation: 'gdpr', locale: 'en' },
+      compliance: { type: 'opt-in' },
+      core: { locale: 'en' },
     })
     return () => widget.destroy()
   }, [])
@@ -687,8 +1045,8 @@ export function ConsentSetup() {
     let widget: WidgetType
     import('@consenti/ui').then(({ ConsentiSetup }) => {
       widget = new ConsentiSetup({
-        core: { regulation: 'gdpr', locale: 'en', autoHonorGPC: true },
         api: { enabled: true, baseUrl: process.env.NEXT_PUBLIC_API_URL },
+        core: {  },
       })
       widgetRef.current = widget
     })
@@ -710,7 +1068,7 @@ let widget: unknown = null
 onMounted(async () => {
   const { ConsentiSetup } = await import('@consenti/ui')
   await import('@consenti/ui/dist/index.css')
-  widget = new ConsentiSetup({ core: { regulation: 'gdpr' } })
+  widget = new ConsentiSetup({ compliance: { type: 'opt-in' } })
 })
 
 onBeforeUnmount(() => (widget as { destroy?: () => void })?.destroy?.())
@@ -739,7 +1097,7 @@ export class ConsentService implements OnDestroy {
   async init() {
     if (!isPlatformBrowser(this.platformId)) return
     const { ConsentiSetup } = await import('@consenti/ui')
-    this.widget = new ConsentiSetup({ core: { regulation: 'gdpr' } })
+    this.widget = new ConsentiSetup({ compliance: { type: 'opt-in' } })
   }
 
   ngOnDestroy() {
@@ -766,7 +1124,7 @@ export class MyComponent {
 import { ConsentiSetup } from '@consenti/ui'
 import '@consenti/ui/dist/index.css'
 
-const widget = new ConsentiSetup({ core: { regulation: 'gdpr', locale: 'en' } })
+const widget = new ConsentiSetup({ compliance: { type: 'opt-in' }, core: { locale: 'en' } })
 
 document.querySelector('#cookie-settings')?.addEventListener('click', () => {
   widget.showModal()
@@ -798,7 +1156,7 @@ class MyPlugin extends ConsentiPlugin {
 }
 
 new ConsentiSetup({
-  core: { regulation: 'gdpr' },
+  compliance: { type: 'opt-in' },
   plugins: [new MyPlugin()],
 })
 ```
@@ -809,7 +1167,7 @@ new ConsentiSetup({
 
 ```ts
 // Safe to call during SSR — silently no-ops, never touches the DOM:
-const widget = new ConsentiSetup({ core: { regulation: 'gdpr' } })
+const widget = new ConsentiSetup({ compliance: { type: 'opt-in' } })
 // All browser API access is guarded by isClient() internally.
 ```
 
@@ -830,8 +1188,8 @@ import {
   simulateConsentSubmitted,
 } from '@consenti/ui/testing'
 
-mockAllGranted()   // fake-grant all cookies for unit tests
-mockAllDenied()    // fake-deny all
+mockAllGranted(['analytics', 'marketing'])   // fake-grant these cookies for unit tests
+mockAllDenied(['analytics', 'marketing'])    // fake-deny these cookies
 simulateConsentSubmitted({ analytics: 'granted' })
 ```
 
@@ -840,20 +1198,44 @@ simulateConsentSubmitted({ analytics: 'granted' })
 ## Minimal Recipes
 
 ```ts
-// CCPA opt-out (no banner shown)
-new ConsentiSetup({ core: { regulation: 'ccpa' } })
+// Auto geo-route — no backend, client-side timezone + language heuristic
+new ConsentiSetup({})
+
+// CCPA opt-out for all visitors
+new ConsentiSetup({ compliance: { type: 'opt-out' } })
 
 // Cross-subdomain consent
-new ConsentiSetup({ core: { regulation: 'gdpr', storage: 'cookie', cookieDomains: '.example.com' } })
+new ConsentiSetup({ core: { storage: 'cookie', cookieDomains: '.example.com' } })
 
 // Authenticated user — cross-device sync via API
-new ConsentiSetup({ core: { regulation: 'gdpr', userId: '{{ server_user_id }}' }, api: { enabled: true } })
+new ConsentiSetup({
+  core: { userId: '{{ server_user_id }}' },
+  api: { enabled: true },
+})
 
-// GPC strict mode + GTM
+// GTM
 new ConsentiSetup({
-  core: { regulation: 'gdpr', autoHonorGPC: 'strict' },
+  core: {},
   utils: { gtm: { containerId: 'GTM-XXXXXX', adsDataRedaction: true } },
 })
+
+// Verbose debug logging during development
+new ConsentiSetup({
+  core: { console: ['error', 'warning', 'info', 'log'] },
+})
+
+// Arabic site — RTL derived automatically from locale
+new ConsentiSetup({ core: { locale: 'ar' } })
+
+// COPPA — block under-13s, require parental consent
+new ConsentiSetup({
+  compliance: { ageGate: { enabled: true, minimumAge: 13, requireParentalConsent: true } },
+})
+
+// TCF — install the __tcfapi stub for ad-tech scripts (cmpId must match the backend's tcf config)
+new ConsentiSetup({
+  compliance: { tcf: { enabled: true, cmpId: 280, cmpVersion: 1 } },
+})
 ```
 
 ---
@@ -864,17 +1246,32 @@ All types are exported from the main entry:
 
 ```ts
 import type {
-  ConsentiConfig,       // top-level config object
-  CoreConfig,           // core section
-  ApiConfig,            // api section
-  UtilsConfig,          // utils section
-  GtmConfig,            // utils.gtm section
-  ThemeConfig,          // core.theme section
-  ConsentValue,         // 'granted' | 'denied' | 'objected'
-  ConsentiProfile,      // local profile class
+  ConsentiConfig,           // top-level config object
+  CoreConfig,               // core section
+  ApiConfig,                // api section
+  ComplianceWidgetConfig,   // compliance section
+  AgeGateWidgetConfig,      // compliance.ageGate section
+  WidgetCountryResolverFn,  // custom geo resolver function type
+  UtilsConfig,              // utils section
+  GtmConfig,                // utils.gtm section
+  ThemeConfig,              // core.theme section
+  ConsentValue,             // 'granted' | 'denied' | 'objected'
+  ConsentiProfile,          // local profile class
+  NonEmptyArray,            // [T, ...T[]] — used by usePrebuiltProfiles
 } from '@consenti/ui'
 ```
 
+### Breaking changes from v0.0.x
+
+The following `CoreConfig` fields were **removed** in v0.1.x:
+
+| Removed field        | Replacement |
+|----------------------|-------------|
+| `core.profileId`     | Use `compliance.type` with a compliance group or local profile key |
+| `core.regulation`    | Use `compliance.type` — compliance group is derived server-side or from pre-built profiles |
+| `core.signCookies`   | Implicit: set `core.cookieSigningKey` to enable signing; no separate flag needed |
+| `core.privacyPolicyUrl` | Add a link button directly in the profile banner/modal `buttons` map with `action: 'link'` |
+
 ---
 
 ## Contributing