@v-tilt/browser 1.12.0 → 1.13.1

package/dist/entrypoints/all-external-dependencies.d.ts

@@ -1,8 +1,15 @@
 /**
- * All External Dependencies
+ * Lazy extension entrypoints bundled into `array.full*` / `module.full*` builds.
  *
- * This file imports all external dependency entrypoints.
- * Used by array.full.ts for the full bundle that includes everything.
+ * Registers factories on `window.__VTiltExtensions__` so `loadExternalDependency`
+ * is skipped when these bundles are used with `disable_external_dependency_loading`.
+ *
+ * **Chat is intentionally excluded** — same as PostHog's `all-external-dependencies.ts`
+ * (recorder, surveys, web-vitals, … but not `conversations`). Chat is ~60 KB gzip
+ * and not every site uses it. Opt in via:
+ * - `array.chat.js` / `module.chat.es.js` (core + chat only)
+ * - `array.full.chat.js` / `module.full.chat.es.js` (recorder + vitals + chat)
+ * - side-effect `import "./chat"` before `vt.init()` (bundler)
  */
 import "./recorder";
 import "./web-vitals";

package/dist/entrypoints/array.chat.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Core snippet plus chat — equivalent to loading `array.js` and `chat.js`
+ * together. Chat registers on `__VTiltExtensions__` at parse time so there is
+ * no second network request for `chat.js`.
+ *
+ * Usage:
+ *   <script src="https://cdn.example.com/dist/array.chat.js"></script>
+ */
+import "./chat";
+import "./array";

package/dist/entrypoints/array.chat.no-external.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `array.chat.js` with external script injection disabled at runtime.
+ * Pair with `disable_external_dependency_loading: true` in `vt.init()`.
+ */
+import "./chat";
+import "./array.no-external";

package/dist/entrypoints/array.full.chat.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Full IIFE bundle with chat pre-registered on `__VTiltExtensions__`.
+ *
+ * Use when the chat widget must be ready immediately (hero CTAs, programmatic
+ * `vt.sendChatMessage()` on first paint) without a second script request.
+ *
+ * PostHog equivalent: load `array.js` and side-effect-import `conversations.js`,
+ * or use their bundler pattern:
+ *   import "posthog-js/dist/conversations"
+ */
+import "./all-external-dependencies";
+import "./chat";
+import "./array";

package/dist/entrypoints/array.full.chat.no-external.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Full IIFE bundle with recorder, web-vitals, and chat pre-registered.
+ * Pair with `disable_external_dependency_loading: true`.
+ */
+import "./all-external-dependencies";
+import "./chat";
+import "./array.no-external";

package/dist/entrypoints/array.full.d.ts

@@ -1,17 +1,13 @@
 /**
- * Full Bundle Entrypoint
- *
- * Same as array.ts but includes all external dependencies bundled in.
- * This is useful for users who want a single script tag without lazy loading.
+ * Full IIFE bundle — core SDK plus session recording and web vitals
+ * pre-registered on `__VTiltExtensions__`.
  *
  * Usage:
  *   <script src="https://cdn.example.com/dist/array.full.js"></script>
  *
- * This bundle includes:
- * - Core SDK (array.no-external.ts)
- * - External scripts loader
- * - Session recording (rrweb)
- * - Web Vitals tracking
+ * Does **not** include chat (PostHog keeps conversations out of `array.full` too).
+ * For chat without a second request, use `array.chat.js` (core + chat) or
+ * `array.full.chat.js` (also includes recorder and web vitals).
  */
 import "./all-external-dependencies";
 import "./array";

package/dist/entrypoints/array.full.no-external.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Full IIFE bundle with external script loading disabled at runtime.
+ *
+ * Same as `array.full.ts` but intended for use with
+ * `disable_external_dependency_loading: true` — extensions are already on
+ * `__VTiltExtensions__`. PostHog equivalent: `array.full.no-external.ts`.
+ *
+ * Does not include chat; use `array.full.chat.no-external.ts` when chat must
+ * be pre-registered without a separate network request.
+ */
+import "./all-external-dependencies";
+import "./array.no-external";

package/dist/entrypoints/module.chat.es.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ESM core bundle with chat pre-registered — bundler equivalent of `array.chat.js`.
+ */
+import "./chat";
+import vt from "./module.es";
+export * from "./module.es";
+export default vt;

package/dist/entrypoints/module.full.chat.es.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Full ESM bundle with chat pre-registered — no extra `chat.js` fetch.
+ *
+ * PostHog equivalent:
+ *   import "posthog-js/dist/conversations"
+ *   import posthog from "posthog-js/dist/module.no-external"
+ */
+import "./all-external-dependencies";
+import "./chat";
+import vt from "./module.es";
+export * from "./module.es";
+export default vt;

package/dist/entrypoints/module.full.es.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Full ESM bundle — core SDK plus recorder and web-vitals pre-registered on
+ * `__VTiltExtensions__`. Same role as PostHog's `module.full.es.ts`.
+ *
+ * Chat is not included (see `module.full.chat.es.ts` or side-effect-import
+ * `./chat` before init). Matches PostHog keeping `conversations` out of the
+ * default full bundle because of bundle size.
+ */
+import "./all-external-dependencies";
+import vt from "./module.es";
+export * from "./module.es";
+export default vt;

package/dist/entrypoints/module.no-external.es.d.ts

@@ -1,4 +1,5 @@
 export { VTilt } from "../vtilt";
 export * from "../types";
+export { VTILT_SNIPPET_STUB_METHODS, VTILT_SNIPPET_STUB_METHOD_NAMES, type VtiltSnippetStubMethodName, } from "../snippet-stub-methods";
 export declare const vt: import("../vtilt").VTilt;
 export default vt;

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

@@ -8,6 +8,14 @@
 interface DraggableOptions {
     /** Element that initiates the drag (defaults to the target element itself) */
     handle?: HTMLElement;
+    /**
+     * Fired after the element settles at a new position: initial restore
+     * from localStorage, drag end, and viewport resize re-clamp. The chat
+     * widget uses this to recompute the panel's opening direction so the
+     * panel always extends into whichever side of the viewport has more
+     * room (see `usePanelAnchor` in `ui/ChatRoot.tsx`).
+     */
+    onPositionChange?: () => void;
 }
 interface DragHandle {
     destroy: () => void;
@@ -15,13 +23,20 @@ interface DragHandle {
 /**
  * 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.
+ * @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.
+ * @param opts.onPositionChange   Called after the element settles —
+ *                                initial restore, drag end, and viewport
+ *                                resize re-clamp. Used by the chat widget
+ *                                to recompute the panel's opening
+ *                                direction.
  *
  * - Restores persisted position from localStorage on attach.
- * - Persists position on drag end.
+ * - Persists position on drag end (and on resize when the clamp had to
+ *   correct an out-of-bounds value, so the next page load is consistent).
  * - 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.

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

@@ -50,6 +50,7 @@ export declare class ChatWrapper extends LazyFeature<ChatConfig, LazyLoadedChatI
     private _connectionCallbacks;
     /** True after vt.showChat() so preloaded widget stays visible after replacing the lightweight bubble. */
     private _bubbleExplicitShow;
+    private _unreadPollIntervalId;
     constructor(instance: VTilt, config?: ChatConfig);
     static extractConfig(config: VTiltConfig): ChatConfig;
     get isEnabled(): boolean;
@@ -79,19 +80,24 @@ export declare class ChatWrapper extends LazyFeature<ChatConfig, LazyLoadedChatI
     selectChannel(channelId: string): void;
     createChannel(): void;
     goToChannelList(): void;
-    sendMessage(content: SendChatMessageContent, options?: SendChatMessageOptions): void;
+    sendMessage(content: SendChatMessageContent, options?: SendChatMessageOptions): Promise<void>;
     markAsRead(): void;
     registerWidget(definition: Parameters<NonNullable<LazyLoadedChatInterface["registerWidget"]>>[0]): void;
     onMessage(callback: MessageCallback): Unsubscribe;
     onTyping(callback: TypingCallback): Unsubscribe;
     onConnectionChange(callback: ConnectionCallback): Unsubscribe;
-    updateConfig(config: Partial<ChatConfig>): void;
+    private _isBubbleDraggable;
     getMergedConfig(): ChatConfig;
+    /** Apply corner + inset to the lightweight bubble and/or loaded shadow host. */
+    private _syncBubbleLayout;
     destroy(): void;
     private _fetchServerSettings;
     private _fetchUnreadForBubble;
     private _showBubble;
     private _onVisibilityChange;
+    private _shouldPollUnread;
+    private _startUnreadPoll;
+    private _stopUnreadPoll;
     private _schedulePreload;
     private _lazyLoadAndThen;
 }

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

@@ -1,223 +1,23 @@
 /**
- * Chat Widget - Lazy loaded chat implementation using Ably for real-time messaging.
+ * Chat Widget — thin re-export shim.
+ *
+ * The entire chat implementation moved to a layered architecture as part of
+ * the May 2026 Preact rewrite. The previous monolithic ~3800-line class
+ * (`LazyLoadedChat`) is now decomposed into:
+ *
+ *   - controller/  (chat-controller, ably-client, ably-handlers, ably-token,
+ *                   message-stream) — orchestration and Ably transport
+ *   - store/       (chat-store)     — signal-based reactive state
+ *   - ui/          (ChatRoot.tsx + components + hooks)
+ *                                   — Preact components rendered in a Shadow DOM
+ *   - widgets/     (collect-email.tsx, escalate-to-human.tsx)
+ *                                   — built-in tool widgets (Preact)
+ *
+ * See `docs/modules/chat/widget-architecture.md` for the full architecture.
+ *
+ * This file remains so external callers (`entrypoints/chat.ts`,
+ * `ChatWrapper`, tests) can keep importing `LazyLoadedChat` from
+ * `extensions/chat/chat` unchanged. New code should import the controller
+ * and store directly from their own modules.
  */
-import type { VTilt } from "../../vtilt";
-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;
-    private _state;
-    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;
-    private _typingDebounce;
-    private _isUserTyping;
-    private _initialUserReadAt;
-    private _isMarkingRead;
-    private _widgetRegistry;
-    /** Tracks whether show() was explicitly called (vs open() temporarily revealing the container). */
-    private _bubbleExplicitShow;
-    constructor(instance: VTilt, config?: ChatConfig);
-    get isOpen(): boolean;
-    get isConnected(): boolean;
-    get isLoading(): boolean;
-    get unreadCount(): number;
-    get channel(): ChatChannel | null;
-    get channels(): ChatChannelSummary[];
-    get currentView(): ChatWidgetView;
-    private get _theme();
-    private get _distinctId();
-    /**
-     * Track a chat message event via the SDK capture pipeline.
-     * Gated by remote config chatTracking settings.
-     *
-     * - User messages: only if chatTracking.trackUserMessages is enabled
-     * - AI/Agent messages: only if chatTracking.trackAgentMessages is enabled
-     */
-    private _trackChatMessage;
-    open(): void;
-    close(): void;
-    toggle(): void;
-    show(): void;
-    hide(): void;
-    getChannels(): Promise<void>;
-    selectChannel(channelId: string): Promise<void>;
-    createChannel(): 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;
-    /**
-     * Calculate unread count based on messages and user_last_read_at
-     * (unread agent/AI messages for the user)
-     */
-    private _calculateUnreadCount;
-    onMessage(callback: MessageCallback): Unsubscribe;
-    onTyping(callback: TypingCallback): Unsubscribe;
-    onConnectionChange(callback: ConnectionCallback): Unsubscribe;
-    destroy(): void;
-    /**
-     * 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.
-     */
-    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;
-    private _getChannelItemHTML;
-    private _getConversationHTML;
-    private _attachChannelListListeners;
-    private _attachConversationListeners;
-    private _formatRelativeTime;
-    private _renderMessages;
-    private _getMessageHTML;
-    private _isMessageReadByAgent;
-    /**
-     * Handle streaming AI response
-     * Industry standard: Real-time streaming with progressive UI updates
-     */
-    private _handleStreamingResponse;
-    /**
-     * Remove temporary message by ID
-     */
-    private _removeTempMessage;
-    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;
-}
+export { ChatController as LazyLoadedChat } from "./controller/chat-controller";

package/dist/extensions/chat/controller/__tests__/fakes/ably-realtime-fake.d.ts

@@ -0,0 +1,84 @@
+/**
+ * In-memory fake of Ably's `BaseRealtime` surface used by AblyClient tests.
+ *
+ * Only models the parts the chat layer actually touches:
+ * - `connection` with `state` + `.on(event, handler)` events
+ *   for "connected" | "disconnected" | "suspended" | "failed"
+ * - `auth.clientId`, `auth.authorize(token)`
+ * - `channels.get(name)` returning a FakeRealtimeChannel with attach/detach,
+ *   subscribe/unsubscribe/publish, and a `state` machine that can be driven
+ *   programmatically.
+ * - `channels.release(name)`
+ * - `connect()` / `close()`
+ *
+ * The Ably typings are wide and surface lots of unrelated APIs; rather than
+ * fight them we expose this fake with its own minimal types and only cast
+ * to `BaseRealtime` at the construction site.
+ */
+import type { ChannelState, ChannelStateChange, TokenRequest } from "ably";
+import type { BaseRealtime } from "ably/modular";
+type Handler<T> = (event: T) => void;
+export declare class FakeRealtimeChannel {
+    readonly name: string;
+    state: ChannelState;
+    readonly subscriptions: Map<string, ((msg: {
+        data: unknown;
+    }) => void)[]>;
+    readonly published: Array<{
+        event: string;
+        data: unknown;
+    }>;
+    attachCalls: number;
+    detachCalls: number;
+    private _stateListeners;
+    private _attachResolvers;
+    constructor(name: string);
+    attach(): Promise<void>;
+    /** Test helper to resolve a pending attach. */
+    resolveAttach(): void;
+    /** Test helper to reject a pending attach. */
+    rejectAttach(err: unknown): void;
+    detach(): Promise<void>;
+    setState(next: ChannelState): void;
+    on(handler: Handler<ChannelStateChange>): void;
+    off(handler: Handler<ChannelStateChange>): void;
+    subscribe(event: string, callback: (msg: {
+        data: unknown;
+    }) => void): void;
+    unsubscribe(): void;
+    publish(event: string, data: unknown): Promise<void>;
+    /** Drive an inbound message for tests. */
+    emit(event: string, data: unknown): void;
+}
+export declare class FakeAuth {
+    clientId: string | null;
+    authorizeCalls: number;
+    shouldFailAuthorize: boolean;
+    authorize(token: TokenRequest): Promise<void>;
+}
+export type ConnectionState = "initialized" | "connecting" | "connected" | "disconnected" | "suspended" | "closing" | "closed" | "failed";
+export declare class FakeConnection {
+    state: ConnectionState;
+    private _listeners;
+    on(event: string, handler: Handler<unknown>): void;
+    emit(event: ConnectionState): void;
+}
+export declare class FakeChannels {
+    releaseCalls: string[];
+    private _registry;
+    get(name: string): FakeRealtimeChannel;
+    release(name: string): void;
+}
+export declare class FakeBaseRealtime {
+    connectCalls: number;
+    closeCalls: number;
+    readonly connection: FakeConnection;
+    readonly auth: FakeAuth;
+    readonly channels: FakeChannels;
+    constructor();
+    connect(): void;
+    close(): void;
+    /** Cast helper to satisfy AblyClient's constructor signature. */
+    asBaseRealtime(): BaseRealtime;
+}
+export {};