@agentforge-io/chat-sdk 2.4.0-dev.8 → 2.4.0

package/dist/react.d.ts

@@ -198,6 +198,26 @@ 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

@@ -291,14 +291,31 @@ function ChatWidget(props) {
         el.focus({ preventScroll: true });
         focusedOnceRef.current = true;
     }, [status]);
-    // ── Session lifecycle. Recreate when token / apiBaseUrl changes. ──────
+    // ── Session lifecycle. Recreate when token / apiBaseUrl / browserSessionId
+    // / stream changes. NOTE: `resumeConversationId` is intentionally NOT a
+    // dependency.
+    //
+    // Why: hosts typically wire `resumeConversationId={conversationId}`
+    // and call `setConversationId(id)` in `onConversationStart`. The
+    // conversation_started event fires AFTER the SSE stream opens and
+    // the first chunks already started flowing. If we treated
+    // resumeConversationId as a reactive dep, this effect would
+    // re-run mid-stream, destroy the live ChatSession, and the
+    // remaining chunks would land in a corpse — the visitor sees
+    // an empty assistant bubble even though the backend completed
+    // the turn successfully.
+    //
+    // We capture the resume id at mount via a ref. Subsequent host
+    // updates to it are ignored — the SDK already owns the live
+    // conversation id internally via session.state.conversationId.
+    const resumeRef = (0, react_1.useRef)(resumeConversationId);
     (0, react_1.useEffect)(() => {
         let cancelled = false;
         const s = new session_1.ChatSession({
             token,
             apiBaseUrl,
             browserSessionId,
-            resumeConversationId,
+            resumeConversationId: resumeRef.current,
             stream,
         });
         setSession(s);
@@ -336,7 +353,10 @@ function ChatWidget(props) {
             unsubscribe();
             s.destroy();
         };
-    }, [token, apiBaseUrl, browserSessionId, resumeConversationId, stream]);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- resumeConversationId
+        // is captured via resumeRef on first mount; reactive updates are
+        // ignored by design. See block comment above.
+    }, [token, apiBaseUrl, browserSessionId, stream]);
     // Auto-scroll on new tokens.
     //
     // We defer the scroll into a requestAnimationFrame so the DOM has
@@ -442,6 +462,20 @@ 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
@@ -532,7 +566,9 @@ function ChatWidget(props) {
                                     onShortcutClick(text, i);
                                 else
                                     setDraft(text);
-                            }, 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, 
+                            }, 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, 
                                 // The textarea stays editable while the agent is
                                 // streaming so the visitor can compose their next
                                 // message without waiting. Only block when the
@@ -547,7 +583,14 @@ function ChatWidget(props) {
                                 // 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": "Send message", children: (0, jsx_runtime_1.jsx)(SendIcon, {}) })] }), !bare && (0, jsx_runtime_1.jsx)("div", { className: "af-footer", children: "Powered by AgentForge" })] })] }));
+                                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" })] })] }));
 }
 function MessageBubble({ message, session, readOnly, onDecision, onContinue, bare = false, showAvatar = false, avatarTheme, avatarName, avatarAgentId, speakerLabel, }) {
     const kind = message.metadata?.kind;
@@ -720,6 +763,11 @@ 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 = `
@@ -804,6 +852,8 @@ 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
@@ -863,6 +913,8 @@ 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

@@ -69,6 +69,7 @@ export declare class ChatSession {
     private removeMessage;
     private setStatus;
     private emitStateChange;
+    private debug;
     private handleError;
     private emit;
 }

package/dist/session.js

@@ -172,6 +172,7 @@ 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.');
         }
@@ -180,6 +181,7 @@ class ChatSession {
         // 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 (!opts?.silent) {
             this.appendMessage({
                 id: makeMessageId('u'),
@@ -203,6 +205,7 @@ 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
@@ -221,8 +224,11 @@ 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 });
@@ -398,6 +404,7 @@ 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;
         }
@@ -458,6 +465,50 @@ 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.8",
+  "version": "2.4.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",