@v-tilt/browser 1.11.0 → 1.12.0

package/dist/request.d.ts

@@ -6,26 +6,38 @@
  * - Multiple transport methods (fetch, XHR, sendBeacon)
  * - Automatic fallback between transports
  *
- * Based on PostHog's request.ts pattern
+ * Compression transport split (important — see `utils/base64.ts`):
+ *
+ *   - fetch / XHR    → binary `Blob` of gzip bytes, body uses `compression=gzip-js`
+ *   - sendBeacon     → base64 *text* of the same gzip bytes, body uses
+ *                      `compression=base64`
+ *
+ *   `sendBeacon` with a binary `Blob` is unreliable on `pagehide` / tab
+ *   discard: the browser queues the beacon synchronously but serializes the
+ *   body *after* JS is torn down, and the underlying `ArrayBuffer` can be
+ *   detached/GC'd by then. The wire body lands empty or truncated while the
+ *   URL we already committed still carries `compression=gzip-js`, and the
+ *   server's `gunzipSync` throws `Z_BUF_ERROR`. Switching the beacon to a
+ *   base64 string body means `Blob([string])` owns its own UTF-8 copy, which
+ *   survives unload reliably.
+ *
+ * Based on PostHog's request.ts pattern.
  */
 /**
- * Compression methods supported by the SDK
+ * Compression methods supported by the SDK. The user-facing config only
+ * accepts `GZipJS` / `None`; the request layer internally picks `Base64`
+ * for the sendBeacon transport (see file header).
  */
 export declare enum Compression {
     GZipJS = "gzip-js",
+    Base64 = "base64",
     None = "none"
 }
-/**
- * Response from a request
- */
 export interface RequestResponse {
     statusCode: number;
     text?: string;
     json?: any;
 }
-/**
- * Options for making a request
- */
 export interface RequestOptions {
     url: string;
     data?: any;
@@ -35,20 +47,22 @@ export interface RequestOptions {
     compression?: Compression;
     timeout?: number;
     callback?: (response: RequestResponse) => void;
+    /**
+     * Project API token. When set, the helper authenticates the request:
+     *
+     *   - `fetch` / `XHR` transports → sent as an `x-api-key` header so the
+     *     URL stays clean and is less likely to match ad/privacy blocker
+     *     filter rules that look for `?token=` on known analytics origins.
+     *   - `sendBeacon` transport → appended as `?token=<token>` because
+     *     beacon requests cannot carry custom headers.
+     *
+     * The server accepts both (`x-api-key` is checked before the query
+     * parameter), so older SDK versions that still embed the token in the
+     * URL continue to work unchanged.
+     */
+    projectToken?: string;
 }
-/**
- * JSON stringify with BigInt support
- */
 export declare const jsonStringify: (data: any) => string;
-/**
- * Main request function - handles transport selection and dispatching
- */
 export declare const request: (options: RequestOptions) => void;
-/**
- * Promise-based request wrapper
- */
 export declare const requestAsync: (options: Omit<RequestOptions, "callback">) => Promise<RequestResponse>;
-/**
- * Check if compression is supported and beneficial
- */
 export declare const shouldCompress: (data: any) => boolean;

package/dist/scroll-depth-tracker.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Scroll depth tracking for autocapture milestone and pageleave modes.
+ */
+import type { AutocaptureConfig, ScrollDepthConfig } from "./autocapture-types";
+export declare const DEFAULT_SCROLL_DEPTH_THRESHOLDS: readonly [25, 50, 75, 100];
+export type ScrollRoot = Window | Element;
+export interface NormalizedScrollDepth {
+    milestones: boolean;
+    thresholds: number[];
+    pageleave: boolean;
+    scroll_root_selector?: string | string[];
+}
+export declare function normalizeScrollDepth(raw: ScrollDepthConfig | undefined): NormalizedScrollDepth | null;
+export declare function scrollDepthModeActive(config: AutocaptureConfig | undefined): boolean;
+export declare function computeScrollDepthPct(root: ScrollRoot | null): number;
+export declare function resolveScrollRoot(selectors: string | string[] | undefined): ScrollRoot | null;
+export type ScrollDepthCaptureFn = (name: string, props: Record<string, unknown>) => void;
+export interface ScrollDepthTrackerOptions {
+    milestones: boolean;
+    pageleave: boolean;
+    thresholds: number[];
+    scroll_root_selector?: string | string[];
+    capture: ScrollDepthCaptureFn;
+    isUrlAllowed: () => boolean;
+    onPageview: (cb: () => void) => () => void;
+}
+export declare class ScrollDepthTracker {
+    private readonly _options;
+    private _maxPctSeen;
+    private readonly _firedThresholds;
+    private _scrollHandler;
+    private _scrollTarget;
+    private _rafId;
+    private _pageviewUnsub;
+    constructor(_options: ScrollDepthTrackerOptions);
+    start(): void;
+    stop(): void;
+    reset(): void;
+    getMaxPct(): number;
+    private _scheduleScrollUpdate;
+    private _onScroll;
+}

package/dist/server.d.ts

@@ -8,6 +8,102 @@
 interface FeatureFlagsConfig {
     [flagKey: string]: boolean | string;
 }
+type GoogleConsentValue = "follow_advertising" | "follow_analytics" | "granted" | "denied";
+interface GoogleConsentOverride {
+    ad_storage?: GoogleConsentValue;
+    ad_user_data?: GoogleConsentValue;
+    ad_personalization?: GoogleConsentValue;
+    analytics_storage?: GoogleConsentValue;
+}
+interface GoogleAdsConversionMapping {
+    event_name: string;
+    send_to: string;
+    value_param_path?: string;
+    currency_param_path?: string;
+    default_currency?: string;
+    send_transaction_id?: boolean;
+    transaction_id_param_path?: string;
+}
+/**
+ * How gtag.js is loaded — mirrors the server-side `proxy_mode` destination
+ * setting:
+ *
+ * - `proxied` (default) — route through `api_host/gt/*`. `api_host` is the
+ *   SDK-level proxy setting; self-hosted customers point it at their own
+ *   domain (which must implement the `/gt/*` spec).
+ * - `direct` — no proxy; gtag.js loads straight from
+ *   `https://www.googletagmanager.com/gtag/js`.
+ */
+type GoogleTagProxyMode = "proxied" | "direct";
+/**
+ * Configuration for the Google Tag Gateway SDK feature. Ships under the
+ * `googleTag` key of /decide when at least one `ga4_gtag` or `google_ads_gtag` destination is
+ * enabled for the project.
+ */
+interface GoogleTagClientConfig {
+    destinationId: string;
+    /**
+     * Proxy mode. When absent the SDK falls back to `proxied` so older
+     * `/decide` responses and the zero-config default remain compatible.
+     */
+    proxyMode?: GoogleTagProxyMode;
+    tagIds: string[];
+    conversions: GoogleAdsConversionMapping[];
+    enhancedConversions: boolean;
+    conversionLinker: boolean;
+    linkerDomains: string[];
+    capturePageview: boolean;
+    debugMode: boolean;
+    consentOverride?: GoogleConsentOverride;
+    /**
+     * Master switch for forwarding every `vt.capture()` event to GA4 via
+     * `gtag('event', name, params)`. Defaults to `true` when absent. When
+     * `false`, only events that match an explicit row in `eventMappings` — or
+     * an Ads `conversions` mapping — fire; everything else is left to the
+     * Google tag's own behavior (page_view, enhanced measurement, etc.).
+     */
+    autoForward?: boolean;
+    /**
+     * Whether to fire the direct Ads conversion beacon
+     * (`gtag('event', 'conversion', {send_to: 'AW-.../...'})`) for rows in
+     * `conversions`. Defaults to `true` when absent. Turn off when GA4 is
+     * linked to Google Ads in the Ads account — in that mode the GA4 event
+     * (marked as a conversion in GA4) propagates to Ads automatically and
+     * the direct beacon would duplicate it. Has no effect when `conversions`
+     * is empty.
+     */
+    sendAdsConversions?: boolean;
+    /**
+     * Admin-configured event renames and param remappings. Mirrors the
+     * generic `event_mappings` configured on the destination. Applied after
+     * the filter check and before firing `gtag('event', ...)`.
+     */
+    eventMappings?: GoogleTagEventMapping[];
+    /**
+     * Admin-configured include/exclude lists. Mirrors the generic
+     * `event_filter` on the destination. Evaluated before any mapping.
+     */
+    eventFilter?: {
+        include?: string[];
+        exclude?: string[];
+    };
+}
+/**
+ * Rename an event and optionally remap payload paths to gtag param paths.
+ * Structurally identical to the server-side `EventMapping` type but lives
+ * in the browser package to avoid cross-package imports. Source paths use
+ * dotted notation into the captured payload (e.g. `order.total`); dest
+ * paths use dotted notation into the outgoing gtag `params` object.
+ */
+interface GoogleTagEventMapping {
+    source: string;
+    destination: string;
+    param_mappings?: GoogleTagParamMapping[];
+}
+interface GoogleTagParamMapping {
+    source: string;
+    destination: string;
+}
 interface RemoteConfig {
     sessionRecording?: {
         enabled?: boolean;
@@ -28,6 +124,8 @@ interface RemoteConfig {
         enabled?: boolean;
         widgetPosition?: "bottom-right" | "bottom-left";
         widgetColor?: string;
+        bubbleDraggable?: boolean;
+        bubbleVisible?: boolean;
     };
     chatTracking?: {
         trackUserMessages?: boolean;
@@ -38,17 +136,33 @@ interface RemoteConfig {
         capturePageleave?: boolean;
         capturePerformance?: boolean;
         autocapture?: boolean;
+        scrollDepthMilestones?: boolean;
+        scrollDepthPageleave?: boolean;
     };
     privacy?: {
         respectDnt?: boolean;
         requireConsent?: boolean;
         ipAnonymization?: boolean;
     };
+    /**
+     * Diagnostics — runtime-tunable console verbosity. Applied by the SDK only
+     * when the integrator did NOT pass `log_level` / `debug` to `vt.init()`.
+     * Set from the dashboard's Default Configuration → Diagnostics tab.
+     */
+    diagnostics?: {
+        defaultLogLevel?: "none" | "error" | "warn" | "info" | "debug";
+    };
     featureFlags?: FeatureFlagsConfig;
     /** Whether to send elements as chain string (PostHog compatibility) */
     elementsChainAsString?: boolean;
     /** Server-side autocapture opt-out */
     autocapture_opt_out?: boolean;
+    /**
+     * Google Tag Gateway config (absent when no client Google gtag destination is
+     * enabled for the project). Drives the gtag.js proxy loader, Consent Mode
+     * v2 bridge, and event → conversion mappings.
+     */
+    googleTag?: GoogleTagClientConfig;
 }
 
 /**

package/dist/server.js

@@ -1,2 +1,2 @@
-function t(t,e,o,n,i,r,c){try{var l=t[r](c),u=l.value}catch(t){return void o(t)}l.done?e(u):Promise.resolve(u).then(n,i)}function e(t){return o.apply(this,arguments)}function o(){var e;return e=function*(t){var{apiHost:e,token:o,timeout:n=3e3}=t;if(!e||!o)return console.warn("[vTilt] Missing apiHost or token for fetchRemoteConfig"),null;var i=e+"/api/decide?token="+o;try{var r=new AbortController,c=setTimeout(()=>r.abort(),n),l=yield fetch(i,{method:"GET",headers:{Accept:"application/json"},signal:r.signal,next:{revalidate:60}});return clearTimeout(c),l.ok?yield l.json():(console.warn("[vTilt] Failed to fetch remote config: "+l.status),null)}catch(t){return"AbortError"===t.name?console.warn("[vTilt] Remote config fetch timed out"):console.warn("[vTilt] Failed to fetch remote config:",t),null}},o=function(){var o=this,n=arguments;return new Promise(function(i,r){var c=e.apply(o,n);function l(e){t(c,i,r,l,u,"next",e)}function u(e){t(c,i,r,l,u,"throw",e)}l(void 0)})},o.apply(this,arguments)}function n(t){return t?"window.__VTILT_BOOTSTRAP__="+JSON.stringify({remoteConfig:t})+";":""}export{e as fetchRemoteConfig,n as generateBootstrapScript};
+function e(e,r,n,o,t,i,f){try{var a=e[i](f),u=a.value}catch(e){return void n(e)}a.done?r(u):Promise.resolve(u).then(o,t)}var r={none:0,error:1,warn:2,info:3,debug:4},n="[vTilt]",o=new Set(["none","error","warn","info","debug"]);function t(){return"undefined"!=typeof console}function i(e){var r=e.length>0&&"string"==typeof e[0]?e[0]:"",o=r?e.slice(1):e;return[r?n+":"+r:n,...o]}var f="warn",a=!1;var u=null;function c(){return u||(u={setLevel(e,r){void 0===r&&(r=!1),f=e,r&&(a=!0)},setLevelFromRemote(e){a||e&&o.has(e)&&(f=e)},getLevel:()=>f,isLockedByInit:()=>a,debug(){if(!(r[f]<r.debug)&&t()){for(var e=arguments.length,n=new Array(e),o=0;o<e;o++)n[o]=arguments[o];console.log(...i(n))}},info(){if(!(r[f]<r.info)&&t()){for(var e=arguments.length,n=new Array(e),o=0;o<e;o++)n[o]=arguments[o];console.log(...i(n))}},warn(){if(!(r[f]<r.warn)&&t()){for(var e=arguments.length,n=new Array(e),o=0;o<e;o++)n[o]=arguments[o];console.warn(...i(n))}},error(){if(!(r[f]<r.error)&&t()){for(var e=arguments.length,n=new Array(e),o=0;o<e;o++)n[o]=arguments[o];console.error(...i(n))}}}),u}function l(e){return v.apply(this,arguments)}function v(){var r;return r=function*(e){var{apiHost:r,token:n,timeout:o=3e3}=e;if(!r||!n)return c().warn("server","missing apiHost or token for fetchRemoteConfig"),null;var t=r.replace(/\/+$/gm,"")+"/api/d";try{var i=new AbortController,f=setTimeout(()=>i.abort(),o),a=yield fetch(t,{method:"GET",headers:{Accept:"application/json","x-api-key":n},signal:i.signal,next:{revalidate:60}});return clearTimeout(f),a.ok?yield a.json():(c().warn("server","failed to fetch remote config: "+a.status),null)}catch(e){return"AbortError"===e.name?c().warn("server","remote config fetch timed out"):c().warn("server","failed to fetch remote config:",e),null}},v=function(){var n=this,o=arguments;return new Promise(function(t,i){var f=r.apply(n,o);function a(r){e(f,t,i,a,u,"next",r)}function u(r){e(f,t,i,a,u,"throw",r)}a(void 0)})},v.apply(this,arguments)}function s(e){return e?"window.__VTILT_BOOTSTRAP__="+JSON.stringify({remoteConfig:e})+";":""}export{l as fetchRemoteConfig,s as generateBootstrapScript};
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sources":["../src/server.ts"],"sourcesContent":[null],"names":["fetchRemoteConfig","_x","_fetchRemoteConfig","apply","this","arguments","options","apiHost","token","timeout","console","warn","url","controller","AbortController","timeoutId","setTimeout","abort","response","fetch","method","headers","Accept","signal","next","revalidate","clearTimeout","ok","json","status","error","name","generateBootstrapScript","remoteConfig","JSON","stringify"],"mappings":"yHA8CA,SAAsBA,EAAiBC,GAAA,OAAAC,EAAAC,MAAAC,KAAAC,UAAA,CA0CvC,SAAAH,UAFC,SAxCM,UACLI,GAEA,IAAMC,QAAEA,EAAOC,MAAEA,EAAKC,QAAEA,EAAU,KAASH,EAE3C,IAAKC,IAAYC,EAEf,OADAE,QAAQC,KAAK,0DACN,KAGT,IAAMC,EAASL,EAAO,qBAAqBC,EAE3C,IACE,IAAMK,EAAa,IAAIC,gBACjBC,EAAYC,WAAW,IAAMH,EAAWI,QAASR,GAEjDS,QAAiBC,MAAMP,EAAK,CAChCQ,OAAQ,MACRC,QAAS,CAAEC,OAAQ,oBACnBC,OAAQV,EAAWU,OAEnBC,KAAM,CAAEC,WAAY,MAKtB,OAFAC,aAAaX,GAERG,EAASS,SAKAT,EAASU,QAJrBlB,QAAQC,KAAI,0CAA2CO,EAASW,QACzD,KAIX,CAAE,MAAOC,GAMP,MAL8B,eAAzBA,EAAgBC,KACnBrB,QAAQC,KAAK,yCAEbD,QAAQC,KAAK,yCAA0CmB,GAElD,IACT,CACF,EAEA5B,8KAFCA,EAAAC,MAAAC,KAAAC,UAAA,CAgBK,SAAU2B,EACdC,GAEA,OAAKA,EAIL,8BAAqCC,KAAKC,UAAU,CAAEF,iBAAe,IAH5D,EAIX"}
+{"version":3,"file":"server.js","sources":["../src/utils/logger.ts","../src/server.ts"],"sourcesContent":[null,null],"names":["LEVEL_PRIORITY","none","error","warn","info","debug","PREFIX","VALID_LEVELS","Set","hasConsole","console","formatArgs","args","scope","length","rest","slice","currentLevel","lockedByInit","singleton","getLogger","setLevel","level","lockFromInit","setLevelFromRemote","has","getLevel","isLockedByInit","_len","arguments","Array","_key","log","_len2","_key2","_len3","_key3","_len4","_key4","fetchRemoteConfig","_x","_fetchRemoteConfig","apply","this","options","apiHost","token","timeout","url","replace","controller","AbortController","timeoutId","setTimeout","abort","response","fetch","method","headers","Accept","signal","next","revalidate","clearTimeout","ok","json","status","name","generateBootstrapScript","remoteConfig","JSON","stringify"],"mappings":"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"}

package/dist/session.d.ts

@@ -10,7 +10,13 @@ import { PersistenceMethod } from "./types";
 export declare class SessionManager {
     private storage;
     private _windowId;
+    private _isNewSession;
     constructor(storageMethod?: PersistenceMethod, cross_subdomain?: boolean);
+    /**
+     * Hydrate window ID from sessionStorage.
+     * Called by VTilt._boot() once the browser environment is ready.
+     */
+    hydrateFromStorage(): void;
     /**
      * Get session ID (always returns a value, generates if needed)
      */
@@ -24,6 +30,12 @@ export declare class SessionManager {
      * Reset session ID (generates new session on reset)
      */
     resetSessionId(): void;
+    /**
+     * Returns true if the current session was just started (new session ID generated
+     * because the session cookie expired or didn't exist). Resets after first call.
+     * Matches GA4's _ss=1 semantics.
+     */
+    consumeSessionStart(): boolean;
     /**
      * Get session ID from storage (raw, can return null)
      * Cookie Max-Age handles expiration automatically

package/dist/types.d.ts

@@ -5,10 +5,15 @@
  * Following PostHog's patterns where applicable.
  */
 import type { PersonProfilesMode } from "./constants";
+import type { BubbleConfig } from "./utils/globals";
 export interface VTiltConfig {
     /** Project identifier (required) */
     token: string;
-    /** API host for tracking (default: https://api.vtilt.io) */
+    /**
+     * API host for all SDK requests (events, config, recordings, chat).
+     * Set this to your own domain when using a reverse proxy.
+     * If not set, SDK uses relative URLs (same-origin).
+     */
     api_host?: string;
     /** UI host for dashboard links */
     ui_host?: string | null;
@@ -18,10 +23,6 @@ export interface VTiltConfig {
      * If not set, falls back to {api_host}/dist/{script}.js
      */
     script_host?: string;
-    /** Proxy domain for tracking requests */
-    proxy?: string;
-    /** Full proxy URL for tracking requests */
-    proxyUrl?: string;
     /** Instance name (for multiple instances) */
     name?: string;
     /** Domain to track (auto-detected if not provided) - used in event properties */
@@ -75,8 +76,25 @@ export interface VTiltConfig {
     mask_all_element_attributes?: boolean;
     /** Respect Do Not Track browser setting */
     respect_dnt?: boolean;
+    /**
+     * When false (default), events are not sent when the browser looks like a bot
+     * (known crawler user agents, `navigator.webdriver`, or blocked CH brands).
+     * Set to true to disable bot filtering (PostHog: `opt_out_useragent_filter`).
+     */
+    opt_out_useragent_filter?: boolean;
+    /**
+     * Extra user-agent substrings to treat as bots (case-insensitive), merged with
+     * the built-in list aligned with PostHog (PostHog: `custom_blocked_useragents`).
+     */
+    custom_blocked_useragents?: string[];
     /** Opt users out by default */
     opt_out_capturing_by_default?: boolean;
+    /**
+     * When true, non-essential events are blocked until setConsent() is called.
+     * Essential events ($identify, $alias, $set) are always allowed.
+     * Use with vt.setConsent({ analytics: true, marketing: true, advertising: true }).
+     */
+    require_consent?: boolean;
     /** Session recording configuration */
     session_recording?: SessionRecordingOptions;
     /** Disable session recording (convenience flag) */
@@ -85,6 +103,46 @@ export interface VTiltConfig {
     chat?: ChatWidgetConfig;
     /** Disable chat (convenience flag) */
     disable_chat?: boolean;
+    /**
+     * Google Tag Gateway feature config (merged `ga4_gtag` + `google_ads_gtag`
+     * rows). Property name is the stable SDK config key; populated from `/decide`
+     * or set for SSR/tests.
+     */
+    google_tag?: GoogleTagClientConfig;
+    /** Disable the Google Tag Gateway feature (convenience flag) */
+    disable_google_tag?: boolean;
+    /**
+     * Console log level for SDK output prefixed with `[vTilt]`.
+     *
+     * Levels (each includes the levels above it):
+     *  - 'none'  — silence everything (escape hatch for shared kiosks etc.)
+     *  - 'error' — SDK errors only
+     *  - 'warn'  — errors + warnings (default)
+     *  - 'info'  — + lifecycle events (init, autocapture started, replay started)
+     *  - 'debug' — + per-event trace (every captured event, autocapture skips, requests)
+     *
+     * Default is 'warn' so SDK errors and warnings always surface without opt-in
+     * (matches Amplitude/PostHog/Sentry).
+     *
+     * NOT to be confused with the per-event `$debug` flag — that is a separate
+     * marker on the event payload itself, controlled by `debug: true` (below)
+     * or the `?vtilt_debug=1` URL parameter, and consumed by the Debug View in
+     * the dashboard. See the public docs for details.
+     *
+     * Setting `log_level` (or `debug: true`) at init time pins the level — it
+     * cannot be overridden by remote config / Default Configuration. Leave it
+     * unset to let project admins control verbosity from the dashboard.
+     */
+    log_level?: "none" | "error" | "warn" | "info" | "debug";
+    /**
+     * PostHog-style shorthand: when true, equivalent to `log_level: 'debug'`.
+     * Ignored if `log_level` is also set.
+     *
+     * Setting this to true ALSO marks every captured event with `$debug: true`
+     * so the dashboard's Debug View highlights it. The `?vtilt_debug=1` URL
+     * parameter sets the event flag without raising the console log level.
+     */
+    debug?: boolean;
     /** Global attributes added to all events */
     globalAttributes?: Record<string, string>;
     /** Bootstrap data for initialization (server-side rendering) */
@@ -99,6 +157,8 @@ export interface VTiltConfig {
     before_send?: (event: CaptureResult) => CaptureResult | null;
     /** Loaded callback */
     loaded?: (vtilt: any) => void;
+    /** @internal Set by RemoteConfigManager after a fresh /decide response (or fetch failure). */
+    __remote_config_loaded?: boolean;
 }
 export interface EventPayload {
     [key: string]: any;
@@ -167,9 +227,13 @@ export interface UserIdentity {
 export interface UserProperties {
     [key: string]: any;
 }
-export interface AliasEvent {
-    distinct_id: string;
-    original: string;
+/** Batched identity state change — applied atomically with a single save. */
+export interface IdentityUpdate {
+    distinct_id?: string;
+    user_state?: "anonymous" | "identified";
+    device_id?: string;
+    properties_set?: Properties;
+    properties_set_once?: Properties;
 }
 /** Supported Web Vitals metrics */
 export type SupportedWebVitalsMetric = "LCP" | "CLS" | "FCP" | "INP" | "TTFB";
@@ -307,6 +371,16 @@ export interface AutocaptureOptions {
      * @default false
      */
     capture_element_values?: boolean;
+    /**
+     * Scroll depth autocapture — two independently opt-in modes (both default off).
+     */
+    scroll_depth?: {
+        milestones?: boolean | {
+            thresholds?: number[];
+        };
+        pageleave?: boolean;
+        scroll_root_selector?: string | string[];
+    };
 }
 /** Mask options for input elements in session recording */
 export interface SessionRecordingMaskInputOptions {
@@ -353,6 +427,11 @@ export interface SessionRecordingOptions {
     blockClass?: string;
     /** Block selector for elements to hide */
     blockSelector?: string;
+    /**
+     * When `true`, skip built-in `blockSelector` entries for common invisible
+     * template nodes (screen-reader-only, Webflow CMS placeholders, etc.).
+     */
+    skipDefaultInvisibleBlocking?: boolean;
     /** Ignore class for input masking (default: 'vt-ignore-input') */
     ignoreClass?: string;
     /** Mask text class (default: 'vt-mask') */
@@ -373,7 +452,7 @@ export interface SessionRecordingOptions {
     recordHeaders?: boolean;
     /** Record body in network requests */
     recordBody?: boolean;
-    /** Compress events before sending (default: true) */
+    /** Gzip-compress the request body before sending (default: true) */
     compressEvents?: boolean;
     /** Internal: Mutation throttler refill rate */
     __mutationThrottlerRefillRate?: number;
@@ -402,6 +481,104 @@ export interface ChatWidgetConfig {
     offlineMessage?: string;
     /** Collect email when offline */
     collectEmailOffline?: boolean;
+    /** Bubble appearance and behavior */
+    bubble?: BubbleConfig;
+}
+export type GoogleConsentValue = "follow_advertising" | "follow_analytics" | "granted" | "denied";
+export interface GoogleConsentOverride {
+    ad_storage?: GoogleConsentValue;
+    ad_user_data?: GoogleConsentValue;
+    ad_personalization?: GoogleConsentValue;
+    analytics_storage?: GoogleConsentValue;
+}
+export interface GoogleAdsConversionMapping {
+    event_name: string;
+    send_to: string;
+    value_param_path?: string;
+    currency_param_path?: string;
+    default_currency?: string;
+    send_transaction_id?: boolean;
+    transaction_id_param_path?: string;
+}
+/**
+ * How gtag.js is loaded — mirrors the server-side `proxy_mode` destination
+ * setting:
+ *
+ * - `proxied` (default) — route through `api_host/gt/*`. `api_host` is the
+ *   SDK-level proxy setting; self-hosted customers point it at their own
+ *   domain (which must implement the `/gt/*` spec).
+ * - `direct` — no proxy; gtag.js loads straight from
+ *   `https://www.googletagmanager.com/gtag/js`.
+ */
+export type GoogleTagProxyMode = "proxied" | "direct";
+/**
+ * Configuration for the Google Tag Gateway SDK feature. Ships under the
+ * `googleTag` key of /decide when at least one `ga4_gtag` or `google_ads_gtag` destination is
+ * enabled for the project.
+ */
+export interface GoogleTagClientConfig {
+    destinationId: string;
+    /**
+     * Proxy mode. When absent the SDK falls back to `proxied` so older
+     * `/decide` responses and the zero-config default remain compatible.
+     */
+    proxyMode?: GoogleTagProxyMode;
+    tagIds: string[];
+    conversions: GoogleAdsConversionMapping[];
+    enhancedConversions: boolean;
+    conversionLinker: boolean;
+    linkerDomains: string[];
+    capturePageview: boolean;
+    debugMode: boolean;
+    consentOverride?: GoogleConsentOverride;
+    /**
+     * Master switch for forwarding every `vt.capture()` event to GA4 via
+     * `gtag('event', name, params)`. Defaults to `true` when absent. When
+     * `false`, only events that match an explicit row in `eventMappings` — or
+     * an Ads `conversions` mapping — fire; everything else is left to the
+     * Google tag's own behavior (page_view, enhanced measurement, etc.).
+     */
+    autoForward?: boolean;
+    /**
+     * Whether to fire the direct Ads conversion beacon
+     * (`gtag('event', 'conversion', {send_to: 'AW-.../...'})`) for rows in
+     * `conversions`. Defaults to `true` when absent. Turn off when GA4 is
+     * linked to Google Ads in the Ads account — in that mode the GA4 event
+     * (marked as a conversion in GA4) propagates to Ads automatically and
+     * the direct beacon would duplicate it. Has no effect when `conversions`
+     * is empty.
+     */
+    sendAdsConversions?: boolean;
+    /**
+     * Admin-configured event renames and param remappings. Mirrors the
+     * generic `event_mappings` configured on the destination. Applied after
+     * the filter check and before firing `gtag('event', ...)`.
+     */
+    eventMappings?: GoogleTagEventMapping[];
+    /**
+     * Admin-configured include/exclude lists. Mirrors the generic
+     * `event_filter` on the destination. Evaluated before any mapping.
+     */
+    eventFilter?: {
+        include?: string[];
+        exclude?: string[];
+    };
+}
+/**
+ * Rename an event and optionally remap payload paths to gtag param paths.
+ * Structurally identical to the server-side `EventMapping` type but lives
+ * in the browser package to avoid cross-package imports. Source paths use
+ * dotted notation into the captured payload (e.g. `order.total`); dest
+ * paths use dotted notation into the outgoing gtag `params` object.
+ */
+export interface GoogleTagEventMapping {
+    source: string;
+    destination: string;
+    param_mappings?: GoogleTagParamMapping[];
+}
+export interface GoogleTagParamMapping {
+    source: string;
+    destination: string;
 }
 export interface RemoteConfig {
     sessionRecording?: {
@@ -423,6 +600,8 @@ export interface RemoteConfig {
         enabled?: boolean;
         widgetPosition?: "bottom-right" | "bottom-left";
         widgetColor?: string;
+        bubbleDraggable?: boolean;
+        bubbleVisible?: boolean;
     };
     chatTracking?: {
         trackUserMessages?: boolean;
@@ -433,15 +612,31 @@ export interface RemoteConfig {
         capturePageleave?: boolean;
         capturePerformance?: boolean;
         autocapture?: boolean;
+        scrollDepthMilestones?: boolean;
+        scrollDepthPageleave?: boolean;
     };
     privacy?: {
         respectDnt?: boolean;
         requireConsent?: boolean;
         ipAnonymization?: boolean;
     };
+    /**
+     * Diagnostics — runtime-tunable console verbosity. Applied by the SDK only
+     * when the integrator did NOT pass `log_level` / `debug` to `vt.init()`.
+     * Set from the dashboard's Default Configuration → Diagnostics tab.
+     */
+    diagnostics?: {
+        defaultLogLevel?: "none" | "error" | "warn" | "info" | "debug";
+    };
     featureFlags?: FeatureFlagsConfig;
     /** Whether to send elements as chain string (PostHog compatibility) */
     elementsChainAsString?: boolean;
     /** Server-side autocapture opt-out */
     autocapture_opt_out?: boolean;
+    /**
+     * Google Tag Gateway config (absent when no client Google gtag destination is
+     * enabled for the project). Drives the gtag.js proxy loader, Consent Mode
+     * v2 bridge, and event → conversion mappings.
+     */
+    googleTag?: GoogleTagClientConfig;
 }