@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/chat/ChatFloating.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 /*
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
@@ -19,9 +19,12 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { IconButton, Text, Tooltip } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
-import { XIcon, CommentDiscussionIcon } from '@primer/octicons-react';
+import { XIcon, CommentDiscussionIcon, GrabberIcon, } from '@primer/octicons-react';
 import { AiAgentIcon } from '@datalayer/icons-react';
+import { createPortal } from 'react-dom';
 import { ChatBase } from './base/ChatBase';
+import { useViewportDrag } from './useViewportDrag';
+import { disabledChatViewModes, resolveMountPoint } from './viewModes';
 import { useChatOpen, useChatMessages, useChatStore, } from '../stores/chatStore';
 import { useChatKeyboardShortcuts, getShortcutDisplay, } from '@datalayer/core/lib/hooks';
 /**
@@ -43,7 +46,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, poweredByProps, clickOutsideToClose = false, escapeToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, onStateUpdate, children, brandIcon, buttonIcon, buttonTooltip = 'Chat with AI', brandColor, offset = 20, animationDuration = 200, renderToolResult, frontendTools, initialState: _initialState, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, defaultViewMode = 'floating', onViewModeChange, showPanelBackdrop = false, availableModels, showModelSelector = false, showToolsMenu = false, showSkillsMenu = false, showTokenUsage = true, 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, 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, }) {
     // Store-based state
     const storeIsOpen = useChatOpen();
     const storeMessages = useChatMessages();
@@ -65,8 +68,39 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
     const [panelHostRect, setPanelHostRect] = useState(null);
     // Map internal viewMode to ChatViewMode for the header toggle
     const chatViewMode = viewMode === 'panel' ? 'sidebar' : viewMode;
+    /*
+     * The host's mount point for a sidebar, resolved each time the chat opens
+     * or changes mode: a container may mount after the chat does.
+     */
+    const [sidebarMount, setSidebarMount] = useState(null);
+    useLayoutEffect(() => {
+        setSidebarMount(resolveMountPoint(sidebarMountPoint));
+    }, [sidebarMountPoint, isOpen, viewMode]);
+    const disabledViewModes = disabledChatViewModes({
+        sidebarMountPoint: sidebarMount,
+        viewMode: chatViewMode,
+    });
+    const sidebarDisabled = disabledViewModes.includes('sidebar');
+    /* Docked into the host's element, rather than measured against it. */
+    const dockedInMount = viewMode === 'panel' && !isMobile && !!sidebarMount;
+    /*
+     * "Floating draggable": the window moves by its handle. Its place is
+     * forgotten on leaving the mode, so it comes back where the small popup
+     * starts rather than wherever it was last dropped.
+     */
+    const drag = useViewportDrag(popupRef);
+    const resetDrag = drag.reset;
+    useEffect(() => {
+        if (viewMode !== 'floating-draggable') {
+            resetDrag();
+        }
+    }, [viewMode, resetDrag]);
     // Handle view mode changes from the header segmented toggle
     const handleChatViewModeChange = useCallback((mode) => {
+        if (mode === 'sidebar' && sidebarDisabled) {
+            // Greyed out in the header: nothing to dock into.
+            return;
+        }
         if (mode === 'sidebar') {
             // When a parent callback is provided, let it switch the host layout
             // (e.g. swap to ChatSidebar). Otherwise, fall back to the built-in
@@ -80,12 +114,12 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             setFocusTrigger(prev => prev + 1);
         }
         else {
-            // 'floating' or 'floating-small' stays within ChatFloating
+            // The floating modes stay within ChatFloating
             setViewMode(mode);
             setFocusTrigger(prev => prev + 1);
             onViewModeChange?.(mode);
         }
-    }, [onViewModeChange]);
+    }, [onViewModeChange, sidebarDisabled]);
     // 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
@@ -95,6 +129,11 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             setPanelInFlow(false);
             return;
         }
+        if (sidebarMount) {
+            // Rendered into the host's element: in its flow by definition.
+            setPanelInFlow(true);
+            return;
+        }
         const parent = popupRef.current?.parentElement;
         if (!parent) {
             setPanelInFlow(false);
@@ -105,7 +144,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             (style.flexDirection === 'row' || style.flexDirection === 'row-reverse');
         const isGrid = style.display.includes('grid');
         setPanelInFlow(isFlexRow || isGrid);
-    }, [viewMode, isMobile, isOpen]);
+    }, [viewMode, isMobile, isOpen, sidebarMount]);
     // For fixed (non-flow) panel mode, measure the host region so the docked
     // panel aligns to the visible content area (below any app header) at full
     // height, and reserve horizontal space so the page content reflows to the
@@ -367,6 +406,150 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         : {};
     // Close button for header
     const closeButton = (_jsx(Tooltip, { text: `Close${escapeToClose ? ' (Esc)' : ''}`, direction: "s", children: _jsx(IconButton, { icon: XIcon, "aria-label": "Close", onClick: handleToggle, variant: "invisible", size: "small" }) }));
+    /* The window itself; where it goes is decided below. */
+    const chatWindow = (_jsxs(Box, { ref: popupRef, className: className, sx: {
+            position: viewMode === 'panel' && !isMobile && (panelInFlow || dockedInMount)
+                ? 'relative'
+                : 'fixed',
+            // floating (normal) — full-height column pinned to the right edge
+            ...(viewMode === 'floating' && !isMobile
+                ? {
+                    top: 0,
+                    right: 0,
+                    bottom: 0,
+                    left: 'auto',
+                }
+                : {}),
+            // floating-small — standard popup positioned via getPositionStyles()
+            ...(viewMode === 'floating-small' && !isMobile
+                ? getPositionStyles()
+                : {}),
+            // floating-draggable — where it was last put down, or where the
+            // small popup starts until somebody moves it
+            ...(viewMode === 'floating-draggable' && !isMobile
+                ? drag.position
+                    ? {
+                        left: drag.position.left,
+                        top: drag.position.top,
+                        right: 'auto',
+                        bottom: 'auto',
+                    }
+                    : getPositionStyles()
+                : {}),
+            ...(viewMode === 'panel' && !isMobile
+                ? {
+                    ...(panelInFlow || dockedInMount
+                        ? {
+                            top: 'auto',
+                            right: 'auto',
+                            bottom: 'auto',
+                            left: 'auto',
+                            marginLeft: 'auto',
+                            alignSelf: 'stretch',
+                        }
+                        : {
+                            // Fixed panel aligned to the measured host region so it
+                            // docks below any app header at full content height,
+                            // instead of overlaying from the very top of the viewport.
+                            top: panelHostRect ? `${panelHostRect.top}px` : 0,
+                            right: panelHostRect ? `${panelHostRect.right}px` : 0,
+                            bottom: panelHostRect ? 'auto' : 0,
+                            left: 'auto',
+                        }),
+                }
+                : {}),
+            width: viewMode === 'panel' && !isMobile
+                ? isOpen || isAnimating
+                    ? `${panelWidthPx}px`
+                    : '0px'
+                : viewMode === 'floating' && !isMobile
+                    ? typeof popupWidth === 'number'
+                        ? `${popupWidth}px`
+                        : popupWidth
+                    : (viewMode === 'floating-small' ||
+                        viewMode === 'floating-draggable') &&
+                        !isMobile
+                        ? typeof popupWidth === 'number'
+                            ? `${popupWidth}px`
+                            : popupWidth
+                        : isMobile
+                            ? '100%'
+                            : typeof popupWidth === 'number'
+                                ? `${popupWidth}px`
+                                : popupWidth,
+            height: viewMode === 'panel' && !isMobile
+                ? panelInFlow || dockedInMount
+                    ? '100%'
+                    : panelHostRect
+                        ? `${panelHostRect.height}px`
+                        : '100%'
+                : viewMode === 'floating' && !isMobile
+                    ? '100%'
+                    : (viewMode === 'floating-small' ||
+                        viewMode === 'floating-draggable') &&
+                        !isMobile
+                        ? typeof popupHeight === 'number'
+                            ? `${popupHeight}px`
+                            : popupHeight
+                        : isMobile
+                            ? '100%'
+                            : typeof popupHeight === 'number'
+                                ? `${popupHeight}px`
+                                : popupHeight,
+            display: 'flex',
+            flexDirection: 'column',
+            bg: 'canvas.default',
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: viewMode === 'panel' || isMobile ? 0 : '12px',
+            boxShadow: viewMode === 'panel' ? 'shadow.none' : 'shadow.extra-large',
+            overflow: 'hidden',
+            transform: viewMode === 'panel'
+                ? isOpen
+                    ? 'translateX(0)'
+                    : 'translateX(100%)'
+                : getAnimationTransform(isOpen),
+            opacity: viewMode === 'panel' ? 1 : isOpen ? 1 : 0,
+            transition: `transform ${animationDuration}ms ease, opacity ${animationDuration}ms ease, width ${animationDuration}ms ease`,
+            zIndex: viewMode === 'panel' && !isMobile
+                ? panelInFlow || dockedInMount
+                    ? 'auto'
+                    : 1001
+                : 1001,
+            // Hide from accessibility and pointer events when closed
+            visibility: isOpen || isAnimating ? 'visible' : 'hidden',
+            pointerEvents: isOpen ? 'auto' : 'none',
+            ...mobileStyles,
+        }, children: [viewMode === 'floating-draggable' && !isMobile && (_jsx(Box, { onPointerDown: drag.onHandlePointerDown, "aria-label": "Move the chat", sx: {
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    flexShrink: 0,
+                    height: 18,
+                    cursor: 'grab',
+                    color: 'fg.subtle',
+                    bg: 'canvas.subtle',
+                    borderBottom: '1px solid',
+                    borderColor: 'border.muted',
+                    touchAction: 'none',
+                    '&:active': { cursor: 'grabbing' },
+                }, children: _jsx(GrabberIcon, { size: 16 }) })), _jsx(ChatBase, { title: title, showHeader: showHeader, useStore: useStoreMode, protocol: protocol, themeVariant: themeVariant, colorMode: colorMode, autoFocus: isOpen, focusTrigger: focusTrigger, launching: launching, launchingMessage: launchingMessage, brandIcon: brandIcon || _jsx(AiAgentIcon, { colored: true, size: 20 }), headerButtons: {
+                    showNewChat: showNewChatButton,
+                    showClear: showClearButton && messages.length > 0,
+                    showSettings: showSettingsButton && !!onSettingsClick,
+                    onNewChat: handleNewChat,
+                    onClear: handleClear,
+                    onSettings: onSettingsClick,
+                }, headerActions: _jsx(_Fragment, { children: closeButton }), chatViewMode: chatViewMode, onChatViewModeChange: handleChatViewModeChange, disabledViewModes: disabledViewModes, showPoweredBy: showPoweredBy, 
+                // Forwarded, so a host can ask for the Lexical editor — and with it
+                // the `@` menu — without giving up the floating chat to get one.
+                promptVariant: promptVariant, mentionableAgents: mentionableAgents, poweredByProps: {
+                    brandName: 'Datalayer',
+                    brandUrl: 'https://datalayer.ai',
+                    ...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: {
                     ...getPositionStyles(),
                 }, children: _jsxs(Box, { sx: {
@@ -442,116 +625,8 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     bg: 'neutral.muted',
                     opacity: 0.3,
                     zIndex: 1000,
-                }, onClick: handleToggle })), _jsx(Box, { ref: popupRef, className: className, sx: {
-                    position: viewMode === 'panel' && !isMobile && panelInFlow
-                        ? 'relative'
-                        : 'fixed',
-                    // floating (normal) — full-height column pinned to the right edge
-                    ...(viewMode === 'floating' && !isMobile
-                        ? {
-                            top: 0,
-                            right: 0,
-                            bottom: 0,
-                            left: 'auto',
-                        }
-                        : {}),
-                    // floating-small — standard popup positioned via getPositionStyles()
-                    ...(viewMode === 'floating-small' && !isMobile
-                        ? getPositionStyles()
-                        : {}),
-                    ...(viewMode === 'panel' && !isMobile
-                        ? {
-                            ...(panelInFlow
-                                ? {
-                                    top: 'auto',
-                                    right: 'auto',
-                                    bottom: 'auto',
-                                    left: 'auto',
-                                    marginLeft: 'auto',
-                                    alignSelf: 'stretch',
-                                }
-                                : {
-                                    // Fixed panel aligned to the measured host region so it
-                                    // docks below any app header at full content height,
-                                    // instead of overlaying from the very top of the viewport.
-                                    top: panelHostRect ? `${panelHostRect.top}px` : 0,
-                                    right: panelHostRect ? `${panelHostRect.right}px` : 0,
-                                    bottom: panelHostRect ? 'auto' : 0,
-                                    left: 'auto',
-                                }),
-                        }
-                        : {}),
-                    width: viewMode === 'panel' && !isMobile
-                        ? isOpen || isAnimating
-                            ? `${panelWidthPx}px`
-                            : '0px'
-                        : viewMode === 'floating' && !isMobile
-                            ? typeof popupWidth === 'number'
-                                ? `${popupWidth}px`
-                                : popupWidth
-                            : viewMode === 'floating-small' && !isMobile
-                                ? typeof popupWidth === 'number'
-                                    ? `${popupWidth}px`
-                                    : popupWidth
-                                : isMobile
-                                    ? '100%'
-                                    : typeof popupWidth === 'number'
-                                        ? `${popupWidth}px`
-                                        : popupWidth,
-                    height: viewMode === 'panel' && !isMobile
-                        ? panelInFlow
-                            ? '100%'
-                            : panelHostRect
-                                ? `${panelHostRect.height}px`
-                                : '100%'
-                        : viewMode === 'floating' && !isMobile
-                            ? '100%'
-                            : viewMode === 'floating-small' && !isMobile
-                                ? typeof popupHeight === 'number'
-                                    ? `${popupHeight}px`
-                                    : popupHeight
-                                : isMobile
-                                    ? '100%'
-                                    : typeof popupHeight === 'number'
-                                        ? `${popupHeight}px`
-                                        : popupHeight,
-                    display: 'flex',
-                    flexDirection: 'column',
-                    bg: 'canvas.default',
-                    border: '1px solid',
-                    borderColor: 'border.default',
-                    borderRadius: viewMode === 'panel' || isMobile ? 0 : '12px',
-                    boxShadow: viewMode === 'panel' ? 'shadow.none' : 'shadow.extra-large',
-                    overflow: 'hidden',
-                    transform: viewMode === 'panel'
-                        ? isOpen
-                            ? 'translateX(0)'
-                            : 'translateX(100%)'
-                        : getAnimationTransform(isOpen),
-                    opacity: viewMode === 'panel' ? 1 : isOpen ? 1 : 0,
-                    transition: `transform ${animationDuration}ms ease, opacity ${animationDuration}ms ease, width ${animationDuration}ms ease`,
-                    zIndex: viewMode === 'panel' && !isMobile
-                        ? panelInFlow
-                            ? 'auto'
-                            : 1001
-                        : 1001,
-                    // Hide from accessibility and pointer events when closed
-                    visibility: isOpen || isAnimating ? 'visible' : 'hidden',
-                    pointerEvents: isOpen ? 'auto' : 'none',
-                    ...mobileStyles,
-                }, children: _jsx(ChatBase, { title: title, showHeader: showHeader, useStore: useStoreMode, protocol: protocol, autoFocus: isOpen, focusTrigger: focusTrigger, launching: launching, launchingMessage: launchingMessage, brandIcon: brandIcon || _jsx(AiAgentIcon, { colored: true, size: 20 }), headerButtons: {
-                        showNewChat: showNewChatButton,
-                        showClear: showClearButton && messages.length > 0,
-                        showSettings: showSettingsButton && !!onSettingsClick,
-                        onNewChat: handleNewChat,
-                        onClear: handleClear,
-                        onSettings: onSettingsClick,
-                    }, headerActions: _jsx(_Fragment, { children: closeButton }), chatViewMode: chatViewMode, onChatViewModeChange: handleChatViewModeChange, showPoweredBy: showPoweredBy, poweredByProps: {
-                        brandName: 'Datalayer',
-                        brandUrl: 'https://datalayer.ai',
-                        ...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, 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 }) })] }));
+                }, onClick: handleToggle })), dockedInMount && sidebarMount
+                ? createPortal(chatWindow, sidebarMount)
+                : chatWindow] }));
 }
 export default ChatFloating;

package/lib/chat/ChatInline.d.ts

@@ -1,3 +1,18 @@
+/**
+ * ChatInline - Inline chat component for text selection AI assistance.
+ *
+ * This component provides an inline AI chat interface that appears when
+ * text is selected in a Lexical editor. It supports:
+ * - Custom prompts via text input
+ * - Pre-defined AI actions (improve, summarize, translate, etc.)
+ * - Streaming responses from an agent via AG-UI protocol
+ * - Actions to apply AI results (replace, insert inline, insert below)
+ *
+ * Uses Primer UI components instead of Tailwind CSS.
+ *
+ * @module chat/ChatInline
+ */
+import type { JSX } from 'react';
 import type { Protocol } from '../types/protocol';
 /**
  * Protocol configuration for ChatInline

package/lib/chat/ChatInline.js

@@ -1,22 +1,4 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-/*
- * Copyright (c) 2025-2026 Datalayer, Inc.
- * Distributed under the terms of the Modified BSD License.
- */
-/**
- * ChatInline - Inline chat component for text selection AI assistance.
- *
- * This component provides an inline AI chat interface that appears when
- * text is selected in a Lexical editor. It supports:
- * - Custom prompts via text input
- * - Pre-defined AI actions (improve, summarize, translate, etc.)
- * - Streaming responses from an agent via AG-UI protocol
- * - Actions to apply AI results (replace, insert inline, insert below)
- *
- * Uses Primer UI components instead of Tailwind CSS.
- *
- * @module chat/ChatInline
- */
 import { useState, useCallback, useMemo, useRef, useEffect, Fragment, } from 'react';
 import { Text, TextInput, IconButton, ActionList, Spinner, } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';

package/lib/chat/ChatPopupStandalone.d.ts

@@ -66,5 +66,5 @@ export interface ChatPopupStandaloneProps extends Omit<ChatCommonProps, 'onSendM
  * ChatPopupStandalone component
  * A floating popup chat that uses ChatBase with custom onSendMessage handler
  */
-export declare function ChatPopupStandalone({ onSendMessage, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, poweredByProps, clickOutsideToClose, escapeToClose, className, placeholder, onSettingsClick, onNewChat, onOpen, onClose, children, brandIcon, buttonIcon, buttonTooltip, brandColor, offset, animationDuration, enableStreaming, emptyStateMessage, renderToolResult, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, }: ChatPopupStandaloneProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatPopupStandalone({ onSendMessage, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, poweredByProps, clickOutsideToClose, escapeToClose, className, placeholder, onSettingsClick, onNewChat, onOpen, onClose, children, brandIcon, buttonIcon, buttonTooltip, brandColor, offset, animationDuration, enableStreaming, emptyStateMessage, renderToolResult, onToolCallStart, onToolCallComplete, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, }: ChatPopupStandaloneProps): React.JSX.Element;
 export default ChatPopupStandalone;

package/lib/chat/ChatSidebar.d.ts

@@ -15,7 +15,19 @@ export interface ChatSidebarProps extends ChatCommonProps {
     enableKeyboardShortcuts?: boolean;
     /** Keyboard shortcut to toggle (default: 'k') */
     toggleShortcut?: string;
-    /** Enable click outside to close */
+    /**
+     * Close the sidebar when a click lands outside it. Off by default.
+     *
+     * On a desktop the sidebar is *docked*: it takes layout width beside the
+     * content, and everything the user is working on — a notebook cell, a
+     * paragraph of the document — is by definition outside it. Closing on that
+     * click made the panel vanish the moment anyone touched what they were
+     * chatting about. Modal semantics for a panel that is not modal.
+     *
+     * The mobile overlay is genuinely modal, and it already closes on its own
+     * backdrop, so nothing needs this to be on there either. Left as a prop for
+     * a consumer that really does want dismiss-on-outside-click.
+     */
     clickOutsideToClose?: boolean;
     /** Enable escape key to close */
     escapeToClose?: boolean;
@@ -23,5 +35,5 @@ export interface ChatSidebarProps extends ChatCommonProps {
 /**
  * Chat Sidebar component
  */
-export declare function ChatSidebar({ title, protocol: protocolProp, defaultOpen, position, width, showHeader, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, poweredByProps, clickOutsideToClose, className, onSettingsClick, onNewChat, onOpen, onClose, children, brandIcon, onSendMessage, enableStreaming, onToolCallStart, onToolCallComplete, placeholder, description, pendingPrompt, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, }: ChatSidebarProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatSidebar({ title, protocol: protocolProp, defaultOpen, position, width, showHeader, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, poweredByProps, clickOutsideToClose, className, onSettingsClick, onNewChat, onOpen, onClose, children, brandIcon, onSendMessage, enableStreaming, onToolCallStart, onToolCallComplete, placeholder, description, pendingPrompt, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, }: ChatSidebarProps): import("react").JSX.Element;
 export default ChatSidebar;

package/lib/chat/ChatSidebar.js

@@ -37,7 +37,7 @@ function useIsMobile(breakpoint = 640) {
 /**
  * Chat Sidebar component
  */
-export function ChatSidebar({ title = 'Chat', protocol: protocolProp, defaultOpen = true, position = 'right', width = 400, showHeader = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = 'k', showPoweredBy = true, poweredByProps, clickOutsideToClose = true, className, onSettingsClick, onNewChat, onOpen, onClose, children, brandIcon, onSendMessage, enableStreaming = true, onToolCallStart, onToolCallComplete, placeholder = 'Ask a question...', description, pendingPrompt, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, }) {
+export function ChatSidebar({ title = 'Chat', protocol: protocolProp, defaultOpen = true, position = 'right', width = 400, showHeader = true, showNewChatButton = true, showClearButton = true, showSettingsButton = false, enableKeyboardShortcuts = true, toggleShortcut = 'k', showPoweredBy = true, poweredByProps, clickOutsideToClose = false, className, onSettingsClick, onNewChat, onOpen, onClose, children, brandIcon, onSendMessage, enableStreaming = true, onToolCallStart, onToolCallComplete, placeholder = 'Ask a question...', description, pendingPrompt, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, }) {
     const isOpen = useChatOpen();
     const messages = useChatMessages();
     const setOpen = useChatStore(state => state.setOpen);

package/lib/chat/ChatStandalone.d.ts

@@ -55,5 +55,5 @@ export interface ChatStandaloneProps extends ChatCommonProps {
  * ChatStandalone component
  * A floating popup chat that uses ChatBase with custom onSendMessage handler
  */
-export declare function ChatStandalone({ onSendMessage, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, poweredByProps, clickOutsideToClose, escapeToClose, className, placeholder, onSettingsClick, onNewChat, onOpen, onClose, children, brandIcon, buttonIcon, buttonTooltip, brandColor, offset, animationDuration, enableStreaming, emptyStateMessage, renderToolResult, onToolCallStart, onToolCallComplete, pendingPrompt, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, }: ChatStandaloneProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatStandalone({ onSendMessage, title, description, position, defaultOpen, width, height, showHeader, showButton, showNewChatButton, showClearButton, showSettingsButton, enableKeyboardShortcuts, toggleShortcut, showPoweredBy, poweredByProps, clickOutsideToClose, escapeToClose, className, placeholder, onSettingsClick, onNewChat, onOpen, onClose, children, brandIcon, buttonIcon, buttonTooltip, brandColor, offset, animationDuration, enableStreaming, emptyStateMessage, renderToolResult, onToolCallStart, onToolCallComplete, pendingPrompt, showToolApprovalBanner, pendingApprovals, onApproveApproval, onRejectApproval, panelProps, }: ChatStandaloneProps): React.JSX.Element;
 export default ChatStandalone;

package/lib/chat/EphemeralSurfaceControl.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Which companion surface is on screen: the chat alone, a notebook, or a
+ * document.
+ *
+ * It lives in the chat's header, and it also has to live on the surface's own
+ * toolbar: a page drawn without a conversation — a Code Sandbox, where nothing
+ * is listening — has no header to put it in, and without it the reader is
+ * stuck in whichever surface opened first. One component in both places, so
+ * the switch is the same thing wherever it is found.
+ */
+import type { JSX } from 'react';
+import type { EphemeralSurfaceMode } from '../types';
+export type EphemeralSurfaceControlProps = {
+    /** The surface on screen. */
+    mode: EphemeralSurfaceMode;
+    onChange?: (mode: EphemeralSurfaceMode) => void;
+    /** Whether a notebook is on offer at all. */
+    enableNotebook?: boolean;
+    /** Whether a document is on offer at all. */
+    enableDocument?: boolean;
+    /**
+     * Whether "chat only" is one of the choices.
+     *
+     * Not where there is no chat: closing the surface would leave the page
+     * empty, which is not a state anyone is asking for.
+     */
+    enableChatOnly?: boolean;
+};
+export declare function EphemeralSurfaceControl({ mode, onChange, enableNotebook, enableDocument, enableChatOnly, }: EphemeralSurfaceControlProps): JSX.Element | null;
+export default EphemeralSurfaceControl;

package/lib/chat/EphemeralSurfaceControl.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Box, Tooltip } from '@primer/react';
+import { CircleSlashIcon, FileIcon, RowsIcon } from '@primer/octicons-react';
+export function EphemeralSurfaceControl({ mode, onChange, enableNotebook = false, enableDocument = false, enableChatOnly = true, }) {
+    const choices = [
+        {
+            mode: 'none',
+            icon: CircleSlashIcon,
+            label: 'Chat only',
+            enabled: enableChatOnly,
+        },
+        {
+            mode: 'notebook',
+            icon: RowsIcon,
+            label: 'Notebook',
+            enabled: enableNotebook,
+        },
+        {
+            mode: 'document',
+            icon: FileIcon,
+            label: 'Document',
+            enabled: enableDocument,
+        },
+    ].filter(({ enabled }) => enabled);
+    // One choice is not a choice.
+    if (choices.length < 2) {
+        return null;
+    }
+    return (_jsx(Box, { sx: {
+            display: 'inline-flex',
+            alignItems: 'center',
+            bg: 'neutral.muted',
+            borderRadius: '6px',
+            p: '2px',
+            gap: '1px',
+        }, children: choices.map(({ mode: choice, icon: ModeIcon, label }) => (_jsx(Tooltip, { text: label, direction: "n", children: _jsx(Box, { as: "button", "aria-label": label, onClick: () => onChange?.(choice), sx: {
+                    display: 'inline-flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    width: 26,
+                    height: 24,
+                    borderRadius: '4px',
+                    border: 'none',
+                    cursor: 'pointer',
+                    bg: mode === choice ? 'canvas.default' : 'transparent',
+                    boxShadow: mode === choice ? 'shadow.small' : 'none',
+                    color: mode === choice ? 'fg.default' : 'fg.muted',
+                    transition: 'all 0.15s ease',
+                    '&:hover': {
+                        color: 'fg.default',
+                        bg: mode === choice ? 'canvas.default' : 'neutral.subtle',
+                    },
+                }, children: _jsx(ModeIcon, { size: 14 }) }) }, choice))) }));
+}
+export default EphemeralSurfaceControl;

package/lib/chat/base/ChatAvailability.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Whether there is an agent to talk to, said once by the host.
+ *
+ * A chat can be unavailable for a reason that has nothing to do with the chat:
+ * the sandbox runs in the browser, or on an anonymous server, and no agent runs
+ * beside it. That is the host's knowledge, not the chat's — and not something
+ * every screen rendering a chat should have to work out and pass down.
+ *
+ * So the host says it once, here, and every `ChatBase` beneath it shows itself
+ * switched off with the reason in its header. An explicit `disabled` prop still
+ * wins: a caller that knows better about one particular chat can say so.
+ *
+ * @module chat/base/ChatAvailability
+ */
+import type { JSX } from 'react';
+import { type ReactNode } from 'react';
+/** What the host knows about whether a chat can be used. */
+export interface ChatAvailability {
+    /** Whether the chat is unusable here. */
+    disabled: boolean;
+    /** Why, in the person's terms. Shown in the chat header. */
+    disableReason?: string;
+}
+/**
+ * Declare, for everything beneath, whether a chat can be used.
+ *
+ * Rendering no provider means available — the common case should cost nothing.
+ */
+export declare function ChatAvailabilityProvider({ disabled, disableReason, children, }: ChatAvailability & {
+    children: ReactNode;
+}): JSX.Element;
+/** What the host said about chat availability here. */
+export declare function useChatAvailability(): ChatAvailability;
+export default ChatAvailabilityProvider;

package/lib/chat/base/ChatAvailability.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from 'react';
+const AVAILABLE = { disabled: false };
+const ChatAvailabilityContext = createContext(AVAILABLE);
+/**
+ * Declare, for everything beneath, whether a chat can be used.
+ *
+ * Rendering no provider means available — the common case should cost nothing.
+ */
+export function ChatAvailabilityProvider({ disabled = false, disableReason, children, }) {
+    const value = useMemo(() => (disabled ? { disabled: true, disableReason } : AVAILABLE), [disabled, disableReason]);
+    return (_jsx(ChatAvailabilityContext.Provider, { value: value, children: children }));
+}
+/** What the host said about chat availability here. */
+export function useChatAvailability() {
+    return useContext(ChatAvailabilityContext);
+}
+export default ChatAvailabilityProvider;

package/lib/chat/base/ChatBase.d.ts

@@ -1,6 +1,7 @@
+import React from 'react';
 import type { ChatBaseProps } from '../../types/chat';
 /**
  * ChatBase component — Universal chat panel supporting store, protocol, and custom modes.
  */
-export declare function ChatBase(props: ChatBaseProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatBase(props: ChatBaseProps): React.JSX.Element;
 export default ChatBase;