@v-tilt/browser 1.11.0 → 1.13.0

package/dist/extensions/google-tag-gateway/enhanced-conversions.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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', { ... })`.
+ */
+export 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;
+}
+export interface HashedUserAddress {
+    sha256_first_name?: string;
+    sha256_last_name?: string;
+    sha256_street?: string;
+    city?: string;
+    region?: string;
+    postal_code?: string;
+    country?: string;
+}
+export interface HashedUserData {
+    sha256_email_address?: string;
+    sha256_phone_number?: string;
+    address?: HashedUserAddress;
+}
+export declare function buildHashedUserData(raw: RawUserData): Promise<HashedUserData | null>;

package/dist/extensions/google-tag-gateway/event-bridge.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Automatic event bridge from `vt.capture()` into `gtag('event', ...)`.
+ *
+ * Two layers run in order on every captured event:
+ *
+ * 1. **GA4 forwarder** (`forwardToGtag`) — applies the admin's
+ *    `event_filter`, then an explicit `event_mappings` row, then a built-in
+ *    preset (e.g. `$pageview` → `page_view`), then the `autoForward`
+ *    default-on fallback. Fires `gtag('event', mapped_name, params)` on
+ *    success. This is the primary path: because most customers link GA4 to
+ *    Google Ads, the GA4 event flows to Ads automatically when marked as a
+ *    conversion.
+ * 2. **Ads-only conversions** (`forwardEvent`) — for customers who
+ *    configured direct Ads conversion mappings on the destination. Fires
+ *    `gtag('event', 'conversion', {send_to: 'AW-.../...'})`. Unchanged by
+ *    design so existing deployments keep working.
+ *
+ * Matching on both layers is by exact event name. vTilt's own internal
+ * events (`$identify`, `$set`, etc.) are skipped unless the admin wired
+ * them up explicitly.
+ */
+import type { GoogleAdsConversionMapping, GoogleTagClientConfig } from "../../types";
+import type { GtagFn } from "./consent-bridge";
+export interface ConversionBuildOptions {
+    mapping: GoogleAdsConversionMapping;
+    payload: Record<string, unknown>;
+}
+export interface BuiltConversion {
+    send_to: string;
+    params: Record<string, unknown>;
+}
+export declare function buildConversionParams({ mapping, payload, }: ConversionBuildOptions): BuiltConversion;
+/**
+ * Bridge a single captured event to gtag using the Ads conversion mappings
+ * that match `eventName`. Each matching mapping results in one
+ * `gtag('event', 'conversion', ...)` call.
+ */
+export declare function forwardEvent(gtag: GtagFn, eventName: string, payload: Record<string, unknown>, config: GoogleTagClientConfig): BuiltConversion[];
+/**
+ * Check whether a captured event name is allowed by the admin's
+ * `event_filter`. `exclude` wins over `include`; an empty/missing
+ * `include` means "all events pass". Mirrors the server-side filter
+ * semantics exactly.
+ */
+export declare function isEventAllowed(eventName: string, filter: GoogleTagClientConfig["eventFilter"]): boolean;
+export interface ForwardToGtagResult {
+    /** `true` when a `gtag('event', ...)` call was made. */
+    fired: boolean;
+    /** The event name that was forwarded (post-mapping/preset), if fired. */
+    eventName?: string;
+    /** The params object that was passed to gtag, if fired. */
+    params?: Record<string, unknown>;
+    /** Which rule produced the forward. */
+    source?: "mapping" | "preset" | "auto";
+}
+/**
+ * Forward one captured event to gtag as a GA4 event. Resolution order:
+ *
+ * 1. Filter — `event_filter.exclude` drops, then `event_filter.include`
+ *    (when non-empty) whitelists. Same as the server-side filter.
+ * 2. Explicit mapping — an `event_mappings` row with matching `source`
+ *    wins and always fires, regardless of `autoForward`. This is the
+ *    admin's "force fire" path.
+ * 3. Built-in preset — when no explicit mapping is set and
+ *    `autoForward !== false`, `$pageview`/`$pageleave` fire their GA4
+ *    analogues with sensibly-named params.
+ * 4. Auto-forward fallback — when `autoForward !== false` and the event
+ *    is not a `$*` internal event, fire `gtag('event', eventName, payload)`
+ *    with reserved/internal keys stripped.
+ *
+ * Admins who want a strict allowlist set `autoForward: false` and use
+ * `event_mappings` to enumerate the events they care about.
+ */
+export declare function forwardToGtag(gtag: GtagFn, eventName: string, payload: Record<string, unknown>, config: GoogleTagClientConfig): ForwardToGtagResult;

package/dist/extensions/google-tag-gateway/google-tag-gateway.d.ts

@@ -0,0 +1,95 @@
+/**
+ * GoogleTagGateway feature.
+ *
+ * Orchestrates the client-side half of the Google Tag Gateway destination:
+ *
+ * 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.
+ *
+ * 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.
+ */
+import type { VTilt } from "../../vtilt";
+import type { VTiltConfig, GoogleTagClientConfig } from "../../types";
+import type { Feature, FeatureConfig } from "../../feature";
+import { type GtagFn } from "./consent-bridge";
+import { type GtagCall } from "./public-api";
+import { type RawUserData } from "./enhanced-conversions";
+export interface GoogleTagGatewayFeatureConfig extends FeatureConfig {
+    remote?: GoogleTagClientConfig;
+}
+export interface DeliveryLogEntry {
+    ts: number;
+    tag_ids: string[];
+    event_name: string;
+    send_to: string;
+    status: "fired" | "dropped";
+    reason?: string;
+}
+export declare class GoogleTagGateway implements Feature {
+    readonly name = "GoogleTagGateway";
+    private _instance;
+    private _config;
+    private _isStarted;
+    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;
+    /** Exposed for tests and the public `vt.gtag` binding. */
+    get gtag(): GtagFn;
+    get deliveryLog(): DeliveryLogEntry[];
+    startIfEnabled(): void;
+    stop(): void;
+    onConfigUpdate(config: VTiltConfig): void;
+    /**
+     * 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.
+     */
+    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;
+}

package/dist/extensions/google-tag-gateway/gtag-loader.d.ts

@@ -0,0 +1,85 @@
+/**
+ * gtag.js loader.
+ *
+ * Loads `gtag/js?id=<primary>` from the vTilt gateway (`/gt`) so that every
+ * subsequent measurement request — `gtag/js`, `/g/collect`, and
+ * `/pagead/conversion` — stays on the first-party origin. Installs the
+ * standard `window.dataLayer` queue and `window.gtag` shim exactly the way
+ * Google's official snippet does, so any third-party integration that
+ * expects them (Ads editor, Tag Assistant, CMP libraries) keeps working.
+ */
+import type { GoogleTagClientConfig } from "../../types";
+import type { GtagFn } from "./consent-bridge";
+export interface GtagLoaderOptions {
+    /** Origin to load gtag.js from. Must include protocol. */
+    origin: string;
+    /** Path under `origin` that hosts the gateway. Defaults to `/gt`. */
+    gatewayPath: string;
+    /** Primary tag id used in the loader URL (first `G-*`, else first id). */
+    primaryTagId: string;
+    /** All tag ids to `gtag('config', id, ...)` after load. */
+    tagIds: string[];
+    /** Extra per-tag config. Currently only used to set `server_container_url`. */
+    configParams?: Record<string, unknown>;
+    /** Whether gtag.js should send its own `page_view` when configured. */
+    sendPageView?: boolean;
+    /** Enable `debug_mode` on gtag configs. */
+    debugMode?: boolean;
+    /** Enable `conversion_linker` (default true in gtag.js). */
+    conversionLinker?: boolean;
+    /** Domains for the `linker` feature (cross-domain). */
+    linkerDomains?: string[];
+}
+export interface LoadedGtag {
+    gtag: GtagFn;
+    dataLayer: unknown[];
+}
+/**
+ * Ensure a single `window.dataLayer` + `window.gtag` pair exists. Safe to
+ * call multiple times — returns the same references. Matches Google's
+ * reference snippet:
+ *
+ *   window.dataLayer = window.dataLayer || [];
+ *   function gtag(){ dataLayer.push(arguments); }
+ */
+export declare function ensureDataLayer(): LoadedGtag;
+/**
+ * Inject the gtag.js <script> tag pointed at the vTilt gateway. The loader
+ * script is fire-and-forget; the dataLayer/gtag shim queues any calls we
+ * make before the script finishes.
+ */
+export declare function loadGtagScript(options: GtagLoaderOptions, onLoaded?: () => void, onError?: (err: Error) => void): HTMLScriptElement | null;
+/**
+ * Initialize gtag (`'js'` + per-id `'config'`) and — if provided — seed
+ * conversion linker and cross-domain `linker` params. This runs through
+ * the dataLayer shim, so calls made before `gtag.js` finishes loading are
+ * replayed automatically once the script boots.
+ */
+export declare function installGtagConfigs(gtag: GtagFn, options: GtagLoaderOptions): void;
+/**
+ * Derive loader options from the server-provided feature config.
+ *
+ * There are exactly two proxy resolutions:
+ *
+ * | proxyMode  | base                                              | path  |
+ * | ---------- | ------------------------------------------------- | ----- |
+ * | `proxied`  | `api_host` verbatim (or `location.origin`)        | `/gt` |
+ * | `direct`   | `https://www.googletagmanager.com`                | `""`  |
+ *
+ * In proxied mode `api_host` is treated as a verbatim URL prefix — matching
+ * how the rest of the SDK builds URLs (`capture`, array loader, chat). It
+ * may be any of:
+ *
+ *   - a full URL with a path, e.g. `https://proxy.example.com/v1`
+ *   - a bare origin, e.g. `https://proxy.example.com`
+ *   - a relative path, e.g. `/vt` (first-party reverse proxy)
+ *
+ * For `transport_url` we still need an absolute URL, so a relative
+ * `api_host` is expanded against `window.location.origin` in that one
+ * place. The loader `<script>` `src` itself keeps the original relative
+ * form and is resolved by the browser against the document.
+ *
+ * Customers who self-host a proxy simply point `api_host` at it — the
+ * proxy must implement `/gt/*` under that prefix.
+ */
+export declare function buildLoaderOptions(config: GoogleTagClientConfig, apiHost: string | undefined): GtagLoaderOptions | null;

package/dist/extensions/google-tag-gateway/index.d.ts

@@ -0,0 +1,7 @@
+export { GoogleTagGateway, type GoogleTagGatewayFeatureConfig, type DeliveryLogEntry, } from "./google-tag-gateway";
+export { createPublicGtagApi, type PublicGtagApi } from "./public-api";
+export { forwardEvent, buildConversionParams } from "./event-bridge";
+export { ensureDataLayer, loadGtagScript, installGtagConfigs, buildLoaderOptions, type GtagLoaderOptions, } from "./gtag-loader";
+export { pushConsentDefault, pushConsentUpdate, buildConsentPayload, type GtagFn, type GoogleConsentPayload, } from "./consent-bridge";
+export { buildHashedUserData, type HashedUserData, type HashedUserAddress, type RawUserData, } from "./enhanced-conversions";
+export { normalizeEmail, normalizePhone, normalizeBasic, normalizePostalCode, getByPath, coerceNumber, coerceString, } from "./normalize";

package/dist/extensions/google-tag-gateway/normalize.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Google-specific normalization for Enhanced Conversions.
+ *
+ * Follows the rules documented in
+ * https://support.google.com/google-ads/answer/13262500 — phone numbers must be
+ * in E.164 format, emails lowercased with provider-specific dot stripping on
+ * gmail/googlemail, and names/addresses normalized to lowercase without
+ * leading/trailing whitespace.
+ */
+export declare function normalizeEmail(raw: string | null | undefined): string | null;
+/**
+ * Normalize a phone number to E.164. If the input has no leading '+' we
+ * cannot reliably infer the country code, so we return null rather than
+ * send an unhashable/ambiguous value — Enhanced Conversions treats missing
+ * fields as acceptable.
+ */
+export declare function normalizePhone(raw: string | null | undefined): string | null;
+export declare function normalizeBasic(raw: string | null | undefined): string | null;
+/** Postal codes: collapse whitespace, uppercase (some ISO formats are alpha). */
+export declare function normalizePostalCode(raw: string | null | undefined): string | null;
+/**
+ * Read a nested path from an object using dot notation. Used by the
+ * event-bridge to extract `value`/`currency`/`transaction_id` from the
+ * captured event payload based on the admin-configured path.
+ */
+export declare function getByPath(source: unknown, path: string | null | undefined): unknown;
+export declare function coerceNumber(value: unknown): number | undefined;
+export declare function coerceString(value: unknown): string | undefined;

package/dist/extensions/google-tag-gateway/public-api.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `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.
+ */
+import type { GtagFn } from "./consent-bridge";
+export type GtagCall = unknown[];
+export interface PublicGtagApi {
+    /** The flat function exposed as `vt.gtag(...)` */
+    call: GtagFn;
+    /** Flush queued calls to a now-ready gtag implementation. */
+    flush(target: GtagFn): void;
+    /** Observability: recent calls sent through this API (ring buffer). */
+    getRecentCalls(): GtagCall[];
+}
+export declare function createPublicGtagApi(): PublicGtagApi;

package/dist/extensions/history-autocapture.d.ts

@@ -10,8 +10,6 @@ import type { VTilt } from "../vtilt";
 import type { VTiltConfig } from "../types";
 import type { Feature, FeatureConfig } from "../feature";
 export interface HistoryAutocaptureConfig extends FeatureConfig {
-    /** Whether to capture pageviews on history changes */
-    enabled?: boolean;
 }
 /**
  * History Autocapture Feature
@@ -39,6 +37,8 @@ export declare class HistoryAutocapture implements Feature {
     onConfigUpdate(config: VTiltConfig): void;
     private _start;
     private _patchHistoryMethods;
+    /** $pageleave must run while the current URL still reflects the page being left. */
+    private _emitPageleaveIfPathWillChange;
     private _setupPopstateListener;
     private _capturePageview;
 }

package/dist/extensions/replay/index.d.ts

@@ -10,4 +10,4 @@
 export { SessionRecordingWrapper, LAZY_LOADING, type SessionRecordingStatus, type LazyLoadedSessionRecordingInterface, } from "./session-recording-wrapper";
 export { LazyLoadedSessionRecording } from "./session-recording";
 export type { SessionRecordingConfig, SessionStartReason, RecordOptions, RRWebRecord, SnapshotBuffer, CanvasRecordingConfig, NetworkPayloadCaptureConfig, MaskingConfig, TriggerType, } from "./types";
-export { compressEvent, estimateSize, truncateLargeConsoleLogs, splitBuffer, isSessionIdleEvent, isRecordingPausedEvent, isInteractiveEvent, RECORDING_MAX_EVENT_SIZE, RECORDING_BUFFER_TIMEOUT, RECORDING_IDLE_THRESHOLD_MS, } from "./session-recording-utils";
+export { estimateSize, truncateLargeConsoleLogs, splitBuffer, isSessionIdleEvent, isRecordingPausedEvent, isInteractiveEvent, RECORDING_MAX_EVENT_SIZE, RECORDING_BUFFER_TIMEOUT, RECORDING_IDLE_THRESHOLD_MS, } from "./session-recording-utils";

package/dist/extensions/replay/session-recording-utils.d.ts

@@ -4,63 +4,33 @@
  * Utility functions for session recording.
  * Based on PostHog's sessionrecording-utils.ts
  */
-import { EventType, IncrementalSource, eventWithTime } from "@rrweb/types";
+import { IncrementalSource, eventWithTime } from "@rrweb/types";
 import type { SnapshotBuffer } from "./types";
 export declare const INCREMENTAL_SNAPSHOT_EVENT_TYPE = 3;
 export declare const ONE_KB = 1024;
 export declare const ONE_MB: number;
 export declare const SEVEN_MB: number;
-export declare const PARTIAL_COMPRESSION_THRESHOLD = 1024;
 export declare const RECORDING_MAX_EVENT_SIZE: number;
 export declare const RECORDING_BUFFER_TIMEOUT = 2000;
 export declare const RECORDING_IDLE_THRESHOLD_MS: number;
-/** Active interaction sources */
-export declare const ACTIVE_SOURCES: IncrementalSource[];
 /**
- * Gzip compress data to a base64 string
+ * Selectors passed to rrweb `blockSelector` by default so common non-visible
+ * template / screen-reader / Webflow CMS nodes are not serialized (they replay
+ * as same-sized placeholders). Reduces payload size and keeps hidden form copy
+ * out of recordings. Stylesheet-only `display:none` is not detectable here.
  */
-export declare function gzipToString(data: unknown): string;
+export declare const DEFAULT_INVISIBLE_TEMPLATE_BLOCK_SELECTOR: string;
 /**
- * Estimate the size of an object in bytes
+ * Merge comma-separated CSS selector lists with de-duplication.
+ * When `skipDefaults` is true, omit {@link DEFAULT_INVISIBLE_TEMPLATE_BLOCK_SELECTOR}.
  */
-export declare function estimateSize(obj: unknown): number;
-export interface CompressedFullSnapshotEvent {
-    type: typeof EventType.FullSnapshot;
-    data: string;
-}
-export interface CompressedIncrementalSnapshotEvent {
-    type: typeof EventType.IncrementalSnapshot;
-    data: {
-        source: IncrementalSource;
-        texts: string;
-        attributes: string;
-        removes: string;
-        adds: string;
-    };
-}
-export interface CompressedIncrementalStyleSnapshotEvent {
-    type: typeof EventType.IncrementalSnapshot;
-    data: {
-        source: typeof IncrementalSource.StyleSheetRule;
-        id?: number;
-        styleId?: number;
-        replace?: string;
-        replaceSync?: string;
-        adds?: string;
-        removes?: string;
-    };
-}
-export type CompressedEvent = CompressedFullSnapshotEvent | CompressedIncrementalSnapshotEvent | CompressedIncrementalStyleSnapshotEvent;
-export type CompressedEventWithTime = CompressedEvent & {
-    timestamp: number;
-    delay?: number;
-    cv: "2024-10";
-};
+export declare function mergeBlockSelectors(skipDefaults: boolean | undefined, ...sources: (string | undefined | null)[]): string | undefined;
+/** Active interaction sources */
+export declare const ACTIVE_SOURCES: IncrementalSource[];
 /**
- * Compress an rrweb event for transmission
- * Only compresses full snapshots and mutation events above threshold
+ * Estimate the size of an object in bytes
  */
-export declare function compressEvent(event: eventWithTime): eventWithTime | CompressedEventWithTime;
+export declare function estimateSize(obj: unknown): number;
 /**
  * Truncate large console log payloads to prevent excessive data
  */

package/dist/extensions/replay/session-recording-wrapper.d.ts

@@ -1,92 +1,36 @@
 /**
  * Session Recording Wrapper
  *
- * Lightweight wrapper that handles the decision of WHEN to load recording.
- * The actual recording logic is in LazyLoadedSessionRecording which is
- * loaded on demand.
+ * Extends ToggleableLazyFeature to handle lazy-loading the rrweb recorder
+ * script and delegating to the heavy LazyLoadedSessionRecording instance.
  *
- * Implements the ToggleableFeature interface for consistent lifecycle management.
- * Based on PostHog's sessionrecording-wrapper.ts
+ * @see docs/patterns/tracker-feature-lifecycle.md
  */
 import type { VTilt } from "../../vtilt";
-import type { VTiltConfig, RemoteConfig } from "../../types";
-import type { ToggleableFeature } from "../../feature";
+import type { VTiltConfig } from "../../types";
 import type { SessionRecordingConfig, SessionStartReason } from "./types";
+import { ToggleableLazyFeature } from "../../feature";
 import { LazyLoadedSessionRecordingInterface } from "../../utils/globals";
-/** Status when lazy loading is in progress */
 export declare const LAZY_LOADING: "lazy_loading";
-/** Session recording status */
 export type SessionRecordingStatus = "disabled" | "buffering" | "active" | "paused" | "sampled" | "trigger_pending" | typeof LAZY_LOADING;
 export type { LazyLoadedSessionRecordingInterface };
-/**
- * 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
- */
-export declare class SessionRecordingWrapper implements ToggleableFeature {
-    private readonly _instance;
+export declare class SessionRecordingWrapper extends ToggleableLazyFeature<SessionRecordingConfig, LazyLoadedSessionRecordingInterface> {
     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.
-     */
+    readonly scriptName = "recorder";
+    constructor(instance: VTilt, config?: SessionRecordingConfig);
     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;
+    protected _createLoaded(): LazyLoadedSessionRecordingInterface;
+    protected _onLoaded(loaded: LazyLoadedSessionRecordingInterface, trigger?: SessionStartReason): void;
     get started(): boolean;
     get status(): SessionRecordingStatus;
     get sessionId(): string;
-    /**
-     * Alias for stop() for backwards compatibility.
-     */
     stopRecording(): void;
-    /**
-     * Log a message to the recording.
-     */
     log(message: string, level?: "log" | "warn" | "error"): void;
-    /**
-     * Update configuration.
-     */
     updateConfig(config: Partial<SessionRecordingConfig>): void;
-    private get _scriptName();
-    /**
-     * Lazy load the recording script and start.
-     */
-    private _lazyLoadAndStart;
-    /**
-     * Called after the recording script is loaded.
-     */
-    private _onScriptLoaded;
 }

package/dist/extensions/replay/session-recording.d.ts

@@ -59,6 +59,7 @@ export declare class LazyLoadedSessionRecording implements LazyLoadedSessionReco
      */
     updateConfig(config: Partial<SessionRecordingConfig>): void;
     private _onBeforeUnload;
+    private _onPageHide;
     private _onOffline;
     private _onOnline;
     private _onVisibilityChange;
@@ -72,12 +73,63 @@ export declare class LazyLoadedSessionRecording implements LazyLoadedSessionReco
     private _updateWindowAndSessionIds;
     private _clearBuffer;
     private _flushBuffer;
+    /**
+     * Unconditionally flush the buffer, ignoring status checks.
+     * Used during stop() and session transitions to prevent data loss.
+     */
+    private _forceFlushBuffer;
+    private _sendBufferContents;
     private _captureSnapshotBuffered;
     private _captureSnapshot;
+    /**
+     * Send a snapshot batch to the ingestion endpoint.
+     *
+     * Transport selection:
+     *
+     *   - FullSnapshots, or batches over `BEACON_SIZE_LIMIT`, always use
+     *     fetch (with retry). They're too important / too big for sendBeacon.
+     *   - Smaller batches use `sendBeacon` first.
+     *
+     * Encoding selection (this is the part that fixes the server-side
+     * `Z_BUF_ERROR`):
+     *
+     *   - **fetch path** sends the gzip bytes as a binary `Blob` and uses
+     *     `?compression=gzip-js`. Reliable because the request lifetime is
+     *     bounded by the JS context.
+     *   - **sendBeacon path** sends the gzip bytes as a base64 *string* and
+     *     uses `?compression=base64`. `sendBeacon(url, Blob([binary]))`
+     *     races with tab discard / `pagehide`: the browser queues the
+     *     beacon synchronously and serializes the body after JS is torn
+     *     down, by which time the Uint8Array's backing `ArrayBuffer` may
+     *     have been detached. A string-backed Blob owns its own UTF-8 copy
+     *     and survives unload. The server already understands both flags.
+     *
+     * The query-param flag is *only* added once we know the encoded body
+     * actually carries that compression — never up front from configuration —
+     * so the URL can never claim compression while the body is empty/JSON.
+     */
     private _sendSnapshot;
+    /**
+     * fetch path — binary gzip body, `compression=gzip-js`. Auth travels
+     * in the `x-api-key` header (see `_sendSnapshot` for the rationale).
+     */
+    private _sendViaFetch;
+    /**
+     * sendBeacon path — base64 text body, `compression=base64`. The token
+     * must be on the URL (caller pre-built `baseUrl` with
+     * `includeTokenQuery: true`) because beacons cannot carry headers.
+     * Falls back to fetch+keepalive — same URL, no header — if the beacon
+     * is refused, so the two transports look identical on the wire.
+     */
+    private _sendViaBeacon;
     /**
      * Fetch with exponential backoff retry (PostHog-style)
-     * Retries on network errors and 5xx server errors
+     * Retries on network errors and 5xx server errors.
+     *
+     * When `token` is non-empty the request is authenticated via the
+     * `x-api-key` header (clean URL, harder to block). When empty the
+     * caller has already authenticated via `?token=` in the URL (used by
+     * the beacon-fallback path where the URL must match the beacon's).
      */
     private _fetchWithRetry;
     /**

package/dist/extensions/replay/types.d.ts

@@ -139,6 +139,11 @@ export interface SessionRecordingConfig {
     blockClass?: string;
     /** Block selector for elements to hide */
     blockSelector?: string;
+    /**
+     * When `true`, do not merge built-in selectors for off-screen / template DOM
+     * (`.sr-only`, Webflow `w-condition-invisible`, etc.). Default `false`.
+     */
+    skipDefaultInvisibleBlocking?: boolean;
     /** Ignore class for input masking */
     ignoreClass?: string;
     /** Mask text class */
@@ -153,7 +158,7 @@ export interface SessionRecordingConfig {
     recordHeaders?: boolean;
     /** Record body in network requests */
     recordBody?: boolean;
-    /** Compress events before sending */
+    /** Gzip-compress the request body before sending (transport-level) */
     compressEvents?: boolean;
     /** Internal: Mutation throttler refill rate */
     __mutationThrottlerRefillRate?: number;