@consenti/ui 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @consenti/ui
 
-Zero-dependency, GDPR-compliant cookie consent widget for any web framework.
+GDPR-style cookie consent widget for any web framework — zero required runtime dependencies.
 
 [![npm version](https://img.shields.io/npm/v/@consenti/ui.svg)](https://www.npmjs.com/package/@consenti/ui)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE)
@@ -12,12 +12,15 @@ Zero-dependency, GDPR-compliant cookie consent widget for any web framework.
 
 - **Zero runtime dependencies** — browser built-ins only (`fetch`, `crypto.subtle`, `BroadcastChannel`, `CustomEvent`, `document.cookie`, `localStorage`)
 - **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
+- **Multi-regulation** — Maintained: GDPR, CCPA, CPRA, LGPD. Partial: TCF v2.3 (real binary encoding requires the `@consenti/api` backend) — only relevant if you monetize through programmatic/RTB ad exchanges. In development: DPDPA. More via 8 built-in compliance groups — see [ECOSYSTEM.md](../../ECOSYSTEM.md) for per-regulation status
+
+> **Registration is only needed for programmatic ad monetization.** For first-party analytics/marketing consent, Consenti is fully compliant with zero external registration. Consenti implements the IAB TCF/GPP technical specs but is **not** itself a registered CMP; if you do need TCF/GPP, you must register your own `cmpId` with IAB Europe/MSPA independently before going live — see the [TCF & GPP Registration Guide](https://consenti.dev/docs/compliance/tcf-and-gpp-registration).
 - **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
+- **Companion CLI**: [`@consenti/scanner`](../scanner) crawls a site under none/reject-all/accept-all consent states and reports undeclared third-party trackers
 
 ---
 
@@ -35,17 +38,15 @@ ES2020+ · Chrome 80+ · Firefox 74+ · Safari 13.1+
 npm install @consenti/ui
 ```
 
-Then import CSS and the class:
+Then import the class:
 
 ```ts
 import { ConsentiSetup } from '@consenti/ui'
-import '@consenti/ui/dist/index.css'
 ```
 
 ### CDN / UMD (no build step)
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@consenti/ui/dist/index.css" />
 <script src="https://cdn.jsdelivr.net/npm/@consenti/ui/dist/index.umd.js"></script>
 <script>
   const { ConsentiSetup } = ConsentiUI
@@ -63,12 +64,15 @@ import '@consenti/ui/dist/index.css'
 ```
 
 ### CSS options
+Choose any approach to load stylesheet, by default it will be auto injected
 
 | Approach                          | How                                                                   |
 |-----------------------------------|-----------------------------------------------------------------------|
-| Import from package (recommended) | `import '@consenti/ui/dist/index.css'`                        |
+| Auto Injection (recommended)      | by default consenti will inject css                                   |
+| Manual injection (avoids FOUC)    | `import '@consenti/ui/dist/index.css'` in your bundler entry or code and set `disableCssTemplate: true;` |
 | Skip all CSS (bring your own)     | Set `core.disableCssTemplate: true` — no styles injected              |
 | CSS custom properties only        | Import CSS, then override `--consenti-*` variables in your stylesheet |
+| core.theme config in ConsentiSetup| Provide css variables for your stylesheet in the setup as js object   |
 
 ---
 
@@ -107,21 +111,30 @@ A consent banner appears on first visit. Everything below is optional.
 
 ```ts
 import { ConsentiSetup } from '@consenti/ui'
-import '@consenti/ui/dist/index.css'
 
 const widget = new ConsentiSetup({
   // ── Core (optional) ──────────────────────────────────────────────────────────
   core: {
     tenantId: 'acme',              // identifies your tenant's profiles; default: 'default'
     locale: 'en',                  // BCP 47; 'auto' = navigator.language; default: 'auto'
-    autoHonorGPC: true,            // explicit operator override: false | true | 'strict'
-                                   // overrides profile.gpcMode when set
+    dir: 'auto',                   // 'ltr' | 'rtl' | 'auto'; 'auto' derives from locale via
+                                   // Intl.Locale(...).getTextInfo().direction (falls back to a
+                                   // hand-maintained ar/he/fa/ur/ps/sd/ug/yi → rtl list on
+                                   // engines without getTextInfo() support); default: 'auto'
     storage: 'cookie',             // 'cookie' | 'localStorage'; default: 'cookie'
+    cookieName: 'consenti_data',   // cookie/localStorage key name; default: 'consenti_data'
+                                   // not switched automatically by detected region — set
+                                   // explicitly if you want a different name (e.g. 'euconsent-v2',
+                                   // only meaningful if you're using the spec-correct binary TCF
+                                   // encoder — @consenti/api + @iabtechlabtcf/core — since that
+                                   // name implies IAB's binary format, not Consenti's own encoding)
     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
+                                   // prefer widget.getUserId()/setUserId() (or the
+                                   // consenti:listener:identify event) to change it after init
 
     // Pre-built profile fallback
     usePrebuiltProfiles: 'all',    // 'all' (default) | ['opt-in', 'opt-out', ...] (non-empty)
@@ -131,24 +144,31 @@ const widget = new ConsentiSetup({
     console: ['error'],            // log levels emitted: 'info' | 'log' | 'warning' | 'error'
                                    // default: ['error'] only — no noise in production
 
+    // Field names mirror their --consenti-* CSS variable literally (--consenti-color-primary
+    // → colorPrimary). Every field is optional and maps 1:1 to one CSS custom property — see
+    // apps/ui/src/styles/_variables.scss for the full set of ~33 variables. Common ones:
     theme: {
-      bgColor: '#ffffff',
-      textColor: '#1a1a1a',
-      primaryColor: '#1565c0',
-      primaryTextColor: '#ffffff',
-      secondaryColor: '#f0f4f8',
-      secondaryTextColor: '#1a3460',
-      borderColor: '#e2e8f0',
-      accentColor: '#d32f2f',
-      accentTextColor: '#ffffff',
+      colorBg: '#ffffff',
+      colorText: '#1a1a1a',
+      colorTextMuted: '#949dab',
+      colorPrimary: '#1565c0',
+      colorPrimaryText: '#ffffff',
+      colorSecondary: '#f0f4f8',
+      colorSecondaryText: '#1a3460',
+      colorBorder: '#e2e8f0',
+      colorAccent: '#d32f2f',
+      colorAccentText: '#ffffff',
       fontFamily: 'system-ui, sans-serif',
       fontSizeBase: '14px',
       fontSizeHeading: '18px',
       fontSizeMultiplier: '1',
       borderRadius: '8px',
-      buttonBorderRadius: '4px',
+      borderRadiusBtn: '4px',
       toggleBgOn: '#1565c0',
       toggleBgOff: '#cccccc',
+      // ...plus colorSecondaryBorder, colorOverlay, fontFamilyMono, fontWeightHeading,
+      // lineHeight, spacingXs/Sm/Md/Lg, shadow, toggleBgPartial, toggleKnob,
+      // toggleWidth/Height, zBanner/Overlay/Modal
     },
   },
 
@@ -166,11 +186,28 @@ const widget = new ConsentiSetup({
     // WidgetCountryResolverFn → custom async function: () => Promise<{ country, region, confidence }>
     geoDataProvider: 'default',
 
-    // Age gate (optional)
-    ageGate: {
+    // Only meaningful when api.enabled = false (ignored, with a warning, otherwise — the server
+    // resolves the group in that mode). Only overrides country→group mapping; country/region
+    // detection above always uses the embedded geo data.
+    // 'default' → embedded map (default) | a URL string (fetched; the browser's own HTTP cache
+    // honors whatever Cache-Control/ETag the response sends) | an inline ComplianceMapData object
+    complianceMap: 'default',
+
+    // 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,
+    },
+
+    // GPP (IAB Global Privacy Platform, US National section) client stub (optional) — see "GPP" section below
+    gpp: {
       enabled: false,
-      minimumAge: 13,
-      requireParentalConsent: false,
+      cmpId: 0,                    // must match the cmpId configured on the backend (GppConfig)
+      cmpVersion: 1,
+      mspaCoveredTransaction: false, // no honest default — required
+      mspaOptOutOptionMode: 0,     // 0 = not applicable | 1 = yes | 2 = no
+      mspaServiceProviderMode: 0,
     },
   },
 
@@ -211,6 +248,30 @@ 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.
+
 ---
 
 ## Compliance Groups
@@ -260,7 +321,7 @@ new ConsentiSetup({
 | **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.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` |
 
@@ -276,25 +337,158 @@ Set `api.trustDomain: true` to bypass this check (useful for localhost / dev env
 
 ## GPC — Global Privacy Control
 
-GPC mode is set per-profile on the server (`gpcMode: 'honor' | 'strict' | 'ignore'`). Widget config (`core.autoHonorGPC`) overrides the profile value when explicitly set.
+GPC mode is set per-profile on the server (`gpcMode: 'honor' | 'strict' | 'ignore'`). Widget config profileOverrides overrides the profile value when explicitly set.
+
+`gpcMode` only applies once the widget itself has loaded and initialized. If a tag-loading script
+sits earlier in `<head>` (GTM/gtag.js, or another script), it can still fire before that. Use
+`buildSyncGpcSnippet()` to close that gap — it returns a tiny, dependency-free `<script>` string to
+place first in `<head>`, ahead of everything else, that checks `navigator.globalPrivacyControl`
+synchronously and pre-freezes Google Consent Mode v2 to denied:
 
 ```ts
-// Respect profile's gpcMode setting (default)
-new ConsentiSetup({ compliance: { type: 'opt-in' } })
+import { buildSyncGpcSnippet } from '@consenti/ui'
+
+buildSyncGpcSnippet()                                  // default dataLayer name
+buildSyncGpcSnippet({ dataLayerName: 'myDataLayer' })  // custom dataLayer name
+```
 
-// Force honor GPC regardless of profile setting
-new ConsentiSetup({ core: { autoHonorGPC: true } })
+Safe to run before Consenti's own `gtm` config pushes its defaults on init — same values, same
+stub-queue, so the second push is a no-op rather than a conflict. Full walkthrough with the
+`<head>` ordering: [Advanced Configuration → GPC](https://consenti.dev/docs/ui/advanced-configuration).
 
-// Force strict GPC — pre-deny silently, no banner
-new ConsentiSetup({ core: { autoHonorGPC: 'strict' } })
+---
+
+## Age Gate
+
+Age gate is a **per-profile, per-locale** setting — not a widget-config option. GDPR Article 8's
+consent age varies 13–16 by EU member state and DPDPA has its own child-data age rules, so one
+global age doesn't fit a multi-region deployment. Enable it on a profile in the dashboard's Profile
+Editor Step 1 (minimum age, optional parental-consent requirement), and author the modal's
+heading/body/button text per locale in the Main Banner content step — the widget reads it off the
+resolved profile (`profile.ageGate`/`profile.ageGateModal`) automatically, no widget config needed.
+For a standalone/local profile (`registerProfile()`), set `ageGate`/`ageGateModal` directly on the
+`EmbeddedProfile`/`EmbeddedTranslations` you register.
+
+When enabled, it blocks every other consent UI (banner, GPC, CCPA opt-out — all of it waits behind
+the age gate on first visit):
+
+- **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 requested from the backend (`POST /consent/:visitorId/parental-consent-request`,
+  signed with the backend's `compliance.dataSigningHash` when configured — falls back to a
+  client-generated, unsigned token if `api.enabled` is false) and a
+  `consenti:parentalConsentRequired` event fires carrying it. There's no email-sending pipeline
+  built into this package — the event (or your backend's `eventBus.on('consent.parentalConsentRequired', ...)`
+  listener, see the `@consenti/api` README's "Parental consent" section) is the hook for wiring
+  your own out-of-band verification process.
+
+When the parent later completes that process (often on a fresh page with no live widget instance —
+their own device, not the child's), resolve the token with the standalone `resolveParentalConsent`
+export instead of a `ConsentiSetup` method:
+
+```ts
+import { resolveParentalConsent } from '@consenti/ui'
+
+const { visitorId, profileId } = await resolveParentalConsent(token, { baseUrl: 'https://consent.example.com' })
+// dispatches consenti:parentalConsentResolved on window — a page with a live widget instance
+// can listen for it and react (e.g. re-show the banner for the real consent choice); what
+// "resolved" should actually do to consent state is host-defined, same as the request side.
 ```
 
-| `core.autoHonorGPC` | Effect |
-|---|---|
-| `undefined` (default) | Profile's `gpcMode` takes effect |
-| `false` | GPC signal always ignored |
-| `true` | `'honor'` — pre-deny GPC cookies; show GPC banner variant |
-| `'strict'` | Pre-deny silently — no banner shown |
+This is plumbing, not verifiable parental consent by itself — see the `@consenti/api` README for
+the full caveats (token replay isn't prevented, staying stateless is a deliberate tradeoff).
+
+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
+  },
+})
+```
+
+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
+default format the backend's `tcfString` uses), not the full IAB binary bitfield encoding, and
+vendor-list metadata (`gvlVersion`, `publisherCC`) is operator-supplied via `TcfWidgetConfig`
+rather than fetched client-side (the GVL is multi-megabyte; IAB policy expects CMPs to cache their
+own copy server-side rather than have every visitor's browser re-fetch it). `gdprApplies` is
+derived automatically from the resolved profile's compliance group.
+
+For spec-correct binary TC-string encoding, run with the `@consenti/api` backend, set
+`compliance.tcf.publisherCC`, and install the optional `@iabtechlabtcf/core` peer dependency
+(the actively-maintained IAB Tech Lab package — not `iabtcf-core`, which doesn't exist on npm).
+See the [TCF & GPP Registration Guide](https://consenti.dev/docs/compliance/tcf-and-gpp-registration) for details.
+
+---
+
+## GPP — IAB Global Privacy Platform (US National)
+
+Set `compliance.gpp.enabled: true` to install `window.__gpp`, the standard IAB entry point
+scripts call for US state-privacy-law signals (`ping`, `addEventListener`, `removeEventListener`,
+`getSection`, `hasSection`) — `usnat` (US National) section only:
+
+```ts
+new ConsentiSetup({
+  compliance: {
+    gpp: {
+      enabled: true,
+      cmpId: 280,                   // must match the backend's GppConfig
+      cmpVersion: 1,
+      mspaCoveredTransaction: true, // whether this deployment falls under MSPA signatory obligations
+      mspaOptOutOptionMode: 1,      // 0 = not applicable | 1 = yes | 2 = no
+      mspaServiceProviderMode: 0,
+    },
+  },
+})
+```
+
+Sale/sharing opt-out flags are derived automatically from the resolved profile's cookies tagged
+`cpraCategory: 'sale'` / `'sharing'` and the visitor's actual consent — no separate config needed.
+Like TCF, only one CMP may own `window.__gpp` per page; this stub does not overwrite an existing one,
+and follows the standard stub-queue convention so load order relative to third-party scripts doesn't
+matter.
+
+Unlike TCF, GPP's US National section needs no Global Vendor List, so both this stub's `gppString`
+and the backend's `gppString` use the same real, spec-correct encoder when the optional
+`@iabgpp/cmpapi` peer dependency is installed on `@consenti/api` — there's no "simplified fallback"
+format the way TCF has. Without it, `gppString` falls back to a base64url-encoded JSON payload.
+
+---
+
+## 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.
 
 ---
 
@@ -327,12 +521,12 @@ import { ConsentiProfile, ConsentiSetup } from '@consenti/ui'
 const profile = new ConsentiProfile({
   defaultLocale: 'en',
   complianceGroup: 'opt-in',
-  cookies: [
-    { id: 'necessary',  mandatory: true,  expiry: 365 },
-    { id: 'analytics',  listenGpc: true,  expiry: 365 },
-    { id: 'marketing',  listenGpc: true,  expiry: 365,  cpraCategory: 'sale' },
+  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: {
@@ -343,13 +537,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 Optional',    style: 'secondary', action: 'custom', cookies: '!' },
-          { text: 'Customize',          style: 'secondary', action: 'manage' },
-          { text: 'Privacy Policy',     style: 'text',      action: 'link',   url: '/privacy' },
-        ],
+          'accept-all': { text: 'Accept All', style: 'primary', action: 'custom', cookies: '*' },
+          'reject-optional': { text: 'Reject Optional', style: 'primary', action: 'custom', cookies: '!' }, // same weight as accept-all — CNIL requires reject not be visually subordinate
+          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',
@@ -357,10 +552,10 @@ 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: 'Customize',  style: 'secondary', action: 'manage' },
-        ],
+        buttons: {
+          understood: { text: 'Understood', style: 'primary', action: 'custom', cookies: '!' },
+          customize: { text: 'Customize', style: 'secondary', action: 'manage' },
+        },
       },
       preferenceModal: {
         heading: 'Cookie Preferences',
@@ -373,34 +568,32 @@ const profile = new ConsentiProfile({
         persistent: false,        // true = cannot dismiss by clicking outside
         overlayOpacity: 50,
         mobileFullScreenBreakpoint: 576,
-        buttons: [
-          { text: 'Accept All',       style: 'primary', action: 'custom', cookies: '*' },
-          { text: 'Save Preferences', style: 'primary', action: 'submit' },
-          { text: 'Reject Optional',  style: 'text',    action: 'custom', cookies: '!' },
-        ],
-        categories: [
-          {
-            id: 'cat-necessary',
+        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',
             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'
+            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: {
@@ -435,18 +628,77 @@ The widget calls `GET /resolve-profile?tz&lang&locale&tenantId`, receives the pr
 
 ## Cookie Format
 
-Consent is persisted as a single cookie named `consenti_{userId}_{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
+}
 ```
 
-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.
+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 },
+}
+```
 
 ---
 
@@ -472,7 +724,13 @@ 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.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
@@ -502,11 +760,19 @@ widget.deleteConsent()           // delete consent record (cookie + backend if e
 widget.reConsent()               // delete consent and re-show banner
 widget.destroy()                 // unmount DOM elements and remove all event listeners
 
+// Logged-in user identity
+widget.getUserId()               // string | null — current application user ID
+widget.setUserId('user-42')      // reconsents (by default) if it differs from the stored cookie's user
+widget.setUserId(null)           // clear identity (e.g. logout)
+widget.setUserId('user-42', false) // update identity without reconsenting
+// Or dispatch from anywhere (e.g. right after your own login flow completes):
+// window.dispatchEvent(new CustomEvent('consenti:listener:identify', { detail: { userId: 'user-42' } }))
+
 // 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.setTheme({ colorPrimary: '#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
 
@@ -575,7 +841,7 @@ await widget.submitConsent({
 
 // Or use the convenience methods:
 await widget.grantAll()   // accept all
-await widget.denyAll()    // reject all non-mandatory
+await widget.denyAll()    // Reject Optional non-mandatory
 ```
 
 ---
@@ -591,6 +857,15 @@ Custom DOM events fire on `window` at every lifecycle step. All are prefixed `co
 | `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` |
+
+The events above are **outbound** (widget → host). `consenti:listener:*` is the opposite
+direction — **inbound** (host → widget), dispatched by your own code to tell the widget
+something:
+
+| Event                          | Dispatch when                                            |
+|--------------------------------|----------------------------------------------------------|
+| `consenti:listener:identify`   | Your own login/logout flow completes — `detail: { userId: string \| null, reConsent?: boolean }`, equivalent to calling `widget.setUserId(userId, reConsent)` |
 
 **Recommended:** use `widget.on()` / `widget.off()` for typed subscriptions (the `consenti:` prefix is optional):
 
@@ -612,39 +887,64 @@ window.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({
   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',
 // }
 ```
 
@@ -667,20 +967,64 @@ new ConsentScript({
 })
 ```
 
-### CookieTrigger — open banner or modal from any element
+### ConsentAction — run a callback on a parameter's grant status
+
+For integrations that expose their own `sdk.optIn()`/`sdk.optOut()` API (Segment, Mixpanel,
+Amplitude, Sentry, etc.) instead of a `<script>` tag — use `ConsentScript` for that case instead.
+
+```ts
+import { ConsentAction } from '@consenti/ui'
+
+new ConsentAction({
+  id: 'analytics_storage',
+  widget,
+  onGrant: () => analyticsSdk.optIn(),
+  onDeny: () => analyticsSdk.optOut(),
+  // bind: true (default) — re-fires on every future consent change
+})
+```
+
+### CategoryScript / CategoryAction — gate on a whole category
+
+Same as `ConsentScript`/`ConsentAction`, but keyed on a preference-modal category instead of a
+single parameter — "granted" only when *every* parameter in the category is `'granted'`.
 
 ```ts
-import { CookieTrigger } from '@consenti/ui'
+import { CategoryScript, CategoryAction } from '@consenti/ui'
+
+new CategoryScript({ categoryId: 'marketing', widget, src: 'https://example.com/ad-pixel.js' })
+
+new CategoryAction({
+  id: 'marketing',
+  widget,
+  onGrant: () => adSdk.enableAll(),
+  onDeny: () => adSdk.disableAll(),
+})
+```
+
+### scanConsentScripts — declarative `data-*` script gating
+
+Zero-JS integration path: mark `<script>` tags with `data-consenti-consent-script` /
+`data-consenti-category-script` and Consenti scans and wires them up automatically at the end of
+every `init()` cycle (call `scanConsentScripts(widget)` again manually after adding tags at runtime).
+
+```html
+<script type="text/plain" data-consenti-consent-script="analytics_storage" src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX"></script>
+<script type="text/plain" data-consenti-category-script="marketing" src="https://example.com/pixel.js"></script>
+<script type="text/plain" data-consenti-consent-script="ad_storage" data-consenti-bind="false">/* inline snippet, evaluated once */</script>
+```
+
+### BannerTrigger — open banner or modal from any element
+
+```ts
+import { BannerTrigger } from '@consenti/ui'
 
 // Attach to existing element
-new CookieTrigger({ selector: '#cookie-settings', action: 'modal' })
+new BannerTrigger({ widget, el: '#cookie-settings', action: 'modal' })
 
 // Auto-create a button
-new CookieTrigger({
-  action: 'modal',
-  label: 'Manage Cookies',
-  appendTo: document.querySelector('#footer'),
-})
+const trigger = new BannerTrigger({ widget, action: 'modal', label: 'Manage Cookies' })
+document.querySelector('#footer')?.appendChild(trigger.getElement())
 ```
 
 ---
@@ -694,41 +1038,50 @@ Override any token in your own stylesheet:
 ```css
 :root {
   /* Colors */
-  --consenti-primary-text: #1a3460;
-  --consenti-secondary-text: #555555;
-  --consenti-primary-bg: #ffffff;
-  --consenti-secondary-bg: #f5f5f5;
-  --consenti-overlay-bg: rgba(0, 0, 0, 0.5);
-
-  /* Buttons */
-  --consenti-btn-primary-bg: #1565c0;
-  --consenti-btn-primary-text: #ffffff;
-  --consenti-btn-secondary-bg: #f5f5f5;
-  --consenti-btn-secondary-text: #1a3460;
-  --consenti-btn-radius: 6px;
-  --consenti-btn-padding: 0.5rem 1.25rem;
-  --consenti-btn-font-weight: 600;
-
-  /* Banner */
-  --consenti-banner-shadow: 0 -4px 24px rgba(0, 0, 0, 0.12);
-  --consenti-banner-radius: 0;
-  --consenti-banner-padding: 1.5rem;
-  --consenti-banner-max-width: 960px;
-
-  /* Modal */
-  --consenti-modal-radius: 12px;
-  --consenti-modal-shadow: 0 8px 32px rgba(0, 0, 0, 0.24);
-  --consenti-modal-width: 560px;
-  --consenti-modal-max-height: 80vh;
-
-  /* Toggle */
-  --consenti-toggle-on: #1565c0;
-  --consenti-toggle-off: #ccc;
+  --consenti-color-bg: #ffffff;
+  --consenti-color-text: #1a2e4a;
+  --consenti-color-text-muted: #949dab;
+  --consenti-color-primary: #04111f;
+  --consenti-color-primary-text: #ffffff;
+  --consenti-color-secondary: #f0f4f8;
+  --consenti-color-secondary-text: #1a2e4a;
+  --consenti-color-border: #dbe4ee;
+  --consenti-color-secondary-border: #1a2e4a;
+  --consenti-color-overlay: #04111f;
+  --consenti-color-accent: #d32f2f;
+  --consenti-color-accent-text: #ffffff;
 
   /* Typography */
-  --consenti-font-size-base: 14px;
-  --consenti-font-size-mult: 1;
   --consenti-font-family: system-ui, -apple-system, sans-serif;
+  --consenti-font-family-mono: ui-monospace, monospace;
+  --consenti-font-size-base: 14px;
+  --consenti-font-size-heading: 16px;
+  --consenti-font-weight-heading: 600;
+  --consenti-line-height: 1.5;
+
+  /* Spacing */
+  --consenti-spacing-xs: 5px;
+  --consenti-spacing-sm: 8px;
+  --consenti-spacing-md: 16px;
+  --consenti-spacing-lg: 24px;
+
+  /* Shape */
+  --consenti-border-radius: 8px;
+  --consenti-border-radius-btn: 0;
+  --consenti-shadow: 0 4px 24px rgba(21, 101, 192, 0.14);
+
+  /* Toggle (preference modal) */
+  --consenti-toggle-bg-on: #43a047;
+  --consenti-toggle-bg-partial: #97c098;
+  --consenti-toggle-bg-off: #9ca3af;
+  --consenti-toggle-knob: #ffffff;
+  --consenti-toggle-width: 52px;
+  --consenti-toggle-height: 28px;
+
+  /* Stacking */
+  --consenti-z-banner: 9999;
+  --consenti-z-overlay: 9998;
+  --consenti-z-modal: 10000;
 }
 ```
 
@@ -739,10 +1092,10 @@ new ConsentiSetup({
   compliance: { type: 'opt-in' },
   core: {
     theme: {
-      primaryColor: '#7c3aed',       // purple brand
-      primaryTextColor: '#ffffff',
+      colorPrimary: '#7c3aed',       // purple brand
+      colorPrimaryText: '#ffffff',
       borderRadius: '12px',
-      buttonBorderRadius: '999px',   // pill buttons
+      borderRadiusBtn: '999px',   // pill buttons
       fontFamily: 'Inter, sans-serif',
     },
   },
@@ -807,7 +1160,6 @@ new ConsentiSetup({
 
 import { useEffect } from 'react'
 import { ConsentiSetup } from '@consenti/ui'
-import '@consenti/ui/dist/index.css'
 
 export function ConsentSetup() {
   useEffect(() => {
@@ -860,7 +1212,6 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 import { useEffect, useRef } from 'react'
 import type { ConsentiSetup as WidgetType } from '@consenti/ui'
-import '@consenti/ui/dist/index.css'
 
 export function ConsentSetup() {
   const widgetRef = useRef<WidgetType | null>(null)
@@ -870,7 +1221,7 @@ export function ConsentSetup() {
     import('@consenti/ui').then(({ ConsentiSetup }) => {
       widget = new ConsentiSetup({
         api: { enabled: true, baseUrl: process.env.NEXT_PUBLIC_API_URL },
-        core: { autoHonorGPC: true },
+        core: {  },
       })
       widgetRef.current = widget
     })
@@ -891,7 +1242,6 @@ let widget: unknown = null
 
 onMounted(async () => {
   const { ConsentiSetup } = await import('@consenti/ui')
-  await import('@consenti/ui/dist/index.css')
   widget = new ConsentiSetup({ compliance: { type: 'opt-in' } })
 })
 
@@ -930,15 +1280,18 @@ export class ConsentService implements OnDestroy {
 }
 ```
 
-Or use the built-in Angular service:
+Or use the built-in Angular integration (`setConsentiWidget()` once at app root, then
+`injectConsent()` in any component/service):
 
 ```ts
-import { ConsentiService } from '@consenti/ui/angular'
+import { injectConsent } from '@consenti/ui/angular'
 
 @Component({ /* ... */ })
 export class MyComponent {
-  consent = inject(ConsentiService)
+  consent = injectConsent()
   // consent.hasConsent() | consent.showModal() | consent.getConsent()
+  // consent.onConsentChange(cb) / onBannerChange(cb) / onModalChange(cb) — call in
+  // ngOnInit, unsubscribe with the returned function in ngOnDestroy
 }
 ```
 
@@ -946,7 +1299,6 @@ export class MyComponent {
 
 ```js
 import { ConsentiSetup } from '@consenti/ui'
-import '@consenti/ui/dist/index.css'
 
 const widget = new ConsentiSetup({ compliance: { type: 'opt-in' }, core: { locale: 'en' } })
 
@@ -1037,9 +1389,9 @@ new ConsentiSetup({
   api: { enabled: true },
 })
 
-// GPC strict mode + GTM
+// GTM
 new ConsentiSetup({
-  core: { autoHonorGPC: 'strict' },
+  core: {},
   utils: { gtm: { containerId: 'GTM-XXXXXX', adsDataRedaction: true } },
 })
 
@@ -1047,6 +1399,17 @@ new ConsentiSetup({
 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: set on the profile in the dashboard
+// (Profile Editor Step 1 → Enable age gate → minimum age 13, require parental consent), not here.
+
+// 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 } },
+})
 ```
 
 ---
@@ -1061,11 +1424,11 @@ import type {
   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
+  IdentifyEventDetail,      // consenti:listener:identify event detail
   ConsentValue,             // 'granted' | 'denied' | 'objected'
   ConsentiProfile,          // local profile class
   NonEmptyArray,            // [T, ...T[]] — used by usePrebuiltProfiles
@@ -1081,7 +1444,18 @@ The following `CoreConfig` fields were **removed** in v0.1.x:
 | `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` array with `action: 'link'` |
+| `core.privacyPolicyUrl` | Add a link button directly in the profile banner/modal `buttons` map with `action: 'link'` |
+
+---
+
+## Security notes
+
+**`core.cookieSigningKey` is spoofable in standalone mode.** Without a `@consenti/api` backend,
+this key has nowhere to live but the shipped browser bundle — so anyone can read it out of your JS
+and re-sign a forged cookie with it. It still catches accidental tampering (e.g. a stale value from
+an older config), but it is not tamper-*proof* against a motivated attacker. If you need consent
+records that hold up as evidence, sign them server-side instead with `compliance.dataSigningHash`
+(`@consenti/api`), where the key never reaches the browser.
 
 ---