@consenti/ui 0.2.0 → 0.4.0

package/dist/vue.d.cts

@@ -1,11 +1,46 @@
 import * as vue from 'vue';
 
 type NonEmptyArray<T> = [T, ...T[]];
+/**
+ * Deep-partial with JSON Merge Patch (RFC 7396) delete semantics: any key may be
+ * set to `null` instead of its usual type to signal "delete this key" when the
+ * partial is applied with `deepMerge()` — `undefined`/omitted keeps the base
+ * value, `null` removes it. Only meaningful for object/map keys (e.g. removing
+ * a `CategoryMap`/`CookieMap` entry via `profileOverride`); array elements are
+ * merged positionally and don't support deletion this way.
+ */
 type DeepPartial<T> = T extends Function ? T : T extends Array<infer InferredArrayType> ? Array<DeepPartial<InferredArrayType>> : T extends ReadonlyArray<infer InferredReadonlyArrayType> ? ReadonlyArray<DeepPartial<InferredReadonlyArrayType>> : T extends object ? {
-    [Key in keyof T]?: DeepPartial<T[Key]>;
+    [Key in keyof T]?: DeepPartial<T[Key]> | null;
 } : T;
 
+/**
+ * Single source of truth for all compliance groups, regulations, and country mappings.
+ *
+ * This is DATA, not types. The `Compliance` and `ComplianceGroupId` literal types
+ * derived from the ID arrays below live in @consenti/types (packages/types/src/compliance.ts),
+ * via a type-only import — that keeps @consenti/types free of runtime code.
+ *
+ * ─── HOW TO UPDATE ────────────────────────────────────────────────────────────
+ *
+ * ADD A NEW REGULATION:
+ *   1. Add regulation ID string to `COMPLIANCE_REGULATION_IDS` below
+ *      (the `Compliance` type in @consenti/types auto-updates from it).
+ *   2. Add it to the appropriate group's `compliances` array below.
+ *   3. Add / update the country entry in `EMBEDDED_COMPLIANCE_MAP` below.
+ *   That is all — no other files need touching.
+ *
+ * ADD A NEW COMPLIANCE GROUP:
+ *   1. Add the kebab-case ID to `COMPLIANCE_GROUP_IDS` below.
+ *   2. Add a full group entry to `COMPLIANCE_GROUPS` below (label, compliances, flags).
+ *   3. Add a validation rule set to `COMPLIANCE_VALIDATION_RULES` below.
+ *   4. Map affected countries in `EMBEDDED_COMPLIANCE_MAP` to the new group.
+ *
+ * ADD OR UPDATE A COUNTRY:
+ *   Edit the entry in `EMBEDDED_COMPLIANCE_MAP.countries` below. That is the ONLY
+ *   place that needs changing for country-level jurisdiction updates.
+ */
 declare const COMPLIANCE_GROUP_IDS: readonly ["opt-in", "opt-out", "opt-out-strict", "opt-in-dpdpa", "opt-in-china", "opt-in-brazil", "general-privacy-consent", "notice-only"];
+declare const COOKIE_PURPOSE_IDS: readonly ["necessary", "functional", "preferences", "analytics", "marketing"];
 
 /**
  * Compliance-related literal types, derived from the regulation/group ID data
@@ -21,6 +56,13 @@ declare const COMPLIANCE_GROUP_IDS: readonly ["opt-in", "opt-out", "opt-out-stri
  */
 
 type ComplianceGroupId = typeof COMPLIANCE_GROUP_IDS[number];
+/**
+ * `(string & {})` (rather than plain `string`) keeps IDE autocomplete for the
+ * known `ComplianceGroupId` literals while still allowing any other string —
+ * used to target a profile authored against a custom (non-built-in)
+ * `customComplianceGroup` instead of one of the 8 built-in groups.
+ */
+type ComplianceType = 'auto' | ComplianceGroupId | (string & {}) | Symbol;
 
 interface ComplianceMapData {
     version: string;
@@ -28,31 +70,81 @@ interface ComplianceMapData {
 }
 interface CountryComplianceEntry {
     complianceGroup: ComplianceGroupId;
-    default: ComplianceGroupId;
-    description: string;
+    /** Fallback group used when only the country (not the region) is known. Defaults to
+     * `complianceGroup` when omitted — only set this explicitly when a region within this
+     * country can be stricter than the country-wide baseline (see `overriddenRegions`). */
+    default?: ComplianceGroupId;
+    description?: string;
     overriddenRegions?: Record<string, {
         complianceGroup: ComplianceGroupId;
-        description: string;
+        description?: string;
     }>;
 }
+interface ConsentDbRecord {
+    id: string;
+    tenantId: string;
+    visitorId: string;
+    profileId: string;
+    locale: string;
+    consentJson: ConsentValue;
+    gpcDetected: boolean;
+    source: 'banner' | 'api' | 'import';
+    ageVerified?: boolean;
+    parentalConsentToken?: string;
+    tcfString?: string;
+    gppString?: string;
+    /** HMAC-SHA256 signature over the record's core fields, hex-encoded — tamper-evidence for
+     * server-stored records via `dataSigningHash` (auto-generated when unset), independent of the
+     * widget's own cookie-signing (`core.cookieSigningKey`). */
+    signature?: string;
+    createdAt: string;
+    updatedAt: string;
+}
 
 type ConsentStatus = 'granted' | 'denied' | 'objected';
 type ConsentAction = 'accept_all' | 'reject_all' | 'custom' | 'update';
 type ConsentValue = Record<string, ConsentStatus>;
+/**
+ * Output format for getConsent(type).
+ * 'default'           → raw ConsentValue, keyed by every cookie parameter ID in the profile (existing behaviour)
+ * 'google-gtm'        → Google Consent Mode v2 keys + ads_data_redaction, url_passthrough
+ * 'purpose'           → consent per the fixed CookiePurpose taxonomy (necessary/functional/preferences/analytics/marketing)
+ * 'category'          → consent per the tenant's own authored preference-modal category, keyed by category ID.
+ *                        'granted' only when every member parameter is granted; 'denied'/'objected' otherwise
+ *                        (same ConsentStatus values as everything else — see getCategoryConsent for the exact rule)
+ * 'adobe'             → { analytics, target, manager, optimizer }
+ * 'meta'              → { pixel, api, plugins, facebookLogin }
+ * 'microsoft-clarity' → { session, heatmaps, performance }
+ * 'twilio-segment'    → { identify, page, track, group, alias }
+ */
+type ConsentType = 'default' | 'google-gtm' | 'purpose' | 'category' | 'adobe' | 'meta' | 'microsoft-clarity' | 'twilio-segment';
+type GpcMode = 'ignore' | 'honor' | 'strict';
+type LegalBasis = 'mandatory' | 'consent' | 'legitimate_interest';
+type CookiePurpose = typeof COOKIE_PURPOSE_IDS[number];
+/**
+ * A single consent parameter (tracker/cookie definition).
+ * Keyed by its own id inside `Record<string, Cookie>` — the map key IS the id,
+ * there is no `id` field on the value itself.
+ */
 interface Cookie {
-    id: string;
-    legalBasis?: 'mandatory' | 'consent' | 'legitimate_interest';
-    /** @deprecated use legalBasis: 'mandatory' */
-    mandatory?: boolean;
-    /** @deprecated use legalBasis */
-    type?: 'consent' | 'legitimate_interest';
+    purpose?: CookiePurpose;
     listenGpc?: boolean;
-    expiry?: number;
+    /**
+     * Pre-grant this parameter's default consent to 'granted' (instead of the
+     * compliance-group-driven default) when no stored decision exists yet.
+     * Only meaningful when the owning category's `legalBasis === 'consent'` —
+     * `mandatory`/`legitimate_interest` categories are already effectively
+     * pre-granted regardless of this flag. Never overrides an active GPC signal.
+     * Default: false.
+     */
+    preGrant?: boolean;
     tcfVendorId?: number;
     tcfPurposes?: number[];
     tcfSpecialFeatures?: number[];
     cpraCategory?: 'sale' | 'sharing' | 'sensitive';
 }
+/** `Cookie` keyed by its own id — the standard shape used everywhere a parameter list is passed around. */
+type CookieMap = Record<string, Cookie>;
 type ButtonStyle = 'primary' | 'secondary' | 'text' | 'accent';
 type ButtonAction = 'submit' | 'manage' | 'close' | 'custom' | 'link';
 interface Button {
@@ -61,8 +153,11 @@ interface Button {
     action: ButtonAction;
     cookies?: string[] | '*' | '!';
     url?: string;
-    type?: string;
 }
+/** `Button` keyed by its own id — e.g. `'accept-all'`. The map key IS the id, rendered as the DOM
+ * `id` (`consenti-btn-{id}`) so integrators can target specific buttons, and is what
+ * `profileOverride`'s `deepMerge` deletes by (`{ 'reject-optional': null }` removes one button). */
+type ButtonMap = Record<string, Button>;
 interface MainBanner {
     position: 'top' | 'bottom' | 'middle' | 'left-bottom' | 'right-bottom';
     overlayOpacity?: number;
@@ -71,68 +166,187 @@ interface MainBanner {
     heading?: string;
     headingTag?: string;
     htmlText: string;
-    buttons: Button[];
+    buttons: ButtonMap;
+    /** Stack buttons vertically below this viewport width in px. 0 or undefined = disabled. Default: 576. */
+    stackButtonsOnBreakpoint?: number;
+    /** Trap keyboard Tab focus within the consent root while this banner is visible. */
+    trapFocus?: boolean;
 }
 type GpcBanner = MainBanner;
+/**
+ * A consent category — the single source of legal basis for every parameter
+ * it lists in `cookies`. Keyed by its own id inside `Record<string, Category>` —
+ * the map key IS the id, there is no `id` field on the value itself.
+ *
+ * A parameter must belong to exactly one category (enforced at authoring time,
+ * not by this type) — that relationship is what `getCookieLegalBasis`/
+ * `isMandatoryCookie` (`@consenti/utils`) resolve at runtime.
+ */
 interface Category {
-    id: string;
     heading: string;
     headingTag?: string;
     htmlText: string;
-    mandatory?: boolean;
-    type?: 'consent' | 'legitimate_interest';
-    legitimateInterest?: {
-        enabled?: boolean;
-        description?: string;
-    };
+    legalBasis: LegalBasis;
+    /** Only meaningful when legalBasis === 'legitimate_interest' — the GDPR balancing-test justification shown to visitors. */
+    legitimateInterestDescription?: string;
+    /** IDs of the parameters (from the profile's `cookies` map) that belong to this category. */
     cookies: string[];
 }
+/** `Category` keyed by its own id — the standard shape used everywhere a category list is passed around. */
+type CategoryMap = Record<string, Category>;
 interface PreferenceModal extends Omit<MainBanner, "position"> {
     position?: 'left' | 'right' | 'center';
     subheading?: string;
-    categories: Category[];
+    categories: CategoryMap;
     persistent?: boolean;
     /** Screen width in px below which the modal expands to full screen. Default: 576. Set to 0 to disable. */
     mobileFullScreenBreakpoint?: number;
+    /** Label for the optional consent-receipt download checkbox (shown when `allowReceipt` is true). Falls back to a default when omitted. */
+    receiptLabel?: string;
+    /** Description shown beneath the consent-receipt checkbox. Falls back to a default when omitted. */
+    receiptDescription?: string;
+    /**
+     * Renders a "Forget me" control in the modal body, below the categories — only shown to
+     * visitors who already have a stored consent decision (nothing to erase otherwise). Wired to
+     * the same `DELETE /consent/:visitorId` erasure endpoint as `widget.deleteConsent()`, giving
+     * visitors self-service access to GDPR Art. 17 / CCPA-CPRA / LGPD Art. 18 / UK GDPR / DPDPA /
+     * KVKK / POPIA / PDPA-TH / APPI erasure-equivalent rights without the host wiring a link
+     * themselves. See the "Right to erasure" guide for the full compliance mapping.
+     */
+    showForgetMe?: boolean;
+    /** Label for the "Forget me" button (shown when `showForgetMe` is true). Falls back to a default when omitted. */
+    forgetMeLabel?: string;
 }
 interface DpdpaConfig {
     dataFiduciary: string;
     grievanceEmail: string;
     purposeDescription?: string;
 }
+/**
+ * Per-profile age gate — GDPR Art. 8's consent age varies 13–16 by EU member state and DPDPA has
+ * its own child-data age rules, so one global age (the old `ConsentiServerConfig.ageGate`) was
+ * wrong for a multi-region deployment. Mirrors `dpdpa` exactly: profile-scoped, not global.
+ */
+interface AgeGateConfig {
+    enabled: boolean;
+    minimumAge: number;
+    requireParentalConsent?: boolean;
+}
+/** Per-locale age-gate modal text — translated the same way `mainBanner`/`preferenceModal`
+ * content is, unlike the widget's own hardcoded UI chrome (close button, locale switcher). */
+interface AgeGateModalContent {
+    heading?: string;
+    htmlText: string;
+    confirmButtonLabel: string;
+    denyButtonLabel: string;
+    parentalConsent: {
+        heading?: string;
+        htmlText: string;
+        confirmButtonLabel: string;
+    };
+}
 interface ResolvedProfile {
-    id: number;
-    profileUuid?: string;
-    version: number;
+    id: string;
+    /** Incremented in place on every save of this profile. Absent for embedded/local profiles that have no server-side version counter. */
+    version?: number;
     defaultLocale: string;
     locales?: string[];
-    cookies: Cookie[];
+    cookies: CookieMap;
+    /** Days until consent expires and the visitor is asked again (profile-wide). Default: 365. */
+    expiryDays?: number;
+    allowReceipt?: boolean;
     mainBanner: MainBanner;
     gpcBanner?: GpcBanner;
     preferenceModal: PreferenceModal;
     cookieSigningKey?: string;
     dpdpa?: DpdpaConfig;
+    ageGate?: AgeGateConfig;
+    ageGateModal?: AgeGateModalContent;
     darkMode?: boolean;
-    gpcMode?: 'ignore' | 'honor' | 'strict';
-    complianceGroup?: string;
+    gpcMode?: GpcMode;
+    /** One of the 8 built-in groups, or a custom group id (via `customComplianceGroup` /
+     * `ComplianceType`'s string passthrough) — this is the join key `complianceGroupsOverride`
+     * looks up by, so it must reflect whichever group this profile actually resolved against,
+     * built-in or custom. */
+    complianceGroup?: ComplianceGroupId | (string & {});
+    /** Set when the geo-resolved region carries a `requiresSensitiveOptIn` carve-out (e.g.
+     * Colorado under `opt-out`) — cookies tagged `cpraCategory: 'sensitive'` default to denied
+     * even though the rest of `complianceGroup`'s cookies default to granted. Only ever set by
+     * server-side geo resolution (`api.enabled: true` + a geoip/maxmind provider); the
+     * client-only timezone heuristic never resolves a region, so this is always unset there. */
+    requiresSensitiveOptIn?: boolean;
     complianceConfig?: Record<string, string>;
+    /** Falls back to `true` (hidden) if neither the widget config nor the profile set it. */
+    hidePoweredBy?: boolean;
+    /** Show metadata footer strip (Consent ID, Date, Version, Privacy Settings link). */
+    showFooterMetadata?: boolean;
+    /** Apply WCAG 2.1 AA accessibility enhancements to the widget. */
+    enhanceAccessibility?: boolean;
 }
 type WidgetCountryResolverFn = () => Promise<{
     country: string | null;
     region: string | null;
     confidence: number;
+    /** Optional escape hatch: when set, profile resolution uses this compliance group directly
+     * instead of computing one from `country`/`region` — mirrors the server-side `GeoResult`'s
+     * `complianceGroup` field (`@consenti/types`'s `api.ts`). `country`/`region` are still used for
+     * anything that reads them independently of group selection. Optional — omitting it preserves
+     * the existing timezone/language-based resolution exactly as before. */
+    complianceGroup?: string;
 }>;
-interface AgeGateWidgetConfig {
+/** Mirrors the server-side `TcfConfig` shape (`@consenti/api`) — `cmpId`/`cmpVersion` must match
+ * what the backend uses to encode `tcfString`, since both feed the same simplified TC string.
+ *
+ * The client-side `__tcfapi` stub never fetches the Global Vendor List itself (multi-megabyte,
+ * and IAB policy requires CMPs to cache their own copy rather than have every visitor's browser
+ * fetch it) — `publisherCC`/`vendorListVersion`/`gvlVersion` are therefore operator-supplied
+ * config here, not auto-derived. Spec-correct binary TC-string encoding happens server-side in
+ * `@consenti/api` (see `compliance.tcf.publisherCC` there); this stub's `tcString` stays the
+ * simplified format documented in `@consenti/utils`'s `encodeTcString`. */
+interface TcfWidgetConfig {
     enabled: boolean;
-    minimumAge: number;
-    requireParentalConsent?: boolean;
+    cmpId: number;
+    cmpVersion: number;
+    /** ISO 3166-1 alpha-2 publisher country code. No honest default exists — leave unset only if
+     * you don't rely on this field downstream; ad-tech vendors that read it will see 'AA'
+     * (an explicit "not configured" placeholder, not a real country). */
+    publisherCC?: string;
+    /** Known Global Vendor List version, if you track it. Defaults to 0 ("unknown"). */
+    vendorListVersion?: number;
+    /** Known GVL specification version, if you track it. Defaults to 0 ("unknown"). */
+    gvlVersion?: number;
+}
+/** Mirrors the server-side `GppConfig` shape (`@consenti/api`) — `cmpId`/`cmpVersion` must match
+ * what the backend uses to encode `gppString`. Unlike TCF, the GPP US National section needs no
+ * Global Vendor List, so both the widget's `window.__gpp` and the server's `gppString` use the
+ * same real, spec-correct encoder (the optional `@iabgpp/cmpapi` peer dependency) — there's no
+ * "simplified fallback" format the way TCF has, since a non-spec GPP string has no consumer that
+ * would accept it. When `@iabgpp/cmpapi` isn't installed, `window.__gpp` is simply not exposed. */
+interface GppWidgetConfig {
+    enabled: boolean;
+    cmpId: number;
+    cmpVersion: number;
+    /** MSPA "covered transaction" — whether this deployment's data transactions fall under MSPA
+     * signatory obligations. No honest default, so it's required rather than optional. */
+    mspaCoveredTransaction: boolean;
+    /** IAB's tri-state encoding for both MSPA fields: 0 = not applicable, 1 = yes, 2 = no. */
+    mspaOptOutOptionMode: 0 | 1 | 2;
+    mspaServiceProviderMode: 0 | 1 | 2;
 }
 interface ComplianceWidgetConfig {
-    type?: 'auto' | ComplianceGroupId | string;
+    type?: ComplianceType;
     geoDataProvider?: 'default' | WidgetCountryResolverFn;
-    autoComplianceMap?: 'default' | ComplianceMapData | 'auto';
-    complianceMapUrl?: string;
-    ageGate?: AgeGateWidgetConfig;
+    /** Only meaningful in standalone mode (no `api.enabled`) — ignored (with a warning) when
+     * `api.enabled: true`, since the server resolves the compliance group in that mode.
+     * `'default'` (embedded map, the default), a URL to fetch a JSON `ComplianceMapData`
+     * document from (the browser's own HTTP cache honors whatever `Cache-Control`/`ETag` the
+     * response sends — no custom caching here), or an inline operator-supplied `ComplianceMapData`
+     * object. Invalid data from either a URL or an object logs a warning and falls back to
+     * `'default'`. Only overrides the country→group mapping — country/region detection itself
+     * always uses the embedded geo data. */
+    complianceMap?: 'default' | string | ComplianceMapData;
+    tcf?: TcfWidgetConfig;
+    gpp?: GppWidgetConfig;
 }
 interface GtmConfig {
     containerId?: string;
@@ -140,6 +354,7 @@ interface GtmConfig {
     dataLayer?: string;
     urlPassthrough?: boolean;
     adsDataRedaction?: boolean;
+    verbose?: boolean;
 }
 interface UtilsConfig {
     gtm?: GtmConfig;
@@ -149,45 +364,81 @@ interface ApiConfig {
     baseUrl?: string;
     authToken?: string;
     tenantId?: string;
-    complianceGroup?: string;
+    complianceGroup?: ComplianceGroupId;
     trustDomain?: boolean;
 }
+/** Field names mirror their `--consenti-*` CSS variable literally (`--consenti-color-primary`
+ * → `colorPrimary`) — see `applyTheme()` in `consenti-setup.ts` for the full mapping. */
 interface ThemeConfig {
-    bgColor?: string;
-    textColor?: string;
-    primaryColor?: string;
-    primaryTextColor?: string;
-    secondaryColor?: string;
-    secondaryTextColor?: string;
-    borderColor?: string;
+    colorBg?: string;
+    colorText?: string;
+    colorTextMuted?: string;
+    colorPrimary?: string;
+    colorPrimaryText?: string;
+    colorSecondary?: string;
+    colorSecondaryText?: string;
+    colorBorder?: string;
+    colorSecondaryBorder?: string;
+    colorOverlay?: string;
+    colorAccent?: string;
+    colorAccentText?: string;
     fontFamily?: string;
+    fontFamilyMono?: string;
     fontSizeBase?: string;
     fontSizeHeading?: string;
     fontSizeMultiplier?: string;
+    fontWeightHeading?: string;
+    lineHeight?: string;
+    spacingXs?: string;
+    spacingSm?: string;
+    spacingMd?: string;
+    spacingLg?: string;
     borderRadius?: string;
-    buttonBorderRadius?: string;
+    borderRadiusBtn?: string;
+    shadow?: string;
     toggleBgOn?: string;
+    toggleBgPartial?: string;
     toggleBgOff?: string;
-    accentColor?: string;
-    accentTextColor?: string;
+    toggleKnob?: string;
+    toggleWidth?: string;
+    toggleHeight?: string;
+    zBanner?: string;
+    zOverlay?: string;
+    zModal?: string;
 }
 interface CoreConfig {
     tenantId?: string;
-    autoHonorGPC?: boolean | 'strict';
     locale?: string;
+    /** Text direction for the banner/modal root. `'auto'` (default) derives it from `locale` via
+     * `Intl.Locale(...).getTextInfo().direction` (falling back to a hand-maintained RTL-language
+     * list on engines without `getTextInfo()` support); set explicitly to override. */
+    dir?: 'ltr' | 'rtl' | 'auto';
     disableCssTemplate?: boolean;
     cookieSigningKey?: string;
     allowReceipt?: boolean;
     cookieDomains?: string;
+    /** Name of the consent cookie/localStorage key. Default: `'consenti_data'`. Not switched
+     * automatically by detected region — set explicitly if you want a different name (e.g.
+     * `'euconsent-v2'`, the IAB TCF convention, but only meaningful for operators using the
+     * spec-correct binary encoder — `@consenti/api` + the optional `@iabtechlabtcf/core` peer
+     * dependency — since the IAB name implies IAB's binary format, not Consenti's own encoding). */
+    cookieName?: string;
     storage?: 'cookie' | 'localStorage';
     theme?: ThemeConfig;
+    /** Initial logged-in application user ID; empty/anonymous when unset. Prefer `getUserId()`/
+     * `setUserId()` (or the `consenti:listener:identify` event) to change it after init — those
+     * also handle reconsent when the identity changes on a shared device. */
     userId?: string;
     usePrebuiltProfiles?: 'all' | NonEmptyArray<ComplianceGroupId>;
     cacheResolvedProfiles?: boolean;
     console?: Array<'info' | 'log' | 'warning' | 'error'>;
 }
 interface ConsentiConfig {
-    core: CoreConfig;
+    verbose?: boolean;
+    /** Optional — every field of `CoreConfig` is itself optional, so `new ConsentiSetup({})` and
+     * `new ConsentiSetup({ compliance: { type: 'opt-in' } })` (omitting `core` entirely) both work,
+     * matching the widget's own "Minimal config" documentation. */
+    core?: CoreConfig;
     compliance?: ComplianceWidgetConfig;
     rootEl?: string | HTMLElement;
     darkMode?: boolean;
@@ -196,13 +447,30 @@ interface ConsentiConfig {
     utils?: UtilsConfig;
     plugins?: ConsentiPlugin[];
     profileOverride?: DeepPartial<ResolvedProfile>;
+    /** Per-compliance-group text/button/cookie overrides — applied on top of whichever profile the
+     * visitor's resolved group loads, keyed by that group's id (one of the 8 built-in
+     * `ComplianceGroupId`s, or any custom group id). Lets you author different copy per country
+     * without creating a separate profile (and separate `compliance.type` wiring) for each one —
+     * e.g. `{ 'opt-in': { mainBanner: { htmlText: '...' } }, 'my-custom-group': { ... } }`.
+     * Applied before `profileOverride`, which still always applies last as the universal catch-all.
+     * Works identically in standalone and server (`api.enabled`) mode. */
+    complianceGroupsOverride?: Partial<Record<ComplianceGroupId | (string & {}), DeepPartial<ResolvedProfile>>>;
     /** When true, suppresses the "Powered by Consenti" footer link in the banner and modal. */
     hidePoweredBy?: boolean;
 }
-type ConsentiEventName = 'bannerInitialized' | 'consenti:bannerInitialized' | 'bannerVisibility' | 'consenti:bannerVisibility' | 'modalVisibility' | 'consenti:modalVisibility' | 'consentBeingSubmitted' | 'consenti:consentBeingSubmitted' | 'consentSubmitted' | 'consenti:consentSubmitted';
+type ConsentiEventName = 'bannerInitialized' | 'consenti:bannerInitialized' | 'bannerVisibility' | 'consenti:bannerVisibility' | 'modalVisibility' | 'consenti:modalVisibility' | 'consentBeingSubmitted' | 'consenti:consentBeingSubmitted' | 'consentSubmitted' | 'consenti:consentSubmitted' | 'parentalConsentRequired' | 'consenti:parentalConsentRequired' | 'forgetMeRequested' | 'consenti:forgetMeRequested' | 'forgotten' | 'consenti:forgotten';
+/** Snapshot of the current visitor's identity. `visitorId` is `null` until a consent decision
+ * has actually happened — it's never minted just to answer this call, see `getVisitor()`. */
+interface VisitorIdentity {
+    visitorId: string | null;
+    type: 'authenticated' | 'anonymous';
+    userId: string | null;
+}
 interface ConsentiWidgetAPI {
     hasConsent(): boolean;
     getConsent(): ConsentValue | null;
+    getConsent(type: ConsentType): Record<string, string> | null;
+    getConsent(type?: ConsentType): ConsentValue | Record<string, string> | null;
     getConsentDate(): Date | false;
     getGTMConsent(): Record<string, string> | null;
     isCookieGranted(cookieId: string, requestValue?: boolean): boolean | ConsentStatus;
@@ -215,8 +483,8 @@ interface ConsentiWidgetAPI {
     off(event: ConsentiEventName, handler: (data: ConsentEvent) => void): void;
     version(): {
         package: string;
-        profileVersion: number | null;
-        consentVersion: number;
+        profileVersion: string | null;
+        consentVersion: string | null;
     };
     bannerVisibility(): 'main' | 'gpc' | false;
     modalVisibility(): 'preference' | false;
@@ -225,13 +493,28 @@ interface ConsentiWidgetAPI {
     hideBanner(): void;
     showModal(triggerEl?: HTMLElement): void;
     hideModal(): void;
-    submitConsent(consent: Partial<ConsentValue>): Promise<void>;
+    submitConsent(consent: Partial<ConsentValue>): Promise<ConsentDbRecord | void>;
     deleteConsent(): Promise<void>;
     reConsent(): Promise<void>;
+    /** Erases the stored consent record (same underlying call as `deleteConsent()`) and
+     * re-prompts, dispatching `consenti:forgetMeRequested` / `consenti:forgotten` around it so a
+     * host app can hook its own identity-verified erasure workflow. Powers the preference modal's
+     * "Forget me" button; also callable directly for a custom placement of the same action. */
+    forgetMe(resetAgeGate?: boolean): Promise<void>;
     getRootElement(): HTMLElement | null;
     getBannerElement(): HTMLElement | null;
     getModalElement(): HTMLElement | null;
     switchLocale(locale: string): void;
+    getUserId(): string | null;
+    /** Sets the logged-in application user ID (`null` for anonymous/logout). When the stored
+     * consent record's user differs from the new value, reconsents by default — pass
+     * `reConsent: false` to just update the identity without prompting again. No-ops (no
+     * reconsent, no warning) when there's no prior consent record to compare against. */
+    setUserId(userId: string | null, reConsent?: boolean): Promise<void>;
+    /** Snapshot of the current visitor's identity: the stable per-browser `visitorId` (`null` if
+     * no consent decision has happened yet — this never creates one), whether they're
+     * `authenticated` or `anonymous`, and the app `userId` (same as `getUserId()`). */
+    getVisitor(): VisitorIdentity;
     setDarkMode(enable?: boolean): void;
     setTheme(theme: Partial<ThemeConfig>): void;
     setConfig(config: DeepPartial<ConsentiConfig>): void;
@@ -249,19 +532,75 @@ declare abstract class ConsentiPlugin {
     onModalShow?(): void | Promise<void>;
     onModalHide?(): void | Promise<void>;
 }
-interface ConsentEvent {
-    profileId?: number;
-    consent?: ConsentValue;
-    hasExistingConsent?: boolean;
-    show?: boolean;
-    action?: boolean;
-    consentAction?: ConsentAction;
-    consentId?: string;
-    pageUrl?: string;
-    apiResponse?: unknown;
+interface BannerInitializedDetail {
+    profileId: string;
+    complianceGroup?: ComplianceType;
+    hasExistingConsent: boolean;
+    gpcDetected: boolean;
+    willShow: boolean;
+}
+interface BannerVisibilityDetail {
+    visible: boolean;
+    variant: 'main' | 'gpc';
+    action: boolean;
+}
+interface ModalVisibilityDetail {
+    visible: boolean;
+    action: boolean;
+}
+interface ConsentBeingSubmitted {
+    consentId: string;
+    visitorId: string;
+    profileId: string;
+    consentJson: ConsentValue;
+    consentAction: ConsentAction;
+    gpcDetected: boolean;
+    pageUrl: string;
+    timestamp: number;
     fromBroadcast?: boolean;
-    gpcDetected?: boolean;
 }
+interface ConsentSubmittedDetail extends ConsentBeingSubmitted {
+    apiResponse: ConsentDbRecord;
+}
+/** Dispatched when the age gate is declined and `requireParentalConsent` is set — see the
+ * profile's `AgeGateConfig`. A deny-all consent (mandatory cookies only) has already been
+ * submitted with `parentalConsentToken` attached; this event is the hook for the site
+ * owner to run their own out-of-band parental-consent verification. `parentalConsentToken` is
+ * server-issued (and signed, when `compliance.dataSigningHash` is configured) when `api.enabled`,
+ * otherwise a client-generated, unsigned fallback — see `POST /consent/:visitorId/parental-consent-request`. */
+interface ParentalConsentRequiredDetail {
+    parentalConsentToken: string;
+    profileId: string;
+    visitorId: string;
+    timestamp: number;
+}
+/** Dispatched by the standalone `resolveParentalConsent()` util (`apps/ui/src/utils/parental-consent.ts`)
+ * after `POST /consent/parental-consent-resolve` succeeds — typically from a fresh page/session
+ * with no live `ConsentiSetup` instance (the parent's own device, not the child's). A page that
+ * does have a live widget instance can listen for this to react (e.g. re-show the banner/modal for
+ * the real consent choice); what "resolved" should actually do to consent state is host-defined. */
+interface ParentalConsentGrantedDetail {
+    visitorId: string;
+    profileId: string;
+}
+/** Dispatched by `forgetMe()` right before the erasure call goes out — the hook for a host app
+ * to kick off its own identity-verified erasure workflow across other systems (CRM, DMP,
+ * analytics). The CMP itself only ever erases its own consent record; see the server-side
+ * `consent.erased` eventBus event (fired by `DELETE /consent/:visitorId`) for the same hook on
+ * the backend. See the "Right to erasure" guide for the full picture. */
+interface ForgetMeRequestedDetail {
+    visitorId: string;
+    profileId: string;
+    timestamp: number;
+}
+/** Dispatched by `forgetMe()` after the consent record has been erased and the banner/age-gate
+ * has been re-prompted (see `reConsent()`, which `forgetMe()` wraps). */
+interface ForgottenDetail {
+    visitorId: string;
+    profileId: string;
+    timestamp: number;
+}
+type ConsentEvent = BannerInitializedDetail | BannerVisibilityDetail | ModalVisibilityDetail | ConsentBeingSubmitted | ConsentSubmittedDetail | ParentalConsentRequiredDetail | ParentalConsentGrantedDetail | ForgetMeRequestedDetail | ForgottenDetail;
 
 /**
  * Main entry point for the Consenti widget.
@@ -281,16 +620,30 @@ interface ConsentEvent {
  */
 
 declare class ConsentiSetup implements ConsentiWidgetAPI {
-    private config;
     private initialized;
     private initializing;
     private profile;
     private resolvedBase;
+    /** cookieId → Category lookup, rebuilt whenever `profile` changes. Avoids rescanning categories on every consent action. */
+    private categoryIndex;
+    /** Watchers created by the declarative `data-consenti-*` DOM scan — destroyed alongside the widget since they have no other owner. */
+    private scannedScripts;
     private consentStore;
+    /**
+     * Stable per-browser identifier. Created lazily the first time a consent decision actually
+     * happens (manual submit, GPC auto-response, or relaying a decision already made in another
+     * tab) — never minted before that, so an undecided visitor leaves nothing in storage. See
+     * `getOrCreateVisitorId()`.
+     */
+    private visitorId;
     private eventBus;
     private banner;
     private modal;
+    private ageGate;
     private renderer;
+    /** Set once the age gate (if enabled) resolves; threaded onto every `submitConsent` call thereafter. */
+    private _ageVerified;
+    private _parentalConsentToken;
     private broadcastChannel;
     private readyResolve;
     private readyPromise;
@@ -299,26 +652,118 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
     private lastSignature;
     /** Tracks which banner variant is currently visible, or null when hidden. */
     private _bannerVariant;
+    /** Tracks which banner variant is currently mounted in the DOM (persists when banner is hidden). */
+    private _bannerMounted;
+    /** Active focus trap keydown listener — removed when modal closes. */
+    private _focusTrapListener;
+    /** Inbound `consenti:listener:identify` window listener — installed once per init(), removed on destroy(). */
+    private _identifyListener;
     /** Maps original handler functions to their DOM-wrapped listeners for on/off bookkeeping. */
     private _eventHandlers;
+    /** `core` defaulted to `{}` in the constructor below — every one of its own fields is
+     * optional, so this narrows back to non-optional for every other method in this class. */
+    private config;
     /**
      * Creates and initialises the consent widget.
      *
      * Construction is synchronous; the async `init()` is launched in the background.
      * Use `await widget.ready` or `widget.onReady(cb)` to run code after init completes.
      *
-     * @param config - Widget configuration. See `ConsentiConfig` for all options.
+     * @param config - Widget configuration. See `ConsentiConfig` for all options. `core` may be
+     *   omitted entirely — every one of its own fields is optional too.
      */
     constructor(config: ConsentiConfig);
     private profileId;
+    /** Patches `base` with `complianceGroupsOverride[base.complianceGroup]`, if both exist — the
+     * per-group counterpart to `profileOverride`. Lets an author supply different text/buttons/
+     * cookies per compliance group (built-in or custom) without authoring a separate profile for
+     * each one. Applied before `profileOverride`, which still always wins as the final catch-all. */
+    private applyComplianceGroupOverride;
+    /**
+     * Whether `window.__tcfapi`/`window.__gpp` should stay uninstalled because the corresponding
+     * server-side registration (`compliance.tcf`/`compliance.gpp`) is unconfirmed (cmpId/cmpVersion
+     * changed since the dashboard's confirmation checkbox was last checked, or never confirmed).
+     * Standalone (no-backend) deployments have no governance layer to check against, so this always
+     * resolves `false` there — the client-side config is used as configured, same as before this
+     * feature existed. A network failure fails closed (`true`) rather than assuming the
+     * unverifiable state is fine.
+     */
+    private isRegistrationBlocked;
     /**
      * Starts widget initialisation. Called automatically unless `autoInit: false` is set.
      * Can be called explicitly after construction when `autoInit: false`, or after `destroy()`
      * to re-initialise the same instance.
      */
     init(): Promise<void>;
+    /**
+     * Everything after the "does consent already exist" check — GPC/CCPA/CPRA silent paths,
+     * then the normal opt-in banner. Extracted from `init()` so the age gate (when enabled and
+     * no consent exists yet) can defer this whole sequence until the visitor answers it via
+     * `resolveAgeGate()`, then resume here with `hasExisting` fixed at `false`.
+     */
+    private continueInit;
+    /** Mounts the age-gate prompt (`profile.ageGate`) in place of the normal banner flow. */
+    private showAgeGate;
+    /**
+     * Handles the visitor's age-gate answer.
+     * - Confirmed → records `ageVerified: true` for all future `submitConsent` calls and
+     *   resumes the normal init flow via `continueInit()`.
+     * - Declined, no parental consent required → immediately submits a deny-all consent
+     *   (mandatory cookies still granted), mirroring the GPC-strict silent-write pattern.
+     * - Declined, parental consent required → same deny-all submission, plus a
+     *   `parentalConsentToken` and a `consenti:parentalConsentRequired` event so the site
+     *   owner can wire their own out-of-band verification flow (no email infra exists in
+     *   this package to do that here).
+     */
+    private resolveAgeGate;
+    /**
+     * Marks the widget ready and runs the declarative DOM-scan for
+     * `data-consenti-consent-script`/`data-consenti-category-script` tags. Called from
+     * every exit path of `init()` so the scan always runs exactly once per init cycle,
+     * whether `init()` was triggered automatically (`autoInit !== false`) or explicitly
+     * by the caller (`autoInit: false`) — it never runs before the widget actually has
+     * a resolved profile to read consent from.
+     */
+    private finishInit;
+    /** Installs the inbound `consenti:listener:identify` window listener — the event-driven
+     * counterpart to `setUserId()`. Removes any previously-installed listener first so repeated
+     * `init()` calls (e.g. from `switchLocale()`) don't stack up duplicate listeners. */
+    private _installIdentifyListener;
+    /** Returns the current logged-in application user ID, or `null` for an anonymous visitor. */
+    getUserId(): string | null;
+    /**
+     * Sets the logged-in application user ID (`null` for anonymous/logout). If a stored consent
+     * record exists and its user differs from `userId`, this is treated as a different data
+     * subject on a shared device: by default it reconsents (deletes the existing record and
+     * re-shows the banner) and logs a warning. Pass `reConsent: false` to just update the identity
+     * without prompting again (still logs the warning). No-ops entirely — no warning, no
+     * reconsent — when there is no prior consent record to compare against (true first-time visitor).
+     */
+    setUserId(userId: string | null, reConsent?: boolean): Promise<void>;
+    /**
+     * Snapshot of the current visitor's identity. `visitorId` is the stable per-browser ID —
+     * `null` until a consent decision has actually happened, since this never mints one just to
+     * answer the call (see `getOrCreateVisitorId()`). `type` is `'authenticated'` whenever a
+     * `userId` is set (via `setUserId()` or `core.userId`), `'anonymous'` otherwise.
+     */
+    getVisitor(): VisitorIdentity;
+    /** Sets the `dir` attribute on the root element from `core.dir` (default `'auto'`, derived from `core.locale`). */
+    private applyDirection;
     /** Applies the `consenti-root--dark` class based on config or profile flag. */
     private applyDarkMode;
+    /** Applies `consenti--enhanced-a11y` class when `profile.enhanceAccessibility` is set. */
+    private applyAccessibility;
+    /** Builds and appends the metadata footer strip to modal container. */
+    private _appendMetaFooter;
+    /**
+     * Injects a `<style>` element into the root for `stackButtonsOnBreakpoint`.
+     * Called once per profile load; a new style replaces the previous one.
+     */
+    private applyStackButtonsBreakpoint;
+    /** Installs a keyboard focus trap on `container` while the modal is open. */
+    private _installFocusTrap;
+    /** Removes the active focus trap keyboard listener. */
+    private _removeFocusTrap;
     /**
      * Injects CSS custom property overrides supplied via `core.theme` into the
      * Consenti root element so they cascade down to all widget elements.
@@ -348,22 +793,31 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      */
     hasConsent(): boolean;
     /**
-     * Returns the stored consent map, or `null` if no consent has been saved.
-     * Always returns `null` during SSR.
+     * Returns the stored consent map, optionally transformed for a specific vendor.
+     * Pass `type` to get a vendor-ready object instead of the raw Consenti format.
+     * Always returns `null` during SSR or when no consent has been saved.
+     *
+     * @param type - Output format:
+     *   - omit / `'default'`  → raw ConsentValue, keyed by every cookie parameter ID in the profile
+     *   - `'purpose'`         → consent per the fixed CookiePurpose taxonomy (necessary/functional/preferences/analytics/marketing)
+     *   - `'category'`        → consent per the tenant's own authored preference-modal category, keyed by category ID
+     *                           ('granted' only when every member parameter is granted; 'denied'/'objected' otherwise)
+     *   - `'google-gtm'`      → Google Consent Mode v2 keys + ads_data_redaction, url_passthrough
+     *   - `'adobe'`           → { analytics, target, manager, optimizer }
+     *   - `'meta'`            → { pixel, api, plugins, facebookLogin }
+     *   - `'microsoft-clarity'` → { session, heatmaps, performance }
+     *   - `'twilio-segment'`  → { identify, page, track, group, alias }
      */
     getConsent(): ConsentValue | null;
+    getConsent(type: ConsentType): Record<string, string> | null;
     /**
      * Returns the `Date` when consent was last saved, or `false` if no consent exists.
      * Always returns `false` during SSR.
      */
     getConsentDate(): Date | false;
     /**
-     * Returns the consent map in Google Consent Mode v2 format, ready to pass to
-     * `gtag('consent', 'update', ...)`. Returns `null` if no consent has been saved.
-     *
-     * Maps Consenti cookie IDs to the seven Google Consent Mode v2 parameters.
-     * Cookies whose IDs exactly match a GCM v2 key are forwarded directly.
-     * Non-GCM cookies are ignored by this method (they appear in `getConsent()` only).
+     * @deprecated Use `getConsent('google-gtm')` instead.
+     * Returns the consent map in Google Consent Mode v2 format.
      */
     getGTMConsent(): Record<string, string> | null;
     /**
@@ -375,7 +829,7 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * @param consent    - Partial or full map of cookie ID → status.
      * @param gpcDerived - Internal flag set to `true` when called from the GPC strict path.
      */
-    submitConsent(consent: Partial<ConsentValue>, gpcDerived?: boolean): Promise<void>;
+    submitConsent(consent: Partial<ConsentValue>, gpcDerived?: boolean, source?: number): Promise<ConsentDbRecord | void>;
     /**
      * Returns the currently visible banner variant, or `false` if no banner is shown.
      * Useful for programmatically checking state before calling `showBanner` / `hideBanner`.
@@ -444,8 +898,30 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * method so callers do not need to coordinate the async deletion with the banner display.
      *
      * Use this to power "Review my consent" links in footers or privacy dashboards.
+     *
+     * @param resetAgeGate - When `true` (default) and the profile has `ageGate.enabled`, the
+     *                        age-gate prompt is shown again instead of jumping straight to the
+     *                        banner — mirroring the original first-visit flow. Pass `false` to
+     *                        skip it and go straight to the banner, keeping the visitor's prior
+     *                        age-gate answer.
      */
-    reConsent(): Promise<void>;
+    reConsent(resetAgeGate?: boolean): Promise<void>;
+    /**
+     * Self-service erasure entry point — GDPR Art. 17 / CCPA-CPRA / LGPD Art. 18 and equivalent
+     * "right to be forgotten" rights, exercised from the widget itself. Wraps `reConsent()` (same
+     * erase-then-reprompt behavior) with `consenti:forgetMeRequested` / `consenti:forgotten`
+     * dispatched around it, so a host app can hook its own identity-verified erasure workflow
+     * across other systems (CRM, DMP, analytics) — the CMP itself only ever erases its own consent
+     * record. See the "Right to erasure" guide for the full picture, including the server-side
+     * `consent:erased` eventBus event fired by `DELETE /consent/:visitorId`.
+     *
+     * Powers the preference modal's "Forget me" button (`preferenceModal.showForgetMe`, only
+     * rendered when the visitor already has a stored consent decision). Also callable directly —
+     * e.g. `widget.forgetMe()` from a custom footer link or privacy-settings page.
+     *
+     * @param resetAgeGate - Forwarded to `reConsent()` — see its docs.
+     */
+    forgetMe(resetAgeGate?: boolean): Promise<void>;
     /**
      * Returns the fully resolved profile for the current session, or `null` during the
      * async init phase (before the profile has been fetched/resolved).
@@ -544,8 +1020,8 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      */
     version(): {
         package: string;
-        profileVersion: number | null;
-        consentVersion: number;
+        profileVersion: string;
+        consentVersion: string | null;
     };
     /**
      * Toggles or sets dark mode at runtime without re-initialising the widget.
@@ -623,15 +1099,22 @@ declare function useConsent(): {
     /** Denies all non-mandatory cookies. Pass `true` to deny mandatory ones too (use with care). */
     denyAll: (includingMandatory?: boolean) => Promise<void>;
     /** Saves the given partial consent map. */
-    submitConsent: (c: Partial<ConsentValue>) => Promise<void>;
-    /** Deletes the current consent record and re-shows the banner. */
-    reConsent: () => Promise<void>;
+    submitConsent: (c: Partial<ConsentValue>) => Promise<void | ConsentDbRecord>;
+    /** Deletes the current consent record and re-shows the banner. Pass `false` to skip
+     * re-showing the age-gate prompt (if the profile has one) and go straight to the banner. */
+    reConsent: (resetAgeGate?: boolean) => Promise<void>;
     /** Returns `true` if the given cookie ID is `'granted'`. */
     isCookieGranted: (id: string) => boolean;
     /** Returns `true` if every cookie in the given category is `'granted'`. */
     isCategoryGranted: (id: string) => boolean;
     /** Switches the active locale and re-renders the banner and modal. */
     switchLocale: (locale: string) => void | undefined;
+    /** Returns the current logged-in application user ID, or `null` if anonymous. */
+    getUserId: () => string | null;
+    /** Sets the logged-in application user ID; reconsents by default when it changes. */
+    setUserId: (userId: string | null, reConsent?: boolean) => Promise<void>;
+    /** Snapshot of the current visitor's identity (`visitorId`, `type`, `userId`). */
+    getVisitor: () => VisitorIdentity;
 };
 
 export { setConsentiWidget, useConsent };