@agentforge-io/chat-react 2.0.17 → 4.0.0

package/dist/index.d.ts

@@ -1,24 +1,27 @@
 /**
  * @agentforge-io/chat-react — React + Next.js bindings for the headless chat SDK.
  *
- * Two ways to use this:
+ * Three 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
+ *   // 2. Drop-in chat panel
  *   <AgentChatProvider ...>
  *     <ChatPanel />
  *   </AgentChatProvider>
  *
+ *   // 3. Full Messenger shell (Home/Messages/Help/News tabs, v4+)
+ *   <MessengerShell
+ *     token={...}
+ *     apiBaseUrl={...}
+ *     helpAdapter={myHelpAdapter}
+ *     newsAdapter={myNewsAdapter}
+ *     homeActions={[...]}
+ *   />
+ *
  * All components are marked `'use client'` so they work with the Next.js
  * App Router out of the box.
  */
@@ -27,4 +30,20 @@ export type { AgentChatProviderProps, ChatUserContext, } from './provider';
 export { useChat, useAgent } from './hooks';
 export { ChatPanel } from './ChatPanel';
 export type { ChatPanelProps, ApprovalActionHandler } from './ChatPanel';
+export { MessengerShell } from './messenger/MessengerShell';
+export type { MessengerShellProps } from './messenger/MessengerShell';
+export type { MessengerTab } from './messenger/MessengerFooter';
+export type { HelpAdapter, HelpResult, HelpCollection, HelpCollectionDetail, NewsAdapter, Announcement, HomeAction, } from './messenger/adapters';
+export { MessengerHeader } from './messenger/MessengerHeader';
+export type { MessengerHeaderProps } from './messenger/MessengerHeader';
+export { MessengerFooter } from './messenger/MessengerFooter';
+export type { MessengerFooterProps } from './messenger/MessengerFooter';
+export { HomeTab } from './messenger/tabs/HomeTab';
+export type { HomeTabProps } from './messenger/tabs/HomeTab';
+export { MessagesTab } from './messenger/tabs/MessagesTab';
+export type { MessagesTabProps } from './messenger/tabs/MessagesTab';
+export { HelpTab } from './messenger/tabs/HelpTab';
+export type { HelpTabProps } from './messenger/tabs/HelpTab';
+export { NewsTab } from './messenger/tabs/NewsTab';
+export type { NewsTabProps } from './messenger/tabs/NewsTab';
 export type { ChatAgentSummary, ChatEvent, ChatMessage, ChatMessageMetadata, ChatRole, ChatSessionStatus, ChatTheme, } from '@agentforge-io/chat-sdk';

package/dist/index.js

@@ -2,29 +2,32 @@
 /**
  * @agentforge-io/chat-react — React + Next.js bindings for the headless chat SDK.
  *
- * Two ways to use this:
+ * Three 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
+ *   // 2. Drop-in chat panel
  *   <AgentChatProvider ...>
  *     <ChatPanel />
  *   </AgentChatProvider>
  *
+ *   // 3. Full Messenger shell (Home/Messages/Help/News tabs, v4+)
+ *   <MessengerShell
+ *     token={...}
+ *     apiBaseUrl={...}
+ *     helpAdapter={myHelpAdapter}
+ *     newsAdapter={myNewsAdapter}
+ *     homeActions={[...]}
+ *   />
+ *
  * 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;
+exports.NewsTab = exports.HelpTab = exports.MessagesTab = exports.HomeTab = exports.MessengerFooter = exports.MessengerHeader = exports.MessengerShell = 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; } });
@@ -34,3 +37,20 @@ Object.defineProperty(exports, "useChat", { enumerable: true, get: function () {
 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; } });
+// — Messenger shell (v4+) —
+var MessengerShell_1 = require("./messenger/MessengerShell");
+Object.defineProperty(exports, "MessengerShell", { enumerable: true, get: function () { return MessengerShell_1.MessengerShell; } });
+// Public sub-components for consumers that want to compose their own
+// shell (e.g. swap one tab while keeping the rest).
+var MessengerHeader_1 = require("./messenger/MessengerHeader");
+Object.defineProperty(exports, "MessengerHeader", { enumerable: true, get: function () { return MessengerHeader_1.MessengerHeader; } });
+var MessengerFooter_1 = require("./messenger/MessengerFooter");
+Object.defineProperty(exports, "MessengerFooter", { enumerable: true, get: function () { return MessengerFooter_1.MessengerFooter; } });
+var HomeTab_1 = require("./messenger/tabs/HomeTab");
+Object.defineProperty(exports, "HomeTab", { enumerable: true, get: function () { return HomeTab_1.HomeTab; } });
+var MessagesTab_1 = require("./messenger/tabs/MessagesTab");
+Object.defineProperty(exports, "MessagesTab", { enumerable: true, get: function () { return MessagesTab_1.MessagesTab; } });
+var HelpTab_1 = require("./messenger/tabs/HelpTab");
+Object.defineProperty(exports, "HelpTab", { enumerable: true, get: function () { return HelpTab_1.HelpTab; } });
+var NewsTab_1 = require("./messenger/tabs/NewsTab");
+Object.defineProperty(exports, "NewsTab", { enumerable: true, get: function () { return NewsTab_1.NewsTab; } });

package/dist/messenger/MessengerFooter.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedTheme } from './theme';
+export type MessengerTab = 'home' | 'messages' | 'help' | 'news';
+/**
+ * Bottom tab bar. Always sticky so it survives scroll inside each tab.
+ *
+ * Icons are inline SVGs rather than a lucide-react dep — keeps the
+ * messenger bundle from pulling a 30kb icon library when consumers
+ * already ship their own. The shapes mirror the Intercom mental model:
+ *   home    → soft chat-bubble outline
+ *   messages → square message bubble with line
+ *   help    → circle + question mark
+ *   news    → megaphone
+ */
+export interface MessengerFooterProps {
+    theme: ResolvedTheme;
+    active: MessengerTab;
+    onChange: (tab: MessengerTab) => void;
+    tabs: MessengerTab[];
+    /** Optional unread counts per tab. Renders a small dot when > 0. */
+    unread?: Partial<Record<MessengerTab, number>>;
+}
+export declare function MessengerFooter({ theme, active, onChange, tabs, unread, }: MessengerFooterProps): import("react/jsx-runtime").JSX.Element;

package/dist/messenger/MessengerFooter.js

@@ -0,0 +1,54 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessengerFooter = MessengerFooter;
+const jsx_runtime_1 = require("react/jsx-runtime");
+function MessengerFooter({ theme, active, onChange, tabs, unread, }) {
+    const rootStyle = {
+        display: 'flex',
+        borderTop: '1px solid #e2e8f0',
+        background: theme.surface,
+        padding: '8px 4px',
+        flexShrink: 0,
+    };
+    return ((0, jsx_runtime_1.jsx)("nav", { style: rootStyle, "aria-label": "Messenger sections", children: tabs.map((t) => ((0, jsx_runtime_1.jsx)(TabButton, { tab: t, active: t === active, onClick: () => onChange(t), accent: theme.accent, unread: unread?.[t] ?? 0 }, t))) }));
+}
+function TabButton({ tab, active, onClick, accent, unread, }) {
+    const label = LABELS[tab];
+    const Icon = ICONS[tab];
+    const color = active ? accent : '#64748b';
+    return ((0, jsx_runtime_1.jsxs)("button", { type: "button", onClick: onClick, "aria-pressed": active, style: {
+            flex: 1,
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            gap: 2,
+            padding: '6px 4px',
+            background: 'transparent',
+            border: 'none',
+            cursor: 'pointer',
+            color,
+            position: 'relative',
+            fontFamily: 'inherit',
+        }, children: [(0, jsx_runtime_1.jsx)(Icon, { filled: active }), (0, jsx_runtime_1.jsx)("span", { style: { fontSize: 11, fontWeight: active ? 600 : 500 }, children: label }), unread > 0 && ((0, jsx_runtime_1.jsx)("span", { "aria-label": `${unread} unread`, style: {
+                    position: 'absolute',
+                    top: 4,
+                    right: '38%',
+                    minWidth: 8,
+                    height: 8,
+                    borderRadius: 4,
+                    background: '#ef4444',
+                } }))] }));
+}
+const LABELS = {
+    home: 'Home',
+    messages: 'Messages',
+    help: 'Help',
+    news: 'News',
+};
+const ICONS = {
+    home: ({ filled }) => ((0, jsx_runtime_1.jsx)("svg", { width: "22", height: "22", viewBox: "0 0 24 24", fill: "none", children: (0, jsx_runtime_1.jsx)("path", { d: "M4 11.5C4 9.8 5 8.3 6.5 7.5L11 5c.6-.3 1.4-.3 2 0l4.5 2.5c1.5.8 2.5 2.3 2.5 4V18a2 2 0 0 1-2 2h-2.5a1 1 0 0 1-1-1V15a1 1 0 0 0-1-1h-3a1 1 0 0 0-1 1v4a1 1 0 0 1-1 1H6a2 2 0 0 1-2-2v-6.5Z", stroke: "currentColor", strokeWidth: "1.6", fill: filled ? 'currentColor' : 'none' }) })),
+    messages: ({ filled }) => ((0, jsx_runtime_1.jsxs)("svg", { width: "22", height: "22", viewBox: "0 0 24 24", fill: "none", children: [(0, jsx_runtime_1.jsx)("rect", { x: "3", y: "4", width: "18", height: "14", rx: "3", stroke: "currentColor", strokeWidth: "1.6", fill: filled ? 'currentColor' : 'none' }), (0, jsx_runtime_1.jsx)("path", { d: "M7 9h10M7 13h6", stroke: filled ? '#fff' : 'currentColor', strokeWidth: "1.6", strokeLinecap: "round" }), (0, jsx_runtime_1.jsx)("path", { d: "M9 18l-2 3", stroke: "currentColor", strokeWidth: "1.6", strokeLinecap: "round" })] })),
+    help: ({ filled }) => ((0, jsx_runtime_1.jsxs)("svg", { width: "22", height: "22", viewBox: "0 0 24 24", fill: "none", children: [(0, jsx_runtime_1.jsx)("circle", { cx: "12", cy: "12", r: "9", stroke: "currentColor", strokeWidth: "1.6", fill: filled ? 'currentColor' : 'none' }), (0, jsx_runtime_1.jsx)("path", { d: "M9.5 9.5a2.5 2.5 0 0 1 5 0c0 1.5-2.5 2-2.5 3.5", stroke: filled ? '#fff' : 'currentColor', strokeWidth: "1.6", strokeLinecap: "round" }), (0, jsx_runtime_1.jsx)("circle", { cx: "12", cy: "17", r: "1", fill: filled ? '#fff' : 'currentColor' })] })),
+    news: ({ filled }) => ((0, jsx_runtime_1.jsxs)("svg", { width: "22", height: "22", viewBox: "0 0 24 24", fill: "none", children: [(0, jsx_runtime_1.jsx)("path", { d: "M3 10v4l11 5V5L3 10Z", stroke: "currentColor", strokeWidth: "1.6", strokeLinejoin: "round", fill: filled ? 'currentColor' : 'none' }), (0, jsx_runtime_1.jsx)("path", { d: "M17 9a3 3 0 0 1 0 6", stroke: "currentColor", strokeWidth: "1.6", strokeLinecap: "round" })] })),
+};

package/dist/messenger/MessengerHeader.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+import type { ResolvedTheme } from './theme';
+/**
+ * Header band sitting at the top of Home and Messages tabs. Help and
+ * News use a simpler title-only header (rendered inline in their tabs)
+ * because their content is denser.
+ *
+ * Three slots:
+ *   - left: brand mark (logo / icon)
+ *   - right: action group (avatars stack + close button)
+ *   - bottom: greeting block (collapses on tab=messages where the chat
+ *             needs the height for the message list)
+ */
+export interface MessengerHeaderProps {
+    theme: ResolvedTheme;
+    /** Brand mark on the top-left. Consumer-provided so we don't ship a
+     *  default that needs to be overridden in 100% of installs. Pass a
+     *  small img / svg / lucide icon. */
+    brand?: ReactNode;
+    /** Up to 3 avatars stacked on the top-right. Adding more silently
+     *  truncates to the first 3 because the stack runs out of room. */
+    avatars?: Array<{
+        src: string;
+        alt: string;
+    }>;
+    /** Close-button click. When omitted, the close button is hidden —
+     *  embeds that have their own chrome (e.g. fullscreen modal) opt out. */
+    onClose?: () => void;
+    /** Greeting block content. When omitted, the bottom row collapses
+     *  cleanly (Messages tab does this so the chat gets the height). */
+    greeting?: ReactNode;
+    /** Extra height on the bottom of the band. Used to round into the
+     *  scrollable content below. */
+    bottomRadius?: number;
+}
+export declare function MessengerHeader({ theme, brand, avatars, onClose, greeting, bottomRadius, }: MessengerHeaderProps): import("react/jsx-runtime").JSX.Element;

package/dist/messenger/MessengerHeader.js

@@ -0,0 +1,61 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessengerHeader = MessengerHeader;
+const jsx_runtime_1 = require("react/jsx-runtime");
+function MessengerHeader({ theme, brand, avatars, onClose, greeting, bottomRadius = 0, }) {
+    const rootStyle = {
+        background: theme.headerBg,
+        color: theme.onHeader,
+        padding: '16px 16px 20px',
+        // The shell content scrolls under the header bottom radius so the
+        // gradient stays visible when the user scrolls — the negative
+        // marginBottom + matching radius creates the effect without a
+        // sticky element.
+        marginBottom: bottomRadius ? -bottomRadius : 0,
+        borderBottomLeftRadius: bottomRadius,
+        borderBottomRightRadius: bottomRadius,
+    };
+    return ((0, jsx_runtime_1.jsxs)("div", { style: rootStyle, children: [(0, jsx_runtime_1.jsxs)("div", { style: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'space-between',
+                    marginBottom: greeting ? 18 : 0,
+                }, children: [(0, jsx_runtime_1.jsx)("div", { style: {
+                            display: 'flex',
+                            alignItems: 'center',
+                            gap: 10,
+                            opacity: brand ? 1 : 0,
+                        }, children: brand ?? (0, jsx_runtime_1.jsx)("div", { style: { width: 36, height: 36 } }) }), (0, jsx_runtime_1.jsxs)("div", { style: { display: 'flex', alignItems: 'center', gap: 8 }, children: [avatars && avatars.length > 0 && ((0, jsx_runtime_1.jsx)(AvatarStack, { avatars: avatars, onHeader: theme.onHeader })), onClose && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: onClose, "aria-label": "Close", style: {
+                                    background: 'transparent',
+                                    border: 'none',
+                                    color: theme.onHeader,
+                                    width: 32,
+                                    height: 32,
+                                    borderRadius: 6,
+                                    cursor: 'pointer',
+                                    fontSize: 18,
+                                    lineHeight: 1,
+                                    opacity: 0.85,
+                                }, children: "\u00D7" }))] })] }), greeting] }));
+}
+/**
+ * Trio of overlapping circular avatars. Caps at 3 so the rendering is
+ * deterministic — adding a "+N" pill would require another design
+ * decision we'd rather defer until a customer asks for it.
+ */
+function AvatarStack({ avatars, onHeader, }) {
+    const visible = avatars.slice(0, 3);
+    return ((0, jsx_runtime_1.jsx)("div", { style: { display: 'flex' }, children: visible.map((a, i) => ((0, jsx_runtime_1.jsx)("img", { src: a.src, alt: a.alt, 
+            // marginLeft on every avatar except the first creates the
+            // overlap. Border in the header foreground color punches the
+            // avatar out of the gradient so each circle stays distinct.
+            style: {
+                width: 32,
+                height: 32,
+                borderRadius: '50%',
+                border: `2px solid ${onHeader}`,
+                marginLeft: i === 0 ? 0 : -10,
+                objectFit: 'cover',
+            } }, a.src))) }));
+}

package/dist/messenger/MessengerShell.d.ts

@@ -0,0 +1,59 @@
+import { type ReactNode } from 'react';
+import { type AgentChatProviderProps } from '../provider';
+import { type MessengerTab } from './MessengerFooter';
+import type { HelpAdapter, HomeAction, NewsAdapter } from './adapters';
+import type { ChatPanelProps } from '../ChatPanel';
+/**
+ * Multi-tab Messenger shell (Home / Messages / Help / News).
+ *
+ * Composition over inheritance: the shell *contains* an
+ * AgentChatProvider for the Messages tab, but Home / Help / News don't
+ * depend on the chat session at all — they pull from the adapters the
+ * consumer passes.
+ *
+ * The shell renders inside whatever the host provides. It does NOT
+ * portal itself or apply fixed positioning. Wrap it in a sized
+ * container (FAB drawer, full-page modal, sidebar) and it fills.
+ *
+ * Two display modes — pure CSS, no portal:
+ *   - `inline`: fills the parent (default; matches ChatPanel's behavior).
+ *   - `floating`: anchors itself to a corner with `position: fixed`.
+ *                 Use this when the host doesn't manage placement and
+ *                 you want a drop-in launcher experience.
+ */
+export interface MessengerShellProps extends Omit<AgentChatProviderProps, 'children'> {
+    /** Which tabs to render, in order. Default: all 4. */
+    tabs?: MessengerTab[];
+    /** Tab shown on first render. Default: 'home'. Controlled mode is
+     *  supported via `activeTab` + `onTabChange`. */
+    defaultTab?: MessengerTab;
+    /** Controlled active tab. When set, `defaultTab` is ignored. */
+    activeTab?: MessengerTab;
+    onTabChange?: (tab: MessengerTab) => void;
+    homeGreeting?: {
+        name?: string;
+        emoji?: string;
+    };
+    homeQuestion?: string;
+    homeActions?: HomeAction[];
+    homeAvatars?: Array<{
+        src: string;
+        alt: string;
+    }>;
+    homeFooter?: ReactNode;
+    /** Brand mark in the header (logo). */
+    brand?: ReactNode;
+    helpAdapter?: HelpAdapter;
+    newsAdapter?: NewsAdapter;
+    /** Forwarded to ChatPanel inside the Messages tab. */
+    panelProps?: Omit<ChatPanelProps, 'style' | 'className'>;
+    /** `inline` fills the parent (default). `floating` pins to a corner. */
+    display?: 'inline' | 'floating';
+    /** Width when `display='floating'`. Default 380. */
+    width?: number;
+    /** Max height when `display='floating'`. Default min(640, viewport-80). */
+    maxHeight?: number;
+    onClose?: () => void;
+    unread?: Partial<Record<MessengerTab, number>>;
+}
+export declare function MessengerShell({ token, apiBaseUrl, browserSessionId, stream, userContext, theme: themeOverride, autoStart, tabs, defaultTab, activeTab, onTabChange, homeGreeting, homeQuestion, homeActions, homeAvatars, homeFooter, brand, helpAdapter, newsAdapter, panelProps, display, width, maxHeight, onClose, unread, }: MessengerShellProps): import("react/jsx-runtime").JSX.Element;

package/dist/messenger/MessengerShell.js

@@ -0,0 +1,138 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessengerShell = MessengerShell;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const provider_1 = require("../provider");
+const hooks_1 = require("../hooks");
+const MessengerFooter_1 = require("./MessengerFooter");
+const HomeTab_1 = require("./tabs/HomeTab");
+const MessagesTab_1 = require("./tabs/MessagesTab");
+const HelpTab_1 = require("./tabs/HelpTab");
+const NewsTab_1 = require("./tabs/NewsTab");
+const theme_1 = require("./theme");
+const DEFAULT_TABS = ['home', 'messages', 'help', 'news'];
+function MessengerShell({ 
+// chat provider props
+token, apiBaseUrl, browserSessionId, stream, userContext, theme: themeOverride, autoStart, 
+// shell props
+tabs = DEFAULT_TABS, defaultTab = 'home', activeTab, onTabChange, homeGreeting, homeQuestion, homeActions, homeAvatars, homeFooter, brand, helpAdapter, newsAdapter, panelProps, display = 'inline', width = 380, maxHeight, onClose, unread, }) {
+    // Controlled / uncontrolled active tab. When the parent passes
+    // activeTab, we never touch internal state.
+    const [internalTab, setInternalTab] = (0, react_1.useState)(defaultTab);
+    const tab = activeTab ?? internalTab;
+    const setTab = (next) => {
+        if (activeTab === undefined)
+            setInternalTab(next);
+        onTabChange?.(next);
+    };
+    // We mount AgentChatProvider once so the session warms up regardless
+    // of which tab is active — that way clicking Messages doesn't trigger
+    // a cold "Loading…". Provider is cheap; the wire only starts on the
+    // first useChat() call.
+    return ((0, jsx_runtime_1.jsx)(provider_1.AgentChatProvider, { token: token, apiBaseUrl: apiBaseUrl, browserSessionId: browserSessionId, stream: stream, userContext: userContext, theme: themeOverride, autoStart: autoStart, children: (0, jsx_runtime_1.jsx)(ShellChrome, { display: display, width: width, maxHeight: maxHeight, themeOverride: themeOverride, children: (0, jsx_runtime_1.jsx)(TabSurface, { tab: tab, tabs: tabs, setTab: setTab, onClose: onClose, brand: brand, homeGreeting: homeGreeting, homeQuestion: homeQuestion, homeActions: homeActions, homeAvatars: homeAvatars, homeFooter: homeFooter, helpAdapter: helpAdapter, newsAdapter: newsAdapter, panelProps: panelProps, unread: unread }) }) }));
+}
+/**
+ * Container that handles the `floating` vs `inline` mode and merges
+ * the resolved theme onto the root so children can read CSS vars.
+ *
+ * Split out from `MessengerShell` so the chrome can read `useAgent()`
+ * (which is only available inside the provider). The theme on the
+ * agent token wins over a static override — but the consumer's
+ * `themeOverride` wins over both (existing v3 behavior, preserved).
+ */
+function ShellChrome({ display, width, maxHeight, themeOverride, children, }) {
+    const { theme: agentTheme } = (0, hooks_1.useAgent)();
+    const merged = (0, react_1.useMemo)(() => ({ ...(agentTheme ?? {}), ...(themeOverride ?? {}) }), [agentTheme, themeOverride]);
+    const theme = (0, react_1.useMemo)(() => (0, theme_1.resolveTheme)(merged), [merged]);
+    const [computedMaxHeight, setComputedMaxHeight] = (0, react_1.useState)(maxHeight ?? 640);
+    (0, react_1.useEffect)(() => {
+        if (maxHeight !== undefined) {
+            setComputedMaxHeight(maxHeight);
+            return;
+        }
+        const update = () => {
+            const vh = typeof window === 'undefined' ? 720 : window.innerHeight;
+            setComputedMaxHeight(Math.min(640, vh - 80));
+        };
+        update();
+        window.addEventListener('resize', update);
+        return () => window.removeEventListener('resize', update);
+    }, [maxHeight]);
+    const baseStyle = {
+        display: 'flex',
+        flexDirection: 'column',
+        background: theme.surface,
+        borderRadius: 18,
+        overflow: 'hidden',
+        border: '1px solid #e2e8f0',
+        boxShadow: '0 12px 40px rgba(15, 23, 42, 0.18)',
+        fontFamily: 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+        color: theme.onSurface,
+        minHeight: 0,
+    };
+    const style = display === 'floating'
+        ? {
+            ...baseStyle,
+            position: 'fixed',
+            right: 20,
+            bottom: 20,
+            width,
+            height: computedMaxHeight,
+            maxHeight: '90vh',
+            zIndex: 2147483000,
+        }
+        : { ...baseStyle, height: '100%' };
+    // Provide the theme via context — but we don't need React.Context
+    // here because each tab is rendered with `theme` as a prop already.
+    // Splitting out a ThemeContext would be over-engineering for v1.
+    return (0, jsx_runtime_1.jsx)("div", { style: style, children: children });
+}
+function TabSurface({ tab, tabs, setTab, onClose, brand, homeGreeting, homeQuestion, homeActions, homeAvatars, homeFooter, helpAdapter, newsAdapter, panelProps, unread, }) {
+    const { theme: agentTheme } = (0, hooks_1.useAgent)();
+    const theme = (0, react_1.useMemo)(() => (0, theme_1.resolveTheme)(agentTheme), [agentTheme]);
+    // Render the active tab. We deliberately do NOT keep mounted tabs in
+    // the tree — switching is cheap and remounting Help/News refetches,
+    // which is the desired behavior (especially News).
+    const content = (() => {
+        switch (tab) {
+            case 'home':
+                return ((0, jsx_runtime_1.jsx)(HomeTab_1.HomeTab, { theme: theme, brand: brand, onClose: onClose, greeting: homeGreeting, question: homeQuestion, avatars: homeAvatars, actions: homeActions, footer: homeFooter, onSendMessage: tabs.includes('messages')
+                        ? () => setTab('messages')
+                        : undefined }));
+            case 'messages':
+                return ((0, jsx_runtime_1.jsx)(MessagesTab_1.MessagesTab, { theme: theme, panelProps: panelProps, topBarAction: onClose && ((0, jsx_runtime_1.jsx)(CloseButton, { onClick: onClose, color: theme.onSurface })) }));
+            case 'help':
+                if (!helpAdapter)
+                    return (0, jsx_runtime_1.jsx)(MissingAdapter, { name: "helpAdapter" });
+                return (0, jsx_runtime_1.jsx)(HelpTab_1.HelpTab, { theme: theme, adapter: helpAdapter });
+            case 'news':
+                if (!newsAdapter)
+                    return (0, jsx_runtime_1.jsx)(MissingAdapter, { name: "newsAdapter" });
+                return (0, jsx_runtime_1.jsx)(NewsTab_1.NewsTab, { theme: theme, adapter: newsAdapter });
+        }
+    })();
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("div", { style: { flex: 1, minHeight: 0, display: 'flex' }, children: (0, jsx_runtime_1.jsx)("div", { style: { flex: 1, minWidth: 0 }, children: content }) }), (0, jsx_runtime_1.jsx)(MessengerFooter_1.MessengerFooter, { theme: theme, active: tab, onChange: setTab, tabs: tabs, unread: unread })] }));
+}
+function CloseButton({ onClick, color, }) {
+    return ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: onClick, "aria-label": "Close", style: {
+            background: 'transparent',
+            border: 'none',
+            color,
+            cursor: 'pointer',
+            fontSize: 20,
+            lineHeight: 1,
+            padding: 4,
+            opacity: 0.7,
+        }, children: "\u00D7" }));
+}
+function MissingAdapter({ name }) {
+    return ((0, jsx_runtime_1.jsxs)("div", { style: {
+            padding: 24,
+            fontSize: 13,
+            color: '#dc2626',
+            background: '#fff',
+            height: '100%',
+        }, children: ["Missing ", (0, jsx_runtime_1.jsx)("code", { children: name }), " prop on ", (0, jsx_runtime_1.jsx)("code", { children: "MessengerShell" }), "."] }));
+}

package/dist/messenger/adapters.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Adapter contracts the consumer wires to feed the Help and News tabs.
+ *
+ * The SDK does NOT bundle a transport for these — they're host-specific:
+ * AgentForge platform queries `/walkthroughs/search`, but a third-party
+ * embedder might point them at their own KB. Keeping the adapter
+ * boundary thin means consumers don't depend on platform internals.
+ *
+ * All adapter methods may throw; the tabs render an error state and let
+ * the user retry. Consumers should NOT swallow errors — surface them.
+ */
+export interface HelpResult {
+    id: string;
+    /** Renders as the primary line in the search result. */
+    title: string;
+    /** Optional one-line context (e.g. collection name, summary). */
+    excerpt?: string;
+    /** Where this content lives. Drives the click behavior:
+     *  - `walkthrough`: clicking calls `onWalkthroughOpen(id)` so the host
+     *    can hand off to the playback engine (no navigation).
+     *  - `article`: clicking opens `href` in a new tab.
+     *  - `external`: same as article but tagged so we render an external-link
+     *    icon (consumer disambiguates internal docs from external links). */
+    kind: 'walkthrough' | 'article' | 'external';
+    href?: string;
+}
+export interface HelpCollection {
+    id: string;
+    name: string;
+    description?: string;
+    /** Used in the list-view "N articles" tail label. */
+    itemCount: number;
+    /** Lucide-react icon name or a custom URL. Free-form on purpose — the
+     *  consumer controls icon vocabulary. */
+    iconUrl?: string;
+}
+export interface HelpCollectionDetail extends HelpCollection {
+    items: HelpResult[];
+}
+export interface HelpAdapter {
+    search(query: string): Promise<HelpResult[]>;
+    listCollections(): Promise<HelpCollection[]>;
+    getCollection(id: string): Promise<HelpCollectionDetail>;
+    /**
+     * Called when the user clicks a result with `kind === 'walkthrough'`.
+     * The host wires this to its in-app playback engine — the SDK never
+     * touches the host DOM. When omitted, walkthrough results fall back
+     * to a no-op + a console warning so the developer notices.
+     */
+    onWalkthroughOpen?: (walkthroughId: string) => void;
+}
+export interface Announcement {
+    id: string;
+    title: string;
+    body: string;
+    /** ISO timestamp; the tab renders relative time. */
+    publishedAt: string;
+    /** Operator override to stick an item at the top. Render order:
+     *  pinned first (by publishedAt desc), then non-pinned by publishedAt desc. */
+    pinned?: boolean;
+    /** Read state is consumer-tracked — the SDK just renders the badge. */
+    read?: boolean;
+    /** Optional CTA: when set, the card becomes a link. */
+    href?: string;
+    /** Optional cover image rendered above the title. */
+    imageUrl?: string;
+}
+export interface NewsAdapter {
+    listAnnouncements(): Promise<Announcement[]>;
+    /** Mark an announcement as read. Best-effort — the tab updates the
+     *  badge optimistically and ignores failures. */
+    markRead?: (announcementId: string) => Promise<void>;
+}
+/**
+ * Default Home action shape. Consumers pass an array of these to the
+ * shell; we render them as a vertical list of card rows under the
+ * greeting + "Send us a message" CTA.
+ */
+export interface HomeAction {
+    id: string;
+    /** Leading emoji or icon component. Strings are rendered raw so
+     *  emojis work out of the box (no font dependency). */
+    icon?: React.ReactNode | string;
+    label: string;
+    /** When provided, clicking opens the link in a new tab. */
+    href?: string;
+    /** Alternative to `href` — fires a callback (e.g. switching tabs). */
+    onClick?: () => void;
+    /** Visual hint on the trailing edge. Defaults to 'external' when
+     *  `href` is set, 'arrow' otherwise. Set explicitly to override. */
+    trailingIcon?: 'external' | 'arrow' | 'none';
+}

package/dist/messenger/adapters.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Adapter contracts the consumer wires to feed the Help and News tabs.
+ *
+ * The SDK does NOT bundle a transport for these — they're host-specific:
+ * AgentForge platform queries `/walkthroughs/search`, but a third-party
+ * embedder might point them at their own KB. Keeping the adapter
+ * boundary thin means consumers don't depend on platform internals.
+ *
+ * All adapter methods may throw; the tabs render an error state and let
+ * the user retry. Consumers should NOT swallow errors — surface them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/messenger/tabs/HelpTab.d.ts

@@ -0,0 +1,21 @@
+import type { ResolvedTheme } from '../theme';
+import type { HelpAdapter } from '../adapters';
+/**
+ * Help tab. Two states:
+ *   1. Default: search input + collection list (browse)
+ *   2. Query active: search input + result list (search)
+ *
+ * We debounce the search so each keystroke doesn't fire a request;
+ * 250ms feels live enough without hammering the adapter when the user
+ * is typing fast.
+ *
+ * When the user clicks a `kind: 'walkthrough'` result, we route through
+ * `adapter.onWalkthroughOpen?.(id)`. The SDK never touches the host
+ * DOM — playback is the host's responsibility.
+ */
+export interface HelpTabProps {
+    theme: ResolvedTheme;
+    adapter: HelpAdapter;
+    title?: string;
+}
+export declare function HelpTab({ theme, adapter, title }: HelpTabProps): import("react/jsx-runtime").JSX.Element;