@promptbook/components 0.101.0-17 → 0.101.0-18

package/esm/typings/src/_packages/components.index.d.ts

@@ -15,6 +15,9 @@ import { BookEditor } from '../book-components/BookEditor/BookEditor';
 import { DEFAULT_BOOK_FONT_CLASS } from '../book-components/BookEditor/config';
 import { Chat } from '../book-components/Chat/Chat/Chat';
 import type { ChatProps } from '../book-components/Chat/Chat/ChatProps';
+import { useChatAutoScroll } from '../book-components/Chat/hooks/useChatAutoScroll';
+import type { SendMessageToLlmChatFunction } from '../book-components/Chat/hooks/useSendMessageToLlmChat';
+import { useSendMessageToLlmChat } from '../book-components/Chat/hooks/useSendMessageToLlmChat';
 import { LlmChat } from '../book-components/Chat/LlmChat/LlmChat';
 import type { LlmChatProps } from '../book-components/Chat/LlmChat/LlmChatProps';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
@@ -44,6 +47,9 @@ export { BookEditor };
 export { DEFAULT_BOOK_FONT_CLASS };
 export { Chat };
 export type { ChatProps };
+export { useChatAutoScroll };
+export type { SendMessageToLlmChatFunction };
+export { useSendMessageToLlmChat };
 export { LlmChat };
 export type { LlmChatProps };
 export type { ChatMessage };

package/esm/typings/src/_packages/types.index.d.ts

@@ -13,6 +13,8 @@ import type { MockedChatDelayConfig } from '../book-components/AvatarProfile/Ava
 import type { MockedChatProps } from '../book-components/AvatarProfile/AvatarProfile/MockedChat';
 import type { BookEditorProps } from '../book-components/BookEditor/BookEditor';
 import type { ChatProps } from '../book-components/Chat/Chat/ChatProps';
+import type { ChatAutoScrollConfig } from '../book-components/Chat/hooks/useChatAutoScroll';
+import type { SendMessageToLlmChatFunction } from '../book-components/Chat/hooks/useSendMessageToLlmChat';
 import type { LlmChatProps } from '../book-components/Chat/LlmChat/LlmChatProps';
 import type { ChatMessage } from '../book-components/Chat/types/ChatMessage';
 import type { ChatParticipant } from '../book-components/Chat/types/ChatParticipant';
@@ -340,6 +342,8 @@ export type { MockedChatDelayConfig };
 export type { MockedChatProps };
 export type { BookEditorProps };
 export type { ChatProps };
+export type { ChatAutoScrollConfig };
+export type { SendMessageToLlmChatFunction };
 export type { LlmChatProps };
 export type { ChatMessage };
 export type { ChatParticipant };

package/esm/typings/src/book-components/Chat/LlmChat/LlmChatProps.d.ts

@@ -2,6 +2,7 @@ import type { LlmExecutionTools } from '../../../execution/LlmExecutionTools';
 import type { ChatProps } from '../Chat/ChatProps';
 import type { ChatMessage } from '../types/ChatMessage';
 import type { ChatParticipant } from '../types/ChatParticipant';
+import type { SendMessageToLlmChatFunction } from '../hooks/useSendMessageToLlmChat';
 /**
  * Props for LlmChat component, derived from ChatProps but with LLM-specific modifications
  *
@@ -17,8 +18,20 @@ export type LlmChatProps = Omit<ChatProps, 'messages' | 'onMessage' | 'onChange'
      * When provided, the conversation will be saved and restored from localStorage
      */
     readonly persistenceKey?: string;
+    /**
+     * Optional initial messages to pre-populate the chat.
+     * - They can include both USER and ASSISTANT messages.
+     * - They are only used when there is no persisted conversation (persistence takes precedence).
+     * - They are not automatically persisted until the user sends a new message.
+     */
+    readonly initialMessages?: ReadonlyArray<ChatMessage>;
     /**
      * Called when the chat state changes (messages, participants, etc.)
      */
     onChange?(messages: ReadonlyArray<ChatMessage>, participants: ReadonlyArray<ChatParticipant>): void;
+    /**
+     * Optional external sendMessage function produced by useSendMessageToLlmChat hook.
+     * When provided, LlmChat will attach its internal handler to it (no React context needed).
+     */
+    readonly sendMessage?: SendMessageToLlmChatFunction;
 };

package/esm/typings/src/book-components/Chat/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export * from './useChatAutoScroll';
+export * from './useSendMessageToLlmChat';

package/esm/typings/src/book-components/Chat/hooks/useChatAutoScroll.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Configuration for the auto-scroll behavior
+ */
+export type ChatAutoScrollConfig = {
+    /**
+     * Threshold in pixels from bottom to consider as "at bottom"
+     * @default 100
+     */
+    bottomThreshold?: number;
+    /**
+     * Whether to use smooth scrolling
+     * @default true
+     */
+    smoothScroll?: boolean;
+    /**
+     * Delay before checking scroll position after new messages (in milliseconds)
+     * @default 100
+     */
+    scrollCheckDelay?: number;
+};
+/**
+ * Hook for managing auto-scroll behavior in chat components
+ *
+ * This hook provides:
+ * - Automatic scrolling to bottom when new messages arrive (if user is already at bottom)
+ * - Detection of when user scrolls away from bottom
+ * - Scroll-to-bottom functionality with smooth animation
+ * - Mobile-optimized scrolling behavior
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function useChatAutoScroll(config?: ChatAutoScrollConfig): {
+    isAutoScrolling: boolean;
+    chatMessagesRef: (element: HTMLDivElement | null) => void;
+    handleScroll: (event: React.UIEvent<HTMLDivElement>) => void;
+    handleMessagesChange: () => void;
+    scrollToBottom: () => void;
+    enableAutoScroll: () => void;
+    disableAutoScroll: () => void;
+    isMobile: boolean;
+};

package/esm/typings/src/book-components/Chat/hooks/useSendMessageToLlmChat.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Function type for sending a message to LlmChat.
+ *
+ * Implementation detail: The returned function is "attachable".
+ * LlmChat will call the internal `_attach` method (if present) to bind
+ * its real message handler. Messages sent before attachment are queued
+ * and flushed after attachment.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export type SendMessageToLlmChatFunction = {
+    /**
+     * Send a message to the bound LlmChat instance (or queue it until attached).
+     */
+    (message: string): void;
+    /**
+     * Internal method used by the <LlmChat/> component to attach its handler.
+     * Not intended for consumer usage.
+     *
+     * @internal
+     */
+    _attach?: (handler: (message: string) => Promise<void> | void) => void;
+};
+/**
+ * Hook to create a sendMessage function for an <LlmChat/> component WITHOUT needing any React Context.
+ *
+ * Usage pattern:
+ * ```tsx
+ * const sendMessage = useSendMessageToLlmChat();
+ * return (
+ *   <>
+ *     <button onClick={() => sendMessage('Hello!')}>Hello</button>
+ *     <LlmChat llmTools={llmTools} sendMessage={sendMessage} />
+ *   </>
+ * );
+ * ```
+ *
+ * - No provider wrapping needed.
+ * - Safe to call before the <LlmChat/> mounts (messages will be queued).
+ * - Keeps DRY by letting <LlmChat/> reuse its internal `handleMessage` logic.
+ *
+ * @public exported from `@promptbook/components`
+ */
+export declare function useSendMessageToLlmChat(): SendMessageToLlmChatFunction;

package/esm/typings/src/version.d.ts

@@ -15,7 +15,7 @@ export declare const BOOK_LANGUAGE_VERSION: string_semantic_version;
 export declare const PROMPTBOOK_ENGINE_VERSION: string_promptbook_version;
 /**
  * Represents the version string of the Promptbook engine.
- * It follows semantic versioning (e.g., `0.101.0-16`).
+ * It follows semantic versioning (e.g., `0.101.0-17`).
  *
  * @generated
  */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@promptbook/components",
-    "version": "0.101.0-17",
+    "version": "0.101.0-18",
     "description": "Promptbook: Run AI apps in plain human language across multiple models and platforms",
     "private": false,
     "sideEffects": false,

package/umd/index.umd.js

@@ -22,7 +22,7 @@
      * @generated
      * @see https://github.com/webgptorg/promptbook
      */
-    const PROMPTBOOK_ENGINE_VERSION = '0.101.0-17';
+    const PROMPTBOOK_ENGINE_VERSION = '0.101.0-18';
     /**
      * TODO: string_promptbook_version should be constrained to the all versions of Promptbook engine
      * Note: [💞] Ignore a discrepancy between file name and entity name
@@ -4131,6 +4131,147 @@
      */
     const TemplateIcon = ({ size }) => (jsxRuntime.jsx("svg", { width: size, height: size, viewBox: "0 0 24 24", fill: "currentColor", children: jsxRuntime.jsx("path", { d: "M14,2H6A2,2 0 0,0 4,4V20A2,2 0 0,0 6,22H18A2,2 0 0,0 20,20V8L14,2M18,20H6V4H13V9H18V20Z" }) }));
 
+    /**
+     * Hook for managing auto-scroll behavior in chat components
+     *
+     * This hook provides:
+     * - Automatic scrolling to bottom when new messages arrive (if user is already at bottom)
+     * - Detection of when user scrolls away from bottom
+     * - Scroll-to-bottom functionality with smooth animation
+     * - Mobile-optimized scrolling behavior
+     *
+     * @public exported from `@promptbook/components`
+     */
+    function useChatAutoScroll(config = {}) {
+        const { bottomThreshold = 100, smoothScroll = true, scrollCheckDelay = 100, } = config;
+        const [isAutoScrolling, setIsAutoScrolling] = react.useState(true);
+        const [isMobile, setIsMobile] = react.useState(false);
+        const chatMessagesRef = react.useRef(null);
+        const scrollTimeoutRef = react.useRef(null);
+        const lastScrollHeightRef = react.useRef(0);
+        // Detect mobile device
+        react.useEffect(() => {
+            const checkMobile = () => {
+                const isMobileDevice = window.innerWidth <= 768 ||
+                    /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+                setIsMobile(isMobileDevice);
+            };
+            checkMobile();
+            window.addEventListener('resize', checkMobile);
+            return () => window.removeEventListener('resize', checkMobile);
+        }, []);
+        // Check if user is at the bottom of the chat
+        const checkIfAtBottom = react.useCallback((element) => {
+            const { scrollTop, scrollHeight, clientHeight } = element;
+            return scrollTop + clientHeight >= scrollHeight - bottomThreshold;
+        }, [bottomThreshold]);
+        // Scroll to bottom function
+        const scrollToBottom = react.useCallback((behavior = 'smooth') => {
+            const chatMessagesElement = chatMessagesRef.current;
+            if (!chatMessagesElement)
+                return;
+            if (isMobile) {
+                // Mobile-optimized scrolling
+                chatMessagesElement.scrollTo({
+                    top: chatMessagesElement.scrollHeight,
+                    behavior: smoothScroll ? behavior : 'auto',
+                });
+            }
+            else {
+                // Desktop scrolling
+                if (smoothScroll && behavior === 'smooth') {
+                    chatMessagesElement.style.scrollBehavior = 'smooth';
+                    chatMessagesElement.scrollTop = chatMessagesElement.scrollHeight;
+                    chatMessagesElement.style.scrollBehavior = 'auto';
+                }
+                else {
+                    chatMessagesElement.scrollTop = chatMessagesElement.scrollHeight;
+                }
+            }
+        }, [isMobile, smoothScroll]);
+        // Handle scroll events
+        const handleScroll = react.useCallback((event) => {
+            const element = event.target;
+            if (!element)
+                return;
+            // Clear any pending scroll timeout
+            if (scrollTimeoutRef.current) {
+                clearTimeout(scrollTimeoutRef.current);
+            }
+            // Debounce scroll position check to avoid too frequent updates
+            scrollTimeoutRef.current = setTimeout(() => {
+                const isAtBottom = checkIfAtBottom(element);
+                setIsAutoScrolling(isAtBottom);
+            }, 50);
+        }, [checkIfAtBottom]);
+        // Auto-scroll when messages change (if user is at bottom)
+        const handleMessagesChange = react.useCallback(() => {
+            const chatMessagesElement = chatMessagesRef.current;
+            if (!chatMessagesElement)
+                return;
+            // Check if this is a new message (scroll height increased)
+            const currentScrollHeight = chatMessagesElement.scrollHeight;
+            const hasNewContent = currentScrollHeight > lastScrollHeightRef.current;
+            lastScrollHeightRef.current = currentScrollHeight;
+            if (!hasNewContent)
+                return;
+            // If user is set to auto-scroll, scroll to bottom
+            if (isAutoScrolling) {
+                // Delay scroll slightly to ensure DOM has updated
+                setTimeout(() => {
+                    scrollToBottom('smooth');
+                }, scrollCheckDelay);
+            }
+        }, [isAutoScrolling, scrollToBottom, scrollCheckDelay]);
+        // Ref callback for chat messages container
+        const chatMessagesRefCallback = react.useCallback((element) => {
+            chatMessagesRef.current = element;
+            if (element) {
+                // Update last scroll height
+                lastScrollHeightRef.current = element.scrollHeight;
+                // If auto-scrolling is enabled, scroll to bottom
+                if (isAutoScrolling) {
+                    // Use requestAnimationFrame for smoother initial scroll
+                    requestAnimationFrame(() => {
+                        scrollToBottom('auto');
+                    });
+                }
+            }
+        }, [isAutoScrolling, scrollToBottom]);
+        // Manual scroll to bottom (for button click)
+        const handleScrollToBottomClick = react.useCallback(() => {
+            setIsAutoScrolling(true);
+            scrollToBottom('smooth');
+        }, [scrollToBottom]);
+        // Force auto-scroll back on (useful for programmatic control)
+        const enableAutoScroll = react.useCallback(() => {
+            setIsAutoScrolling(true);
+            scrollToBottom('smooth');
+        }, [scrollToBottom]);
+        // Disable auto-scroll (useful for programmatic control)
+        const disableAutoScroll = react.useCallback(() => {
+            setIsAutoScrolling(false);
+        }, []);
+        // Cleanup timeout on unmount
+        react.useEffect(() => {
+            return () => {
+                if (scrollTimeoutRef.current) {
+                    clearTimeout(scrollTimeoutRef.current);
+                }
+            };
+        }, []);
+        return {
+            isAutoScrolling,
+            chatMessagesRef: chatMessagesRefCallback,
+            handleScroll,
+            handleMessagesChange,
+            scrollToBottom: handleScrollToBottomClick,
+            enableAutoScroll,
+            disableAutoScroll,
+            isMobile,
+        };
+    }
+
     /**
      * Parses markdown buttons in the format [Button Text](?message=Message%20to%20send)
      * Returns both the content without buttons and the extracted buttons
@@ -4319,9 +4460,9 @@
         // exportHeaderMarkdown,
         participants = [], } = props;
         const { onUseTemplate } = props;
-        const [isAutoScrolling, setAutoScrolling] = react.useState(true);
+        // Use the auto-scroll hook
+        const { isAutoScrolling, chatMessagesRef, handleScroll, handleMessagesChange, scrollToBottom, isMobile: isMobileFromHook, } = useChatAutoScroll();
         const textareaRef = react.useRef(null);
-        const chatMessagesRef = react.useRef(null);
         const buttonSendRef = react.useRef(null);
         const [ratingModalOpen, setRatingModalOpen] = react.useState(false);
         const [selectedMessage, setSelectedMessage] = react.useState(null);
@@ -4334,18 +4475,8 @@
         // const [inputValue, setInputValue] = useState('');
         const [mode] = react.useState('LIGHT'); // Simplified light/dark mode
         const [ratingConfirmation, setRatingConfirmation] = react.useState(null);
-        const [isMobile, setIsMobile] = react.useState(false);
-        // Detect mobile device
-        react.useEffect(() => {
-            const checkMobile = () => {
-                const isMobileDevice = window.innerWidth <= 768 ||
-                    /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
-                setIsMobile(isMobileDevice);
-            };
-            checkMobile();
-            window.addEventListener('resize', checkMobile);
-            return () => window.removeEventListener('resize', checkMobile);
-        }, []);
+        // Use mobile detection from the hook
+        const isMobile = isMobileFromHook;
         react.useEffect(( /* Focus textarea on page load */) => {
             if (!textareaRef.current) {
                 return;
@@ -4471,59 +4602,16 @@
                 return { ...message, content: humanizeAiText(message.content) };
             });
         }, [messages, isAiTextHumanized]);
-        return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [ratingConfirmation && jsxRuntime.jsx("div", { className: styles$1.ratingConfirmation, children: ratingConfirmation }), jsxRuntime.jsx("div", { className: classNames(className, styles$1.Chat, useChatCssClassName('Chat')), style, children: jsxRuntime.jsxs("div", { className: classNames(className, styles$1.chatMainFlow, useChatCssClassName('chatMainFlow')), children: [children && jsxRuntime.jsx("div", { className: classNames(styles$1.chatBar, chatBarCssClassName), children: children }), !isAutoScrolling && (jsxRuntime.jsx("div", { className: styles$1.scrollToBottomContainer, children: jsxRuntime.jsx("button", { "data-button-type": "custom", className: classNames(styles$1.scrollToBottom, scrollToBottomCssClassName), onClick: () => {
-                                        const chatMessagesElement = chatMessagesRef.current;
-                                        if (chatMessagesElement === null) {
-                                            return;
-                                        }
-                                        // Mobile-optimized scroll to bottom
-                                        if (isMobile) {
-                                            chatMessagesElement.scrollTo({
-                                                top: chatMessagesElement.scrollHeight,
-                                                behavior: 'smooth',
-                                            });
-                                        }
-                                        else {
-                                            chatMessagesElement.style.scrollBehavior = 'smooth';
-                                            chatMessagesElement.scrollBy(0, 10000);
-                                            chatMessagesElement.style.scrollBehavior = 'auto';
-                                        }
-                                    }, children: jsxRuntime.jsx(ArrowIcon, { direction: "DOWN", size: 33 }) }) })), isVoiceCalling && (jsxRuntime.jsx("div", { className: styles$1.voiceCallIndicatorBar, children: jsxRuntime.jsxs("div", { className: styles$1.voiceCallIndicator, children: [jsxRuntime.jsx("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "currentColor", children: jsxRuntime.jsx("path", { d: "M6.62 10.79c1.44 2.83 3.76 5.14 6.59 6.59l2.2-2.2c.27-.27.67-.36 1.02-.24 1.12.37 2.33.57 3.57.57.55 0 1 .45 1 1V20c0 .55-.45 1-1 1-9.39 0-17-7.61-17-17 0-.55.45-1 1-1h3.5c.55 0 1 .45 1 1 0 1.25.2 2.45.57 3.57.11.35.03.74-.25 1.02l-2.2 2.2z" }) }), jsxRuntime.jsx("span", { children: "Voice call active" }), jsxRuntime.jsx("div", { className: styles$1.voiceCallPulse })] }) })), jsxRuntime.jsxs("div", { className: classNames(actionsAlignmentClass), children: [onReset && postprocessedMessages.length !== 0 && (jsxRuntime.jsxs("button", { className: classNames(styles$1.resetButton), onClick: () => {
+        // Trigger auto-scroll when messages change
+        react.useEffect(() => {
+            handleMessagesChange();
+        }, [postprocessedMessages, handleMessagesChange]);
+        return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [ratingConfirmation && jsxRuntime.jsx("div", { className: styles$1.ratingConfirmation, children: ratingConfirmation }), jsxRuntime.jsx("div", { className: classNames(className, styles$1.Chat, useChatCssClassName('Chat')), style, children: jsxRuntime.jsxs("div", { className: classNames(className, styles$1.chatMainFlow, useChatCssClassName('chatMainFlow')), children: [children && jsxRuntime.jsx("div", { className: classNames(styles$1.chatBar, chatBarCssClassName), children: children }), !isAutoScrolling && (jsxRuntime.jsx("div", { className: styles$1.scrollToBottomContainer, children: jsxRuntime.jsx("button", { "data-button-type": "custom", className: classNames(styles$1.scrollToBottom, scrollToBottomCssClassName), onClick: scrollToBottom, children: jsxRuntime.jsx(ArrowIcon, { direction: "DOWN", size: 33 }) }) })), isVoiceCalling && (jsxRuntime.jsx("div", { className: styles$1.voiceCallIndicatorBar, children: jsxRuntime.jsxs("div", { className: styles$1.voiceCallIndicator, children: [jsxRuntime.jsx("svg", { width: "16", height: "16", viewBox: "0 0 24 24", fill: "currentColor", children: jsxRuntime.jsx("path", { d: "M6.62 10.79c1.44 2.83 3.76 5.14 6.59 6.59l2.2-2.2c.27-.27.67-.36 1.02-.24 1.12.37 2.33.57 3.57.57.55 0 1 .45 1 1V20c0 .55-.45 1-1 1-9.39 0-17-7.61-17-17 0-.55.45-1 1-1h3.5c.55 0 1 .45 1 1 0 1.25.2 2.45.57 3.57.11.35.03.74-.25 1.02l-2.2 2.2z" }) }), jsxRuntime.jsx("span", { children: "Voice call active" }), jsxRuntime.jsx("div", { className: styles$1.voiceCallPulse })] }) })), jsxRuntime.jsxs("div", { className: classNames(actionsAlignmentClass), children: [onReset && postprocessedMessages.length !== 0 && (jsxRuntime.jsxs("button", { className: classNames(styles$1.resetButton), onClick: () => {
                                             if (!confirm(`Do you really want to reset the chat?`)) {
                                                 return;
                                             }
                                             onReset();
-                                        }, children: [jsxRuntime.jsx(ResetIcon, {}), jsxRuntime.jsx("span", { className: styles$1.resetButtonText, children: "New chat" })] })), onUseTemplate && (jsxRuntime.jsxs("button", { className: classNames(styles$1.useTemplateButton), onClick: onUseTemplate, children: [jsxRuntime.jsx("span", { className: styles$1.resetButtonText, children: "Use this template" }), jsxRuntime.jsx(TemplateIcon, { size: 16 })] }))] }), jsxRuntime.jsx("div", { className: classNames(styles$1.chatMessages, useChatCssClassName('chatMessages')), ref: (chatMessagesElement) => {
-                                    chatMessagesRef.current = chatMessagesElement;
-                                    if (chatMessagesElement === null) {
-                                        return;
-                                    }
-                                    if (!isAutoScrolling) {
-                                        return;
-                                    }
-                                    // Mobile-optimized scrolling
-                                    if (isMobile) {
-                                        // Delay scroll slightly on mobile for better performance
-                                        requestAnimationFrame(() => {
-                                            chatMessagesElement.scrollTo({
-                                                top: chatMessagesElement.scrollHeight,
-                                                behavior: 'smooth',
-                                            });
-                                        });
-                                    }
-                                    else {
-                                        // Desktop smooth scrolling
-                                        chatMessagesElement.style.scrollBehavior = 'smooth';
-                                        chatMessagesElement.scrollBy(0, 1000);
-                                        chatMessagesElement.style.scrollBehavior = 'auto';
-                                    }
-                                }, onScroll: (event) => {
-                                    const element = event.target;
-                                    if (!(element instanceof HTMLDivElement)) {
-                                        return;
-                                    }
-                                    setAutoScrolling(element.scrollTop + element.clientHeight > element.scrollHeight - 100);
-                                }, children: postprocessedMessages.map((message, i) => {
+                                        }, children: [jsxRuntime.jsx(ResetIcon, {}), jsxRuntime.jsx("span", { className: styles$1.resetButtonText, children: "New chat" })] })), onUseTemplate && (jsxRuntime.jsxs("button", { className: classNames(styles$1.useTemplateButton), onClick: onUseTemplate, children: [jsxRuntime.jsx("span", { className: styles$1.resetButtonText, children: "Use this template" }), jsxRuntime.jsx(TemplateIcon, { size: 16 })] }))] }), jsxRuntime.jsx("div", { className: classNames(styles$1.chatMessages, useChatCssClassName('chatMessages')), ref: chatMessagesRef, onScroll: handleScroll, children: postprocessedMessages.map((message, i) => {
                                     const participant = participants.find((participant) => participant.name === message.from);
                                     const avatarSrc = (participant && participant.avatarSrc) || '';
                                     const color = Color.from((participant && participant.color) || '#ccc');
@@ -5397,6 +5485,53 @@
         return (jsxRuntime.jsx("div", { "data-book-component": "BookEditor", ref: hostRef, className: classNames(styles.BookEditor, isVerbose && styles.isVerbose, className), style: style, children: shadowReady && shadowRootRef.current ? reactDom.createPortal(editorInner, shadowRootRef.current) : jsxRuntime.jsx(jsxRuntime.Fragment, { children: "Loading..." }) }));
     }
 
+    /**
+     * Hook to create a sendMessage function for an <LlmChat/> component WITHOUT needing any React Context.
+     *
+     * Usage pattern:
+     * ```tsx
+     * const sendMessage = useSendMessageToLlmChat();
+     * return (
+     *   <>
+     *     <button onClick={() => sendMessage('Hello!')}>Hello</button>
+     *     <LlmChat llmTools={llmTools} sendMessage={sendMessage} />
+     *   </>
+     * );
+     * ```
+     *
+     * - No provider wrapping needed.
+     * - Safe to call before the <LlmChat/> mounts (messages will be queued).
+     * - Keeps DRY by letting <LlmChat/> reuse its internal `handleMessage` logic.
+     *
+     * @public exported from `@promptbook/components`
+     */
+    function useSendMessageToLlmChat() {
+        const ref = react.useRef(null);
+        if (!ref.current) {
+            let handler = null;
+            const queue = [];
+            const sendMessage = (message) => {
+                if (handler) {
+                    // Fire and forget
+                    void handler(message);
+                }
+                else {
+                    queue.push(message);
+                }
+            };
+            sendMessage._attach = (attachedHandler) => {
+                handler = attachedHandler;
+                // Flush queued messages
+                while (queue.length > 0) {
+                    const next = queue.shift();
+                    void handler(next);
+                }
+            };
+            ref.current = sendMessage;
+        }
+        return ref.current;
+    }
+
     /**
      * Utility functions for persisting chat conversations in localStorage
      *
@@ -5483,16 +5618,22 @@
      * @public exported from `@promptbook/components`
      */
     function LlmChat(props) {
-        const { llmTools, persistenceKey, onChange, onReset, ...restProps } = props;
+        const { llmTools, persistenceKey, onChange, onReset, initialMessages, sendMessage, ...restProps } = props;
         // Internal state management
-        const [messages, setMessages] = react.useState([]);
+        const [messages, setMessages] = react.useState(() => (initialMessages ? [...initialMessages] : []));
         const [tasksProgress, setTasksProgress] = react.useState([]);
+        /**
+         * Tracks whether the user (or system via persistence restoration) has interacted.
+         * We do NOT persist purely initialMessages until the user sends something.
+         */
+        const hasUserInteractedRef = react.useRef(false);
         // Load persisted messages on component mount
         react.useEffect(() => {
             if (persistenceKey && ChatPersistence.isAvailable()) {
                 const persistedMessages = ChatPersistence.loadMessages(persistenceKey);
                 if (persistedMessages.length > 0) {
                     setMessages(persistedMessages);
+                    hasUserInteractedRef.current = true; // Persisted conversation exists; allow saving next changes
                     // Notify about loaded messages
                     if (onChange) {
                         onChange(persistedMessages, participants);
@@ -5502,7 +5643,10 @@
         }, [persistenceKey]); // Only depend on persistenceKey, not participants or onChange to avoid infinite loops
         // Save messages to localStorage whenever messages change (and persistence is enabled)
         react.useEffect(() => {
-            if (persistenceKey && ChatPersistence.isAvailable() && messages.length > 0) {
+            if (persistenceKey &&
+                ChatPersistence.isAvailable() &&
+                messages.length > 0 &&
+                hasUserInteractedRef.current) {
                 ChatPersistence.saveMessages(persistenceKey, messages);
             }
         }, [messages, persistenceKey]);
@@ -5523,6 +5667,7 @@
         ], [llmTools.profile, llmTools.title]);
         // Handle user messages and LLM responses
         const handleMessage = react.useCallback(async (messageContent) => {
+            hasUserInteractedRef.current = true;
             // Add user message
             const userMessage = {
                 id: `user_${Date.now()}`,
@@ -5610,6 +5755,7 @@
         const handleReset = react.useCallback(async () => {
             setMessages([]);
             setTasksProgress([]);
+            hasUserInteractedRef.current = false;
             // Clear persisted messages if persistence is enabled
             if (persistenceKey && ChatPersistence.isAvailable()) {
                 ChatPersistence.clearMessages(persistenceKey);
@@ -5622,6 +5768,12 @@
                 onChange([], participants);
             }
         }, [persistenceKey, onReset, onChange, participants]);
+        // Attach internal handler to external sendMessage (from useSendMessageToLlmChat) if provided
+        react.useEffect(() => {
+            if (sendMessage && sendMessage._attach) {
+                sendMessage._attach(handleMessage);
+            }
+        }, [sendMessage, handleMessage]);
         return (jsxRuntime.jsx(Chat, { ...restProps, messages, onReset, tasksProgress, participants, onMessage: handleMessage, onReset: handleReset }));
     }
 
@@ -5643,6 +5795,8 @@
     exports.isMarkdownContent = isMarkdownContent;
     exports.parseMessageButtons = parseMessageButtons;
     exports.renderMarkdown = renderMarkdown;
+    exports.useChatAutoScroll = useChatAutoScroll;
+    exports.useSendMessageToLlmChat = useSendMessageToLlmChat;
 
     Object.defineProperty(exports, '__esModule', { value: true });