@v-tilt/browser 1.11.0 → 1.13.0

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

@@ -2,8 +2,9 @@
  * Chat Widget - Lazy loaded chat implementation using Ably for real-time messaging.
  */
 import type { VTilt } from "../../vtilt";
-import { type ChatConfig, type ChatChannel, type ChatChannelSummary, type ChatWidgetView, type LazyLoadedChatInterface } from "../../utils/globals";
+import { type ChatConfig, type ChatChannel, type ChatChannelSummary, type ChatWidgetView, type LazyLoadedChatInterface, type SendChatMessageContent, type SendChatMessageOptions } from "../../utils/globals";
 import { type MessageCallback, type TypingCallback, type ConnectionCallback, type Unsubscribe } from "./types";
+import { type WidgetContext } from "./widget-registry";
 export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     private _instance;
     private _config;
@@ -11,10 +12,19 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     private _container;
     private _widget;
     private _bubble;
+    private _bubbleDragHandle;
+    private _chatTheme;
+    private _widgetResizeCleanup;
     private _ably;
+    private _notificationsChannel;
     private _ablyChannel;
     private _typingChannel;
     private _connectionState;
+    private _ablyProjectId;
+    /** Channel id included in the last per-channel Ably token authorize. */
+    private _realtimeChannelId;
+    /** Channel id we are connecting to (select/create in flight). */
+    private _pendingRealtimeChannelId;
     private _messageCallbacks;
     private _typingCallbacks;
     private _connectionCallbacks;
@@ -22,6 +32,18 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     private _isUserTyping;
     private _initialUserReadAt;
     private _isMarkingRead;
+    private _widgetRegistry;
+    /** Tracks whether show() was explicitly called (vs open() temporarily revealing the container). */
+    private _bubbleExplicitShow;
+    private _lastConnectedDistinctId;
+    private _unsubscribeIdentity;
+    private _unsubscribeReset;
+    private _identityChangeInFlight;
+    private _userScrolledUp;
+    private _unreadNewMessagesCount;
+    private _messagesScrollListenerBound;
+    private _conversationListenersBound;
+    private _channelListListenersBound;
     constructor(instance: VTilt, config?: ChatConfig);
     get isOpen(): boolean;
     get isConnected(): boolean;
@@ -45,12 +67,38 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     toggle(): void;
     show(): void;
     hide(): void;
+    /**
+     * Build a stub ChatChannel from a ChatChannelSummary so that
+     * `selectChannel` can populate state synchronously while the real
+     * `GET /channels/:id` response is in flight. The header reads `ai_mode`
+     * and `status` immediately; remaining fields are filled by the response.
+     */
+    private _stubChannelFromSummary;
+    /**
+     * Handle a vTilt identity change (anon → identified, or user → user).
+     *
+     * Ably enforces that the connection's `clientId` is immutable for the
+     * lifetime of a Realtime connection. Authorizing a token with a different
+     * `clientId` puts the connection into the terminal `failed` state and
+     * produces a 40102 error. The correct response is to fully close the
+     * existing client and create a new one with a token bound to the new id.
+     *
+     * This also clears per-identity state (channels, messages, unread count)
+     * since those belong to the previous user.
+     */
+    private _handleIdentityChange;
     getChannels(): Promise<void>;
     selectChannel(channelId: string): Promise<void>;
     createChannel(): Promise<void>;
-    goToChannelList(): void;
-    sendMessage(content: string): Promise<void>;
+    goToChannelList(): Promise<void>;
+    sendMessage(content: SendChatMessageContent, options?: SendChatMessageOptions): Promise<void>;
     markAsRead(): void;
+    /**
+     * Send a silent trigger to the messages API after a widget action completes.
+     * This makes the AI respond to the action (e.g., acknowledge email collection)
+     * without creating a visible user message in the chat.
+     */
+    private _triggerAIAfterWidgetAction;
     private _autoMarkAsRead;
     private _isMessageReadByUser;
     /**
@@ -62,32 +110,188 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     onTyping(callback: TypingCallback): Unsubscribe;
     onConnectionChange(callback: ConnectionCallback): Unsubscribe;
     destroy(): void;
-    private _connectRealtime;
-    private _disconnectRealtime;
+    /**
+     * Ensure Ably client is connected and subscribed to the project notifications channel.
+     * Called when the widget opens. Safe to call multiple times.
+     */
+    private _ensureAblyConnected;
+    /**
+     * Request an Ably token for the current connection scope.
+     * Pass channelId when subscribing to a conversation; omit on channel list.
+     */
+    private _refreshAblyToken;
+    /**
+     * Subscribe to per-channel messages and typing for a specific conversation.
+     *
+     * Attach is async; the user may close the widget or switch to a different
+     * channel while we are still awaiting `attach()`. In that case
+     * `_disconnectChannel()` runs concurrently — it nulls `this._ablyChannel`
+     * and calls `detach()`, which makes Ably reject the pending `attach()` with
+     * "Attach request superseded by a subsequent detach request". We treat
+     * that race as expected: bail out silently instead of logging an error.
+     */
+    private _connectChannel;
+    /**
+     * Unsubscribe, detach, and release per-channel Ably channels.
+     * Ably only allows release() when the channel is initialized, detached, or
+     * failed — not when attached. So we detach first, then release.
+     * Releasing removes the channel from the Ably internal registry so a
+     * subsequent auth.authorize() with narrower capabilities won't try to
+     * reattach it and fail with "Channel denied access."
+     */
+    private _disconnectChannel;
+    /**
+     * Fully disconnect from Ably — unsubscribe everything and close the connection.
+     */
+    private _disconnectAll;
+    /**
+     * Handle project-level notifications (new channels, updates, closes).
+     * Updates channel list and badge count in real time.
+     */
+    private _handleNotification;
     private _handleNewMessage;
     private _handleTypingEvent;
     private _handleReadCursorEvent;
     private _notifyConnectionChange;
     private _createUI;
     private _attachEventListeners;
+    /**
+     * Mark a widget as submitted in local message metadata.
+     * Called after a successful widget action — _renderWidgets() uses this
+     * to show the confirmation UI instead of the input form.
+     */
+    private _markWidgetSubmitted;
     private _handleUserTyping;
     private _sendTypingIndicator;
     private _handleSend;
     private _updateUI;
+    private _isMobile;
+    private _containerBaseStyle;
+    private _savedTransform;
+    private _isMobileFullscreen;
+    /**
+     * Mobile fullscreen: make the *container* fullscreen instead of the widget.
+     * Using position:fixed on the widget is unreliable because the container
+     * may have a CSS transform (from drag) which creates a new containing block.
+     * The container is a direct child of <body> so position:fixed is always safe.
+     *
+     * Both elements get their full style replaced atomically via setAttribute.
+     * Display is set by _updateUI after this call.
+     */
+    private _applyMobileFullscreen;
+    private _removeMobileFullscreen;
+    private _scrollY;
+    private _lockBodyScroll;
+    /**
+     * Ensure the opened widget:
+     * 1. Covers the bubble (anchored at container bottom-right) for UI consistency.
+     * 2. Stays fully inside the viewport by shifting its position when near edges (no size change).
+     *
+     * On mobile the CSS media query handles fullscreen positioning, so this is a no-op.
+     */
+    private _constrainWidgetToViewport;
     private _updateHeader;
-    private _getChannelListHTML;
+    /**
+     * Render the channel-list view with mode-aware diffing.
+     *
+     * Three modes share a single content container so the click delegation
+     * stays bound across them:
+     * - empty:    no channels and not loading → welcome / CTA screen
+     * - skeleton: no channels and loading     → shimmer placeholders
+     * - populated: 1+ channels                 → scaffold + diff items by id
+     *
+     * Only the populated mode preserves item DOM identity; the other two are
+     * rare transient states where a full innerHTML write is cheap.
+     */
+    private _renderChannelList;
+    /**
+     * Wire a single delegated click handler on the list container so we don't
+     * re-attach per-item listeners on every render.
+     */
+    private _setupChannelListDelegation;
+    private _createChannelItemNode;
+    private _updateChannelItemNode;
+    /**
+     * Compact fingerprint used to decide whether a channel-item DOM node needs
+     * an update. Only includes fields that the rendered HTML depends on.
+     */
+    private _channelItemFingerprint;
+    private _getEmptyListHTML;
+    private _getListScaffoldHTML;
+    private _getListSkeletonHTML;
+    /**
+     * Build a skeleton bubble that mirrors the shape of a real chat message
+     * from `_getMessageHTML`: same avatar size (32×32), same bubble padding
+     * (12px 16px), same asymmetric border-radius (20/20/20/4 incoming,
+     * 20/20/4/20 outgoing), and a meta line underneath sized like the
+     * "Sender · 12:34" footer. The shimmer fills the bubble interior — not
+     * floating lines — so the placeholder reads as a "loading message"
+     * rather than a generic content blob. Width varies per call so the
+     * stack of bubbles has visual rhythm instead of looking like a parade
+     * of identical rectangles.
+     */
+    private _getSkeletonBubbleHTML;
+    /**
+     * Skeleton placeholder shown while `selectChannel` is loading the
+     * messages of an existing conversation. Three alternating bubbles
+     * (incoming → outgoing → incoming) imply history is on its way.
+     * Bubble widths vary to avoid the "fake repeated rectangles" look.
+     */
+    private _getMessageSkeletonHTML;
+    /**
+     * New-conversation loader shown while `createChannel` (or
+     * `sendMessage({channel: 'new'})`) is in flight. A single incoming
+     * bubble using *exactly* the same shape, padding, border-radius, and
+     * avatar treatment as a real incoming message from `_getMessageHTML`
+     * — so when the real greeting arrives it morphs in place rather than
+     * snapping to a new layout. The avatar uses the live AI/Support color
+     * + icon (identity is known from `_config.aiMode`), and the bubble
+     * carries three animated typing dots instead of text, signalling
+     * "the assistant is preparing your greeting."
+     */
+    private _getNewChannelLoaderHTML;
     private _getChannelItemHTML;
     private _getConversationHTML;
-    private _attachChannelListListeners;
     private _attachConversationListeners;
-    private _escapeHtml;
     private _formatRelativeTime;
+    /**
+     * Render messages with a key-based diff.
+     *
+     * - Each message node carries `data-msg-key="msg:<id>"` and a fingerprint;
+     *   if both match what we already have, the node is left untouched.
+     * - The "New" divider lives as a sibling node with its own key so it
+     *   participates in the same diff (no flicker when it moves).
+     * - Scroll position is preserved: we only snap to the bottom when the user
+     *   was already near the bottom or just sent their own message. Otherwise
+     *   we surface a "↓ N new messages" pill instead of yanking them down.
+     * - Newly-inserted message nodes get the `vtilt-msg-enter` class for a
+     *   subtle fade-in animation. The initial bulk render skips animation.
+     */
     private _renderMessages;
-    private _getContainerStyles;
-    private _getBubbleStyles;
-    private _getBubbleHTML;
-    private _getWidgetStyles;
-    private _getWidgetHTML;
+    /**
+     * Build the "New" divider node (rendered above the first unread agent/AI
+     * message when scrolled into view).
+     */
+    private _createMessageDividerNode;
+    /**
+     * Build a single message DOM node from the message model.
+     */
+    private _createMessageNode;
+    /**
+     * Compact fingerprint used to decide whether a message node needs an update.
+     * Streaming AI responses update the content field many times — re-rendering
+     * the same DOM lets the cursor and layout stay stable for the user.
+     */
+    private _messageFingerprint;
+    /**
+     * Wire (once per container) a scroll listener that tracks whether the user
+     * is reading history above the latest message. Used to suppress auto-scroll
+     * and to dismiss the "new messages" pill when the user scrolls back down.
+     */
+    private _setupMessagesScrollListener;
+    private _isNearBottom;
+    private _showNewMessagesPill;
+    private _hideNewMessagesPill;
     private _getMessageHTML;
     private _isMessageReadByAgent;
     /**
@@ -99,8 +303,51 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
      * Remove temporary message by ID
      */
     private _removeTempMessage;
-    private _apiRequest;
     private _getTimeOpen;
+    /**
+     * Bubble body for any message — plain escaped text or sanitized rich HTML,
+     * using the same rules for user (html/markdown) and agent/AI messages.
+     */
+    private _renderMessageContent;
+    private _renderMessageHtml;
+    /**
+     * Render widgets for a message. Widget data sources (checked in order):
+     * 1. metadata._widgets -- set during streaming (temp messages)
+     * 2. metadata.widgets -- persisted in DB (loaded on refresh, received via Ably)
+     * 3. Content markers -- fallback for legacy messages with <!--vtilt:widget:...--> in content
+     *
+     * If a widget has submitted=true in metadata, render the confirmation instead of the input.
+     */
+    private _renderWidgets;
+    /**
+     * Build WidgetContext for widget renderers.
+     */
+    private _getWidgetContext;
+    /**
+     * Extract widget blocks from streamed text, strip them, and return parsed widgets.
+     */
+    private _parseWidgetBlocks;
+    /**
+     * Public method for SDK consumers to register custom widgets.
+     */
+    registerWidget(definition: {
+        type: string;
+        toolDescription: string;
+        parameters: Record<string, {
+            type: string;
+            description: string;
+        }>;
+        render: (params: Record<string, unknown>, context: WidgetContext) => string;
+        onAction: (action: string, data: Record<string, unknown>, context: WidgetContext) => Promise<{
+            replaceHTML?: string;
+            sendMessage?: string;
+        }>;
+    }): void;
     private _escapeHTML;
+    /**
+     * Get a human-readable preview for a message (for channel list).
+     * Falls back to widget labels if content is empty (tool-only messages).
+     */
+    private _getMessagePreview;
     private _formatTime;
 }

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

@@ -0,0 +1 @@
+export declare const CHAT_MESSAGE_CONTENT_CSS = "\n  #vtilt-chat-widget .vtilt-md {\n    max-width: 100%;\n    overflow-wrap: anywhere;\n    word-break: break-word;\n    font-size: inherit;\n    line-height: 1.45;\n  }\n  #vtilt-chat-widget .vtilt-md * {\n    box-sizing: border-box;\n  }\n  #vtilt-chat-widget .vtilt-md :is(p, h1, h2, h3, h4, h5, h6, ul, ol, blockquote, pre) {\n    margin: 0;\n  }\n  #vtilt-chat-widget .vtilt-md p { margin: 0 0 0.5em 0; }\n  #vtilt-chat-widget .vtilt-md p:last-child { margin-bottom: 0; }\n  #vtilt-chat-widget .vtilt-md :is(b, strong) { font-weight: 600; }\n  #vtilt-chat-widget .vtilt-md :is(i, em) { font-style: italic; }\n  #vtilt-chat-widget .vtilt-md u { text-decoration: underline; }\n  #vtilt-chat-widget .vtilt-md :is(h1, h2, h3, h4, h5, h6) {\n    font-size: 1em;\n    font-weight: 600;\n    margin: 0.65em 0 0.35em 0;\n    line-height: 1.3;\n  }\n  #vtilt-chat-widget .vtilt-md :is(h1, h2, h3):first-child { margin-top: 0.15em; }\n\n  /* Lists \u2014 flex rows + ::before bullets (beats host list-item / ::marker resets) */\n  #vtilt-chat-widget .vtilt-md :is(ul, ol) {\n    list-style: none !important;\n    margin: 0.5em 0 !important;\n    padding: 0 0 0 0.35em !important;\n  }\n  #vtilt-chat-widget .vtilt-md li {\n    display: flex !important;\n    flex-direction: row !important;\n    flex-wrap: wrap !important;\n    align-items: flex-start !important;\n    gap: 0.35em !important;\n    margin: 0.2em 0 !important;\n    padding: 0 !important;\n    line-height: 1.45;\n    list-style: none !important;\n    list-style-type: none !important;\n  }\n  #vtilt-chat-widget .vtilt-md li::marker {\n    content: \"\" !important;\n    font-size: 0 !important;\n    color: transparent !important;\n  }\n  #vtilt-chat-widget .vtilt-md li::-webkit-list-marker {\n    display: none !important;\n  }\n  #vtilt-chat-widget .vtilt-md ul > li::before {\n    content: \"\u2022\" !important;\n    display: inline-block !important;\n    position: static !important;\n    flex: 0 0 auto;\n    line-height: 1.45;\n  }\n  #vtilt-chat-widget .vtilt-md ul ul > li::before {\n    content: \"\u25E6\" !important;\n  }\n  #vtilt-chat-widget .vtilt-md ol { counter-reset: vtilt-ol; }\n  #vtilt-chat-widget .vtilt-md ol > li { counter-increment: vtilt-ol; }\n  #vtilt-chat-widget .vtilt-md ol > li::before {\n    content: counter(vtilt-ol) \".\" !important;\n    display: inline-block !important;\n    position: static !important;\n    flex: 0 0 auto;\n    min-width: 1.1em;\n    line-height: 1.45;\n  }\n  #vtilt-chat-widget .vtilt-md ol ol { counter-reset: vtilt-ol; }\n  #vtilt-chat-widget .vtilt-md li > :is(ul, ol) {\n    flex: 1 0 100% !important;\n    width: 100% !important;\n    margin: 0.25em 0 0 0 !important;\n    padding-left: 0.75em !important;\n  }\n\n  #vtilt-chat-widget .vtilt-md code {\n    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n    font-size: 0.9em;\n    background: rgba(0, 0, 0, 0.06);\n    padding: 0.1em 0.35em;\n    border-radius: 4px;\n  }\n  #vtilt-chat-widget .vtilt-md pre {\n    margin: 0.5em 0;\n    padding: 0.5em 0.65em;\n    border-radius: 6px;\n    background: rgba(0, 0, 0, 0.06);\n    overflow-x: auto;\n    white-space: pre-wrap;\n  }\n  #vtilt-chat-widget .vtilt-md pre code { background: none; padding: 0; }\n  #vtilt-chat-widget .vtilt-md blockquote {\n    margin: 0.5em 0;\n    padding-left: 0.75em;\n    border-left: 3px solid rgba(0, 0, 0, 0.15);\n  }\n  #vtilt-chat-widget .vtilt-md a { color: inherit; text-decoration: underline; }\n  #vtilt-chat-widget .vtilt-md br { line-height: inherit; }\n\n  /* Widget visitor bubble (brand color) */\n  #vtilt-chat-widget .vtilt-user-md code { background: rgba(255, 255, 255, 0.2); }\n  #vtilt-chat-widget .vtilt-user-md pre { background: rgba(255, 255, 255, 0.15); }\n  #vtilt-chat-widget .vtilt-user-md pre code { background: none; }\n  #vtilt-chat-widget .vtilt-user-md blockquote { border-left-color: rgba(255, 255, 255, 0.35); }\n";

package/dist/extensions/chat/message-html.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Convert stored message content to safe HTML for bubble rendering.
+ */
+export declare function formatMessageBodyHtml(text: string, contentType: "text" | "html" | "attachment", doc: Document | null): string;
+/** Plain-text preview for channel list (strips widgets and HTML). */
+export declare function plainTextMessagePreview(content: string, maxLength?: number): string;

package/dist/extensions/chat/message-markdown.d.ts

@@ -0,0 +1,8 @@
+/** Detect content that already contains HTML block-level tags. */
+export declare const HTML_BLOCK_TAG_RE: RegExp;
+/**
+ * Best-effort markdown → HTML. Returns input unchanged when it already looks like HTML.
+ */
+export declare function markdownToHtml(src: string): string;
+/** Whether markdown conversion should run before sanitization. */
+export declare function shouldUseMarkdownPipeline(contentType: "text" | "html" | "attachment", cleanText: string): boolean;

package/dist/extensions/chat/normalize-send-content.d.ts

@@ -0,0 +1,24 @@
+import type { SendChatMessageContent, SendChatMessageOptions } from "../../utils/globals";
+import type { ContentType } from "./types";
+/** Metadata key for markdown stored as `content_type: text`. Must match dashboard `message-rendering.ts`. */
+export declare const RICH_FORMAT_METADATA_KEY = "rich_format";
+export declare const RICH_FORMAT_MARKDOWN = "markdown";
+export interface NormalizedOutgoingMessage {
+    content: string;
+    content_type: ContentType;
+    metadata: Record<string, unknown>;
+}
+export declare function isRichUserMessage(message: {
+    content_type: string;
+    metadata?: Record<string, unknown>;
+}): boolean;
+/** Whether a stored message should use the rich HTML renderer in the widget. */
+export declare function messageUsesRichRendering(message: {
+    sender_type: string;
+    content_type: string;
+    metadata?: Record<string, unknown>;
+}): boolean;
+/**
+ * Normalize integrator input into stored message fields.
+ */
+export declare function normalizeSendChatMessageContent(input: SendChatMessageContent, options?: SendChatMessageOptions): NormalizedOutgoingMessage | null;

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

@@ -4,7 +4,9 @@
  * Type definitions for the chat widget extension.
  * Core types are re-exported from globals.ts for consistency.
  */
-export type { ChatMessage, ChatChannel, ChatChannelSummary, ChatConfig, ChatTheme, ChatWidgetView, LazyLoadedChatInterface, } from "../../utils/globals";
+export type { ChatMessage, ChatChannel, ChatChannelSummary, ChatConfig, ChatTheme, ChatWidgetView, LazyLoadedChatInterface, SendChatMessageContent, SendChatMessageOptions, } from "../../utils/globals";
+export { messageUsesRichRendering, normalizeSendChatMessageContent, } from "./normalize-send-content";
+export type { NormalizedOutgoingMessage } from "./normalize-send-content";
 /**
  * Sender types for chat messages
  */
@@ -45,75 +47,35 @@ export interface PresenceStatus {
     current_page_url?: string;
 }
 /**
- * Chat event names for analytics tracking
+ * Normalized channel event names for analytics tracking
  *
  * Message events are tracked client-side via capture() for full enrichment
- * (person properties, geo, device, referrer, etc.).
+ * (session, page URL, device, person properties, etc.).
  * Widget UI events (open/close) are exposed via callbacks in ChatConfig.
  *
- * All chat message events use a single event type ($chat_message) with properties:
- * - $sender_type: 'user' | 'ai' | 'agent'
- * - $channel_id: Chat channel ID
- * - $message_id: Message ID
+ * All channel message events use $channel_message with normalized properties:
+ * - $channel_type: channel discriminator ('chat', 'email', 'sms')
+ * - $conversation_id: conversation identifier
+ * - $message_id: message identifier
+ * - $direction: 'inbound' | 'outbound'
+ * - $sender_type: 'user' | 'ai' | 'agent' | 'system'
+ * - $content_preview: first 100 chars of content
  *
  * Tracking is gated by remote config:
  * - chatTracking.trackUserMessages → captures when $sender_type=user
  * - chatTracking.trackAgentMessages → captures when $sender_type=ai|agent
  */
-export declare const CHAT_EVENTS: {
-    /** Tracked client-side for all messages (user, AI, agent) */
-    readonly MESSAGE: "$chat_message";
+export declare const CHANNEL_EVENTS: {
+    readonly MESSAGE: "$channel_message";
 };
-/**
- * Chat event properties for $chat_message (server-side)
- */
-export interface ChatMessageEventProperties {
-    $channel_id: string;
-    $message_id: string;
-    $sender_type: SenderType;
-    $content_preview: string;
-    $ai_mode: boolean;
-    $word_count: number;
-}
-/**
- * @deprecated Use ChatMessageEventProperties instead
- */
-export interface ChatMessageSentEventProperties {
-    $channel_id: string;
+export interface ChannelMessageEventProperties {
+    $channel_type: string;
+    $conversation_id: string;
     $message_id: string;
-    $content_preview: string;
+    $direction: "inbound" | "outbound";
     $sender_type: SenderType;
-    $ai_mode: boolean;
-    $word_count: number;
-}
-/**
- * @deprecated Use ChatMessageEventProperties instead
- */
-export interface ChatMessageReceivedEventProperties {
-    $channel_id: string;
-    $message_id: string;
     $content_preview: string;
-    $sender_type: SenderType;
-    $response_time_ms?: number;
-}
-/**
- * Chat event properties for $chat_started
- */
-export interface ChatStartedEventProperties {
-    $channel_id: string;
-    $initiated_by: "user" | "agent";
-    $ai_mode: boolean;
-}
-/**
- * Chat event properties for $chat_closed
- */
-export interface ChatClosedEventProperties {
-    $channel_id: string;
-    $resolved_by: "agent" | "user" | "system" | "auto";
-    $resolution: "resolved" | "unresolved" | "abandoned";
-    $message_count: number;
-    $duration_seconds: number;
-    $ai_only: boolean;
+    $ai_mode?: boolean;
 }
 /**
  * Internal widget state

package/dist/extensions/chat/widget-registry.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Chat Widget Registry - Extensible widget system for AI-triggered UI.
+ * Tool calls from the AI are mapped to registered widgets; each widget provides render() and onAction().
+ */
+export interface WidgetContext {
+    channelId: string;
+    distinctId: string;
+    primaryColor: string;
+    /** @deprecated Use buildEndpointUrl() instead */
+    apiBase: string;
+    token: string;
+    /** The ID of the message containing this widget */
+    messageId: string;
+    /** Build a full URL for a given endpoint path, respecting api_host */
+    buildEndpointUrl(path: string): string;
+}
+export interface WidgetActionResult {
+    /** Whether the action succeeded — drives metadata-based re-render */
+    success?: boolean;
+    /** @deprecated Use metadata-driven rendering instead. Kept for custom widget compat. */
+    replaceHTML?: string;
+}
+export interface ChatWidgetDefinition {
+    /** Unique type identifier, e.g. "collect_email", "schedule_meeting" */
+    type: string;
+    /** AI tool description (sent to LLM so it knows when to invoke) */
+    toolDescription: string;
+    /** JSON schema shape for the tool parameters */
+    parameters: Record<string, {
+        type: string;
+        description: string;
+    }>;
+    /** Returns an HTML string to render inline in the chat bubble */
+    render(params: Record<string, unknown>, context: WidgetContext): string;
+    /** Called when the widget form is submitted or button clicked */
+    onAction(action: string, data: Record<string, unknown>, context: WidgetContext): Promise<WidgetActionResult>;
+}
+export declare class ChatWidgetRegistry {
+    private _widgets;
+    register(definition: ChatWidgetDefinition): void;
+    get(type: string): ChatWidgetDefinition | undefined;
+    getAll(): ChatWidgetDefinition[];
+    /**
+     * Build tool definitions for the AI from all registered widgets.
+     */
+    getToolDefinitions(): Record<string, {
+        description: string;
+        parameters: Record<string, {
+            type: string;
+            description: string;
+        }>;
+    }>;
+}

package/dist/extensions/chat/widgets/collect-email.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Built-in collect_email widget: renders name + email inputs, POSTs to widget actions API.
+ * UI state is metadata-driven — submitted state is rendered by _renderWidgets().
+ */
+import type { ChatWidgetDefinition } from "../widget-registry";
+export declare const collectEmailWidget: ChatWidgetDefinition;

package/dist/extensions/chat/widgets/escalate-to-human.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Built-in escalate_to_human widget: shows a "Connect with a human" button.
+ * UI state is metadata-driven — submitted state is rendered by _renderWidgets().
+ */
+import type { ChatWidgetDefinition } from "../widget-registry";
+export declare const escalateToHumanWidget: ChatWidgetDefinition;

package/dist/extensions/ga4-proxy.d.ts

@@ -0,0 +1,59 @@
+/**
+ * GA4 Proxy Feature
+ *
+ * Automatically configures gtag.js to send through vTilt's domain.
+ * When enabled, either reconfigures an existing gtag.js or loads a new one
+ * with server_container_url pointing to vTilt's proxy routes.
+ *
+ * Config sources (init config takes priority over remote config):
+ *   vt.init({ ga4: { measurementId: 'G-XXX' } })
+ *   /api/decide → { ga4: { measurementId: 'G-XXX' } }
+ */
+import type { VTiltConfig } from "../types";
+import type { Feature, FeatureConfig } from "../feature";
+export interface GA4ProxyConfig extends FeatureConfig {
+    measurementId?: string;
+    debugMode?: boolean;
+}
+export declare class GA4Proxy implements Feature {
+    readonly name = "GA4Proxy";
+    private _instance;
+    private _config;
+    private _isStarted;
+    private _pendingGtagCallbacks;
+    /** Fires once both client_id and session_id gtag callbacks complete. */
+    onIdentityResolved?: () => void;
+    constructor(instance: {
+        getConfig(): VTiltConfig;
+    }, config?: GA4ProxyConfig);
+    static extractConfig(config: VTiltConfig): GA4ProxyConfig;
+    get isEnabled(): boolean;
+    get isStarted(): boolean;
+    startIfEnabled(): void;
+    stop(): void;
+    /**
+     * Sync user_id to gtag.js so both proxy and MP event streams share
+     * the same identity after identify(). GA4 Realtime uses user_id as
+     * the highest-priority identifier; without this, proxy events (no
+     * user_id) and MP events (with user_id) count as separate users.
+     */
+    setUserId(userId: string | null): void;
+    onConfigUpdate(config: VTiltConfig): void;
+    private _start;
+    private _getApiBase;
+    private _hasGtag;
+    private _reconfigureExistingGtag;
+    private _loadAndConfigureGtag;
+    /**
+     * Use gtag('get', ...) to obtain the authoritative client_id and
+     * session_id from gtag.js. Fires onIdentityResolved once BOTH
+     * callbacks have completed (counter-based).
+     */
+    private _resolveGtagIdentity;
+    /**
+     * Fires after each gtag('get', ...) callback. When all pending callbacks
+     * have settled, notifies the host (EventBuffer) so buffered MP events
+     * can flush with stable GA4 IDs (same client_id as gtag.js).
+     */
+    private _onGtagCallbackSettled;
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Consent Mode v2 bridge.
+ *
+ * Maps vTilt's 3-boolean consent (analytics / marketing / advertising) to
+ * Google's 4-key Consent Mode v2 payload (ad_storage, ad_user_data,
+ * ad_personalization, analytics_storage) and pushes it through gtag.
+ *
+ * Mapping (default):
+ *   advertising -> ad_storage + ad_user_data + ad_personalization
+ *   analytics   -> analytics_storage
+ *   marketing is not sent to Google by default (it covers email/SMS, not ads).
+ *
+ * Admin UI may override individual keys (`consentOverride`) to hard-wire a
+ * specific value regardless of user consent — useful for jurisdictions or
+ * projects with fixed policies.
+ */
+import type { ConsentState } from "../../core/consent";
+import type { GoogleConsentOverride } from "../../types";
+export type GtagFn = (...args: unknown[]) => void;
+export type GoogleConsentPayload = Record<"ad_storage" | "ad_user_data" | "ad_personalization" | "analytics_storage", "granted" | "denied">;
+export declare function buildConsentPayload(consent: ConsentState, override?: GoogleConsentOverride): GoogleConsentPayload;
+/**
+ * Send the default consent state BEFORE gtag.js loads so that every
+ * subsequent request carries the right flags. Call once at feature start.
+ */
+export declare function pushConsentDefault(gtag: GtagFn, consent: ConsentState, override?: GoogleConsentOverride): void;
+export declare function pushConsentUpdate(gtag: GtagFn, consent: ConsentState, override?: GoogleConsentOverride): void;