@consenti/ui 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,9 +1,18 @@
 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;
 
 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 +28,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;
@@ -33,24 +49,67 @@ interface CountryComplianceEntry {
         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;
+    /** HMAC-SHA256 signature over the record's core fields, hex-encoded. Only present when
+     * `consentSigningKey` is configured — opt-in tamper-evidence for server-stored records,
+     * 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 (existing behaviour)
+ * 'google-gtm'        → Google Consent Mode v2 keys + ads_data_redaction, url_passthrough
+ * 'category'          → consent per CookiePurpose category
+ * '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' | '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 +118,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 +131,50 @@ 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;
 }
 interface LocaleTranslations {
-    mainBanner: MainBanner;
-    gpcBanner?: GpcBanner;
-    preferenceModal: PreferenceModal;
+    mainBanner: DeepPartial<MainBanner>;
+    gpcBanner?: DeepPartial<GpcBanner>;
+    preferenceModal: DeepPartial<PreferenceModal>;
 }
 interface ProfileTranslations {
     [locale: string]: LocaleTranslations;
@@ -110,64 +188,127 @@ 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;
     };
 }
 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;
     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;
     darkMode?: boolean;
-    gpcMode?: 'ignore' | 'honor' | 'strict';
-    complianceGroup?: string;
+    gpcMode?: GpcMode;
+    complianceGroup?: ComplianceGroupId;
     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;
@@ -179,12 +320,20 @@ interface AgeGateWidgetConfig {
     minimumAge: number;
     requireParentalConsent?: boolean;
 }
+/** 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. */
+interface TcfWidgetConfig {
+    enabled: boolean;
+    cmpId: number;
+    cmpVersion: number;
+}
 interface ComplianceWidgetConfig {
-    type?: 'auto' | ComplianceGroupId | string;
+    type?: ComplianceType;
     geoDataProvider?: 'default' | WidgetCountryResolverFn;
     autoComplianceMap?: 'default' | ComplianceMapData | 'auto';
     complianceMapUrl?: string;
     ageGate?: AgeGateWidgetConfig;
+    tcf?: TcfWidgetConfig;
 }
 interface GtmConfig {
     containerId?: string;
@@ -192,6 +341,7 @@ interface GtmConfig {
     dataLayer?: string;
     urlPassthrough?: boolean;
     adsDataRedaction?: boolean;
+    verbose?: boolean;
 }
 interface UtilsConfig {
     gtm?: GtmConfig;
@@ -201,7 +351,7 @@ interface ApiConfig {
     baseUrl?: string;
     authToken?: string;
     tenantId?: string;
-    complianceGroup?: string;
+    complianceGroup?: ComplianceGroupId;
     trustDomain?: boolean;
 }
 interface ThemeConfig {
@@ -225,8 +375,10 @@ interface ThemeConfig {
 }
 interface CoreConfig {
     tenantId?: string;
-    autoHonorGPC?: boolean | 'strict';
     locale?: string;
+    /** Text direction for the banner/modal root. `'auto'` (default) derives it from `locale`
+     * (Arabic, Hebrew, Persian, Urdu, ... → `rtl`); set explicitly to override. */
+    dir?: 'ltr' | 'rtl' | 'auto';
     disableCssTemplate?: boolean;
     cookieSigningKey?: string;
     allowReceipt?: boolean;
@@ -239,7 +391,11 @@ interface CoreConfig {
     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;
@@ -251,10 +407,12 @@ interface ConsentiConfig {
     /** 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';
 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 +425,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,7 +435,7 @@ 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>;
     getRootElement(): HTMLElement | null;
@@ -316,41 +474,67 @@ 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
+ * `AgeGateWidgetConfig`. 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. */
+interface ParentalConsentRequiredDetail {
+    parentalConsentToken: string;
+    profileId: string;
+    visitorId: string;
+    timestamp: number;
+}
+type ConsentEvent = BannerInitializedDetail | BannerVisibilityDetail | ModalVisibilityDetail | ConsentBeingSubmitted | ConsentSubmittedDetail | ParentalConsentRequiredDetail;
 type ConsentiMessage = {
     type: 'consentUpdated';
     consent: ConsentValue;
-    profileId: number;
+    profileId: string;
 } | {
     type: 'bannerClosed';
 } | {
@@ -375,16 +559,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,15 +591,23 @@ 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;
     /** 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;
@@ -411,8 +617,53 @@ declare class ConsentiSetup implements ConsentiWidgetAPI {
      * 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 (`compliance.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;
+    /** 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 a banner or 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 +693,23 @@ 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 - Vendor format: 'google-gtm', 'category', 'adobe', 'meta',
+     *               'microsoft-clarity', 'twilio-segment', or omit for raw format.
      */
     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 +721,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`.
@@ -638,8 +890,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 +1014,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 +1051,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 +1149,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 +1413,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 +1432,42 @@ 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>;
+
+export { type AgeGateWidgetConfig, 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 LocaleTranslations, type MainBanner, type ParentalConsentRequiredDetail, type ParsedConsent, type PreferenceModal, type ProfileConfig, type ProfileTranslations, type RegisterableProfileConfig, type ResolvedProfile, type TcfWidgetConfig, type ThemeConfig, type UtilsConfig, scanConsentScripts };