@datalayer/agent-runtimes 1.0.28 → 1.3.10

package/lib/chat/display/EmptyState.d.ts

@@ -8,6 +8,20 @@
  */
 import { type ReactNode } from 'react';
 import type { EmptyStateConfig, Suggestion } from '../../types/chat';
+export { groupSuggestions } from './groupSuggestions';
+/**
+ * How wide a suggestion chip stands, in pixels — fixed, not a cap.
+ *
+ * An opener is a whole request in the words somebody would type, and some
+ * are a sentence long — "Explain this notebook cell by cell, as if I am new
+ * to Python" — while others are a few words — "Rerun with another model".
+ * Sized to their own words, a row of them read as uneven lines of text
+ * rather than as one set of options. One width, for every chip and every
+ * place that draws them (the empty state below and the page layout's row
+ * under the composer); past it the label truncates, and the chip's own
+ * title still carries the whole sentence on hover.
+ */
+export declare const SUGGESTION_CHIP_WIDTH = 140;
 export interface ChatEmptyStateProps {
     /** Empty-state configuration (icon, title, subtitle, render) */
     emptyState?: EmptyStateConfig;
@@ -24,4 +38,4 @@ export interface ChatEmptyStateProps {
     /** Whether clicking a suggestion auto-submits it */
     submitOnSuggestionClick?: boolean;
 }
-export declare function ChatEmptyState({ emptyState, brandIcon, description, suggestions, onSuggestionSubmit, onSuggestionFill, submitOnSuggestionClick, }: ChatEmptyStateProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatEmptyState({ emptyState, brandIcon, description, suggestions, onSuggestionSubmit, onSuggestionFill, submitOnSuggestionClick, }: ChatEmptyStateProps): import("react").JSX.Element;

package/lib/chat/display/EmptyState.js

@@ -2,6 +2,21 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { Text, LabelGroup, Label, Truncate, ThemeProvider, } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { AiAgentIcon } from '@datalayer/icons-react';
+import { groupSuggestions } from './groupSuggestions';
+export { groupSuggestions } from './groupSuggestions';
+/**
+ * How wide a suggestion chip stands, in pixels — fixed, not a cap.
+ *
+ * An opener is a whole request in the words somebody would type, and some
+ * are a sentence long — "Explain this notebook cell by cell, as if I am new
+ * to Python" — while others are a few words — "Rerun with another model".
+ * Sized to their own words, a row of them read as uneven lines of text
+ * rather than as one set of options. One width, for every chip and every
+ * place that draws them (the empty state below and the page layout's row
+ * under the composer); past it the label truncates, and the chip's own
+ * title still carries the whole sentence on hover.
+ */
+export const SUGGESTION_CHIP_WIDTH = 140;
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
@@ -18,24 +33,75 @@ export function ChatEmptyState({ emptyState, brandIcon, description, suggestions
             onSuggestionFill?.(suggestion.message);
         }
     };
+    /*
+     * The openers in blocks: the ungrouped ones first, as the one row they
+     * always were, then each group under its own heading in the order the
+     * groups first appear. A team's openers and, beneath them, the addressed
+     * member's own is the case this draws — and when the host gave the empty
+     * state *levels*, each level takes its own group's openers and the blocks
+     * below are only what no level claimed.
+     */
+    const sections = emptyState?.sections ?? [];
+    const claimed = new Set(sections.map(section => section.group));
+    const blocks = groupSuggestions((suggestions ?? []).filter(suggestion => suggestion.group === undefined || !claimed.has(suggestion.group)));
+    const chips = (items) => (_jsx(LabelGroup, { sx: { justifyContent: 'center' }, children: items.map((suggestion, index) => (_jsx(Label, { variant: "accent", 
+            // The whole request: the chip may show only its summary.
+            title: suggestion.message, sx: {
+                cursor: 'pointer',
+                display: 'inline-flex',
+                alignItems: 'center',
+                width: SUGGESTION_CHIP_WIDTH,
+                flex: `0 0 ${SUGGESTION_CHIP_WIDTH}px`,
+                '&:hover': {
+                    bg: 'accent.emphasis',
+                    color: 'var(--button-primary-fgColor-rest)',
+                    borderColor: 'accent.emphasis',
+                },
+            }, onClick: () => handleSuggestionClick(suggestion), children: _jsx(Truncate, { title: suggestion.message, maxWidth: "100%", sx: { minWidth: 0 }, children: suggestion.title }) }, index))) }));
     return (_jsx(ThemeProvider, { children: _jsxs(Box, { sx: {
                 display: 'flex',
                 flexDirection: 'column',
+                // Centred across the column, anchored to its top: the introduction
+                // is where a conversation starts, and the first message should
+                // appear under it rather than push it around the canvas.
                 alignItems: 'center',
-                justifyContent: 'center',
-                height: '100%',
+                justifyContent: 'flex-start',
                 p: 4,
                 color: 'fg.muted',
                 textAlign: 'center',
                 gap: 2,
-            }, children: [emptyState?.icon || brandIcon || _jsx(AiAgentIcon, { colored: true, size: 48 }), _jsx(Text, { sx: { fontSize: 2 }, children: emptyState?.title || 'Start a conversation' }), (emptyState?.subtitle || description) && (_jsx(Text, { sx: { fontSize: 1 }, children: emptyState?.subtitle || description })), suggestions && suggestions.length > 0 && (_jsx(LabelGroup, { sx: { mt: 2, justifyContent: 'center' }, children: suggestions.map((suggestion, index) => (_jsx(Label, { variant: "accent", title: suggestion.title, sx: {
-                            cursor: 'pointer',
-                            display: 'inline-flex',
-                            alignItems: 'center',
-                            '&:hover': {
-                                bg: 'accent.emphasis',
-                                color: 'var(--button-primary-fgColor-rest)',
-                                borderColor: 'accent.emphasis',
-                            },
-                        }, onClick: () => handleSuggestionClick(suggestion), children: _jsx(Box, { sx: { width: 140, maxWidth: 140, minWidth: 140 }, children: _jsx(Truncate, { title: suggestion.title, maxWidth: "100%", children: suggestion.title }) }) }, index))) }))] }) }));
+            }, children: [sections.length > 0 ? (
+                /*
+                 * Levels: the first at full size, the ones under it a step
+                 * smaller and set off by a rule — a team, then the member of it
+                 * being addressed, each introducing itself and offering its own
+                 * openers.
+                 */
+                sections.map((section, level) => (_jsxs(Box, { sx: {
+                        display: 'flex',
+                        flexDirection: 'column',
+                        alignItems: 'center',
+                        gap: 2,
+                        width: '100%',
+                        ...(level > 0
+                            ? {
+                                mt: 3,
+                                pt: 3,
+                                borderTop: '1px solid',
+                                borderColor: 'border.muted',
+                            }
+                            : null),
+                    }, children: [section.icon, _jsx(Text, { sx: {
+                                fontSize: level === 0 ? 2 : 1,
+                                fontWeight: level === 0 ? 'normal' : 'semibold',
+                            }, children: section.title }), section.subtitle ? (_jsx(Text, { sx: { fontSize: level === 0 ? 1 : 0 }, children: section.subtitle })) : null, (() => {
+                            const own = (suggestions ?? []).filter(suggestion => suggestion.group === section.group);
+                            return own.length > 0 ? chips(own) : null;
+                        })()] }, section.group)))) : (_jsxs(_Fragment, { children: [emptyState?.icon || brandIcon || _jsx(AiAgentIcon, { colored: true, size: 48 }), _jsx(Text, { sx: { fontSize: 2 }, children: emptyState?.title || 'Start a conversation' }), (emptyState?.subtitle || description) && (_jsx(Text, { sx: { fontSize: 1 }, children: emptyState?.subtitle || description }))] })), blocks.map(block => (_jsxs(Box, { sx: {
+                        display: 'flex',
+                        flexDirection: 'column',
+                        alignItems: 'center',
+                        gap: 1,
+                        mt: 2,
+                    }, children: [block.group ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: block.group })) : null, chips(block.items)] }, block.group ?? '')))] }) }));
 }

package/lib/chat/display/FloatingBrandButton.d.ts

@@ -30,5 +30,5 @@ export interface FloatingBrandButtonProps {
  * Floating brand button component
  * A circular button that floats in a corner to open/close the chat
  */
-export declare function FloatingBrandButton({ isOpen, onToggle, position, icon, tooltip, unreadCount, className, brandColor, }: FloatingBrandButtonProps): import("react/jsx-runtime").JSX.Element;
+export declare function FloatingBrandButton({ isOpen, onToggle, position, icon, tooltip, unreadCount, className, brandColor, }: FloatingBrandButtonProps): React.JSX.Element;
 export default FloatingBrandButton;

package/lib/chat/display/PoweredByTag.d.ts

@@ -22,5 +22,5 @@ export interface PoweredByTagProps {
  * PoweredBy tag component
  * Displays a "Powered by X" branding tag
  */
-export declare function PoweredByTag({ show, brandName, brandUrl, brandIcon, }: PoweredByTagProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function PoweredByTag({ show, brandName, brandUrl, brandIcon, }: PoweredByTagProps): React.JSX.Element | null;
 export default PoweredByTag;

package/lib/chat/display/groupSuggestions.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Openers in blocks.
+ *
+ * A suggestion may name a `group`; the ungrouped ones come first, as one
+ * block, and each group follows as a block of its own in the order it first
+ * appears. The empty state draws the blocks as rows of chips under headings
+ * and the composer's suggestions menu as sections — the same shape, so a
+ * team's openers and the addressed member's own read the same in both.
+ *
+ * @module chat/display/groupSuggestions
+ */
+/** The least a suggestion needs to be grouped. */
+export type Groupable = {
+    group?: string;
+};
+export type SuggestionBlock<T extends Groupable> = {
+    group?: string;
+    items: T[];
+};
+/** The openers in blocks: the ungrouped first, then each group as it first appears. */
+export declare function groupSuggestions<T extends Groupable>(suggestions: T[]): SuggestionBlock<T>[];

package/lib/chat/display/groupSuggestions.js

@@ -0,0 +1,18 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** The openers in blocks: the ungrouped first, then each group as it first appears. */
+export function groupSuggestions(suggestions) {
+    const blocks = [];
+    for (const suggestion of suggestions) {
+        const block = blocks.find(entry => entry.group === suggestion.group);
+        if (block) {
+            block.items.push(suggestion);
+        }
+        else {
+            blocks.push({ group: suggestion.group, items: [suggestion] });
+        }
+    }
+    return blocks.sort((left, right) => left.group === undefined ? -1 : right.group === undefined ? 1 : 0);
+}

package/lib/chat/document/EphemeralDocument.d.ts

@@ -1,8 +1,27 @@
+/**
+ * EphemeralDocument — an in-memory Lexical rich-text document rendered next to
+ * the chat.
+ *
+ * This is the document analogue of {@link EphemeralNotebook}. The Lexical
+ * editor state lives purely in memory and is mirrored into the agent-runtime
+ * Zustand store (`ephemeralDocumentModels`) so the document survives navigating
+ * away from and back to the same runtime page. While mounted, its lexical
+ * frontend tools are reported upward via `onToolsReady` so the agent can drive
+ * the document blocks (insert / update / delete / read).
+ *
+ * IMPORTANT: this module statically imports `@datalayer/jupyter-lexical`, which
+ * initialises Lumino-backed nodes on load. It is therefore lazy-loaded by
+ * `ChatBase` (via `React.lazy`) so notebook-only chats never pull in lexical.
+ *
+ * @module chat/document/EphemeralDocument
+ */
+import '@datalayer/jupyter-react/lib/css/PrismCss';
+import type { JSX } from 'react';
+import { ServiceManager } from '@jupyterlab/services';
 import type { IKernelConnection } from '@jupyterlab/services/lib/kernel/kernel';
 import { type ToolbarItem } from '@datalayer/primer-addons';
 import type { FrontendToolDefinition } from '../../types/tools';
 import type { EphemeralRuntimeOverride } from '../notebook/EphemeralNotebook';
-import '@datalayer/jupyter-react/lib/css/PrismCss';
 import '@datalayer/jupyter-lexical/style/index.css';
 /**
  * Real-time collaboration configuration for the ephemeral document.
@@ -38,9 +57,27 @@ export interface EphemeralDocumentProps {
      */
     documentId: string;
     /** Preferred runtime pod name to bind the document kernel to. */
-    runtimePodName?: string;
+    runtimeName?: string;
     /** Optional explicit runtime endpoint (agent-node tunnel proxy path). */
     runtimeOverride?: EphemeralRuntimeOverride;
+    /**
+     * Services the host already has, used instead of building some from a URL.
+     *
+     * An in-page sandbox — JupyterLite over Pyodide — has no address to connect
+     * to: it *is* the services. Without this the document had no way to reach
+     * such a kernel and rendered an empty editor with nothing in the console,
+     * because "no base url" was a silent early return rather than a failure.
+     *
+     * The host keeps ownership: a manager passed in is never disposed here.
+     */
+    serviceManager?: ServiceManager.IManager;
+    /**
+     * Kernel to join on that manager, rather than starting another.
+     *
+     * The agent and the reader should be looking at one kernel; starting a
+     * second one beside it is how they end up with different variables.
+     */
+    kernelId?: string;
     /** Optional theme variant override from host chat context. */
     themeVariant?: string;
     /** Optional color mode override from host chat context. */
@@ -73,10 +110,37 @@ export interface EphemeralDocumentProps {
      * change it — the same way the notebook surface does through the
      * `extraItems` of its toolbar.
      */
+    /**
+     * Render without wrapping the content in a theme provider.
+     *
+     * For a host that already owns one — the LOOP workspace, where the entry
+     * point provides the theme and the views inherit it. Nested providers fight
+     * over `BaseStyles` and font tokens, and the inner one wins for the wrong
+     * reasons.
+     */
+    inheritTheme?: boolean;
     toolbarExtraItems?: ToolbarItem[];
+    /**
+     * Whether to draw a toolbar at all. Defaults to true.
+     *
+     * For a host where the toolbar is somebody's to provide — the LOOP
+     * workspace, where a plugin owns it and can be switched off. `false` draws
+     * no bar rather than an empty one: an empty bar still costs a row and a
+     * border, and reads as broken rather than as absent.
+     */
+    showToolbar?: boolean;
+    /**
+     * Whether the document takes the caret once its editor mounts. Defaults to
+     * `true`.
+     *
+     * `false` for a host whose composer already asked for the caret on mount:
+     * this editor only exists once a sandbox — and, for the ephemeral case, a
+     * kernel — has finished starting, well after a chat composer's own
+     * `autoFocus` effect has already run and stopped watching, so the
+     * document's unconditional autofocus otherwise steals the caret back a
+     * moment later purely by mounting second.
+     */
+    autoFocus?: boolean;
 }
-/**
- * Renders an in-memory Lexical document backed by a sandbox kernel.
- */
-export declare function EphemeralDocument({ documentId, runtimePodName, runtimeOverride, themeVariant, colorMode, content, onContentChange, onToolsReady, onKernelChange, collaboration, toolbarExtraItems, }: EphemeralDocumentProps): import("react/jsx-runtime").JSX.Element;
+export declare function EphemeralDocument({ documentId, runtimeName, runtimeOverride, serviceManager: providedServiceManager, kernelId, themeVariant, colorMode, content, onContentChange, onToolsReady, onKernelChange, collaboration, toolbarExtraItems, showToolbar, inheritTheme, autoFocus, }: EphemeralDocumentProps): JSX.Element;
 export default EphemeralDocument;

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;