@v-tilt/browser 1.13.0 → 1.13.1

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

package/dist/extensions/chat/controller/ably-client.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Ably client wrapper for the chat widget.
+ *
+ * Owns the `BaseRealtime` lifecycle (connect/disconnect), the channel
+ * registry (notifications + per-conversation message + per-conversation
+ * typing), and the race-safe attach/detach flow.
+ *
+ * Writes connection state into the store; reads channel routing from the
+ * store. Does NOT mutate `messages` / `channels` / `typing` signals
+ * directly — those flow through the `applyMessage` / `applyNotification`
+ * / `applyTyping` handlers in `ably-handlers.ts`.
+ *
+ * See: docs/modules/chat/widget-architecture.md (Ably layer)
+ */
+import { BaseRealtime } from "ably/modular";
+import type { ApiRequestInstance } from "../chat-api";
+import type { ChatStore } from "../store/chat-store";
+import { type TypingPayload } from "./ably-handlers";
+/**
+ * Hooks the controller plugs into the client so domain decisions stay in
+ * the controller (e.g. how to react to an inbound message). The client
+ * only owns the Ably mechanics.
+ */
+export interface AblyClientHooks {
+    getDistinctId: () => string;
+    onIdentityChange: () => void;
+    onNewChannelNotification: () => void;
+    onAgentMessageWhileOpen: () => void;
+    onMessageTrack: (m: import("../../../utils/globals").ChatMessage) => void;
+    onMessageDispatched: (m: import("../../../utils/globals").ChatMessage) => void;
+    onTypingDispatched: (isTyping: boolean, senderName: string) => void;
+}
+/**
+ * Wire `BaseRealtime` lazily — keeps tests free of the constructor side
+ * effect of opening a WebSocket.
+ */
+export type BaseRealtimeFactory = (options: ConstructorParameters<typeof BaseRealtime>[0]) => BaseRealtime;
+export declare class AblyClient {
+    private readonly instance;
+    private readonly store;
+    private readonly hooks;
+    private _client;
+    private _notificationsChannel;
+    private _conversationChannel;
+    private _typingChannel;
+    /**
+     * Latest in-flight pre-attach teardown. `_doAttach` must `await` this so a
+     * newly-requested attach never calls `auth.authorize()` while a previous
+     * channel is still attached — Ably re-validates ALL attached channels
+     * against the new token and the previous one would fail with 40160.
+     */
+    private _teardownInFlight;
+    private _factory;
+    constructor(instance: ApiRequestInstance, store: ChatStore, hooks: AblyClientHooks, factory?: BaseRealtimeFactory);
+    /**
+     * Expose the live clientId (used by `authCallback` mismatch guard and by
+     * the controller's identity-change detector on the `connected` event).
+     */
+    get clientId(): string | null;
+    /**
+     * Whether we already own a live (or live-ish) client. Multiple calls to
+     * `ensureConnected()` are idempotent — the first one creates the client,
+     * the rest no-op.
+     */
+    get isLive(): boolean;
+    /** Currently-attached per-conversation channel id (null on list view). */
+    get currentChannelId(): string | null;
+    /**
+     * Idempotently bootstrap the Ably client and attach to the project
+     * notifications channel. Safe to call from `open()` and on first load.
+     */
+    ensureConnected(): Promise<void>;
+    /**
+     * Refresh the Ably token, optionally scoping it to a specific channel.
+     * Refuses to authorize on a `failed` connection (terminal — only fix is
+     * to recreate the client, which the identity-change hook does).
+     */
+    refreshToken(channelId?: string): Promise<boolean>;
+    /**
+     * Subscribe to per-conversation messages + typing for `channelId`.
+     *
+     * Atomic swap semantics: `realtimeChannelId` and `realtimeAttached`
+     * still reflect the **last successful attach** for the entire duration
+     * of this method — they only flip to `channelId` after both the main
+     * and typing channels have attached and subscribed. This means
+     * `realtimeReady` (and therefore the "Connecting…" banner) does not
+     * blink during normal channel switches; the worst case is a slightly
+     * stale `realtimeChannelId` for a few ms while the new channel
+     * negotiates, which is harmless because:
+     *
+     * - Stale inbound frames are filtered by the `_conversationChannel !==
+     *   mainChannel` ref guard inside the subscribe callbacks.
+     * - `realtimeReady` already requires `realtimeChannelId === channel.value.id`,
+     *   so once the new channel.value is set the computed signal correctly
+     *   reads false until the swap completes.
+     *
+     * Concurrent navigations (rapid switch / goToChannelList) are caught
+     * by `wasSuperseded()` and the `pendingRealtimeChannelId` guard before
+     * the final write.
+     *
+     * Before refreshing the token this method awaits any previously-attached
+     * conversation channels' detach, so the `auth.authorize()` call in
+     * `refreshToken()` cannot trigger an Ably 40160 capability check against
+     * the old channel.
+     */
+    attachConversation(channelId: string): Promise<void>;
+    /**
+     * Detach + release the per-conversation channels. Safe to call from
+     * `close()`, `goToChannelList()`, and rapid switching paths.
+     *
+     * Tracks the in-flight teardown on `_teardownInFlight` so the next
+     * `attachConversation()` can await it before refreshing the token.
+     */
+    detachConversation(): Promise<void>;
+    /** Synchronously clear the channel refs and kick off async detach.
+     *
+     *  Does NOT touch `realtimeChannelId` / `realtimeAttached` — those reflect
+     *  the last successful attach and are owned by `attachConversation()`
+     *  (which swaps them atomically when the new channel is fully ready) and
+     *  by `disconnectAll()` (which clears them on full teardown). Leaving
+     *  them intact during a channel-switch detach is what kills the
+     *  "Connecting…" flash; see widget-architecture.md §"Atomic realtime
+     *  swap". */
+    private _teardownActive;
+    /** Publish a typing event on the active typing channel. Best-effort. */
+    publishTyping(payload: TypingPayload & {
+        sender_id: string;
+    }): void;
+    /**
+     * Full teardown — detach all channels, close the Ably connection, reset
+     * the store's realtime signals. Used on `destroy()` and identity change.
+     */
+    disconnectAll(): Promise<void>;
+    /**
+     * After a `connected` event, if the live clientId no longer matches the
+     * distinct id we authorized for (e.g. the page slept through an identity
+     * change), trigger a full client recreate.
+     */
+    private _checkClientIdDrift;
+    /**
+     * Unsubscribe + detach. We intentionally do NOT call
+     * `client.channels.release()` here.
+     *
+     * Ably's `channels.release(name)` removes the channel object from the
+     * client's local registry. Any inbound WebSocket frame that arrives for
+     * that name afterwards triggers the library's
+     * "received event for non-existent channel" warning, because dispatch
+     * looks the channel up in the same registry. In-flight typing and
+     * message frames are easy to land after a detach on a rapid switch, so
+     * release-on-switch deterministically surfaces the warning.
+     *
+     * Per Ably's guidance, `release()` is for permanent cleanup. For
+     * conversation switching we just `unsubscribe()` + `detach()`; the
+     * channel object stays in the registry with no listeners and any
+     * residual frames are silently ignored. Full cleanup happens in
+     * `disconnectAll()` via `client.close()`, which tears down the
+     * connection without per-channel release.
+     */
+    private _teardownChannel;
+}

package/dist/extensions/chat/controller/ably-handlers.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Pure functions that translate inbound Ably events into store mutations.
+ *
+ * No DOM, no fetch, no Ably types — only the wire shapes of the messages
+ * Ably delivers to us. Easy to unit-test against a fake `BaseRealtime`.
+ *
+ * See: docs/modules/chat/widget-architecture.md (Message-arrival contract)
+ */
+import type { ChatMessage } from "../../../utils/globals";
+import type { ChatStore } from "../store/chat-store";
+export interface NotificationPayload {
+    type: string;
+    channel_id: string;
+    data?: Record<string, unknown>;
+}
+export interface TypingPayload {
+    sender_type: string;
+    sender_name: string | null;
+    is_typing: boolean;
+}
+export interface ReadCursorPayload {
+    reader_type: "user" | "agent";
+    reader_id: string | null;
+    read_at: string;
+}
+/**
+ * Insert or replace a message in the array. Pure id-based reconciliation:
+ * because the SDK mints the user message id client-side and the AI bubble
+ * adopts the persisted id from the streaming response header, every
+ * inbound payload arrives with the same identity the bubble already
+ * displays — no content+sender heuristic, no temp-id matching.
+ *
+ * Two special cases preserved:
+ *
+ * 1. Streaming `_widgets` metadata: if the local bubble accumulated
+ *    `_widgets` (from inline tool-call markers) and the Ably echo doesn't
+ *    carry an authoritative `widgets`, we merge the local `_widgets`
+ *    into the persisted row so the form / button doesn't disappear.
+ *
+ * 2. Legacy `temp-ai-*` fallback: very old servers (or a stream that
+ *    failed to pre-create its row) leave the SDK with a `temp-ai-*` id.
+ *    When a persisted AI message arrives we swap the first such row so
+ *    the user still sees a single bubble.
+ *
+ * Returns the **same array reference** when nothing actually changed
+ * (incoming matches an existing row by deep field equality). This lets
+ * memoised components (MessageBubble) skip re-renders on duplicate
+ * echoes, which is critical for streaming throughput where the same
+ * message id can be re-published multiple times.
+ */
+export declare function upsertMessage(messages: ChatMessage[], incoming: ChatMessage): ChatMessage[];
+/** Returns true when the message id is already in the array. */
+export declare function hasMessage(messages: ChatMessage[], id: string): boolean;
+/**
+ * Apply an inbound chat message to the store. Performs the upsert, updates
+ * unread counts (skipping when the user is currently viewing this channel),
+ * and clears the typing indicator.
+ *
+ * `currentUserDistinctId` is consulted only to suppress duplicate side
+ * effects on the user's own echoes — the upsert itself is pure id-based.
+ *
+ * `onAgentMessageWhileOpen` is invoked when an agent/AI message arrives
+ * while the widget is open and viewing this channel — used by the
+ * controller to schedule `markAsRead`.
+ *
+ * `onTrack` is invoked for agent/AI messages so the controller can forward
+ * to the SDK's `capture()` pipeline and `config.onMessageReceived` callback.
+ */
+export declare function applyMessage(store: ChatStore, incoming: ChatMessage, currentUserDistinctId: string | null, callbacks: {
+    onAgentMessageWhileOpen: () => void;
+    onTrack: (m: ChatMessage) => void;
+    onMessageDispatched: (m: ChatMessage) => void;
+}): void;
+/**
+ * Handle project-level notifications (new channels, channel updates, closes).
+ * Updates the channel list and total badge count in real time without
+ * touching `messages` — message-list updates flow through the per-channel
+ * Ably channel.
+ */
+export declare function applyNotification(store: ChatStore, notification: NotificationPayload, callbacks: {
+    onNewChannel: () => void;
+}): void;
+/**
+ * Apply an inbound typing event. The user's own typing events are echoed
+ * back from Ably and must be ignored here so the indicator only reflects
+ * the other party.
+ */
+export declare function applyTyping(store: ChatStore, event: TypingPayload, callbacks: {
+    onTyping: (isTyping: boolean, senderName: string) => void;
+}): void;
+/**
+ * Apply an agent read-cursor advance. User cursors are not needed in the
+ * widget because the widget *is* the user.
+ */
+export declare function applyReadCursor(store: ChatStore, event: ReadCursorPayload): void;

package/dist/extensions/chat/controller/ably-token.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Ably token provisioning for the chat widget.
+ *
+ * - `requestToken()` performs the initial token request before the Ably
+ *   client is created.
+ * - `createAuthCallback()` builds the `authCallback` Ably calls when it
+ *   needs to refresh or scope a token (e.g. attaching to a per-channel
+ *   subscription). The callback guards against clientId mismatches (40102)
+ *   that would land the connection in the terminal `failed` state.
+ *
+ * No DOM, no Ably types — just `fetch` + the wire payload + a thin
+ * `IdentityChangeHook` callback for the rare clientId drift case.
+ *
+ * See: docs/modules/chat/widget-architecture.md (Race-free identity changes)
+ */
+import type { TokenRequest } from "ably";
+import { type ApiRequestInstance } from "../chat-api";
+export interface InitialTokenResponse {
+    tokenRequest: TokenRequest;
+    clientId: string;
+    projectId: number;
+}
+/** Wire payload returned by the widget token endpoint. */
+interface RawTokenResponse {
+    success: boolean;
+    tokenRequest: TokenRequest;
+    clientId?: string;
+    project_id?: number;
+}
+/**
+ * Request an Ably token from the widget endpoint.
+ *
+ * Returns `null` when the request fails — the caller should bail out and
+ * leave the store in `connectionState: "failed"`.
+ */
+export declare function requestToken(instance: ApiRequestInstance, distinctId: string, channelId?: string): Promise<RawTokenResponse | null>;
+/**
+ * Request the initial token used to bootstrap the Ably client. Asserts that
+ * `clientId` and `project_id` are present, since both are required to
+ * authorize the connection.
+ */
+export declare function requestInitialToken(instance: ApiRequestInstance, distinctId: string): Promise<InitialTokenResponse | null>;
+/**
+ * Provide the live Ably client's clientId. Returning `null` short-circuits
+ * the mismatch guard (used in tests / before the client exists).
+ */
+export type LiveClientIdAccessor = () => string | null;
+/** Notify the controller that a clientId drift was detected. */
+export type IdentityChangeHook = () => void;
+/**
+ * Build an Ably `authCallback`. Each refresh:
+ *
+ * 1. Calls the widget token endpoint with the *current* channel scope
+ *    (derived from the store's `realtimeChannelId` / `pendingRealtimeChannelId`).
+ * 2. Verifies the token's `clientId` matches the live connection's
+ *    `clientId`. If they differ, refuses the token and fires the identity
+ *    change hook — refusing here prevents Ably from transitioning to the
+ *    terminal `failed` state.
+ */
+export declare function createAuthCallback(args: {
+    instance: ApiRequestInstance;
+    getDistinctId: () => string;
+    getChannelScope: () => string | null;
+    getLiveClientId: LiveClientIdAccessor;
+    onIdentityChange: IdentityChangeHook;
+}): (_: unknown, cb: (err: string | null, token: TokenRequest | null) => void) => Promise<void>;
+export {};

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

@@ -0,0 +1,194 @@
+/**
+ * ChatController — orchestrates the chat widget.
+ *
+ * - Implements `LazyLoadedChatInterface` (the public SDK surface)
+ * - Owns the ChatStore (state)
+ * - Owns the AblyClient (realtime transport)
+ * - Performs HTTP calls (channel CRUD, message send, mark-read)
+ * - Mounts the Preact UI inside a Shadow DOM via `mountChatUI()`
+ *
+ * No DOM logic lives here beyond mount/unmount — components read signals
+ * directly and emit user intent back to the controller through props.
+ *
+ * See: docs/modules/chat/widget-architecture.md
+ */
+import { type ChatChannel, type ChatChannelSummary, type ChatConfig, type ChatWidgetView, type LazyLoadedChatInterface, type SendChatMessageContent, type SendChatMessageOptions } from "../../../utils/globals";
+import type { VTilt } from "../../../vtilt";
+import { type ConnectionCallback, type MessageCallback, type TypingCallback, type Unsubscribe } from "../types";
+import { ChatWidgetRegistry, type ChatWidgetDefinition, type WidgetContext } from "../widget-registry";
+import { ChatStore, DEFAULT_THEME } from "../store/chat-store";
+export declare class ChatController implements LazyLoadedChatInterface {
+    private _instance;
+    private _config;
+    private _store;
+    private _ably;
+    private _ui;
+    private _registry;
+    private _messageCallbacks;
+    private _typingCallbacks;
+    private _connectionCallbacks;
+    private _lastConnectedNotified;
+    private _unsubscribeIdentity;
+    private _unsubscribeReset;
+    private _identityChangeInFlight;
+    private _typingIdleTimer;
+    private _isUserTyping;
+    private _lastTypingPublishAt;
+    private _lastTypingActivityAt;
+    private _pendingTypingIntent;
+    private _disposeRealtimeReadyWatcher;
+    private _isMarkingRead;
+    private _streamAbort;
+    private _streamingMessageId;
+    /** Local typing dot shown before the HTTP response headers arrive. */
+    private _optimisticAiTyping;
+    private _openedAt;
+    private _disposeConnectionWatcher;
+    private _outbox;
+    /** Distinct id the active outbox storage key was opened for. */
+    private _outboxDistinctId;
+    private _drainInFlight;
+    private _drainTimer;
+    private readonly _onOutboxOnline;
+    private readonly _onOutboxVisible;
+    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;
+    /** Exposed so components can read the live store inside JSX. */
+    get store(): ChatStore;
+    /** Exposed so the widget slot can look up custom definitions. */
+    get widgets(): ChatWidgetRegistry;
+    get theme(): typeof DEFAULT_THEME;
+    get config(): ChatConfig;
+    open(): void;
+    close(): void;
+    /** Drop per-channel subs and close Ably — badge while closed uses Tier A REST. */
+    private _teardownRealtimeOnClose;
+    /**
+     * Tier A closed-badge: apply aggregate unread from `GET /api/chat/widget/unread`
+     * (called by `chat-wrapper` poll / visibility refresh).
+     */
+    applyPolledUnreadCount(count: number): void;
+    toggle(): void;
+    private _bubbleExplicitShow;
+    show(): void;
+    hide(): void;
+    getChannels(): Promise<void>;
+    selectChannel(channelId: string): Promise<void>;
+    /**
+     * Create a new conversation channel.
+     *
+     * `options.skipGreeting` tells the server not to seed the AI welcome
+     * message (used when the user is initiating the conversation via
+     * `sendChatMessage` and their own message will arrive immediately after).
+     *
+     * `options.preserveMessages` keeps any messages already in the store
+     * (e.g. an optimistic user temp message inserted before the create call)
+     * and merges them with the server response — server messages first, then
+     * any local `temp-` rows we still have. This is what powers the
+     * "show the user's message instantly while the channel is being
+     * created" UX path.
+     */
+    createChannel(options?: {
+        skipGreeting?: boolean;
+        preserveMessages?: boolean;
+    }): Promise<void>;
+    goToChannelList(): void;
+    /** Abort the in-flight AI stream and remove its partial bubble. */
+    private _cancelActiveStream;
+    /**
+     * Remove AI bubbles trailing the last user message — used when a new send
+     * aborts an in-flight stream before `onStreamStart` registered its id.
+     */
+    private _stripTrailingAiAfterLastUser;
+    /** Show the AI typing bubble while waiting for stream headers / first token. */
+    private _showOptimisticAiTyping;
+    private _clearOptimisticAiTyping;
+    sendMessage(content: SendChatMessageContent, options?: SendChatMessageOptions): Promise<void>;
+    /** Retry a failed outbound message (tap-to-retry in the bubble meta). */
+    retryFailedMessage(messageId: string): void;
+    markAsRead(): void;
+    /**
+     * Send a silent trigger to the messages API after a widget action so the
+     * AI follows up (e.g. acknowledges email collection) without creating a
+     * visible user message in the chat.
+     */
+    triggerAIAfterWidgetAction(channelId: string): Promise<void>;
+    onMessage(callback: MessageCallback): Unsubscribe;
+    onTyping(callback: TypingCallback): Unsubscribe;
+    onConnectionChange(callback: ConnectionCallback): Unsubscribe;
+    updateConfig(config: ChatConfig): void;
+    private _applyBubbleLayout;
+    registerWidget(definition: ChatWidgetDefinition): void;
+    /**
+     * Called by `MessageInput` on each keystroke.
+     *
+     * Strategy (industry-standard for Slack/Intercom/Front):
+     * - Publish `true` once on the leading edge of a typing burst.
+     * - Refresh `true` every 4s while the user keeps typing so the
+     *   dashboard's local timeout doesn't drop the indicator mid-burst.
+     * - Schedule a 5s idle timer that publishes `false` once the user
+     *   stops. Each new keystroke resets the timer.
+     * - When realtime isn't attached (initial load, reconnect window),
+     *   queue the intent and flush it when `realtimeReady` flips true,
+     *   provided the activity is still recent (<3s old).
+     */
+    notifyUserTyping(): void;
+    /**
+     * Called from `MessageInput` on send/blur, from `close()`, and from
+     * `destroy()`. Synchronously emits `false` so the dashboard's
+     * indicator clears immediately rather than waiting for the 5s idle
+     * timeout.
+     */
+    stopUserTyping(): void;
+    private _scheduleTypingIdle;
+    destroy(): void;
+    /** Build the WidgetContext passed to custom widget renderers and actions. */
+    getWidgetContext(messageId: string, widgetType: string): WidgetContext;
+    /**
+     * Mark a widget as submitted in local message metadata so the next render
+     * shows the confirmation UI instead of the input form, then trigger an AI
+     * follow-up unless the widget is `escalate_to_human` (AI mode is off).
+     */
+    markWidgetSubmittedAndFollowUp(messageId: string, widgetType: string, formData: Record<string, unknown>): void;
+    private _outboxStorageKey;
+    private _refreshOutboxKey;
+    private _markOutboxSending;
+    private _failOutboxMessage;
+    private _bindOutboxToChannel;
+    private _rememberLastCreatedChannel;
+    private _migrateOutboxFromDistinctId;
+    private _bindOutboxLifecycle;
+    private _unbindOutboxLifecycle;
+    private _enqueueOutbox;
+    private _markMessageDelivered;
+    private _scheduleDrainOutbox;
+    private _drainOutbox;
+    private _deliverOutboxEntry;
+    private _createChannelIdForOutbox;
+    private _postUserMessageSilent;
+    private _postUserMessage;
+    private get _distinctId();
+    private _stubChannelFromSummary;
+    private _handleIdentityChange;
+    /**
+     * Resolve once `identityChangeInFlight` becomes `false`. Used by
+     * `sendMessage` so a `vt.sendChatMessage()` call that arrives immediately
+     * after `vt.identify()` doesn't race the in-flight identity reset.
+     */
+    private _waitForIdentityChange;
+    private _trackChatMessage;
+    private _autoMarkAsRead;
+    private _publishTyping;
+    /**
+     * Subscribe to `connectionState` changes and forward `connected`/
+     * `disconnected` transitions through the legacy `onConnectionChange`
+     * callback contract.
+     */
+    private _watchConnectionState;
+}

package/dist/extensions/chat/controller/message-delivery-status.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Local delivery status on optimistic user messages (not persisted server-side).
+ */
+import type { ChatStore } from "../store/chat-store";
+export type MessageDeliveryStatus = "pending" | "sending" | "failed";
+export declare function setMessageDeliveryStatus(store: ChatStore, messageId: string, status: MessageDeliveryStatus | undefined): void;

package/dist/extensions/chat/controller/message-order.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Chronological ordering for chat messages.
+ *
+ * The server orders by `(created_at, id)`. The widget store must match
+ * that contract whenever messages are inserted out of band (streaming
+ * races, Ably echoes) so bubbles don't land in append order.
+ */
+import type { ChatMessage } from "../../../utils/globals";
+/** Compare two messages the way Postgres orders inbox rows. */
+export declare function compareMessagesChronologically(a: ChatMessage, b: ChatMessage): number;
+export declare function sortMessagesChronologically(messages: ChatMessage[]): ChatMessage[];
+export declare function insertMessageChronologically(messages: ChatMessage[], incoming: ChatMessage): ChatMessage[];

package/dist/extensions/chat/controller/message-stream.d.ts

@@ -0,0 +1,49 @@
+/**
+ * AI streaming response reader.
+ *
+ * Reads chunks from a `Response`'s body, batches store updates to one
+ * per animation frame, strips trailing incomplete HTML tags so partial
+ * flash, and parses widget blocks at completion.
+ *
+ * Pure with respect to the DOM — only writes into the store. The bubble
+ * keeps the same id from frame one: the server pre-creates the row and
+ * returns the persisted id via the `X-Vtilt-Message-Id` header, so the
+ * later Ably echo / DB-update merges into the same row with no remount.
+ * On older servers that don't send the header we fall back to the legacy
+ * `temp-ai-*` id and upsertMessage's id-swap behaviour.
+ */
+import type { ChatStore } from "../store/chat-store";
+/** Header the server uses to publish the persisted AI message id up-front. */
+export declare const AI_MESSAGE_ID_HEADER = "X-Vtilt-Message-Id";
+/** Header the server uses to publish the persisted AI message timestamp. */
+export declare const AI_MESSAGE_CREATED_AT_HEADER = "X-Vtilt-Message-Created-At";
+/** Widget block marker regex: `<!--vtilt:widget:{...}-->` */
+export declare const WIDGET_BLOCK_RE: RegExp;
+/** Parse `<!--vtilt:widget:{...}-->` markers out of streamed content. */
+export declare function parseWidgetBlocks(text: string): Array<{
+    type: string;
+    params: Record<string, unknown>;
+}>;
+interface StreamArgs {
+    store: ChatStore;
+    response: Response;
+    channelId: string;
+    tempId?: string;
+    /** When aborted, the reader stops and removes its partial bubble. */
+    signal?: AbortSignal;
+    /** Extra guard for superseded streams (new user send while still reading). */
+    isActive?: () => boolean;
+    onStreamStart?: (messageId: string) => void;
+    onComplete?: (messageId: string) => void;
+}
+/**
+ * Read an AI streaming response into the store. The bubble id is decided
+ * once at frame one (persisted id from `X-Vtilt-Message-Id` if the server
+ * provided it, otherwise a `temp-ai-*` fallback) and never changes, so
+ * the same `MessageBubble` instance receives content updates without
+ * re-keying.
+ */
+export declare function handleStreamingResponse({ store, response, channelId, tempId, signal, isActive, onStreamStart, onComplete, }: StreamArgs): Promise<void>;
+/** Remove a single message by id (used to clean up failed temp messages). */
+export declare function removeMessageById(store: ChatStore, id: string): void;
+export {};