@v-tilt/browser 1.11.0 → 1.12.0

package/dist/feature.d.ts

@@ -1,231 +1,113 @@
 /**
- * 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
  */
-import type { VTiltConfig, RemoteConfig } from "./types";
+import type { VTiltConfig } from "./types";
 /**
  * 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;
- *     }
- *   }
- * }
- * ```
  */
 export 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.
+ * Used for features that should actively stop when disabled mid-session
+ * (e.g. session recording stops if server disables it).
  */
 export 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.
- */
 export interface FeatureConfig {
-    /** Whether the feature is enabled */
     enabled?: boolean;
 }
 /**
  * Static interface for feature classes.
- * Defines the extractConfig static method pattern.
+ * Every feature class must provide extractConfig for self-contained config extraction.
  */
 export interface FeatureStatic<TConfig extends FeatureConfig = FeatureConfig> {
-    /**
-     * Extract feature-specific config from VTiltConfig.
-     * This allows features to be self-contained - vtilt.ts doesn't need
-     * to know about feature-specific config transformations.
-     *
-     * @param config - The main VTilt configuration
-     * @returns Feature-specific configuration
-     */
     extractConfig(config: VTiltConfig): TConfig;
 }
-/**
- * VTilt instance interface (minimal - avoids circular imports)
- */
 export interface VTiltInstance {
     getConfig(): VTiltConfig;
     capture(event: string, properties?: Record<string, unknown>): void;
 }
 /**
- * Abstract base class for features.
- * Provides common functionality and enforces the Feature interface.
- *
- * Features can extend this class or implement the Feature interface directly.
- *
- * @example
- * ```typescript
- * class MyFeature extends BaseFeature<MyFeatureConfig> {
- *   readonly name = 'MyFeature';
+ * Abstract base class for features that require lazy-loaded external scripts.
  *
- *   static extractConfig(config: VTiltConfig): MyFeatureConfig {
- *     return { enabled: !!config.myFeature };
- *   }
+ * Handles the common pattern of:
+ * 1. Checking if extension is already on window.__VTiltExtensions__
+ * 2. Loading the script via loadExternalDependency if not
+ * 3. Creating the heavy instance via _createLoaded()
+ * 4. Calling _onLoaded() for feature-specific start logic
+ * 5. Guarding against duplicate loads
  *
- *   get isEnabled(): boolean {
- *     return this._config.enabled !== false;
- *   }
+ * Subclasses must implement: name, scriptName, _createLoaded()
+ * Subclasses may override: _onLoaded(), isEnabled, startIfEnabled(), stop()
  *
- *   protected _start(): void {
- *     // Setup logic
- *   }
- *
- *   protected _stop(): void {
- *     // Cleanup logic
- *   }
- * }
- * ```
+ * Deferral: Subclasses with public API methods (e.g. Chat) use _deferCall()
+ * to queue calls until async initialization completes, then _markApiReady()
+ * to flush the queue. This is the standard pattern for features whose
+ * public API must wait for an async start step.
  */
-export declare abstract class BaseFeature<TConfig extends FeatureConfig = FeatureConfig> implements Feature {
-    /** Feature name for logging */
-    abstract readonly name: string;
-    /** VTilt instance reference */
+export declare abstract class LazyFeature<TConfig extends object, TLoaded> implements Feature {
     protected _instance: VTiltInstance;
-    /** Feature-specific configuration */
     protected _config: TConfig;
-    /** Whether the feature has been started */
+    protected _loaded: TLoaded | undefined;
     protected _isStarted: boolean;
-    /** Whether the feature has been initialized (guards against double-init) */
-    protected _initialized: boolean;
+    protected _isLoading: boolean;
+    private _apiReady;
+    private _deferredCalls;
+    abstract readonly name: string;
+    /** Script name passed to loadExternalDependency (e.g. "recorder", "chat", "web-vitals") */
+    abstract readonly scriptName: string;
     constructor(instance: VTiltInstance, config: TConfig);
-    /**
-     * Check if feature is enabled. Override in subclass for custom logic.
-     */
     get isEnabled(): boolean;
-    /**
-     * Check if feature is started.
-     */
     get isStarted(): boolean;
+    get isLoaded(): boolean;
+    /** Create the heavy instance after the external script has loaded. */
+    protected abstract _createLoaded(): TLoaded;
     /**
-     * Start the feature if enabled.
-     * Uses initialization guard to prevent double-initialization.
+     * Load external script (if needed) then invoke callback with the loaded instance.
+     * Safe to call multiple times — guards against duplicate loads.
      */
+    protected _ensureLoaded(callback: (loaded: TLoaded) => void): void;
     startIfEnabled(): void;
-    /**
-     * Stop the feature and cleanup.
-     */
+    /** Called after the script loads and the loaded instance is created. Override for custom start logic. */
+    protected _onLoaded(_loaded: TLoaded): void;
     stop(): void;
-    /**
-     * Handle config updates. Override in subclass for custom behavior.
-     */
-    onConfigUpdate(_config: VTiltConfig): void;
-    /**
-     * Handle remote config updates. Override in subclass for custom behavior.
-     */
-    onRemoteConfig(_remoteConfig: RemoteConfig): void;
-    /**
-     * Internal start logic. Called when feature should start.
-     * Override in subclass to setup event listeners, observers, etc.
-     */
-    protected abstract _start(): void;
-    /**
-     * Internal stop logic. Called when feature should stop.
-     * Override in subclass to cleanup event listeners, observers, etc.
-     */
-    protected abstract _stop(): void;
-    /**
-     * Update the feature's configuration.
-     */
-    protected updateConfig(config: Partial<TConfig>): void;
-    /**
-     * Capture an event through the VTilt instance.
-     */
-    protected capture(event: string, properties?: Record<string, unknown>): void;
-    /**
-     * Get the current VTilt config.
-     */
-    protected getVTiltConfig(): VTiltConfig;
+    onConfigUpdate?(config: VTiltConfig): void;
+    updateConfig(config: Partial<TConfig>): void;
+    /** Queue fn until _markApiReady(). If already ready, execute immediately. */
+    protected _deferCall(fn: () => void): void;
+    /** Flush all deferred calls. Idempotent — subsequent calls are no-ops. */
+    protected _markApiReady(): void;
+    /** Reset deferral state (for destroy/cleanup). */
+    protected _resetDeferral(): void;
 }
 /**
- * Helper to create a feature instance with config extraction.
- *
- * @param FeatureClass - The feature class (must have static extractConfig)
- * @param instance - The VTilt instance
- * @returns Feature instance with extracted config
+ * Lazy-loaded feature that can be toggled on/off at runtime.
+ * Adds startIfEnabledOrStop() which actively stops the feature when disabled.
  */
-export declare function createFeature<TConfig extends FeatureConfig, TFeature extends BaseFeature<TConfig>>(FeatureClass: (new (instance: VTiltInstance, config: TConfig) => TFeature) & FeatureStatic<TConfig>, instance: VTiltInstance): TFeature;
+export declare abstract class ToggleableLazyFeature<TConfig extends object, TLoaded> extends LazyFeature<TConfig, TLoaded> implements ToggleableFeature {
+    startIfEnabledOrStop(trigger?: string): void;
+}