@v-tilt/browser 1.11.0 → 1.13.0

package/dist/autocapture-types.d.ts

@@ -102,6 +102,23 @@ export interface AutocaptureConfig {
      * @default false
      */
     capture_element_values?: boolean;
+    /**
+     * Scroll depth autocapture — two independently opt-in modes (both default off).
+     */
+    scroll_depth?: ScrollDepthConfig;
+}
+/**
+ * Scroll depth autocapture configuration.
+ */
+export interface ScrollDepthConfig {
+    /** Fire `$scroll_depth` when the user crosses depth thresholds while scrolling. */
+    milestones?: boolean | {
+        thresholds?: number[];
+    };
+    /** Add max scroll depth to `$pageleave` as `$prev_pageview_scroll_depth_pct`. */
+    pageleave?: boolean;
+    /** CSS selector(s) for the scroll container; falls back to `window`. */
+    scroll_root_selector?: string | string[];
 }
 /**
  * Properties extracted from a DOM element

package/dist/autocapture-utils.d.ts

@@ -33,6 +33,10 @@ export declare function getDirectAndNestedSpanText(target: Element): string;
 export declare function getEventTarget(e: Event): Element | null;
 export declare function previousElementSibling(el: Element): Element | null;
 export declare function getParentElement(curEl: Element): Element | false;
+/**
+ * Whether the current page URL passes autocapture url allow/ignore lists.
+ */
+export declare function isAutocaptureUrlAllowed(autocaptureConfig: AutocaptureConfig | undefined): boolean;
 /**
  * Check whether a string value should be captured or if it may contain sensitive data
  */
@@ -76,7 +80,26 @@ export interface InputValueResult {
  */
 export declare function getInputValue(el: Element): InputValueResult | null;
 /**
- * Check whether a DOM event should be "captured" or if it may contain sensitive data
+ * Why a DOM event was rejected by `shouldCaptureDomEvent`. Surfaced through
+ * the rich variant `evaluateDomEventCapture` so the caller can produce a
+ * useful debug log instead of a silent skip.
+ */
+export type DomEventRejectReason = "no_window" | "no_element" | "html_element" | "url_allowlist_miss" | "url_ignorelist_hit" | "dom_event_not_allowed" | "element_allowlist_miss" | "css_selector_allowlist_miss" | "css_selector_ignorelist_hit" | "tag_html" | "form_event_not_allowed" | "input_event_not_allowed" | "tag_not_capturable";
+export interface DomEventEvaluation {
+    /** True when the event passes every filter and should be captured. */
+    capture: boolean;
+    /** Why we rejected the event. Undefined when `capture` is true. */
+    reason?: DomEventRejectReason;
+}
+/**
+ * Rich variant of {@link shouldCaptureDomEvent} that also returns the
+ * rejection reason. Use this from places that want to debug-log why an
+ * event was skipped (e.g. the Autocapture trace log).
+ */
+export declare function evaluateDomEventCapture(el: Element, event: Event, autocaptureConfig?: AutocaptureConfig | undefined, captureOnAnyElement?: boolean, allowedEventTypes?: string[]): DomEventEvaluation;
+/**
+ * Boolean wrapper around {@link evaluateDomEventCapture} kept for any
+ * callers that don't need the rejection reason.
  */
 export declare function shouldCaptureDomEvent(el: Element, event: Event, autocaptureConfig?: AutocaptureConfig | undefined, captureOnAnyElement?: boolean, allowedEventTypes?: string[]): boolean;
 export declare function getPropertiesFromElement(elem: Element, maskAllAttributes: boolean, maskText: boolean, elementAttributeIgnorelist: string[] | undefined): Properties;

package/dist/autocapture.d.ts

@@ -3,10 +3,49 @@
  *
  * Automatic DOM event capture for clicks, form submissions, and input changes.
  * Privacy-first approach with element chain tracking and sensitive data filtering.
+ *
+ * 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`.
+ *
+ * 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
  */
 import type { VTilt } from "./vtilt";
-import type { VTiltConfig, RemoteConfig } from "./types";
+import type { VTiltConfig } from "./types";
 import type { Feature } from "./feature";
+/**
+ * Reasons isEnabled may evaluate to false. Surfaced by getDiagnostics() so that
+ * integrators can pinpoint why no `$autocapture` events are flowing.
+ */
+export type AutocaptureDisabledReason = "user_stop_called" | "server_opt_out" | "config_autocapture_false" | "config_autocapture_undefined";
+export 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 class for automatic DOM event tracking.
  * Implements the Feature interface for consistent lifecycle management.
@@ -16,26 +55,76 @@ export 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 _removeDomEventHandlers;
+    /**
+     * Scroll depth listener — opt-in via `autocapture.scroll_depth` milestones and/or pageleave.
+     */
+    private _syncScrollDepthHandler;
+    private _teardownScrollDepth;
+    /**
+     * 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.
+     */
+    private _syncCopyHandler;
     private _captureEvent;
     private _isBrowserSupported;
 }