@consenti/ui 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,9 +1,44 @@
 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
@@ -19,6 +54,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;
@@ -26,31 +68,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 ConsentAction$1 = '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 {
@@ -59,8 +151,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;
@@ -69,34 +164,63 @@ 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 LocaleTranslations {
-    mainBanner: MainBanner;
-    gpcBanner?: GpcBanner;
-    preferenceModal: PreferenceModal;
+    mainBanner: DeepPartial<MainBanner>;
+    gpcBanner?: DeepPartial<GpcBanner>;
+    preferenceModal: DeepPartial<PreferenceModal>;
+    /** Only meaningful when the profile's `ageGate.enabled` is true. */
+    ageGateModal?: DeepPartial<AgeGateModalContent>;
 }
 interface ProfileTranslations {
     [locale: string]: LocaleTranslations;
@@ -106,85 +230,241 @@ interface DpdpaConfig {
     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 LocaleTextContent {
     mainBanner: {
         heading?: string;
         htmlText: string;
-        buttonLabels?: string[];
+        /** Keyed by the linked UI template's button id — was a positional array matched to
+         * `buttons[i]` by index; now matched by key, robust against button reordering. */
+        buttonLabels?: Record<string, string>;
     };
     gpcBanner: {
         heading?: string;
         htmlText: string;
-        buttonLabels?: string[];
+        buttonLabels?: Record<string, string>;
     };
     preferenceModal: {
         heading: string;
         subheading?: string;
         htmlText?: string;
-        buttonLabels?: string[];
-        categories: {
-            id: string;
+        buttonLabels?: Record<string, string>;
+        /** `legitimateInterestDescription` is only meaningful for categories whose legalBasis is 'legitimate_interest'; optional GDPR balancing-test text, translated per locale like heading/htmlText. */
+        categories: Record<string, {
             heading: string;
             htmlText: string;
-        }[];
+            legitimateInterestDescription?: string;
+        }>;
+        receiptLabel?: string;
+        receiptDescription?: string;
+        /** Per-locale override of `PreferenceModal.forgetMeLabel`; only meaningful when `showForgetMe` is true. */
+        forgetMeLabel?: string;
     };
+    /** Only meaningful when the profile's `ageGate.enabled` is true. */
+    ageGateModal?: AgeGateModalContent;
 }
 interface ProfileConfig {
-    cookies?: Cookie[];
+    id: string;
+    cookies?: CookieMap;
     defaultLocale: string;
+    /** Days until consent expires and the visitor is asked again (profile-wide). Default: 365. */
+    expiryDays?: number;
     translations?: ProfileTranslations;
-    gpcBanner?: boolean;
+    mainBanner: MainBanner;
+    gpcBanner?: GpcBanner;
+    preferenceModal: PreferenceModal;
     darkMode?: boolean;
     allowedOrigins?: string[];
     dpdpa?: DpdpaConfig;
+    ageGate?: AgeGateConfig;
+    /** Default locale's age-gate modal text — mirrors `mainBanner`/`preferenceModal` (inline,
+     * required-shape-when-present), not `dpdpa` (which has no locale text at all). Every other
+     * locale's `ageGateModal` lives in `localeContents`/`LocaleContentInput` like the rest of
+     * that locale's content. */
+    ageGateModal?: AgeGateModalContent;
     regulation?: 'gdpr' | 'ccpa' | 'cpra' | 'dpdpa' | 'uk-gdpr' | 'lgpd' | 'pipeda' | 'popia' | 'pdpa-th' | 'appi' | 'kvkk';
     regulations?: string[];
-    cookieTemplateId?: string;
+    consentTemplateId?: string;
     uiTemplateId?: string;
     localeContents?: Record<string, LocaleTextContent>;
-    complianceGroup?: string;
-    /** @deprecated use gpcMode */
-    gpcCompliance?: 'strict' | 'honor' | 'ignore';
-    gpcMode?: 'ignore' | 'honor' | 'strict';
+    complianceGroup?: ComplianceGroupId;
+    /**
+     * Free-form identifier (lower-kebab-case) for profiles that don't map to one of the
+     * built-in `complianceGroup` values — the identifier the widget's `compliance.type`
+     * config targets to fetch this profile. Participates in activation, deactivation, and
+     * "one active profile per group" conflict detection the same way `complianceGroup` does;
+     * no `COMPLIANCE_GROUPS` validation rules or GPC defaults apply to it, since none exist
+     * for a free-form name.
+     */
+    customComplianceGroup?: string;
+    /**
+     * Per-profile deltas applied on top of the consent template's authored `Cookie` values
+     * (e.g. an overridden `preGrant`) when resolving this profile — see the dashboard's Step 2
+     * pre-grant override UX. Keyed by cookie id; only the overridden fields need to be present.
+     */
+    cookiesOverride?: Record<string, Partial<Cookie>>;
+    /**
+     * Reserved for a future phase — stored but not yet applied when resolving a profile.
+     * Intended to mirror `cookiesOverride` for per-category deltas.
+     */
+    categoriesOverride?: Record<string, Partial<Category>>;
+    /**
+     * Reserved for a future phase — stored but not yet applied when resolving a profile.
+     * Intended to hold per-profile UI-template deltas.
+     */
+    uiOverride?: Record<string, unknown>;
+    /**
+     * When registered via `registerProfile()` and `complianceGroup` matches one of
+     * Consenti's built-in groups: `false` (default) fully replaces the built-in
+     * embedded profile for that group; `true` deep-merges this config onto the
+     * built-in profile instead (only meaningful together with `complianceGroup`).
+     */
+    deepMerge?: boolean;
+    gpcMode?: GpcMode;
     isActive?: boolean;
     hidePoweredBy?: boolean;
     allowReceipt?: boolean;
     /** Per-compliance extra config (e.g. DPDPA data fiduciary name). */
     complianceConfig?: Record<string, string>;
+    /** Show a metadata footer strip in the banner/modal with Consent ID, Date, Version, Privacy Settings link. */
+    showFooterMetadata?: boolean;
+    /** Apply WCAG 2.1 AA button sizing (44px min-height), visible focus rings, and screen-reader labels. */
+    enhanceAccessibility?: boolean;
 }
+/**
+ * Input accepted by `registerProfile()`. Either a complete `ProfileConfig`
+ * (used as-is or, if `complianceGroup` matches a built-in group, fully replaces
+ * it), or a partial overlay explicitly opted into `deepMerge: true` — merged
+ * onto the built-in embedded profile for `complianceGroup` at resolution time.
+ */
+type RegisterableProfileConfig = ProfileConfig | (DeepPartial<ProfileConfig> & {
+    complianceGroup: ComplianceGroupId;
+    deepMerge: true;
+});
 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;
@@ -192,6 +472,7 @@ interface GtmConfig {
     dataLayer?: string;
     urlPassthrough?: boolean;
     adsDataRedaction?: boolean;
+    verbose?: boolean;
 }
 interface UtilsConfig {
     gtm?: GtmConfig;
@@ -201,45 +482,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;
@@ -248,13 +565,30 @@ interface ConsentiConfig {
     utils?: UtilsConfig;
     plugins?: ConsentiPlugin$1[];
     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;
@@ -267,8 +601,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;
@@ -277,13 +611,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;
@@ -316,41 +665,102 @@ interface ParsedConsent {
 interface ConsentRecord {
     visitorId: string;
     consentId?: string;
-    profileId: number;
-    profileVersion: number;
+    profileId: string;
     consent: ConsentValue;
     timestamp: string;
     gpc?: boolean;
-    action?: ConsentAction;
+    action?: ConsentAction$1;
     pageUrl?: string;
 }
 interface ConsentReceipt {
-    version: '1.0';
+    version: string;
     issuedAt: string;
     visitorId: string;
-    profileId: number;
-    profileVersion: number;
+    profileId: string;
     locale: string;
     consent: ConsentValue;
     signature?: string;
 }
-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$1;
+    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;
+}
+/** Detail payload for the inbound `consenti:listener:identify` event — dispatched by the *host*
+ * page (not the widget) to tell the widget which application user is logged in, equivalent to
+ * calling `setUserId(userId, reConsent)`. `reConsent` defaults to `true`. */
+interface IdentifyEventDetail {
+    userId: string | null;
+    reConsent?: boolean;
+}
+/** 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;
 type ConsentiMessage = {
     type: 'consentUpdated';
     consent: ConsentValue;
-    profileId: number;
+    profileId: string;
 } | {
     type: 'bannerClosed';
 } | {
@@ -375,16 +785,30 @@ type ConsentiMessage = {
  */
 
 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;
@@ -393,26 +817,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.
@@ -442,22 +958,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;
     /**
@@ -469,7 +994,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`.
@@ -538,8 +1063,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).
@@ -638,8 +1185,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.
@@ -762,28 +1309,36 @@ declare abstract class ConsentiPlugin {
  * import { ConsentiProfile, ConsentiSetup } from '@consenti/ui'
  *
  * const profile = new ConsentiProfile({
- *   cookies: [
- *     { id: 'necessary', mandatory: true },
- *     { id: 'analytics' },
- *   ],
+ *   cookies: {
+ *     necessary: {},
+ *     analytics: {},
+ *   },
  *   defaultLocale: 'en',
  *   translations: {
  *     en: {
  *       mainBanner: {
  *         position: 'bottom',
  *         htmlText: 'We use cookies.',
- *         buttons: [{ text: 'Accept All', type: 'primary', cookies: '*' }],
+ *         buttons: { 'accept-all': { text: 'Accept All', style: 'primary', action: 'submit', cookies: '*' } },
  *       },
  *       preferenceModal: {
- *         categories: [],
- *         buttons: [{ text: 'Save', type: 'submit' }],
+ *         categories: {
+ *           necessary: { heading: 'Necessary', htmlText: '...', legalBasis: 'mandatory', cookies: ['necessary'] },
+ *         },
+ *         buttons: { save: { text: 'Save', style: 'primary', action: 'submit' } },
  *       },
  *     },
  *   },
  * })
  *
- * const widget = new ConsentiSetup({ core: { profileId: profile.getId() } })
+ * const widget = new ConsentiSetup({ core: { profileId: profile.getType() } })
  * ```
+ *
+ * To instead patch one of Consenti's built-in profiles for a given `complianceGroup`
+ * (rather than defining a full standalone profile), pass `complianceGroup` and
+ * `deepMerge: true` with only the fields you want to override — see
+ * `RegisterableProfileConfig` and the `complianceGroup`/`deepMerge` resolver behavior
+ * in `profile-resolver.ts`.
  */
 
 /**
@@ -791,15 +1346,17 @@ declare abstract class ConsentiPlugin {
  */
 declare class ConsentiProfile {
     private config;
-    private id;
+    private type;
     /**
-     * @param config - Full profile configuration including cookies, locales, and UI text.
+     * @param config - Full profile configuration including cookies, locales, and UI text,
+     *                 or a `{ complianceGroup, deepMerge: true, ... }` partial overlay to
+     *                 patch a built-in profile instead of defining a standalone one.
      */
-    constructor(config: ProfileConfig);
+    constructor(config: RegisterableProfileConfig);
     /** Returns the auto-assigned numeric profile ID. Pass this to `core.profileId`. */
-    getId(): number;
-    /** Returns the raw `ProfileConfig` passed to the constructor. */
-    toJSON(): ProfileConfig;
+    getType(): Symbol;
+    /** Returns the raw config passed to the constructor. */
+    toJSON(): RegisterableProfileConfig;
 }
 
 /**
@@ -887,37 +1444,248 @@ declare class ConsentScript {
 }
 
 /**
- * CookieTrigger — a pre-built accessible UI element that reopens the Consenti
- * preference panel when clicked.
+ * ConsentAction — runs a callback based on a specific consent parameter's grant status.
+ *
+ * Same lifecycle as `ConsentScript` (evaluates immediately on construction so
+ * existing consent is honoured, re-evaluates on `consenti:consentSubmitted`,
+ * `destroy()` to unbind) but fires `onGrant`/`onDeny` callbacks instead of
+ * injecting a `<script>` element — for integrations that expose their own
+ * `sdk.optIn()`/`sdk.optOut()` API (Segment, Mixpanel, Amplitude, Sentry, etc.)
+ * rather than needing a script tag toggled. Use `ConsentScript` for that case instead.
+ *
+ * @example
+ * ```ts
+ * import { ConsentiSetup, ConsentAction } from '@consenti/ui'
+ *
+ * const widget = new ConsentiSetup({ core: { profileId: 0 } })
+ * await widget.ready
+ *
+ * new ConsentAction({
+ *   id: 'analytics_storage',
+ *   widget,
+ *   onGrant: () => analyticsSdk.optIn(),
+ *   onDeny: () => analyticsSdk.optOut(),
+ * })
+ * ```
+ */
+
+/** Passed to `onGrant`/`onDeny` — the resolved parameter's metadata plus the full current consent map. */
+interface ConsentActionParams {
+    cookieId: string;
+    status: ConsentStatus;
+    cookie: Cookie | undefined;
+    consent: ConsentValue | null;
+}
+/** Options for constructing a {@link ConsentAction} instance. */
+interface ConsentActionOptions {
+    /** The consent parameter ID to watch (e.g. `'analytics_storage'`). */
+    id: string;
+    /** The `ConsentiSetup` widget instance to read consent from. */
+    widget: ConsentiSetup;
+    /**
+     * When `true` (default), the callbacks re-fire automatically on every future consent
+     * change. Set to `false` to evaluate consent only once at construction time — no
+     * event listener is attached.
+     */
+    bind?: boolean;
+    /** Called when the parameter's status transitions to `'granted'`. */
+    onGrant?: (params: ConsentActionParams) => void;
+    /** Called when the parameter's status transitions away from `'granted'` (`'denied'` or `'objected'`). */
+    onDeny?: (params: ConsentActionParams) => void;
+}
+/**
+ * Watches a single consent parameter's grant status and fires `onGrant`/`onDeny`
+ * callbacks on transitions. Call {@link ConsentAction.destroy} when no longer
+ * needed to remove the event listener.
+ */
+declare class ConsentAction {
+    private readonly options;
+    private granted;
+    private readonly handler;
+    constructor(options: ConsentActionOptions);
+    private evaluate;
+    /** Removes the event listener (if bound). */
+    destroy(): void;
+}
+
+/**
+ * CategoryAction — runs a callback based on a category's rollup consent state.
+ *
+ * A category is considered "granted" only when *every* parameter it contains is
+ * `'granted'` — matching the preference modal's tri-state rollup rule. `onDeny`
+ * fires for both a fully-denied category and a partially-granted ("mixed") one,
+ * since neither represents full consent for the category.
+ *
+ * Same lifecycle as `ConsentAction`: evaluates immediately on construction,
+ * re-evaluates on `consenti:consentSubmitted`, `destroy()` to unbind.
+ *
+ * @example
+ * ```ts
+ * import { ConsentiSetup, CategoryAction } from '@consenti/ui'
+ *
+ * const widget = new ConsentiSetup({ core: { profileId: 0 } })
+ * await widget.ready
+ *
+ * new CategoryAction({
+ *   id: 'marketing',
+ *   widget,
+ *   onGrant: () => adSdk.enableAll(),
+ *   onDeny: () => adSdk.disableAll(),
+ * })
+ * ```
+ */
+
+/** Passed to `onGrant`/`onDeny` — the category's member parameter IDs plus the full current consent map. */
+interface CategoryActionParams {
+    categoryId: string;
+    cookieIds: string[];
+    consent: ConsentValue | null;
+}
+/** Options for constructing a {@link CategoryAction} instance. */
+interface CategoryActionOptions {
+    /** The category ID to watch (e.g. `'marketing'`). */
+    id: string;
+    /** The `ConsentiSetup` widget instance to read consent from. */
+    widget: ConsentiSetup;
+    /**
+     * When `true` (default), the callbacks re-fire automatically on every future consent
+     * change. Set to `false` to evaluate consent only once at construction time — no
+     * event listener is attached.
+     */
+    bind?: boolean;
+    /** Called when every parameter in the category transitions to `'granted'`. */
+    onGrant?: (params: CategoryActionParams) => void;
+    /** Called when the category transitions away from fully-granted (any parameter denied/objected). */
+    onDeny?: (params: CategoryActionParams) => void;
+}
+/**
+ * Watches a category's rollup grant status and fires `onGrant`/`onDeny` callbacks
+ * on transitions. Call {@link CategoryAction.destroy} when no longer needed to
+ * remove the event listener.
+ */
+declare class CategoryAction {
+    private readonly options;
+    private granted;
+    private readonly handler;
+    constructor(options: CategoryActionOptions);
+    private evaluate;
+    /** Removes the event listener (if bound). */
+    destroy(): void;
+}
+
+/**
+ * CategoryScript — conditionally loads/unloads a third-party `<script>` tag
+ * based on a whole category's rollup consent state, instead of one parameter.
+ *
+ * A category is considered "granted" only when *every* parameter it contains is
+ * `'granted'` — matching the preference modal's tri-state rollup rule and
+ * `CategoryAction`'s behavior. Injection mechanics (src validation, inline-script
+ * escape hatch, attribute filtering) are identical to `ConsentScript` — both share
+ * the same underlying `injectScript`/`revokeScript` helpers.
+ *
+ * @example
+ * ```ts
+ * import { ConsentiSetup, CategoryScript } from '@consenti/ui'
+ *
+ * const widget = new ConsentiSetup({ core: { profileId: 0 } })
+ * await widget.ready
+ *
+ * new CategoryScript({
+ *   categoryId: 'marketing',
+ *   widget,
+ *   src: 'https://example.com/ad-pixel.js',
+ * })
+ * ```
+ */
+
+/** Options for constructing a {@link CategoryScript} instance. */
+interface CategoryScriptOptions {
+    /** The category ID to watch (e.g. `'marketing'`). */
+    categoryId: string;
+    /** The `ConsentiSetup` widget instance to read consent from. */
+    widget: ConsentiSetup;
+    /** Remote script `src` URL to inject when every parameter in the category is granted. */
+    src?: string;
+    /**
+     * Inline JavaScript to inject when granted (e.g. a GTM snippet).
+     * WARNING: this string is assigned directly to `script.innerHTML` — only
+     * pass a static, trusted literal. Never pass user-supplied or remote content.
+     */
+    unsafeInnerHTML?: string;
+    /**
+     * Additional HTML attributes applied to the injected `<script>` element.
+     * Set a key to an empty string for boolean attributes (e.g. `{ async: '', defer: '' }`).
+     */
+    attributes?: Record<string, string>;
+    /** Called after the `<script>` element has been appended to `<head>`. */
+    onLoad?: () => void;
+    /** Called after the `<script>` element has been removed from the DOM. */
+    onRevoke?: () => void;
+    /**
+     * When `true` (default), the script is automatically removed when the category is no
+     * longer fully granted and re-injected when it becomes fully granted again. Set to
+     * `false` to evaluate consent only once at construction time — no event listener is
+     * attached and the script is never auto-removed.
+     */
+    bind?: boolean;
+}
+/**
+ * Conditionally injects and removes a `<script>` element based on a category's
+ * rollup consent status (every member parameter granted).
+ *
+ * Call {@link CategoryScript.destroy} when the trigger is no longer needed
+ * (e.g. on SPA route unmount) to remove the event listener and the injected element.
+ */
+declare class CategoryScript {
+    private readonly options;
+    private scriptEl;
+    private readonly handler;
+    constructor(options: CategoryScriptOptions);
+    private evaluate;
+    private inject;
+    private revoke;
+    /**
+     * Removes the event listener and the injected `<script>` element (if present).
+     * Call this when the widget is destroyed or the script is no longer needed.
+     */
+    destroy(): void;
+}
+
+/**
+ * BannerTrigger — a pre-built accessible UI element that reopens the Consenti
+ * banner or preference modal when clicked.
  *
  * Use this to add a "Cookie Settings" link in your site footer or cookie policy
  * page without wiring up the click handler manually or importing the widget module
  * into your layout component.
  *
+ * (Renamed from `CookieTrigger` — it was never scoped to a specific cookie, it
+ * just opens the banner or modal.)
+ *
  * @example
  * ```ts
- * import { ConsentiSetup, CookieTrigger } from '@consenti/ui'
+ * import { ConsentiSetup, BannerTrigger } from '@consenti/ui'
  *
  * const widget = new ConsentiSetup({ core: { profileId: 0 } })
  *
  * // Attach to an existing element
- * new CookieTrigger({ widget, el: '#footer-cookie-settings' })
+ * new BannerTrigger({ widget, el: '#footer-cookie-settings' })
  *
  * // — or — create a new button and place it yourself
- * const trigger = new CookieTrigger({ widget, label: 'Cookie Settings' })
+ * const trigger = new BannerTrigger({ widget, label: 'Cookie Settings' })
  * document.querySelector('.site-footer')?.appendChild(trigger.getElement())
  * ```
  */
 
-/** Options for constructing a {@link CookieTrigger} instance. */
-interface CookieTriggerOptions {
+/** Options for constructing a {@link BannerTrigger} instance. */
+interface BannerTriggerOptions {
     /** The widget instance to control when the trigger is clicked. */
     widget: ConsentiSetup;
     /**
      * Element to attach the click handler to.
      * - `HTMLElement` — used directly.
      * - `string` — treated as a CSS selector; the first matching element is used.
-     * - Omitted — a new `<button>` is created. Retrieve it with {@link CookieTrigger.getElement}
+     * - Omitted — a new `<button>` is created. Retrieve it with {@link BannerTrigger.getElement}
      *   and append it to the DOM at the desired location.
      */
     el?: HTMLElement | string;
@@ -940,12 +1708,12 @@ interface CookieTriggerOptions {
  * The created button uses the `.consenti-btn` and `.consenti-btn--text` classes so
  * it inherits the widget's theme automatically.
  */
-declare class CookieTrigger {
+declare class BannerTrigger {
     private readonly el;
     private readonly clickHandler;
     /** Whether this instance created the element (used to decide if `destroy()` removes it). */
     private readonly created;
-    constructor(options: CookieTriggerOptions);
+    constructor(options: BannerTriggerOptions);
     /**
      * Returns the trigger element.
      * When no `el` was provided, append the returned element to the desired location
@@ -959,4 +1727,82 @@ declare class CookieTrigger {
     destroy(): void;
 }
 
-export { type ApiConfig, type Button, type ButtonAction, type ButtonStyle, type Category, type ConsentAction, type ConsentEvent, type ConsentReceipt, type ConsentRecord, ConsentScript, type ConsentScriptOptions, type ConsentStatus, type ConsentValue, type ConsentiConfig, type ConsentiEventName, type ConsentiMessage, ConsentiPlugin, ConsentiProfile, ConsentiSetup, type ConsentiWidgetAPI, type Cookie, type CookieOptions, CookieTrigger, type CookieTriggerOptions, type CoreConfig, type GpcBanner, type GtmConfig, type LocaleTranslations, type MainBanner, type ParsedConsent, type PreferenceModal, type ProfileConfig, type ProfileTranslations, type ResolvedProfile, type ThemeConfig, type UtilsConfig };
+/**
+ * Declarative DOM-scan bindings — a zero-JS integration path for gating
+ * third-party scripts via `data-*` attributes instead of hand-written
+ * `ConsentScript`/`CategoryScript` calls.
+ *
+ * ```html
+ * <script type="text/plain" data-consenti-category-script="marketing" src="https://example.com/pixel.js"></script>
+ * <script type="text/plain" data-consenti-consent-script="analytics_storage">/* inline snippet *\/</script>
+ * <script type="text/plain" data-consenti-consent-script="ad_storage" data-consenti-bind="false" src="..."></script>
+ * ```
+ *
+ * Scanned automatically once per `ConsentiSetup.init()` cycle (after `init()`
+ * completes — so it respects `autoInit: false`, only running once the widget is
+ * actually initialized, however `init()` was triggered). The scanned tags are
+ * read-only config sources and stay inert (`type="text/plain"`) in the DOM
+ * permanently — `ConsentScript`/`CategoryScript` inject their own separate
+ * `<script>` element exactly as they do when constructed by hand.
+ */
+
+/**
+ * Scans the document for `<script type="text/plain">` tags carrying
+ * `data-consenti-consent-script` or `data-consenti-category-script`, and
+ * instantiates `ConsentScript`/`CategoryScript` for each. Called automatically
+ * by `ConsentiSetup` at the end of every `init()` cycle.
+ *
+ * v1 scans once automatically; scripts injected into the DOM after that point
+ * (e.g. by a late-loading CMS widget) are not picked up automatically — call this
+ * function again manually after adding more tags dynamically if needed. Each element
+ * is only ever scanned once (marked with `data-consenti-scanned`), so calling this
+ * again is safe — it only processes newly-added tags, never re-instantiates a watcher
+ * for one already scanned.
+ *
+ * Returns the created watchers — `ConsentiSetup` holds onto these and calls
+ * `.destroy()` on each when the widget itself is destroyed, since a scanner-created
+ * watcher has no other owner to release its `consenti:consentSubmitted` listener.
+ */
+declare function scanConsentScripts(widget: ConsentiSetup): Array<ConsentScript | CategoryScript>;
+
+/**
+ * Standalone resolver for the parental-consent hook (see `AgeGate`/`ConsentiSetup.resolveAgeGate`).
+ * Not a `ConsentiSetup` instance method — the parent typically opens the token link (emailed by
+ * the host's own eventBus listener, see `consenti:parentalConsentRequired`) on a fresh page or
+ * even a different device, with no live widget instance around at all.
+ */
+
+interface ParentalConsentApiConfig {
+    baseUrl?: string;
+    authToken?: string;
+}
+/**
+ * POSTs a parental-consent token to `POST /consent/parental-consent-resolve`. On success,
+ * dispatches `consenti:parentalConsentResolved` on `window` (same mechanism `EventBus.dispatch`
+ * uses) so any page with a live widget instance can react — what "resolved" should actually do to
+ * consent state is left to that listener, matching the "we provide the hook, not the behavior"
+ * scope of this whole feature. Throws on an invalid/expired token or network failure.
+ */
+declare function resolveParentalConsent(token: string, apiConfig?: ParentalConsentApiConfig): Promise<ParentalConsentGrantedDetail>;
+
+/**
+ * Builds a synchronous, dependency-free `<head>` snippet that freezes Google Consent Mode
+ * to denied-by-default the instant a visitor's browser sends the Global Privacy Control (GPC)
+ * signal — before any tag-loading script runs, including GTM/gtag.js itself and Consenti's own
+ * bundle (which only applies GPC once it has loaded, parsed, and initialized asynchronously).
+ *
+ * This is a documentation helper, not something the widget loads itself: paste the returned
+ * string as the very first `<script>` in `<head>`, ahead of GTM/gtag.js and the Consenti bundle.
+ * It only touches `window[dataLayerName]`/`window.gtag` (the same stub-queue pattern
+ * `EventBus.initConsentMode()` uses), so it's safe to run before those exist and harmless to
+ * run again after they do — Consenti's own `gtag('consent', 'default', …)` call on init just
+ * pushes another entry onto the same queue.
+ *
+ * The default values pushed here mirror `getGoogleGTMConsent({})` in `consent-mapper.ts` (safe
+ * defaults for an empty consent map) — keep the two in sync if either changes.
+ */
+declare function buildSyncGpcSnippet(options?: {
+    dataLayerName?: string;
+}): string;
+
+export { type ApiConfig, BannerTrigger, type BannerTriggerOptions, type Button, type ButtonAction, type ButtonStyle, type Category, CategoryAction, type CategoryActionOptions, type CategoryActionParams, type CategoryMap, CategoryScript, type CategoryScriptOptions, type ComplianceWidgetConfig, ConsentAction, type ConsentActionOptions, type ConsentActionParams, type ConsentAction$1 as ConsentActionType, type ConsentEvent, type ConsentReceipt, type ConsentRecord, ConsentScript, type ConsentScriptOptions, type ConsentStatus, type ConsentValue, type ConsentiConfig, type ConsentiEventName, type ConsentiMessage, ConsentiPlugin, ConsentiProfile, ConsentiSetup, type ConsentiWidgetAPI, type Cookie, type CookieMap, type CookieOptions, type CoreConfig, type GpcBanner, type GtmConfig, type IdentifyEventDetail, type LocaleTranslations, type MainBanner, type ParentalConsentApiConfig, type ParentalConsentGrantedDetail, type ParentalConsentRequiredDetail, type ParsedConsent, type PreferenceModal, type ProfileConfig, type ProfileTranslations, type RegisterableProfileConfig, type ResolvedProfile, type TcfWidgetConfig, type ThemeConfig, type UtilsConfig, type VisitorIdentity, buildSyncGpcSnippet, resolveParentalConsent, scanConsentScripts };