@datalayer/agent-runtimes 1.0.29 → 1.3.11

package/lib/chat/document/EphemeralDocument.js

@@ -20,34 +20,32 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  *
  * @module chat/document/EphemeralDocument
  */
+/*
+ * First, before anything lexical: `@lexical/code` pulls Prism *language
+ * components*, plain scripts that read the bare global `Prism` the moment
+ * they evaluate — and this module is what defines it. Imported lower down,
+ * the languages ran first and the whole editor died on "Prism is not
+ * defined" before it could draw anything.
+ */
+import '@datalayer/jupyter-react/lib/css/PrismCss';
 import { useCallback, useEffect, useMemo, useRef, useState, } from 'react';
-import { $getRoot, $createParagraphNode, } from 'lexical';
-import { LexicalComposer } from '@lexical/react/LexicalComposer';
-import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
+import { $getRoot, $createParagraphNode, defineExtension, } from 'lexical';
+import { LexicalExtensionComposer } from '@lexical/react/LexicalExtensionComposer';
 import { ContentEditable } from '@lexical/react/LexicalContentEditable';
-import { HistoryPlugin } from '@lexical/react/LexicalHistoryPlugin';
 import { OnChangePlugin } from '@lexical/react/LexicalOnChangePlugin';
 import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
-import { LexicalErrorBoundary } from '@lexical/react/LexicalErrorBoundary';
-import { AutoFocusPlugin } from '@lexical/react/LexicalAutoFocusPlugin';
-import { MarkdownShortcutPlugin } from '@lexical/react/LexicalMarkdownShortcutPlugin';
-import { TRANSFORMERS } from '@lexical/markdown';
-import { registerCodeHighlighting } from '@lexical/code';
-import { ListPlugin } from '@lexical/react/LexicalListPlugin';
-import { CheckListPlugin } from '@lexical/react/LexicalCheckListPlugin';
-import { LinkPlugin } from '@lexical/react/LexicalLinkPlugin';
+import { AutoFocusExtension, getExtensionDependencyFromEditor, } from '@lexical/extension';
+import { HistoryExtension } from '@lexical/history';
 import { ServerConnection, ServiceManager } from '@jupyterlab/services';
 import { DatalayerThemeProvider, getThemeConfig, useSystemColorMode, useThemeStore, } from '@datalayer/primer-addons';
-import { Box, Spinner, Text } from '@primer/react';
+import { Box } from '@primer/react';
 import { JupyterReactTheme, Kernel, disposeServiceManager, } from '@datalayer/jupyter-react';
-import { ComponentPickerMenuPlugin, JupyterCellPlugin, JupyterInputOutputPlugin, DraggableBlockPlugin, ImagesPlugin, ExcalidrawPlugin, TablePlugin, TableCellResizerPlugin, TableActionMenuPlugin, TableHoverActionsV2Plugin, CollapsiblePlugin, HorizontalRulePlugin, EquationsPlugin, YouTubePlugin, AutoLinkPlugin, AutoEmbedPlugin, LexicalConfigProvider, LexicalStatePlugin, FloatingTextFormatToolbarPlugin, CodeActionMenuPlugin, ListMaxIndentLevelPlugin, ToolbarPlugin, ToolbarContext, CommentsProvider, commentTheme, } from '@datalayer/jupyter-lexical';
+import { ComponentPickerMenuPlugin, JupyterLexicalExtension, JupyterInputOutputPlugin, DraggableBlockPlugin, TableCellResizerPlugin, TableActionMenuPlugin, TableHoverActionsV2Plugin, LexicalConfigProvider, LexicalStatePlugin, FloatingTextFormatToolbarPlugin, CodeActionMenuPlugin, ToolbarPlugin, ToolbarContext, CommentsProvider, DocumentSkeleton, commentTheme, } from '@datalayer/jupyter-lexical';
 import { createWebsocketProvider, LoroCollaborationPlugin, } from '@datalayer/lexical-loro';
-import { editorConfig } from '../../examples/lexical/editorConfig';
 import { useLexicalTools } from '../../tools/adapters/agent-runtimes/lexicalHooks';
 import { useAgentsRuntimes } from '../../hooks/useAgentRuntimes';
 import { registerSandboxServiceManager } from '../../services/sandboxServiceManagers';
 import { useProgressTask } from '../../hooks/useProgressTask';
-import '@datalayer/jupyter-react/lib/css/PrismCss';
 import '@datalayer/jupyter-lexical/style/index.css';
 /**
  * Lexical plugin that loads the initial (restored) editor state exactly once.
@@ -89,10 +87,18 @@ function LoadContentPlugin({ content }) {
     }, [content, editor]);
     return null;
 }
-/** Registers code syntax highlighting for code blocks. */
-function CodeHighlightPlugin() {
+/**
+ * Undo history follows the collaboration mode.
+ *
+ * The history is the bundled `HistoryExtension`'s. Its `disabled` signal is
+ * flipped here rather than set in the root extension, so that a change of
+ * mode does not rebuild the editor and lose the document with it.
+ */
+function HistoryTogglePlugin({ disabled }) {
     const [editor] = useLexicalComposerContext();
-    useEffect(() => registerCodeHighlighting(editor), [editor]);
+    useEffect(() => {
+        getExtensionDependencyFromEditor(editor, HistoryExtension).output.disabled.value = disabled;
+    }, [editor, disabled]);
     return null;
 }
 /**
@@ -108,7 +114,20 @@ function DocumentToolbar({ setIsLinkEditMode, extraItems, }) {
 /**
  * Renders an in-memory Lexical document backed by a sandbox kernel.
  */
-export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride, themeVariant, colorMode, content, onContentChange, onToolsReady, onKernelChange, collaboration, toolbarExtraItems, }) {
+/**
+ * The theme provider, or nothing.
+ *
+ * A host that already owns a theme root passes `inherit`; nested providers
+ * fight over `BaseStyles` and font tokens, and the inner one wins for the wrong
+ * reasons.
+ */
+function ThemeRoot({ inherit, colorMode, themeConfig, children, }) {
+    if (inherit) {
+        return _jsx(_Fragment, { children: children });
+    }
+    return (_jsx(DatalayerThemeProvider, { colorMode: colorMode, theme: themeConfig.primerTheme, themeStyles: themeConfig.themeStyles, children: children }));
+}
+export function EphemeralDocument({ documentId, runtimeName, runtimeOverride, serviceManager: providedServiceManager, kernelId, themeVariant, colorMode, content, onContentChange, onToolsReady, onKernelChange, collaboration, toolbarExtraItems, showToolbar = true, inheritTheme = false, autoFocus = true, }) {
     // Real-time collaboration is active only when both a WebSocket endpoint and a
     // room id are supplied. In that mode the shared Loro CRDT is the single source
     // of truth: local content-seeding and undo history are disabled so the local
@@ -162,17 +181,18 @@ export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride,
                 url: overrideBaseUrl,
                 wsUrl: String(runtimeOverride?.wsUrl || '').trim() || undefined,
                 token: String(runtimeOverride?.token || '').trim(),
-                pod_name: String(runtimeOverride?.podName || '').trim() || 'agent-node-proxy',
+                runtime_name: String(runtimeOverride?.runtimeName || '').trim() ||
+                    'agent-node-proxy',
             };
         }
-        const preferredPod = String(runtimePodName || '').trim();
-        if (!preferredPod) {
+        const preferredRuntime = String(runtimeName || '').trim();
+        if (!preferredRuntime) {
             return undefined;
         }
-        return runtimes.find(rt => String(rt?.pod_name || '') === preferredPod);
-    }, [runtimeOverride, runtimePodName, runtimes]);
+        return runtimes.find(rt => String(rt?.runtime_name || '') === preferredRuntime);
+    }, [runtimeOverride, runtimeName, runtimes]);
     const needsRuntimeLookup = Boolean(!runtimeOverride?.baseUrl &&
-        String(runtimePodName || '').trim() &&
+        String(runtimeName || '').trim() &&
         !selectedRuntime);
     useEffect(() => {
         if (!needsRuntimeLookup) {
@@ -195,6 +215,41 @@ export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride,
         let manager = null;
         let unregisterManager = null;
         const connectRuntime = async () => {
+            // Services handed over by the host — an in-page JupyterLite sandbox —
+            // are used as they are. There is no URL to connect to in that case, and
+            // the old code read "no url" as "nothing to do" and returned silently,
+            // which is why the editor came up blank with an empty console.
+            if (providedServiceManager) {
+                try {
+                    await providedServiceManager.ready;
+                    const connection = kernelId
+                        ? providedServiceManager.kernels.connectTo({
+                            model: { id: kernelId, name: 'python' },
+                        })
+                        : await providedServiceManager.kernels.startNew();
+                    if (!cancelled) {
+                        setRuntimeServiceManager(providedServiceManager);
+                        setDocumentKernel(new Kernel({
+                            kernelName: connection.model.name,
+                            kernelSpecName: connection.model.name,
+                            kernelModel: connection.model,
+                            kernelManager: providedServiceManager.kernels,
+                            kernelspecsManager: providedServiceManager.kernelspecs,
+                            sessionManager: providedServiceManager.sessions,
+                        }));
+                    }
+                }
+                catch (reason) {
+                    // Said out loud. A document that silently shows nothing is the
+                    // hardest kind of failure to chase.
+                    console.error('[agent-runtimes] The document could not reach the kernel of the sandbox it was given.', reason);
+                    if (!cancelled) {
+                        setRuntimeServiceManager(null);
+                        setDocumentKernel(undefined);
+                    }
+                }
+                return;
+            }
             const baseUrl = String(selectedRuntime?.url || '').trim();
             if (!baseUrl) {
                 if (!cancelled) {
@@ -216,7 +271,7 @@ export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride,
                 manager = new ServiceManager({ serverSettings });
                 // Central sandbox registry: runtime terminate/pause disposes this
                 // manager immediately so its pollers cannot hit the dead pod ingress.
-                unregisterManager = registerSandboxServiceManager(String(selectedRuntime?.pod_name || ''), manager);
+                unregisterManager = registerSandboxServiceManager(String(selectedRuntime?.runtime_name || ''), manager);
                 await manager.ready;
                 const kernelConnection = await manager.kernels.startNew();
                 if (!cancelled) {
@@ -243,11 +298,19 @@ export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride,
         return () => {
             cancelled = true;
             unregisterManager?.();
+            // Only what this component built. A manager the host passed in is still
+            // theirs, and disposing it would take the sandbox down with the view.
             if (manager) {
                 disposeServiceManager(manager);
             }
         };
-    }, [selectedRuntime?.pod_name, selectedRuntime?.url, selectedRuntime?.token]);
+    }, [
+        providedServiceManager,
+        kernelId,
+        selectedRuntime?.runtime_name,
+        selectedRuntime?.url,
+        selectedRuntime?.token,
+    ]);
     // Surface the document's live kernel connection to the parent so the chat
     // header's kernel indicator reflects the real connected kernel instead of
     // the "disconnected"/"no-kernel" placeholder while the document is active.
@@ -258,23 +321,31 @@ export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride,
         };
     }, [documentKernel, onKernelChange]);
     const activeServiceManager = runtimeServiceManager;
-    const isRuntimeStarting = Boolean((String(runtimePodName || '').trim() ||
-        String(runtimeOverride?.baseUrl || '').trim()) &&
+    // Starting covers the supplied-services path too. Without it the spinner
+    // appeared and vanished in the same frame — the only sign that anything was
+    // happening — and then the editor sat empty while the kernel connected.
+    const isRuntimeStarting = Boolean((String(runtimeName || '').trim() ||
+        String(runtimeOverride?.baseUrl || '').trim() ||
+        providedServiceManager) &&
         !activeServiceManager);
     useProgressTask(`ephemeral-document-start-${documentId}`, isRuntimeStarting);
-    // Build the initial config once per documentId, without the demo content so
-    // the document starts empty and is either restored or filled by the agent.
-    const initialConfig = useMemo(() => {
-        // Drop the demo `editorState` and the examples `lexicalTheme`. Use the
-        // shared `commentTheme` (same as the document editor) so the Jupyter cell
-        // and rich-text nodes get the class names styled by jupyter-lexical CSS.
-        const { editorState: _ignored, theme: _theme, ...rest } = editorConfig;
-        return {
-            ...rest,
-            theme: commentTheme,
-            namespace: `ephemeral-document-${documentId}`,
-        };
-    }, [documentId]);
+    // The root extension, once per documentId: the shared Jupyter Lexical
+    // document with the `commentTheme` the jupyter-lexical stylesheet styles,
+    // focus on mount unless the host asked otherwise, and no content — the
+    // document starts empty and is either restored or filled by the agent
+    // (LoadContentPlugin) or by the room.
+    const extension = useMemo(() => defineExtension({
+        name: '@datalayer/agent-runtimes/EphemeralDocument',
+        namespace: `ephemeral-document-${documentId}`,
+        theme: commentTheme,
+        dependencies: [
+            JupyterLexicalExtension,
+            ...(autoFocus ? [AutoFocusExtension] : []),
+        ],
+        onError(error) {
+            console.error('[EphemeralDocument]', error);
+        },
+    }), [documentId, autoFocus]);
     const handleChange = useCallback((editorState) => {
         if (!onContentChange) {
             return;
@@ -288,6 +359,14 @@ export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride,
     }, [onContentChange]);
     const [floatingAnchorElem, setFloatingAnchorElem] = useState(null);
     const [, setIsLinkEditMode] = useState(false);
+    // A collaborative document is not here until its room has sent the first
+    // snapshot: an editor drawn before that is an empty page for a document
+    // that exists. Remembered per room, so another room waits again; without a
+    // room the content is local and known at mount.
+    const roomId = isCollaborative ? collaboration?.roomId : undefined;
+    const [initializedRoom, setInitializedRoom] = useState();
+    const documentReady = roomId === undefined || initializedRoom === roomId;
+    const onRoomInitialization = useCallback((isInitialized) => setInitializedRoom(isInitialized ? roomId : undefined), [roomId]);
     const onAnchorRef = (elem) => {
         if (elem !== null) {
             setFloatingAnchorElem(elem);
@@ -313,7 +392,7 @@ export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride,
             position: 'relative',
             overflow: 'hidden',
             bg: 'canvas.default',
-        }, children: activeServiceManager ? (_jsx(DatalayerThemeProvider, { colorMode: effectiveColorMode, theme: themeConfig.primerTheme, themeStyles: themeConfig.themeStyles, children: _jsx(JupyterReactTheme, { colormode: resolvedMode, backgroundColor: themeBackground, children: _jsx(Box, { sx: {
+        }, children: activeServiceManager ? (_jsx(ThemeRoot, { inherit: inheritTheme, colorMode: effectiveColorMode, themeConfig: themeConfig, children: _jsx(JupyterReactTheme, { colormode: resolvedMode, backgroundColor: themeBackground, children: _jsx(Box, { sx: {
                         position: 'absolute',
                         inset: 0,
                         display: 'flex',
@@ -322,6 +401,26 @@ export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride,
                         overflow: 'hidden',
                         overscrollBehaviorY: 'contain',
                         padding: 2,
+                        backgroundColor: themeBackground,
+                        /*
+                         * The variable Lexical's own stylesheets paint from.
+                         *
+                         * `Editor.css`, `Rich.css` and `TableNode.css` all write
+                         * `background: var(--bgColor-default, #fff)` — they are theme-
+                         * aware by design, and go white only where that variable is
+                         * undefined. In the lexical package's own examples it is
+                         * defined, because `LexicalPrimerThemeProvider` wraps them in a
+                         * `DatalayerThemeProvider`; here the host owns the theme and
+                         * this subtree never inherited it.
+                         *
+                         * Defining it here fixes every one of those rules at once,
+                         * including the ones nobody has hit yet. Chasing them class by
+                         * class is what the block below used to do, and it lost: an
+                         * emotion rule and `.editor-shell .editor-container` have the
+                         * same specificity, so which one wins comes down to stylesheet
+                         * order.
+                         */
+                        '--bgColor-default': themeBackground,
                         '& .editor-shell': {
                             backgroundColor: themeBackground,
                             borderRadius: 2,
@@ -384,13 +483,16 @@ export function EphemeralDocument({ documentId, runtimePodName, runtimeOverride,
                         '& [role="toolbar"][aria-label="Editor toolbar"]': {
                             backgroundColor: themeBackground,
                         },
-                    }, children: _jsx(LexicalConfigProvider, { lexicalId: documentId, serviceManager: activeServiceManager, children: _jsx(LexicalComposer, { initialConfig: initialConfig, children: _jsx(CommentsProvider, { children: _jsx(ToolbarContext, { children: _jsxs("div", { className: "editor-shell", children: [_jsx(DocumentToolbar, { setIsLinkEditMode: setIsLinkEditMode, extraItems: toolbarExtraItems }), _jsx("div", { className: "editor-container", children: _jsxs("div", { className: "editor-inner", children: [isCollaborative && collaboration ? (_jsx(LoroCollaborationPlugin, { id: collaboration.roomId, providerFactory: createWebsocketProvider, websocketUrl: collaboration.websocketUrl, shouldBootstrap: true, showCollaborators: true, username: collaborationName, cursorColor: collaborationColor, awarenessData: collaborationAwarenessData })) : null, _jsx(LexicalStatePlugin, {}), _jsx(RichTextPlugin, { contentEditable: _jsx("div", { className: "editor-scroller", children: _jsx("div", { className: "editor", ref: onAnchorRef, children: _jsx(ContentEditable, { className: "editor-input", "aria-label": "Ephemeral document editor" }) }) }), ErrorBoundary: LexicalErrorBoundary }), !isCollaborative && (_jsx(OnChangePlugin, { onChange: handleChange })), !isCollaborative && _jsx(HistoryPlugin, {}), _jsx(AutoFocusPlugin, {}), _jsx(ListPlugin, {}), _jsx(CheckListPlugin, {}), _jsx(LinkPlugin, {}), _jsx(AutoLinkPlugin, {}), _jsx(ListMaxIndentLevelPlugin, { maxDepth: 7 }), _jsx(MarkdownShortcutPlugin, { transformers: TRANSFORMERS }), !isCollaborative && (_jsx(LoadContentPlugin, { content: initialContent })), _jsx(CodeHighlightPlugin, {}), _jsx(ImagesPlugin, { captionsEnabled: false }), _jsx(ExcalidrawPlugin, {}), _jsx(TablePlugin, {}), _jsx(TableCellResizerPlugin, {}), _jsx(TableActionMenuPlugin, {}), _jsx(TableHoverActionsV2Plugin, {}), _jsx(CollapsiblePlugin, {}), _jsx(HorizontalRulePlugin, {}), _jsx(EquationsPlugin, {}), _jsx(YouTubePlugin, {}), _jsx(AutoEmbedPlugin, {}), _jsx(JupyterCellPlugin, {}), _jsx(ComponentPickerMenuPlugin, { kernel: documentKernel }), _jsx(JupyterInputOutputPlugin, { kernel: documentKernel }), floatingAnchorElem && (_jsxs(_Fragment, { children: [_jsx(DraggableBlockPlugin, { anchorElem: floatingAnchorElem }), _jsx(FloatingTextFormatToolbarPlugin, { anchorElem: floatingAnchorElem, setIsLinkEditMode: setIsLinkEditMode }), _jsx(CodeActionMenuPlugin, { anchorElem: floatingAnchorElem })] }))] }) })] }) }) }) }) }) }) }) })) : isRuntimeStarting ? (_jsxs(Box, { sx: {
-                height: '100%',
-                display: 'flex',
-                alignItems: 'center',
-                justifyContent: 'center',
-                gap: 2,
-                color: 'fg.muted',
-            }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Starting document..." })] })) : null }));
+                    }, children: _jsx(LexicalConfigProvider, { lexicalId: documentId, serviceManager: activeServiceManager, children: _jsx(LexicalExtensionComposer, { extension: extension, contentEditable: null, children: _jsx(CommentsProvider, { children: _jsx(ToolbarContext, { children: _jsxs("div", { className: "editor-shell", children: [showToolbar ? (_jsx(DocumentToolbar, { setIsLinkEditMode: setIsLinkEditMode, extraItems: toolbarExtraItems })) : null, _jsx("div", { className: "editor-container", children: _jsxs("div", { className: "editor-inner", children: [isCollaborative && collaboration ? (_jsx(LoroCollaborationPlugin, { id: collaboration.roomId, providerFactory: createWebsocketProvider, websocketUrl: collaboration.websocketUrl, shouldBootstrap: true, showCollaborators: true, username: collaborationName, cursorColor: collaborationColor, awarenessData: collaborationAwarenessData, onInitialization: onRoomInitialization })) : null, _jsx(LexicalStatePlugin, {}), documentReady ? (_jsx("div", { className: "editor-scroller", children: _jsx("div", { className: "editor", ref: onAnchorRef, children: _jsx(ContentEditable, { className: "editor-input", "aria-label": "Ephemeral document editor" }) }) })) : (_jsx(DocumentSkeleton, { maxWidth: "100%" })), !isCollaborative && (_jsx(OnChangePlugin, { onChange: handleChange })), _jsx(HistoryTogglePlugin, { disabled: isCollaborative }), !isCollaborative && (_jsx(LoadContentPlugin, { content: initialContent })), _jsx(TableCellResizerPlugin, {}), _jsx(TableActionMenuPlugin, {}), _jsx(TableHoverActionsV2Plugin, {}), _jsx(ComponentPickerMenuPlugin, { kernel: documentKernel }), _jsx(JupyterInputOutputPlugin, { kernel: documentKernel }), floatingAnchorElem && (_jsxs(_Fragment, { children: [_jsx(DraggableBlockPlugin, { anchorElem: floatingAnchorElem }), _jsx(FloatingTextFormatToolbarPlugin, { anchorElem: floatingAnchorElem, setIsLinkEditMode: setIsLinkEditMode }), _jsx(CodeActionMenuPlugin, { anchorElem: floatingAnchorElem })] }))] }) })] }) }) }) }) }) }) }) })) : isRuntimeStarting ? (
+        // The document's shape while its runtime starts, where the document
+        // will be — not a wheel, which says nothing about what is coming.
+        _jsx(ThemeRoot, { inherit: inheritTheme, colorMode: effectiveColorMode, themeConfig: themeConfig, children: _jsx(Box, { sx: {
+                    position: 'absolute',
+                    inset: 0,
+                    display: 'flex',
+                    flexDirection: 'column',
+                    padding: 2,
+                    backgroundColor: themeBackground,
+                }, children: _jsx(DocumentSkeleton, { label: "Starting the document", maxWidth: "100%" }) }) })) : null }));
 }
 export default EphemeralDocument;

package/lib/chat/header/ChatHeader.d.ts

@@ -38,5 +38,5 @@ export interface ChatHeaderProps {
  * />
  * ```
  */
-export declare function ChatHeader({ title, description, connectionState, runtimeBusy, onReconnect, onDisconnect, onLogout, onCollapsePanel, }: ChatHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatHeader({ title, description, connectionState, runtimeBusy, onReconnect, onDisconnect, onLogout, onCollapsePanel, }: ChatHeaderProps): import("react").JSX.Element;
 export default ChatHeader;

package/lib/chat/header/ChatHeaderBase.d.ts

@@ -18,6 +18,13 @@ export declare function toRuntimeExecutionState(runtimeStatus?: RuntimeStatus |
 export interface ChatBaseHeaderProps {
     title?: string;
     subtitle?: string;
+    /**
+     * Why the chat is off, shown beside the title.
+     *
+     * The header is where someone looks when a control does not respond, so the
+     * reason belongs here rather than in a tooltip they would have to find.
+     */
+    disableReason?: string;
     brandIcon?: ReactNode;
     headerContent?: ReactNode;
     headerActions?: ReactNode;
@@ -60,6 +67,8 @@ export interface ChatBaseHeaderProps {
     chatViewMode?: ChatViewMode;
     /** Callback when view mode changes */
     onChatViewModeChange?: (mode: ChatViewMode) => void;
+    /** Modes shown greyed out: the sidebar, when the host has no mount point. */
+    disabledViewModes?: readonly ChatViewMode[];
     /** Show the companion-surface segmented control (None / Notebook / Document). */
     showEphemeralSurfaceControl?: boolean;
     /** Whether the Notebook option is available in the surface control. */
@@ -71,5 +80,5 @@ export interface ChatBaseHeaderProps {
     /** Callback fired when the user changes the companion-surface mode. */
     onEphemeralSurfaceModeChange?: (mode: EphemeralSurfaceMode) => void;
 }
-export declare function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, headerActions, showInformation, onInformationClick, padding, kernelIndicatorState, kernelIndicatorPlacement, runtimeStatus, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, headerButtons, messageCount, onNewChat, onClear, chatViewMode, onChatViewModeChange, showEphemeralSurfaceControl, enableEphemeralNotebookOption, enableEphemeralDocumentOption, ephemeralSurfaceMode, onEphemeralSurfaceModeChange, }: ChatBaseHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatBaseHeader({ title, subtitle, disableReason, brandIcon, headerContent, headerActions, showInformation, onInformationClick, padding, kernelIndicatorState, kernelIndicatorPlacement, runtimeStatus, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, headerButtons, messageCount, onNewChat, onClear, chatViewMode, onChatViewModeChange, disabledViewModes, showEphemeralSurfaceControl, enableEphemeralNotebookOption, enableEphemeralDocumentOption, ephemeralSurfaceMode, onEphemeralSurfaceModeChange, }: ChatBaseHeaderProps): import("react").JSX.Element;
 export {};

package/lib/chat/header/ChatHeaderBase.js

@@ -1,9 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Heading, IconButton, Text, Tooltip, Truncate } from '@primer/react';
+import { Heading, IconButton, Label, Text, Truncate } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { KernelIndicator } from '@datalayer/jupyter-react';
-import { PlusIcon, TrashIcon, GearIcon, CommentDiscussionIcon, DeviceMobileIcon, SidebarExpandIcon, InfoIcon, RowsIcon, FileIcon, CircleSlashIcon, } from '@primer/octicons-react';
+import { PlusIcon, TrashIcon, GearIcon, InfoIcon, } from '@primer/octicons-react';
+import { ChatViewModeToggle } from './ChatViewModeToggle';
 import { AiAgentIcon } from '@datalayer/icons-react';
+import { EphemeralSurfaceControl } from '../EphemeralSurfaceControl';
 export function toRuntimeExecutionState(runtimeStatus) {
     if (!runtimeStatus) {
         return undefined;
@@ -29,9 +31,23 @@ export function toRuntimeExecutionState(runtimeStatus) {
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, headerActions, showInformation, onInformationClick, padding, kernelIndicatorState, kernelIndicatorPlacement = 'left', runtimeStatus, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, headerButtons, messageCount, onNewChat, onClear, chatViewMode, onChatViewModeChange, showEphemeralSurfaceControl = false, enableEphemeralNotebookOption = false, enableEphemeralDocumentOption = false, ephemeralSurfaceMode = 'none', onEphemeralSurfaceModeChange, }) {
+export function ChatBaseHeader({ title, subtitle, disableReason, brandIcon, headerContent, headerActions, showInformation, onInformationClick, padding, kernelIndicatorState, kernelIndicatorPlacement = 'left', runtimeStatus, kernel, kernelEnvironmentName, kernelCpu, kernelMemory, kernelGpu, headerButtons, messageCount, onNewChat, onClear, chatViewMode, onChatViewModeChange, disabledViewModes = [], showEphemeralSurfaceControl = false, enableEphemeralNotebookOption = false, enableEphemeralDocumentOption = false, ephemeralSurfaceMode = 'none', onEphemeralSurfaceModeChange, }) {
     const effectiveIndicatorState = kernelIndicatorState ?? toRuntimeExecutionState(runtimeStatus);
-    const kernelIndicatorElement = kernel ? (_jsx(KernelIndicator, { kernel: kernel, environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "s", bordered: false })) : (_jsx(KernelIndicator, { state: effectiveIndicatorState ?? 'undefined', environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "s", bordered: false }));
+    /*
+     * No indicator where there is nothing to indicate.
+     *
+     * It used to fall back to `'undefined'` with no kernel and no state, which
+     * draws a full control — dot, label and a details overlay reading
+     * "State: undefined, Kernel: unknown-kernel, Server: unknown-url" down to
+     * the last field. A reader cannot tell that apart from a runtime that has
+     * genuinely gone wrong, so a host that simply never wired the indicator up
+     * was reporting a broken sandbox on every page.
+     *
+     * A host with something to say passes a `kernel`, a state, or a runtime
+     * status. Passing none of the three is not a state; it is silence, and the
+     * honest rendering of silence is nothing at all.
+     */
+    const kernelIndicatorElement = kernel ? (_jsx(KernelIndicator, { kernel: kernel, environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "s", bordered: false })) : effectiveIndicatorState ? (_jsx(KernelIndicator, { state: effectiveIndicatorState, environmentName: kernelEnvironmentName, cpu: kernelCpu, memory: kernelMemory, gpu: kernelGpu, position: "s", bordered: false })) : null;
     return (_jsx(Box, { sx: {
             display: 'flex',
             flexDirection: 'column',
@@ -64,102 +80,5 @@ export function ChatBaseHeader({ title, subtitle, brandIcon, headerContent, head
                                         color: 'fg.muted',
                                         minWidth: 0,
                                         maxWidth: '100%',
-                                    }, children: _jsx(Truncate, { title: subtitle, maxWidth: "40ch", children: subtitle }) }))] })), headerContent, showInformation && (_jsx(IconButton, { icon: InfoIcon, "aria-label": "Information", variant: "invisible", size: "small", onClick: onInformationClick })), kernelIndicatorPlacement === 'center' && kernelIndicatorElement] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, flexShrink: 0 }, children: [kernelIndicatorPlacement === 'right' && kernelIndicatorElement, headerButtons?.showNewChat && (_jsx(IconButton, { icon: PlusIcon, "aria-label": "New chat", variant: "invisible", size: "small", onClick: onNewChat })), headerButtons?.showClear && messageCount > 0 && (_jsx(IconButton, { icon: TrashIcon, "aria-label": "Clear messages", variant: "invisible", size: "small", onClick: onClear })), headerButtons?.showSettings && (_jsx(IconButton, { icon: GearIcon, "aria-label": "Settings", variant: "invisible", size: "small", onClick: headerButtons.onSettings })), showEphemeralSurfaceControl && (_jsx(Box, { sx: {
-                                display: 'inline-flex',
-                                alignItems: 'center',
-                                bg: 'neutral.muted',
-                                borderRadius: '6px',
-                                p: '2px',
-                                gap: '1px',
-                            }, children: [
-                                {
-                                    mode: 'none',
-                                    icon: CircleSlashIcon,
-                                    label: 'Chat only',
-                                    enabled: true,
-                                },
-                                {
-                                    mode: 'notebook',
-                                    icon: RowsIcon,
-                                    label: 'Notebook',
-                                    enabled: enableEphemeralNotebookOption,
-                                },
-                                {
-                                    mode: 'document',
-                                    icon: FileIcon,
-                                    label: 'Document',
-                                    enabled: enableEphemeralDocumentOption,
-                                },
-                            ]
-                                .filter(({ enabled }) => enabled)
-                                .map(({ mode, icon: ModeIcon, label }) => (_jsx(Tooltip, { text: label, direction: "n", children: _jsx(Box, { as: "button", "aria-label": label, onClick: () => onEphemeralSurfaceModeChange?.(mode), sx: {
-                                        display: 'inline-flex',
-                                        alignItems: 'center',
-                                        justifyContent: 'center',
-                                        width: 26,
-                                        height: 24,
-                                        borderRadius: '4px',
-                                        border: 'none',
-                                        cursor: 'pointer',
-                                        bg: ephemeralSurfaceMode === mode
-                                            ? 'canvas.default'
-                                            : 'transparent',
-                                        boxShadow: ephemeralSurfaceMode === mode
-                                            ? 'shadow.small'
-                                            : 'none',
-                                        color: ephemeralSurfaceMode === mode
-                                            ? 'fg.default'
-                                            : 'fg.muted',
-                                        transition: 'all 0.15s ease',
-                                        '&:hover': {
-                                            color: 'fg.default',
-                                            bg: ephemeralSurfaceMode === mode
-                                                ? 'canvas.default'
-                                                : 'neutral.subtle',
-                                        },
-                                    }, children: _jsx(ModeIcon, { size: 14 }) }) }, mode))) })), chatViewMode && onChatViewModeChange && (_jsx(Box, { sx: {
-                                display: 'inline-flex',
-                                alignItems: 'center',
-                                bg: 'neutral.muted',
-                                borderRadius: '6px',
-                                p: '2px',
-                                gap: '1px',
-                            }, children: [
-                                {
-                                    mode: 'floating',
-                                    icon: CommentDiscussionIcon,
-                                    label: 'Full-height popup',
-                                },
-                                {
-                                    mode: 'floating-small',
-                                    icon: DeviceMobileIcon,
-                                    label: 'Floating popup',
-                                },
-                                {
-                                    mode: 'sidebar',
-                                    icon: SidebarExpandIcon,
-                                    label: 'Sidebar panel',
-                                },
-                            ].map(({ mode, icon: ModeIcon, label }) => (_jsx(Tooltip, { text: label, direction: "n", children: _jsx(Box, { as: "button", "aria-label": label, onClick: () => onChatViewModeChange(mode), sx: {
-                                        display: 'inline-flex',
-                                        alignItems: 'center',
-                                        justifyContent: 'center',
-                                        width: 26,
-                                        height: 24,
-                                        borderRadius: '4px',
-                                        border: 'none',
-                                        cursor: 'pointer',
-                                        bg: chatViewMode === mode
-                                            ? 'canvas.default'
-                                            : 'transparent',
-                                        boxShadow: chatViewMode === mode ? 'shadow.small' : 'none',
-                                        color: chatViewMode === mode ? 'fg.default' : 'fg.muted',
-                                        transition: 'all 0.15s ease',
-                                        '&:hover': {
-                                            color: 'fg.default',
-                                            bg: chatViewMode === mode
-                                                ? 'canvas.default'
-                                                : 'neutral.subtle',
-                                        },
-                                    }, children: _jsx(ModeIcon, { size: 14 }) }) }, mode))) })), headerActions] })] }) }));
+                                    }, children: _jsx(Truncate, { title: subtitle, maxWidth: "40ch", children: subtitle }) }))] })), disableReason && (_jsx(Label, { variant: "attention", sx: { flexShrink: 0 }, children: disableReason })), headerContent, showInformation && (_jsx(IconButton, { icon: InfoIcon, "aria-label": "Information", variant: "invisible", size: "small", onClick: onInformationClick })), kernelIndicatorPlacement === 'center' && kernelIndicatorElement] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 1, flexShrink: 0 }, children: [kernelIndicatorPlacement === 'right' && kernelIndicatorElement, headerButtons?.showNewChat && (_jsx(IconButton, { icon: PlusIcon, "aria-label": "New chat", variant: "invisible", size: "small", onClick: onNewChat })), headerButtons?.showClear && messageCount > 0 && (_jsx(IconButton, { icon: TrashIcon, "aria-label": "Clear messages", variant: "invisible", size: "small", onClick: onClear })), headerButtons?.showSettings && (_jsx(IconButton, { icon: GearIcon, "aria-label": "Settings", variant: "invisible", size: "small", onClick: headerButtons.onSettings })), showEphemeralSurfaceControl && (_jsx(EphemeralSurfaceControl, { mode: ephemeralSurfaceMode, onChange: onEphemeralSurfaceModeChange, enableNotebook: enableEphemeralNotebookOption, enableDocument: enableEphemeralDocumentOption })), chatViewMode && onChatViewModeChange && (_jsx(ChatViewModeToggle, { value: chatViewMode, onChange: onChatViewModeChange, disabledModes: disabledViewModes })), headerActions] })] }) }));
 }

package/lib/chat/header/ChatViewModeToggle.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The segmented toggle for how a chat is shown — the four modes of
+ * `CHAT_VIEW_MODES`, drawn as icons in a pill, the current one raised.
+ *
+ * It grew up in the chat header, and lives apart from it so the same
+ * control can stand elsewhere: a composer floating over a page as a
+ * draggable card carries it in its own footer, where the person deciding
+ * how the chat should sit has the chat under their hands. The rules — the
+ * order, the words, which modes are greyed out — stay in `viewModes.ts`;
+ * this is only their drawing.
+ *
+ * @module chat/header/ChatViewModeToggle
+ */
+import type { JSX } from 'react';
+import { type Icon } from '@primer/octicons-react';
+import type { ChatViewMode } from '../../types/chat';
+/** The drawing of each mode. */
+export declare const VIEW_MODE_ICONS: Record<ChatViewMode, Icon>;
+export type ChatViewModeToggleProps = {
+    /** The mode the chat is in now. */
+    value?: ChatViewMode;
+    /** The mode the person picked. */
+    onChange: (mode: ChatViewMode) => void;
+    /** Modes shown greyed out: the sidebar, when the host has no mount point. */
+    disabledModes?: readonly ChatViewMode[];
+    /** Where the tooltips open. Above by default; below for a control at the top of its window. */
+    tooltipDirection?: 'n' | 's';
+};
+export declare function ChatViewModeToggle({ value, onChange, disabledModes, tooltipDirection, }: ChatViewModeToggleProps): JSX.Element;

package/lib/chat/header/ChatViewModeToggle.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Tooltip } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { CommentDiscussionIcon, DeviceMobileIcon, GrabberIcon, SidebarExpandIcon, } from '@primer/octicons-react';
+import { CHAT_VIEW_MODES, SIDEBAR_NEEDS_MOUNT_POINT } from '../viewModes';
+/** The drawing of each mode. */
+export const VIEW_MODE_ICONS = {
+    floating: CommentDiscussionIcon,
+    'floating-small': DeviceMobileIcon,
+    'floating-draggable': GrabberIcon,
+    sidebar: SidebarExpandIcon,
+};
+export function ChatViewModeToggle({ value, onChange, disabledModes = [], tooltipDirection = 'n', }) {
+    return (_jsx(Box, { role: "group", "aria-label": "Display mode", "data-chat-view-mode-toggle": "", sx: {
+            display: 'inline-flex',
+            alignItems: 'center',
+            bg: 'neutral.muted',
+            borderRadius: '6px',
+            p: '2px',
+            gap: '1px',
+        }, children: CHAT_VIEW_MODES.map(({ mode, label }) => {
+            const ModeIcon = VIEW_MODE_ICONS[mode];
+            const selected = value === mode;
+            /* Greyed rather than left out: the person sees the mode exists, and
+               that this page has no place for it. */
+            const disabled = disabledModes.includes(mode);
+            return (_jsx(Tooltip, { text: disabled && mode === 'sidebar'
+                    ? `${label} — ${SIDEBAR_NEEDS_MOUNT_POINT}`
+                    : label, direction: tooltipDirection, children: _jsx(Box, { as: "button", type: "button", "aria-label": label, "aria-pressed": selected, "aria-disabled": disabled || undefined, onClick: () => {
+                        if (!disabled) {
+                            onChange(mode);
+                        }
+                    }, sx: {
+                        display: 'inline-flex',
+                        alignItems: 'center',
+                        justifyContent: 'center',
+                        width: 26,
+                        height: 24,
+                        borderRadius: '4px',
+                        border: 'none',
+                        cursor: disabled ? 'not-allowed' : 'pointer',
+                        opacity: disabled ? 0.45 : 1,
+                        bg: selected ? 'canvas.default' : 'transparent',
+                        boxShadow: selected ? 'shadow.small' : 'none',
+                        color: selected ? 'fg.default' : 'fg.muted',
+                        transition: 'all 0.15s ease',
+                        '&:hover': disabled
+                            ? {}
+                            : {
+                                color: 'fg.default',
+                                bg: selected ? 'canvas.default' : 'neutral.subtle',
+                            },
+                    }, children: _jsx(ModeIcon, { size: 14 }) }) }, mode));
+        }) }));
+}

package/lib/chat/index.d.ts

@@ -49,14 +49,17 @@
  * ```
  */
 export { ChatMessages, type ChatMessagesProps } from './messages/ChatMessages';
+export { ChatMessageList, type ChatMessageListProps, } from './messages/ChatMessageList';
+export { NotebookToolSurfaces, notebookToolSurfacesRenderer, } from './messages/NotebookToolSurfaces';
 export { ChatSidebar, type ChatSidebarProps } from './ChatSidebar';
 export { ChatStandalone } from './ChatStandalone';
 export { ChatBase } from './base/ChatBase';
-export { InputPrompt, type InputPromptProps } from './prompt';
+export { InputPrompt, type InputPromptProps, InputPromptBase, type InputPromptBaseProps, } from './prompt';
 export { McpStatusIndicator, type McpStatusIndicatorProps, type McpServerStatus, type McpAggregateStatus, SandboxStatusIndicator, type SandboxStatusIndicatorProps, type SandboxAggregateStatus, type SandboxWsStatus, } from './indicators';
 export { PoweredByTag, type PoweredByTagProps } from './display/PoweredByTag';
 export { FloatingBrandButton, type FloatingBrandButtonProps, } from './display/FloatingBrandButton';
 export { ChatHeader, type ChatHeaderProps } from './header/ChatHeader';
+export { ChatViewModeToggle, VIEW_MODE_ICONS, type ChatViewModeToggleProps, } from './header/ChatViewModeToggle';
 export { MessagePart, type MessagePartProps, TextPart, type TextPartProps, ReasoningPart, type ReasoningPartProps, ToolPart, type ToolPartProps, DynamicToolPart, type DynamicToolPartProps, } from './parts';
 export { ToolCallDisplay, type ToolCallDisplayProps } from './tools';
 export { ToolApprovalDialog, useToolApprovalDialog, type ToolApprovalDialogProps, } from './tools/ToolApprovalDialog';
@@ -65,3 +68,4 @@ export { Chat, type ChatProps } from './Chat';
 export { ChatFloating, type ChatFloatingProps } from './ChatFloating';
 export { ChatInline, type ChatInlineProps, type ChatInlineProtocolConfig, } from './ChatInline';
 export { AgentRuntimeChat, type AgentRuntimeChatProps, } from '../agents/AgentRuntimeChat';
+export * from './EphemeralSurfaceControl';