@agentforge-io/chat-sdk 2.4.0-dev.3 → 2.4.0-dev.5

package/dist/ChatDrawer.d.ts

@@ -1,41 +1,24 @@
 /**
- * `<ChatDrawer>` — standard mobile chat shell.
+ * `<ChatDrawer>` — fullscreen mobile chat shell.
  *
- * Mobile-first fullscreen modal that wraps `<ChatWidget>` and gets the
- * three pieces of mobile UX every embed needs right:
+ * Plain `position: fixed` modal. No Vaul, no Radix Dialog, no focus
+ * trap. Those libraries fought us repeatedly: Radix's `onPointerDownOutside`
+ * mis-classified the Send tap as "interact outside" and closed the
+ * drawer; Radix's focus trap moved focus to the wrapper when the send
+ * button disabled, collapsing the mobile keyboard.
  *
- *   1. **Sticky header** at the top (back button + agent identity).
- *   2. **Scrollable transcript** in the middle (the SDK panel +
- *      its own scroller).
- *   3. **Sticky composer** at the bottom that NEVER hides under
- *      the on-screen keyboard.
- *
- * Why Vaul: implementing the keyboard-aware sticky composer with
- * vanilla `visualViewport` listeners is doable in 50 lines but the
- * real-world iOS Safari / Chrome Android edge cases (rubber-band
- * scroll, address-bar transitions, autocorrect bar over the keyboard,
- * focus loss on send button disable) are not. Vaul handles all of
- * them (used by Linear, Vercel, etc.). It's declared as an OPTIONAL
- * peerDependency so the SDK stays portable — if a host doesn't install
- * Vaul, `<ChatDrawer>` falls back to a render that asks the host to
- * install it. Most hosts already have Vaul (Radix design system).
- *
- * Why fullscreen (not snap points): the operator decision was that a
- * conversation should occupy the whole device. No drag-to-dismiss,
- * no peek of the page behind. Close via the explicit back button in
- * the header. This is the "modal" feel — predictable, no accidental
- * dismissals from a fast scroll.
- *
- * Why we still don't manage the chat session: the SDK's `ChatWidget`
- * owns that, this component is purely the surround.
+ * What this gives us:
+ *   - 100dvh (dynamic viewport height): the surface shrinks automatically
+ *     when the on-screen keyboard appears, so the composer stays above
+ *     the keys without any visualViewport bookkeeping.
+ *   - No focus interception: the textarea owns its own focus. As long
+ *     as the host's Send button uses `onPointerDown preventDefault`,
+ *     focus never leaves the textarea and the keyboard never collapses.
+ *   - No drag-to-dismiss, no click-outside, no ESC handling. The host
+ *     closes via the back chevron in its header.
  */
 import { type CSSProperties, type ReactNode } from 'react';
 import { type ChatWidgetProps } from './react';
-/**
- * Two intake shapes — either drop in a pre-built `<ChatWidget>` as
- * `chatSlot` (most hosts) or hand us the widget props and the drawer
- * mounts the widget itself.
- */
 type ChatSurface = {
     widgetProps: ChatWidgetProps;
     chatSlot?: never;
@@ -46,22 +29,21 @@ type ChatSurface = {
 export type ChatDrawerProps = ChatSurface & {
     /** Controlled visibility. */
     open: boolean;
-    /** Fired when the drawer wants to close (back button, ESC). The
-     *  host is responsible for setting `open=false`. */
+    /** Fired when the drawer wants to close. Today only the host's back
+     *  chevron emits this — no auto-dismiss paths exist. Kept in the
+     *  shape so the host doesn't have to change call sites. */
     onOpenChange: (open: boolean) => void;
-    /** Sticky header above the chat panel. Templates pass the agent /
-     *  team identity card here. Optional — when omitted the drawer
-     *  renders just the close button. */
+    /** Sticky header above the chat panel. */
     header?: ReactNode;
-    /** Custom close button. Defaults to a chevron-left back button at
-     *  the left edge of the header. */
+    /** Custom close button rendered ABOVE `header`. Default is the SDK's
+     *  chevron-left. Pass `null` to opt out (when the host renders its
+     *  own close affordance inline within `header`). */
     closeButton?: ReactNode;
-    /** Extra class on the drawer surface (the full-height card). */
+    /** Extra class on the drawer surface. */
     drawerClassName?: string;
-    /** CSS variables (`--af-bg`, `--af-fg`, `--af-bubble-*`, etc.) for
-     *  the drawer surface. Because the drawer renders into a portal,
-     *  the host's page-wrapper vars don't cascade in — re-declare them
-     *  here so the chat surface theme matches. */
+    /** CSS vars (`--af-bg`, `--af-fg`, `--af-bubble-*`, …) for the
+     *  surface. The drawer renders into a portal, so the host's
+     *  page-wrapper vars don't cascade in — re-declare them here. */
     surfaceStyle?: CSSProperties & Record<string, string>;
 };
 export declare function ChatDrawer(props: ChatDrawerProps): JSX.Element | null;

package/dist/ChatDrawer.js

@@ -3,59 +3,36 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatDrawer = ChatDrawer;
 const jsx_runtime_1 = require("react/jsx-runtime");
 /**
- * `<ChatDrawer>` — standard mobile chat shell.
+ * `<ChatDrawer>` — fullscreen mobile chat shell.
  *
- * Mobile-first fullscreen modal that wraps `<ChatWidget>` and gets the
- * three pieces of mobile UX every embed needs right:
+ * Plain `position: fixed` modal. No Vaul, no Radix Dialog, no focus
+ * trap. Those libraries fought us repeatedly: Radix's `onPointerDownOutside`
+ * mis-classified the Send tap as "interact outside" and closed the
+ * drawer; Radix's focus trap moved focus to the wrapper when the send
+ * button disabled, collapsing the mobile keyboard.
  *
- *   1. **Sticky header** at the top (back button + agent identity).
- *   2. **Scrollable transcript** in the middle (the SDK panel +
- *      its own scroller).
- *   3. **Sticky composer** at the bottom that NEVER hides under
- *      the on-screen keyboard.
- *
- * Why Vaul: implementing the keyboard-aware sticky composer with
- * vanilla `visualViewport` listeners is doable in 50 lines but the
- * real-world iOS Safari / Chrome Android edge cases (rubber-band
- * scroll, address-bar transitions, autocorrect bar over the keyboard,
- * focus loss on send button disable) are not. Vaul handles all of
- * them (used by Linear, Vercel, etc.). It's declared as an OPTIONAL
- * peerDependency so the SDK stays portable — if a host doesn't install
- * Vaul, `<ChatDrawer>` falls back to a render that asks the host to
- * install it. Most hosts already have Vaul (Radix design system).
- *
- * Why fullscreen (not snap points): the operator decision was that a
- * conversation should occupy the whole device. No drag-to-dismiss,
- * no peek of the page behind. Close via the explicit back button in
- * the header. This is the "modal" feel — predictable, no accidental
- * dismissals from a fast scroll.
- *
- * Why we still don't manage the chat session: the SDK's `ChatWidget`
- * owns that, this component is purely the surround.
+ * What this gives us:
+ *   - 100dvh (dynamic viewport height): the surface shrinks automatically
+ *     when the on-screen keyboard appears, so the composer stays above
+ *     the keys without any visualViewport bookkeeping.
+ *   - No focus interception: the textarea owns its own focus. As long
+ *     as the host's Send button uses `onPointerDown preventDefault`,
+ *     focus never leaves the textarea and the keyboard never collapses.
+ *   - No drag-to-dismiss, no click-outside, no ESC handling. The host
+ *     closes via the back chevron in its header.
  */
 const react_1 = require("react");
 const react_2 = require("./react");
-// Lazy import of Vaul. We can't `import { Drawer } from 'vaul'` at
-// the top of the file because vaul is an OPTIONAL peerDependency
-// and the package shouldn't crash at import-time when the host
-// hasn't installed it. We resolve at module evaluation but inside a
-// try/catch so the missing-vaul case is just a runtime "please
-// install vaul" warning instead of a build break.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-let VaulDrawer = null;
-try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    VaulDrawer = require('vaul').Drawer;
-}
-catch {
-    // vaul not installed — render a fallback in the component.
-}
 function ChatDrawer(props) {
     const { open, onOpenChange, header, closeButton, drawerClassName, surfaceStyle, widgetProps, chatSlot, } = props;
-    // Body scroll lock — Vaul does this internally on open, but it
-    // also restores on unmount, which interacts badly with a portal
-    // re-mount when the drawer re-renders during a heavy parent
-    // update. Belt-and-braces.
+    // Defer the first paint until after mount so SSR doesn't try to
+    // render a portal target that doesn't exist yet.
+    const [mounted, setMounted] = (0, react_1.useState)(false);
+    (0, react_1.useEffect)(() => {
+        setMounted(true);
+    }, []);
+    // Lock body scroll while the drawer is open. Standard pattern: save
+    // the previous overflow, set hidden, restore on close/unmount.
     (0, react_1.useEffect)(() => {
         if (typeof document === 'undefined')
             return;
@@ -67,73 +44,31 @@ function ChatDrawer(props) {
             document.body.style.overflow = prev;
         };
     }, [open]);
-    if (!VaulDrawer) {
-        // Host hasn't installed vaul. We log a one-time warning and
-        // render nothing. Most hosts that hit this never wanted the
-        // drawer in the first place (they're using ChatWidget inline).
-        if (open && typeof console !== 'undefined') {
-            console.warn('[@agentforge-io/chat-sdk] <ChatDrawer> requires `vaul` to render. ' +
-                'Install it with `npm install vaul` or `yarn add vaul`. ' +
-                'The drawer is a no-op until vaul is available.');
-        }
+    if (!mounted || !open)
         return null;
-    }
     const chatNode = chatSlot ?? (widgetProps ? ((0, jsx_runtime_1.jsx)(react_2.ChatWidget, { ...widgetProps, inline: true, variant: widgetProps.variant ?? 'bare' })) : null);
-    return ((0, jsx_runtime_1.jsx)(VaulDrawer.Root, { open: open, onOpenChange: onOpenChange, 
-        // `direction="bottom"` is the standard bottom-sheet origin.
-        direction: "bottom", 
-        // No drag-to-dismiss. The visitor closes with the explicit
-        // back button in the header (or ESC). Prevents accidental
-        // dismissals when the visitor scrolls fast in the transcript.
-        dismissible: false, 
-        // No native snap points — we WANT fullscreen.
-        shouldScaleBackground: false, children: (0, jsx_runtime_1.jsxs)(VaulDrawer.Portal, { children: [(0, jsx_runtime_1.jsx)(VaulDrawer.Overlay, { className: "af-drawer-overlay", style: {
-                        position: 'fixed',
-                        inset: 0,
-                        backgroundColor: 'rgba(0, 0, 0, 0.6)',
-                        zIndex: 2147483600,
-                    } }), (0, jsx_runtime_1.jsxs)(VaulDrawer.Content, { className: `af-drawer-surface ${drawerClassName ?? ''}`, style: {
-                        // Fullscreen: 100% of the visual viewport height. Vaul
-                        // tracks visualViewport internally so this height
-                        // shrinks when the keyboard pops up, keeping the
-                        // composer always above the keys.
-                        position: 'fixed',
-                        inset: 0,
-                        zIndex: 2147483600,
-                        display: 'flex',
-                        flexDirection: 'column',
-                        outline: 'none',
-                        backgroundColor: 'var(--af-bg, #ffffff)',
-                        color: 'var(--af-fg, inherit)',
-                        // Re-apply the host's theme vars on the portalled
-                        // surface so the chat widget below picks them up. The
-                        // `--af-bg` declared here is what the chat panel reads
-                        // for its message background; without this the drawer
-                        // would strobe white over a dark themed page.
-                        ...surfaceStyle,
-                    }, children: [(0, jsx_runtime_1.jsx)(VaulDrawer.Title, { style: {
-                                position: 'absolute',
-                                width: '1px',
-                                height: '1px',
-                                padding: 0,
-                                margin: '-1px',
-                                overflow: 'hidden',
-                                clip: 'rect(0, 0, 0, 0)',
-                                whiteSpace: 'nowrap',
-                                border: 0,
-                            }, children: "Chat" }), (0, jsx_runtime_1.jsxs)("div", { style: {
-                                flexShrink: 0,
-                                position: 'sticky',
-                                top: 0,
-                                zIndex: 1,
-                                backgroundColor: 'var(--af-bg, #ffffff)',
-                                borderBottom: '1px solid var(--af-border, rgba(15, 23, 42, 0.08))',
-                            }, children: [closeButton === undefined ? ((0, jsx_runtime_1.jsx)(DefaultCloseButton, { onClose: () => onOpenChange(false) })) : (closeButton), header] }), (0, jsx_runtime_1.jsx)("div", { style: {
-                                flex: 1,
-                                minHeight: 0,
-                                display: 'flex',
-                                flexDirection: 'column',
-                            }, "data-af-drawer-body": true, children: chatNode })] })] }) }));
+    return ((0, jsx_runtime_1.jsxs)("div", { role: "dialog", "aria-modal": "true", "aria-label": "Chat", className: `af-drawer-surface ${drawerClassName ?? ''}`, style: {
+            // 100dvh shrinks when the on-screen keyboard appears.
+            // `inset: 0` + `position: fixed` covers the viewport.
+            position: 'fixed',
+            inset: 0,
+            height: '100dvh',
+            zIndex: 2147483600,
+            display: 'flex',
+            flexDirection: 'column',
+            backgroundColor: 'var(--af-bg, #ffffff)',
+            color: 'var(--af-fg, inherit)',
+            ...surfaceStyle,
+        }, children: [(0, jsx_runtime_1.jsxs)("div", { style: {
+                    flexShrink: 0,
+                    backgroundColor: 'var(--af-bg, #ffffff)',
+                    borderBottom: '1px solid var(--af-border, rgba(15, 23, 42, 0.08))',
+                }, children: [closeButton === undefined ? ((0, jsx_runtime_1.jsx)(DefaultCloseButton, { onClose: () => onOpenChange(false) })) : (closeButton), header] }), (0, jsx_runtime_1.jsx)("div", { style: {
+                    flex: 1,
+                    minHeight: 0,
+                    display: 'flex',
+                    flexDirection: 'column',
+                }, "data-af-drawer-body": true, children: chatNode })] }));
 }
 function DefaultCloseButton({ onClose }) {
     return ((0, jsx_runtime_1.jsx)("div", { style: {

package/dist/react.js

@@ -268,20 +268,28 @@ function ChatWidget(props) {
     (0, react_1.useEffect)(() => {
         onConversationStartRef.current = onConversationStart;
     }, [onConversationStart]);
-    // Auto-focus the composer once the session is ready. We always
-    // focus — even on touch devices — because:
-    //   • On mobile the chat is opened from a drawer behind a tap.
-    //     That tap is a user gesture that authorises opening the
-    //     keyboard, so it's NOT jarring to focus the textarea.
-    //   • On desktop the user expects ready-to-type.
-    //   • After a send, the visitor is in conversation rhythm and
-    //     the keyboard MUST stay alive.
+    // Auto-focus the composer ONCE, the first time the session
+    // reaches `ready` AND the textarea is enabled. After that,
+    // focus is preserved by the composer's `onPointerDown
+    // preventDefault` (the send button never steals it) and by NOT
+    // firing focus() on every status change. That used to cause a
+    // visible "blink": status flips `ready → sending → streaming →
+    // ready` on every send, and a status-watching focus effect
+    // would refocus AFTER the keyboard had already started
+    // collapsing, producing the jitter.
+    const focusedOnceRef = (0, react_1.useRef)(false);
     (0, react_1.useEffect)(() => {
+        if (focusedOnceRef.current)
+            return;
         if (status !== 'ready')
             return;
         if (typeof window === 'undefined')
             return;
-        inputRef.current?.focus({ preventScroll: true });
+        const el = inputRef.current;
+        if (!el || el.disabled)
+            return;
+        el.focus({ preventScroll: true });
+        focusedOnceRef.current = true;
     }, [status]);
     // ── Session lifecycle. Recreate when token / apiBaseUrl changes. ──────
     (0, react_1.useEffect)(() => {
@@ -370,25 +378,14 @@ function ChatWidget(props) {
         const text = draft.trim();
         if (!text)
             return;
-        // Mark engagement BEFORE the status flip so the auto-focus
-        // effect (which watches `status`) sees the flag when it
-        // re-runs after `ready` returns. Subsequent renders will
-        // refocus the textarea on every send completion.
         hasInteractedRef.current = true;
         setDraft('');
+        // session.send awaits start() internally, so it's safe to fire
+        // even before the initial agent/theme fetch resolves. The send
+        // button's `onPointerDown preventDefault` keeps the textarea
+        // focused through tap/click, so we don't manually re-focus
+        // here (manual focus during the status flip caused a blink).
         void session.send(text);
-        // Mobile UX: when the send button disables (sendDisabled flips
-        // true the moment status goes to 'sending'), focus would jump to
-        // <body> and the on-screen keyboard would collapse. The send
-        // button uses `onMouseDown preventDefault` to keep the textarea
-        // focused through the click, but we still re-anchor focus here
-        // as a one-shot synchronous fallback (e.g. Enter-key submit on a
-        // hardware keyboard). NO rAF retry — that caused a visible focus
-        // blink on mobile (focus left, came back a frame later).
-        const el = inputRef.current;
-        if (el && document.activeElement !== el) {
-            el.focus({ preventScroll: true });
-        }
     }, [session, draft]);
     const onKeyDown = (0, react_1.useCallback)((e) => {
         if (e.key === 'Enter' && !e.shiftKey) {

package/dist/session.d.ts

@@ -23,12 +23,13 @@ export declare class ChatSession {
     private readonly resumeId?;
     private listeners;
     private state;
-    private started;
+    private startPromise;
     constructor(opts: ChatSessionOptions);
     /** Returns an unsubscribe function. Listeners are called synchronously. */
     onEvent(listener: Listener): () => void;
     getState(): ChatSessionState;
     start(): Promise<void>;
+    private runStart;
     /**
      * Mark the active conversation as ended on the server and lock the
      * session locally. After this, sends throw — the consumer should drop

package/dist/session.js

@@ -25,7 +25,13 @@ class ChatSession {
             status: 'idle',
             messages: [],
         };
-        this.started = false;
+        // Tracks the in-flight (or completed) `start()` invocation.
+        // Used so concurrent callers — typically a React effect that
+        // fires `void s.start()` AND a user that taps Send before
+        // start resolved — both await the SAME promise instead of
+        // either firing two starts or skipping the wait entirely.
+        // Resolves once status reaches `ready`/`ended` (or throws).
+        this.startPromise = null;
         if (!opts.token)
             throw new Error('ChatSession: token is required');
         const apiBaseUrl = opts.apiBaseUrl ?? defaultApiBase();
@@ -49,9 +55,14 @@ class ChatSession {
     }
     // ─── Lifecycle ──────────────────────────────────────────────────────────
     async start() {
-        if (this.started)
-            return;
-        this.started = true;
+        // Idempotent: if another caller already kicked off start(),
+        // join their promise. Critical for the React + send race.
+        if (this.startPromise)
+            return this.startPromise;
+        this.startPromise = this.runStart();
+        return this.startPromise;
+    }
+    async runStart() {
         this.setStatus('loading');
         try {
             const { agent, theme } = await this.transport.getAgent();
@@ -141,7 +152,7 @@ class ChatSession {
         this.emit({ type: 'destroyed' });
         // Drop everything — a destroyed session shouldn't be reused.
         this.state = { status: 'idle', messages: [] };
-        this.started = false;
+        this.startPromise = null;
     }
     // ─── User actions ───────────────────────────────────────────────────────
     /**
@@ -164,8 +175,11 @@ class ChatSession {
         if (this.state.status === 'ended') {
             throw new Error('Conversation has ended. Start a fresh chat to continue.');
         }
-        if (!this.started)
-            await this.start();
+        // Always await start — start() is idempotent and resolves
+        // immediately if it already completed. This closes the race
+        // where the user taps Send while the initial agent/theme
+        // fetch is still in flight and conversationId is unset.
+        await this.start();
         if (!opts?.silent) {
             this.appendMessage({
                 id: makeMessageId('u'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/chat-sdk",
-  "version": "2.4.0-dev.3",
+  "version": "2.4.0-dev.5",
   "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",
@@ -24,15 +24,11 @@
     "clean": "rm -rf dist *.tgz"
   },
   "peerDependencies": {
-    "react": ">=18.0.0",
-    "vaul": ">=1.0.0"
+    "react": ">=18.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
-    },
-    "vaul": {
-      "optional": true
     }
   },
   "devDependencies": {
@@ -40,7 +36,6 @@
     "@types/react": "^18.3.28",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
-    "typescript": "^5.0.0",
-    "vaul": "^1.1.2"
+    "typescript": "^5.0.0"
   }
 }