@lowdefy/blocks-antd-x 5.6.0 → 6.1.0

package/dist/blocks/AgentChat/AgentChat.js

@@ -16,27 +16,36 @@
 import { useChat } from '@ai-sdk/react';
 import { lastAssistantMessageIsCompleteWithApprovalResponses, lastAssistantMessageIsCompleteWithToolCalls } from 'ai';
 import { FileCard, Prompts, Sender } from '@ant-design/x';
-import { Button } from 'antd';
+import { Button, Skeleton } from 'antd';
 import { PaperClipOutlined } from '@ant-design/icons';
 import { isReserved, setKey, type } from '@lowdefy/helpers';
+import getLegacyObjectUrl from '@lowdefy/blocks-files/utils/getLegacyObjectUrl.js';
+import getUploadPolicy from '@lowdefy/blocks-files/utils/getUploadPolicy.js';
+import uploadFile from '@lowdefy/blocks-files/utils/uploadFile.js';
 import { getFileCardType, getFileCardIcon } from './fileCardUtils.js';
 import DrawerWrapper from './DrawerWrapper.js';
 import createLowdefyChatTransport from './LowdefyChatTransport.js';
 import MessageList from './MessageList.js';
+import replayableMessages from './replayableMessages.js';
 import useAgentEvents, { collectExternalEventIds } from './useAgentEvents.js';
 import WelcomeScreen from './WelcomeScreen.js';
 function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageId, properties }) {
-    const { agentId, urlQuery, sharedState, welcome, messageDisplay, sender, conversationId, feedbackValues: storedFeedbackValues, messages: externalMessages, display, drawer: drawerConfig, suggestions } = properties;
+    const { agentId, urlQuery, sharedState, welcome, messageDisplay, sender, conversationId, feedbackValues: storedFeedbackValues, messages: externalMessages, display, drawer: drawerConfig, suggestions, loading } = properties;
     const senderRef = useRef(null);
     const finishMetaRef = useRef(null);
     const fileInputRef = useRef(null);
     const [attachedFiles, setAttachedFiles] = useState([]);
     const [dragOver, setDragOver] = useState(false);
+    // Controlled composer value, so a starter prompt (or the setInput method) can
+    // fill the box, and a send can leave typed text in place when it is rejected.
+    const [inputValue, setInputValue] = useState('');
     // Mirror the operator-evaluated sharedState object into a ref so transport.body()
     // sees the freshest value at send time without re-constructing the transport.
     const sharedStateRef = useRef(null);
     sharedStateRef.current = type.isObject(sharedState) && Object.keys(sharedState).length > 0 ? sharedState : null;
     const attachmentsConfig = sender?.attachments;
+    const uploadPolicyRequestId = attachmentsConfig?.uploadPolicyRequestId ?? attachmentsConfig?.s3PostPolicyRequestId;
+    const downloadPolicyRequestId = attachmentsConfig?.downloadPolicyRequestId;
     const switchConfigs = sender?.switches ?? [];
     const [headerOpen, setHeaderOpen] = useState(sender?.header?.open ?? true);
     const [switchState, setSwitchState] = useState(()=>{
@@ -68,6 +77,11 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         urlQueryKey
     ]);
     const bubbleListRef = useRef(null);
+    // Call ids of client-side tools still running: their parts sit unanswered until
+    // addToolOutput, exactly like a cut-off call, and must survive the dead-call filter.
+    const pendingToolCallsRef = useRef(new Set());
+    // Read by the filter from mount-time method closures, which would see a stale `status`.
+    const statusRef = useRef('ready');
     const { messages, sendMessage, status, stop, addToolApprovalResponse, addToolOutput, setMessages, regenerate, clearError } = useChat({
         // Key the Chat instance by conversation: without an id, useChat creates its
         // Chat once per mount and CAPTURES that transport — the transport rebuilt by
@@ -85,6 +99,7 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         async onToolCall ({ toolCall }) {
             if (toolCall.dynamic) return;
             if (toolCall.toolName === 'update-page-state') {
+                pendingToolCallsRef.current.add(toolCall.toolCallId);
                 try {
                     const updates = toolCall.input?.updates ?? {};
                     // Allowlist writes against the keys currently exposed via sharedState —
@@ -131,10 +146,19 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
                         state: 'output-error',
                         errorText: err.message
                     });
+                } finally{
+                    pendingToolCallsRef.current.delete(toolCall.toolCallId);
                 }
             }
         },
         onError: (error)=>{
+            // A request that fails after the stream's `start` chunk leaves the
+            // assistant shell the SDK pushed on that chunk — id set, parts: [] — in
+            // the message list. Left there, every later send fails UIMessage
+            // validation ("Message must contain at least one part") and the
+            // conversation is dead until a reload. Drop empty shells so the user can
+            // simply try again; there is nothing in them to show or to send.
+            setMessages((prev)=>prev.filter((m)=>m.role !== 'assistant' || (m.parts?.length ?? 0) > 0));
             methods.triggerEvent({
                 name: 'onError',
                 event: {
@@ -160,6 +184,7 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
             });
         }
     });
+    statusRef.current = status;
     // The control is otherwise write-only: it reports a rating and immediately forgets it,
     // so the thumb un-highlights on the next render and the message looks unrated. This holds
     // what was clicked THIS visit; the block still persists nothing itself.
@@ -190,13 +215,29 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         effectiveConversationId,
         setMessages
     ]);
+    // Abort a reply still streaming into the conversation being left. useChat swaps its
+    // Chat instance during the render that changes the id, and the `stop` it returns is
+    // the NEW instance's — calling it in the effect above would stop an idle chat and
+    // leave the old request running, still firing onDataPart / onToolCall / onFinish
+    // into the page (and the server still generating) for a conversation no longer shown.
+    // A cleanup keyed only on the id closes over the previous render's `stop`, which is
+    // the old instance's. stop() on an idle chat is a no-op.
+    useEffect(()=>()=>stop(), [
+        effectiveConversationId
+    ]); // eslint-disable-line react-hooks/exhaustive-deps
     // Sync external messages when provided — undefined means "not provided" (no sync),
     // null means "clear messages", array means "load these messages".
     // Compare by count + last ID to avoid re-syncing on every Lowdefy re-render
     // (operators like _state create new array references even when data hasn't changed).
+    // The conversation id is part of the key: two conversations whose transcripts have the
+    // same length and last id (every assistant message an older onFinish hook persisted
+    // carries id '', so any two same-length transcripts collide) would otherwise not
+    // re-sync on a switch, leaving the new conversation's transcript empty.
+    // Seeded with the mount-time id so an undefined `messages` stays "no sync" on mount.
     const prevExternalRef = useRef({
         count: 0,
-        lastId: null
+        lastId: null,
+        conversationId: effectiveConversationId
     });
     // Event-dedup ids of externally loaded messages. Restored history must not
     // replay onToolCall / onToolResult / onUserMessage / onTitleGenerated side
@@ -207,36 +248,38 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         const msgs = externalMessages ?? [];
         const count = msgs.length;
         const lastId = count > 0 ? msgs[count - 1]?.id : null;
-        if (count !== prevExternalRef.current.count || lastId !== prevExternalRef.current.lastId) {
+        if (count !== prevExternalRef.current.count || lastId !== prevExternalRef.current.lastId || effectiveConversationId !== prevExternalRef.current.conversationId) {
             prevExternalRef.current = {
                 count,
-                lastId
+                lastId,
+                conversationId: effectiveConversationId
             };
-            externalIdsRef.current = collectExternalEventIds(msgs);
-            setMessages(msgs);
+            const replayable = withoutDeadToolCalls(msgs);
+            externalIdsRef.current = collectExternalEventIds(replayable);
+            setMessages(replayable);
         }
     }, [
         externalMessages,
+        effectiveConversationId,
         setMessages
     ]);
     // Register CallMethod methods so YAML actions can control the chat.
     useEffect(()=>{
         methods.registerMethod('regenerate', (args)=>{
-            regenerate(args?.messageId ? {
-                messageId: args.messageId
-            } : undefined);
+            if (sendingRef.current) return;
+            regenerateReply(args?.messageId);
         });
         methods.registerMethod('setMessages', (args)=>{
-            const msgs = args?.messages ?? [];
+            const msgs = withoutDeadToolCalls(args?.messages ?? []);
             externalIdsRef.current = collectExternalEventIds(msgs);
             setMessages(msgs);
         });
         methods.registerMethod('sendMessage', (args)=>{
-            if (args?.text) {
-                sendMessage({
+            if (args?.text && !sendingRef.current) {
+                deliver({
                     text: args.text,
                     ...args.files ? {
-                        experimental_attachments: args.files
+                        files: args.files
                     } : {},
                     ...args.metadata ? {
                         metadata: args.metadata
@@ -244,6 +287,9 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
                 });
             }
         });
+        methods.registerMethod('setInput', (args)=>{
+            setInputValue(typeof args?.text === 'string' ? args.text : '');
+        });
         methods.registerMethod('clearMessages', ()=>{
             setMessages([]);
         });
@@ -275,19 +321,36 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
                 }
             ]
         });
-        if (attachmentsConfig?.s3PostPolicyRequestId) {
+        if (uploadPolicyRequestId) {
+            if (attachmentsConfig?.s3PostPolicyRequestId) {
+                console.warn('AgentChat attachments property "s3PostPolicyRequestId" is deprecated. Use "uploadPolicyRequestId" instead.');
+            }
             methods.registerEvent({
-                name: '__getS3PostPolicy',
+                name: '__getUploadPolicy',
                 actions: [
                     {
-                        id: '__getS3PostPolicy',
+                        id: '__getUploadPolicy',
                         type: 'Request',
                         params: [
-                            attachmentsConfig.s3PostPolicyRequestId
+                            uploadPolicyRequestId
                         ]
                     }
                 ]
             });
+            if (downloadPolicyRequestId) {
+                methods.registerEvent({
+                    name: '__getDownloadPolicy',
+                    actions: [
+                        {
+                            id: '__getDownloadPolicy',
+                            type: 'Request',
+                            params: [
+                                downloadPolicyRequestId
+                            ]
+                        }
+                    ]
+                });
+            }
         }
     }, []);
     useAgentEvents({
@@ -300,6 +363,45 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
     });
     const isEmpty = messages.length === 0;
     const isBusy = status === 'streaming' || status === 'submitted';
+    // The app is still fetching this conversation's transcript (the `loading` property): a
+    // skeleton stands in for the message area and the composer is disabled, so nothing can
+    // be sent into a conversation whose history has not synced yet.
+    const isLoading = loading === true;
+    // A send awaits onBeforeSend while useChat still reports `ready`, so every submit during a
+    // slow quota check used to send again. The ref refuses re-entry (state is a render behind a
+    // double click); the state is what the Sender shows. Every other way of sending (prompts,
+    // suggestions, edit, regenerate, the sendMessage and regenerate methods) checks the ref too,
+    // or it would go out first and the composer's message straight after it.
+    const sendingRef = useRef(false);
+    const [sending, setSending] = useState(false);
+    // An unanswered tool call left by a reply cut off this session fails validation for the
+    // whole history, as one in a loaded history does. A reply still streaming is not cut off,
+    // and a client-side tool still running will add its output.
+    function withoutDeadToolCalls(list) {
+        if (statusRef.current === 'streaming' || statusRef.current === 'submitted') return list;
+        return replayableMessages({
+            messages: list,
+            liveToolCallIds: pendingToolCallsRef.current
+        });
+    }
+    // Every send goes through here. useChat applies the setter synchronously, so sendMessage
+    // reads the filtered list.
+    function deliver(message) {
+        setMessages((prev)=>withoutDeadToolCalls(prev));
+        sendMessage(message);
+    }
+    function regenerateReply(messageId) {
+        let kept = [];
+        setMessages((prev)=>{
+            kept = withoutDeadToolCalls(prev);
+            return kept;
+        });
+        // The reply asked for may have held nothing but a dead call and be gone; regenerate
+        // from the end instead of letting useChat throw on the missing id.
+        regenerate(kept.some((m)=>m.id === messageId) ? {
+            messageId
+        } : undefined);
+    }
     function fileToContentPart(file) {
         return new Promise((resolve)=>{
             const reader = new FileReader();
@@ -314,42 +416,41 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
             reader.readAsDataURL(file);
         });
     }
-    async function uploadFileToS3(file) {
-        const { name, size, type: fileType } = file;
-        const s3PostPolicyResponse = await methods.triggerEvent({
-            name: '__getS3PostPolicy',
-            event: {
-                file: {
-                    name,
-                    size,
-                    type: fileType
-                }
-            }
+    async function uploadFileToStorage(file) {
+        const { name, type: fileType } = file;
+        const descriptor = await getUploadPolicy({
+            methods,
+            file
         });
-        if (s3PostPolicyResponse.success !== true) {
-            throw new Error('S3 post policy request failed.');
-        }
-        const { url, fields = {} } = s3PostPolicyResponse.responses.__getS3PostPolicy.response[0];
-        const { key } = fields;
-        const formData = new FormData();
-        Object.keys(fields).forEach((field)=>{
-            formData.append(field, fields[field]);
+        await uploadFile({
+            descriptor,
+            file
         });
-        formData.append('file', file);
-        await new Promise((resolve, reject)=>{
-            const xhr = new XMLHttpRequest();
-            xhr.addEventListener('load', ()=>{
-                if (xhr.status >= 200 && xhr.status < 300) {
-                    resolve();
-                } else {
-                    reject(new Error(`S3 upload failed with status ${xhr.status}`));
+        // The model provider fetches this URL, so resolve it through the download
+        // request when configured (stable public URL or signed URL). Otherwise
+        // fall back to the legacy unsigned object URL from the descriptor.
+        let objectUrl;
+        if (downloadPolicyRequestId) {
+            const response = await methods.triggerEvent({
+                name: '__getDownloadPolicy',
+                event: {
+                    file: {
+                        bucket: descriptor.bucket,
+                        key: descriptor.key,
+                        name,
+                        type: fileType
+                    }
                 }
             });
-            xhr.addEventListener('error', ()=>reject(new Error('S3 upload network error')));
-            xhr.open('POST', url);
-            xhr.send(formData);
-        });
-        const objectUrl = url.endsWith('/') ? `${url}${key}` : `${url}/${key}`;
+            if (response.success !== true) {
+                throw new Error('Download policy request failed.');
+            }
+            objectUrl = response.responses.__getDownloadPolicy.response[0];
+        } else {
+            objectUrl = getLegacyObjectUrl({
+                descriptor
+            });
+        }
         return {
             url: objectUrl,
             mediaType: fileType,
@@ -393,7 +494,18 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         return Array.from(e.dataTransfer?.types ?? []).includes('Files');
     }
     async function handleSend(text) {
+        if (sendingRef.current) return;
         if (!text.trim() && attachedFiles.length === 0) return;
+        sendingRef.current = true;
+        setSending(true);
+        try {
+            await submitMessage(text);
+        } finally{
+            sendingRef.current = false;
+            setSending(false);
+        }
+    }
+    async function submitMessage(text) {
         const filesMeta = attachedFiles.map((file)=>({
                 name: file.name,
                 size: file.size,
@@ -417,9 +529,9 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
                     text
                 }
             ];
-            if (attachmentsConfig?.s3PostPolicyRequestId) {
+            if (uploadPolicyRequestId) {
                 try {
-                    const uploadResults = await Promise.all(attachedFiles.map((file)=>uploadFileToS3(file)));
+                    const uploadResults = await Promise.all(attachedFiles.map((file)=>uploadFileToStorage(file)));
                     for (const result of uploadResults){
                         parts.push({
                             type: 'file',
@@ -432,7 +544,7 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
                     methods.triggerEvent({
                         name: 'onError',
                         event: {
-                            message: error.message ?? 'File upload to S3 failed.'
+                            message: error.message ?? 'File upload failed.'
                         }
                     });
                     return;
@@ -443,16 +555,21 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
                     parts.push(part);
                 }
             }
-            sendMessage({
+            deliver({
                 parts
             });
             setAttachedFiles([]);
         } else {
-            sendMessage({
+            deliver({
                 text
             });
         }
-        senderRef.current?.clear();
+        // Empty the composer here, after the sends and downstream of both the
+        // onBeforeSend cancellation return and the upload await, so a send that was
+        // rejected or failed to upload leaves the user's text in the box. Resetting
+        // from the Sender's onSubmit handler instead would silently lose typed input
+        // on every rejected send.
+        setInputValue('');
     }
     function handleStop() {
         stop();
@@ -464,18 +581,26 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         });
     }
     function handlePromptClick(prompt) {
-        sendMessage({
+        if (sendingRef.current) return;
+        deliver({
             text: prompt.label
         });
     }
+    // A two-track welcome starter fills the composer instead of sending, so a
+    // generic shipped default is an editable first draft rather than a message the
+    // user never meant to send. Reuses the controlled Sender value.
+    function handleWelcomePromptFill(text) {
+        setInputValue(typeof text === 'string' ? text : '');
+    }
     function handleSuggestionClick(suggestion) {
+        if (sendingRef.current) return;
         methods.triggerEvent({
             name: 'onSuggestionClick',
             event: {
                 suggestion
             }
         });
-        sendMessage({
+        deliver({
             text: suggestion.label
         });
     }
@@ -505,6 +630,8 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         messages
     ]);
     const activeSuggestions = agentSuggestions ?? suggestions;
+    // Hidden while a composer send awaits onBeforeSend as well as while a reply streams.
+    const showSuggestions = !isEmpty && !isLoading && (activeSuggestions?.length ?? 0) > 0 && !isBusy && !sending;
     // A link in an answer was a plain anchor: a full browser navigation out of the
     // conversation, with no way for an app to do anything else with it. Default is only
     // prevented when the app actually handles onLinkClick — otherwise the link keeps
@@ -551,6 +678,7 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         });
     }
     function handleRegenerate({ messageId }) {
+        if (sendingRef.current) return;
         methods.triggerEvent({
             name: 'onRegenerate',
             event: {
@@ -558,11 +686,10 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
                 messages
             }
         });
-        regenerate({
-            messageId
-        });
+        regenerateReply(messageId);
     }
     function handleEditMessage({ messageId, originalContent, newContent }) {
+        if (sendingRef.current) return;
         methods.triggerEvent({
             name: 'onEditMessage',
             event: {
@@ -575,7 +702,7 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         const messageIndex = messages.findIndex((m)=>m.id === messageId);
         if (messageIndex >= 0) {
             setMessages((prev)=>prev.slice(0, messageIndex));
-            sendMessage({
+            deliver({
                 text: newContent
             });
         }
@@ -609,7 +736,36 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
             minHeight: 0,
             padding: '16px 0'
         }
-    }, isEmpty ? /*#__PURE__*/ React.createElement(WelcomeScreen, {
+    }, isLoading ? /*#__PURE__*/ React.createElement("div", {
+        className: "agent-chat-loading",
+        style: {
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 24,
+            padding: '0 16px'
+        }
+    }, /*#__PURE__*/ React.createElement(Skeleton, {
+        active: true,
+        title: false,
+        paragraph: {
+            rows: 2,
+            width: [
+                '60%',
+                '40%'
+            ]
+        }
+    }), /*#__PURE__*/ React.createElement(Skeleton, {
+        active: true,
+        title: false,
+        paragraph: {
+            rows: 3,
+            width: [
+                '90%',
+                '75%',
+                '50%'
+            ]
+        }
+    })) : isEmpty && !welcome?.tracks ? /*#__PURE__*/ React.createElement(WelcomeScreen, {
         config: welcome,
         onPromptClick: handlePromptClick
     }) : /*#__PURE__*/ React.createElement(MessageList, {
@@ -617,6 +773,8 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         messages: messages,
         isStreaming: isBusy,
         config: messageDisplay,
+        welcome: welcome,
+        onWelcomePromptFill: handleWelcomePromptFill,
         addToolApprovalResponse: addToolApprovalResponse,
         onFeedback: handleFeedback,
         onLinkClick: handleLinkClick,
@@ -626,7 +784,7 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         onDelete: handleDelete,
         onEditMessage: handleEditMessage,
         translate: methods.translate
-    })), !isEmpty && activeSuggestions && activeSuggestions.length > 0 && !isBusy && /*#__PURE__*/ React.createElement("div", {
+    })), showSuggestions && /*#__PURE__*/ React.createElement("div", {
         style: {
             padding: '0 16px 8px'
         }
@@ -699,6 +857,8 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         }
     }), /*#__PURE__*/ React.createElement(Sender, {
         ref: senderRef,
+        value: inputValue,
+        onChange: setInputValue,
         placeholder: sender?.placeholder ?? methods.translate('agent.sender.placeholder'),
         submitType: sender?.submitType ?? 'enter',
         allowSpeech: sender?.allowSpeech ?? false,
@@ -708,8 +868,12 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
         onPasteFile: attachmentsConfig?.enabled ? (files)=>addFiles(files, {
                 pasted: true
             }) : undefined,
-        onCancel: handleStop,
-        loading: isBusy,
+        // Not during the onBeforeSend wait: nothing is streaming, so onStop would be false.
+        onCancel: isBusy ? handleStop : undefined,
+        loading: isBusy || sending,
+        disabled: isLoading,
+        styles: sender?.styles,
+        classNames: sender?.classNames,
         prefix: attachmentsConfig?.enabled ? /*#__PURE__*/ React.createElement(Button, {
             type: "text",
             icon: /*#__PURE__*/ React.createElement(PaperClipOutlined, null),
@@ -741,7 +905,6 @@ function AgentChat({ blockId, components: { Icon, Link }, events, methods, pageI
 }
 AgentChat.meta = {
     category: 'display',
-    icons: [],
-    styles: []
+    icons: []
 };
 export default AgentChat;

package/dist/blocks/AgentChat/LowdefyChatTransport.js

@@ -14,7 +14,9 @@
   limitations under the License.
 */ import { DefaultChatTransport } from 'ai';
 function createLowdefyChatTransport({ pageId, agentId, conversationId, urlQuery, sharedStateRef }) {
-    const base = `/api/agent/${pageId}/${agentId}`;
+    // The server route takes the last path segment as the agentId — module-scoped
+    // agent ids contain '/', so encode the agentId into a single segment.
+    const base = `/api/agent/${pageId}/${encodeURIComponent(agentId)}`;
     const api = conversationId ? `${base}?conversationId=${encodeURIComponent(conversationId)}` : base;
     return new DefaultChatTransport({
         api,

package/dist/blocks/AgentChat/MessageList.js

@@ -21,6 +21,7 @@ import { hasVisibleContent } from './messageParts.js';
 import MessageBubble from './MessageBubble.js';
 import ThinkingIndicator from './ThinkingIndicator.js';
 import useThinkingMessage from './useThinkingMessage.js';
+import WelcomeScreen from './WelcomeScreen.js';
 function roleAvatar(roleConfig, fallbackIcon) {
     if (roleConfig?.avatar) {
         return /*#__PURE__*/ React.createElement(Avatar, {
@@ -55,7 +56,7 @@ function ThinkingBubbleContent({ bubbleId, config }) {
         label: label
     });
 }
-const MessageList = /*#__PURE__*/ React.forwardRef(function MessageList({ messages, isStreaming, config, addToolApprovalResponse, onFeedback, onLinkClick, Link, feedbackValues, onRegenerate, onDelete, onEditMessage, translate }, ref) {
+const MessageList = /*#__PURE__*/ React.forwardRef(function MessageList({ messages, isStreaming, config, welcome, onWelcomePromptFill, addToolApprovalResponse, onFeedback, onLinkClick, Link, feedbackValues, onRegenerate, onDelete, onEditMessage, translate }, ref) {
     // Build a lookup map for message parts.
     // Bubble.List's contentRender callback only receives (content, info) where info.key is the
     // item key — it does not receive the full message object with its parts array. This map
@@ -119,14 +120,42 @@ const MessageList = /*#__PURE__*/ React.forwardRef(function MessageList({ messag
             streaming: true
         });
     }
+    // The welcome renders as a leading item so it scrolls up with the transcript
+    // and stays reachable by scrolling back, rather than being swapped out on the
+    // first send. With no messages yet it is simply the only item in the list.
+    if (welcome?.tracks) {
+        items.unshift({
+            key: '__welcome__',
+            role: 'welcome'
+        });
+    }
     return /*#__PURE__*/ React.createElement(Bubble.List, {
         ref: ref,
         items: items,
         role: {
+            welcome: {
+                placement: 'start',
+                variant: 'borderless',
+                style: {
+                    maxWidth: '100%'
+                },
+                styles: {
+                    content: {
+                        width: '100%'
+                    }
+                },
+                contentRender: ()=>/*#__PURE__*/ React.createElement(WelcomeScreen, {
+                        config: welcome,
+                        onFill: onWelcomePromptFill,
+                        inFlow: true
+                    })
+            },
             user: {
                 placement: 'end',
                 variant: config?.roles?.user?.variant ?? 'filled',
                 shape: config?.roles?.user?.shape ?? 'round',
+                styles: config?.roles?.user?.styles,
+                classNames: config?.roles?.user?.classNames,
                 avatar: roleAvatar(config?.roles?.user, /*#__PURE__*/ React.createElement(UserOutlined, null)),
                 header: roleHeader(config?.roles?.user, 'agent.message.userHeader', translate),
                 editable: config?.editableMessages !== false ? {
@@ -173,6 +202,8 @@ const MessageList = /*#__PURE__*/ React.forwardRef(function MessageList({ messag
                 style: {
                     maxWidth: '100%'
                 },
+                styles: config?.roles?.assistant?.styles,
+                classNames: config?.roles?.assistant?.classNames,
                 avatar: roleAvatar(config?.roles?.assistant, /*#__PURE__*/ React.createElement(RobotOutlined, null)),
                 header: roleHeader(config?.roles?.assistant, 'agent.message.assistantHeader', translate),
                 typing: config?.roles?.assistant?.typing ? config.roles.assistant.typing : {

package/dist/blocks/AgentChat/WelcomeScreen.js

@@ -14,8 +14,95 @@
   limitations under the License.
 */ import React from 'react';
 import { Welcome, Prompts } from '@ant-design/x';
-function WelcomeScreen({ config, onPromptClick }) {
+import { Button } from 'antd';
+// One track: a bordered card holding a heading and a column of starter chips.
+// A chip fills the composer (onFill) rather than sending — a near-miss starter
+// becomes an editable first draft, not a message the user never meant to send.
+function TrackCard({ track, onFill }) {
+    const prompts = track.prompts ?? [];
+    return /*#__PURE__*/ React.createElement("div", {
+        style: {
+            flex: '1 1 240px',
+            border: '1px solid var(--ant-color-border)',
+            borderRadius: 'var(--ant-border-radius-lg)',
+            padding: 16,
+            backgroundColor: 'var(--ant-color-bg-container)',
+            display: 'flex',
+            flexDirection: 'column',
+            gap: 8
+        }
+    }, track.label && /*#__PURE__*/ React.createElement("h5", {
+        style: {
+            margin: '0 0 4px',
+            fontSize: 'var(--ant-font-size-heading-5)',
+            fontWeight: 'var(--ant-font-weight-strong, 600)',
+            lineHeight: 'var(--ant-line-height-heading-5)'
+        }
+    }, track.label), prompts.map((prompt, index)=>{
+        const text = typeof prompt === 'string' ? prompt : prompt.label;
+        return /*#__PURE__*/ React.createElement(Button, {
+            key: index,
+            block: true,
+            // antd buttons are nowrap and size to their longest line; height auto
+            // plus whiteSpace normal lets a sentence-length starter wrap left.
+            style: {
+                height: 'auto',
+                whiteSpace: 'normal',
+                textAlign: 'left',
+                paddingTop: 6,
+                paddingBottom: 6
+            },
+            onClick: ()=>onFill?.(text)
+        }, text);
+    }));
+}
+// The chat empty state. Two modes:
+//   - `config.tracks` present → a two-track teaching panel (ask a question /
+//     build a report), each track a card of fill-the-composer starters. When
+//     `inFlow` it renders top-aligned as a leading item inside the message
+//     scroll area, so it scrolls up with the conversation and stays reachable
+//     by scrolling back rather than being swapped out on the first send.
+//   - otherwise → the flat Welcome + Prompts row, centred, sending on click.
+function WelcomeScreen({ config, onPromptClick, onFill, inFlow }) {
     if (!config) return null;
+    if (config.tracks) {
+        return /*#__PURE__*/ React.createElement("div", {
+            style: inFlow ? {
+                display: 'flex',
+                flexDirection: 'column',
+                gap: 16,
+                width: '100%'
+            } : {
+                flex: 1,
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'center',
+                justifyContent: 'center',
+                gap: 16
+            }
+        }, config.title && /*#__PURE__*/ React.createElement("h3", {
+            style: {
+                margin: 0,
+                fontSize: 'var(--ant-font-size-heading-3)',
+                fontWeight: 'var(--ant-font-weight-strong, 600)',
+                lineHeight: 'var(--ant-line-height-heading-3)'
+            }
+        }, config.title), config.description && /*#__PURE__*/ React.createElement("div", {
+            style: {
+                color: 'var(--ant-color-text-secondary)'
+            }
+        }, config.description), /*#__PURE__*/ React.createElement("div", {
+            style: {
+                display: 'flex',
+                gap: 12,
+                flexWrap: 'wrap'
+            }
+        }, config.tracks.map((track, index)=>/*#__PURE__*/ React.createElement(TrackCard, {
+                key: index,
+                track: track,
+                onFill: onFill
+            }))));
+    }
     const promptItems = (config.prompts ?? []).map((prompt, index)=>({
             key: prompt.key ?? `prompt-${index}`,
             label: prompt.label,

package/dist/blocks/AgentChat/replayableMessages.js

@@ -0,0 +1,60 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+// A reply cut off mid-stream leaves its tool call with no result, and UIMessage validation
+// rejects the whole history for one such part: every later send fails, and a history stored
+// that way fails on every load. Approval states stay; a pending approval is answerable on resume.
+// A client-side tool the block is still running is in the same state, so its call id is in
+// liveToolCallIds and the part is kept: its output is on the way.
+const UNANSWERED = new Set([
+    'input-streaming',
+    'input-available'
+]);
+function isDeadToolPart({ part, liveToolCallIds }) {
+    const partType = part?.type;
+    const isTool = partType === 'dynamic-tool' || type.isString(partType) && partType.startsWith('tool-');
+    return isTool && UNANSWERED.has(part.state) && !liveToolCallIds.has(part.toolCallId);
+}
+function replayableMessages({ messages, liveToolCallIds = new Set() }) {
+    const list = messages ?? [];
+    let changed = false;
+    const result = [];
+    for (const message of list){
+        if (!type.isArray(message?.parts)) {
+            result.push(message);
+            continue;
+        }
+        const parts = message.parts.filter((part)=>!isDeadToolPart({
+                part,
+                liveToolCallIds
+            }));
+        // Only a step marker left is the empty shell onError already drops.
+        if (!parts.some((part)=>part?.type !== 'step-start')) {
+            changed = true;
+            continue;
+        }
+        if (parts.length === message.parts.length) {
+            result.push(message);
+            continue;
+        }
+        changed = true;
+        result.push({
+            ...message,
+            parts
+        });
+    }
+    return changed ? result : list;
+}
+export default replayableMessages;

package/dist/blocks/AgentChat/schema.json

@@ -137,6 +137,14 @@
                 "shape": {
                   "type": "string",
                   "enum": ["default", "round", "corner"]
+                },
+                "styles": {
+                  "type": "object",
+                  "description": "Inline styles per bubble part: root, content, body, header, footer, avatar, extra. The way to recolour a bubble: the filled and outlined colours come from the theme's colorPrimary and are not reachable from a stylesheet."
+                },
+                "classNames": {
+                  "type": "object",
+                  "description": "Class names per bubble part, same keys as styles."
                 }
               }
             },
@@ -152,6 +160,14 @@
                 "shape": {
                   "type": "string",
                   "enum": ["default", "round", "corner"]
+                },
+                "styles": {
+                  "type": "object",
+                  "description": "Inline styles per bubble part: root, content, body, header, footer, avatar, extra."
+                },
+                "classNames": {
+                  "type": "object",
+                  "description": "Class names per bubble part, same keys as styles."
                 }
               }
             }
@@ -188,6 +204,14 @@
           "default": "enter"
         },
         "allowSpeech": { "type": "boolean", "default": false },
+        "styles": {
+          "type": "object",
+          "description": "Inline styles per composer part: root, prefix, input, suffix, footer, switch, content. The way to recolour the composer border, which the theme sets with a precedence no page stylesheet beats."
+        },
+        "classNames": {
+          "type": "object",
+          "description": "Class names per composer part, same keys as styles."
+        },
         "attachments": {
           "type": "object",
           "description": "File attachments on the composer. When enabled, files can be picked with the paperclip, pasted from the clipboard (e.g. a screenshot) or dragged onto the composer; accept and maxSize apply to all three.",
@@ -201,9 +225,17 @@
               "type": "number",
               "description": "Maximum file size in bytes. Larger files are silently skipped."
             },
+            "uploadPolicyRequestId": {
+              "type": "string",
+              "description": "Id of an upload-policy request (e.g. AwsS3PresignedPostPolicy, GcsSignedPostPolicy, AzureBlobUploadSas). When set, files are uploaded to storage and their URLs are sent to the LLM instead of base64 data."
+            },
+            "downloadPolicyRequestId": {
+              "type": "string",
+              "description": "Id of a download request used to resolve the URL of an uploaded attachment. The URL is fetched by the model provider, so it should remain reachable — use public: true on the request for public buckets, or a long expiry. When unset, a legacy unsigned object URL is constructed from the upload response (S3-shaped, deprecated)."
+            },
             "s3PostPolicyRequestId": {
               "type": "string",
-              "description": "Request ID of type AwsS3PresignedPostPolicy. When set, files are uploaded to S3 and their URLs are sent to the LLM instead of base64 data."
+              "description": "Deprecated — use uploadPolicyRequestId instead."
             }
           }
         },
@@ -235,6 +267,11 @@
         "title": { "type": "string" }
       }
     },
+    "loading": {
+      "type": "boolean",
+      "default": false,
+      "description": "The app is still loading this conversation's transcript. While true, a skeleton replaces the message area, suggestions are hidden and the composer is disabled, so nothing can be sent into a conversation whose messages have not synced yet."
+    },
     "suggestions": {
       "type": "array",
       "items": {

package/dist/blocks/AgentChat/tests/AgentChat.e2e.yaml

@@ -0,0 +1,339 @@
+# Copyright 2020-2026 Lowdefy, Inc
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+id: agent-chat
+type: PageHeaderMenu
+properties:
+  title: AgentChat
+blocks:
+  # Both chats are driven from the messages property, so nothing here calls the agent.
+  - id: chat_wired
+    type: AgentChat
+    properties:
+      agentId: test_agent
+      height: 300
+      conversationId: wired
+      messageDisplay:
+        actions:
+          - feedback
+      messages:
+        - id: w1
+          role: assistant
+          parts:
+            - type: text
+              text: |
+                [in-app link](/agent-chat-target) and [external link](https://example.com)
+                and [**bold** link](/agent-chat-target?tab=two)
+    events:
+      onFeedback:
+        - id: record_rating
+          type: SetState
+          params:
+            last_rating:
+              _event: rating
+      onLinkClick:
+        - id: record_link_click
+          type: SetState
+          params:
+            last_href:
+              _event: href
+            last_text:
+              _event: text
+            click_count:
+              _sum:
+                - _if_none:
+                    - _state: click_count
+                    - 0
+                - 1
+
+  # Seeded from feedbackValues rather than from a click: what a reload or a conversation
+  # switch looks like to an app that stored the rating itself.
+  - id: chat_seeded
+    type: AgentChat
+    properties:
+      agentId: test_agent
+      height: 300
+      conversationId: seeded
+      messageDisplay:
+        actions:
+          - feedback
+      feedbackValues:
+        s1: like
+      messages:
+        - id: s1
+          role: assistant
+          parts:
+            - type: text
+              text: A rated answer.
+    events:
+      onFeedback:
+        - id: record_seeded_rating
+          type: SetState
+          params:
+            seeded_rating:
+              _event: rating
+
+  - id: wired_readout
+    type: Html
+    properties:
+      html:
+        _nunjucks:
+          template: |
+            <span id="readout_href">{{ href }}</span>
+            <span id="readout_text">{{ text }}</span>
+            <span id="readout_count">{{ count or 0 }}</span>
+            <span id="readout_rating">{{ rating }}</span>
+            <span id="readout_seeded_rating">{{ seeded_rating }}</span>
+          on:
+            href:
+              _state: last_href
+            text:
+              _state: last_text
+            count:
+              _state: click_count
+            rating:
+              _state: last_rating
+            seeded_rating:
+              _state: seeded_rating
+
+  - id: chat_unwired
+    type: AgentChat
+    properties:
+      agentId: test_agent
+      height: 300
+      conversationId: unwired
+      messages:
+        - id: u1
+          role: assistant
+          parts:
+            - type: text
+              text: '[in-app link](/agent-chat-target) and [external link](https://example.com)'
+
+  # A history stored after a reply was cut off mid-stream: c2's tool call never got its result,
+  # c3 is nothing but that, and c4 is a call that completed and must be left alone.
+  - id: chat_cutoff
+    type: AgentChat
+    properties:
+      agentId: test_agent
+      height: 300
+      conversationId: cutoff
+      messages:
+        - id: c1
+          role: user
+          parts:
+            - type: text
+              text: What is in this repo?
+        - id: c2
+          role: assistant
+          parts:
+            - type: step-start
+            - type: text
+              text: Let me look.
+            - type: tool-search
+              toolCallId: tc1
+              state: input-available
+              input: {}
+        - id: c3
+          role: assistant
+          parts:
+            - type: step-start
+            - type: tool-fetch
+              toolCallId: tc2
+              state: input-available
+              input: {}
+        - id: c4
+          role: assistant
+          parts:
+            - type: tool-lookup
+              toolCallId: tc3
+              state: output-available
+              input: {}
+              output:
+                ok: true
+            - type: text
+              text: Done looking.
+
+  # onBeforeSend that takes as long as a quota request might, counts how often it ran, then
+  # refuses the send so nothing ever calls the agent.
+  - id: chat_guarded
+    type: AgentChat
+    properties:
+      agentId: test_agent
+      height: 300
+      conversationId: guarded
+      messages:
+        - id: g1
+          role: assistant
+          parts:
+            - type: text
+              text: Ask me something.
+    events:
+      onBeforeSend:
+        - id: count_before_send
+          type: SetState
+          params:
+            before_send_count:
+              _sum:
+                - _if_none:
+                    - _state: before_send_count
+                    - 0
+                - 1
+        - id: slow_check
+          type: Wait
+          params:
+            ms: 1500
+        - id: refuse
+          type: Throw
+          params:
+            throw: true
+            message: Refused by the test.
+
+  - id: guarded_readout
+    type: Html
+    properties:
+      html:
+        _nunjucks:
+          template: '<span id="readout_before_send">{{ n or 0 }}</span>'
+          on:
+            n:
+              _state: before_send_count
+
+  - id: chat_styled
+    type: AgentChat
+    properties:
+      agentId: test_agent
+      height: 300
+      conversationId: styled
+      messageDisplay:
+        roles:
+          assistant:
+            styles:
+              content:
+                backgroundColor: 'rgb(1, 2, 3)'
+          user:
+            classNames:
+              content: styled-user-content
+      sender:
+        styles:
+          root:
+            borderColor: 'rgb(4, 5, 6)'
+      messages:
+        - id: y1
+          role: user
+          parts:
+            - type: text
+              text: Styled question
+        - id: y2
+          role: assistant
+          parts:
+            - type: text
+              text: Styled answer
+
+  # Two conversations with the SAME message count and the same last id (''), the shape
+  # every persisted transcript had before assistant messages were given ids. Switching
+  # between them has to re-sync the transcript from `messages`.
+  - id: switch_to_a
+    type: Button
+    properties:
+      title: Switch to A
+    events:
+      onClick:
+        - id: set_a
+          type: SetState
+          params:
+            switch_id: conv-a
+  - id: switch_to_b
+    type: Button
+    properties:
+      title: Switch to B
+    events:
+      onClick:
+        - id: set_b
+          type: SetState
+          params:
+            switch_id: conv-b
+  - id: chat_switch
+    type: AgentChat
+    properties:
+      agentId: test_agent
+      height: 300
+      conversationId:
+        _if_none:
+          - _state: switch_id
+          - conv-a
+      messages:
+        _if:
+          test:
+            _eq:
+              - _if_none:
+                  - _state: switch_id
+                  - conv-a
+              - conv-b
+          then:
+            - id: b-user
+              role: user
+              parts:
+                - type: text
+                  text: Question in B
+            - id: ''
+              role: assistant
+              parts:
+                - type: text
+                  text: Answer from conversation B.
+          else:
+            - id: a-user
+              role: user
+              parts:
+                - type: text
+                  text: Question in A
+            - id: ''
+              role: assistant
+              parts:
+                - type: text
+                  text: Answer from conversation A.
+
+  # The loading property: a skeleton in place of the transcript, composer disabled.
+  - id: toggle_loading
+    type: Button
+    properties:
+      title: Toggle loading
+    events:
+      onClick:
+        - id: flip_loading
+          type: SetState
+          params:
+            chat_loading:
+              _not:
+                _eq:
+                  - _state: chat_loading
+                  - true
+  - id: chat_loading
+    type: AgentChat
+    properties:
+      agentId: test_agent
+      height: 300
+      conversationId: loading
+      loading:
+        _eq:
+          - _state: chat_loading
+          - true
+      suggestions:
+        - key: s
+          label: A suggestion
+      messages:
+        - id: l1
+          role: assistant
+          parts:
+            - type: text
+              text: Loaded answer.

package/dist/blocks/AgentChat/tests/AgentChatTarget.e2e.yaml

@@ -0,0 +1,25 @@
+# Copyright 2020-2026 Lowdefy, Inc
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+
+#     http://www.apache.org/licenses/LICENSE-2.0
+
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+id: agent-chat-target
+type: PageHeaderMenu
+properties:
+  title: Link target
+blocks:
+  - id: target_marker
+    type: Html
+    properties:
+      # No id on the span: Lowdefy renders the block id into the DOM, so repeating it here
+      # gives two matching elements and a strict-mode violation.
+      html: <span>arrived</span>

package/dist/blocks/AgentConversations/AgentConversations.js

@@ -82,9 +82,6 @@ function AgentConversations({ blockId, methods, properties }) {
 }
 AgentConversations.meta = {
     category: 'display',
-    icons: [],
-    styles: [
-        'blocks/AgentConversations/style.less'
-    ]
+    icons: []
 };
 export default AgentConversations;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/blocks-antd-x",
-  "version": "5.6.0",
+  "version": "6.1.0",
   "license": "Apache-2.0",
   "description": "Lowdefy Ant Design X Blocks",
   "homepage": "https://lowdefy.com",
@@ -41,17 +41,19 @@
     "@ant-design/icons": "6.1.0",
     "@ant-design/x": "2.7.0",
     "@ant-design/x-markdown": "2.7.0",
-    "@lowdefy/block-utils": "5.6.0",
-    "@lowdefy/helpers": "5.6.0",
+    "@lowdefy/block-utils": "6.1.0",
+    "@lowdefy/blocks-files": "6.1.0",
+    "@lowdefy/helpers": "6.1.0",
     "ai": "6.0.176"
   },
   "devDependencies": {
-    "@lowdefy/block-dev-e2e": "5.6.0",
-    "@lowdefy/e2e-utils": "5.6.0",
-    "@playwright/test": "1.50.1",
-    "@swc/cli": "0.8.0",
-    "@swc/core": "1.15.18",
-    "copyfiles": "2.4.1"
+    "@lowdefy/block-dev-e2e": "6.1.0",
+    "@lowdefy/e2e-utils": "6.1.0",
+    "@playwright/test": "1.59.1",
+    "@swc/cli": "0.8.1",
+    "@swc/core": "1.15.32",
+    "copyfiles": "2.4.1",
+    "react-dom": "18.2.0"
   },
   "peerDependencies": {
     "antd": "6.3.1",
@@ -63,7 +65,7 @@
   "scripts": {
     "build": "swc src --out-dir dist --config-file ../../../../.swcrc --cli-config-file ../../../../.swc-cli.json && pnpm copyfiles",
     "clean": "rm -rf dist",
-    "copyfiles": "copyfiles -u 1 \"./src/**/*\" dist -e \"./src/**/*.js\" -e \"./src/**/*.yaml\" -e \"./src/**/*.snap\"",
+    "copyfiles": "copyfiles -u 1 \"./src/**/*\" dist -e \"./src/**/*.js\" -e \"./src/**/*.snap\"",
     "e2e": "playwright test --config e2e/playwright.config.js",
     "e2e:ui": "playwright test --config e2e/playwright.config.js --ui"
   }

package/dist/blocks/AgentConversations/style.less

@@ -1 +0,0 @@
-// AgentConversations styles — currently uses inline styles and Ant Design X defaults.