@agentforge-io/chat-react 0.1.0

package/dist/ChatPanel.d.ts

@@ -0,0 +1,21 @@
+import { type CSSProperties } from 'react';
+export interface ChatPanelProps {
+    /** Override the header title. Falls back to theme.title, then agent.name. */
+    title?: string;
+    /** Override the input placeholder. */
+    placeholder?: string;
+    /** Tagline shown under the title in the header. Falls back to agent.description. */
+    subtitle?: string;
+    /** Extra style for the root container. The panel is `flex column` and
+     *  fills its parent by default — wrap it in a sized element to control
+     *  the height. */
+    style?: CSSProperties;
+    className?: string;
+}
+/**
+ * Reference rendering of a chat panel. Pure React, no portal, no fixed
+ * positioning — drop it inside whatever container your app provides
+ * (modal, sidebar, page section). For the floating launcher pattern, see
+ * the script-tag widget at /widget.js.
+ */
+export declare function ChatPanel({ title, placeholder, subtitle, style, className, }: ChatPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/ChatPanel.js

@@ -0,0 +1,185 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatPanel = ChatPanel;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const hooks_1 = require("./hooks");
+/**
+ * Reference rendering of a chat panel. Pure React, no portal, no fixed
+ * positioning — drop it inside whatever container your app provides
+ * (modal, sidebar, page section). For the floating launcher pattern, see
+ * the script-tag widget at /widget.js.
+ */
+function ChatPanel({ title, placeholder = 'Type a message…', subtitle, style, className, }) {
+    const { agent, theme } = (0, hooks_1.useAgent)();
+    const { messages, status, send, isBusy, error } = (0, hooks_1.useChat)();
+    const resolvedTitle = title ?? theme?.title ?? agent?.name ?? 'Chat';
+    const resolvedSubtitle = subtitle ?? agent?.description ?? (status === 'loading' ? 'Loading…' : '');
+    const primary = theme?.primaryColor ?? '#7c5cff';
+    const primarySoft = hexToRgba(primary, 0.35);
+    // Same CSS variable contract as the script-tag widget, so a custom <style>
+    // block at app level can re-skin both views with one rule.
+    const containerStyle = {
+        ['--af-primary']: primary,
+        ['--af-primary-soft']: primarySoft,
+        display: 'flex',
+        flexDirection: 'column',
+        height: '100%',
+        minHeight: 0,
+        background: '#fff',
+        color: '#0f172a',
+        borderRadius: 16,
+        overflow: 'hidden',
+        border: '1px solid #e2e8f0',
+        fontFamily: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+        ...style,
+    };
+    const [draft, setDraft] = (0, react_1.useState)('');
+    const messagesRef = (0, react_1.useRef)(null);
+    // Stick to the bottom as new chunks arrive. Cheap and works well for the
+    // streaming-reply case where messages grow.
+    (0, react_1.useEffect)(() => {
+        const el = messagesRef.current;
+        if (!el)
+            return;
+        el.scrollTop = el.scrollHeight;
+    }, [messages]);
+    function onSubmit(e) {
+        e.preventDefault();
+        const text = draft.trim();
+        if (!text || isBusy)
+            return;
+        setDraft('');
+        void send(text);
+    }
+    function onKeyDown(e) {
+        if (e.key === 'Enter' && !e.shiftKey) {
+            e.preventDefault();
+            onSubmit(e);
+        }
+    }
+    return ((0, jsx_runtime_1.jsxs)("div", { className: className, style: containerStyle, children: [(0, jsx_runtime_1.jsxs)("header", { style: {
+                    padding: '14px 16px',
+                    background: '#0f172a',
+                    color: 'white',
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 10,
+                }, children: [theme?.avatarUrl && ((0, jsx_runtime_1.jsx)("img", { src: theme.avatarUrl, alt: "", style: {
+                            width: 28,
+                            height: 28,
+                            borderRadius: '50%',
+                            objectFit: 'cover',
+                            background: 'rgba(255,255,255,0.1)',
+                        } })), (0, jsx_runtime_1.jsxs)("div", { style: { flex: 1, minWidth: 0 }, children: [(0, jsx_runtime_1.jsx)("div", { style: { fontWeight: 600, fontSize: 14 }, children: resolvedTitle }), resolvedSubtitle && ((0, jsx_runtime_1.jsx)("div", { style: { fontSize: 11, opacity: 0.7, marginTop: 2 }, children: resolvedSubtitle }))] })] }), (0, jsx_runtime_1.jsx)("div", { ref: messagesRef, style: {
+                    flex: 1,
+                    minHeight: 0,
+                    overflowY: 'auto',
+                    padding: 16,
+                    background: '#f8fafc',
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: 10,
+                }, children: messages.map((m) => ((0, jsx_runtime_1.jsx)(Bubble, { role: m.role, streaming: m.isStreaming, primary: primary, children: m.content }, m.id))) }), error && ((0, jsx_runtime_1.jsx)("div", { style: {
+                    padding: '10px 16px',
+                    fontSize: 12,
+                    color: '#b91c1c',
+                    background: '#fef2f2',
+                    borderTop: '1px solid #fee2e2',
+                }, children: error })), (0, jsx_runtime_1.jsxs)("form", { onSubmit: onSubmit, style: {
+                    padding: 12,
+                    borderTop: '1px solid #e2e8f0',
+                    background: 'white',
+                    display: 'flex',
+                    gap: 8,
+                }, children: [(0, jsx_runtime_1.jsx)("textarea", { value: draft, onChange: (e) => setDraft(e.target.value), onKeyDown: onKeyDown, placeholder: placeholder, rows: 1, style: {
+                            flex: 1,
+                            border: '1px solid #cbd5e1',
+                            borderRadius: 10,
+                            padding: '10px 12px',
+                            fontSize: 14,
+                            fontFamily: 'inherit',
+                            outline: 'none',
+                            resize: 'none',
+                            minHeight: 40,
+                            maxHeight: 120,
+                            color: '#0f172a',
+                        } }), (0, jsx_runtime_1.jsx)("button", { type: "submit", disabled: isBusy || !draft.trim(), style: {
+                            background: primary,
+                            color: 'white',
+                            border: 'none',
+                            borderRadius: 10,
+                            padding: '0 14px',
+                            cursor: isBusy || !draft.trim() ? 'not-allowed' : 'pointer',
+                            fontWeight: 500,
+                            fontSize: 14,
+                            opacity: isBusy || !draft.trim() ? 0.5 : 1,
+                        }, children: "Send" })] })] }));
+}
+function Bubble({ role, streaming, primary, children, }) {
+    if (role === 'system') {
+        return ((0, jsx_runtime_1.jsx)("div", { style: { alignSelf: 'center', fontSize: 12, color: '#64748b', padding: '4px 8px' }, children: children }));
+    }
+    const isUser = role === 'user';
+    // No content yet but still streaming → render the typing-dots indicator
+    // standalone, without the trailing caret that would have nothing to
+    // anchor to.
+    const isTyping = !isUser && streaming && (children === '' || children == null);
+    return ((0, jsx_runtime_1.jsxs)("div", { style: {
+            alignSelf: isUser ? 'flex-end' : 'flex-start',
+            maxWidth: '80%',
+            padding: isTyping ? '14px 14px' : '10px 12px',
+            minWidth: isTyping ? 56 : undefined,
+            borderRadius: 14,
+            fontSize: 14,
+            lineHeight: 1.5,
+            wordWrap: 'break-word',
+            whiteSpace: 'pre-wrap',
+            background: isUser ? primary : '#ffffff',
+            color: isUser ? 'white' : '#0f172a',
+            border: isUser ? 'none' : '1px solid #e2e8f0',
+            borderBottomRightRadius: isUser ? 4 : 14,
+            borderBottomLeftRadius: isUser ? 14 : 4,
+            animation: 'af-react-msg-in 220ms cubic-bezier(.2,.8,.2,1)',
+        }, children: [isTyping ? (0, jsx_runtime_1.jsx)(TypingDots, {}) : children, !isTyping && streaming && ((0, jsx_runtime_1.jsx)("span", { "aria-hidden": true, style: {
+                    display: 'inline-block',
+                    marginLeft: 2,
+                    color: '#94a3b8',
+                    animation: 'af-react-blink 1s infinite',
+                }, children: "\u258D" })), (0, jsx_runtime_1.jsx)("style", { children: `
+        @keyframes af-react-blink { 0%,80%,100% { opacity:.3 } 40% { opacity:1 } }
+        @keyframes af-react-bounce {
+          0%, 60%, 100% { transform: translateY(0); opacity: 0.4; }
+          30% { transform: translateY(-4px); opacity: 1; }
+        }
+        @keyframes af-react-msg-in {
+          from { opacity: 0; transform: translateY(6px); }
+          to { opacity: 1; transform: translateY(0); }
+        }
+      ` })] }));
+}
+function TypingDots() {
+    const dot = {
+        width: 7,
+        height: 7,
+        borderRadius: '50%',
+        background: '#64748b',
+        display: 'inline-block',
+        animation: 'af-react-bounce 1.2s infinite ease-in-out',
+    };
+    return ((0, jsx_runtime_1.jsxs)("span", { "aria-label": "Assistant is typing", style: { display: 'inline-flex', gap: 4, alignItems: 'center' }, children: [(0, jsx_runtime_1.jsx)("span", { style: { ...dot } }), (0, jsx_runtime_1.jsx)("span", { style: { ...dot, animationDelay: '0.15s' } }), (0, jsx_runtime_1.jsx)("span", { style: { ...dot, animationDelay: '0.3s' } })] }));
+}
+function hexToRgba(hex, alpha) {
+    if (!hex || hex[0] !== '#')
+        return hex;
+    let h = hex.slice(1);
+    if (h.length === 3)
+        h = h.split('').map((c) => c + c).join('');
+    if (h.length !== 6)
+        return hex;
+    const r = parseInt(h.slice(0, 2), 16);
+    const g = parseInt(h.slice(2, 4), 16);
+    const b = parseInt(h.slice(4, 6), 16);
+    return `rgba(${r},${g},${b},${alpha})`;
+}

package/dist/hooks.d.ts

@@ -0,0 +1,27 @@
+import type { ChatAgentSummary, ChatMessage, ChatSessionStatus, ChatTheme } from '@agentforge-io/chat-sdk';
+/**
+ * Primary hook. Returns reactive chat state + actions. Re-renders on every
+ * SDK event, but the underlying state object is recreated each time so
+ * referential equality only changes when something actually changes —
+ * downstream `useMemo`s stay efficient.
+ */
+export declare function useChat(): {
+    status: ChatSessionStatus;
+    messages: ChatMessage[];
+    conversationId?: string;
+    error?: string;
+    browserSessionId: string;
+    send: (text: string) => Promise<string>;
+    start: () => Promise<void>;
+    destroy: () => void;
+    isBusy: boolean;
+};
+/**
+ * Read-only metadata about the resolved agent + theme. Returns `undefined`
+ * until the session finishes its initial `start()` call.
+ */
+export declare function useAgent(): {
+    agent?: ChatAgentSummary;
+    theme?: ChatTheme;
+    loading: boolean;
+};

package/dist/hooks.js

@@ -0,0 +1,53 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useChat = useChat;
+exports.useAgent = useAgent;
+const react_1 = require("react");
+const provider_1 = require("./provider");
+/**
+ * Primary hook. Returns reactive chat state + actions. Re-renders on every
+ * SDK event, but the underlying state object is recreated each time so
+ * referential equality only changes when something actually changes —
+ * downstream `useMemo`s stay efficient.
+ */
+function useChat() {
+    const { session } = (0, provider_1.useAgentChatContext)();
+    const state = (0, provider_1.useChatSessionState)();
+    const send = (0, react_1.useCallback)((text) => session.send(text), [session]);
+    const start = (0, react_1.useCallback)(() => session.start(), [session]);
+    const destroy = (0, react_1.useCallback)(() => session.destroy(), [session]);
+    return (0, react_1.useMemo)(() => ({
+        status: state.status,
+        messages: state.messages,
+        conversationId: state.conversationId,
+        error: state.lastError,
+        browserSessionId: session.browserSessionId,
+        send,
+        start,
+        destroy,
+        isBusy: state.status === 'loading' ||
+            state.status === 'sending' ||
+            state.status === 'streaming',
+    }), [state, session.browserSessionId, send, start, destroy]);
+}
+/**
+ * Read-only metadata about the resolved agent + theme. Returns `undefined`
+ * until the session finishes its initial `start()` call.
+ */
+function useAgent() {
+    const { themeOverride } = (0, provider_1.useAgentChatContext)();
+    const state = (0, provider_1.useChatSessionState)();
+    return (0, react_1.useMemo)(() => {
+        // Provider-level theme wins over the token's theme — same precedence
+        // as the data-* overrides in the script-tag widget.
+        const mergedTheme = state.theme || themeOverride
+            ? { ...(state.theme ?? {}), ...(themeOverride ?? {}) }
+            : undefined;
+        return {
+            agent: state.agent,
+            theme: mergedTheme,
+            loading: state.status === 'loading' || (!state.agent && state.status !== 'error'),
+        };
+    }, [state.agent, state.theme, state.status, themeOverride]);
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @agentforge-io/chat-react — React + Next.js bindings for the headless chat SDK.
+ *
+ * Two ways to use this:
+ *
+ *   // 1. Provider + hooks: build your own UI
+ *   <AgentChatProvider token={...} apiBaseUrl={...}>
+ *     <YourChatUi />
+ *   </AgentChatProvider>
+ *
+ *   function YourChatUi() {
+ *     const { messages, send, isBusy } = useChat();
+ *     const { agent, theme } = useAgent();
+ *     ...
+ *   }
+ *
+ *   // 2. Drop-in: use the reference panel
+ *   <AgentChatProvider ...>
+ *     <ChatPanel />
+ *   </AgentChatProvider>
+ *
+ * All components are marked `'use client'` so they work with the Next.js
+ * App Router out of the box.
+ */
+export { AgentChatProvider, useAgentChatContext, useChatSessionState } from './provider';
+export type { AgentChatProviderProps, ChatUserContext, } from './provider';
+export { useChat, useAgent } from './hooks';
+export { ChatPanel } from './ChatPanel';
+export type { ChatPanelProps } from './ChatPanel';
+export type { ChatAgentSummary, ChatEvent, ChatMessage, ChatRole, ChatSessionStatus, ChatTheme, } from '@agentforge-io/chat-sdk';

package/dist/index.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * @agentforge-io/chat-react — React + Next.js bindings for the headless chat SDK.
+ *
+ * Two ways to use this:
+ *
+ *   // 1. Provider + hooks: build your own UI
+ *   <AgentChatProvider token={...} apiBaseUrl={...}>
+ *     <YourChatUi />
+ *   </AgentChatProvider>
+ *
+ *   function YourChatUi() {
+ *     const { messages, send, isBusy } = useChat();
+ *     const { agent, theme } = useAgent();
+ *     ...
+ *   }
+ *
+ *   // 2. Drop-in: use the reference panel
+ *   <AgentChatProvider ...>
+ *     <ChatPanel />
+ *   </AgentChatProvider>
+ *
+ * All components are marked `'use client'` so they work with the Next.js
+ * App Router out of the box.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatPanel = exports.useAgent = exports.useChat = exports.useChatSessionState = exports.useAgentChatContext = exports.AgentChatProvider = void 0;
+var provider_1 = require("./provider");
+Object.defineProperty(exports, "AgentChatProvider", { enumerable: true, get: function () { return provider_1.AgentChatProvider; } });
+Object.defineProperty(exports, "useAgentChatContext", { enumerable: true, get: function () { return provider_1.useAgentChatContext; } });
+Object.defineProperty(exports, "useChatSessionState", { enumerable: true, get: function () { return provider_1.useChatSessionState; } });
+var hooks_1 = require("./hooks");
+Object.defineProperty(exports, "useChat", { enumerable: true, get: function () { return hooks_1.useChat; } });
+Object.defineProperty(exports, "useAgent", { enumerable: true, get: function () { return hooks_1.useAgent; } });
+var ChatPanel_1 = require("./ChatPanel");
+Object.defineProperty(exports, "ChatPanel", { enumerable: true, get: function () { return ChatPanel_1.ChatPanel; } });

package/dist/provider.d.ts

@@ -0,0 +1,48 @@
+import { type ReactNode } from 'react';
+import { ChatSession, type ChatSessionState, type ChatTheme } from '@agentforge-io/chat-sdk';
+/**
+ * UserContext is opaque metadata your app can attach to a chat. It travels in
+ * the conversation's `metadata.userContext` when one is created — useful for
+ * tying server-side analytics or chat transcripts back to the logged-in user
+ * in YOUR app. Nothing here is enforced by the chat token; treat it as data,
+ * not auth.
+ */
+export type ChatUserContext = Record<string, unknown>;
+export interface AgentChatProviderProps {
+    /** Public chat token from your AgentForge admin. */
+    token: string;
+    /** Base URL of your AgentForge API (e.g. https://api.example.com). */
+    apiBaseUrl: string;
+    /** Optional persistent browser id. If omitted, the SDK generates one and
+     *  the consumer can read it via `useChat().browserSessionId`. */
+    browserSessionId?: string;
+    /** Disable SSE streaming. Defaults to true (stream). */
+    stream?: boolean;
+    /** Theme override. Wins over whatever the token's theme says, mirroring
+     *  the data-* override semantics of the script-tag widget. */
+    theme?: ChatTheme;
+    /** Free-form metadata about the end-user, attached to new conversations. */
+    userContext?: ChatUserContext;
+    /** Auto-start the session on mount. Defaults true; set false to start
+     *  manually via `useChat().start()`. */
+    autoStart?: boolean;
+    children: ReactNode;
+}
+interface ContextValue {
+    session: ChatSession;
+    subscribe: (cb: () => void) => () => void;
+    getState: () => ChatSessionState;
+    /** Theme override passed via Provider, surfaced to consumers separately
+     *  from the token's theme so the View layer can merge them as it wants. */
+    themeOverride?: ChatTheme;
+    userContext?: ChatUserContext;
+}
+export declare function AgentChatProvider({ token, apiBaseUrl, browserSessionId, stream, theme, userContext, autoStart, children, }: AgentChatProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useAgentChatContext(): ContextValue;
+/**
+ * Internal: subscribe a component to the session's state changes via React
+ * 18's `useSyncExternalStore`. Returns the latest state on every render and
+ * triggers re-renders only when the session emits.
+ */
+export declare function useChatSessionState(): ChatSessionState;
+export {};

package/dist/provider.js

@@ -0,0 +1,90 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentChatProvider = AgentChatProvider;
+exports.useAgentChatContext = useAgentChatContext;
+exports.useChatSessionState = useChatSessionState;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const chat_sdk_1 = require("@agentforge-io/chat-sdk");
+const AgentChatContext = (0, react_1.createContext)(null);
+function AgentChatProvider({ token, apiBaseUrl, browserSessionId, stream, theme, userContext, autoStart = true, children, }) {
+    // Keep a stable session for the lifetime of these props. Re-create only
+    // when the inputs that materially identify the chat change.
+    const sessionRef = (0, react_1.useRef)(null);
+    const key = `${token}|${apiBaseUrl}|${browserSessionId ?? ''}|${stream ?? true}`;
+    if (!sessionRef.current || sessionRef.current.key !== key) {
+        // Tear down a previous session if any — switching tokens is rare but
+        // we don't want a dangling SDK instance holding listeners.
+        sessionRef.current?.session.destroy();
+        const opts = { token, apiBaseUrl, browserSessionId, stream };
+        sessionRef.current = { session: new chat_sdk_1.ChatSession(opts), key };
+    }
+    const session = sessionRef.current.session;
+    // Auto-start once per session instance.
+    const startedRef = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (!autoStart)
+            return;
+        if (startedRef.current)
+            return;
+        startedRef.current = true;
+        session.start();
+    }, [session, autoStart]);
+    // Clean up on unmount. Only when the component is actually leaving — the
+    // session ref above survives Strict Mode double-invocation in dev.
+    (0, react_1.useEffect)(() => {
+        return () => {
+            session.destroy();
+            sessionRef.current = null;
+            startedRef.current = false;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [session]);
+    // Cached snapshot for useSyncExternalStore. `session.getState()` returns a
+    // fresh object on every call (it's a fresh aggregate of the session's
+    // internal mutable state), so reading it directly trips React's
+    // "getSnapshot should be cached" detector and loops.
+    //
+    // We keep the last seen snapshot in a ref, invalidate it inside the
+    // subscribe callback, and only recompute on the next getState() call.
+    // Result: stable reference between events, fresh reference per event.
+    const snapshotRef = (0, react_1.useRef)(null);
+    const value = (0, react_1.useMemo)(() => {
+        // Reset cache when the session itself swaps (token change, etc).
+        snapshotRef.current = null;
+        return {
+            session,
+            themeOverride: theme,
+            userContext,
+            subscribe: (cb) => session.onEvent(() => {
+                // Invalidate cache so the next getState() re-reads — then notify.
+                snapshotRef.current = null;
+                cb();
+            }),
+            getState: () => {
+                if (snapshotRef.current === null) {
+                    snapshotRef.current = session.getState();
+                }
+                return snapshotRef.current;
+            },
+        };
+    }, [session, theme, userContext]);
+    return ((0, jsx_runtime_1.jsx)(AgentChatContext.Provider, { value: value, children: children }));
+}
+function useAgentChatContext() {
+    const ctx = (0, react_1.useContext)(AgentChatContext);
+    if (!ctx) {
+        throw new Error('useAgentChatContext must be used inside <AgentChatProvider>');
+    }
+    return ctx;
+}
+/**
+ * Internal: subscribe a component to the session's state changes via React
+ * 18's `useSyncExternalStore`. Returns the latest state on every render and
+ * triggers re-renders only when the session emits.
+ */
+function useChatSessionState() {
+    const { subscribe, getState } = useAgentChatContext();
+    return (0, react_1.useSyncExternalStore)(subscribe, getState, getState);
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@agentforge-io/chat-react",
+  "version": "0.1.0",
+  "description": "React + Next.js adapter for @agentforge-io/chat-sdk. Provider, hooks, and a reference ChatPanel component.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist *.tgz"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@agentforge-io/chat-sdk": "^0.1.0"
+  },
+  "dependencies": {
+    "@agentforge-io/chat-sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0 || ^19.0.0",
+    "@types/react-dom": "^18.0.0 || ^19.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "typescript": "^5.0.0"
+  }
+}