@v-tilt/browser 1.12.0 → 1.13.0

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

@@ -35,6 +35,15 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     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;
@@ -58,6 +67,26 @@ 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>;
@@ -93,6 +122,13 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
     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;
     /**
@@ -155,13 +191,107 @@ export declare class LazyLoadedChat implements LazyLoadedChatInterface {
      */
     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 _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;
+    /**
+     * 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;
     /**