@datalayer/agent-runtimes 1.3.28 → 1.3.30

package/lib/AgentNode.js

@@ -345,7 +345,8 @@ export function AgentNode() {
     ]);
     const [inferenceProvider, setInferenceProvider] = useState('datalayer');
     const [inferenceModels, setInferenceModels] = useState([]);
-    const [inferenceDefaultModel, setInferenceDefaultModel] = useState(null);
+    // The runtime's sentence about its models, or why it gave none.
+    const [inferenceModelsNote, setInferenceModelsNote] = useState(null);
     const [configurationLoaded, setConfigurationLoaded] = useState(false);
     const [isActiveAgentRunning, setIsActiveAgentRunning] = useState(false);
     // The protocol the active agent actually speaks, as reported by the node.
@@ -712,49 +713,26 @@ export function AgentNode() {
     useEffect(() => {
         if (inferenceProvider !== 'datalayer') {
             setInferenceModels([]);
-            setInferenceDefaultModel(null);
+            setInferenceModelsNote(null);
             return;
         }
+        // The runtime's answer, as it had it from ai-inference: no list of its
+        // own when that answer is empty or did not come — the sentence says why.
         const loadInferenceModels = async () => {
             try {
                 const response = await fetch(`${AGENT_RUNTIMES_BASE_URL}/api/v1/configure/inference/models`);
                 if (!response.ok) {
                     setInferenceModels([]);
-                    setInferenceDefaultModel(null);
+                    setInferenceModelsNote(`The runtime did not list its models (${response.status}).`);
                     return;
                 }
                 const payload = await response.json();
-                const fromModels = Array.isArray(payload.models)
-                    ? payload.models.filter(Boolean)
-                    : [];
-                const fromBedrock = Array.isArray(payload.bedrock_anthropic_models)
-                    ? payload.bedrock_anthropic_models.filter(Boolean)
-                    : [];
-                const fallback = [
-                    'bedrock/us.anthropic.claude-3-5-sonnet-20240620-v1:0',
-                    'bedrock/us.anthropic.claude-3-7-sonnet-20250219-v1:0',
-                    'bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0',
-                ];
-                const models = fromModels.length > 0
-                    ? fromModels
-                    : fromBedrock.length > 0
-                        ? fromBedrock
-                        : fallback;
-                setInferenceModels(models);
-                const specDefault = Array.isArray(payload.bedrock_anthropic_model_specs)
-                    ? payload.bedrock_anthropic_model_specs.find(s => s?.default)?.id
-                    : undefined;
-                const selected = (specDefault && models.includes(specDefault) ? specDefault : null) ||
-                    (payload.default_model && models.includes(payload.default_model)
-                        ? payload.default_model
-                        : null) ||
-                    models[0] ||
-                    null;
-                setInferenceDefaultModel(selected);
+                setInferenceModels(Array.isArray(payload.models) ? payload.models.filter(Boolean) : []);
+                setInferenceModelsNote(payload.note ?? null);
             }
-            catch {
+            catch (error) {
                 setInferenceModels([]);
-                setInferenceDefaultModel(null);
+                setInferenceModelsNote(`The runtime did not list its models (${String(error)}).`);
             }
         };
         loadInferenceModels();
@@ -1280,7 +1258,10 @@ export function AgentNode() {
                                                                     display: 'flex',
                                                                     flexDirection: 'column',
                                                                     gap: 1,
-                                                                }, children: [_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Bedrock Anthropic model" }), inferenceModels.length === 0 ? (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "No model list available." })) : (_jsxs(ActionMenu, { children: [_jsx(ActionMenu.Button, { children: inferenceDefaultModel || inferenceModels[0] }), _jsx(ActionMenu.Overlay, { width: "large", children: _jsx(ActionList, { selectionVariant: "single", children: inferenceModels.map(model => (_jsx(ActionList.Item, { selected: inferenceDefaultModel === model, inactiveText: "Selection is locked", children: model }, model))) }) })] }))] }))] }), iamUser ? (_jsxs(Box, { sx: {
+                                                                }, children: [_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Models ai-inference serves" }), inferenceModels.length === 0 ? (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: inferenceModelsNote ??
+                                                                            'The runtime has not said which models ai-inference serves.' })) : (_jsxs(ActionMenu, { children: [_jsx(ActionMenu.Button, { children: inferenceModels.length === 1
+                                                                                    ? inferenceModels[0]
+                                                                                    : `${inferenceModels.length} models` }), _jsx(ActionMenu.Overlay, { width: "large", children: _jsx(ActionList, { children: inferenceModels.map(model => (_jsx(ActionList.Item, { inactiveText: "Selection is locked", children: model }, model))) }) })] }))] }))] }), iamUser ? (_jsxs(Box, { sx: {
                                                             border: '1px solid',
                                                             borderColor: 'border.default',
                                                             borderRadius: 2,

package/lib/chat/ChatFloating.d.ts

@@ -12,6 +12,8 @@
  * @module chat/ChatFloating
  */
 import React from 'react';
+import { type AssistantCharacter } from './assistant/characters';
+import type { AssistantCharacterData } from './assistant/formats/types';
 import type { ChatCommonProps, ChatViewMode } from '../types';
 /**
  * ChatFloating props — extends ChatCommonProps with floating/popup-specific configuration.
@@ -67,10 +69,18 @@ export interface ChatFloatingProps extends ChatCommonProps {
      * - 'floating': Full-height floating panel (pinned to right edge with offset)
      * - 'floating-small': Standard floating popup
      * - 'floating-draggable': The popup with a handle, movable about the viewport
+     * - 'assistant': A character on the page that speaks in a balloon (LOOP T-21)
      * - 'panel': Full-height side panel (right edge, no floating offset)
      * @default 'floating'
      */
-    defaultViewMode?: 'floating' | 'floating-small' | 'floating-draggable' | 'panel';
+    defaultViewMode?: 'floating' | 'floating-small' | 'floating-draggable' | 'assistant' | 'panel';
+    /**
+     * The character of the floating assistant: one Datalayer ships, by id
+     * (`ASSISTANT_CHARACTERS`, LOOP T-25), or one a person loaded from a file
+     * they hold the rights to (`readClippyCharacter`, `readAcsCharacter`, T-26).
+     * @default 'paperclip'
+     */
+    assistantCharacter?: string | AssistantCharacter | AssistantCharacterData;
     /**
      * Callback when the user switches view mode via the header toggle.
      * The parent component receives the new ChatViewMode value.
@@ -99,5 +109,5 @@ export interface ChatFloatingProps extends ChatCommonProps {
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, buttonGlow, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, }: ChatFloatingProps): React.JSX.Element;
+export declare function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose, escapeToClose, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip, brandColor, buttonGlow, offset, animationDuration, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, defaultViewMode, onViewModeChange, sidebarMountPoint, showPanelBackdrop, availableModels, showModelSelector, showToolsMenu, showSkillsMenu, showTokenUsage, showContextRing, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching, launchingMessage, assistantCharacter, }: ChatFloatingProps): React.JSX.Element;
 export default ChatFloating;

package/lib/chat/ChatFloating.js

@@ -26,6 +26,11 @@ import { ChatBase } from './base/ChatBase';
 import { ButtonGlow } from './display/ButtonGlow';
 import { useViewportDrag } from './useViewportDrag';
 import { disabledChatViewModes, resolveMountPoint } from './viewModes';
+import { AssistantStage } from './assistant/AssistantStage';
+import { SpeechBalloon } from './assistant/SpeechBalloon';
+import { DEFAULT_ASSISTANT_CHARACTER, } from './assistant/characters';
+import { assistantStateOf, latestSaying, newestIsAnswer, keepAway, keptAway, } from './assistant/state';
+import { presenceState, presenceToolOf, } from './presence/presenceStatus';
 import { useChatOpen, useChatMessages, useChatStore, } from '../stores/chatStore';
 import { useChatKeyboardShortcuts, getShortcutDisplay, } from '@datalayer/core/lib/hooks';
 /**
@@ -47,7 +52,7 @@ function useIsMobile(breakpoint = 640) {
  * ChatFloating component
  * A floating chat window built on ChatBase
  */
-export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, buttonGlow = true, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, }) {
+export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useStoreMode = true, title = 'Chat', description = 'Start a conversation with the AI agent.', position = 'bottom-right', defaultOpen = false, width = 400, height = 550, showHeader = true, showButton = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = '/', showPoweredBy = true, promptVariant, mentionableAgents, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, buttonGlow = true, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, sidebarMountPoint = null, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, showContextRing = false, themeVariant, colorMode, runtimeId, historyEndpoint, authToken, historyAuthToken, pendingPrompt, showInformation = false, onInformationClick, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, launching = false, launchingMessage, assistantCharacter = DEFAULT_ASSISTANT_CHARACTER, }) {
     // Store-based state
     const storeIsOpen = useChatOpen();
     const storeMessages = useChatMessages();
@@ -96,6 +101,88 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             resetDrag();
         }
     }, [viewMode, resetDrag]);
+    /*
+     * The floating assistant (LOOP T-21, T-22, T-27): a character that acts out
+     * the presence of what answers — read here from the chat's own loading and
+     * items — greets when it arrives, says goodbye when sent away, and is
+     * dragged about by itself, the conversation following it.
+     */
+    const ASSISTANT_SIZE = 88;
+    const assistantMode = viewMode === 'assistant' && !isMobile;
+    const [chatBusy, setChatBusy] = useState(false);
+    const [chatTool, setChatTool] = useState({
+        open: false,
+        pendingApproval: false,
+    });
+    const [answering, setAnswering] = useState(false);
+    const [arriving, setArriving] = useState(false);
+    const [leaving, setLeaving] = useState(false);
+    const [assistantAway, setAssistantAway] = useState(keptAway);
+    const assistantShown = assistantMode && assistantAway === 'none';
+    const callAssistantBack = useCallback(() => {
+        keepAway('none');
+        setAssistantAway('none');
+    }, []);
+    /* The agent's newest words, said in the balloon until heard (T-23). */
+    const [saying, setSaying] = useState();
+    const [heardId, setHeardId] = useState();
+    const [freshSaying, setFreshSaying] = useState(false);
+    useEffect(() => {
+        if (!saying || isOpen) {
+            return;
+        }
+        setFreshSaying(true);
+        const timer = setTimeout(() => setFreshSaying(false), 12000);
+        return () => clearTimeout(timer);
+    }, [saying?.id, saying?.text, isOpen]);
+    useEffect(() => {
+        if (isOpen && saying) {
+            setHeardId(saying.id);
+        }
+    }, [isOpen, saying]);
+    const stageRef = useRef(null);
+    const stageDrag = useViewportDrag(stageRef);
+    useEffect(() => {
+        if (!assistantShown) {
+            return;
+        }
+        setArriving(true);
+        const timer = setTimeout(() => setArriving(false), 1800);
+        return () => clearTimeout(timer);
+    }, [assistantShown]);
+    const assistantState = assistantStateOf(presenceState(chatBusy, chatTool), {
+        arriving,
+        leaving,
+        speaking: answering,
+    });
+    const unheard = !!saying && saying.id !== heardId;
+    const assistantBalloon = assistantState === 'waiting'
+        ? { text: 'Waiting for you — open the conversation to answer.' }
+        : unheard && saying
+            ? { text: saying.text, more: saying.more }
+            : { text: description };
+    const balloonInsists = assistantState === 'greeting' ||
+        assistantState === 'waiting' ||
+        (unheard && (assistantState === 'speaking' || freshSaying));
+    const panelOnLoadingChange = panelProps?.onLoadingChange;
+    const panelOnDisplayItemsChange = panelProps?.onDisplayItemsChange;
+    const handleLoadingChange = useCallback((loading) => {
+        setChatBusy(loading);
+        panelOnLoadingChange?.(loading);
+    }, [panelOnLoadingChange]);
+    const handleDisplayItemsChange = useCallback((items) => {
+        const tool = presenceToolOf(items);
+        setChatTool(previous => previous.open === tool.open &&
+            previous.pendingApproval === tool.pendingApproval
+            ? previous
+            : tool);
+        setAnswering(newestIsAnswer(items));
+        const said = latestSaying(items);
+        setSaying(previous => previous?.id === said?.id && previous?.text === said?.text
+            ? previous
+            : said);
+        panelOnDisplayItemsChange?.(items);
+    }, [panelOnDisplayItemsChange]);
     // Handle view mode changes from the header segmented toggle
     const handleChatViewModeChange = useCallback((mode) => {
         if (mode === 'sidebar' && sidebarDisabled) {
@@ -115,12 +202,16 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             setFocusTrigger(prev => prev + 1);
         }
         else {
-            // The floating modes stay within ChatFloating
+            // The floating modes stay within ChatFloating; picking the assistant
+            // calls it back, however long it was sent away for (T-27).
+            if (mode === 'assistant') {
+                callAssistantBack();
+            }
             setViewMode(mode);
             setFocusTrigger(prev => prev + 1);
             onViewModeChange?.(mode);
         }
-    }, [onViewModeChange, sidebarDisabled]);
+    }, [onViewModeChange, sidebarDisabled, callAssistantBack]);
     // Detect whether the chat is mounted inside a parent that is intentionally
     // configured for docked side panels (Notebook example lays the chat out as a
     // flex sibling). Those hosts dock the panel in-flow. Plain content pages
@@ -272,6 +363,42 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         // Reset animating after duration
         setTimeout(() => setIsAnimating(false), animationDuration);
     }, [isOpen, setIsOpen, onOpen, onClose, animationDuration]);
+    /*
+     * The assistant sent away (T-27): goodbye first, then the popup's round
+     * button in its place — which calls it back when it went for the page, and
+     * opens the chat when it went for the session or for good.
+     */
+    const dismissAssistant = useCallback((away) => {
+        if (isOpen) {
+            handleToggle();
+        }
+        keepAway(away);
+        setLeaving(true);
+        setTimeout(() => {
+            setLeaving(false);
+            setAssistantAway(away);
+        }, 600);
+    }, [isOpen, handleToggle]);
+    /*
+     * The conversation as the assistant's balloon: above the character, its
+     * right edge on the character's, and never off the screen.
+     */
+    const balloonPlace = () => {
+        const widthPx = typeof width === 'number' ? width : 400;
+        const heightPx = typeof height === 'number' ? height : 550;
+        if (stageDrag.position) {
+            return {
+                left: Math.max(8, stageDrag.position.left + ASSISTANT_SIZE - widthPx),
+                top: Math.max(8, stageDrag.position.top - heightPx - 16),
+                right: 'auto',
+                bottom: 'auto',
+            };
+        }
+        const corner = getPositionStyles();
+        return position.startsWith('bottom')
+            ? { ...corner, bottom: offset + ASSISTANT_SIZE + 16 }
+            : { ...corner, top: offset + ASSISTANT_SIZE + 16 };
+    };
     // Handle new chat
     const handleNewChat = useCallback(() => {
         if (useStoreMode) {
@@ -437,6 +564,11 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     }
                     : getPositionStyles()
                 : {}),
+            ...(assistantShown
+                ? balloonPlace()
+                : assistantMode && !isMobile
+                    ? getPositionStyles()
+                    : {}),
             ...(viewMode === 'panel' && !isMobile
                 ? {
                     ...(panelInFlow || dockedInMount
@@ -468,7 +600,8 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                         ? `${popupWidth}px`
                         : popupWidth
                     : (viewMode === 'floating-small' ||
-                        viewMode === 'floating-draggable') &&
+                        viewMode === 'floating-draggable' ||
+                        viewMode === 'assistant') &&
                         !isMobile
                         ? typeof popupWidth === 'number'
                             ? `${popupWidth}px`
@@ -487,7 +620,8 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                 : viewMode === 'floating' && !isMobile
                     ? '100%'
                     : (viewMode === 'floating-small' ||
-                        viewMode === 'floating-draggable') &&
+                        viewMode === 'floating-draggable' ||
+                        viewMode === 'assistant') &&
                         !isMobile
                         ? typeof popupHeight === 'number'
                             ? `${popupHeight}px`
@@ -502,7 +636,11 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             bg: 'canvas.default',
             border: '1px solid',
             borderColor: 'border.default',
-            borderRadius: viewMode === 'panel' || isMobile ? 0 : '12px',
+            borderRadius: viewMode === 'panel' || isMobile
+                ? 0
+                : assistantMode
+                    ? 'var(--theme-radius-bubble, 16px)'
+                    : '12px',
             boxShadow: viewMode === 'panel' ? 'shadow.none' : 'shadow.extra-large',
             overflow: 'hidden',
             transform: viewMode === 'panel'
@@ -550,30 +688,56 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     ...poweredByProps,
                 }, renderToolResult: renderToolResult, description: description, onStateUpdate: onStateUpdate, onNewChat: onNewChat, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: {
                     showAvatars: true,
-                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, ...panelProps, children: children })] }));
-    return (_jsxs(_Fragment, { children: [showButton && !isOpen && (_jsx(Box, { sx: {
+                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, ...panelProps, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, children: children })] }));
+    /*
+     * The floating popup's button. Words not yet heard make it blink for the
+     * person's attention, until the chat is opened; hovered, they show in a
+     * balloon above it in place of the tooltip.
+     */
+    const chatButton = (_jsx(IconButton, { icon: buttonIcon ? buttonIcon : CommentDiscussionIcon, "aria-label": buttonTooltip, onClick: assistantMode && assistantAway === 'page'
+            ? callAssistantBack
+            : handleToggle, size: "large", sx: {
+            width: 56,
+            height: 56,
+            borderRadius: '50%',
+            bg: brandColor || 'accent.emphasis',
+            color: 'fg.onEmphasis',
+            boxShadow: 'shadow.large',
+            transition: 'transform 0.2s ease, box-shadow 0.2s ease',
+            transform: isHovered ? 'scale(1.1)' : 'scale(1)',
+            // Words not yet heard: the circle blinks for the person's
+            // attention, and stops once the chat is opened.
+            ...(unheard
+                ? {
+                    animation: 'chatFloatingBlink 1.1s ease-in-out infinite',
+                    '@keyframes chatFloatingBlink': {
+                        '0%, 100%': {
+                            filter: 'brightness(1)',
+                            boxShadow: '0 0 0 0 rgba(0,0,0,0)',
+                        },
+                        '50%': {
+                            filter: 'brightness(1.25)',
+                            boxShadow: '0 0 0 6px var(--bgColor-accent-muted, rgba(84,174,255,0.4))',
+                        },
+                    },
+                    '@media (prefers-reduced-motion: reduce)': { animation: 'none' },
+                }
+                : {}),
+            '&:hover': {
+                bg: brandColor || 'accent.emphasis',
+                boxShadow: 'shadow.extra-large',
+            },
+        } }));
+    return (_jsxs(_Fragment, { children: [assistantShown && (_jsx(AssistantStage, { character: assistantCharacter, state: assistantState, size: ASSISTANT_SIZE, place: stageDrag.position
+                    ? { left: stageDrag.position.left, top: stageDrag.position.top }
+                    : getPositionStyles(), stageRef: stageRef, onDragStart: stageDrag.onHandlePointerDown, open: isOpen, onToggle: handleToggle, balloon: assistantBalloon, insist: balloonInsists, onDismiss: dismissAssistant })), showButton && !isOpen && !assistantShown && (_jsx(Box, { sx: {
                     ...getPositionStyles(),
                 }, children: _jsxs(Box, { sx: {
                         position: 'relative',
                         display: 'inline-flex',
                         // The glow's halos go behind the button, not behind the page.
                         isolation: 'isolate',
-                    }, onMouseEnter: () => setIsHovered(true), onMouseLeave: () => setIsHovered(false), children: [buttonGlow && _jsx(ButtonGlow, { color: brandColor }), _jsx(Tooltip, { text: `${buttonTooltip}${shortcutHint ? ` (${shortcutHint})` : ''}`, direction: position.includes('right') ? 'w' : 'e', children: _jsx(IconButton, { icon: buttonIcon
-                                    ? buttonIcon
-                                    : CommentDiscussionIcon, "aria-label": buttonTooltip, onClick: handleToggle, size: "large", sx: {
-                                    width: 56,
-                                    height: 56,
-                                    borderRadius: '50%',
-                                    bg: brandColor || 'accent.emphasis',
-                                    color: 'fg.onEmphasis',
-                                    boxShadow: 'shadow.large',
-                                    transition: 'transform 0.2s ease, box-shadow 0.2s ease',
-                                    transform: isHovered ? 'scale(1.1)' : 'scale(1)',
-                                    '&:hover': {
-                                        bg: brandColor || 'accent.emphasis',
-                                        boxShadow: 'shadow.extra-large',
-                                    },
-                                } }) }), messages.length > 0 && (_jsx(Box, { sx: {
+                    }, onMouseEnter: () => setIsHovered(true), onMouseLeave: () => setIsHovered(false), children: [buttonGlow && _jsx(ButtonGlow, { color: brandColor }), isHovered && saying ? (_jsx(SpeechBalloon, { text: saying.text, more: saying.more, onOpen: handleToggle, above: 64, side: position.startsWith('bottom') ? 'above' : 'below', align: position.includes('right') ? 'right' : 'left', tailAt: 28 })) : null, saying ? (chatButton) : (_jsx(Tooltip, { text: `${buttonTooltip}${shortcutHint ? ` (${shortcutHint})` : ''}`, direction: position.includes('right') ? 'w' : 'e', children: chatButton })), messages.length > 0 && (_jsx(Box, { sx: {
                                 position: 'absolute',
                                 top: 0,
                                 right: 0,
@@ -589,7 +753,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                                 fontSize: 0,
                                 fontWeight: 'bold',
                                 pointerEvents: 'none',
-                            }, children: _jsx(Text, { sx: { fontSize: 0 }, children: messages.length > 99 ? '99+' : messages.length }) })), messages.length > 0 && (_jsx(Box, { sx: {
+                            }, children: _jsx(Text, { sx: { fontSize: 0 }, children: messages.length > 99 ? '99+' : messages.length }) })), unheard && (_jsx(Box, { sx: {
                                 position: 'absolute',
                                 top: 0,
                                 left: 0,
@@ -610,6 +774,13 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                                         opacity: 0,
                                     },
                                 },
+                                // Still, as a ring held around the button, for a reader
+                                // who asks the system for reduced motion (T-28).
+                                '@media (prefers-reduced-motion: reduce)': {
+                                    animation: 'none',
+                                    transform: 'scale(1.15)',
+                                    opacity: 0.6,
+                                },
                             } }))] }) })), isMobile && isOpen && (_jsx(Box, { sx: {
                     position: 'fixed',
                     top: 0,

package/lib/chat/assistant/AssistantStage.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The floating assistant on the page (LOOP T-21, T-22, T-27): a character in
+ * a corner, acting out what the application is doing, with a balloon that
+ * says a word while the conversation is closed. Clicked, it opens the
+ * conversation; dragged, it moves, and the conversation follows; sent away,
+ * it says goodbye and leaves a small way back.
+ *
+ * Its motions are one set for every character, by the parts each drawing
+ * names (`assistant-body`, `-pupils`, `-lids`, `-mouth`), and nothing moves
+ * for a reader who asks the system for reduced motion.
+ *
+ * @module chat/assistant/AssistantStage
+ */
+import type { JSX, RefObject } from 'react';
+import { type AssistantCharacter } from './characters';
+import type { AssistantCharacterData } from './formats/types';
+import type { AssistantAway, AssistantState } from './state';
+/**
+ * Where the balloon goes so that it stays inside the window (T-23): toward
+ * the middle of the page from whichever half the character stands in, and
+ * below it when it stands too near the top.
+ */
+export declare function balloonSide(place: {
+    left?: unknown;
+    top?: unknown;
+    right?: unknown;
+    bottom?: unknown;
+}, viewport?: {
+    width: number;
+    height: number;
+}): {
+    side: 'above' | 'below';
+    align: 'left' | 'right';
+};
+export interface AssistantStageProps {
+    /** The character: one Datalayer ships, by id (T-25), or one loaded from a file (T-26). */
+    character: string | AssistantCharacter | AssistantCharacterData;
+    /** What it acts out (T-22). */
+    state: AssistantState;
+    /** Its size, in pixels. */
+    size?: number;
+    /** Where it sits once moved, or the corner it starts in. */
+    place: {
+        left: number;
+        top: number;
+    } | React.CSSProperties;
+    /** The element the drag measures. */
+    stageRef: RefObject<HTMLDivElement | null>;
+    /** Starts a drag. */
+    onDragStart: (event: React.PointerEvent<HTMLElement>) => void;
+    /** The conversation is open: the balloon above is the chat itself. */
+    open: boolean;
+    /** Open or close the conversation. */
+    onToggle: () => void;
+    /**
+     * What the balloon says while the conversation is closed: the agent's
+     * newest words, as the Office Assistant said them (T-23), or a welcome.
+     * `more` adds *Open the conversation* for the rest.
+     */
+    balloon?: {
+        text: string;
+        more?: boolean;
+    };
+    /** Show the balloon without being hovered: something new to say. */
+    insist?: boolean;
+    /** Send it away (T-27): for the page, for the session, or for good. */
+    onDismiss: (away: AssistantAway) => void;
+}
+export declare function AssistantStage({ character, state, size, place, stageRef, onDragStart, open, onToggle, balloon, insist, onDismiss, }: AssistantStageProps): JSX.Element;
+export default AssistantStage;