@v-tilt/browser 1.11.0 → 1.12.0

package/dist/module.d.ts

@@ -6,6 +6,48 @@
  */
 type PersonProfilesMode = "always" | "identified_only" | "never";
 
+/**
+ * First argument to `vt.sendChatMessage()` / {@link LazyLoadedChatInterface.sendMessage}.
+ *
+ * Plain strings stay plain text for backward compatibility. Use `{ markdown: '...' }`,
+ * `{ html: '...' }`, or `options.format` for rich content.
+ */
+type SendChatMessageContent = string | {
+    text: string;
+} | {
+    markdown: string;
+} | {
+    html: string;
+};
+/**
+ * Options for `vt.sendChatMessage()` / {@link LazyLoadedChatInterface.sendMessage}.
+ */
+interface SendChatMessageOptions {
+    /**
+     * Target conversation: `'new'` creates a channel, a UUID selects an existing one,
+     * omit to use the active conversation (must already be in conversation view).
+     */
+    channel?: "new" | string;
+    /**
+     * Open the widget panel before sending. Default: true. Pass `open: false` to send without opening.
+     */
+    open?: boolean;
+    /**
+     * Applies when the first argument is a plain string. Default: `text`.
+     * `markdown` and `html` use the same sanitized rendering as AI/agent messages.
+     */
+    format?: "text" | "markdown" | "html";
+}
+/**
+ * Chat bubble appearance and behavior configuration
+ */
+interface BubbleConfig {
+    /** Allow user to drag the bubble to reposition (default: false) */
+    draggable?: boolean;
+    /** Show the bubble on load (default: true). Set to false to control via vt.chat.show() */
+    visible?: boolean;
+}
+
 /**
  * VTilt Types
  *
@@ -16,7 +58,11 @@ type PersonProfilesMode = "always" | "identified_only" | "never";
 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;
@@ -26,10 +72,6 @@ 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 */
@@ -83,8 +125,25 @@ 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) */
@@ -93,6 +152,46 @@ 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) */
@@ -107,6 +206,8 @@ 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;
 }
 interface EventPayload {
     [key: string]: any;
@@ -175,9 +276,13 @@ interface UserIdentity {
 interface UserProperties {
     [key: string]: any;
 }
-interface AliasEvent {
-    distinct_id: string;
-    original: string;
+/** Batched identity state change — applied atomically with a single save. */
+interface IdentityUpdate {
+    distinct_id?: string;
+    user_state?: "anonymous" | "identified";
+    device_id?: string;
+    properties_set?: Properties;
+    properties_set_once?: Properties;
 }
 /** Supported Web Vitals metrics */
 type SupportedWebVitalsMetric = "LCP" | "CLS" | "FCP" | "INP" | "TTFB";
@@ -315,6 +420,16 @@ 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 */
 interface SessionRecordingMaskInputOptions {
@@ -361,6 +476,11 @@ 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') */
@@ -381,7 +501,7 @@ 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;
@@ -410,6 +530,104 @@ interface ChatWidgetConfig {
     offlineMessage?: string;
     /** Collect email when offline */
     collectEmailOffline?: boolean;
+    /** Bubble appearance and behavior */
+    bubble?: BubbleConfig;
+}
+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?: {
@@ -431,6 +649,8 @@ interface RemoteConfig {
         enabled?: boolean;
         widgetPosition?: "bottom-right" | "bottom-left";
         widgetColor?: string;
+        bubbleDraggable?: boolean;
+        bubbleVisible?: boolean;
     };
     chatTracking?: {
         trackUserMessages?: boolean;
@@ -441,17 +661,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;
 }
 
 /**
@@ -466,7 +702,13 @@ interface RemoteConfig {
 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)
      */
@@ -480,6 +722,12 @@ 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
@@ -537,8 +785,22 @@ declare class SessionManager {
 declare class UserManager {
     private storage;
     private userIdentity;
-    private _cachedPersonProperties;
+    private _isFirstVisit;
     constructor(storageMethod?: PersistenceMethod, cross_subdomain?: boolean);
+    /**
+     * Hydrate identity from persistent storage.
+     *
+     * Called by VTilt._boot() once the browser environment is guaranteed ready
+     * (DOMContentLoaded). This is the only code path that reads from
+     * localStorage / cookies. If storage is empty (first visit), the generated
+     * IDs are persisted so they survive the next page load.
+     */
+    hydrateFromStorage(): void;
+    /**
+     * Generate an ephemeral in-memory identity with no storage access.
+     * Used by the constructor so the SDK is safe to instantiate in SSR.
+     */
+    private generateEphemeralIdentity;
     /**
      * Get current user identity
      */
@@ -568,42 +830,20 @@ declare class UserManager {
      */
     getUserState(): "anonymous" | "identified";
     /**
-     * Identify a user with distinct ID and properties
-     */
-    identify(newDistinctId?: string, userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
-    /**
-     * Set user properties without changing distinct ID
+     * Returns true if this is the user's first visit (no prior anonymous_id
+     * in storage when the SDK booted). Resets after first call.
+     * Matches GA4's _fv=1 semantics.
      */
-    setUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): boolean;
+    consumeFirstVisit(): boolean;
     /**
-     * Reset user identity (logout)
-     * Generates new anonymous ID, clears user data, optionally resets device ID
+     * Apply batched identity changes with a single save.
+     * Replaces individual setters to avoid multiple storage writes per operation.
      */
-    reset(reset_device_id?: boolean): void;
+    applyUpdate(update: IdentityUpdate): void;
     /**
-     * Update distinct ID (internal use - for VTilt)
+     * Reset identity to anonymous state. Generates new IDs and clears user data.
      */
-    setDistinctId(distinctId: string): void;
-    /**
-     * Update user state (internal use - for VTilt)
-     */
-    setUserState(state: "anonymous" | "identified"): void;
-    /**
-     * Update user properties (internal use - for VTilt)
-     */
-    updateUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
-    /**
-     * Set device ID if not already set (internal use - for VTilt)
-     */
-    ensureDeviceId(deviceId: string): void;
-    /**
-     * Create an alias to link two distinct IDs
-     */
-    createAlias(alias: string, original?: string): AliasEvent | null;
-    /**
-     * Check if distinct ID is string-like (hardcoded string) - public for validation
-     */
-    isDistinctIdStringLikePublic(distinctId: string): boolean;
+    reset(resetDeviceId?: boolean): void;
     /**
      * Set initial person info
      */
@@ -650,275 +890,95 @@ declare class UserManager {
      * Register a value once (only if not already set)
      */
     private register_once;
-    /**
-     * Generate a new anonymous ID
-     */
     private generateAnonymousId;
-    /**
-     * Generate a new device ID
-     */
     private generateDeviceId;
     /**
-     * Get hash for person properties (for deduplication)
-     */
-    private getPersonPropertiesHash;
-    /**
-     * Validate distinct ID
-     */
-    private isValidDistinctId;
-    /**
-     * Check if distinct ID is string-like (hardcoded string)
-     */
-    private isDistinctIdStringLike;
-    /**
-     * Update storage method at runtime
+     * Update storage method at runtime.
      */
     updateStorageMethod(method: PersistenceMethod, cross_subdomain?: boolean): void;
 }
 
 /**
- * Feature Interface & Base Class
+ * Feature Interface & Base Classes
  *
- * Standard interface that all vTilt features implement.
- * Provides consistent lifecycle management and self-contained configuration.
+ * Standard interfaces and abstract base classes for vTilt SDK features.
  *
- * Design Principles:
- * 1. Features are self-contained - they extract their own config
- * 2. Features implement a common interface - vtilt.ts doesn't need to know details
- * 3. Features handle their own errors - using safewrap utilities
- * 4. Features can communicate via events - using the event emitter
+ * Hierarchy:
+ *   Feature (interface)          — eager features (Autocapture, HistoryAutocapture)
+ *   ToggleableFeature (interface)— features that actively stop when disabled
+ *   LazyFeature (abstract)       — lazy-loaded features (WebVitals, Chat)
+ *   ToggleableLazyFeature        — lazy-loaded + toggle (SessionRecording)
  *
- * Based on PostHog's convention patterns, formalized as TypeScript interfaces.
+ * @see docs/patterns/tracker-feature-lifecycle.md
  */
 
 /**
  * Feature interface that all vTilt features should implement.
  * Provides a consistent lifecycle for feature initialization and management.
- *
- * @example
- * ```typescript
- * class MyFeature implements Feature {
- *   static extractConfig(config: VTiltConfig): MyFeatureConfig {
- *     return { enabled: !!config.myFeature };
- *   }
- *
- *   get isEnabled(): boolean { return this._config.enabled; }
- *   get isStarted(): boolean { return this._started; }
- *
- *   startIfEnabled(): void {
- *     if (this.isEnabled && !this._started) {
- *       this._start();
- *     }
- *   }
- *
- *   stop(): void {
- *     if (this._started) {
- *       this._cleanup();
- *       this._started = false;
- *     }
- *   }
- * }
- * ```
  */
 interface Feature {
-    /**
-     * Feature name for logging and debugging.
-     */
     readonly name: string;
-    /**
-     * Check if the feature is enabled based on current configuration.
-     * Features should check both local config and remote config.
-     */
     readonly isEnabled: boolean;
-    /**
-     * Check if the feature is currently started/active.
-     */
     readonly isStarted: boolean;
-    /**
-     * Start the feature if it's enabled, otherwise do nothing.
-     * This is the primary lifecycle method called during initialization.
-     *
-     * Safe to call multiple times - should be idempotent.
-     */
     startIfEnabled(): void;
-    /**
-     * Stop the feature and clean up any resources (event listeners, timers, etc.).
-     * Safe to call multiple times - should be idempotent.
-     */
     stop(): void;
     /**
      * Handle VTilt configuration updates.
      * Called when the main VTilt config is updated via updateConfig().
-     *
      * Features should re-evaluate their enabled state and start/stop accordingly.
-     *
-     * @param config - The new VTilt configuration
      */
     onConfigUpdate?(config: VTiltConfig): void;
-    /**
-     * Handle remote configuration updates from /decide endpoint.
-     * Called when new remote config is received from the server.
-     *
-     * Features can use this to enable/disable themselves based on server settings.
-     *
-     * @param remoteConfig - The remote configuration response
-     */
-    onRemoteConfig?(remoteConfig: RemoteConfig): void;
 }
-/**
- * Feature with the startIfEnabledOrStop pattern.
- * Used for features that should stop when disabled (not just stay stopped).
- *
- * Example: Session recording should stop if disabled mid-session.
- */
-interface ToggleableFeature extends Feature {
-    /**
-     * Start the feature if enabled, or stop it if disabled.
-     * More aggressive than startIfEnabled - actively stops if conditions change.
-     *
-     * @param trigger - Optional trigger name for debugging
-     */
-    startIfEnabledOrStop(trigger?: string): void;
-}
-/**
- * Base configuration that all features receive.
- * Features extend this for their specific config needs.
- */
 interface FeatureConfig {
-    /** Whether the feature is enabled */
     enabled?: boolean;
 }
 
 /**
- * Web Vitals Manager
- *
- * Captures Core Web Vitals (LCP, CLS, FCP, INP, TTFB) and sends them
- * as batched $web_vitals events. Implements the Feature interface for
- * consistent lifecycle management.
- *
- * Follows PostHog's approach with:
- * 1. Extension pattern - checks for callbacks registered on __VTiltExtensions__
- * 2. Lazy loading - loads web-vitals.js on demand if not bundled
- * 3. Configurable metrics - choose which metrics to capture
- * 4. Smart buffering - collects metrics per page, flushes on navigation or timeout
- * 5. Session context - includes session_id and window_id for correlation
+ * Autocapture
  *
- * Event structure:
- * - event: "$web_vitals"
- * - properties:
- *   - $web_vitals_LCP_value: number
- *   - $web_vitals_LCP_event: { name, value, delta, rating, ... }
- *   - $pathname: string
- *   - $current_url: string
- */
-
-declare class WebVitalsManager implements Feature {
-    readonly name = "WebVitals";
-    private _instance;
-    private _buffer;
-    private _flushTimer;
-    private _isStarted;
-    private _config;
-    /**
-     * Extract web vitals config from VTiltConfig (self-contained)
-     */
-    static extractConfig(config: VTiltConfig): CapturePerformanceConfig;
-    constructor(instance: VTilt);
-    /**
-     * Check if web vitals capture is enabled
-     */
-    get isEnabled(): boolean;
-    /**
-     * Check if capturing has started
-     */
-    get isStarted(): boolean;
-    /**
-     * Start capturing if enabled
-     */
-    startIfEnabled(): void;
-    /**
-     * Stop capturing (flushes any pending metrics)
-     */
-    stop(): void;
-    /**
-     * Handle config update
-     */
-    onConfigUpdate(config: VTiltConfig): void;
-    /**
-     * Get the list of metrics to capture
-     */
-    get allowedMetrics(): SupportedWebVitalsMetric[];
-    /**
-     * Get flush timeout in ms
-     */
-    get flushTimeoutMs(): number;
-    /**
-     * Get maximum allowed metric value
-     */
-    get maxAllowedValue(): number;
-    private _createEmptyBuffer;
-    private _getWebVitalsCallbacks;
-    private _loadWebVitals;
-    private _startCapturing;
-    private _getCurrentUrl;
-    private _getCurrentPathname;
-    private _addToBuffer;
-    private _cleanAttribution;
-    private _getWindowId;
-    private _scheduleFlush;
-    private _flush;
-}
-
-/**
- * History Autocapture
+ * Automatic DOM event capture for clicks, form submissions, and input changes.
+ * Privacy-first approach with element chain tracking and sensitive data filtering.
  *
- * Captures pageview events when the user navigates using the History API
- * (pushState, replaceState) or browser back/forward buttons.
+ * Lifecycle (see docs/patterns/tracker-feature-lifecycle.md):
+ *  - Construction:   created by FeatureManager when not hard-disabled.
+ *  - startIfEnabled: attaches DOM listeners when isEnabled becomes true.
+ *  - stop:           detaches DOM listeners. Subsequent startIfEnabled re-attaches.
+ *  - onConfigUpdate: re-evaluates isEnabled on every config change and starts or
+ *                    stops accordingly. This is what flips autocapture on when the
+ *                    /decide endpoint returns `analytics.autocapture: true`.
  *
- * Implements the Feature interface for consistent lifecycle management.
+ * Enabled state precedence (highest first):
+ *  1. _userOverride === false        → off (set by vt.stopAutocapture())
+ *  2. _isDisabledServerSide === true → off (set by remote autocapture_opt_out)
+ *  3. _userOverride === true         → on  (set by vt.startAutocapture())
+ *  4. config.autocapture truthy      → on
+ *  5. otherwise                      → off
  */
 
-interface HistoryAutocaptureConfig extends FeatureConfig {
-    /** Whether to capture pageviews on history changes */
-    enabled?: boolean;
-}
 /**
- * History Autocapture Feature
- *
- * Automatically captures $pageview events on SPA navigation.
- * Implements the Feature interface for consistent lifecycle management.
+ * Reasons isEnabled may evaluate to false. Surfaced by getDiagnostics() so that
+ * integrators can pinpoint why no `$autocapture` events are flowing.
  */
-declare class HistoryAutocapture implements Feature {
-    readonly name = "HistoryAutocapture";
-    private _instance;
-    private _config;
-    private _isStarted;
-    private _popstateListener;
-    private _lastPathname;
-    constructor(instance: VTilt, config?: HistoryAutocaptureConfig);
-    /**
-     * Extract history autocapture config from VTiltConfig.
-     * Self-contained - vtilt.ts doesn't need to know config details.
-     */
-    static extractConfig(config: VTiltConfig): HistoryAutocaptureConfig;
-    get isEnabled(): boolean;
-    get isStarted(): boolean;
-    startIfEnabled(): void;
-    stop(): void;
-    onConfigUpdate(config: VTiltConfig): void;
-    private _start;
-    private _patchHistoryMethods;
-    private _setupPopstateListener;
-    private _capturePageview;
+type AutocaptureDisabledReason = "user_stop_called" | "server_opt_out" | "config_autocapture_false" | "config_autocapture_undefined";
+interface AutocaptureDiagnostics {
+    /** Whether the feature is enabled given current config and overrides. */
+    isEnabled: boolean;
+    /** Whether DOM listeners are currently attached. */
+    isStarted: boolean;
+    /** Why the feature is disabled (if any). */
+    disabledReason: AutocaptureDisabledReason | null;
+    /** Snapshot of inputs that drove the decision. */
+    inputs: {
+        configAutocapture: unknown;
+        isDisabledServerSide: boolean;
+        userOverride: boolean | null;
+        elementsChainAsString: boolean;
+        captureCopiedText: boolean;
+        scrollDepthMilestones: boolean;
+        scrollDepthPageleave: boolean;
+        scrollDepthListenerAttached: boolean;
+    };
 }
-
-/**
- * Autocapture
- *
- * Automatic DOM event capture for clicks, form submissions, and input changes.
- * Privacy-first approach with element chain tracking and sensitive data filtering.
- */
-
 /**
  * Autocapture class for automatic DOM event tracking.
  * Implements the Feature interface for consistent lifecycle management.
@@ -928,531 +988,287 @@ declare class Autocapture implements Feature {
     private _instance;
     private _initialized;
     private _isDisabledServerSide;
+    /** Explicit user override via vt.startAutocapture() / vt.stopAutocapture(). */
+    private _userOverride;
     private _elementSelectors;
     private _rageclicks;
+    /**
+     * Compact-payload mode for `$autocapture`. When true (the default), the SDK
+     * only sends the `$elements_chain` string and omits the verbose `$elements`
+     * array — the array is duplicate information for the ingestion side and is
+     * what pushes payloads past the client size cap on apps with deep DOM
+     * trees / Tailwind / Material class soup. Integrators that still need
+     * `$elements` (legacy filters / external pipelines) can opt out with
+     * `vt.init({ elementsChainAsString: false })` or via `/decide`.
+     */
     private _elementsChainAsString;
-    constructor(instance: VTilt);
+    private _cachedConfig;
+    private _cachedConfigSource;
+    /**
+     * Bound DOM handlers. Stored so stop() can detach them — passing the same
+     * function reference is required by removeEventListener().
+     */
+    private _domHandler;
+    private _copyHandler;
+    private _copyHandlerAttached;
+    private _scrollDepthTracker;
+    private _pageviewUnsubscribe;
+    static extractConfig(config: VTiltConfig): {
+        enabled: boolean;
+    };
+    constructor(instance: VTilt, _config?: {
+        enabled: boolean;
+    });
     private get _config();
     get isEnabled(): boolean;
     get isStarted(): boolean;
     startIfEnabled(): void;
     stop(): void;
-    onConfigUpdate(_config: VTiltConfig): void;
-    onRemoteConfig(response: RemoteConfig): void;
     /**
-     * Update autocapture configuration (for programmatic control)
+     * Max scroll depth % for the current page when pageleave mode is enabled.
+     * Used to enrich `$pageleave` payloads.
+     */
+    getMaxScrollDepthPctForPageleave(): number | null;
+    onConfigUpdate(config: VTiltConfig): void;
+    /**
+     * Update autocapture configuration (for programmatic control).
+     * Called from vt.startAutocapture() / vt.stopAutocapture().
      */
     updateConfig(config: Partial<{
         enabled: boolean;
     }>): void;
+    getDiagnostics(): AutocaptureDiagnostics;
     setElementSelectors(selectors: Set<string>): void;
     getElementSelectors(element: Element | null): string[] | null;
+    /**
+     * Single-source-of-truth for whether autocapture should be active.
+     * Returns the disabled reason so diagnostics and logging can be precise.
+     */
+    private _evaluateEnabled;
     private _addDomEventHandlers;
-    private _captureEvent;
-    private _isBrowserSupported;
-}
-
-/**
- * Session Recording Types
- *
- * Type definitions for rrweb session recording.
- * Based on PostHog's implementation.
- */
-
-/** Mask options for input elements */
-type MaskInputOptions = Partial<{
-    color: boolean;
-    date: boolean;
-    "datetime-local": boolean;
-    email: boolean;
-    month: boolean;
-    number: boolean;
-    range: boolean;
-    search: boolean;
-    tel: boolean;
-    text: boolean;
-    time: boolean;
-    url: boolean;
-    week: boolean;
-    textarea: boolean;
-    select: boolean;
-    password: boolean;
-}>;
-/** Masking configuration */
-interface MaskingConfig {
-    maskAllInputs?: boolean;
-    maskTextSelector?: string;
-    blockSelector?: string;
-}
-/** Session recording configuration */
-interface SessionRecordingConfig {
-    /** Enable session recording */
-    enabled?: boolean;
-    /** Sample rate (0-1, where 1 = 100%) */
-    sampleRate?: number;
-    /** Minimum session duration in ms before sending */
-    minimumDurationMs?: number;
-    /** Session idle threshold in ms */
-    sessionIdleThresholdMs?: number;
-    /** Full snapshot interval in ms */
-    fullSnapshotIntervalMs?: number;
-    /** Enable console log capture */
-    captureConsole?: boolean;
-    /** Enable network request capture */
-    captureNetwork?: boolean;
-    /** Canvas recording settings */
-    captureCanvas?: {
-        recordCanvas?: boolean;
-        canvasFps?: number;
-        canvasQuality?: number;
-    };
-    /** Masking settings */
-    masking?: MaskingConfig;
-    /** Block class for elements to hide */
-    blockClass?: string;
-    /** Block selector for elements to hide */
-    blockSelector?: string;
-    /** Ignore class for input masking */
-    ignoreClass?: string;
-    /** Mask text class */
-    maskTextClass?: string;
-    /** Mask text selector */
-    maskTextSelector?: string;
-    /** Mask all inputs */
-    maskAllInputs?: boolean;
-    /** Mask input options */
-    maskInputOptions?: MaskInputOptions;
-    /** Record headers in network requests */
-    recordHeaders?: boolean;
-    /** Record body in network requests */
-    recordBody?: boolean;
-    /** Compress events before sending */
-    compressEvents?: boolean;
-    /** Internal: Mutation throttler refill rate */
-    __mutationThrottlerRefillRate?: number;
-    /** Internal: Mutation throttler bucket size */
-    __mutationThrottlerBucketSize?: number;
-}
-/** Recording start reason */
-type SessionStartReason = "recording_initialized" | "session_id_changed" | "linked_flag_matched" | "linked_flag_overridden" | "sampling_overridden" | "url_trigger_matched" | "event_trigger_matched" | "sampled" | "config_updated" | "remote_config";
-
-/**
- * Chat message structure (matches PostgreSQL chat_messages table)
- * Note: Read status is determined by cursor comparison, not per-message
- */
-interface ChatMessage {
-    id: string;
-    channel_id: string;
-    sender_type: "user" | "agent" | "ai" | "system";
-    sender_id: string | null;
-    sender_name: string | null;
-    sender_avatar_url: string | null;
-    content: string;
-    content_type: "text" | "html" | "attachment";
-    metadata: Record<string, unknown>;
-    created_at: string;
-}
-/**
- * Chat channel structure (maps 1:1 to Ably channel)
- */
-interface ChatChannel {
-    id: string;
-    project_id: string;
-    person_id: string;
-    distinct_id: string;
-    status: "open" | "closed" | "snoozed";
-    ai_mode: boolean;
-    unread_count: number;
-    last_message_at: string | null;
-    last_message_preview: string | null;
-    last_message_sender: "user" | "agent" | "ai" | "system" | null;
-    user_last_read_at: string | null;
-    agent_last_read_at: string | null;
-    created_at: string;
-}
-/**
- * Lightweight channel summary for channel list view
- * Used to avoid loading full channel data until user selects one
- */
-interface ChatChannelSummary {
-    id: string;
-    status: "open" | "closed" | "snoozed";
-    ai_mode: boolean;
-    last_message_at: string | null;
-    last_message_preview: string | null;
-    last_message_sender: "user" | "agent" | "ai" | "system" | null;
-    unread_count: number;
-    user_last_read_at: string | null;
-    created_at: string;
-}
-/**
- * Widget view state - determines what UI to show
- */
-type ChatWidgetView = "list" | "conversation";
-/**
- * Chat widget configuration
- *
- * Settings can come from two sources:
- * 1. Dashboard (fetched from /api/chat/settings) - "snippet-only" mode
- * 2. Code config (passed to vt.init) - overrides dashboard settings
- *
- * This enables Intercom-like flexibility: just add snippet OR customize with code.
- */
-interface ChatConfig {
+    private _removeDomEventHandlers;
     /**
-     * Enable/disable chat widget.
-     * - undefined: Use dashboard setting (auto-fetch)
-     * - true: Enable (override dashboard)
-     * - false: Disable entirely
+     * Scroll depth listener — opt-in via `autocapture.scroll_depth` milestones and/or pageleave.
      */
-    enabled?: boolean;
+    private _syncScrollDepthHandler;
+    private _teardownScrollDepth;
     /**
-     * Auto-fetch settings from dashboard (default: true)
-     * When true, SDK fetches /api/chat/settings and uses those as base config.
-     * Code config always overrides fetched settings.
+     * The copy/cut listener is opt-in via `autocapture.capture_copied_text`.
+     * Callable from both startIfEnabled and onConfigUpdate so toggling the flag
+     * mid-session correctly attaches or detaches the listener.
      */
-    autoConfig?: boolean;
-    /** Widget position (default: 'bottom-right') */
-    position?: "bottom-right" | "bottom-left";
-    /** Widget header/greeting message */
-    greeting?: string;
-    /** Widget primary color */
-    color?: string;
-    /** Start in AI mode (default: true) */
-    aiMode?: boolean;
-    /** AI greeting message (first message from AI) */
-    aiGreeting?: string;
-    /** Preload widget script on idle vs on-demand */
-    preload?: boolean;
-    /** Custom theme */
-    theme?: ChatTheme;
-    /** Offline message shown when business is unavailable */
-    offlineMessage?: string;
-    /** Collect email when offline */
-    collectEmailOffline?: boolean;
-    /** Called when widget is opened */
-    onWidgetOpen?: () => void;
-    /** Called when widget is closed */
-    onWidgetClose?: (data: {
-        timeOpenSeconds: number;
-        messagesSent: number;
-    }) => void;
-    /** Called when a new conversation is started */
-    onConversationStart?: (data: {
-        channelId: string;
-        aiMode: boolean;
-    }) => void;
-    /** Called when user sends a message */
-    onMessageSent?: (data: {
-        channelId: string;
-        messageId: string;
-    }) => void;
-    /** Called when a message is received (from AI or agent) */
-    onMessageReceived?: (data: {
-        channelId: string;
-        messageId: string;
-        senderType: "ai" | "agent";
-    }) => void;
-}
-/**
- * Chat theme customization
- */
-interface ChatTheme {
-    primaryColor?: string;
-    fontFamily?: string;
-    borderRadius?: string;
-    headerBgColor?: string;
-    userBubbleColor?: string;
-    agentBubbleColor?: string;
+    private _syncCopyHandler;
+    private _captureEvent;
+    private _isBrowserSupported;
 }
 
 /**
- * Session Recording Wrapper
+ * Consent Manager
  *
- * Lightweight wrapper that handles the decision of WHEN to load recording.
- * The actual recording logic is in LazyLoadedSessionRecording which is
- * loaded on demand.
+ * Manages user consent state for analytics, marketing, and advertising.
+ * Stores consent in a first-party cookie (_vtilt_consent) and provides
+ * consent properties to attach to every event.
  *
- * Implements the ToggleableFeature interface for consistent lifecycle management.
- * Based on PostHog's sessionrecording-wrapper.ts
+ * When `requireConsent` is true in config, the CaptureManager gates
+ * non-essential events until setConsent() is called.
  */
-
-/** Status when lazy loading is in progress */
-declare const LAZY_LOADING: "lazy_loading";
-/** Session recording status */
-type SessionRecordingStatus = "disabled" | "buffering" | "active" | "paused" | "sampled" | "trigger_pending" | typeof LAZY_LOADING;
-
-/**
- * Session Recording Wrapper
- *
- * This is the lightweight class that lives in the main bundle.
- * Implements ToggleableFeature for consistent lifecycle management.
- *
- * It handles:
- * - Deciding if recording should be enabled
- * - Lazy loading the actual recording code
- * - Delegating to LazyLoadedSessionRecording
- */
-declare class SessionRecordingWrapper implements ToggleableFeature {
-    private readonly _instance;
-    readonly name = "SessionRecording";
-    private _lazyLoadedRecording;
-    private _config;
-    private _isStarted;
-    constructor(_instance: VTilt, config?: SessionRecordingConfig);
-    /**
-     * Extract session recording config from VTiltConfig.
-     * Self-contained - vtilt.ts doesn't need to know config details.
-     */
-    static extractConfig(config: VTiltConfig): SessionRecordingConfig;
-    get isEnabled(): boolean;
-    get isStarted(): boolean;
-    /**
-     * Start if enabled (Feature interface).
-     * Use startIfEnabledOrStop for recording as it needs to actively stop.
-     */
-    startIfEnabled(): void;
-    /**
-     * Start if enabled, or stop if disabled (ToggleableFeature interface).
-     * This is the primary method for session recording.
-     */
-    startIfEnabledOrStop(trigger?: SessionStartReason): void;
-    /**
-     * Stop recording (Feature interface).
-     */
-    stop(): void;
-    /**
-     * Handle config updates (Feature interface).
-     */
-    onConfigUpdate(config: VTiltConfig): void;
+interface ConsentState {
+    analytics?: boolean;
+    marketing?: boolean;
+    advertising?: boolean;
+}
+interface ConsentHost {
+    _emitter?: {
+        emit(event: string, payload?: unknown): void;
+    };
+    getConfig(): {
+        require_consent?: boolean;
+    };
+}
+declare class ConsentManager {
+    private _host;
+    private _state;
+    private _hasBeenSet;
+    constructor(host: ConsentHost);
     /**
-     * Handle remote config updates (Feature interface).
+     * Set consent state. Merges with existing state.
+     * Persists to cookie and emits consent:updated.
      */
-    onRemoteConfig(remoteConfig: RemoteConfig): void;
-    get started(): boolean;
-    get status(): SessionRecordingStatus;
-    get sessionId(): string;
+    setConsent(consent: ConsentState): void;
     /**
-     * Alias for stop() for backwards compatibility.
+     * Get current consent state.
+     * Returns undefined fields for categories not yet set.
      */
-    stopRecording(): void;
+    getConsent(): ConsentState;
     /**
-     * Log a message to the recording.
+     * Whether setConsent() has been called (or consent was loaded from cookie).
+     * Used by CaptureManager to gate events when requireConsent is true.
      */
-    log(message: string, level?: "log" | "warn" | "error"): void;
+    hasConsent(): boolean;
     /**
-     * Update configuration.
+     * Apply default-all-granted state when no explicit consent exists.
+     * Sets all categories to true in memory but does NOT persist to cookie
+     * (implicit defaults don't need storage — only explicit user choices do).
      */
-    updateConfig(config: Partial<SessionRecordingConfig>): void;
-    private get _scriptName();
+    setDefaultGranted(): void;
     /**
-     * Lazy load the recording script and start.
+     * Returns event properties to attach to every captured event.
+     * Only includes fields that have been explicitly set.
      */
-    private _lazyLoadAndStart;
+    getConsentProperties(): Record<string, boolean>;
     /**
-     * Called after the recording script is loaded.
+     * Reset consent state (e.g. on user logout).
      */
-    private _onScriptLoaded;
+    reset(): void;
+    private _readFromCookie;
+    private _writeToCookie;
+    private _removeCookie;
 }
 
 /**
- * Message callback type
- */
-type MessageCallback = (message: ChatMessage) => void;
-/**
- * Typing callback type
+ * Consent Mode v2 bridge.
+ *
+ * Maps vTilt's 3-boolean consent (analytics / marketing / advertising) to
+ * Google's 4-key Consent Mode v2 payload (ad_storage, ad_user_data,
+ * ad_personalization, analytics_storage) and pushes it through gtag.
+ *
+ * Mapping (default):
+ *   advertising -> ad_storage + ad_user_data + ad_personalization
+ *   analytics   -> analytics_storage
+ *   marketing is not sent to Google by default (it covers email/SMS, not ads).
+ *
+ * Admin UI may override individual keys (`consentOverride`) to hard-wire a
+ * specific value regardless of user consent — useful for jurisdictions or
+ * projects with fixed policies.
  */
-type TypingCallback = (isTyping: boolean, senderType: string) => void;
+
+type GtagFn = (...args: unknown[]) => void;
+
 /**
- * Connection callback type
+ * `vt.gtag(...)` escape hatch.
+ *
+ * Power users may need to call `gtag` directly (e.g. to fire a custom
+ * conversion from a third-party widget or to set a debug param). We expose
+ * a flat passthrough that:
+ *
+ * - queues calls made before the SDK has booted (keeps them in FIFO order),
+ * - queues calls made before `gtag.js` has loaded (forwarded via the
+ *   `dataLayer` shim, which naturally buffers until the real script runs),
+ * - records every call so tests + the delivery log can see them.
  */
-type ConnectionCallback = (connected: boolean) => void;
+
+type GtagCall = unknown[];
+
 /**
- * Unsubscribe function type
+ * Enhanced Conversions helper.
+ *
+ * Hashes user-provided PII (email/phone/name/address) with SHA-256 before
+ * it leaves the browser, matching Google Ads' Enhanced Conversions format:
+ * https://support.google.com/google-ads/answer/13258081
+ *
+ * Returns an object suitable for `gtag('set', 'user_data', { ... })`.
  */
-type Unsubscribe$1 = () => void;
+interface RawUserData {
+    email?: string | null;
+    phone?: string | null;
+    first_name?: string | null;
+    last_name?: string | null;
+    street?: string | null;
+    city?: string | null;
+    region?: string | null;
+    postal_code?: string | null;
+    country?: string | null;
+}
 
 /**
- * Chat Wrapper
+ * GoogleTagGateway feature.
+ *
+ * Orchestrates the client-side half of the Google Tag Gateway destination:
  *
- * This is the lightweight class that lives in the main bundle.
- * Implements Feature for consistent lifecycle management.
+ * 1. Maintains `window.dataLayer` / `window.gtag`.
+ * 2. Pushes Consent Mode v2 defaults BEFORE gtag.js loads, and re-pushes
+ *    on `consent:updated` events.
+ * 3. Injects `gtag/js?id=<primary>` from the vTilt gateway (`/gt`) so
+ *    every measurement request flows through the first-party origin.
+ * 4. Subscribes to EVENT_CAPTURED and forwards mapped events to Ads
+ *    (`gtag('event', 'conversion', ...)`).
+ * 5. Exposes a flat `vt.gtag(...)` passthrough for power users.
  *
- * It handles:
- * - Auto-fetching settings from dashboard (Intercom-like)
- * - Merging server settings with code config
- * - Deciding if chat should be enabled
- * - Lazy loading the actual chat widget code
- * - Delegating to LazyLoadedChat
- * - Queuing messages/callbacks before widget loads
+ * Forwards only after `__remote_config_loaded` is true (same signal as
+ * EventBuffer: fresh `/decide` applied, bootstrap, or fetch failure).
+ * Captures before that are queued so we never drop events just because
+ * `/decide` has not committed yet. After remote is ready, we install the
+ * official `dataLayer` + `gtag` shim (`ensureDataLayer`) and forward
+ * immediately — the shim queues until `gtag.js` loads; we do not maintain a
+ * second SDK queue for that window.
+ *
+ * Feature lifecycle matches the rest of the SDK — registered with
+ * FeatureManager via a descriptor that pulls the admin-configured shape
+ * out of `/decide` under the `googleTag` key.
  */
-declare class ChatWrapper implements Feature {
-    private readonly _instance;
-    readonly name = "Chat";
-    private _lazyLoadedChat;
+
+interface GoogleTagGatewayFeatureConfig extends FeatureConfig {
+    remote?: GoogleTagClientConfig;
+}
+interface DeliveryLogEntry {
+    ts: number;
+    tag_ids: string[];
+    event_name: string;
+    send_to: string;
+    status: "fired" | "dropped";
+    reason?: string;
+}
+declare class GoogleTagGateway implements Feature {
+    readonly name = "GoogleTagGateway";
+    private _instance;
     private _config;
-    private _serverConfig;
-    private _configFetched;
-    private _isLoading;
     private _isStarted;
-    private _loadError;
-    private _pendingMessages;
-    private _pendingCallbacks;
-    private _messageCallbacks;
-    private _typingCallbacks;
-    private _connectionCallbacks;
-    constructor(_instance: VTilt, config?: ChatConfig);
-    /**
-     * Extract chat config from VTiltConfig.
-     * Self-contained - vtilt.ts doesn't need to know config details.
-     */
-    static extractConfig(config: VTiltConfig): ChatConfig;
+    private _scriptInjected;
+    private _scriptLoaded;
+    private _consentDefaultsPushed;
+    private _gtag;
+    private _publicApi;
+    private _loaderOptions;
+    private _unsubscribeCaptured;
+    private _unsubscribeConsent;
+    private _deliveryLog;
+    private readonly _maxDeliveryLog;
+    /**
+     * Captures observed before `__remote_config_loaded` only. Once remote
+     * commits, `ensureDataLayer` + gtag forward — gtag's own queue handles
+     * ordering until `gtag.js` is on the wire.
+     */
+    private readonly _pendingCaptures;
+    constructor(instance: VTilt, config?: GoogleTagGatewayFeatureConfig);
+    static extractConfig(config: VTiltConfig): GoogleTagGatewayFeatureConfig;
     get isEnabled(): boolean;
     get isStarted(): boolean;
-    /**
-     * Start chat if enabled (Feature interface).
-     * This is async because it may fetch server settings.
-     */
+    /** Exposed for tests and the public `vt.gtag` binding. */
+    get gtag(): GtagFn;
+    get deliveryLog(): DeliveryLogEntry[];
     startIfEnabled(): void;
-    /**
-     * Stop the chat widget (Feature interface).
-     */
     stop(): void;
-    /**
-     * Handle config updates (Feature interface).
-     */
     onConfigUpdate(config: VTiltConfig): void;
     /**
-     * Handle remote config updates (Feature interface).
-     */
-    onRemoteConfig(remoteConfig: RemoteConfig): void;
-    /**
-     * Async start implementation
-     */
-    private _startAsync;
-    /**
-     * Whether the chat widget is open
-     */
-    get isOpen(): boolean;
-    /**
-     * Whether connected to realtime service
-     */
-    get isConnected(): boolean;
-    /**
-     * Whether the widget is loading
-     */
-    get isLoading(): boolean;
-    /**
-     * Number of unread messages
-     */
-    get unreadCount(): number;
-    /**
-     * Current channel (if any)
-     */
-    get channel(): ChatChannel | null;
-    /**
-     * List of user's channels (multi-channel support)
-     */
-    get channels(): ChatChannelSummary[];
-    /**
-     * Current view state ('list' or 'conversation')
-     */
-    get currentView(): ChatWidgetView;
-    /**
-     * Open the chat widget
-     */
-    open(): void;
-    /**
-     * Close the chat widget
-     */
-    close(): void;
-    /**
-     * Toggle the chat widget open/closed
-     */
-    toggle(): void;
-    /**
-     * Show the chat widget (make visible but not necessarily open)
-     */
-    show(): void;
-    /**
-     * Hide the chat widget
-     */
-    hide(): void;
-    /**
-     * Fetch/refresh the list of user's channels
-     */
-    getChannels(): void;
-    /**
-     * Select a channel and load its messages
-     */
-    selectChannel(channelId: string): void;
-    /**
-     * Create a new channel and enter it
-     */
-    createChannel(): void;
-    /**
-     * Go back to channel list from conversation view
-     */
-    goToChannelList(): void;
-    /**
-     * Send a message
-     */
-    sendMessage(content: string): void;
-    /**
-     * Mark messages as read
-     */
-    markAsRead(): void;
-    /**
-     * Subscribe to new messages
-     */
-    onMessage(callback: MessageCallback): Unsubscribe$1;
-    /**
-     * Subscribe to typing indicators
-     */
-    onTyping(callback: TypingCallback): Unsubscribe$1;
-    /**
-     * Subscribe to connection changes
-     */
-    onConnectionChange(callback: ConnectionCallback): Unsubscribe$1;
-    /**
-     * Update configuration
-     */
-    updateConfig(config: Partial<ChatConfig>): void;
-    /**
-     * Get the merged configuration (server + code, code takes precedence)
-     */
-    getMergedConfig(): ChatConfig;
-    /**
-     * Destroy the chat widget
-     */
-    destroy(): void;
-    /**
-     * Fetch chat settings from the server
-     * This enables "snippet-only" installation where widget configures from dashboard
-     */
-    private _fetchServerSettings;
-    /**
-     * Show the chat bubble (launcher button) without fully loading the widget
-     * This creates a lightweight bubble that loads the full widget on click
+     * Set the user identifiers that power Enhanced Conversions. Values are
+     * normalized + SHA-256 hashed client-side before being pushed to gtag,
+     * so raw PII never leaves the browser.
      */
-    private _showBubble;
-    private get _scriptName();
-    /**
-     * Schedule preload on idle
-     */
-    private _schedulePreload;
-    /**
-     * Lazy load and then execute callback
-     */
-    private _lazyLoadAndThen;
-    /**
-     * Lazy load the chat script
-     */
-    private _lazyLoad;
-    /**
-     * Called after the chat script is loaded
-     */
-    private _onScriptLoaded;
+    setUserData(raw: RawUserData): Promise<void>;
+    getRecentPublicCalls(): GtagCall[];
+    private _start;
+    private _drainPending;
+    private _pushConsentDefaultsOnce;
+    private _subscribeCaptured;
+    /**
+     * Handle one captured event. Only `__remote_config_loaded === false` uses
+     * `_pendingCaptures`. After remote commits, we boot the gtag pipeline on
+     * demand (`startIfEnabled`) and forward — the dataLayer shim buffers until
+     * `gtag.js` loads.
+     */
+    private _handleCaptured;
+    private _subscribeConsent;
+    private _record;
 }
 
 /**
@@ -1547,6 +1363,18 @@ interface QueuedRequest {
     transport?: "xhr" | "sendBeacon";
 }
 
+/**
+ * Rate Limiter - Token Bucket Algorithm (PostHog-style)
+ *
+ * Prevents runaway loops from flooding the server with events.
+ * Uses a token bucket algorithm with configurable rate and burst limits.
+ *
+ * Features:
+ * - Configurable events per second (default: 10)
+ * - Configurable burst limit (default: 100)
+ * - Token replenishment over time
+ * - Warning event when rate limited
+ */
 interface RateLimitBucket {
     tokens: number;
     last: number;
@@ -1669,6 +1497,93 @@ declare class SimpleEventEmitter {
     hasListeners(event: string): boolean;
 }
 
+/**
+ * Feature Manager
+ *
+ * Central registry for SDK features. Features self-describe via descriptors
+ * that declare their config keys, remote config mappings, and class references.
+ *
+ * Responsibilities:
+ * - Registration: features register descriptors before init
+ * - Instance creation: createInstances() constructs instances during init() (pre-boot)
+ * - Starting: initAll() starts created instances at boot via startIfEnabled
+ * - Config propagation: notifyAll() calls onConfigUpdate on each instance
+ * - Descriptor exposure: getDescriptors() lets RemoteConfigManager._apply iterate
+ *
+ * @see docs/patterns/tracker-feature-lifecycle.md
+ */
+
+/**
+ * Self-describing metadata for a feature.
+ * Declared once at registration time; used by FeatureManager and RemoteConfigManager.
+ */
+interface FeatureDescriptor {
+    /** Unique name (used as map key and for get()) */
+    name: string;
+    /** VTiltConfig key that holds this feature's config (e.g. "session_recording") */
+    configKey?: keyof VTiltConfig;
+    /** VTiltConfig boolean key that hard-disables the feature (e.g. "disable_session_recording") */
+    disableKey?: keyof VTiltConfig;
+    /** Remote config mapping — tells _apply how to extract config from RemoteConfig */
+    remoteConfig?: {
+        /** Key on the RemoteConfig object (e.g. "sessionRecording") */
+        key: string;
+        /** Transform remote section into the shape written to VTiltConfig[configKey] */
+        map: (remote: Record<string, unknown>) => Record<string, unknown>;
+    };
+    /** Feature class — must have a static extractConfig and a constructor */
+    FeatureClass: {
+        new (instance: any, config?: any): Feature;
+        extractConfig(config: VTiltConfig): any;
+    };
+}
+/**
+ * Minimal host interface to avoid circular dependency with VTilt.
+ */
+interface FeatureHost {
+    getConfig(): VTiltConfig;
+}
+declare class FeatureManager {
+    private _host;
+    private _descriptors;
+    private _instances;
+    constructor(host: FeatureHost);
+    /** Register a feature descriptor. Call before initAll(). */
+    register(desc: FeatureDescriptor): void;
+    /**
+     * Create instances for all registered features without starting them.
+     * Safe to call before DOM boot — constructors are lightweight.
+     * Idempotent: skips features that already have an instance.
+     *
+     * Hard-disabled features are skipped (instance not created):
+     * - `disableKey` is true (e.g. `disable_chat: true`)
+     * - `configKey` section has `enabled: false` (e.g. `chat: { enabled: false }`)
+     */
+    createInstances(): void;
+    /**
+     * Create and start all registered features.
+     * Calls `createInstances()` first (idempotent), then `startIfEnabled()` on each.
+     */
+    initAll(): void;
+    /** Notify all initialized features of a config change. */
+    notifyAll(config: VTiltConfig): void;
+    /** Get a feature instance by name. */
+    get<T extends Feature>(name: string): T | undefined;
+    /** Register a late-created feature instance (e.g. from a public start*() call). */
+    set(name: string, instance: Feature): void;
+    /** Expose descriptors so RemoteConfigManager._apply can iterate for remote config mapping. */
+    getDescriptors(): Map<string, FeatureDescriptor>;
+    /**
+     * True when the integrator explicitly hard-disabled this feature in code config.
+     * Two signals: `disableKey` flag (e.g. `disable_chat: true`) or
+     * `configKey` section with `enabled: false` (e.g. `chat: { enabled: false }`).
+     *
+     * When `enabled` is omitted (undefined), the feature may still auto-configure
+     * from dashboard settings, so we must construct the instance.
+     */
+    private _isHardDisabled;
+}
+
 /**
  * VTilt SDK - Main Entry Point
  *
@@ -1681,57 +1596,111 @@ declare class SimpleEventEmitter {
  * - CaptureManager: Event capture and payload enrichment
  * - IdentityManager: High-level identity operations
  * - RemoteConfigManager: Remote configuration from /decide
- * - FeatureManager: Feature lifecycle management
+ * - FeatureManager: Feature lifecycle management (descriptors, initAll, notifyAll)
  *
- * @see docs/tracker/README.md for full documentation
+ * @see docs/patterns/tracker-feature-lifecycle.md
  */
 
 declare class VTilt {
     readonly version: string;
     __loaded: boolean;
-    __request_queue: QueuedRequest[];
-    historyAutocapture?: HistoryAutocapture;
-    autocapture?: Autocapture;
-    sessionRecording?: SessionRecordingWrapper;
-    chat?: ChatWrapper;
-    webVitals?: WebVitalsManager;
-    vtdOverlay?: VtdOverlay;
     private configManager;
     sessionManager: SessionManager;
     userManager: UserManager;
     private _captureManager;
     private _identityManager;
     private _remoteConfigManager;
-    private _featureManager;
+    consentManager: ConsentManager;
+    _featureManager: FeatureManager;
+    vtdOverlay?: VtdOverlay;
+    private _eventBuffer;
     private requestQueue;
     private retryQueue;
     rateLimiter: RateLimiter;
     _emitter: SimpleEventEmitter;
     private _has_warned_about_config;
+    private static readonly BOOT_GATED_METHODS;
+    private _booted;
+    private _pendingCalls;
+    private _postBootInitDone;
     constructor(config?: Partial<VTiltConfig>);
+    /**
+     * Register all features with their descriptors.
+     * Descriptors tell FeatureManager and RemoteConfigManager how each feature works.
+     */
+    private _registerFeatures;
+    private _installBootGate;
+    _boot(): void;
     init(token: string, config?: Partial<VTiltConfig>, name?: string): VTilt;
     private _init;
-    private _initFeatures;
-    private _initHistoryAutocapture;
-    private _initAutocapture;
-    private _initWebVitals;
-    _initSessionRecording(): void;
-    _initChat(): void;
+    /**
+     * Substantive init work that requires both init() config AND a booted
+     * browser environment. Runs exactly once.
+     *
+     * Init order: hydrate storage -> initAll features -> load remote config
+     * Features must exist before remote config loads so cached/fresh config
+     * can trigger onConfigUpdate on already-initialized features.
+     */
+    private _runPostBootInit;
     startAutocapture(): void;
     stopAutocapture(): void;
     isAutocaptureActive(): boolean;
+    /**
+     * Returns a structured snapshot of the autocapture state — useful for
+     * debugging "no `$autocapture` events" complaints. Returns `null` if the
+     * Autocapture feature has not been registered (e.g. before init).
+     */
+    getAutocaptureDiagnostics(): ReturnType<Autocapture["getDiagnostics"]> | null;
     startSessionRecording(): void;
     stopSessionRecording(): void;
     isRecordingActive(): boolean;
     getSessionRecordingId(): string | null;
+    openChat(): void;
+    closeChat(): void;
+    toggleChat(): void;
+    showChat(): void;
+    hideChat(): void;
+    /**
+     * Send a chat message. By default uses the active conversation; pass options to
+     * start a new conversation, target a channel, or open the widget panel.
+     */
+    sendChatMessage(content: SendChatMessageContent, options?: SendChatMessageOptions): void;
+    /**
+     * Raw `gtag(...)` passthrough. Queues calls made before the feature is
+     * enabled or before `gtag.js` has loaded, flushed FIFO once ready. Safe
+     * to call at any time, including before `vt.init()`.
+     *
+     * @example
+     *   vt.gtag('event', 'sign_up', { method: 'email' })
+     */
+    gtag(...args: unknown[]): void;
+    /**
+     * Set Enhanced Conversions user identifiers. Values are normalized and
+     * SHA-256 hashed in the browser before being forwarded to gtag.
+     */
+    setGoogleUserData(data: Parameters<GoogleTagGateway["setUserData"]>[0]): Promise<void>;
+    get featureManager(): FeatureManager;
+    on<T = unknown>(event: string, listener: EventListener<T>): Unsubscribe;
+    once<T = unknown>(event: string, listener: EventListener<T>): Unsubscribe;
+    /** Removes all listeners for `event` (same semantics as internal emitter). */
+    off(event: string): void;
+    /**
+     * Whether this browser session looks like a bot/crawler (PostHog parity).
+     * When true and bot filtering is enabled, `capture()` is a no-op.
+     */
+    _is_bot(): boolean;
     capture(name: string, payload: EventPayload, options?: {
         skip_client_rate_limiting?: boolean;
+        skip_engagement?: boolean;
     }): void;
-    trackEvent(name: string, payload?: EventPayload): void;
+    /** Emit $pageleave for the current page when enabled (SPA transitions, lifecycle hooks). */
+    tryCapturePageleave(reason: string): void;
     identify(newDistinctId?: string, userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
     setUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
     resetUser(reset_device_id?: boolean): void;
-    createAlias(alias: string, original?: string): void;
+    alias(alias: string, original?: string): void;
+    setConsent(consent: ConsentState): void;
+    getConsent(): ConsentState;
     getUserIdentity(): Record<string, any>;
     getDeviceId(): string;
     getUserState(): "anonymous" | "identified";
@@ -1742,9 +1711,15 @@ declare class VTilt {
     getAnonymousId(): string;
     toString(): string;
     updateConfig(config: Partial<VTiltConfig>): void;
-    private _notifyFeaturesOfConfigUpdate;
     buildUrl(): string;
-    sendRequest(url: string, event: TrackingEvent, shouldEnqueue?: boolean): void;
+    buildEndpointUrl(path: string): string;
+    sendRequest(url: string, event: TrackingEvent): void;
+    /**
+     * Route a captured event through the EventBuffer.
+     * $snapshot and $snapshot_items bypass the buffer (they have identity from
+     * UserManager and don't need config filtering).
+     */
+    bufferEvent(name: string, url: string, event: TrackingEvent): void;
     private _is_configured;
     private _send_batched_request;
     private _send_http_request;
@@ -1761,4 +1736,4 @@ declare class VTilt {
 declare const vt: VTilt;
 
 export { ALL_WEB_VITALS_METRICS, DEFAULT_WEB_VITALS_METRICS, VTilt, vt as default, vt };
-export type { AliasEvent, AutocaptureOptions, CaptureOptions, CapturePerformanceConfig, CaptureResult, ChatWidgetConfig, EventPayload, FeatureFlagsConfig, GeolocationData, GroupsConfig, PersistenceMethod, Properties, Property, PropertyOperations, RemoteConfig, RequestOptions, SessionData, SessionIdChangedCallback, SessionRecordingMaskInputOptions, SessionRecordingOptions, SupportedWebVitalsMetric, TrackingEvent, UserIdentity, UserProperties, VTiltConfig, WebVitalMetric };
+export type { AutocaptureOptions, CaptureOptions, CapturePerformanceConfig, CaptureResult, ChatWidgetConfig, EventPayload, FeatureFlagsConfig, GeolocationData, GoogleAdsConversionMapping, GoogleConsentOverride, GoogleConsentValue, GoogleTagClientConfig, GoogleTagEventMapping, GoogleTagParamMapping, GoogleTagProxyMode, GroupsConfig, IdentityUpdate, PersistenceMethod, Properties, Property, PropertyOperations, RemoteConfig, RequestOptions, SessionData, SessionIdChangedCallback, SessionRecordingMaskInputOptions, SessionRecordingOptions, SupportedWebVitalsMetric, TrackingEvent, UserIdentity, UserProperties, VTiltConfig, WebVitalMetric };