@v-tilt/browser 1.9.0 → 1.10.0

package/dist/module.d.ts

@@ -56,8 +56,12 @@ interface VTiltConfig {
      * - 'never': Never create person profiles
      */
     person_profiles?: PersonProfilesMode;
-    /** Enable autocapture */
-    autocapture?: boolean;
+    /**
+     * Enable autocapture for automatic DOM event tracking.
+     * Can be a boolean or an object with detailed configuration.
+     * When true, captures clicks, form submissions, and input changes.
+     */
+    autocapture?: boolean | AutocaptureOptions;
     /**
      * Enable web vitals tracking.
      * Can be a boolean or an object with detailed configuration.
@@ -230,6 +234,48 @@ interface RequestOptions {
     timeout?: number;
     retry?: boolean;
 }
+/**
+ * Autocapture configuration options
+ * Controls automatic DOM event tracking (clicks, form submissions, input changes)
+ */
+interface AutocaptureOptions {
+    /**
+     * Enable autocapture (default: true when autocapture config is present)
+     */
+    enabled?: boolean;
+    /**
+     * URL patterns to allow autocapture on (default: all URLs)
+     * Supports strings (exact match) and RegExp patterns
+     */
+    url_allowlist?: (string | RegExp)[];
+    /**
+     * URL patterns to exclude from autocapture
+     * Supports strings (exact match) and RegExp patterns
+     */
+    url_ignorelist?: (string | RegExp)[];
+    /**
+     * DOM events to capture (default: ['click', 'change', 'submit'])
+     */
+    dom_event_allowlist?: ("click" | "change" | "submit")[];
+    /**
+     * Element tags to capture (default: ['a', 'button', 'form', 'input', 'select', 'textarea', 'label'])
+     */
+    element_allowlist?: string[];
+    /**
+     * CSS selectors to allow for capture (elements matching these are always captured)
+     * Example: ['[data-track]', '.track-click']
+     */
+    css_selector_allowlist?: string[];
+    /**
+     * Element attributes to exclude from capture
+     * Example: ['data-secret', 'aria-label']
+     */
+    element_attribute_ignorelist?: string[];
+    /**
+     * Capture text content from copy/cut events (default: false)
+     */
+    capture_copied_text?: boolean;
+}
 /** Mask options for input elements in session recording */
 interface SessionRecordingMaskInputOptions {
     color?: boolean;
@@ -330,6 +376,8 @@ interface RemoteConfig {
         enabled?: boolean;
         sampleRate?: number;
         minimumDurationMs?: number;
+        /** Full DOM snapshot interval in ms (default 300000 = 5 min). Higher = less data. */
+        fullSnapshotIntervalMs?: number;
         maskAllInputs?: boolean;
         maskAllText?: boolean;
         captureConsole?: boolean;
@@ -359,20 +407,596 @@ interface RemoteConfig {
 }
 
 /**
- * This class is used to capture pageview events when the user navigates using the history API (pushState, replaceState)
- * and when the user navigates using the browser's back/forward buttons.
+ * Session Manager - Handles session_id and window_id
+ *
+ * Uses shared StorageManager for consistent storage operations.
+ *
+ * Session ID: Unique per user session, expires after 30 minutes of inactivity
+ * Window ID: Unique per browser tab, persists across page reloads
+ */
+
+declare class SessionManager {
+    private storage;
+    private _windowId;
+    constructor(storageMethod?: PersistenceMethod, cross_subdomain?: boolean);
+    /**
+     * Get session ID (always returns a value, generates if needed)
+     */
+    getSessionId(): string;
+    /**
+     * Set session ID in storage
+     * Extends TTL if session_id exists, generates new one if not
+     */
+    setSessionId(): string;
+    /**
+     * Reset session ID (generates new session on reset)
+     */
+    resetSessionId(): void;
+    /**
+     * Get session ID from storage (raw, can return null)
+     * Cookie Max-Age handles expiration automatically
+     */
+    private _getSessionIdRaw;
+    /**
+     * Store session ID
+     * Uses plain string format - cookie Max-Age handles expiration
+     */
+    private _storeSessionId;
+    /**
+     * Clear session ID from storage
+     */
+    private _clearSessionId;
+    /**
+     * Get window ID
+     * Window ID is unique per browser tab/window and persists across page reloads
+     * Always returns a window_id (generates one if not set)
+     */
+    getWindowId(): string;
+    /**
+     * Set window ID
+     * Stores in sessionStorage which is unique per tab
+     */
+    private _setWindowId;
+    /**
+     * Initialize window ID
+     * Detects tab duplication and handles window_id persistence
+     */
+    private _initializeWindowId;
+    /**
+     * Listen to window unload to clear primary window flag
+     * This helps distinguish between page reloads and tab duplication
+     */
+    private _listenToUnload;
+    /**
+     * Update storage method at runtime
+     */
+    updateStorageMethod(method: PersistenceMethod, cross_subdomain?: boolean): void;
+}
+
+/**
+ * User Manager - Handles user identity and properties
+ *
+ * Uses shared StorageManager for consistent storage operations.
+ *
+ * Manages:
+ * - anonymous_id: Generated ID for anonymous users
+ * - distinct_id: User-provided ID after identification
+ * - device_id: Persistent device identifier
+ * - user_properties: Custom properties set via identify/setUserProperties
+ * - user_state: "anonymous" or "identified"
+ */
+
+declare class UserManager {
+    private storage;
+    private userIdentity;
+    private _cachedPersonProperties;
+    constructor(storageMethod?: PersistenceMethod, cross_subdomain?: boolean);
+    /**
+     * Get current user identity
+     */
+    getUserIdentity(): UserIdentity;
+    /**
+     * Get current distinct ID (identified user ID)
+     */
+    getDistinctId(): string | null;
+    /**
+     * Get current anonymous ID
+     */
+    getAnonymousId(): string;
+    /**
+     * Get current user properties
+     */
+    getUserProperties(): Record<string, any>;
+    /**
+     * Get the effective ID for event tracking
+     */
+    getEffectiveId(): string;
+    /**
+     * Get current device ID
+     */
+    getDeviceId(): string;
+    /**
+     * Get current user state
+     */
+    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
+     */
+    setUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): boolean;
+    /**
+     * Reset user identity (logout)
+     * Generates new anonymous ID, clears user data, optionally resets device ID
+     */
+    reset(reset_device_id?: boolean): void;
+    /**
+     * Update distinct ID (internal use - for VTilt)
+     */
+    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;
+    /**
+     * Set initial person info
+     */
+    set_initial_person_info(maskPersonalDataProperties?: boolean, customPersonalDataProperties?: string[]): void;
+    /**
+     * Get initial props
+     */
+    get_initial_props(): Record<string, any>;
+    /**
+     * Update referrer info
+     */
+    update_referrer_info(): void;
+    /**
+     * Load user identity from storage.
+     *
+     * For traditional SSR websites where each page navigation reloads JavaScript,
+     * identity MUST be persisted immediately when generated to ensure the same
+     * anonymous_id is used across all page loads.
+     *
+     * Flow:
+     * 1. Load from storage (reads cookies first for critical properties in SSR mode)
+     * 2. Generate new IDs if not found
+     * 3. Immediately persist to storage (saved to both localStorage and cookies)
+     *
+     * With `localStorage+cookie` persistence (default):
+     * - Critical properties are stored in cookies for SSR compatibility
+     * - Full data is stored in localStorage for fast SPA-style access
+     * - Cookies ensure identity persists across full page reloads
+     */
+    private loadUserIdentity;
+    /**
+     * Save user identity to storage
+     */
+    private saveUserIdentity;
+    /**
+     * Get user properties from storage
+     */
+    private getStoredUserProperties;
+    /**
+     * Set user properties in storage
+     */
+    private setStoredUserProperties;
+    /**
+     * 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
+     */
+    updateStorageMethod(method: PersistenceMethod, cross_subdomain?: boolean): void;
+}
+
+/**
+ * Feature Interface & Base Class
+ *
+ * Standard interface that all vTilt features implement.
+ * Provides consistent lifecycle management and self-contained configuration.
+ *
+ * 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
+ *
+ * Based on PostHog's convention patterns, formalized as TypeScript interfaces.
+ */
+
+/**
+ * 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
+ *
+ * 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
+ *
+ * Captures pageview events when the user navigates using the History API
+ * (pushState, replaceState) or browser back/forward buttons.
+ *
+ * Implements the Feature interface for consistent lifecycle management.
+ */
+
+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.
  */
-declare class HistoryAutocapture {
+declare class HistoryAutocapture implements Feature {
+    readonly name = "HistoryAutocapture";
     private _instance;
+    private _config;
+    private _isStarted;
     private _popstateListener;
     private _lastPathname;
-    constructor(instance: VTilt);
+    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;
-    monitorHistoryChanges(): void;
-    private _capturePageview;
+    onConfigUpdate(config: VTiltConfig): void;
+    private _start;
+    private _patchHistoryMethods;
     private _setupPopstateListener;
+    private _capturePageview;
+}
+
+/**
+ * Autocapture Types
+ *
+ * Type definitions for the DOM autocapture feature.
+ * Following PostHog's patterns for element capture and privacy.
+ */
+/**
+ * Autocapture configuration options
+ * Controls what events and elements are captured
+ */
+interface AutocaptureConfig {
+    /**
+     * Enable autocapture (default: true when autocapture config is present)
+     */
+    enabled?: boolean;
+    /**
+     * URL patterns to allow autocapture on (default: all URLs)
+     * Supports strings (exact match) and RegExp patterns
+     */
+    url_allowlist?: (string | RegExp)[];
+    /**
+     * URL patterns to exclude from autocapture
+     * Supports strings (exact match) and RegExp patterns
+     */
+    url_ignorelist?: (string | RegExp)[];
+    /**
+     * DOM events to capture (default: ['click', 'change', 'submit'])
+     */
+    dom_event_allowlist?: AutocaptureEventType[];
+    /**
+     * Element tags to capture (default: ['a', 'button', 'form', 'input', 'select', 'textarea', 'label'])
+     */
+    element_allowlist?: string[];
+    /**
+     * CSS selectors to allow for capture (elements matching these are always captured)
+     * Example: ['[data-track]', '.track-click']
+     */
+    css_selector_allowlist?: string[];
+    /**
+     * Element attributes to exclude from capture
+     * Example: ['data-secret', 'aria-label']
+     */
+    element_attribute_ignorelist?: string[];
+    /**
+     * Capture text content from copy/cut events (default: false)
+     */
+    capture_copied_text?: boolean;
+}
+/**
+ * Supported DOM event types for autocapture
+ */
+type AutocaptureEventType = "click" | "change" | "submit";
+
+/**
+ * Autocapture
+ *
+ * Automatic DOM event capture for clicks, form submissions, and input changes.
+ * Following PostHog's privacy-first approach with element chain tracking.
+ */
+
+/**
+ * Autocapture class for automatic DOM event tracking.
+ * Implements the Feature interface for consistent lifecycle management.
+ */
+declare class Autocapture implements Feature {
+    readonly name = "Autocapture";
+    private _instance;
+    private _config;
+    private _isStarted;
+    private _eventHandlers;
+    constructor(instance: VTilt, config?: AutocaptureConfig);
+    /**
+     * Extract autocapture config from VTiltConfig.
+     * This allows the feature to be self-contained - vtilt.ts doesn't need
+     * to know about autocapture-specific config transformations.
+     */
+    static extractConfig(config: VTiltConfig): AutocaptureConfig;
+    /**
+     * Check if autocapture is enabled
+     */
+    get isEnabled(): boolean;
+    /**
+     * Check if autocapture is currently active
+     */
+    get isStarted(): boolean;
+    /**
+     * Start autocapture if enabled (Feature interface)
+     */
+    startIfEnabled(): void;
+    /**
+     * Stop autocapture (Feature interface)
+     */
+    stop(): void;
+    /**
+     * Handle config updates (Feature interface)
+     */
+    onConfigUpdate(config: VTiltConfig): void;
+    /**
+     * Update autocapture configuration
+     */
+    updateConfig(config: Partial<AutocaptureConfig>): void;
+    /**
+     * Start autocapture
+     */
+    private _start;
+    /**
+     * Add DOM event handlers
+     */
+    private _addEventHandlers;
+    /**
+     * Remove DOM event handlers
+     */
+    private _removeEventHandlers;
+    /**
+     * Create event handler for a specific event type
+     */
+    private _createEventHandler;
+    /**
+     * Capture a DOM event
+     */
+    private _captureEvent;
+    /**
+     * Build properties for an autocapture event
+     */
+    private _buildEventProperties;
+    /**
+     * Add element-specific properties
+     */
+    private _addElementSpecificProps;
+    /**
+     * Add event-specific properties
+     */
+    private _addEventSpecificProps;
 }
 
 /**
@@ -457,7 +1081,7 @@ interface SessionRecordingConfig {
     __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";
+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)
@@ -596,6 +1220,7 @@ interface ChatTheme {
  * The actual recording logic is in LazyLoadedSessionRecording which is
  * loaded on demand.
  *
+ * Implements the ToggleableFeature interface for consistent lifecycle management.
  * Based on PostHog's sessionrecording-wrapper.ts
  */
 
@@ -608,43 +1233,71 @@ type SessionRecordingStatus = "disabled" | "buffering" | "active" | "paused" | "
  * 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 {
+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;
+    /**
+     * Handle remote config updates (Feature interface).
+     */
+    onRemoteConfig(remoteConfig: RemoteConfig): void;
     get started(): boolean;
     get status(): SessionRecordingStatus;
     get sessionId(): string;
     /**
-     * Start recording if enabled, otherwise stop
-     */
-    startIfEnabledOrStop(startReason?: SessionStartReason): void;
-    /**
-     * Stop recording
+     * Alias for stop() for backwards compatibility.
      */
     stopRecording(): void;
     /**
-     * Log a message to the recording
+     * Log a message to the recording.
      */
     log(message: string, level?: "log" | "warn" | "error"): void;
     /**
-     * Update configuration
+     * Update configuration.
      */
     updateConfig(config: Partial<SessionRecordingConfig>): void;
-    private get _isRecordingEnabled();
     private get _scriptName();
     /**
-     * Lazy load the recording script and start
+     * Lazy load the recording script and start.
      */
     private _lazyLoadAndStart;
     /**
-     * Called after the recording script is loaded
+     * Called after the recording script is loaded.
      */
     private _onScriptLoaded;
 }
@@ -664,12 +1317,14 @@ type ConnectionCallback = (connected: boolean) => void;
 /**
  * Unsubscribe function type
  */
-type Unsubscribe = () => void;
+type Unsubscribe$1 = () => void;
 
 /**
  * Chat Wrapper
  *
  * This is the lightweight class that lives in the main bundle.
+ * Implements Feature for consistent lifecycle management.
+ *
  * It handles:
  * - Auto-fetching settings from dashboard (Intercom-like)
  * - Merging server settings with code config
@@ -678,13 +1333,15 @@ type Unsubscribe = () => void;
  * - Delegating to LazyLoadedChat
  * - Queuing messages/callbacks before widget loads
  */
-declare class ChatWrapper {
+declare class ChatWrapper implements Feature {
     private readonly _instance;
+    readonly name = "Chat";
     private _lazyLoadedChat;
     private _config;
     private _serverConfig;
     private _configFetched;
     private _isLoading;
+    private _isStarted;
     private _loadError;
     private _pendingMessages;
     private _pendingCallbacks;
@@ -692,6 +1349,34 @@ declare class ChatWrapper {
     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;
+    get isEnabled(): boolean;
+    get isStarted(): boolean;
+    /**
+     * Start chat if enabled (Feature interface).
+     * This is async because it may fetch server settings.
+     */
+    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
      */
@@ -767,23 +1452,15 @@ declare class ChatWrapper {
     /**
      * Subscribe to new messages
      */
-    onMessage(callback: MessageCallback): Unsubscribe;
+    onMessage(callback: MessageCallback): Unsubscribe$1;
     /**
      * Subscribe to typing indicators
      */
-    onTyping(callback: TypingCallback): Unsubscribe;
+    onTyping(callback: TypingCallback): Unsubscribe$1;
     /**
      * Subscribe to connection changes
      */
-    onConnectionChange(callback: ConnectionCallback): Unsubscribe;
-    /**
-     * Start chat if enabled, called by VTilt after init
-     *
-     * This method supports two modes (Intercom-like):
-     * 1. Auto-config: Fetch settings from /api/chat/settings (default)
-     * 2. Code-only: Use only code config (autoConfig: false)
-     */
-    startIfEnabled(): Promise<void>;
+    onConnectionChange(callback: ConnectionCallback): Unsubscribe$1;
     /**
      * Update configuration
      */
@@ -796,7 +1473,6 @@ declare class ChatWrapper {
      * Destroy the chat widget
      */
     destroy(): void;
-    private get _isChatEnabled();
     /**
      * Fetch chat settings from the server
      * This enables "snippet-only" installation where widget configures from dashboard
@@ -846,334 +1522,215 @@ interface QueuedRequest {
     transport?: "xhr" | "sendBeacon";
 }
 
-declare class VTilt {
-    readonly version = "1.9.0";
-    private configManager;
-    private sessionManager;
-    private userManager;
-    private webVitalsManager;
-    private requestQueue;
-    private retryQueue;
-    private rateLimiter;
-    historyAutocapture?: HistoryAutocapture;
-    sessionRecording?: SessionRecordingWrapper;
-    chat?: ChatWrapper;
-    __loaded: boolean;
-    private _initial_pageview_captured;
-    private _visibility_state_listener;
-    __request_queue: QueuedRequest[];
-    private _has_warned_about_config;
-    private _set_once_properties_sent;
-    private _remoteConfig;
-    /** Person UUID from vt= URL param (manual person tracking link); sent as $vt until backend links distinct_id */
-    private _vt_person_uuid;
-    constructor(config?: Partial<VTiltConfig>);
-    /**
-     * Initializes a new instance of the VTilt tracking object.
-     *
-     * @remarks
-     * All new instances are added to the main vt object as sub properties (such as
-     * `vt.library_name`) and also returned by this function.
-     *
-     * @example
-     * ```js
-     * // basic initialization
-     * vt.init('<project_id>', {
-     *     api_host: '<client_api_host>'
-     * })
-     * ```
-     *
-     * @example
-     * ```js
-     * // multiple instances
-     * vt.init('<project_id>', {}, 'project1')
-     * vt.init('<project_id>', {}, 'project2')
-     * ```
-     *
-     * @public
-     *
-     * @param projectId - Your VTilt project ID
-     * @param config - A dictionary of config options to override
-     * @param name - The name for the new VTilt instance that you want created
+interface RateLimitBucket {
+    tokens: number;
+    last: number;
+}
+interface RateLimiterConfig {
+    eventsPerSecond?: number;
+    eventsBurstLimit?: number;
+    persistence?: {
+        get: (key: string) => RateLimitBucket | null;
+        set: (key: string, value: RateLimitBucket) => void;
+    };
+    captureWarning?: (message: string) => void;
+}
+declare class RateLimiter {
+    private eventsPerSecond;
+    private eventsBurstLimit;
+    private lastEventRateLimited;
+    private persistence?;
+    private captureWarning?;
+    constructor(config?: RateLimiterConfig);
+    /**
+     * Check if the client should be rate limited
      *
-     * @returns The newly initialized VTilt instance
+     * @param checkOnly - If true, don't consume a token (just check)
+     * @returns Object with isRateLimited flag and remaining tokens
      */
-    init(projectId: string, config?: Partial<VTiltConfig>, name?: string): VTilt;
-    /**
-     * Handles the actual initialization logic for a VTilt instance.
-     * This internal method should only be called by `init()`.
-     */
-    private _init;
-    /**
-     * Start the request queue if user hasn't opted out
-     * Following PostHog's pattern - called from both _init() and _dom_loaded()
-     * Safe to call multiple times as enable() is idempotent
-     */
-    private _start_queue_if_opted_in;
-    /**
-     * Set up handler to flush event queue on page unload
-     * Uses both beforeunload and pagehide for maximum compatibility
-     */
-    private _setup_unload_handler;
-    /**
-     * Read vt=person_uuid from current URL (tracking link for manually created persons).
-     * Stores the value for inclusion in event payload as $vt; removes param from URL via replaceState.
-     */
-    private _read_vt_param_from_url;
-    /**
-     * Load remote config from cache and fetch fresh in background.
-     * Uses sessionStorage for per-session caching.
-     * Local config always overrides remote config.
-     */
-    private _loadRemoteConfig;
+    checkRateLimit(checkOnly?: boolean): {
+        isRateLimited: boolean;
+        remainingTokens: number;
+    };
     /**
-     * Fetch remote config from /decide endpoint.
-     * Caches response in localStorage for persistence across sessions.
+     * Check if an event should be allowed (consumes a token if allowed)
      */
-    private _fetchRemoteConfig;
+    shouldAllowEvent(): boolean;
     /**
-     * Apply remote config to current config.
-     * Local config takes precedence over remote.
-     * Also triggers feature initialization if settings changed after init.
+     * Get remaining tokens without consuming
      */
-    private _applyRemoteConfig;
+    getRemainingTokens(): number;
+}
+
+/**
+ * Simple Event Emitter
+ *
+ * Lightweight pub/sub system for internal feature communication.
+ * Following PostHog's SimpleEventEmitter pattern.
+ */
+/**
+ * Event listener function type
+ */
+type EventListener<T = unknown> = (payload: T) => void;
+/**
+ * Unsubscribe function returned by on()
+ */
+type Unsubscribe = () => void;
+/**
+ * Simple event emitter for internal SDK communication.
+ * Features can emit and listen to events without direct coupling.
+ *
+ * @example
+ * ```typescript
+ * const emitter = new SimpleEventEmitter();
+ *
+ * // Subscribe to events
+ * const unsubscribe = emitter.on('user:identified', (data) => {
+ *   console.log('User identified:', data);
+ * });
+ *
+ * // Emit events
+ * emitter.emit('user:identified', { userId: '123' });
+ *
+ * // Unsubscribe when done
+ * unsubscribe();
+ * ```
+ */
+declare class SimpleEventEmitter {
+    private _events;
+    private _onceEvents;
     /**
-     * Returns a string representation of the instance name
-     * Used for debugging and logging
+     * Subscribe to an event.
      *
-     * @internal
+     * @param event - Event name to subscribe to
+     * @param listener - Callback function
+     * @returns Unsubscribe function
      */
-    toString(): string;
-    /**
-     * Get current domain from location
-     * Returns full URL format for consistency with dashboard
-     */
-    private getCurrentDomain;
-    /**
-     * Check if tracking is properly configured
-     * Returns true if projectId and token are present, false otherwise
-     * Logs a warning only once per instance if not configured
-     */
-    private _is_configured;
-    /**
-     * Build the tracking URL with token in query parameters
-     */
-    private buildUrl;
+    on<T = unknown>(event: string, listener: EventListener<T>): Unsubscribe;
     /**
-     * Send HTTP request
-     * This is the central entry point for all tracking requests
-     * Events are batched and sent every 3 seconds for better performance
-     */
-    private sendRequest;
-    /**
-     * Send a batched request with multiple events
-     * Called by RequestQueue when flushing
-     * Uses RetryQueue for automatic retry on failure
+     * Subscribe to an event once (auto-unsubscribes after first call).
+     *
+     * @param event - Event name to subscribe to
+     * @param listener - Callback function
+     * @returns Unsubscribe function
      */
-    private _send_batched_request;
+    once<T = unknown>(event: string, listener: EventListener<T>): Unsubscribe;
     /**
-     * Send HTTP request and return status code
-     * Uses GZip compression for payloads > 1KB
-     * Used by RetryQueue for retryable requests
+     * Emit an event to all listeners.
+     *
+     * @param event - Event name to emit
+     * @param payload - Data to pass to listeners
      */
-    private _send_http_request;
+    emit<T = unknown>(event: string, payload?: T): void;
     /**
-     * Send request using sendBeacon for reliable delivery on page unload
-     * Uses GZip compression for payloads > 1KB
+     * Remove all listeners for an event.
+     *
+     * @param event - Event name (or undefined to remove all)
      */
-    private _send_beacon_request;
+    off(event?: string): void;
     /**
-     * Send a queued request (called after DOM is loaded)
+     * Get the number of listeners for an event.
+     *
+     * @param event - Event name
+     * @returns Number of listeners
      */
-    _send_retriable_request(item: QueuedRequest): void;
+    listenerCount(event: string): number;
     /**
-     * Capture an event
-     * Automatically adds common properties to all events
-     * ($current_url, $host, $pathname, $referrer, $referring_domain, $browser, $os, $device, $timezone, etc.)
-     * Only properties in EVENT_TO_PERSON_PROPERTIES are copied to person properties
-     * Also adds title property for $pageview events only
+     * Check if there are any listeners for an event.
      *
-     * @param name - Event name
-     * @param payload - Event payload
-     * @param options - Optional capture options
+     * @param event - Event name
+     * @returns True if there are listeners
      */
+    hasListeners(event: string): boolean;
+}
+
+/**
+ * VTilt SDK - Main Entry Point
+ *
+ * Privacy-first analytics SDK with modular architecture.
+ * This file is a thin orchestrator that delegates to specialized managers:
+ *
+ * - ConfigManager: Configuration management
+ * - SessionManager: Session and window ID management
+ * - UserManager: User identity and properties
+ * - CaptureManager: Event capture and payload enrichment
+ * - IdentityManager: High-level identity operations
+ * - RemoteConfigManager: Remote configuration from /decide
+ * - FeatureManager: Feature lifecycle management
+ *
+ * @see docs/tracker/README.md for full documentation
+ */
+
+declare class VTilt {
+    readonly version = "1.10.0";
+    __loaded: boolean;
+    __request_queue: QueuedRequest[];
+    historyAutocapture?: HistoryAutocapture;
+    autocapture?: Autocapture;
+    sessionRecording?: SessionRecordingWrapper;
+    chat?: ChatWrapper;
+    webVitals?: WebVitalsManager;
+    private configManager;
+    sessionManager: SessionManager;
+    userManager: UserManager;
+    private _captureManager;
+    private _identityManager;
+    private _remoteConfigManager;
+    private _featureManager;
+    private requestQueue;
+    private retryQueue;
+    rateLimiter: RateLimiter;
+    _emitter: SimpleEventEmitter;
+    private _has_warned_about_config;
+    constructor(config?: Partial<VTiltConfig>);
+    init(projectId: string, config?: Partial<VTiltConfig>, name?: string): VTilt;
+    private _init;
+    private _initFeatures;
+    private _initHistoryAutocapture;
+    private _initAutocapture;
+    private _initWebVitals;
+    _initSessionRecording(): void;
+    _initChat(): void;
+    startAutocapture(): void;
+    stopAutocapture(): void;
+    isAutocaptureActive(): boolean;
+    startSessionRecording(): void;
+    stopSessionRecording(): void;
+    isRecordingActive(): boolean;
+    getSessionRecordingId(): string | null;
     capture(name: string, payload: EventPayload, options?: {
         skip_client_rate_limiting?: boolean;
     }): void;
-    /**
-     * Internal capture method that bypasses rate limiting
-     * Used for system events like rate limit warnings
-     */
-    private _capture_internal;
-    /**
-     * Track a custom event (alias for capture)
-     */
     trackEvent(name: string, payload?: EventPayload): void;
-    /**
-     * Identify a user with property operations
-     * Sends $identify event when transitioning from anonymous to identified
-     * Event's distinct_id is the previous/anonymous ID, new distinct_id is in payload
-     *
-     * @example
-     * ```js
-     * // Basic identify with properties
-     * vTilt.identify('user_123',
-     *   { name: 'John Doe', email: 'john@example.com' },  // $set properties
-     *   { first_login: new Date().toISOString() }         // $set_once properties
-     * )
-     * ```
-     *
-     * @example
-     * ```js
-     * // If no $set is provided, all properties are treated as $set
-     * vTilt.identify('user_123', { name: 'John Doe', email: 'john@example.com' })
-     * ```
-     */
     identify(newDistinctId?: string, userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
-    /**
-     * Set user properties
-     * Sets properties on the person profile associated with the current distinct_id
-     *
-     * @example
-     * ```js
-     * // Set properties that can be updated
-     * vTilt.setUserProperties({ name: 'John Doe', email: 'john@example.com' })
-     * ```
-     *
-     * @example
-     * ```js
-     * // Set properties with $set and $set_once operations
-     * vTilt.setUserProperties(
-     *   { name: 'John Doe', last_login: new Date().toISOString() },  // $set properties
-     *   { first_login: new Date().toISOString() }                     // $set_once properties
-     * )
-     * ```
-     *
-     * @param userPropertiesToSet Optional: Properties to set (can be updated)
-     * @param userPropertiesToSetOnce Optional: Properties to set once (preserves first value)
-     */
     setUserProperties(userPropertiesToSet?: Record<string, any>, userPropertiesToSetOnce?: Record<string, any>): void;
-    /**
-     * Reset user identity (logout)
-     * Clears all user data, generates new anonymous ID, resets session
-     *
-     * @param reset_device_id - If true, also resets device_id. Default: false
-     *
-     * @example
-     * // Reset on user logout
-     * vtilt.resetUser()
-     *
-     * @example
-     * // Reset and generate new device ID
-     * vtilt.resetUser(true)
-     */
     resetUser(reset_device_id?: boolean): void;
-    /**
-     * Get current user identity
-     */
-    getUserIdentity(): UserIdentity;
-    /**
-     * Get current device ID
-     */
+    createAlias(alias: string, original?: string): void;
+    getUserIdentity(): Record<string, any>;
     getDeviceId(): string;
-    /**
-     * Get current user state
-     */
     getUserState(): "anonymous" | "identified";
-    /**
-     * Create an alias to link two distinct IDs
-     * Links anonymous session to account on signup
-     *
-     * @param alias - A unique identifier that you want to use for this user in the future
-     * @param original - The current identifier being used for this user (optional, defaults to current distinct_id)
-     *
-     * @example
-     * // Link anonymous user to account on signup
-     * vtilt.createAlias('user_12345')
-     *
-     * @example
-     * // Explicit alias with original ID
-     * vtilt.createAlias('user_12345', 'anonymous_abc123')
-     */
-    createAlias(alias: string, original?: string): void;
-    /**
-     * Capture initial pageview with visibility check
-     * Note: The capture_pageview config check happens at the call site (in _init)
-     */
-    private _capture_initial_pageview;
-    /**
-     * Get current configuration
-     */
     getConfig(): VTiltConfig;
-    /**
-     * Get current session ID
-     */
     getSessionId(): string | null;
-    /**
-     * Get current distinct ID
-     */
     getDistinctId(): string;
-    /**
-     * Get anonymous ID
-     */
     getAnonymousId(): string;
-    /**
-     * Update configuration
-     */
+    toString(): string;
     updateConfig(config: Partial<VTiltConfig>): void;
-    /**
-     * Initialize session recording
-     */
-    private _initSessionRecording;
-    /**
-     * Build session recording config from VTiltConfig
-     */
-    private _buildSessionRecordingConfig;
-    /**
-     * Start session recording
-     * Call this to manually start recording if it wasn't enabled initially
-     */
-    startSessionRecording(): void;
-    /**
-     * Stop session recording
-     */
-    stopSessionRecording(): void;
-    /**
-     * Check if session recording is active
-     */
-    isRecordingActive(): boolean;
-    /**
-     * Get session recording ID
-     */
-    getSessionRecordingId(): string | null;
-    /**
-     * Initialize chat widget
-     */
-    private _initChat;
-    /**
-     * Build chat config from VTiltConfig
-     */
-    private _buildChatConfig;
-    /**
-     * _execute_array() deals with processing any vTilt function
-     * calls that were called before the vTilt library was loaded
-     * (and are thus stored in an array so they can be called later)
-     *
-     * Note: we fire off all the vTilt function calls BEFORE we fire off
-     * tracking calls. This is so identify/setUserProperties/updateConfig calls
-     * can properly modify early tracking calls.
-     *
-     * @param {Array} array Array of queued calls in format [methodName, ...args]
-     */
+    private _notifyFeaturesOfConfigUpdate;
+    buildUrl(): string;
+    sendRequest(url: string, event: TrackingEvent, shouldEnqueue?: boolean): void;
+    private _is_configured;
+    private _send_batched_request;
+    private _send_http_request;
+    private _send_beacon_request;
+    _send_retriable_request(item: QueuedRequest): void;
+    private _setup_unload_handler;
+    private _start_queue_if_opted_in;
+    private _read_vt_param_from_url;
     _execute_array(array: any[]): void;
-    /**
-     * Called when DOM is loaded - processes queued requests and enables batching
-     * Following PostHog's pattern in _dom_loaded()
-     */
     _dom_loaded(): void;
 }
 
 declare const vt: VTilt;
 
 export { ALL_WEB_VITALS_METRICS, DEFAULT_WEB_VITALS_METRICS, VTilt, vt as default, vt };
-export type { AliasEvent, 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 { 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 };