@v-tilt/browser 1.11.0 → 1.13.0

package/dist/core/remote-config.d.ts

@@ -3,48 +3,45 @@
  *
  * Handles loading, fetching, caching, and applying remote configuration
  * from the /decide endpoint. Supports bootstrap data for instant loading.
+ *
+ * Config merge precedence: client init > remote > defaults
+ * Uses _initConfig snapshot to distinguish user-set values from cache-applied values.
+ *
+ * @see docs/patterns/tracker-feature-lifecycle.md
  */
 import { VTiltConfig, RemoteConfig } from "../types";
-/**
- * Interface for the VTilt instance methods needed by RemoteConfigManager.
- * Using a minimal interface avoids circular dependency.
- */
+import type { FeatureManager } from "./feature-manager";
 export interface RemoteConfigHost {
     getConfig(): VTiltConfig;
     updateConfig(config: Partial<VTiltConfig>): void;
+    buildEndpointUrl(path: string): string;
     __loaded: boolean;
-    startSessionRecording?(): void;
-    startAutocapture?(): void;
-    _initChat?(): void;
+    featureManager: FeatureManager;
 }
-/**
- * Callback when remote config is loaded/applied
- */
 export type RemoteConfigCallback = (config: RemoteConfig) => void;
 export declare class RemoteConfigManager {
     private _host;
     private _remoteConfig;
     private _onApply?;
     private _onLoad?;
+    private _initConfig;
     constructor(host: RemoteConfigHost);
-    /** Get the current remote config (may be null if not loaded) */
     get config(): RemoteConfig | null;
-    /** Set callback for when config is applied */
     onApply(callback: RemoteConfigCallback): void;
-    /** Set callback for when fresh config is loaded */
     onLoad(callback: RemoteConfigCallback): void;
     /**
      * Load remote config from cache and fetch fresh in background.
      * Priority: 1) Bootstrap config 2) Window bootstrap 3) localStorage cache
      */
     load(): void;
-    /**
-     * Fetch remote config from /decide endpoint.
-     */
     private _fetch;
     /**
      * Apply remote config to current config.
-     * Local config takes precedence over remote.
+     * Uses _initConfig snapshot: only values NOT set by the user in vt.init() are applied.
+     * Feature config is mapped via FeatureManager descriptors; non-feature config is handled inline.
+     *
+     * @param fromCache When true, analytics toggles are skipped to avoid acting on stale
+     *   localStorage data before the fresh /decide fetch resolves.
      */
     private _apply;
 }

package/dist/extensions/chat/bubble-drag.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Draggable bubble utility.
+ *
+ * Attaches pointer-based drag behavior to a fixed-position bubble element.
+ * Persists the drag offset in localStorage so the position survives page
+ * navigations and transfers between the lightweight and full bubbles.
+ */
+interface DraggableOptions {
+    /** Element that initiates the drag (defaults to the target element itself) */
+    handle?: HTMLElement;
+}
+interface DragHandle {
+    destroy: () => void;
+}
+/**
+ * Make a fixed-position element draggable.
+ *
+ * @param el      The element to reposition via translate3d.
+ * @param opts.handle  Optional drag handle element (e.g. bubble inside a container).
+ *                     Pointer events listen on the handle; transform applies to `el`.
+ *                     Defaults to `el` itself.
+ *
+ * - Restores persisted position from localStorage on attach.
+ * - Persists position on drag end.
+ * - Distinguishes click from drag via a 5px movement threshold.
+ *   When dragged, the subsequent `click` event on the handle is suppressed once.
+ * - Re-clamps on viewport resize.
+ */
+export declare function makeDraggable(el: HTMLElement, opts?: DraggableOptions): DragHandle;
+export {};

package/dist/extensions/chat/chat-api.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Chat widget API – HTTP helpers and endpoint constants.
+ */
+import type { VTiltConfig } from "../../types";
+export declare const API: {
+    readonly channels: "/api/chat/widget/channels";
+    readonly messages: (channelId: string) => string;
+    readonly read: (channelId: string) => string;
+    readonly ablyToken: "/api/chat/token/widget";
+};
+/** Minimal host surface for HTTP helpers (lazy chat bundle must not rely on `VTilt` prototype methods). */
+export interface ApiRequestInstance {
+    getConfig(): Pick<VTiltConfig, "api_host" | "token">;
+}
+export declare function apiRequest<T>(instance: ApiRequestInstance, endpoint: string, options?: RequestInit): Promise<T | null>;

package/dist/extensions/chat/chat-styles.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Chat widget style and HTML string builders.
+ * Keeps all style/logic in TS (no separate CSS file), aligned with Intercom/PostHog.
+ */
+export type ChatWidgetPosition = "bottom-right" | "bottom-left";
+export interface ChatTheme {
+    primaryColor: string;
+    fontFamily: string;
+    borderRadius?: string;
+}
+export declare function getContainerStyles(theme: ChatTheme, position?: ChatWidgetPosition): string;
+export declare function getBubbleStyles(theme: ChatTheme): string;
+export declare function getBubbleHTML(): string;
+export declare function getWidgetStyles(): string;
+/**
+ * Container styles when the widget is fullscreen on mobile.
+ * The container (direct child of body) becomes the fullscreen overlay;
+ * any drag transform is cleared so position:fixed works correctly.
+ */
+export declare function getMobileContainerStyles(theme: ChatTheme): string;
+/**
+ * Widget styles when fullscreen on mobile.
+ * Widget fills the container with absolute positioning.
+ * Display is omitted — set by _updateUI based on open state.
+ */
+export declare function getMobileWidgetStyles(): string;
+export declare function getWidgetHTML(theme: ChatTheme): string;

package/dist/extensions/chat/chat-wrapper.d.ts

@@ -1,12 +1,9 @@
 /**
  * Chat Wrapper
  *
- * Lightweight wrapper that handles the decision of WHEN to load the chat widget.
+ * Extends LazyFeature to handle lazy-loading the chat widget script.
  * The actual chat logic is in LazyLoadedChat which is loaded on demand.
  *
- * Implements the Feature interface for consistent lifecycle management.
- * This follows the same pattern as SessionRecordingWrapper.
- *
  * ## Initialization Modes (Intercom-like flexibility)
  *
  * 1. **Snippet-only (dashboard configured)**:
@@ -30,193 +27,71 @@
  *    ```
  *
  * Code config always takes precedence over dashboard settings.
+ *
+ * @see docs/patterns/tracker-feature-lifecycle.md
  */
 import type { VTilt } from "../../vtilt";
-import type { VTiltConfig, RemoteConfig } from "../../types";
-import type { Feature } from "../../feature";
-import { type ChatConfig, type ChatChannelSummary, type ChatWidgetView } from "../../utils/globals";
+import type { VTiltConfig } from "../../types";
+import { LazyFeature } from "../../feature";
+import { type ChatConfig, type ChatChannelSummary, type ChatWidgetView, type LazyLoadedChatInterface, type SendChatMessageContent, type SendChatMessageOptions } from "../../utils/globals";
 import type { MessageCallback, TypingCallback, ConnectionCallback, Unsubscribe } from "./types";
-/** Status when lazy loading is in progress */
 export declare const CHAT_LOADING: "loading";
-/**
- * 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
- * - Deciding if chat should be enabled
- * - Lazy loading the actual chat widget code
- * - Delegating to LazyLoadedChat
- * - Queuing messages/callbacks before widget loads
- */
-export declare class ChatWrapper implements Feature {
-    private readonly _instance;
+export declare class ChatWrapper extends LazyFeature<ChatConfig, LazyLoadedChatInterface> {
     readonly name = "Chat";
-    private _lazyLoadedChat;
-    private _config;
+    readonly scriptName = "chat";
     private _serverConfig;
     private _configFetched;
-    private _isLoading;
-    private _isStarted;
     private _loadError;
+    private _bubbleDragHandle;
     private _pendingMessages;
     private _pendingCallbacks;
     private _messageCallbacks;
     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.
-     */
+    /** True after vt.showChat() so preloaded widget stays visible after replacing the lightweight bubble. */
+    private _bubbleExplicitShow;
+    constructor(instance: VTilt, config?: ChatConfig);
     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.
+     * Chat has a custom start flow: fetch server settings, show bubble,
+     * lazy-load full widget on user interaction.
      */
     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
-     */
+    protected _createLoaded(): LazyLoadedChatInterface;
+    protected _onLoaded(loaded: LazyLoadedChatInterface): void;
     private _startAsync;
-    /**
-     * Whether the chat widget is open
-     */
     get isOpen(): boolean;
-    /**
-     * Whether connected to realtime service
-     */
     get isConnected(): boolean;
-    /**
-     * Whether the widget is loading
-     */
     get isLoading(): boolean;
-    /**
-     * Number of unread messages
-     */
     get unreadCount(): number;
-    /**
-     * Current channel (if any)
-     */
     get channel(): import("./types").ChatChannel | null;
-    /**
-     * List of user's channels (multi-channel support)
-     */
     get channels(): ChatChannelSummary[];
-    /**
-     * Current view state ('list' or 'conversation')
-     */
     get currentView(): ChatWidgetView;
-    /**
-     * Open the chat widget
-     */
     open(): void;
-    /**
-     * Close the chat widget
-     */
     close(): void;
-    /**
-     * Toggle the chat widget open/closed
-     */
     toggle(): void;
-    /**
-     * Show the chat widget (make visible but not necessarily open)
-     */
     show(): void;
-    /**
-     * Hide the chat widget
-     */
     hide(): void;
-    /**
-     * Fetch/refresh the list of user's channels
-     */
     getChannels(): void;
-    /**
-     * Select a channel and load its messages
-     */
     selectChannel(channelId: string): void;
-    /**
-     * Create a new channel and enter it
-     */
     createChannel(): void;
-    /**
-     * Go back to channel list from conversation view
-     */
     goToChannelList(): void;
-    /**
-     * Send a message
-     */
-    sendMessage(content: string): void;
-    /**
-     * Mark messages as read
-     */
+    sendMessage(content: SendChatMessageContent, options?: SendChatMessageOptions): void;
     markAsRead(): void;
-    /**
-     * Subscribe to new messages
-     */
+    registerWidget(definition: Parameters<NonNullable<LazyLoadedChatInterface["registerWidget"]>>[0]): void;
     onMessage(callback: MessageCallback): Unsubscribe;
-    /**
-     * Subscribe to typing indicators
-     */
     onTyping(callback: TypingCallback): Unsubscribe;
-    /**
-     * Subscribe to connection changes
-     */
     onConnectionChange(callback: ConnectionCallback): Unsubscribe;
-    /**
-     * Update configuration
-     */
     updateConfig(config: Partial<ChatConfig>): void;
-    /**
-     * Get the merged configuration (server + code, code takes precedence)
-     */
     getMergedConfig(): ChatConfig;
-    /**
-     * Destroy the chat widget
-     */
     destroy(): void;
-    /**
-     * Fetch chat settings from the server
-     * This enables "snippet-only" installation where widget configures from dashboard
-     */
     private _fetchServerSettings;
-    /**
-     * Show the chat bubble (launcher button) without fully loading the widget
-     * This creates a lightweight bubble that loads the full widget on click
-     */
+    private _fetchUnreadForBubble;
     private _showBubble;
-    private get _scriptName();
-    /**
-     * Schedule preload on idle
-     */
+    private _onVisibilityChange;
     private _schedulePreload;
-    /**
-     * Lazy load and then execute callback
-     */
     private _lazyLoadAndThen;
-    /**
-     * Lazy load the chat script
-     */
-    private _lazyLoad;
-    /**
-     * Called after the chat script is loaded
-     */
-    private _onScriptLoaded;
 }