@agentforge-io/chat-sdk 2.4.0-dev.12 → 2.4.0-dev.2

package/dist/ChatDrawer.d.ts

@@ -1,60 +1,40 @@
 /**
- * `<ChatDrawer>` — standard bottom-sheet wrapper around `<ChatWidget>`.
+ * `<ChatDrawer>` — standard mobile chat shell.
  *
- * 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.
+ * Mobile-first fullscreen modal that wraps `<ChatWidget>` and gets the
+ * three pieces of mobile UX every embed needs right:
  *
- * 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.
+ *   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.
  *
- * 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)`.
+ * 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.
  */
 import { type CSSProperties, 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.
+ * 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;
@@ -64,39 +44,24 @@ type ChatSurface = {
     widgetProps?: never;
 };
 export type ChatDrawerProps = ChatSurface & {
-    /** Whether the drawer is visible. Controlled. */
+    /** Controlled visibility. */
     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`. */
+    /** Fired when the drawer wants to close (back button, ESC). The
+     *  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. */
+    /** Sticky header above the chat panel. Templates pass the agent /
+     *  team identity card here. Optional — when omitted the drawer
+     *  renders just the close button. */
     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. */
+    /** Custom close button. Defaults to a chevron-left back button at
+     *  the left edge of the header. */
+    closeButton?: ReactNode;
+    /** Extra class on the drawer surface (the full-height card). */
     drawerClassName?: string;
-    /** Inline style applied to the drawer surface — typically the host's
-     *  bundle of `--af-bg`, `--af-fg`, `--af-bubble-*`, etc. CSS vars.
-     *  Because the drawer renders into a portal (`document.body`), any
-     *  vars declared on the host's page wrapper DON'T cascade in. The
-     *  host re-declares them here so the chat surface inside the portal
-     *  picks up the same theme.
-     *
-     *  We default the SURFACE BG to `var(--af-bg, …)` so passing
-     *  `--af-bg` in `surfaceStyle` themes the drawer's background.
-     *  When omitted the drawer falls back to white in light mode and
-     *  the system default elsewhere — passable but not theme-perfect. */
+    /** 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. */
     surfaceStyle?: CSSProperties & Record<string, string>;
 };
 export declare function ChatDrawer(props: ChatDrawerProps): JSX.Element | null;

package/dist/ChatDrawer.js

@@ -3,143 +3,59 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatDrawer = ChatDrawer;
 const jsx_runtime_1 = require("react/jsx-runtime");
 /**
- * `<ChatDrawer>` — standard bottom-sheet wrapper around `<ChatWidget>`.
+ * `<ChatDrawer>` — standard mobile chat shell.
  *
- * 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.
+ * Mobile-first fullscreen modal that wraps `<ChatWidget>` and gets the
+ * three pieces of mobile UX every embed needs right:
  *
- * 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.
+ *   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.
  *
- * 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)`.
+ * 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.
  */
 const react_1 = require("react");
-const react_dom_1 = require("react-dom");
 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, snap = 1, header, closeOnBackdropClick = true, drawerClassName, surfaceStyle: surfaceStyleProp, widgetProps, chatSlot, } = props;
-    // `fullscreen` mode: snap=1 (the default). The drawer occupies the
-    // entire visible viewport. We disable drag-to-dismiss, the backdrop,
-    // the rounded top corners, and the drag handle in this mode — they
-    // exist purely for the bottom-sheet form factor (snap<1) where the
-    // page peeks behind the surface. With snap=1 there's nothing behind
-    // and no affordance to drag against.
-    const fullscreen = snap >= 1;
-    // 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.
+    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.
     (0, react_1.useEffect)(() => {
         if (typeof document === 'undefined')
             return;
@@ -151,127 +67,90 @@ function ChatDrawer(props) {
             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;
-    // Motion / sizing portion of the surface style, kept separate from
-    // the host-supplied theming so a re-render driven by drag offset
-    // doesn't smash the host's CSS vars.
-    //
-    // Two distinct positioning modes:
-    //
-    // **fullscreen (snap=1)**: pin the surface to the VISUAL viewport
-    // box. `top = visualViewport.offsetTop` + `height = visualViewport.h`
-    // means the drawer sits exactly on the area the user can see, with
-    // the bottom edge flush against the on-screen keyboard (when it's up)
-    // or the bottom of the screen (when it's down). No layout viewport
-    // gymnastics needed.
-    //
-    // **bottom-sheet (snap<1)**: anchor the surface to the bottom of the
-    // visual viewport. `bottom = visualViewport.offsetTop` is the legacy
-    // path that handles the rubber-band scroll case on iOS Safari.
-    const surfaceMotionStyle = fullscreen
-        ? {
-            top: `${vv.offsetTop}px`,
-            height: `${vv.h}px`,
-            transform: `translate3d(0, ${translateY}, 0)`,
-            transition: isDragging
-                ? 'none'
-                : 'transform 240ms cubic-bezier(.32,.72,0,1)',
-            willChange: 'transform',
+    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.');
         }
-        : {
-            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: [!fullscreen && ((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%',
-                    // Host supplies the CSS vars via `surfaceStyle`; the
-                    // backgroundColor resolves from `--af-bg` (which the host
-                    // declares in that same prop). When `surfaceStyle` is
-                    // omitted we fall back to white — passable for an unthemed
-                    // demo, wrong for a themed embed; passing surfaceStyle is
-                    // the correct path.
-                    backgroundColor: 'var(--af-bg, #ffffff)',
-                    color: 'var(--af-fg, inherit)',
-                    // Bottom-sheet visuals only — fullscreen mode is flat.
-                    borderTopLeftRadius: fullscreen ? 0 : '16px',
-                    borderTopRightRadius: fullscreen ? 0 : '16px',
-                    boxShadow: fullscreen ? 'none' : '0 -8px 24px rgba(15, 23, 42, 0.25)',
-                    display: 'flex',
-                    flexDirection: 'column',
-                    overflow: 'hidden',
-                    // Host-supplied theme vars come FIRST so the motion
-                    // properties below override any conflicting `transform` /
-                    // `height` declarations a careless host might pass.
-                    ...surfaceStyleProp,
-                    ...surfaceMotionStyle,
-                }, children: [!fullscreen && ((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);
+        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 })] })] }) }));
+}
+function DefaultCloseButton({ onClose }) {
+    return ((0, jsx_runtime_1.jsx)("div", { style: {
+            display: 'flex',
+            alignItems: 'center',
+            padding: '8px 12px',
+        }, children: (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: onClose, "aria-label": "Close chat", style: {
+                appearance: 'none',
+                background: 'transparent',
+                border: 'none',
+                padding: '8px',
+                margin: 0,
+                cursor: 'pointer',
+                color: 'var(--af-fg, inherit)',
+                display: 'inline-flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                borderRadius: '8px',
+            }, children: (0, jsx_runtime_1.jsx)("svg", { width: "20", height: "20", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, children: (0, jsx_runtime_1.jsx)("polyline", { points: "15 18 9 12 15 6" }) }) }) }));
 }

package/dist/react.d.ts

@@ -198,26 +198,6 @@ export interface ChatWidgetHandle {
      * and the cursor lands at the end of the inserted text.
      */
     insertText(text: string): void;
-    /**
-     * Move keyboard focus to the composer textarea. Use when the
-     * host UI surfaces the widget late (e.g. opening a drawer) and
-     * wants the on-screen keyboard up immediately. Safe no-op when
-     * the textarea hasn't mounted yet or is disabled.
-     */
-    focus(): void;
-    /**
-     * Warm up the underlying session — fires the initial
-     * `GET /agent` (and optionally a `resumeConversation` lookup) so
-     * the first `send()` doesn't pay the round-trip. Idempotent:
-     * subsequent calls join the same in-flight promise.
-     *
-     * Hosts call this when the visitor signals INTENT to chat (e.g.
-     * tapping a fake-composer pill that opens a drawer) so the
-     * session boot overlaps with the visitor finding the keyboard
-     * and tapping out their first message. Safe no-op if the session
-     * is already past `loading`.
-     */
-    warmup(): void;
 }
 /**
  * Drop-in chat widget. Owns its own `ChatSession` and re-renders on every

package/dist/react.js

@@ -268,28 +268,20 @@ function ChatWidget(props) {
     (0, react_1.useEffect)(() => {
         onConversationStartRef.current = onConversationStart;
     }, [onConversationStart]);
-    // 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);
+    // 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.
     (0, react_1.useEffect)(() => {
-        if (focusedOnceRef.current)
-            return;
         if (status !== 'ready')
             return;
         if (typeof window === 'undefined')
             return;
-        const el = inputRef.current;
-        if (!el || el.disabled)
-            return;
-        el.focus({ preventScroll: true });
-        focusedOnceRef.current = true;
+        inputRef.current?.focus({ preventScroll: true });
     }, [status]);
     // ── Session lifecycle. Recreate when token / apiBaseUrl changes. ──────
     (0, react_1.useEffect)(() => {
@@ -378,14 +370,25 @@ 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) {
@@ -442,20 +445,6 @@ function ChatWidget(props) {
                 void session.send(trimmed);
             },
             insertText,
-            focus: () => {
-                const el = inputRef.current;
-                if (!el || el.disabled)
-                    return;
-                el.focus({ preventScroll: true });
-            },
-            warmup: () => {
-                // session.start() is idempotent — joins the in-flight
-                // promise if one exists, resolves immediately if start
-                // already completed.
-                if (!session)
-                    return;
-                void session.start();
-            },
         };
         return () => {
             // Drop the handle on unmount so a stale ref can't fire send
@@ -546,31 +535,20 @@ function ChatWidget(props) {
                                     onShortcutClick(text, i);
                                 else
                                     setDraft(text);
-                            }, children: text }, `${i}-${text}`))) })), (0, jsx_runtime_1.jsxs)("div", { className: "af-input-row", "data-loading": status === 'loading' || status === 'idle' ? '' : undefined, 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: status === 'idle' || status === 'loading'
-                                    ? 'Preparing chat…'
-                                    : inputPlaceholder ?? 'Type a message…', rows: 1, 
+                            }, 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, 
                                 // The textarea stays editable while the agent is
                                 // streaming so the visitor can compose their next
                                 // message without waiting. Only block when the
                                 // conversation has actually ended OR before the
                                 // session is ready at all.
                                 disabled: status === 'ended' || status === 'loading' || status === 'idle' }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-send", 
-                                // `onPointerDown preventDefault` is the single cross-
-                                // device guarantee that the button never steals focus
-                                // from the textarea. PointerEvents cover touch, mouse,
-                                // AND pen — `onMouseDown` alone misses mobile touch.
-                                // Without this, the focus shifts to the button just
-                                // before `handleSend` runs, the button then disables
-                                // (sendDisabled flips true on status change), focus
-                                // jumps to <body>, and the on-screen keyboard collapses.
-                                onPointerDown: (e) => e.preventDefault(), onClick: handleSend, disabled: sendDisabled, "aria-label": status === 'sending' || status === 'streaming'
-                                    ? 'Sending message'
-                                    : status === 'idle' || status === 'loading'
-                                        ? 'Preparing chat'
-                                        : 'Send message', children: status === 'sending' ||
-                                    status === 'streaming' ||
-                                    status === 'idle' ||
-                                    status === 'loading' ? ((0, jsx_runtime_1.jsx)(SpinnerIcon, {})) : ((0, jsx_runtime_1.jsx)(SendIcon, {})) })] }), !bare && (0, jsx_runtime_1.jsx)("div", { className: "af-footer", children: "Powered by AgentForge" })] })] }));
+                                // `onMouseDown preventDefault` prevents the button from
+                                // stealing focus from the textarea when the visitor
+                                // taps Send. Without this, the focus shifts to the
+                                // button just before `handleSend` runs, the button
+                                // then disables (sendDisabled flips true), focus jumps
+                                // to <body>, and on mobile the keyboard collapses.
+                                onMouseDown: (e) => e.preventDefault(), 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, avatarAgentId, speakerLabel, }) {
     const kind = message.metadata?.kind;
@@ -743,11 +721,6 @@ function CloseIcon() {
 function SendIcon() {
     return ((0, jsx_runtime_1.jsxs)("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, children: [(0, jsx_runtime_1.jsx)("line", { x1: "22", y1: "2", x2: "11", y2: "13" }), (0, jsx_runtime_1.jsx)("polygon", { points: "22 2 15 22 11 13 2 9 22 2" })] }));
 }
-function SpinnerIcon() {
-    // Inline SVG spinner — no external dep. Stroke-dasharray
-    // arc rotates via the CSS keyframes injected by WIDGET_CSS.
-    return ((0, jsx_runtime_1.jsxs)("svg", { viewBox: "0 0 24 24", fill: "none", className: "af-spinner", "aria-hidden": true, children: [(0, jsx_runtime_1.jsx)("circle", { cx: "12", cy: "12", r: "9", stroke: "currentColor", strokeOpacity: "0.25", strokeWidth: "2.5" }), (0, jsx_runtime_1.jsx)("path", { d: "M21 12a9 9 0 0 0-9-9", stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round" })] }));
-}
 // Stylesheet kept verbatim from the standalone widget.js so the React
 // component is visually indistinguishable from the script-injected one.
 const WIDGET_CSS = `
@@ -832,8 +805,6 @@ 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; }
-.af-input-row[data-loading] .af-input { cursor: progress; opacity: 0.7; }
-.af-input-row[data-loading] .af-input::placeholder { font-style: italic; }
 /* 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
@@ -893,8 +864,6 @@ const WIDGET_CSS = `
 .af-send:active:not(:disabled) { transform: translateY(0); }
 .af-send:disabled { opacity: 0.5; cursor: not-allowed; }
 .af-send svg { width: 16px; height: 16px; }
-.af-send .af-spinner { animation: af-spin 720ms linear infinite; }
-@keyframes af-spin { to { transform: rotate(360deg); } }
 .af-error { padding: 10px 16px; font-size: 12px; color: #b91c1c; background: #fef2f2; border-top: 1px solid #fee2e2; }
 .af-footer { padding: 6px 12px; font-size: 10px; color: var(--af-muted); text-align: center; background: var(--af-bubble-bg); border-top: 1px solid var(--af-border); }
 /* Approval and blocked bubbles. Amber for needs-decision, red for

package/dist/session.d.ts

@@ -23,13 +23,12 @@ export declare class ChatSession {
     private readonly resumeId?;
     private listeners;
     private state;
-    private startPromise;
+    private started;
     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
@@ -69,7 +68,6 @@ export declare class ChatSession {
     private removeMessage;
     private setStatus;
     private emitStateChange;
-    private debug;
     private handleError;
     private emit;
 }

package/dist/session.js

@@ -25,13 +25,7 @@ class ChatSession {
             status: 'idle',
             messages: [],
         };
-        // 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;
+        this.started = false;
         if (!opts.token)
             throw new Error('ChatSession: token is required');
         const apiBaseUrl = opts.apiBaseUrl ?? defaultApiBase();
@@ -55,14 +49,9 @@ class ChatSession {
     }
     // ─── Lifecycle ──────────────────────────────────────────────────────────
     async start() {
-        // 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() {
+        if (this.started)
+            return;
+        this.started = true;
         this.setStatus('loading');
         try {
             const { agent, theme } = await this.transport.getAgent();
@@ -152,7 +141,7 @@ class ChatSession {
         this.emit({ type: 'destroyed' });
         // Drop everything — a destroyed session shouldn't be reused.
         this.state = { status: 'idle', messages: [] };
-        this.startPromise = null;
+        this.started = false;
     }
     // ─── User actions ───────────────────────────────────────────────────────
     /**
@@ -172,16 +161,11 @@ class ChatSession {
         const trimmed = text.trim();
         if (!trimmed)
             return '';
-        this.debug('send() called', { text: trimmed, status: this.state.status });
         if (this.state.status === 'ended') {
             throw new Error('Conversation has ended. Start a fresh chat to continue.');
         }
-        // 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();
-        this.debug('send() start awaited, status=' + this.state.status);
+        if (!this.started)
+            await this.start();
         if (!opts?.silent) {
             this.appendMessage({
                 id: makeMessageId('u'),
@@ -205,7 +189,6 @@ class ChatSession {
     }
     // ─── Internals ──────────────────────────────────────────────────────────
     async runStream(text, assistant) {
-        this.debug('runStream start', { hasConvId: !!this.state.conversationId });
         this.setStatus('sending');
         // The "active" message is the one we're currently appending
         // text_deltas into. For non-team sessions it's always the initial
@@ -224,11 +207,8 @@ class ChatSession {
             const generator = this.state.conversationId
                 ? this.transport.streamSendMessage(this.state.conversationId, text, this.browserSessionId)
                 : this.transport.streamCreateConversation(text, this.browserSessionId);
-            this.debug('runStream got generator, awaiting events');
             let sawAnyChunk = false;
-            let chunkCount = 0;
             for await (const evt of generator) {
-                this.debug('SSE evt', evt.kind, chunkCount++);
                 if (evt.kind === 'conversation') {
                     this.state.conversationId = evt.id;
                     this.emit({ type: 'conversation_started', conversationId: evt.id });
@@ -404,7 +384,6 @@ class ChatSession {
             cleanup(assistant);
             if (active !== assistant)
                 cleanup(active);
-            this.debug('runStream THREW', err instanceof Error ? err.message : String(err));
             this.handleError(err);
             return assistant.content;
         }
@@ -465,50 +444,6 @@ class ChatSession {
     emitStateChange() {
         this.emit({ type: 'state', state: this.getState() });
     }
-    // Lightweight debug logger that BOTH logs to console AND appends
-    // to a visible on-screen overlay so mobile QA without remote
-    // devtools can still see what's happening. Enable by running
-    // `localStorage.setItem('af-chat-debug', '1')` in the browser
-    // console (or via the URL `?af-debug=1` once mounted) and
-    // reloading. Disabled by default so production ships clean.
-    debug(...args) {
-        try {
-            if (typeof window === 'undefined')
-                return;
-            const ls = window.localStorage;
-            let enabled = ls?.getItem('af-chat-debug') === '1';
-            if (!enabled && window.location?.search?.includes('af-debug=1')) {
-                ls?.setItem('af-chat-debug', '1');
-                enabled = true;
-            }
-            if (!enabled)
-                return;
-            const msg = args
-                .map((a) => (typeof a === 'string' ? a : JSON.stringify(a)))
-                .join(' ');
-            // eslint-disable-next-line no-console
-            console.log('[chat-sdk]', msg);
-            // Visible overlay (single shared element across all sessions).
-            let panel = document.getElementById('af-debug-panel');
-            if (!panel) {
-                panel = document.createElement('div');
-                panel.id = 'af-debug-panel';
-                panel.style.cssText =
-                    'position:fixed;top:0;left:0;right:0;max-height:38vh;overflow:auto;' +
-                        'background:rgba(0,0,0,0.85);color:#7CFC00;font:11px/1.3 monospace;' +
-                        'padding:6px 8px;z-index:2147483647;pointer-events:auto;' +
-                        'white-space:pre-wrap;word-break:break-all;';
-                document.body.appendChild(panel);
-            }
-            const line = document.createElement('div');
-            line.textContent = `${new Date().toISOString().slice(11, 23)} ${msg}`;
-            panel.appendChild(line);
-            panel.scrollTop = panel.scrollHeight;
-        }
-        catch {
-            /* localStorage can throw in private mode — ignore */
-        }
-    }
     handleError(err) {
         const message = err instanceof Error ? err.message : String(err);
         const code = err && typeof err === 'object' && 'code' in err

package/package.json

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