@v-tilt/browser 1.11.0 → 1.13.0

package/dist/extensions/web-vitals/web-vitals-manager.d.ts

@@ -1,16 +1,9 @@
 /**
  * Web Vitals Manager
  *
+ * Extends LazyFeature to handle lazy-loading the web-vitals script.
  * 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
+ * as batched $web_vitals events.
  *
  * Event structure:
  * - event: "$web_vitals"
@@ -19,57 +12,35 @@
  *   - $web_vitals_LCP_event: { name, value, delta, rating, ... }
  *   - $pathname: string
  *   - $current_url: string
+ *
+ * @see docs/patterns/tracker-feature-lifecycle.md
  */
 import { VTiltConfig, CapturePerformanceConfig, SupportedWebVitalsMetric } from "../../types";
-import type { Feature } from "../../feature";
-import { VTilt } from "../../vtilt";
-export declare class WebVitalsManager implements Feature {
+import { LazyFeature } from "../../feature";
+import type { VTilt } from "../../vtilt";
+import { WebVitalsCallbacks } from "../../utils/globals";
+export declare class WebVitalsManager extends LazyFeature<CapturePerformanceConfig, WebVitalsCallbacks> {
     readonly name = "WebVitals";
-    private _instance;
+    readonly scriptName = "web-vitals";
     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
-     */
+    constructor(instance: VTilt, config?: CapturePerformanceConfig);
     get isEnabled(): boolean;
     /**
-     * Check if capturing has started
-     */
-    get isStarted(): boolean;
-    /**
-     * Start capturing if enabled
+     * Web Vitals checks if callbacks are already registered (from full bundle)
+     * before trying to lazy-load the script.
      */
     startIfEnabled(): void;
-    /**
-     * Stop capturing (flushes any pending metrics)
-     */
     stop(): void;
-    /**
-     * Handle config update
-     */
     onConfigUpdate(config: VTiltConfig): void;
-    /**
-     * Get the list of metrics to capture
-     */
+    protected _createLoaded(): WebVitalsCallbacks;
+    protected _onLoaded(loaded: WebVitalsCallbacks): void;
     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;

package/dist/external-scripts-loader.js

@@ -1,2 +1,2 @@
-!function(n){"use strict";var i="undefined"!=typeof window?window:void 0,o="undefined"!=typeof globalThis?globalThis:i,l=null==o?void 0:o.navigator,r=null==o?void 0:o.document;null==o||o.location,null==o||o.fetch,i&&r&&r.createElement,null==o||o.XMLHttpRequest,null==o||o.AbortController,null==l||l.userAgent;var d=null!=i?i:{},t="[ExternalScriptsLoader]",e=(n,i,o)=>{if(n.getConfig().disable_external_dependency_loading)return console.warn(t+" "+i+" was requested but loading of external scripts is disabled."),o("Loading of external scripts is disabled");var l=null==r?void 0:r.querySelectorAll("script");if(l)for(var d,e=function(){if(l[a].src===i){var n=l[a];return n.__vtilt_loading_callback_fired?{v:o()}:(n.addEventListener("load",i=>{n.__vtilt_loading_callback_fired=!0,o(void 0,i)}),n.onerror=n=>o(n),{v:void 0})}},a=0;a<l.length;a++)if(d=e())return d.v;var s=()=>{var n;if(!r)return o("document not found");var l=r.createElement("script");l.type="text/javascript",l.crossOrigin="anonymous",l.src=i,l.onload=n=>{l.__vtilt_loading_callback_fired=!0,o(void 0,n)},l.onerror=n=>o(n);var d=r.querySelectorAll("body > script");d.length>0?null===(n=d[0].parentNode)||void 0===n||n.insertBefore(l,d[0]):r.body.appendChild(l)};(null==r?void 0:r.body)?s():null==r||r.addEventListener("DOMContentLoaded",s)},a=(n,i)=>{var o=n.getConfig();return o.script_host?o.script_host.replace(/\/+$/gm,"")+"/"+i+".js":o.api_host?o.api_host.replace(/\/+$/gm,"")+"/dist/"+i+".js":(console.error(t+" Cannot load "+i+".js: api_host is required"),"")};d.__VTiltExtensions__=d.__VTiltExtensions__||{},d.__VTiltExtensions__.loadExternalDependency=(n,i,o)=>{var l=a(n,i);e(n,l,o)},n.getExtensionUrl=a,n.loadScript=e}({});
+!function(r){"use strict";var n="undefined"!=typeof window?window:void 0,e="undefined"!=typeof globalThis?globalThis:n,o=null==e?void 0:e.navigator,i=null==e?void 0:e.document;null==e||e.location,null==e||e.fetch,n&&i&&i.createElement,null==e||e.XMLHttpRequest,null==e||e.AbortController,null==o||o.userAgent;var t=null!=n?n:{},l={none:0,error:1,warn:2,info:3,debug:4},a="[vTilt]",u=new Set(["none","error","warn","info","debug"]);function d(){return"undefined"!=typeof console}function s(r){var n=r.length>0&&"string"==typeof r[0]?r[0]:"",e=n?r.slice(1):r;return[n?a+":"+n:a,...e]}var v="warn",f=!1;var c=null;function w(){return c||(c={setLevel(r,n){void 0===n&&(n=!1),v=r,n&&(f=!0)},setLevelFromRemote(r){f||r&&u.has(r)&&(v=r)},getLevel:()=>v,isLockedByInit:()=>f,debug(){if(!(l[v]<l.debug)&&d()){for(var r=arguments.length,n=new Array(r),e=0;e<r;e++)n[e]=arguments[e];console.log(...s(n))}},info(){if(!(l[v]<l.info)&&d()){for(var r=arguments.length,n=new Array(r),e=0;e<r;e++)n[e]=arguments[e];console.log(...s(n))}},warn(){if(!(l[v]<l.warn)&&d()){for(var r=arguments.length,n=new Array(r),e=0;e<r;e++)n[e]=arguments[e];console.warn(...s(n))}},error(){if(!(l[v]<l.error)&&d()){for(var r=arguments.length,n=new Array(r),e=0;e<r;e++)n[e]=arguments[e];console.error(...s(n))}}}),c}var p="external-scripts",g=(r,n,e)=>{if(r.getConfig().disable_external_dependency_loading)return w().warn(p,n+" was requested but loading of external scripts is disabled."),e("Loading of external scripts is disabled");var o=null==i?void 0:i.querySelectorAll("script");if(o)for(var t,l=function(){if(o[a].src===n){var r=o[a];return r.__vtilt_loading_callback_fired?{v:e()}:(r.addEventListener("load",n=>{r.__vtilt_loading_callback_fired=!0,e(void 0,n)}),r.onerror=r=>e(r),{v:void 0})}},a=0;a<o.length;a++)if(t=l())return t.v;var u=()=>{var r;if(!i)return e("document not found");var o=i.createElement("script");o.type="text/javascript",o.crossOrigin="anonymous",o.src=n,o.onload=r=>{o.__vtilt_loading_callback_fired=!0,e(void 0,r)},o.onerror=r=>e(r);var t=i.querySelectorAll("body > script");t.length>0?null===(r=t[0].parentNode)||void 0===r||r.insertBefore(o,t[0]):i.body.appendChild(o)};(null==i?void 0:i.body)?u():null==i||i.addEventListener("DOMContentLoaded",u)},y=(r,n)=>{var e=r.getConfig();return e.script_host?e.script_host.replace(/\/+$/gm,"")+"/"+n+".js":e.api_host?e.api_host.replace(/\/+$/gm,"")+"/dist/"+n+".js":(w().error(p,"cannot load "+n+".js: api_host is required"),"")};t.__VTiltExtensions__=t.__VTiltExtensions__||{},t.__VTiltExtensions__.loadExternalDependency=(r,n,e)=>{var o=y(r,n);g(r,o,e)},r.getExtensionUrl=y,r.loadScript=g}({});
 //# sourceMappingURL=external-scripts-loader.js.map

package/dist/external-scripts-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"external-scripts-loader.js","sources":["../src/utils/globals.ts","../src/entrypoints/external-scripts-loader.ts"],"sourcesContent":[null,null],"names":["win","window","undefined","global","globalThis","navigator","document","location","fetch","createElement","XMLHttpRequest","AbortController","userAgent","assignableWindow","LOGGER_PREFIX","loadScript","vtilt","url","callback","getConfig","disable_external_dependency_loading","console","warn","existingScripts","querySelectorAll","_ret","_loop","i","src","alreadyExistingScriptTag","__vtilt_loading_callback_fired","v","addEventListener","event","onerror","error","length","addScript","scriptTag","type","crossOrigin","onload","scripts","_a","parentNode","insertBefore","body","appendChild","getExtensionUrl","kind","config","script_host","replace","api_host","__VTiltExtensions__","loadExternalDependency"],"mappings":"0BAaA,IAAMA,EACc,oBAAXC,OAAyBA,YAASC,EAiSrCC,EACkB,oBAAfC,WAA6BA,WAAaJ,EAMtCK,EAAYF,aAAM,EAANA,EAAQE,UACpBC,EAAWH,aAAM,EAANA,EAAQG,SACRH,SAAAA,EAAQI,SACXJ,SAAAA,EAAQK,MAOzBR,GAASM,GAAmBA,EAASG,cAIXN,SAAAA,EAAQO,eACPP,SAAAA,EAAQQ,gBACdN,SAAAA,EAAWO,UAC7B,IAAMC,EAAqCb,QAAAA,EAAQ,CAAA,ECzTpDc,EAAgB,0BAKhBC,EAAaA,CACjBC,EACAC,EACAC,KAKA,GAHeF,EAAMG,YAGDC,oCAIlB,OAHAC,QAAQC,KACHR,EAAa,IAAIG,iEAEfC,EAAS,2CAIlB,IAAMK,EAAkBjB,aAAQ,EAARA,EAAUkB,iBAAiB,UACnD,GAAID,EACF,IADmB,IAuBlBE,EAvBkBC,EAAA,WAEjB,GAAIH,EAAgBI,GAAGC,MAAQX,EAAK,CAClC,IAAMY,EAA2BN,EAC/BI,GAKF,OAAIE,EAAyBC,+BAC3B,CAAAC,EACOb,MAITW,EAAyBG,iBAAiB,OAASC,IACjDJ,EAAyBC,gCAAiC,EAC1DZ,OAAShB,EAAW+B,KAEtBJ,EAAyBK,QAAWC,GAAUjB,EAASiB,GAAO,CAAAJ,OAAA,GAGhE,CACF,EAtBSJ,EAAI,EAAGA,EAAIJ,EAAgBa,OAAQT,IAAG,GAAAF,EAAAC,IAAA,OAAAD,EAAAM,EAyBjD,IAAMM,EAAYA,WAChB,IAAK/B,EACH,OAAOY,EAAS,sBAGlB,IAAMoB,EAAYhC,EAASG,cAAc,UAGzC6B,EAAUC,KAAO,kBACjBD,EAAUE,YAAc,YACxBF,EAAUV,IAAMX,EAChBqB,EAAUG,OAAUR,IAClBK,EAAUR,gCAAiC,EAC3CZ,OAAShB,EAAW+B,IAEtBK,EAAUJ,QAAWC,GAAUjB,EAASiB,GAExC,IAAMO,EAAUpC,EAASkB,iBAAiB,iBACtCkB,EAAQN,OAAS,EACE,QAArBO,EAAAD,EAAQ,GAAGE,kBAAU,IAAAD,GAAAA,EAAEE,aAAaP,EAAWI,EAAQ,IAEvDpC,EAASwC,KAAKC,YAAYT,KAI1BhC,aAAQ,EAARA,EAAUwC,MACZT,IAEA/B,SAAAA,EAAU0B,iBAAiB,mBAAoBK,IAe7CW,EAAkBA,CAAChC,EAAciC,KACrC,IAAMC,EAASlC,EAAMG,YAGrB,OAAI+B,EAAOC,YACSD,EAAOC,YAAYC,QAAQ,SAAU,QAChCH,EAAI,MAIzBC,EAAOG,SACSH,EAAOG,SAASD,QAAQ,SAAU,aACxBH,EAAI,OAIlC5B,QAAQc,MACHrB,EAAa,gBAAgBmC,+BAE3B,KAITpC,EAAiByC,oBACfzC,EAAiByC,qBAAuB,CAAA,EAK1CzC,EAAiByC,oBAAoBC,uBAAyB,CAC5DvC,EACAiC,EACA/B,KAEA,IAAMD,EAAM+B,EAAgBhC,EAAOiC,GACnClC,EAAWC,EAAOC,EAAKC"}
+{"version":3,"file":"external-scripts-loader.js","sources":["../src/utils/globals.ts","../src/utils/logger.ts","../src/entrypoints/external-scripts-loader.ts"],"sourcesContent":[null,null,null],"names":["win","window","undefined","global","globalThis","navigator","document","location","fetch","createElement","XMLHttpRequest","AbortController","userAgent","assignableWindow","LEVEL_PRIORITY","none","error","warn","info","debug","PREFIX","VALID_LEVELS","Set","hasConsole","console","formatArgs","args","scope","length","rest","slice","currentLevel","lockedByInit","singleton","getLogger","setLevel","level","lockFromInit","setLevelFromRemote","has","getLevel","isLockedByInit","_len","arguments","Array","_key","log","_len2","_key2","_len3","_key3","_len4","_key4","LOG_SCOPE","loadScript","vtilt","url","callback","getConfig","disable_external_dependency_loading","existingScripts","querySelectorAll","_ret","_loop","i","src","alreadyExistingScriptTag","__vtilt_loading_callback_fired","v","addEventListener","event","onerror","addScript","scriptTag","type","crossOrigin","onload","scripts","_a","parentNode","insertBefore","body","appendChild","getExtensionUrl","kind","config","script_host","replace","api_host","__VTiltExtensions__","loadExternalDependency"],"mappings":"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"}

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;
+}