@v-tilt/browser 1.13.0 → 1.13.1

package/dist/extensions/chat/lib/bubble-offset.d.ts

@@ -0,0 +1,18 @@
+import type { BubbleOffset } from "../../../utils/globals";
+export declare const DEFAULT_BUBBLE_OFFSET: {
+    readonly bottom: 20;
+    readonly right: 20;
+    readonly left: 20;
+};
+export interface ResolvedBubbleOffset {
+    bottom: number;
+    right: number;
+    left: number;
+}
+/** Merge partial offset with SDK defaults (20px on each edge). */
+export declare function resolveBubbleOffset(partial?: BubbleOffset | null): ResolvedBubbleOffset;
+/** Set CSS custom properties consumed by shadow-styles on the chat host. */
+export declare function applyBubbleOffsetStyles(host: HTMLElement, offset: ResolvedBubbleOffset): void;
+export type WidgetPosition = "bottom-right" | "bottom-left";
+/** Apply fixed positioning to the pre-load lightweight bubble element. */
+export declare function applyLightweightBubblePosition(el: HTMLElement, position: WidgetPosition, offset: ResolvedBubbleOffset): void;

package/dist/extensions/chat/lib/merge-chat-config.d.ts

@@ -0,0 +1,3 @@
+import type { ChatConfig } from "../../../utils/globals";
+/** Deep-merge a partial chat config patch into the current code config. */
+export declare function mergeChatConfig(current: ChatConfig, patch: Partial<ChatConfig>): ChatConfig;

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

@@ -3,6 +3,8 @@ 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";
+/** Must match `MESSAGE_SOURCE_METADATA_KEY` in app `message-source.ts`. */
+export declare const MESSAGE_SOURCE_METADATA_KEY = "message_source";
 export interface NormalizedOutgoingMessage {
     content: string;
     content_type: ContentType;

package/dist/extensions/chat/outbox/message-delivery.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Client-side detection of user-message persistence from widget POST responses.
+ */
+/** Set on streaming responses after the user row INSERT (before AI bytes). */
+export declare const USER_MESSAGE_ID_HEADER = "X-Vtilt-User-Message-Id";
+/** ISO timestamp for the persisted user row (streaming responses). */
+export declare const USER_MESSAGE_CREATED_AT_HEADER = "X-Vtilt-User-Message-Created-At";
+/**
+ * Returns true when the server has acknowledged the client-minted user row.
+ * For streaming responses, reads response headers without consuming the body.
+ * For JSON responses, clones and parses `{ message }`.
+ *
+ * vTilt persists the user row before streaming AI bytes. When the user ack
+ * header is absent (older builds), `text/plain` + `response.ok` is treated as
+ * persisted so retries do not spin forever.
+ */
+export declare function isUserMessagePersisted(response: Response, expectedMessageId: string): Promise<boolean>;

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

@@ -0,0 +1,57 @@
+/**
+ * Session-scoped outbound message queue for reliable widget delivery.
+ */
+import type { ChatMessage } from "../../../utils/globals";
+/** Requeue `sending` rows stuck longer than this (crash / abort mid-flight). */
+export declare const STALE_SENDING_MS = 30000;
+/** Reuse a recently created channel for `newChannel` drain instead of POSTing again. */
+export declare const LAST_CREATED_CHANNEL_TTL_MS: number;
+export type OutboxEntryState = "pending" | "sending" | "failed";
+export interface OutboxEntry {
+    messageId: string;
+    channelId: string;
+    distinctId: string;
+    body: string;
+    content_type: ChatMessage["content_type"];
+    metadata: Record<string, unknown>;
+    created_at: string;
+    state: OutboxEntryState;
+    attempts: number;
+    /** Epoch ms — do not drain before this instant (exponential backoff). */
+    nextRetryAt: number;
+    /** Epoch ms — when the row entered `sending` (stale recovery). */
+    sendingSince?: number;
+    /** When set, drain creates a channel before POSTing the message. */
+    newChannel?: {
+        skipGreeting: boolean;
+    };
+}
+export interface LastCreatedChannelHint {
+    channelId: string;
+    at: number;
+}
+export declare function outboxStorageKey(projectToken: string, distinctId: string): string;
+export declare function lastCreatedChannelStorageKey(storageKey: string): string;
+export declare function readLastCreatedChannelHint(storageKey: string, now?: number): LastCreatedChannelHint | null;
+export declare function writeLastCreatedChannelHint(storageKey: string, channelId: string): void;
+export declare class MessageOutbox {
+    private readonly _storageKey;
+    /** Fallback when sessionStorage is unavailable or writes fail. */
+    private _memory;
+    constructor(_storageKey: string);
+    list(): OutboxEntry[];
+    get(messageId: string): OutboxEntry | undefined;
+    upsert(entry: OutboxEntry): void;
+    patch(messageId: string, partial: Partial<OutboxEntry>): void;
+    remove(messageId: string): void;
+    /** Entries eligible for drain (not in backoff, not actively sending). */
+    dueEntries(now?: number): OutboxEntry[];
+    /**
+     * Recover rows left in `sending` after a crash, tab kill, or aborted fetch.
+     */
+    requeueStaleSending(maxAgeMs?: number, now?: number): void;
+    private _readStorage;
+    private _write;
+}
+/** Backoff: 1s, 2s, 4s, … capped at 60s. */
+export declare function nextOutboxRetryAt(attempts: number, now?: number): number;

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

@@ -0,0 +1,122 @@
+/**
+ * ChatStore — signal-based state container for the chat widget.
+ *
+ * All UI state (view, messages, channels, typing) and all realtime state
+ * (connection state, channel ids) live here as @preact/signals signals.
+ * Components read `.value` inside JSX; Preact's signal integration re-renders
+ * only the affected subtree.
+ *
+ * Mutations are direct assignments (`store.isOpen.value = true`) from the
+ * controller or the Ably handler layer. The store itself has no I/O and no
+ * DOM dependency, which makes the rest of the widget trivially testable.
+ *
+ * See: docs/modules/chat/widget-architecture.md
+ */
+import type { ChatChannel, ChatChannelSummary, ChatMessage, ChatTheme, ChatWidgetView } from "../../../utils/globals";
+/** Realtime connection state vocabulary the store exposes to UI. */
+export type RealtimeConnectionState = "disconnected" | "connecting" | "connected" | "suspended" | "failed";
+/** Banner state derived from connection state. */
+export type ConnectionBanner = "none" | "reconnecting" | "failed";
+/** Default theme — Inter is vTilt's brand font; system stack as fallback. */
+export declare const DEFAULT_THEME: Required<Pick<ChatTheme, "primaryColor" | "fontFamily" | "borderRadius">>;
+export declare class ChatStore {
+    isOpen: import("@preact/signals").Signal<boolean>;
+    isVisible: import("@preact/signals").Signal<boolean>;
+    isLoading: import("@preact/signals").Signal<boolean>;
+    currentView: import("@preact/signals").Signal<ChatWidgetView>;
+    channels: import("@preact/signals").Signal<ChatChannelSummary[]>;
+    channel: import("@preact/signals").Signal<ChatChannel | null>;
+    messages: import("@preact/signals").Signal<ChatMessage[]>;
+    isTyping: import("@preact/signals").Signal<boolean>;
+    typingSender: import("@preact/signals").Signal<string | null>;
+    typingSenderType: import("@preact/signals").Signal<"user" | "agent" | "ai" | null>;
+    agentLastReadAt: import("@preact/signals").Signal<string | null>;
+    initialUserReadAt: import("@preact/signals").Signal<string | null>;
+    userScrolledUp: import("@preact/signals").Signal<boolean>;
+    unreadNewMessagesCount: import("@preact/signals").Signal<number>;
+    theme: import("@preact/signals").Signal<Required<Pick<ChatTheme, "borderRadius" | "fontFamily" | "primaryColor">>>;
+    /** Live connection state from Ably's connection events. */
+    connectionState: import("@preact/signals").Signal<RealtimeConnectionState>;
+    /** Numeric Ably project id (set after first successful token request). */
+    ablyProjectId: import("@preact/signals").Signal<number | null>;
+    /** Channel id the realtime layer has attached to. `null` on list view. */
+    realtimeChannelId: import("@preact/signals").Signal<string | null>;
+    /**
+     * True once both the per-conversation main + typing Ably channels have
+     * successfully attached for `realtimeChannelId`. Flips back to `false`
+     * on detach, attach failure, or identity change. Drives the "Connecting…"
+     * indicator in the conversation view.
+     */
+    realtimeAttached: import("@preact/signals").Signal<boolean>;
+    /**
+     * Channel id whose details we are currently fetching. Guards against rapid
+     * navigation: a slow GET resolver checks `pendingRealtimeChannelId === id`
+     * before writing into the store.
+     */
+    pendingRealtimeChannelId: import("@preact/signals").Signal<string | null>;
+    /** True while `handleIdentityChange()` is tearing down and rebuilding. */
+    identityChangeInFlight: import("@preact/signals").Signal<boolean>;
+    /**
+     * Distinct id the live Ably connection was authorised for. Used by the
+     * `connected` event handler to detect drift after `vt.identify()`.
+     */
+    lastConnectedDistinctId: import("@preact/signals").Signal<string | null>;
+    /** Max distinct channels to keep in the cache. LRU-trimmed on write. */
+    private static readonly MESSAGES_CACHE_LIMIT;
+    private _messagesCache;
+    isConnected: import("@preact/signals").ReadonlySignal<boolean>;
+    /**
+     * Tier A aggregate from `GET /api/chat/widget/unread` while the panel is
+     * closed. Cleared on `open()` so channel rows own the badge again.
+     */
+    polledUnreadTotal: import("@preact/signals").Signal<number | null>;
+    /** Sum of unread across all channels — drives the bubble badge. */
+    unreadCount: import("@preact/signals").ReadonlySignal<number>;
+    /** Banner shown above the input when realtime is degraded. */
+    connectionBanner: import("@preact/signals").ReadonlySignal<ConnectionBanner>;
+    /**
+     * True when the realtime transport is fully ready for the *currently
+     * displayed* conversation: connection is `connected`, the channel object
+     * exists, and the realtime layer has attached the per-conversation
+     * channels for it. Used by the UI to show a subtle "Connecting…" pill
+     * while realtime is still spinning up after navigation or identify.
+     */
+    realtimeReady: import("@preact/signals").ReadonlySignal<boolean>;
+    /**
+     * Replace `messages` only if `next` differs by identity from current array.
+     * Signals trigger re-renders only on identity change of the value, so we
+     * always pass a new array to ensure subscribers re-evaluate.
+     */
+    setMessages(next: ChatMessage[]): void;
+    /** Patch a single channel summary in place, then re-sort by last_message_at. */
+    patchChannelSummary(id: string, patch: Partial<ChatChannelSummary>): void;
+    /** Insert a channel summary at the top of the list (skip if id exists). */
+    prependChannelSummary(summary: ChatChannelSummary): void;
+    /** Reset all realtime / channel-scoped state. Used on goToChannelList()
+     *  and `_handleIdentityChange()` — places where we leave the conversation
+     *  entirely. For *between-channel* transitions, prefer
+     *  `prepareChannelSwitch()` which leaves the realtime signals tracking
+     *  the last good attach so `realtimeReady` doesn't blink false. */
+    clearActiveChannel(): void;
+    /** Soft reset between channels — clears conversation-scoped state but
+     *  leaves `realtimeChannelId` / `realtimeAttached` tracking the previous
+     *  successful attach. `AblyClient.attachConversation()` atomically swaps
+     *  those signals once the new channel is fully attached, so
+     *  `realtimeReady` (and therefore the "Connecting…" banner) doesn't
+     *  flicker during normal channel switches.
+     *
+     *  Inbound stale frames from the previous channel are already filtered
+     *  by AblyClient's channel-ref guard, so leaving these signals true is
+     *  safe from a correctness standpoint. */
+    prepareChannelSwitch(): void;
+    /**
+     * Cache the message list for a channel so a later `selectChannel(id)`
+     * can paint instantly. Drops `temp-*` rows (they don't belong to a
+     * persisted state) and LRU-trims to `MESSAGES_CACHE_LIMIT`.
+     */
+    cacheMessages(channelId: string, messages: ChatMessage[]): void;
+    /** Returns the cached message list for a channel, or null if absent. */
+    getCachedMessages(channelId: string): ChatMessage[] | null;
+    /** Drop a channel from the cache. Used on full identity reset. */
+    clearMessagesCache(): void;
+}

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

@@ -4,7 +4,7 @@
  * 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, SendChatMessageContent, SendChatMessageOptions, } from "../../utils/globals";
+export type { BubbleOffset, 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";
 /**
@@ -77,24 +77,6 @@ export interface ChannelMessageEventProperties {
     $content_preview: string;
     $ai_mode?: boolean;
 }
-/**
- * Internal widget state
- */
-export interface ChatWidgetState {
-    isOpen: boolean;
-    isVisible: boolean;
-    isConnected: boolean;
-    isLoading: boolean;
-    unreadCount: number;
-    currentView: import("../../utils/globals").ChatWidgetView;
-    channels: import("../../utils/globals").ChatChannelSummary[];
-    channel: import("../../utils/globals").ChatChannel | null;
-    messages: import("../../utils/globals").ChatMessage[];
-    isTyping: boolean;
-    typingSender: string | null;
-    typingSenderType: "user" | "agent" | "ai" | null;
-    agentLastReadAt: string | null;
-}
 /**
  * Message callback type
  */

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

@@ -0,0 +1,12 @@
+/**
+ * ChannelItem — single row in the channel list. Renders avatar, name,
+ * relative time, preview, and unread badge.
+ */
+import type { JSX } from "preact";
+import type { ChatChannelSummary } from "../../../utils/globals";
+interface ChannelItemProps {
+    channel: ChatChannelSummary;
+    onSelect: (id: string) => void;
+}
+export declare function ChannelItem({ channel, onSelect, }: ChannelItemProps): JSX.Element;
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * ChannelListView — three modes: empty welcome (no channels, not loading),
+ * skeleton (no channels, loading), populated list. The controller manages
+ * selection / creation flow; this component only renders + emits intent.
+ */
+import type { JSX } from "preact";
+import type { ChatController } from "../controller/chat-controller";
+import type { ChatStore } from "../store/chat-store";
+interface ChannelListViewProps {
+    store: ChatStore;
+    controller: ChatController;
+}
+export declare function ChannelListView({ store, controller, }: ChannelListViewProps): JSX.Element;
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * ChatBubble — circular floating button rendered when the panel is closed.
+ * Shows the unread badge derived from the channels-summary computed signal.
+ */
+import type { JSX, Ref } from "preact";
+import type { ChatController } from "../controller/chat-controller";
+import type { ChatStore } from "../store/chat-store";
+interface ChatBubbleProps {
+    store: ChatStore;
+    controller: ChatController;
+    bubbleRef: Ref<HTMLButtonElement>;
+}
+export declare function ChatBubble({ store, controller, bubbleRef, }: ChatBubbleProps): JSX.Element;
+export {};

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

@@ -0,0 +1,13 @@
+/**
+ * ChatHeader — top bar that shows either the "Messages" title (list view) or
+ * back button + avatar + agent label + online indicator (conversation view).
+ */
+import type { JSX } from "preact";
+import type { ChatController } from "../controller/chat-controller";
+import type { ChatStore } from "../store/chat-store";
+interface ChatHeaderProps {
+    store: ChatStore;
+    controller: ChatController;
+}
+export declare function ChatHeader({ store, controller, }: ChatHeaderProps): JSX.Element;
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * ChatPanel — the open widget panel: header + content (list or conversation).
+ * Display is driven via the parent container's `data-open` attribute so the
+ * close/open animation can hook in via CSS.
+ */
+import type { JSX } from "preact";
+import type { ChatController } from "../controller/chat-controller";
+import type { ChatStore } from "../store/chat-store";
+interface ChatPanelProps {
+    store: ChatStore;
+    controller: ChatController;
+}
+export declare function ChatPanel({ store, controller }: ChatPanelProps): JSX.Element;
+export {};

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

@@ -0,0 +1,31 @@
+/**
+ * ChatRoot — top-level Preact component + Shadow DOM bootstrap.
+ *
+ * `mountChatUI()` creates a host `<div>` on `<body>`, attaches an open
+ * shadow root, injects the shared style string, and renders `<ChatRoot/>`.
+ *
+ * The host element receives a CSS transform when `bubbleDraggable` is
+ * enabled (via `bubble-drag.ts`); the shadow content is purely structural.
+ */
+import { type JSX } from "preact";
+import type { ChatController } from "../controller/chat-controller";
+import type { ChatStore } from "../store/chat-store";
+export interface MountChatUIArgs {
+    store: ChatStore;
+    controller: ChatController;
+    position: "bottom-right" | "bottom-left";
+    bubbleDraggable: boolean;
+}
+export interface MountedChatUI {
+    host: HTMLElement;
+    destroy(): void;
+}
+export declare function mountChatUI(args: MountChatUIArgs): MountedChatUI;
+interface ChatRootProps {
+    store: ChatStore;
+    controller: ChatController;
+    position: "bottom-right" | "bottom-left";
+    bubbleDraggable: boolean;
+}
+export declare function ChatRoot({ store, controller, position, bubbleDraggable, }: ChatRootProps): JSX.Element;
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * ClosedBanner — flat banner shown above the input area when the active
+ * channel's status is "closed". Replaces the imperative DOM banner manipulation
+ * the old chat.ts performed in `_updateUI`.
+ */
+import type { JSX } from "preact";
+export declare function ClosedBanner(): JSX.Element;

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

@@ -0,0 +1,32 @@
+/**
+ * ConnectionBanner — minimal, action-only surface for degraded realtime.
+ *
+ * Industry alignment (Intercom / Slack / iMessage):
+ *
+ *  - The **initial attach** ("connecting") is invisible. The user can
+ *    already see their history (painted from the REST hydrate) and the
+ *    SDK queues anything they type until realtime attaches, so there is
+ *    nothing actionable to surface. The old "Connecting…" banner was
+ *    visual noise that flashed on every channel switch and `vt.identify()`.
+ *
+ *  - **Reconnecting** (Ably is `suspended` / `disconnected` mid-session
+ *    and retrying) only surfaces after a 2.5 s grace window so the brief
+ *    blips that happen on a healthy network never reach the UI. When it
+ *    does appear it's a compact inline pill with a pulsing dot — not a
+ *    full-width amber banner — so it doesn't dominate the conversation.
+ *
+ *  - **Failed** (Ably terminal failure) is the only state that asks the
+ *    user to do something, so we render an actionable card with a Retry
+ *    button instead of a passive "refresh to retry" hint.
+ *
+ * Anything that needs to know the SDK is mid-attach (e.g. typing
+ * indicators) reads `store.realtimeReady` directly — this banner is
+ * purely a user-facing surface.
+ */
+import type { JSX } from "preact";
+import type { ChatStore } from "../store/chat-store";
+interface ConnectionBannerProps {
+    store: ChatStore;
+}
+export declare function ConnectionBanner({ store, }: ConnectionBannerProps): JSX.Element | null;
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * ConversationView — message list (which now owns the trailing typing
+ * bubble) + connection banner + closed banner + message input. Driven
+ * entirely by store signals.
+ */
+import type { JSX } from "preact";
+import type { ChatController } from "../controller/chat-controller";
+import type { ChatStore } from "../store/chat-store";
+interface ConversationViewProps {
+    store: ChatStore;
+    controller: ChatController;
+}
+export declare function ConversationView({ store, controller, }: ConversationViewProps): JSX.Element;
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * MessageBubble — renders a single chat message (avatar, bubble, meta).
+ *
+ * Markdown / HTML rendering for AI/agent messages goes through
+ * `formatMessageBodyHtml` which sanitizes inside a detached `<div>` then
+ * we inject the sanitized result via `dangerouslySetInnerHTML`. User
+ * messages render as escaped text unless they opted into a rich format
+ * (markdown / html) at send time.
+ *
+ * Memoised so unrelated store updates (typing, scroll, channel list)
+ * don't re-render every bubble. Reference equality on `message` is the
+ * fast path — `upsertMessage` deliberately returns the same object when
+ * nothing actually changed, so duplicate Ably echoes don't churn either.
+ */
+import type { JSX } from "preact";
+import type { ChatMessage } from "../../../utils/globals";
+import type { ChatController } from "../controller/chat-controller";
+interface MessageBubbleProps {
+    message: ChatMessage;
+    controller: ChatController;
+    isReadByAgent: boolean;
+}
+declare function MessageBubbleImpl({ message, controller, isReadByAgent, }: MessageBubbleProps): JSX.Element;
+export declare const MessageBubble: typeof MessageBubbleImpl;
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * MessageInput — auto-resizing textarea + send button. Owns its own value
+ * (not in the store) because keystroke-level reactivity through the store
+ * would re-render the whole conversation tree on every character.
+ */
+import type { JSX } from "preact";
+import type { ChatController } from "../controller/chat-controller";
+import type { ChatStore } from "../store/chat-store";
+interface MessageInputProps {
+    store: ChatStore;
+    controller: ChatController;
+}
+export declare function MessageInput({ store, controller, }: MessageInputProps): JSX.Element;
+export {};

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

@@ -0,0 +1,19 @@
+/**
+ * MessageList — renders the message stream with scroll preservation and a
+ * "new messages" pill. Uses keyed children so Preact reuses existing
+ * MessageBubble nodes across renders.
+ *
+ * The typing indicator lives **inside** this list as a trailing
+ * `TypingBubble`, not as a separate element below the list, so the dots
+ * occupy the exact slot the real message will land in and the bubble
+ * shape stays put when content arrives.
+ */
+import type { JSX } from "preact";
+import type { ChatController } from "../controller/chat-controller";
+import type { ChatStore } from "../store/chat-store";
+interface MessageListProps {
+    store: ChatStore;
+    controller: ChatController;
+}
+export declare function MessageList({ store, controller, }: MessageListProps): JSX.Element;
+export {};

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

@@ -0,0 +1,13 @@
+/**
+ * NewMessagesPill — floating "↓ N new messages" affordance shown when the
+ * user has scrolled up while new agent/AI messages arrived. Clicking jumps
+ * back to the bottom and clears the counter.
+ */
+import type { JSX } from "preact";
+interface NewMessagesPillProps {
+    count: number;
+    visible: boolean;
+    onJump: () => void;
+}
+export declare function NewMessagesPill({ count, visible, onJump, }: NewMessagesPillProps): JSX.Element;
+export {};

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

@@ -0,0 +1,14 @@
+/**
+ * Skeleton placeholders for the channel list (first-load) and conversation
+ * (mid-`selectChannel`). Sized to match the live row dimensions so layout
+ * doesn't jump when real content arrives.
+ *
+ * The new-channel pending placeholder used to live here as
+ * `NewChannelLoader`; it has been unified with the live typing indicator
+ * — both flow through `TypingBubble` rendered inside `MessageList`.
+ */
+import type { JSX } from "preact";
+/** Skeleton stack for the channel list while channels are loading. */
+export declare function ListSkeleton(): JSX.Element;
+/** Three alternating skeleton bubbles to imply message history is incoming. */
+export declare function MessageSkeleton(): JSX.Element;

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

@@ -0,0 +1,23 @@
+/**
+ * TypingBubble — incoming-style chat bubble with animated typing dots and
+ * the matching avatar. Rendered as the last child of the message list so
+ * the dots occupy the exact slot the real message will land in; when the
+ * message arrives the bubble shape stays put and the content morphs from
+ * dots to text. Used for two cases:
+ *
+ *   1. Live typing event (agent / AI publishes `is_typing: true`) —
+ *      rendered while `store.isTyping` is true.
+ *   2. New-channel pending state — rendered while we wait for the server
+ *      response to `POST /channels` (replaces the old `NewChannelLoader`
+ *      so the empty-conversation placeholder and the live indicator share
+ *      one component).
+ */
+import type { JSX } from "preact";
+interface TypingBubbleProps {
+    /** Who's composing — drives avatar variant and label. */
+    senderType: "ai" | "agent";
+    /** Agent's display name. Ignored for AI (always "AI Assistant"). */
+    senderName?: string | null;
+}
+export declare function TypingBubble({ senderType, senderName, }: TypingBubbleProps): JSX.Element;
+export {};

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

@@ -0,0 +1,12 @@
+/**
+ * TypingIndicator — animated three-dot affordance shown above the input
+ * when an agent or the AI is composing a reply. Driven entirely by store
+ * signals; no manual show/hide DOM toggling.
+ */
+import type { JSX } from "preact";
+import type { ChatStore } from "../store/chat-store";
+interface TypingIndicatorProps {
+    store: ChatStore;
+}
+export declare function TypingIndicator({ store }: TypingIndicatorProps): JSX.Element;
+export {};

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

@@ -0,0 +1,20 @@
+/**
+ * WidgetSlot — renders inline widgets (e.g. collect-email, escalate-to-human)
+ * for a message via the ChatWidgetRegistry. Reads the same metadata sources
+ * the previous string-builder did, but the registry now returns Preact
+ * VNodes so widgets compose naturally inside the message list.
+ *
+ * Submission UI is metadata-driven: once a widget is `submitted: true`
+ * (set by the controller after a successful `onAction`), this component
+ * renders a type-specific confirmation instead of the input form.
+ */
+import type { JSX } from "preact";
+import type { ChatMessage } from "../../../utils/globals";
+import type { ChatController } from "../controller/chat-controller";
+interface WidgetSlotProps {
+    message: ChatMessage;
+    controller: ChatController;
+}
+declare function WidgetSlotImpl({ message, controller, }: WidgetSlotProps): JSX.Element | null;
+export declare const WidgetSlot: typeof WidgetSlotImpl;
+export {};

package/dist/extensions/chat/ui/hooks/use-auto-mark-read.d.ts

@@ -0,0 +1,18 @@
+/**
+ * useAutoMarkRead — fire `markAsRead` shortly after the user reaches the
+ * conversation view with unread messages, and again when new messages
+ * arrive while the widget is open.
+ *
+ * The actual server call is debounced inside the controller via the
+ * `_isMarkingRead` guard.
+ */
+import type { ChatMessage } from "../../../../utils/globals";
+import type { ChatController } from "../../controller/chat-controller";
+import type { ChatStore } from "../../store/chat-store";
+interface UseAutoMarkReadArgs {
+    store: ChatStore;
+    controller: ChatController;
+    messages: ChatMessage[];
+}
+export declare function useAutoMarkRead({ store, controller, messages, }: UseAutoMarkReadArgs): void;
+export {};

package/dist/extensions/chat/ui/hooks/use-scroll-preservation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * useScrollPreservation — manage the message list's scroll behaviour:
+ *
+ * 1. Auto-scroll to bottom when:
+ *    - The user was already near the bottom AND a new message arrived
+ *    - The user just sent a message (`stickToBottom()` is called by sendMessage path)
+ *    - The conversation first mounts
+ * 2. Preserve scroll position when the user has scrolled up (reading history)
+ *    and new agent/AI messages arrive — instead, surface the
+ *    "↓ N new messages" pill.
+ * 3. Detect when the user manually scrolls back to the bottom and reset the
+ *    "scrolled up" flag + clear the pill counter.
+ */
+import type { RefObject } from "preact";
+import type { ChatMessage } from "../../../../utils/globals";
+import type { ChatStore } from "../../store/chat-store";
+interface UseScrollPreservationArgs {
+    store: ChatStore;
+    scrollRef: RefObject<HTMLElement | null>;
+    messages: ChatMessage[];
+    /**
+     * Whether the trailing typing bubble is currently rendered. When it
+     * flips from `false` → `true` the bubble grows the list by ~one
+     * message-height; if the user was at the bottom we snap them to keep
+     * the dots in view, matching the behaviour for newly-arrived
+     * messages.
+     */
+    typingActive?: boolean;
+}
+export declare function useScrollPreservation({ store, scrollRef, messages, typingActive, }: UseScrollPreservationArgs): {
+    jumpToBottom: () => void;
+};
+export {};