@agentforge-io/chat-sdk 2.1.1 → 2.3.0

package/dist/ChatDrawer.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `<ChatDrawer>` — standard bottom-sheet wrapper around `<ChatWidget>`.
+ *
+ * The host gives us:
+ *   - `open` / `onOpenChange`: controlled visibility (host owns the route /
+ *     URL sync, the SDK doesn't touch the URL).
+ *   - All the `<ChatWidget>` props (token, apiBaseUrl, etc.): forwarded
+ *     verbatim. The widget mounts INSIDE the drawer.
+ *
+ * What the drawer adds on top:
+ *   - Mounts via React portal (`document.body`) so it overlays the page
+ *     regardless of the host's stacking context. Lazy-mounted: the portal
+ *     target is computed at first open so SSR stays clean.
+ *   - Visually pinned to the bottom of the *visual viewport* (not the
+ *     layout viewport). On iOS Safari and Android Chrome the on-screen
+ *     keyboard shrinks `window.visualViewport.height`; we listen to
+ *     `resize` / `scroll` on visualViewport and reflow the drawer's
+ *     `height` + `bottom` so the composer never gets clipped by the
+ *     keyboard.
+ *   - Opens at a configurable snap fraction (default 0.98 = 98% of the
+ *     visible viewport). The visitor sees a thin sliver of the page
+ *     underneath, which keeps context and lets a tap-outside dismiss.
+ *   - Drag-to-dismiss with vanilla touch events: drag the handle down
+ *     past 30% of the panel height and the drawer closes. No external
+ *     deps — the SDK stays portable.
+ *   - Survives close+reopen: the widget inside is rendered once and kept
+ *     alive (CSS `display:none` toggle when closed, NOT unmounted), so
+ *     the chat session, transcript, and any in-flight tool calls stay
+ *     intact when the visitor closes and reopens the drawer.
+ *
+ * What the drawer does NOT do (deliberately):
+ *   - It doesn't sync with the URL. The host decides whether `?view=chat`,
+ *     `/chat`, or any other route shape opens it.
+ *   - It doesn't manage the chat session lifecycle. That's `<ChatWidget>`'s
+ *     job. We just provide presentation.
+ *   - It doesn't render a "fake composer" to trigger opening. The host
+ *     decides what trigger UX makes sense (button, input pill, FAB, etc.)
+ *     and calls `onOpenChange(true)`.
+ */
+import { type ReactNode } from 'react';
+import { type ChatWidgetProps } from './react';
+/**
+ * Drawer accepts the chat surface in two shapes:
+ *
+ *   - `widgetProps`: pass the ChatWidget configuration and the drawer
+ *     creates the widget internally. The standard / forward-looking
+ *     API — most consumers should use this.
+ *
+ *   - `chatSlot`: pass a pre-rendered React node (typically a
+ *     `<ChatWidget>` instance the host wired up itself). Useful when
+ *     the host already orchestrates the widget (multiple chat slots,
+ *     custom decorators, legacy code) and just wants the drawer's
+ *     positioning + drag UX on top.
+ *
+ * Exactly one of the two MUST be passed. Mutual exclusivity isn't
+ * encoded at the type level (TS unions with optional props get noisy)
+ * — the runtime asserts gracefully if neither is present.
+ */
+type ChatSurface = {
+    widgetProps: ChatWidgetProps;
+    chatSlot?: never;
+} | {
+    chatSlot: ReactNode;
+    widgetProps?: never;
+};
+export type ChatDrawerProps = ChatSurface & {
+    /** Whether the drawer is visible. Controlled. */
+    open: boolean;
+    /** Fired when the drawer wants to close (drag-to-dismiss, tap on the
+     *  backdrop, close button). Host is responsible for setting `open=false`. */
+    onOpenChange: (open: boolean) => void;
+    /** Snap fraction of the visible viewport, 0–1. Defaults to 0.98 (98% =
+     *  the standard "near-fullscreen drawer that still hints at the page
+     *  below" pattern). Lower numbers leave more of the page visible. */
+    snap?: number;
+    /** Display in the drawer header above the chat. Templates pass the
+     *  agent / team identity here. When omitted, the drawer renders a
+     *  bare drag handle only — useful for hosts that want a borderless
+     *  panel. */
+    header?: ReactNode;
+    /** Backdrop click closes the drawer. Default true — set false if the
+     *  host wants a "modal" feel where the only escape is the close button
+     *  or the drag-down gesture. */
+    closeOnBackdropClick?: boolean;
+    /** Extra class on the drawer's root surface (the white card). Use it to
+     *  add a custom shadow / border colour. The CSS vars on `--af-*` already
+     *  let you re-theme the chat widget itself; this is for the SURROUND. */
+    drawerClassName?: string;
+};
+export declare function ChatDrawer(props: ChatDrawerProps): JSX.Element | null;
+export {};

package/dist/ChatDrawer.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatDrawer = ChatDrawer;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * `<ChatDrawer>` — standard bottom-sheet wrapper around `<ChatWidget>`.
+ *
+ * The host gives us:
+ *   - `open` / `onOpenChange`: controlled visibility (host owns the route /
+ *     URL sync, the SDK doesn't touch the URL).
+ *   - All the `<ChatWidget>` props (token, apiBaseUrl, etc.): forwarded
+ *     verbatim. The widget mounts INSIDE the drawer.
+ *
+ * What the drawer adds on top:
+ *   - Mounts via React portal (`document.body`) so it overlays the page
+ *     regardless of the host's stacking context. Lazy-mounted: the portal
+ *     target is computed at first open so SSR stays clean.
+ *   - Visually pinned to the bottom of the *visual viewport* (not the
+ *     layout viewport). On iOS Safari and Android Chrome the on-screen
+ *     keyboard shrinks `window.visualViewport.height`; we listen to
+ *     `resize` / `scroll` on visualViewport and reflow the drawer's
+ *     `height` + `bottom` so the composer never gets clipped by the
+ *     keyboard.
+ *   - Opens at a configurable snap fraction (default 0.98 = 98% of the
+ *     visible viewport). The visitor sees a thin sliver of the page
+ *     underneath, which keeps context and lets a tap-outside dismiss.
+ *   - Drag-to-dismiss with vanilla touch events: drag the handle down
+ *     past 30% of the panel height and the drawer closes. No external
+ *     deps — the SDK stays portable.
+ *   - Survives close+reopen: the widget inside is rendered once and kept
+ *     alive (CSS `display:none` toggle when closed, NOT unmounted), so
+ *     the chat session, transcript, and any in-flight tool calls stay
+ *     intact when the visitor closes and reopens the drawer.
+ *
+ * What the drawer does NOT do (deliberately):
+ *   - It doesn't sync with the URL. The host decides whether `?view=chat`,
+ *     `/chat`, or any other route shape opens it.
+ *   - It doesn't manage the chat session lifecycle. That's `<ChatWidget>`'s
+ *     job. We just provide presentation.
+ *   - It doesn't render a "fake composer" to trigger opening. The host
+ *     decides what trigger UX makes sense (button, input pill, FAB, etc.)
+ *     and calls `onOpenChange(true)`.
+ */
+const react_1 = require("react");
+const react_dom_1 = require("react-dom");
+const react_2 = require("./react");
+function ChatDrawer(props) {
+    const { open, onOpenChange, snap = 0.98, header, closeOnBackdropClick = true, drawerClassName, widgetProps, chatSlot, } = props;
+    // We mount once and keep alive across close→reopen so the chat session
+    // doesn't get destroyed. After the FIRST open the panel stays in the
+    // DOM forever (toggled by `display:none`) — `hasOpened` gates the
+    // initial mount so SSR doesn't render an empty portal.
+    const [hasOpened, setHasOpened] = (0, react_1.useState)(open);
+    (0, react_1.useEffect)(() => {
+        if (open)
+            setHasOpened(true);
+    }, [open]);
+    // Visible viewport tracking. iOS Safari + Android Chrome shrink
+    // `visualViewport.height` when the on-screen keyboard pops up; the
+    // layout viewport stays the same. We pin the drawer's height + bottom
+    // to the visual viewport so the composer is always above the keyboard.
+    const [vv, setVv] = (0, react_1.useState)(() => ({
+        h: typeof window === 'undefined' ? 0 : window.innerHeight,
+        offsetTop: 0,
+    }));
+    (0, react_1.useEffect)(() => {
+        if (typeof window === 'undefined')
+            return;
+        const view = window.visualViewport;
+        if (!view)
+            return;
+        const update = () => setVv({ h: view.height, offsetTop: view.offsetTop });
+        update();
+        view.addEventListener('resize', update);
+        view.addEventListener('scroll', update);
+        return () => {
+            view.removeEventListener('resize', update);
+            view.removeEventListener('scroll', update);
+        };
+    }, []);
+    // Snap-point height: % of the visible viewport. Recomputed when vv
+    // changes so a keyboard popup keeps the drawer aligned.
+    const drawerHeight = Math.max(0, Math.round(vv.h * Math.min(Math.max(snap, 0.1), 1)));
+    // Drag-to-dismiss. Vanilla touch handlers — no library. We track
+    // pointerdown on the handle, follow movement on pointermove, and
+    // decide on pointerup whether the drag crossed the "dismiss" threshold
+    // (30% of the panel height).
+    const surfaceRef = (0, react_1.useRef)(null);
+    const dragStateRef = (0, react_1.useRef)(null);
+    const [dragOffset, setDragOffset] = (0, react_1.useState)(0);
+    const onHandlePointerDown = (0, react_1.useCallback)((e) => {
+        if (e.button !== 0 && e.pointerType !== 'touch')
+            return;
+        e.currentTarget.setPointerCapture?.(e.pointerId);
+        dragStateRef.current = {
+            startY: e.clientY,
+            startTime: Date.now(),
+            dragging: true,
+        };
+    }, []);
+    const onHandlePointerMove = (0, react_1.useCallback)((e) => {
+        const s = dragStateRef.current;
+        if (!s?.dragging)
+            return;
+        const delta = Math.max(0, e.clientY - s.startY);
+        setDragOffset(delta);
+    }, []);
+    const onHandlePointerUp = (0, react_1.useCallback)((e) => {
+        const s = dragStateRef.current;
+        if (!s?.dragging)
+            return;
+        dragStateRef.current = null;
+        try {
+            e.currentTarget.releasePointerCapture?.(e.pointerId);
+        }
+        catch {
+            // Pointer was already released by some other code path; nothing
+            // to do here. Releasing a non-captured pointer throws — swallow.
+        }
+        const delta = Math.max(0, e.clientY - s.startY);
+        const dismissThreshold = drawerHeight * 0.3;
+        const elapsed = Date.now() - s.startTime;
+        // Dismiss on EITHER a long-drag (past the threshold) or a quick
+        // flick (small distance but high velocity). Velocity unit is
+        // px/ms; >0.5 is roughly the threshold iOS sheets use.
+        const velocity = elapsed > 0 ? delta / elapsed : 0;
+        if (delta > dismissThreshold || velocity > 0.5) {
+            onOpenChange(false);
+        }
+        setDragOffset(0);
+    }, [drawerHeight, onOpenChange]);
+    // Lock body scroll while the drawer is open so the page underneath
+    // doesn't move when the visitor scrolls inside the chat. Restored on
+    // close. Necessary on iOS Safari where the rubber-band scroll bleeds
+    // through to the body even with overflow:hidden on a child.
+    (0, react_1.useEffect)(() => {
+        if (typeof document === 'undefined')
+            return;
+        if (!open)
+            return;
+        const prev = document.body.style.overflow;
+        document.body.style.overflow = 'hidden';
+        return () => {
+            document.body.style.overflow = prev;
+        };
+    }, [open]);
+    // Escape closes the drawer. Keyboard-friendly even when focus is in
+    // the textarea — preventDefault on the input itself swallows Escape
+    // before it bubbles, so we use capture phase.
+    (0, react_1.useEffect)(() => {
+        if (!open)
+            return;
+        if (typeof window === 'undefined')
+            return;
+        const onKey = (e) => {
+            if (e.key === 'Escape')
+                onOpenChange(false);
+        };
+        window.addEventListener('keydown', onKey, true);
+        return () => window.removeEventListener('keydown', onKey, true);
+    }, [open, onOpenChange]);
+    // Lazy portal target. We render to `document.body` so the drawer
+    // overlays everything regardless of the consumer's stacking context.
+    const [portalEl, setPortalEl] = (0, react_1.useState)(null);
+    (0, react_1.useLayoutEffect)(() => {
+        if (typeof document === 'undefined')
+            return;
+        setPortalEl(document.body);
+    }, []);
+    // Stable id so the drag handle's `aria-controls` can point at the
+    // panel. Required for screen readers to announce the relationship.
+    const panelId = (0, react_1.useId)();
+    if (!portalEl)
+        return null;
+    if (!hasOpened)
+        return null;
+    // The translate3d ensures the drawer animates from below on first
+    // open (initial transform = 100%, becomes 0% after the open prop
+    // flips). When dragging we add the manual drag offset on top.
+    const translateY = open ? `${dragOffset}px` : `${drawerHeight}px`;
+    // Transition disabled WHILE dragging so the surface follows the
+    // finger 1:1. Re-enabled at the end of the drag (delta back to 0
+    // smoothly when below threshold).
+    const isDragging = dragStateRef.current?.dragging === true;
+    const surfaceStyle = {
+        height: `${drawerHeight}px`,
+        transform: `translate3d(0, ${translateY}, 0)`,
+        bottom: `${vv.offsetTop}px`,
+        transition: isDragging ? 'none' : 'transform 240ms cubic-bezier(.32,.72,0,1)',
+        willChange: 'transform',
+    };
+    return (0, react_dom_1.createPortal)((0, jsx_runtime_1.jsxs)("div", { className: "af-drawer-root", "data-state": open ? 'open' : 'closed', style: {
+            position: 'fixed',
+            inset: 0,
+            zIndex: 2147483600,
+            pointerEvents: open ? 'auto' : 'none',
+        }, children: [(0, jsx_runtime_1.jsx)("div", { className: "af-drawer-backdrop", onClick: closeOnBackdropClick ? () => onOpenChange(false) : undefined, style: {
+                    position: 'absolute',
+                    inset: 0,
+                    backgroundColor: 'rgba(0, 0, 0, 0.4)',
+                    opacity: open ? 1 : 0,
+                    transition: 'opacity 200ms ease-out',
+                }, "aria-hidden": true }), (0, jsx_runtime_1.jsxs)("div", { ref: surfaceRef, id: panelId, role: "dialog", "aria-modal": "true", className: `af-drawer-surface ${drawerClassName ?? ''}`, style: {
+                    position: 'absolute',
+                    left: 0,
+                    right: 0,
+                    width: '100%',
+                    backgroundColor: 'var(--af-bg, #ffffff)',
+                    borderTopLeftRadius: '16px',
+                    borderTopRightRadius: '16px',
+                    boxShadow: '0 -8px 24px rgba(15, 23, 42, 0.15)',
+                    display: 'flex',
+                    flexDirection: 'column',
+                    overflow: 'hidden',
+                    ...surfaceStyle,
+                }, children: [(0, jsx_runtime_1.jsx)("div", { onPointerDown: onHandlePointerDown, onPointerMove: onHandlePointerMove, onPointerUp: onHandlePointerUp, onPointerCancel: onHandlePointerUp, style: {
+                            padding: '10px 0',
+                            cursor: 'grab',
+                            touchAction: 'none',
+                            display: 'flex',
+                            justifyContent: 'center',
+                            flexShrink: 0,
+                        }, "aria-label": "Drag to close", children: (0, jsx_runtime_1.jsx)("span", { style: {
+                                width: '40px',
+                                height: '4px',
+                                borderRadius: '999px',
+                                backgroundColor: 'var(--af-muted, rgba(100, 116, 139, 0.45))',
+                                display: 'block',
+                            } }) }), header, (0, jsx_runtime_1.jsx)("div", { style: { flex: 1, minHeight: 0, display: 'flex', flexDirection: 'column' }, children: chatSlot ?? (widgetProps ? ((0, jsx_runtime_1.jsx)(react_2.ChatWidget, { ...widgetProps, inline: true, variant: widgetProps.variant ?? 'bare' })) : null) })] })] }), portalEl);
+}

package/dist/entities.d.ts

@@ -160,6 +160,17 @@ export type ChatEvent = {
     type: 'error';
     message: string;
     code?: string;
+}
+/**
+ * Emitted exactly once per session, the moment the server hands us
+ * back the new conversation id after the visitor sent the first
+ * message. View layers use this to write the id into URL query
+ * (`?c=<id>`), localStorage, etc. so a refresh / drawer-reopen
+ * resumes the same conversation instead of starting fresh.
+ */
+ | {
+    type: 'conversation_started';
+    conversationId: string;
 } | {
     type: 'destroyed';
 };

package/dist/react.d.ts

@@ -77,6 +77,14 @@ export interface ChatWidgetProps {
     browserSessionId?: string;
     /** Existing conversation id to resume. */
     resumeConversationId?: string;
+    /**
+     * Fired exactly once per session, when the server hands back the
+     * new conversation id after the visitor sends their first message.
+     * Hosts use this to write the id to URL query, localStorage, etc.
+     * so a refresh or drawer-reopen resumes the same conversation.
+     * Not called when resuming an existing conversation (the host
+     * already has the id in that case). */
+    onConversationStart?: (conversationId: string) => void;
     /** Disable SSE streaming and use plain POSTs. */
     stream?: boolean;
     /** Extra class on the root container. */
@@ -151,6 +159,17 @@ export interface ChatWidgetProps {
      * behaviour).
      */
     members?: ChatTeamMember[];
+    /**
+     * Slot rendered inside the composer row, BEFORE the textarea. Hosts
+     * use this for affordances that scope or augment the next turn —
+     * e.g. a Team chat's member-picker chip (the "@<agent>" affordance),
+     * a tools menu à la Gemini, an attachment button.
+     *
+     * Kept as a generic React slot rather than a typed prop list so the
+     * SDK doesn't have to learn every product surface that wants to put
+     * something there.
+     */
+    composerLeftSlot?: React.ReactNode;
     /**
      * Imperative handle. The widget fills this ref on mount with a
      * small command object the host can call to drive the session
@@ -170,9 +189,20 @@ export interface ChatWidgetHandle {
      *  entirely. No-op if the session isn't ready yet (status ===
      *  'idle' / 'loading'). */
     sendNow(text: string): void;
+    /**
+     * Insert `text` into the composer's draft at the current cursor
+     * position (replacing any selection). Used by mention pickers,
+     * suggested-fragment chips, or slash-menu commands — the user
+     * sees the text appear in the input as if they had typed it and
+     * can keep editing before sending. Focus stays on the textarea
+     * and the cursor lands at the end of the inserted text.
+     */
+    insertText(text: string): void;
 }
 /**
  * Drop-in chat widget. Owns its own `ChatSession` and re-renders on every
  * SDK event. Consumers don't need to read `session.getState()` themselves.
  */
 export declare function ChatWidget(props: ChatWidgetProps): JSX.Element;
+export { ChatDrawer } from './ChatDrawer';
+export type { ChatDrawerProps } from './ChatDrawer';

package/dist/react.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatDrawer = void 0;
 exports.ChatWidget = ChatWidget;
 const jsx_runtime_1 = require("react/jsx-runtime");
 /**
@@ -227,7 +228,7 @@ function fallbackCopy(ctx) {
  * SDK event. Consumers don't need to read `session.getState()` themselves.
  */
 function ChatWidget(props) {
-    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, stream, className, style, onApprovalDecision, readOnlyApprovals = false, variant = 'card', greeting, personaName, shortcuts, onShortcutClick, inputPlaceholder, members, } = props;
+    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, onConversationStart, stream, className, style, onApprovalDecision, readOnlyApprovals = false, variant = 'card', greeting, personaName, shortcuts, onShortcutClick, inputPlaceholder, members, composerLeftSlot, handleRef, } = props;
     // Build a lookup so MessageBubble can resolve actingAgentId → identity
     // in O(1) per render without re-walking the members array. Stable
     // identity per `members` prop change.
@@ -259,6 +260,14 @@ function ChatWidget(props) {
     // ALWAYS — the user is mid-conversation, losing the cursor
     // breaks the typing-rhythm).
     const hasInteractedRef = (0, react_1.useRef)(false);
+    // Hold the latest `onConversationStart` in a ref so the session
+    // effect doesn't recreate the ChatSession every time the parent
+    // passes a new function identity (typical with inline arrow props).
+    // Recreating the session would wipe the transcript on every render.
+    const onConversationStartRef = (0, react_1.useRef)(onConversationStart);
+    (0, react_1.useEffect)(() => {
+        onConversationStartRef.current = onConversationStart;
+    }, [onConversationStart]);
     // Auto-focus the composer once the session is ready.
     //
     //   Landing (hasInteractedRef.current === false):
@@ -316,6 +325,10 @@ function ChatWidget(props) {
                 setLastError(evt.message);
                 return;
             }
+            if (evt.type === 'conversation_started') {
+                onConversationStartRef.current?.(evt.conversationId);
+                return;
+            }
         });
         void s.start();
         return () => {
@@ -379,6 +392,63 @@ function ChatWidget(props) {
             handleSend();
         }
     }, [handleSend]);
+    // Insert `text` at the current cursor position of the composer
+    // textarea. Replaces any active selection, advances the cursor to
+    // the end of the inserted slice, and keeps focus on the input so
+    // the user can keep typing without a click. Falls back to "append
+    // at the end" when the textarea isn't mounted yet (e.g. the host
+    // calls insertText before the session has booted).
+    const insertText = (0, react_1.useCallback)((text) => {
+        if (!text)
+            return;
+        const el = inputRef.current;
+        if (!el) {
+            setDraft((prev) => prev + text);
+            return;
+        }
+        const start = el.selectionStart ?? el.value.length;
+        const end = el.selectionEnd ?? el.value.length;
+        const before = el.value.slice(0, start);
+        const after = el.value.slice(end);
+        const next = before + text + after;
+        setDraft(next);
+        // Imperatively place the cursor after the commit. React's
+        // state update is async, so we wait one tick — by then the
+        // controlled value has flushed into the DOM and we can move
+        // the selection without it being clobbered.
+        queueMicrotask(() => {
+            const cursor = before.length + text.length;
+            el.focus({ preventScroll: true });
+            el.setSelectionRange(cursor, cursor);
+        });
+    }, []);
+    // Wire the imperative handle. The host's ref slot is filled in on
+    // every render so a late-binding consumer still gets the live
+    // closure (sendNow reads the latest session/state via the closure
+    // it captures here).
+    (0, react_1.useEffect)(() => {
+        if (!handleRef)
+            return;
+        handleRef.current = {
+            sendNow: (text) => {
+                if (!session)
+                    return;
+                const trimmed = text.trim();
+                if (!trimmed)
+                    return;
+                hasInteractedRef.current = true;
+                setDraft('');
+                void session.send(trimmed);
+            },
+            insertText,
+        };
+        return () => {
+            // Drop the handle on unmount so a stale ref can't fire send
+            // after the component is gone.
+            if (handleRef.current)
+                handleRef.current = null;
+        };
+    }, [handleRef, session, insertText]);
     const sendDisabled = !session ||
         status === 'idle' ||
         status === 'loading' ||
@@ -436,7 +506,14 @@ function ChatWidget(props) {
                                 ? { ...theme, avatarUrl: member.avatarUrl }
                                 : theme;
                             const bubbleAvatarName = member?.name ?? personaName ?? agent?.name;
-                            return ((0, jsx_runtime_1.jsx)(MessageBubble, { message: m, session: session, readOnly: readOnlyApprovals, onDecision: onApprovalDecision, bare: bare, showAvatar: showAvatar, avatarTheme: bubbleAvatarTheme, avatarName: bubbleAvatarName, speakerLabel: member?.name, onContinue: () => {
+                            // Seed for the deterministic-hue fallback avatar. Prefer
+                            // the acting agent id (so each member in a team gets its
+                            // own stable color) and fall back to the primary agent's
+                            // slug for solo chats / orchestrator-self turns. The
+                            // `agent` summary doesn't carry an id — slug is stable
+                            // and unique, which is all hueFromSeed needs.
+                            const bubbleAgentId = m.actingAgentId ?? agent?.slug;
+                            return ((0, jsx_runtime_1.jsx)(MessageBubble, { message: m, session: session, readOnly: readOnlyApprovals, onDecision: onApprovalDecision, bare: bare, showAvatar: showAvatar, avatarTheme: bubbleAvatarTheme, avatarName: bubbleAvatarName, avatarAgentId: bubbleAgentId, speakerLabel: member?.name, onContinue: () => {
                                     // After a successful Approve, kick the next turn so the
                                     // gate's fast-path consumes the approval and the tool
                                     // actually runs. `silent: true` keeps the literal
@@ -449,23 +526,23 @@ function ChatWidget(props) {
                                         void session.send('continue', { silent: true });
                                     }, 250);
                                 } }, m.id));
-                        }) }), lastError && status === 'error' && ((0, jsx_runtime_1.jsx)("div", { className: "af-error", children: lastError })), bare && greeting && messages.length === 0 && status !== 'loading' && ((0, jsx_runtime_1.jsx)("div", { className: "af-greeting-slot", children: (0, jsx_runtime_1.jsxs)("div", { className: "af-msg-row af-msg-row-assistant af-msg-row-greeting", children: [(0, jsx_runtime_1.jsx)(AssistantAvatar, { theme: theme, name: personaName ?? agent?.name, show: true }), (0, jsx_runtime_1.jsx)("div", { className: "af-msg af-msg-assistant af-msg-greeting", dangerouslySetInnerHTML: { __html: renderMarkdown(greeting) } })] }) })), shortcuts && shortcuts.length > 0 && messages.length === 0 && ((0, jsx_runtime_1.jsx)("div", { className: "af-shortcut-row", children: shortcuts.map((text, i) => ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-shortcut", onClick: () => {
+                        }) }), lastError && status === 'error' && ((0, jsx_runtime_1.jsx)("div", { className: "af-error", children: lastError })), bare && greeting && messages.length === 0 && status !== 'loading' && ((0, jsx_runtime_1.jsx)("div", { className: "af-greeting-slot", children: (0, jsx_runtime_1.jsxs)("div", { className: "af-msg-row af-msg-row-assistant af-msg-row-greeting", children: [(0, jsx_runtime_1.jsx)(AssistantAvatar, { theme: theme, name: personaName ?? agent?.name, agentId: agent?.slug, show: true }), (0, jsx_runtime_1.jsx)("div", { className: "af-msg af-msg-assistant af-msg-greeting", dangerouslySetInnerHTML: { __html: renderMarkdown(greeting) } })] }) })), shortcuts && shortcuts.length > 0 && messages.length === 0 && ((0, jsx_runtime_1.jsx)("div", { className: "af-shortcut-row", children: shortcuts.map((text, i) => ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-shortcut", onClick: () => {
                                 if (onShortcutClick)
                                     onShortcutClick(text, i);
                                 else
                                     setDraft(text);
-                            }, children: text }, `${i}-${text}`))) })), (0, jsx_runtime_1.jsxs)("div", { className: "af-input-row", children: [(0, jsx_runtime_1.jsx)("textarea", { ref: inputRef, className: "af-input", value: draft, onChange: (e) => setDraft(e.target.value), onKeyDown: onKeyDown, placeholder: inputPlaceholder ?? 'Type a message…', rows: 1, disabled: status === 'ended' || status === 'loading' || status === 'idle' }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-send", onClick: handleSend, disabled: sendDisabled, "aria-label": "Send message", children: (0, jsx_runtime_1.jsx)(SendIcon, {}) })] }), !bare && (0, jsx_runtime_1.jsx)("div", { className: "af-footer", children: "Powered by AgentForge" })] })] }));
+                            }, children: text }, `${i}-${text}`))) })), (0, jsx_runtime_1.jsxs)("div", { className: "af-input-row", children: [composerLeftSlot && ((0, jsx_runtime_1.jsx)("div", { className: "af-input-left", children: composerLeftSlot })), (0, jsx_runtime_1.jsx)("textarea", { ref: inputRef, className: "af-input", value: draft, onChange: (e) => setDraft(e.target.value), onKeyDown: onKeyDown, placeholder: inputPlaceholder ?? 'Type a message…', rows: 1, disabled: status === 'ended' || status === 'loading' || status === 'idle' }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-send", onClick: handleSend, disabled: sendDisabled, "aria-label": "Send message", children: (0, jsx_runtime_1.jsx)(SendIcon, {}) })] }), !bare && (0, jsx_runtime_1.jsx)("div", { className: "af-footer", children: "Powered by AgentForge" })] })] }));
 }
-function MessageBubble({ message, session, readOnly, onDecision, onContinue, bare = false, showAvatar = false, avatarTheme, avatarName, speakerLabel, }) {
+function MessageBubble({ message, session, readOnly, onDecision, onContinue, bare = false, showAvatar = false, avatarTheme, avatarName, avatarAgentId, speakerLabel, }) {
     const kind = message.metadata?.kind;
     if (kind === 'awaiting_approval') {
         // Approval / blocked bubbles also count as "assistant-side" so we
         // wrap them in the same row geometry — keeps the conversation
         // aligned even when a tool dispatch interrupts the regular flow.
-        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)(ApprovalBubble, { message: message, session: session, readOnly: readOnly, onDecision: onDecision, onContinue: onContinue }), speakerLabel);
+        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, avatarAgentId, (0, jsx_runtime_1.jsx)(ApprovalBubble, { message: message, session: session, readOnly: readOnly, onDecision: onDecision, onContinue: onContinue }), speakerLabel);
     }
     if (kind === 'tool_blocked') {
-        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)(BlockedBubble, { message: message }), speakerLabel);
+        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, avatarAgentId, (0, jsx_runtime_1.jsx)(BlockedBubble, { message: message }), speakerLabel);
     }
     const cls = `af-msg af-msg-${message.role}${message.role === 'assistant' && message.isStreaming
         ? message.content
@@ -474,10 +551,10 @@ function MessageBubble({ message, session, readOnly, onDecision, onContinue, bar
         : ''}`;
     // Typing state (no content yet): render the three-dot indicator, no markdown.
     if (message.role === 'assistant' && message.isStreaming && !message.content) {
-        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)("div", { className: cls, children: (0, jsx_runtime_1.jsxs)("span", { className: "af-typing-dots", "aria-label": "Assistant is typing", children: [(0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {})] }) }), speakerLabel);
+        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, avatarAgentId, (0, jsx_runtime_1.jsx)("div", { className: cls, children: (0, jsx_runtime_1.jsxs)("span", { className: "af-typing-dots", "aria-label": "Assistant is typing", children: [(0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {})] }) }), speakerLabel);
     }
     if (message.role === 'assistant') {
-        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, (0, jsx_runtime_1.jsx)("div", { className: cls, 
+        return wrapAssistantRow(bare, showAvatar, avatarTheme, avatarName, avatarAgentId, (0, jsx_runtime_1.jsx)("div", { className: cls, 
             // Output is sanitized by escapeHtml + a fixed tag whitelist in
             // renderMarkdown — safe to inject as HTML.
             dangerouslySetInnerHTML: { __html: renderMarkdown(message.content) } }), speakerLabel);
@@ -491,22 +568,27 @@ function MessageBubble({ message, session, readOnly, onDecision, onContinue, bar
  * avatar column. Card variant skips the wrapper entirely so its
  * historical layout is unchanged.
  */
-function wrapAssistantRow(bare, showAvatar, theme, name, child, 
+function wrapAssistantRow(bare, showAvatar, theme, name, agentId, child, 
 /** When set + this is the first bubble of a speaker run (showAvatar
  *  is true), render the speaker's display name just above the
  *  bubble. Used by Team chats so members are visually attributed. */
 speakerLabel) {
     if (!bare)
         return child;
-    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg-row af-msg-row-assistant", children: [(0, jsx_runtime_1.jsx)(AssistantAvatar, { theme: theme, name: name, show: showAvatar }), (0, jsx_runtime_1.jsxs)("div", { className: "af-msg-col", children: [showAvatar && speakerLabel ? ((0, jsx_runtime_1.jsx)("div", { className: "af-msg-speaker", children: speakerLabel })) : null, child] })] }));
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg-row af-msg-row-assistant", children: [(0, jsx_runtime_1.jsx)(AssistantAvatar, { theme: theme, name: name, agentId: agentId, show: showAvatar }), (0, jsx_runtime_1.jsxs)("div", { className: "af-msg-col", children: [showAvatar && speakerLabel ? ((0, jsx_runtime_1.jsx)("div", { className: "af-msg-speaker", children: speakerLabel })) : null, child] })] }));
 }
 /**
  * Small circular avatar for the assistant-side column. Prefers the
- * agent's avatarUrl when set; otherwise renders a gradient circle
- * with the first letter of `name`. The slot reserves space even when
- * `show` is false so consecutive bubbles stay column-aligned.
+ * agent's avatarUrl when set; otherwise renders a SOLID circle with
+ * the first letter of `name` over a hue derived from `agentId`. The
+ * hash → HSL mapping means every agent in a team gets a stable,
+ * distinguishable color across renders without us needing a palette
+ * table or per-agent config.
+ *
+ * The slot reserves space even when `show` is false so consecutive
+ * bubbles stay column-aligned.
  */
-function AssistantAvatar({ theme, name, show, }) {
+function AssistantAvatar({ theme, name, agentId, show, }) {
     const initial = (name ?? 'A').trim().charAt(0).toUpperCase() || 'A';
     if (!show) {
         return (0, jsx_runtime_1.jsx)("div", { className: "af-msg-avatar af-msg-avatar-spacer", "aria-hidden": true });
@@ -516,7 +598,21 @@ function AssistantAvatar({ theme, name, show, }) {
         // eslint-disable-next-line @next/next/no-img-element -- vanilla widget; consumer can override host
         (0, jsx_runtime_1.jsx)("img", { className: "af-msg-avatar af-msg-avatar-img", src: theme.avatarUrl, alt: "", "aria-hidden": true }));
     }
-    return ((0, jsx_runtime_1.jsx)("div", { className: "af-msg-avatar af-msg-avatar-fallback", "aria-hidden": true, children: (0, jsx_runtime_1.jsx)("span", { children: initial }) }));
+    const seed = agentId || name || 'agent';
+    return ((0, jsx_runtime_1.jsx)("div", { className: "af-msg-avatar af-msg-avatar-fallback", "aria-hidden": true, style: { backgroundColor: hueFromSeed(seed) }, children: (0, jsx_runtime_1.jsx)("span", { children: initial }) }));
+}
+/**
+ * Deterministic per-agent hue. Hash the seed into the HSL hue space
+ * so an agent's avatar color stays stable across renders and looks
+ * varied across a roster. Saturation/lightness are tuned for both
+ * light + dark chat surfaces: mid-saturation + mid-lightness reads
+ * legibly with white text on either background.
+ */
+function hueFromSeed(seed) {
+    let h = 0;
+    for (let i = 0; i < seed.length; i++)
+        h = (h * 31 + seed.charCodeAt(i)) >>> 0;
+    return `hsl(${h % 360} 60% 52%)`;
 }
 /**
  * Awaiting-approval bubble. Renders the tool name + a countdown, and
@@ -692,6 +788,11 @@ const WIDGET_CSS = `
   to { opacity: 1; transform: translateY(0); }
 }
 .af-input-row { padding: 12px; border-top: 1px solid var(--af-border); background: var(--af-bg); display: flex; gap: 8px; align-items: flex-end; }
+/* Composer left slot — hosts use this for affordance buttons that
+   scope the next turn (member picker, tools menu, attachments).
+   align-items: center keeps a single-line chip vertically centered
+   against the auto-growing textarea. */
+.af-input-left { display: flex; align-items: center; padding-bottom: 4px; flex-shrink: 0; }
 .af-shortcut-row {
   display: flex;
   gap: 6px;
@@ -815,7 +916,13 @@ const WIDGET_CSS = `
   background: transparent;
   border-radius: 0;
   box-shadow: none;
-  overflow: visible;
+  /* overflow:hidden so a long transcript (markdown tables, long
+     lists) scrolls inside af-messages instead of pushing the
+     af-input-row past the bottom of the host envelope. Was 'visible'
+     before, which let a tall message break out of the host sized
+     container and shove the composer off-screen. The messages region
+     itself carries overflow-y:auto so internal scroll keeps working. */
+  overflow: hidden;
   display: flex;
   flex-direction: column;
   flex: 1;
@@ -1048,7 +1155,11 @@ const WIDGET_CSS = `
   font-size: 11.5px;
   font-weight: 600;
   letter-spacing: 0.01em;
-  background-image: linear-gradient(135deg, var(--af-primary, #8b5cf6), color-mix(in srgb, var(--af-primary, #8b5cf6) 60%, #6366f1));
+  /* SOLID fill — the React component sets the actual color via an
+   * inline style.backgroundColor (deterministic hash of agentId).
+   * No gradient here on purpose: the gradient was masking the
+   * inline color and made every agent avatar look the same. */
+  background-color: var(--af-primary, #8b5cf6);
 }
 @media (min-width: 768px) {
   .af-widget-root.af-variant-bare .af-msg-avatar { width: 30px; height: 30px; }
@@ -1159,3 +1270,9 @@ const WIDGET_CSS = `
   }
 }
 `;
+// ─── Re-exports ───────────────────────────────────────────────────────
+// Bottom-sheet wrapper around the widget. Hosts that need the full
+// drawer UX (98% snap, visualViewport-aware composer, drag-to-dismiss)
+// import this from `@agentforge-io/chat-sdk/react` next to ChatWidget.
+var ChatDrawer_1 = require("./ChatDrawer");
+Object.defineProperty(exports, "ChatDrawer", { enumerable: true, get: function () { return ChatDrawer_1.ChatDrawer; } });

package/dist/session.js

@@ -211,6 +211,7 @@ class ChatSession {
             for await (const evt of generator) {
                 if (evt.kind === 'conversation') {
                     this.state.conversationId = evt.id;
+                    this.emit({ type: 'conversation_started', conversationId: evt.id });
                     continue;
                 }
                 if (evt.kind === 'chunk') {
@@ -398,6 +399,7 @@ class ChatSession {
             else {
                 const res = await this.transport.createConversation(text, this.browserSessionId);
                 this.state.conversationId = res.conversationId;
+                this.emit({ type: 'conversation_started', conversationId: res.conversationId });
                 content = res.content;
             }
             assistant.content = content;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/chat-sdk",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Framework-free chat session SDK for AgentForge public chat tokens. Headless — no DOM. Drop into any frontend (React, Vue, Svelte, vanilla) and listen for events.",
   "license": "MIT",
   "main": "dist/index.js",