@datalayer/agent-runtimes 1.0.29 → 1.3.10

package/lib/examples/LexicalAgentSidebarExample.js

@@ -4,7 +4,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Agent Runtime Lexical Example - Next generation chat with Lexical editor.
+ * Lexical Example - Next generation chat with Lexical editor.
  *
  * This example demonstrates using the chat component with:
  * - Lexical editor integration
@@ -18,67 +18,48 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  * @module examples/LexicalAgentSidebarExample
  */
 import '@datalayer/jupyter-react/lib/css/PrismCss';
-import { useCallback, useEffect, useMemo, useState } from 'react';
-import { LexicalComposer } from '@lexical/react/LexicalComposer';
-import { RichTextPlugin } from '@lexical/react/LexicalRichTextPlugin';
+import { useCallback, useState } from 'react';
+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 { Box } from '@datalayer/primer-addons';
 import { useJupyter } from '@datalayer/jupyter-react';
-import { ThemedJupyterProvider } from './utils/themedProvider';
-import { ComponentPickerMenuPlugin, JupyterCellPlugin, JupyterInputOutputPlugin, DraggableBlockPlugin, ImagesPlugin, HorizontalRulePlugin, EquationsPlugin, YouTubePlugin, ExcalidrawPlugin, CollapsiblePlugin, AutoLinkPlugin, AutoEmbedPlugin, FloatingTextFormatToolbarPlugin, CodeActionMenuPlugin, ListMaxIndentLevelPlugin, LexicalConfigProvider, LexicalStatePlugin, TableCellResizerPlugin, TablePlugin, } from '@datalayer/jupyter-lexical';
+import { ThemedProvider } from './utils/themedProvider';
+import { useExampleThemeStore } from './utils/themeStore';
+import { ComponentPickerMenuPlugin, JupyterInputOutputPlugin, DraggableBlockPlugin, FloatingTextFormatToolbarPlugin, CodeActionMenuPlugin, LexicalConfigProvider, LexicalPrimerThemeProvider, LexicalStatePlugin, TableCellResizerPlugin, } from '@datalayer/jupyter-lexical';
 import { ChatSidebar } from '../chat';
 import { ChatInlinePlugin } from '../lexical/ChatInlinePlugin';
 import { useChatInlineToolbarItems } from '../lexical/useChatInlineToolbarItems';
 import { useLexicalTools } from '../tools/adapters/agent-runtimes/lexicalHooks';
-import { editorConfig } from './lexical/editorConfig';
-import { useExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
-import { useExampleAgentRuntime } from './hooks/useExampleAgentRuntime';
-import { DEFAULT_MODEL } from '../specs';
+import { editorExtension } from './lexical/editorConfig';
+import { useExampleJupyterAgent } from './hooks/useExampleJupyterAgent';
 import '@datalayer/jupyter-lexical/style/index.css';
 import './lexical/lexical-theme.css';
 // Fixed lexical document ID
 const LEXICAL_ID = 'chat-lexical-example';
 // Default configuration
 const DEFAULT_AGENT_ID = import.meta.env.VITE_AGENT_ID || 'lexical-sidebar-agent-runtime-example';
-function getJupyterSandboxUrl(serviceManager) {
-    const envUrl = import.meta.env.VITE_JUPYTER_SANDBOX_URL;
-    if (envUrl) {
-        return envUrl;
-    }
-    const baseUrl = serviceManager?.serverSettings?.baseUrl?.replace(/\/$/, '');
-    if (!baseUrl) {
-        return undefined;
-    }
-    if (baseUrl.includes('token=')) {
-        return baseUrl;
-    }
-    const token = serviceManager?.serverSettings?.token;
-    if (!token) {
-        return baseUrl;
-    }
-    const separator = baseUrl.includes('?') ? '&' : '?';
-    return `${baseUrl}${separator}token=${encodeURIComponent(token)}`;
-}
+/** The agentspec this example's agent is built from. */
+const AGENTSPEC_ID = 'example-document-agent-sidebar';
 /**
- * Lexical plugin for code highlighting
+ * The plugins that need a kernel, and the kernel they need.
+ *
+ * `ComponentPickerMenuPlugin` and `JupyterInputOutputPlugin` both take a
+ * `kernel` prop, and both were mounted here without one — so a Jupyter cell in
+ * the document had nothing to run on and said "No runtime connected" however
+ * healthy the sandbox was. `LexicalAgentExample` had this right all along;
+ * this is the same component.
+ *
+ * The service manager is passed explicitly rather than left ambient. A bare
+ * `useJupyter()` builds its own from the page config, which is the cloud —
+ * see the note on `AgentRuntimeLexicalAgentSidebarExample`.
  */
-function CodeHighlightingPlugin() {
-    const [editor] = useLexicalComposerContext();
-    useEffect(() => {
-        return registerCodeHighlighting(editor);
-    }, [editor]);
-    return null;
+function DocumentKernelPlugins({ serviceManager, }) {
+    const { defaultKernel } = useJupyter({
+        serviceManager,
+        startDefaultKernel: !!serviceManager,
+    });
+    return (_jsxs(_Fragment, { children: [_jsx(ComponentPickerMenuPlugin, { kernel: defaultKernel }), _jsx(JupyterInputOutputPlugin, { kernel: defaultKernel })] }));
 }
 function LexicalEditor({ serviceManager, endpoint }) {
     const [floatingAnchorElem, setFloatingAnchorElem] = useState(null);
@@ -94,79 +75,54 @@ function LexicalEditor({ serviceManager, endpoint }) {
     const onChange = useCallback((_editorState) => {
         // Could persist state here
     }, []);
-    return (_jsx(LexicalConfigProvider, { lexicalId: LEXICAL_ID, serviceManager: serviceManager, children: _jsxs(LexicalComposer, { initialConfig: editorConfig, children: [_jsx(LexicalStatePlugin, {}), _jsxs(Box, { sx: {
-                        position: 'relative',
-                        flex: 1,
-                        display: 'flex',
-                        flexDirection: 'column',
-                        overflow: 'hidden',
-                    }, children: [_jsx(RichTextPlugin, { contentEditable: _jsx("div", { ref: onRef, style: { flex: 1, display: 'flex', flexDirection: 'column' }, children: _jsx(ContentEditable, { className: "lexical-editor-content", style: {
-                                        flex: 1,
-                                        padding: '24px',
-                                        outline: 'none',
-                                        overflow: 'auto',
-                                    } }) }), placeholder: _jsx("div", { style: {
-                                    position: 'absolute',
-                                    top: '24px',
-                                    left: '24px',
-                                    color: 'var(--fgColor-muted)',
-                                    pointerEvents: 'none',
-                                }, children: "Start typing or use the chat to create content..." }), ErrorBoundary: LexicalErrorBoundary }), _jsx(HistoryPlugin, {}), _jsx(AutoFocusPlugin, {}), _jsx(OnChangePlugin, { onChange: onChange }), _jsx(MarkdownShortcutPlugin, { transformers: TRANSFORMERS }), _jsx(CodeHighlightingPlugin, {}), _jsx(ListPlugin, {}), _jsx(CheckListPlugin, {}), _jsx(LinkPlugin, {}), _jsx(TablePlugin, {}), _jsx(TableCellResizerPlugin, {}), _jsx(JupyterCellPlugin, {}), _jsx(JupyterInputOutputPlugin, {}), _jsx(ImagesPlugin, {}), _jsx(HorizontalRulePlugin, {}), _jsx(EquationsPlugin, {}), _jsx(YouTubePlugin, {}), _jsx(ExcalidrawPlugin, {}), _jsx(CollapsiblePlugin, {}), _jsx(AutoLinkPlugin, {}), _jsx(AutoEmbedPlugin, {}), _jsx(ListMaxIndentLevelPlugin, { maxDepth: 7 }), floatingAnchorElem && (_jsxs(_Fragment, { children: [_jsx(ComponentPickerMenuPlugin, {}), _jsx(DraggableBlockPlugin, { anchorElem: floatingAnchorElem }), _jsx(FloatingTextFormatToolbarPlugin, { anchorElem: floatingAnchorElem, setIsLinkEditMode: setIsLinkEditMode, extraItems: toolbarItems }), _jsx(CodeActionMenuPlugin, { anchorElem: floatingAnchorElem })] })), _jsx(ChatInlinePlugin, { protocol: {
-                                type: 'vercel-ai',
-                                endpoint,
-                            }, isOpen: isAiOpen, onClose: closeAi, pendingPrompt: pendingPrompt, onPendingPromptConsumed: clearPendingPrompt })] })] }) }));
+    /*
+     * The editor's own theme scope.
+     *
+     * `LexicalPrimerThemeProvider` is what the platform's document editor uses,
+     * and it carries the two halves this example was missing: the resolved
+     * `colormode` and canvas background handed to `JupyterReactTheme`, so the
+     * `--jp-*` variables the editor's stylesheet reads follow the picker; and a
+     * `ThemeContext`, which is where `ExcalidrawModal` and `ExcalidrawImage`
+     * read light-or-dark from. Without it a drawing rendered light on a dark
+     * document, and the editor surface kept Primer's stock palette.
+     *
+     * Only the editor is wrapped. `JupyterReactTheme` nests a Primer theme of
+     * its own, and putting the header, the chat sidebar and the error panel
+     * inside it is what made them read `canvas.default` from the stock light
+     * palette — the same trap `NotebookAgentSidebarExample` documents.
+     */
+    return (_jsx(LexicalPrimerThemeProvider, { useStore: useExampleThemeStore, children: _jsx(LexicalConfigProvider, { lexicalId: LEXICAL_ID, serviceManager: serviceManager, children: _jsxs(LexicalExtensionComposer, { extension: editorExtension, contentEditable: null, children: [_jsx(LexicalStatePlugin, {}), _jsxs(Box, { sx: { position: 'relative', width: '100%' }, children: [_jsx("div", { ref: onRef, children: _jsx(ContentEditable, { placeholder: _jsx("div", { style: {
+                                            position: 'absolute',
+                                            top: '24px',
+                                            left: '24px',
+                                            color: 'var(--fgColor-muted)',
+                                            pointerEvents: 'none',
+                                        }, children: "Start typing or use the chat to create content..." }), "aria-placeholder": "Start typing or use the chat to create content...", className: "lexical-editor-content", "aria-label": "Lexical Editor", style: { padding: '24px', outline: 'none' } }) }), _jsx(OnChangePlugin, { onChange: onChange }), _jsx(TableCellResizerPlugin, {}), _jsx(DocumentKernelPlugins, { serviceManager: serviceManager }), floatingAnchorElem && (_jsxs(_Fragment, { children: [_jsx(DraggableBlockPlugin, { anchorElem: floatingAnchorElem }), _jsx(FloatingTextFormatToolbarPlugin, { anchorElem: floatingAnchorElem, setIsLinkEditMode: setIsLinkEditMode, extraItems: toolbarItems }), _jsx(CodeActionMenuPlugin, { anchorElem: floatingAnchorElem })] })), _jsx(ChatInlinePlugin, { protocol: {
+                                    type: 'vercel-ai',
+                                    endpoint,
+                                }, isOpen: isAiOpen, onClose: closeAi, pendingPrompt: pendingPrompt, onPendingPromptConsumed: clearPendingPrompt })] })] }) }) }));
 }
 export function ChatLexicalAgentExampleInner({ serviceManager, }) {
-    const baseUrl = useExampleAgentRuntimesUrl();
-    const vercelAiEndpoint = `${baseUrl}/api/v1/vercel-ai/${DEFAULT_AGENT_ID}`;
-    const [createRequested, setCreateRequested] = useState(false);
-    const jupyterSandboxUrl = useMemo(() => getJupyterSandboxUrl(serviceManager), [serviceManager]);
-    const { agentId, isReady, status, error, createAgent } = useExampleAgentRuntime({
+    // The tools. Which of the chat and the harness runs them depends on
+    // where the loop turns, and the hook decides that.
+    const tools = useLexicalTools(LEXICAL_ID);
+    const { agentReady, protocol: protocolConfig, chatFrontendTools, error, unavailableReason, } = useExampleJupyterAgent({
         exampleId: 'LexicalAgentSidebarExample',
         agentName: DEFAULT_AGENT_ID,
-        autoCreateAgent: false,
-        agentConfig: {
-            name: DEFAULT_AGENT_ID,
-            description: 'Demo agent for lexical sidebar example',
-            protocol: 'vercel-ai',
-            model: DEFAULT_MODEL,
-            systemPrompt: 'You are a helpful AI assistant that helps users work with lexical documents. For document operations, always use the lexical frontend tools so actions happen in the live document UI. Use executeCode only for temporary inspection code that should not modify persisted document content.',
-            enableCodemode: false,
-            sandboxVariant: 'jupyter',
-            jupyterSandbox: jupyterSandboxUrl,
-        },
+        specId: AGENTSPEC_ID,
+        description: 'Demo agent for lexical sidebar example',
+        systemPrompt: 'You are a helpful AI assistant that helps users work with lexical documents. For document operations, always use the lexical frontend tools so actions happen in the live document UI. Diagrams are documents too: this editor mounts the Excalidraw plugin, so draw with the excalidraw* tools rather than describing a picture in prose or writing it as ASCII art — excalidrawInsertNode to make one, excalidrawListDrawings then excalidrawReadScene to find and read an existing one before changing it. Use executeCodeInDocument only for temporary inspection code that should not modify persisted document content.',
+        serviceManager,
+        frontendTools: tools,
     });
-    useEffect(() => {
-        if (!jupyterSandboxUrl || createRequested || agentId) {
-            return;
-        }
-        setCreateRequested(true);
-        void createAgent({
-            name: DEFAULT_AGENT_ID,
-            description: 'Demo agent for lexical sidebar example',
-            protocol: 'vercel-ai',
-            model: DEFAULT_MODEL,
-            systemPrompt: 'You are a helpful AI assistant that helps users work with lexical documents. For document operations, always use the lexical frontend tools so actions happen in the live document UI. Use executeCode only for temporary inspection code that should not modify persisted document content.',
-            enableCodemode: false,
-            sandboxVariant: 'jupyter',
-            jupyterSandbox: jupyterSandboxUrl,
-        }).catch(() => {
-            setCreateRequested(false);
-        });
-    }, [jupyterSandboxUrl, createRequested, agentId, createAgent]);
-    const effectiveReady = isReady || status === 'ready';
+    // One failed attempt is reported, not retried — see
+    // `useExampleJupyterAgent`.
+    const chatError = error || unavailableReason;
+    // The example's own agent, not merely the runtime: on the cloud target the
+    // runtime is ready before this agent has been registered on it.
+    const effectiveReady = agentReady;
     // Get lexical tools for ChatSidebar
-    const tools = useLexicalTools(LEXICAL_ID);
     // Build Vercel AI protocol config
-    const protocolConfig = useMemo(() => {
-        return {
-            type: 'vercel-ai',
-            endpoint: vercelAiEndpoint,
-            agentId: DEFAULT_AGENT_ID,
-            enableConfigQuery: true,
-            configEndpoint: `${baseUrl}/api/v1/configure`,
-        };
-    }, [baseUrl, vercelAiEndpoint]);
     return (_jsxs(_Fragment, { children: [_jsxs(Box, { sx: {
                     height: 'calc(100vh - 70px)',
                     width: '100vw',
@@ -182,34 +138,39 @@ export function ChatLexicalAgentExampleInner({ serviceManager, }) {
                                     borderBottom: '1px solid',
                                     borderColor: 'border.default',
                                     bg: 'canvas.default',
-                                }, children: [_jsx("h1", { style: { margin: 0, fontSize: '1.5rem' }, children: "Agent Runtime Lexical Sidebar Example" }), _jsx("p", { style: { margin: '8px 0 0', color: 'var(--fgColor-muted)' }, children: "Next generation chat with Lexical editor integration (NO Provider!)" })] }), _jsx(Box, { sx: {
+                                }, children: [_jsx("h1", { style: { margin: 0, fontSize: '1.5rem' }, children: "Lexical Agent Sidebar Example" }), _jsx("p", { style: { margin: '8px 0 0', color: 'var(--fgColor-muted)' }, children: "Next generation chat with Lexical editor integration" })] }), _jsx(Box, { sx: {
                                     flex: 1,
+                                    minHeight: 0,
                                     display: 'flex',
-                                    overflow: 'hidden',
+                                    flexDirection: 'column',
+                                    overflow: 'auto',
                                     bg: 'canvas.default',
-                                }, children: _jsx(LexicalEditor, { serviceManager: serviceManager, endpoint: vercelAiEndpoint }) })] }), effectiveReady && (_jsx(ChatSidebar, { kernelIndicatorPlacement: "right", title: "AI Assistant", protocol: protocolConfig, position: "right", width: 400, showNewChatButton: true, showClearButton: true, showSettingsButton: true, defaultOpen: true, panelProps: {
+                                }, children: _jsx(LexicalEditor, { serviceManager: serviceManager, endpoint: protocolConfig.endpoint }) })] }), effectiveReady && (_jsx(ChatSidebar, { kernelIndicatorPlacement: "right", title: "AI Assistant", protocol: protocolConfig, position: "right", width: 400, showNewChatButton: true, showClearButton: true, showSettingsButton: true, defaultOpen: true, panelProps: {
                             protocol: protocolConfig,
-                            frontendTools: tools,
+                            frontendTools: chatFrontendTools,
                             useStore: true,
+                            // Two of these exercise the drawing tools the mounted
+                            // `ExcalidrawPlugin` contributes, because a suggestion is how
+                            // anyone finds out a tool exists.
                             suggestions: [
                                 {
                                     title: '✍️ Help me write',
                                     message: 'Can you help me write a document?',
                                 },
                                 {
-                                    title: '📝 Summarize text',
-                                    message: 'Can you summarize the content in the editor?',
+                                    title: '📊 Draw a diagram',
+                                    message: 'Draw a flowchart of a three-stage data pipeline — ingest, transform, publish — with labelled arrows between the stages.',
                                 },
                                 {
-                                    title: '🔍 Proofread',
-                                    message: 'Can you proofread and improve my text?',
+                                    title: '🎨 Edit the drawing',
+                                    message: 'Read the drawing in this document and add a box for a validation step between ingest and transform, wired into the existing arrows.',
                                 },
                                 {
-                                    title: '💡 Generate ideas',
-                                    message: 'Can you suggest some ideas for content?',
+                                    title: '📝 Summarize text',
+                                    message: 'Can you summarize the content in the editor?',
                                 },
                             ],
-                        } }))] }), error && (_jsxs(Box, { sx: {
+                        } }))] }), chatError && (_jsxs(Box, { sx: {
                     position: 'fixed',
                     bottom: 20,
                     right: 20,
@@ -218,16 +179,23 @@ export function ChatLexicalAgentExampleInner({ serviceManager, }) {
                     color: 'danger.fg',
                     borderRadius: 2,
                     maxWidth: 300,
-                }, children: [_jsx("strong", { children: "Error:" }), " ", error] }))] }));
+                }, children: [_jsx("strong", { children: "Error:" }), " ", chatError] }))] }));
 }
 /**
- * Main example component with Simple wrapper
+ * The example, in the app's theme, on the shell's runtime.
+ *
+ * The service manager comes from the shell, as it does in every other
+ * example. Reading it from an ambient `useJupyter()` instead — which is what
+ * this example used to do — did not merely risk showing a document on a
+ * different runtime than the picker says: with no `<Jupyter>` provider above
+ * it there was nothing ambient to read, so the hook fell back to
+ * `DEFAULT_JUPYTER_SERVER_URL` (`prod1.datalayer.run/api/jupyter-server`).
+ * That URL is what the example then handed the agent runtime as its sandbox,
+ * and validating it is what came back as "Failed to connect to Jupyter
+ * sandbox: Jupyter server returned HTTP 404" — a server that was running all
+ * along, just not the one being asked.
  */
-export function AgentRuntimeLexicalAgentSidebarExample() {
-    return (_jsx(ThemedJupyterProvider, { children: _jsx(SimpleWrapper, {}) }));
-}
-function SimpleWrapper() {
-    const { serviceManager } = useJupyter();
-    return _jsx(ChatLexicalAgentExampleInner, { serviceManager: serviceManager });
+export function AgentRuntimeLexicalAgentSidebarExample({ serviceManager, }) {
+    return (_jsx(ThemedProvider, { children: _jsx(ChatLexicalAgentExampleInner, { serviceManager: serviceManager }) }));
 }
 export default AgentRuntimeLexicalAgentSidebarExample;

package/lib/examples/LoopShellExample.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The Loop Shell: the workspace with almost everything taken away.
+ *
+ * Where `LoopWorkspaceExample` shows everything Loop can mount, this shows how
+ * little it needs: a blank shell, a floating prompt that can be dragged out of
+ * the way, and one control in the top-right corner choosing the editor —
+ * `None` by default, the notebook and the document on offer. Everything on
+ * screen is a plugin; the example itself only picks them.
+ *
+ * The code runs in the browser sandbox — the in-page kernel reached through
+ * the Jupyter service manager — so the page needs no server and no account.
+ * The agents are the `jupyter` team the landing page runs — Analyst,
+ * Reviewer, Writer, Decks, Tutor and Compactor — with the Analyst at the
+ * front door; `@` in the composer reaches the others, and the team picker in
+ * the header switches to one. The decks plugin is mounted so the Decks member
+ * has its tools and a deck can open beside the conversation, like the
+ * notebook and the document.
+ *
+ * @module examples/LoopShellExample
+ */
+import type { JSX } from 'react';
+export type LoopShellExampleProps = {
+    /** Server backing the session. Defaults to this page's origin. */
+    serverUrl?: string;
+    /** Agent bound to the session; the team's front door by default. */
+    agentId?: string;
+    /**
+     * Which editor the shell opens on.
+     *
+     * `'none'` is the point of this example: the conversation is the canvas,
+     * and the selector in the top-right corner is how an editor arrives.
+     */
+    defaultEditor?: 'none' | 'notebook' | 'document' | 'deck';
+    /** Render without wrapping the shell in a theme provider. */
+    inheritTheme?: boolean;
+};
+export declare function LoopShellExample({ serverUrl, agentId, defaultEditor, inheritTheme, }: LoopShellExampleProps): JSX.Element;
+export default LoopShellExample;

package/lib/examples/LoopShellExample.js

@@ -0,0 +1,68 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { Box } from '@primer/react';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { useReactor } from '@datalayer/reactor/react';
+import { registerDecks } from '@datalayer/decks';
+import { exampleDecks } from '@datalayer/decks/examples';
+import { buildLoopReactor, LoopWorkspace } from '../loop/shell';
+import { DeckViewPlugin, LoopDecksPlugin } from '../loop/plugins/decks';
+import { loopPlugins } from '../loop/presets';
+import { internalQueryClient } from '../utils';
+import { resolveExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
+import { ThemedProvider } from './utils/themedProvider';
+/** The team the landing page runs, and this example with it. */
+const TEAM_ID = 'jupyter';
+/** Its front door: the member a prompt reaches unless `@` says otherwise. */
+const FRONT_DOOR = 'jupyter-data-analyst';
+// The package's example decks, so the Decks member has something to open and
+// change before it has made one. Once, at module load.
+registerDecks(exampleDecks);
+export function LoopShellExample({ serverUrl = resolveExampleAgentRuntimesUrl('local'), agentId = FRONT_DOOR, defaultEditor = 'none', inheritTheme = false, }) {
+    // Built once: rebuilding would restart every plugin on each render.
+    const reactor = useMemo(() => buildLoopReactor([
+        ...loopPlugins({
+            serverUrl,
+            // The browser sandbox: the in-page kernel behind the Jupyter
+            // service manager, so nothing has to be installed or signed into.
+            target: 'browser',
+            showAgentVariants: false,
+            defaultEditor,
+            // The two plugins this example exists to show: the draggable
+            // prompt floating over the shell, and the editor choice in the
+            // header. Each switches the chat's own copy of itself off.
+            floatingPrompt: true,
+            editorSelector: true,
+            // Naked: the page names the example, and a title bar inside an
+            // otherwise blank shell would be the only chrome in sight.
+            hideChatHeader: true,
+            // First-class commands still deserve their keystrokes.
+            commandPalette: true,
+            // The landing page's team, front door and all: what `@` offers
+            // in the composer and what the header's picker switches between.
+            teamId: TEAM_ID,
+            localAgentSpec: FRONT_DOOR,
+        }),
+        // The deck beside the chat — an editor in the selector, a footer
+        // icon, a menu in the composer — and the tools the Decks member
+        // reads and writes decks with. Without these the fourth member
+        // would be a name with nothing behind it.
+        LoopDecksPlugin,
+        DeckViewPlugin,
+    ]), [serverUrl, defaultEditor]);
+    // Registered here rather than inside the workspace, because this component
+    // built it; the workspace is told not to manage it a second time.
+    useReactor(reactor);
+    const shell = (_jsx(QueryClientProvider, { client: internalQueryClient, children: _jsx(Box, { sx: { height: '100%', minHeight: 0 }, children: _jsx(LoopWorkspace, { serverUrl: serverUrl, agentId: agentId, reactor: reactor, manageReactor: false, 
+                // The header stays for the one thing living in it — the editor
+                // selector on its trailing edge — but offers no view switcher:
+                // a blank shell with one control is the example.
+                showViewSelector: false }) }) }));
+    if (inheritTheme) {
+        return shell;
+    }
+    // The one theme provider in the tree; see LoopWorkspaceExample for why the
+    // editors need it even when the chrome looks right without it.
+    return _jsx(ThemedProvider, { children: shell });
+}
+export default LoopShellExample;

package/lib/examples/LoopWorkspaceEmbed.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The LOOP workspace, ready to drop into somebody else's page.
+ *
+ * `LoopWorkspaceExample` is the workspace; this is everything a host has to do
+ * around it, done once here instead of once per host:
+ *
+ * - **Loaded lazily, fetched eagerly.** The workspace pulls in a notebook
+ *   editor and a Python runtime measured in megabytes, so it must not be in
+ *   the bundle a page needs before it can paint. Downloading it only when it
+ *   first renders turns that saving into a wait, so the chunk is requested as
+ *   soon as this module evaluates and is usually there before anyone scrolls
+ *   to it.
+ * - **Fenced off.** An old browser, a blocked worker, a network that dropped
+ *   the Python payload: none of those should cost the host the rest of its
+ *   page, so a failure inside the workspace stops here.
+ * - **Honest while it waits**, and honest when it cannot start.
+ *
+ * The landing page had all three, written against a package it embeds — which
+ * is the wrong side of the boundary for them to live on: a change to how the
+ * workspace boots would have had to be made in a repository that only
+ * *renders* it. What a host keeps is the frame it puts around the thing and
+ * where a failure should send its readers.
+ *
+ * @module examples/LoopWorkspaceEmbed
+ */
+import type { JSX } from 'react';
+import { type ReactNode } from 'react';
+import type { LoopWorkspaceExampleProps } from './LoopWorkspaceExample';
+/** Ask for the workspace's code before anything renders it. */
+export declare function preloadLoopWorkspace(): void;
+export type LoopWorkspaceEmbedProps = LoopWorkspaceExampleProps & {
+    /**
+     * What to show in place of the workspace when it cannot run.
+     *
+     * The default says what happened and nothing else. A host with somewhere
+     * useful to send a reader — a gallery, a sign-up — should say so here: this
+     * package does not know what else that page has to offer.
+     */
+    fallback?: ReactNode;
+    /** What to show while the workspace is on its way. */
+    loading?: ReactNode;
+};
+/**
+ * The workspace, framed by whoever is embedding it.
+ *
+ * Fills its container: give it a height. Every other prop is the example's own
+ * — see {@link LoopWorkspaceExampleProps}.
+ */
+export declare function LoopWorkspaceEmbed({ fallback, loading, ...workspace }: LoopWorkspaceEmbedProps): JSX.Element;
+export default LoopWorkspaceEmbed;

package/lib/examples/LoopWorkspaceEmbed.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component, Suspense } from 'react';
+import { Spinner, Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { lazyWithPreload } from '@datalayer/core/lib/utils';
+/**
+ * The workspace itself, split out of the host's bundle.
+ *
+ * The real one — plugins, views, chat, sandbox and all, exactly as the
+ * examples app runs it. Reaching for it rather than rebuilding a smaller one
+ * for embedding is the whole point: a second implementation drifts from the
+ * first by the following release.
+ */
+const LazyLoopWorkspace = lazyWithPreload(async () => {
+    const module = await import('./LoopWorkspaceExample');
+    return { default: module.LoopWorkspaceExample };
+});
+// Requested now, rendered later. See the note at the top of the file.
+LazyLoopWorkspace.preload();
+/** Ask for the workspace's code before anything renders it. */
+export function preloadLoopWorkspace() {
+    void LazyLoopWorkspace.preload();
+}
+/** Rendered while the editor and its runtime are arriving. */
+function WorkspaceLoading() {
+    return (_jsxs(Box, { sx: {
+            height: '100%',
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: 3,
+        }, children: [_jsx(Spinner, {}), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Starting the workspace\u2026" })] }));
+}
+/** Said when the workspace will not start, and the host offered nothing better. */
+function WorkspaceUnavailable() {
+    return (_jsxs(Box, { sx: {
+            height: '100%',
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+            gap: 2,
+            px: 4,
+            textAlign: 'center',
+        }, children: [_jsx(Text, { sx: { fontSize: 2, fontWeight: 'semibold' }, children: "The live workspace could not start in this browser." }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1, maxWidth: 420 }, children: "It needs a modern browser that can run Python in a worker." })] }));
+}
+/** Keeps a failing workspace from taking its host's page with it. */
+class WorkspaceBoundary extends Component {
+    state = { failed: false };
+    static getDerivedStateFromError() {
+        return { failed: true };
+    }
+    componentDidCatch(error) {
+        // Worth a console line for whoever is debugging it; not worth a banner on
+        // somebody's landing page.
+        console.warn('The embedded agent workspace could not start.', error);
+    }
+    render() {
+        return this.state.failed ? this.props.fallback : this.props.children;
+    }
+}
+/**
+ * The workspace, framed by whoever is embedding it.
+ *
+ * Fills its container: give it a height. Every other prop is the example's own
+ * — see {@link LoopWorkspaceExampleProps}.
+ */
+export function LoopWorkspaceEmbed({ fallback, loading, ...workspace }) {
+    const waiting = loading ?? _jsx(WorkspaceLoading, {});
+    return (_jsx(WorkspaceBoundary, { fallback: fallback ?? _jsx(WorkspaceUnavailable, {}), children: _jsx(Suspense, { fallback: waiting, children: _jsx(LazyLoopWorkspace, { ...workspace }) }) }));
+}
+export default LoopWorkspaceEmbed;