@datalayer/agent-runtimes 1.3.73 → 1.3.75

package/lib/examples/{ChatAssistantExample.js → AssistantExample.js}

@@ -15,8 +15,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * and so are the characters clippy.js publishes, fetched when picked.
  */
 import { useEffect, useRef, useState } from 'react';
+import { useAgentInspector } from '../components/inspector/agentInspector';
 import { buildReactorFromPlugins } from '@datalayer/reactor';
-import { Button, Heading, Text } from '@primer/react';
+import { Button, Heading, Text, ToggleSwitch } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { ThemedProvider } from './utils/themedProvider';
 import { ChatFloating } from '../chat';
@@ -34,6 +35,35 @@ const SERVER = ((typeof window === 'undefined'
     ? null
     : new URLSearchParams(window.location.search).get('agentRuntimesUrl')) ||
     'http://127.0.0.1:8765').replace(/\/+$/, '');
+/** The agent the assistant talks to on that server. */
+const AGENT_ID = 'assistant';
+/**
+ * Make sure the server has the assistant's agent: `npm run examples` starts
+ * the server with none, so the page creates it from the
+ * `example-agentic-chat` spec the first time, over AG-UI, the spec's own
+ * protocol.
+ */
+async function ensureAssistantAgent() {
+    const found = await fetch(`${SERVER}/api/v1/agents/${AGENT_ID}`);
+    if (found.ok) {
+        return;
+    }
+    if (found.status !== 404) {
+        throw new Error(`The server could not say whether the ${AGENT_ID} agent exists (${found.status}).`);
+    }
+    const created = await fetch(`${SERVER}/api/v1/agents`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            name: AGENT_ID,
+            agent_spec_id: 'example-agentic-chat',
+            transport: 'ag-ui',
+        }),
+    });
+    if (!created.ok && created.status !== 409) {
+        throw new Error(`The server could not create the ${AGENT_ID} agent (${created.status}).`);
+    }
+}
 /** The plugins this page enables: Datalayer's characters and the owl's. */
 const reactor = buildReactorFromPlugins([
     AssistantCharactersPlugin,
@@ -66,15 +96,28 @@ async function readPicked(files) {
         soundsJs: soundsJs ? await soundsJs.text() : undefined,
     });
 }
-const ChatAssistantExample = () => {
+const AssistantExample = () => {
     const [character, setCharacter] = useState('paperclip');
     // A character chosen by id is the one its plugin contributes.
     const drawn = typeof character === 'string'
         ? assistantCharacterNamed(reactor, character)
         : character;
     const [loadError, setLoadError] = useState();
+    // The agent on the server, made if it is not there yet.
+    const [agentReady, setAgentReady] = useState(false);
+    const [agentError, setAgentError] = useState();
+    useEffect(() => {
+        let cancelled = false;
+        ensureAssistantAgent().then(() => !cancelled && setAgentReady(true), error => !cancelled &&
+            setAgentError(`${error instanceof Error ? error.message : String(error)} The assistant talks to an agent-runtimes server at ${SERVER}.`));
+        return () => {
+            cancelled = true;
+        };
+    }, []);
     // How the balloon shows the conversation (T-23): history, or current.
     const [balloon, setBalloon] = useState('history');
+    // What the agent does, for the menu's *Inspect the agent…*.
+    const { sink: inspector } = useAgentInspector();
     // Pixel, the test sprite, read once through the clippy.js reader.
     const [pixel, setPixel] = useState();
     useEffect(() => {
@@ -131,13 +174,15 @@ const ChatAssistantExample = () => {
     };
     const isClippyJs = typeof character !== 'string' &&
         Object.values(clippyJs).includes(character);
-    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: { minHeight: '100vh', bg: 'canvas.default', p: 4 }, children: [_jsxs(Box, { sx: { maxWidth: 720, mx: 'auto' }, children: [_jsx(Heading, { as: "h1", sx: { mb: 2 }, children: "Chat Assistant" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', mb: 3 }, children: "The chat as a character on the page. It greets you, acts out what the agent is doing, and says the agent\u2019s words in a balloon while the conversation is closed. Click it to talk, drag it to move it, hover it to send it away." }), _jsxs(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: [CATALOGUE.map(option => (_jsx(Button, { variant: option.id === character ? 'primary' : 'default', onClick: () => {
+    return (_jsx(ThemedProvider, { children: _jsxs(Box, { sx: { minHeight: '100vh', bg: 'canvas.default', p: 4 }, children: [_jsxs(Box, { sx: { maxWidth: 720, mx: 'auto' }, children: [_jsx(Heading, { as: "h1", sx: { mb: 2 }, children: "Assistant" }), _jsx(Text, { as: "p", sx: { color: 'fg.muted', mb: 3 }, children: "The chat as a character on the page. It greets you, acts out what the agent is doing, and says the agent\u2019s words in a balloon while the conversation is closed. Click it to talk, drag it to move it, hover it to send it away." }), _jsxs(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: [CATALOGUE.map(option => (_jsx(Button, { variant: option.id === character ? 'primary' : 'default', onClick: () => {
                                         setCharacter(option.id);
                                         setLoadError(undefined);
                                     }, "aria-pressed": option.id === character, "data-assistant-character": option.id, children: option.name }, option.id))), pixel && (_jsxs(Button, { variant: character === pixel ? 'primary' : 'default', onClick: () => {
                                         setCharacter(pixel);
                                         setLoadError(undefined);
-                                    }, "aria-pressed": character === pixel, "data-assistant-character": "sprite", children: [pixel.name, " (sprite)"] }))] }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "The balloon" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: [_jsx("strong", { children: "History" }), ": open, the whole conversation, counted in its header, the composer last. ", _jsx("strong", { children: "Current" }), ": only what it says or does now \u2014 the answer as it is written, or the tool it calls (\u201CUsing current_time\u2026\u201D) \u2014 in one compact balloon. Either way, a tool call is said in the balloon."] }), _jsx(Box, { sx: { display: 'flex', gap: 2 }, children: ['history', 'current'].map(option => (_jsx(Button, { variant: option === balloon ? 'primary' : 'default', "aria-pressed": option === balloon, "data-assistant-balloon-choice": option, onClick: () => setBalloon(option), children: option === 'history' ? 'History' : 'Current' }, option))) })] }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "The clippy.js characters" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: ["Fetched when picked from the", ' ', _jsxs("code", { children: ["clippyjs@", CLIPPY_JS_VERSION] }), " package on jsDelivr and read as data by the same reader. They are not in this repository: clippy.js\u2019s licence covers its code only, and the characters are Microsoft\u2019s."] }), _jsx(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: CLIPPY_JS_CHARACTERS.map(name => {
+                                    }, "aria-pressed": character === pixel, "data-assistant-character": "sprite", children: [pixel.name, " (sprite)"] }))] }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "The balloon" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: [_jsx("strong", { children: "History" }), ": the whole conversation, counted in its header \u2014 closed, every message listed and scrolled; open, the composer last. ", _jsx("strong", { children: "Current" }), ": only what it says or does now \u2014 the answer as it is written, or the tool it calls (\u201CUsing current_time\u2026\u201D) \u2014 in one compact balloon. Either way, a tool call is said in the balloon."] }), _jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, "data-assistant-balloon-toggle": "", children: [_jsx(Text, { id: "assistant-balloon-history", sx: { fontWeight: 'semibold' }, children: "History" }), _jsx(ToggleSwitch, { "aria-labelledby": "assistant-balloon-history", size: "small", checked: balloon === 'history', 
+                                            // Controlled, Primer's switch flips only through its click.
+                                            onClick: () => setBalloon(balloon === 'history' ? 'current' : 'history') }), _jsx(Text, { "aria-live": "polite", "data-toggle-state": "", sx: { color: 'fg.muted' }, children: balloon === 'history' ? 'History' : 'Current' })] })] }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "The clippy.js characters" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: ["Fetched when picked from the", ' ', _jsxs("code", { children: ["clippyjs@", CLIPPY_JS_VERSION] }), " package on jsDelivr and read as data by the same reader. They are not in this repository: clippy.js\u2019s licence covers its code only, and the characters are Microsoft\u2019s."] }), _jsx(Box, { sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: CLIPPY_JS_CHARACTERS.map(name => {
                                         const picked = clippyJs[name] !== undefined && character === clippyJs[name];
                                         return (_jsx(Button, { variant: picked ? 'primary' : 'default', onClick: () => void pickClippyJs(name), disabled: fetching !== undefined, "aria-pressed": picked, "data-assistant-character": `clippy-js-${name.toLowerCase()}`, children: fetching === name ? `${name}…` : name }, name));
                                     }) })] }), _jsxs(Box, { as: "section", sx: { mt: 4 }, children: [_jsx(Heading, { as: "h2", sx: { fontSize: 2, mb: 1 }, children: "A character you bring" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 2 }, children: ["The characters of Microsoft Office \u2014 Clippy, Merlin, Links and the others \u2014 are Microsoft\u2019s. Load only a character file you have the right to use: a Microsoft Agent ", _jsx("code", { children: ".acs" }), " file, or a clippy.js character\u2019s ", _jsx("code", { children: "agent.js" }), " and map image. It is read in this page and sent nowhere."] }), _jsx("input", { type: "file", multiple: true, accept: ".acs,.js,.png,.gif,.webp,.jpg,.jpeg", "aria-label": "Character files", onChange: async (event) => {
@@ -154,8 +199,25 @@ const ChatAssistantExample = () => {
                                         }
                                     } }), loadError && (_jsx(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mt: 2 }, children: loadError })), typeof character !== 'string' &&
                                     character !== pixel &&
-                                    !isClippyJs && (_jsxs(Text, { as: "p", sx: { mt: 2 }, children: ["Playing ", character.name, "."] }))] })] }), _jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: drawn, balloonDisplay: balloon, protocol: "vercel-ai", endpoint: `${SERVER}/api/v1/vercel-ai/assistant`, title: "Assistant", description: "Hello! Ask me anything about this page.", position: "bottom-right", useStore: false, 
+                                    !isClippyJs && (_jsxs(Text, { as: "p", sx: { mt: 2 }, children: ["Playing ", character.name, "."] }))] })] }), agentError && (_jsx(Box, { sx: { maxWidth: 720, mx: 'auto', mt: 3 }, children: _jsx(Text, { as: "p", role: "alert", sx: { color: 'danger.fg' }, children: agentError }) })), agentReady && (_jsx(ChatFloating, { defaultViewMode: "assistant", assistantCharacter: drawn, balloonDisplay: balloon, protocol: "ag-ui", endpoint: `${SERVER}/api/v1/ag-ui/${AGENT_ID}/`, title: "Assistant", description: "Hello! Ask me anything about this page.", position: "bottom-right", useStore: false, 
                     // Ask a decision beside the composer: Jev, through this server.
-                    decisions: { serverUrl: SERVER } }, typeof character === 'string' ? character : character.sprite)] }) }));
+                    decisions: { serverUrl: SERVER }, 
+                    // Right-click the character: its menu.
+                    inspector: inspector, onBalloonDisplayChange: setBalloon, onChangeCharacter: () => document
+                        .querySelector('[data-assistant-character]')
+                        ?.focus(), about: {
+                        name: 'Assistant',
+                        spec: AGENT_ID,
+                        where: `on a runtime, ${new URL(SERVER).host}`,
+                    }, suggestions: [
+                        {
+                            title: 'What is on this page?',
+                            message: 'What is on this page?',
+                        },
+                        {
+                            title: 'Tell me a joke',
+                            message: 'Tell me a short joke about accountants.',
+                        },
+                    ] }, typeof character === 'string' ? character : character.sprite))] }) }));
 };
-export default ChatAssistantExample;
+export default AssistantExample;

package/lib/examples/{ChatAssistantGalleryExample.d.ts → AssistantGalleryExample.d.ts}

@@ -13,5 +13,5 @@
  * Static data, no agent: it opens without a server or an account.
  */
 import React from 'react';
-declare const ChatAssistantGalleryExample: React.FC;
-export default ChatAssistantGalleryExample;
+declare const AssistantGalleryExample: React.FC;
+export default AssistantGalleryExample;

package/lib/examples/{ChatAssistantGalleryExample.js → AssistantGalleryExample.js}

@@ -18,17 +18,17 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * Static data, no agent: it opens without a server or an account.
  */
 import { useEffect, useRef, useState } from 'react';
-import { Button, Checkbox, FormControl, Heading, SegmentedControl, Text, } from '@primer/react';
+import { Button, Checkbox, FormControl, Heading, SegmentedControl, Text, ToggleSwitch, } from '@primer/react';
 import { Box, DatalayerThemeProvider, themeConfigs, } from '@datalayer/primer-addons';
 import { ThemedProvider } from './utils/themedProvider';
 import { useExampleThemeStore } from './utils/themeStore';
 import { AssistantStage } from '../chat/assistant/AssistantStage';
 import { useViewportDrag } from '../chat/useViewportDrag';
-import { AssistantGalleryGrid, GalleryBalloons, GalleryNotebook, GalleryObstacle, Still, useGalleryCharacters, } from './utils/AssistantGalleryGrid';
-import { GALLERY_POSES, GALLERY_POSE_LABELS, SAMPLE_NOTEBOOK_SAYING, balloonForPose, sampleApproval, sampleSaying, sampleToolLine, stateOfPose, } from './utils/assistantGallery';
+import { AssistantGalleryGrid, GalleryBalloons, GalleryNotebook, GalleryObstacle, galleryNotebookVisual, Still, useGalleryCharacters, } from './utils/AssistantGalleryGrid';
+import { GALLERY_POSES, GALLERY_POSE_LABELS, SAMPLE_NOTEBOOK_SAYING, balloonForPose, sampleApproval, sampleHistory, sampleSaying, sampleToolLine, stateOfPose, } from './utils/assistantGallery';
 import { CLIPPY_JS_VERSION, useClippyJsCharacters, } from './utils/clippyJsCharacters';
 const STAGE_SIZE = 96;
-const PANEL_HEIGHT = 520;
+const PANEL_HEIGHT = 640;
 const LEAVE_MS = 700;
 const ARRIVE_MS = 1900;
 const AWAY_WORDS = {
@@ -38,7 +38,7 @@ const AWAY_WORDS = {
     always: 'for good',
 };
 /** One colour mode's panel, with the character on its own stage. */
-function ModePanel({ mode, character, pose, presence, balloon, insist, onToggle, onDismiss, onCallBack, away, replay, display, }) {
+function ModePanel({ mode, character, pose, presence, balloon, insist, onToggle, onDismiss, onCallBack, away, replay, display, expandTarget, }) {
     const panelRef = useRef(null);
     const stageRef = useRef(null);
     const drag = useViewportDrag(stageRef, { whole: true });
@@ -84,13 +84,19 @@ function ModePanel({ mode, character, pose, presence, balloon, insist, onToggle,
                     position: 'absolute',
                     left: spot.left,
                     top: spot.top + STAGE_SIZE / 2 - 16,
-                }, children: [_jsxs(Button, { size: "small", onClick: onCallBack, "data-gallery-call-back": "", children: ["Call ", character.name, " back"] }), _jsxs(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1 }, children: ["Sent away ", AWAY_WORDS[away], "."] })] })) : (_jsx(AssistantStage, { character: character.character, state: state, size: STAGE_SIZE, place: { position: 'absolute', left: spot.left, top: spot.top }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: false, onToggle: onToggle, balloon: presence === 'here' ? balloon : undefined, balloonDisplay: display, insist: insist, onDismiss: onDismiss }, `${character.id}-${replay}`)), pose === 'aside' && presence === 'here' && (_jsx(GalleryObstacle, { sx: {
+                }, children: [_jsxs(Button, { size: "small", onClick: onCallBack, "data-gallery-call-back": "", children: ["Call ", character.name, " back"] }), _jsxs(Text, { as: "p", sx: { fontSize: 0, color: 'fg.muted', mt: 1 }, children: ["Sent away ", AWAY_WORDS[away], "."] })] })) : (_jsx(AssistantStage, { character: character.character, state: state, size: STAGE_SIZE, place: { position: 'absolute', left: spot.left, top: spot.top }, stageRef: stageRef, onDragStart: drag.onHandlePointerDown, open: false, onToggle: onToggle, balloon: presence === 'here' ? balloon : undefined, balloonDisplay: display, expandTarget: expandTarget, insist: insist, onDismiss: onDismiss }, `${character.id}-${replay}`)), pose === 'aside' && presence === 'here' && (_jsx(GalleryObstacle, { sx: {
                     left: spot.left - 12,
                     top: spot.top - 12,
                     width: STAGE_SIZE + 24,
                     height: STAGE_SIZE + 24,
                 } }))] }));
 }
+/** A two-way choice as a Primer toggle: its label, the switch, what is on. */
+function GalleryToggle({ id, label, on, onChange, state, ...rest }) {
+    return (_jsxs(Box, { sx: { display: 'flex', alignItems: 'center', gap: 2 }, ...rest, children: [_jsx(Text, { id: id, sx: { fontSize: 1, fontWeight: 'semibold' }, children: label }), _jsx(ToggleSwitch, { "aria-labelledby": id, size: "small", checked: on, 
+                // Controlled, Primer's switch flips only through its click.
+                onClick: () => onChange(!on) }), _jsx(Text, { "aria-live": "polite", "data-toggle-state": "", sx: { fontSize: 1, color: 'fg.muted' }, children: state })] }));
+}
 /** The panels in the modes asked, each in the examples' theme. */
 function InModes({ modes, stacked = false, children, }) {
     const { theme } = useExampleThemeStore();
@@ -103,7 +109,7 @@ function InModes({ modes, stacked = false, children, }) {
             flexWrap: 'wrap',
         }, children: shown.map(mode => (_jsx(Box, { sx: { flex: '1 1 320px', minWidth: 0 }, children: _jsx(DatalayerThemeProvider, { colorMode: mode, theme: config.primerTheme, themeStyles: config.themeStyles, children: children(mode) }) }, mode))) }));
 }
-const ChatAssistantGalleryExample = () => {
+const AssistantGalleryExample = () => {
     const { characters: ours, problem } = useGalleryCharacters();
     const [withClippyJs, setWithClippyJs] = useState(false);
     const clippyJs = useClippyJsCharacters(withClippyJs);
@@ -123,6 +129,9 @@ const ChatAssistantGalleryExample = () => {
     const [display, setDisplay] = useState('current');
     const [toolPhase, setToolPhase] = useState();
     const [withNotebook, setWithNotebook] = useState(false);
+    // Where Expand draws the notebook: the area under the stage, or a dialog.
+    const [expandIntoPage, setExpandIntoPage] = useState(true);
+    const expandArea = useRef(null);
     const character = characters.find(entry => entry.id === characterId) ?? characters[0];
     // Leaving takes the goodbye's length; arriving, the greeting's.
     useEffect(() => {
@@ -145,6 +154,21 @@ const ChatAssistantGalleryExample = () => {
         setSaid(said + 1);
     };
     const approval = sampleApproval(() => setDecision('Approved: send_reply.'), () => setDecision('Denied: send_reply.'));
+    // History: the conversation so far, every message, as the chat holds it.
+    const history = display === 'history'
+        ? [
+            ...sampleHistory(saying === undefined ? said : saying + 1),
+            ...(withNotebook
+                ? [
+                    {
+                        id: 'notebook',
+                        role: 'assistant',
+                        text: SAMPLE_NOTEBOOK_SAYING,
+                    },
+                ]
+                : []),
+        ]
+        : undefined;
     const balloon = balloonForPose(pose, {
         saying: saying === undefined
             ? withNotebook
@@ -153,7 +177,9 @@ const ChatAssistantGalleryExample = () => {
             : sampleSaying(saying),
         approval,
         tool: toolPhase ? sampleToolLine(toolPhase) : undefined,
-        attachment: withNotebook && display === 'current' ? (_jsx(GalleryNotebook, { onOpen: () => setDecision('The notebook would open below to run.') })) : undefined,
+        attachment: withNotebook ? _jsx(GalleryNotebook, {}) : undefined,
+        visual: withNotebook ? galleryNotebookVisual() : undefined,
+        history,
     });
     const insist = saying !== undefined ||
         toolPhase !== undefined ||
@@ -165,7 +191,7 @@ const ChatAssistantGalleryExample = () => {
                 bg: 'canvas.default',
                 color: 'fg.default',
                 p: 4,
-            }, children: _jsxs(Box, { sx: { maxWidth: 1200, mx: 'auto' }, children: [_jsx(Heading, { as: "h1", sx: { mb: 2 }, children: "Chat Assistant gallery" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 3, maxWidth: 760 }, children: ["Every character in every state the floating assistant acts, with its balloon, in light and dark. Datalayer\u2019s four and the owl are what the enabled plugins contribute to", ' ', _jsx("code", { children: "loop.assistant.character" }), "; Pixel is a test sprite of our own, read through the clippy.js reader. No agent is behind it: the words are a sample conversation."] }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 3, maxWidth: 760 }, children: ["The characters clippy.js publishes \u2014 Clippy, Merlin, Links, Rover and the others \u2014 are loaded on request from the", ' ', _jsxs("code", { children: ["clippyjs@", CLIPPY_JS_VERSION] }), " package on jsDelivr (about 15 MB) and read by the same reader. They are not in this repository: clippy.js\u2019s licence covers its code only, and the characters are Microsoft\u2019s."] }), _jsxs(Box, { as: "section", "aria-label": "Gallery controls", sx: {
+            }, children: _jsxs(Box, { sx: { maxWidth: 1200, mx: 'auto' }, children: [_jsx(Heading, { as: "h1", sx: { mb: 2 }, children: "Assistant gallery" }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 3, maxWidth: 760 }, children: ["Every character in every state the floating assistant acts, with its balloon, in light and dark. Datalayer\u2019s four and the owl are what the enabled plugins contribute to", ' ', _jsx("code", { children: "loop.assistant.character" }), "; Pixel is a test sprite of our own, read through the clippy.js reader. No agent is behind it: the words are a sample conversation."] }), _jsxs(Text, { as: "p", sx: { color: 'fg.muted', mb: 3, maxWidth: 760 }, children: ["The characters clippy.js publishes \u2014 Clippy, Merlin, Links, Rover and the others \u2014 are loaded on request from the", ' ', _jsxs("code", { children: ["clippyjs@", CLIPPY_JS_VERSION] }), " package on jsDelivr (about 15 MB) and read by the same reader. They are not in this repository: clippy.js\u2019s licence covers its code only, and the characters are Microsoft\u2019s."] }), _jsxs(Box, { as: "section", "aria-label": "Gallery controls", sx: {
                             display: 'grid',
                             gap: 3,
                             mb: 4,
@@ -192,7 +218,7 @@ const ChatAssistantGalleryExample = () => {
                                             gap: 2,
                                             flexWrap: 'wrap',
                                             alignItems: 'center',
-                                        }, children: [_jsx(SegmentedControl, { "aria-label": "Balloon", children: ['history', 'current'].map(option => (_jsx(SegmentedControl.Button, { selected: display === option, onClick: () => setDisplay(option), "data-gallery-balloon": option, children: option === 'history' ? 'History' : 'Current' }, option))) }), _jsx(Button, { onClick: say, "data-gallery-say": "", children: "Say something" }), _jsx(Button, { "data-gallery-tool": toolPhase ?? 'none', onClick: () => setToolPhase(toolPhase === undefined
+                                        }, children: [_jsx(GalleryToggle, { id: "gallery-balloon-history", label: "History", on: display === 'history', onChange: on => setDisplay(on ? 'history' : 'current'), state: display === 'history' ? 'History' : 'Current', "data-gallery-balloon-toggle": "" }), _jsx(GalleryToggle, { id: "gallery-expand-into-page", label: "Expand into the page", on: expandIntoPage, onChange: setExpandIntoPage, state: expandIntoPage ? 'The page area' : 'An overlay', "data-gallery-expand-toggle": "" }), _jsx(Button, { onClick: say, "data-gallery-say": "", children: "Say something" }), _jsx(Button, { "data-gallery-tool": toolPhase ?? 'none', onClick: () => setToolPhase(toolPhase === undefined
                                                     ? 'running'
                                                     : toolPhase === 'running'
                                                         ? 'done'
@@ -204,13 +230,19 @@ const ChatAssistantGalleryExample = () => {
                                                         ? 'Tool done'
                                                         : toolPhase === 'done'
                                                             ? 'Tool failed'
-                                                            : 'No tool' }), _jsx(Button, { "data-gallery-notebook": withNotebook ? 'on' : 'off', "aria-pressed": withNotebook, onClick: () => setWithNotebook(!withNotebook), children: withNotebook ? 'Take the notebook' : 'Give a notebook' }), saying !== undefined && (_jsx(Button, { variant: "invisible", onClick: () => setSaying(undefined), children: "Hush" })), presence === 'away' ? (_jsx(Button, { onClick: callBack, children: "Call it back" })) : (_jsx(Button, { onClick: () => sendAway('page'), disabled: presence !== 'here', "data-gallery-send-away": "", children: "Send it away" })), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Drag the character to move it; hover it for its own send-away menu." }), decision && (_jsx(Text, { role: "status", sx: { fontSize: 1 }, children: decision }))] })] }))] }), problem && (_jsxs(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mb: 3 }, children: ["The test sprite could not be read: ", problem] })), clippyJs.problem && (_jsxs(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mb: 3 }, children: ["A clippy.js character could not be read: ", clippyJs.problem] })), _jsx(Still, { still: still, children: view === 'stage' ? (_jsx(InModes, { modes: modes, children: mode => (_jsx(ModePanel, { mode: mode, character: character, pose: pose, presence: presence, balloon: balloon, insist: insist, onToggle: () => saying === undefined ? say() : setSaying(undefined), onDismiss: sendAway, onCallBack: callBack, away: away, replay: replay, display: display })) })) : (_jsx(InModes, { modes: modes, stacked: true, children: mode => (_jsxs(Box, { "data-gallery-mode": mode, sx: {
+                                                            : 'No tool' }), _jsx(Button, { "data-gallery-notebook": withNotebook ? 'on' : 'off', "aria-pressed": withNotebook, onClick: () => setWithNotebook(!withNotebook), children: withNotebook ? 'Take the notebook' : 'Give a notebook' }), saying !== undefined && (_jsx(Button, { variant: "invisible", onClick: () => setSaying(undefined), children: "Hush" })), presence === 'away' ? (_jsx(Button, { onClick: callBack, children: "Call it back" })) : (_jsx(Button, { onClick: () => sendAway('page'), disabled: presence !== 'here', "data-gallery-send-away": "", children: "Send it away" })), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: "Drag the character to move it; hover it for its own send-away menu." }), decision && (_jsx(Text, { role: "status", sx: { fontSize: 1 }, children: decision }))] })] }))] }), problem && (_jsxs(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mb: 3 }, children: ["The test sprite could not be read: ", problem] })), clippyJs.problem && (_jsxs(Text, { as: "p", role: "alert", sx: { color: 'danger.fg', mb: 3 }, children: ["A clippy.js character could not be read: ", clippyJs.problem] })), _jsx(Still, { still: still, children: view === 'stage' ? (_jsx(InModes, { modes: modes, children: mode => (_jsx(ModePanel, { mode: mode, character: character, pose: pose, presence: presence, balloon: balloon, insist: insist, onToggle: () => saying === undefined ? say() : setSaying(undefined), onDismiss: sendAway, onCallBack: callBack, away: away, replay: replay, display: display, expandTarget: expandIntoPage ? expandArea : undefined })) })) : (_jsx(InModes, { modes: modes, stacked: true, children: mode => (_jsxs(Box, { "data-gallery-mode": mode, sx: {
                                     bg: 'canvas.default',
                                     border: '1px solid',
                                     borderColor: 'border.default',
                                     borderRadius: 2,
                                     p: 2,
                                     overflowX: 'auto',
-                                }, children: [_jsx(AssistantGalleryGrid, { characters: characters }, replay), _jsx(GalleryBalloons, { character: character })] })) })) })] }) }) }));
+                                }, children: [_jsx(AssistantGalleryGrid, { characters: characters }, replay), _jsx(GalleryBalloons, { character: character })] })) })) }), view === 'stage' && expandIntoPage && (_jsxs(Box, { as: "section", "aria-label": "Expanded here", sx: {
+                            mt: 4,
+                            p: 3,
+                            border: '1px dashed',
+                            borderColor: 'border.default',
+                            borderRadius: 2,
+                        }, children: [_jsxs(Text, { as: "p", sx: { m: 0, mb: 2, color: 'fg.muted', fontSize: 1 }, children: ["Expanded here: what the balloon\u2019s ", _jsx("em", { children: "Expand" }), " draws large when the page names an area for it \u2014 the notebook, to edit and run on the browser sandbox. Without one, it opens in an overlay."] }), _jsx(Box, { ref: expandArea, "data-gallery-expand-target": "" })] }))] }) }) }));
 };
-export default ChatAssistantGalleryExample;
+export default AssistantGalleryExample;

package/lib/examples/example-selector.js

@@ -43,6 +43,8 @@ function inferTags(id) {
         tags.add('document');
     if (id.includes('Chat'))
         tags.add('chat');
+    if (id.startsWith('Assistant'))
+        tags.add('assistant');
     if (id.includes('Sandbox'))
         tags.add('sandbox');
     if (id.includes('Monitoring') || id.includes('Otel'))
@@ -87,9 +89,9 @@ export const EXAMPLE_ENTRIES = [
     makeEntry('DocumentPageAgent', () => import('./DocumentPageAgent'), 'A document as a page: floating prompt on top, an agent writing in it.'),
     makeEntry('DecksAgent', () => import('./DecksAgent'), 'A deck beside the chat: the decks plugin in a Loop, and an agent that writes presentations as data.'),
     makeEntry('CellExample', () => import('./CellExample'), 'Simple cell example.'),
-    makeEntry('ChatAssistantExample', () => import('./ChatAssistantExample'), 'The floating assistant: the chat as a character on the page.'),
+    makeEntry('AssistantExample', () => import('./AssistantExample'), 'The floating assistant: the chat as a character on the page.'),
     makeEntry('VoiceChatExample', () => import('./VoiceChatExample'), 'A voice chat with the floating assistant: push-to-talk heard in the page, answers read aloud by the speech service, the mouth moving with the sound.'),
-    makeEntry('ChatAssistantGalleryExample', () => import('./ChatAssistantGalleryExample'), 'Every representation of the floating assistant: each character in each state, its balloon, light and dark, still or moving, one at a time or as a grid.'),
+    makeEntry('AssistantGalleryExample', () => import('./AssistantGalleryExample'), 'Every representation of the floating assistant: each character in each state, its balloon, light and dark, still or moving, one at a time or as a grid.'),
     makeEntry('ChatCustomExample', () => import('./ChatCustomExample'), 'Custom chat experience composition example.'),
     makeEntry('ChatExample', () => import('./ChatExample'), 'Baseline chat integration example.'),
     makeEntry('ChatStandaloneExample', () => import('./ChatStandaloneExample'), 'Standalone chat component usage example.'),

package/lib/examples/exampleGroups.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The examples' groups, in the menu's order, and the group of each example
+ * by its id: a module of its own so the order can be tested without the
+ * examples shell.
+ *
+ * @module examples/exampleGroups
+ */
+export declare const EXAMPLE_GROUP_ORDER: readonly ["Apps", "A2UI", "A2A", "AG-UI", "Assistant", "Chat", "Document", "Notebook", "Capabilities", "Cell", "CopilotKit"];
+export declare const getExampleGroup: (id: string) => string;

package/lib/examples/exampleGroups.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The examples' groups, in the menu's order, and the group of each example
+ * by its id: a module of its own so the order can be tested without the
+ * examples shell.
+ *
+ * @module examples/exampleGroups
+ */
+export const EXAMPLE_GROUP_ORDER = [
+    'Apps',
+    'A2UI',
+    'A2A',
+    'AG-UI',
+    'Assistant',
+    'Chat',
+    'Document',
+    'Notebook',
+    'Capabilities',
+    'Cell',
+    'CopilotKit',
+];
+export const getExampleGroup = (id) => {
+    if (id === 'AgentspecsExample' ||
+        id.startsWith('Loop') ||
+        id === 'DecksAgent') {
+        return 'Apps';
+    }
+    if (id.startsWith('A2Ui'))
+        return 'A2UI';
+    // Agents reached over the A2A protocol: their own category, after A2UI.
+    if (id.startsWith('AgentA2A'))
+        return 'A2A';
+    if (id.startsWith('AgUi'))
+        return 'AG-UI';
+    if (id.startsWith('CopilotKit'))
+        return 'CopilotKit';
+    // Each remaining Agent* example demonstrates one capability of the
+    // runtime: checkpoints, hooks, memory, guardrails…
+    if (id.startsWith('Agent'))
+        return 'Capabilities';
+    // The floating assistant, and its gallery: before the chat they wrap.
+    if (id.startsWith('Assistant'))
+        return 'Assistant';
+    if (id.startsWith('Chat') || id === 'VoiceChatExample')
+        return 'Chat';
+    // The document examples: the ones on the Lexical editor, and the page
+    // with a document on it.
+    if (id.startsWith('Lexical') || id.startsWith('Document'))
+        return 'Document';
+    if (id.startsWith('Notebook'))
+        return 'Notebook';
+    return 'Cell';
+};

package/lib/examples/index.d.ts

@@ -15,7 +15,7 @@ export { default as AgUiHumanInTheLoopExample } from './AgUiHumanInTheLoopExampl
 export { default as AgUiSharedStateExample } from './AgUiSharedStateExample';
 export { default as AgUiToolsBasedGenUiExample } from './AgUiToolsBasedGenUiExample';
 export { default as CellExample } from './CellExample';
-export { default as ChatAssistantGalleryExample } from './ChatAssistantGalleryExample';
+export { default as AssistantGalleryExample } from './AssistantGalleryExample';
 export { default as ChatStandaloneExample } from './ChatStandaloneExample';
 export { default as CopilotKitLexicalExample } from './CopilotKitLexicalExample';
 export { default as CopilotKitNotebookExample } from './CopilotKitNotebookExample';

package/lib/examples/index.js

@@ -21,7 +21,7 @@ export { default as AgUiHumanInTheLoopExample } from './AgUiHumanInTheLoopExampl
 export { default as AgUiSharedStateExample } from './AgUiSharedStateExample';
 export { default as AgUiToolsBasedGenUiExample } from './AgUiToolsBasedGenUiExample';
 export { default as CellExample } from './CellExample';
-export { default as ChatAssistantGalleryExample } from './ChatAssistantGalleryExample';
+export { default as AssistantGalleryExample } from './AssistantGalleryExample';
 export { default as ChatStandaloneExample } from './ChatStandaloneExample';
 export { default as CopilotKitLexicalExample } from './CopilotKitLexicalExample';
 export { default as CopilotKitNotebookExample } from './CopilotKitNotebookExample';

package/lib/examples/main.js

@@ -27,6 +27,7 @@ import { useSimpleAuthStore } from '@datalayer/core/lib/views/otel';
 import { teardownExampleAgents } from './utils/teardownAgents';
 import { OAuthCallback } from '../identity';
 import { EXAMPLES, getExampleEntries, } from './example-selector';
+import { EXAMPLE_GROUP_ORDER, getExampleGroup } from './exampleGroups';
 import { RUNTIME_TARGETS, runtimeTargetCapabilities, runtimeTargetStore, targetHasAgent, useRuntimeTargetStore, } from './utils/runtimeTargetStore';
 import { resolveExampleAgentRuntimesUrl } from './utils/useExampleAgentRuntimesUrl';
 import { isLocalUrl } from './utils/localUrl';
@@ -46,18 +47,6 @@ const DEFAULT_RUNTIMES_URL = 'https://r1.datalayer.run';
 const DEFAULT_LOCAL_JUPYTER_SERVER_URL = 'http://localhost:8888/api/jupyter-server';
 const DEFAULT_LOCAL_JUPYTER_SERVER_TOKEN = '60c1661cc408f978c309d04157af55c9588ff9557c9380e4fb50785750703da6';
 const DEFAULT_CLOUD_RUNTIME_ENVIRONMENT = 'ai-agents-env';
-const EXAMPLE_GROUP_ORDER = [
-    'Apps',
-    'A2UI',
-    'A2A',
-    'AG-UI',
-    'Chat',
-    'Document',
-    'Notebook',
-    'Capabilities',
-    'Cell',
-    'CopilotKit',
-];
 /**
  * The examples that open without an account.
  *
@@ -88,42 +77,13 @@ const ANONYMOUS_EXAMPLES = new Set([
     'DecksAgent',
     // The floating assistant: the character, its balloon and its motions need
     // no runtime; a conversation does, and says so when there is none.
-    'ChatAssistantExample',
+    'AssistantExample',
     // Every character in every state, from static data: no agent at all.
-    'ChatAssistantGalleryExample',
+    'AssistantGalleryExample',
     // Voice: heard in the page, the agent on the local server, the speech
     // service named in the address.
     'VoiceChatExample',
 ]);
-const getExampleGroup = (id) => {
-    if (id === 'AgentspecsExample' ||
-        id.startsWith('Loop') ||
-        id === 'DecksAgent') {
-        return 'Apps';
-    }
-    if (id.startsWith('A2Ui'))
-        return 'A2UI';
-    // Agents reached over the A2A protocol: their own category, after A2UI.
-    if (id.startsWith('AgentA2A'))
-        return 'A2A';
-    if (id.startsWith('AgUi'))
-        return 'AG-UI';
-    if (id.startsWith('CopilotKit'))
-        return 'CopilotKit';
-    // Each remaining Agent* example demonstrates one capability of the
-    // runtime: checkpoints, hooks, memory, guardrails…
-    if (id.startsWith('Agent'))
-        return 'Capabilities';
-    if (id.startsWith('Chat') || id === 'VoiceChatExample')
-        return 'Chat';
-    // The document examples: the ones on the Lexical editor, and the page
-    // with a document on it.
-    if (id.startsWith('Lexical') || id.startsWith('Document'))
-        return 'Document';
-    if (id.startsWith('Notebook'))
-        return 'Notebook';
-    return 'Cell';
-};
 const wait = (ms) => new Promise(resolve => {
     window.setTimeout(resolve, ms);
 });

package/lib/examples/utils/AssistantGalleryGrid.d.ts

@@ -46,7 +46,12 @@ export declare function GalleryNotebook({ onOpen, }: {
     onOpen?: () => void;
 }): JSX.Element;
 /**
- * The balloon's displays (T-23), one character: a peek of the history, the
+ * The sample notebook as the balloon's large visual: expanded, the notebook
+ * that runs and is edited on the browser sandbox (`TeamNotebook`).
+ */
+export declare function galleryNotebookVisual(): import("../../chat/assistant/BalloonVisual").BalloonVisual;
+/**
+ * The balloon's displays (T-23), one character: the history, every message listed, the
  * current balloon with a tool line, and with a notebook given — the same
  * read-only jupyter-react notebook as in the stage, loaded when drawn.
  */

package/lib/examples/utils/AssistantGalleryGrid.js

@@ -7,8 +7,9 @@ import { AssistantStage } from '../../chat/assistant/AssistantStage';
 import { AssistantCharactersPlugin, assistantCharactersOf, } from '../../loop/plugins/assistant-characters';
 import { OWL_CHARACTER, OwlCharacterPlugin } from './owlCharacterPlugin';
 import { NotebookPreview } from '../../components/teams/NotebookPreview';
+import { notebookBalloonVisual } from '../../components/teams/TeamNotebook';
 import { readTestSpriteCharacter } from './testSpriteCharacter';
-import { GALLERY_POSES, GALLERY_POSE_LABELS, SAMPLE_NOTEBOOK, SAMPLE_NOTEBOOK_SAYING, sampleSaying, sampleToolLine, stateOfPose, } from './assistantGallery';
+import { GALLERY_POSES, GALLERY_POSE_LABELS, SAMPLE_NOTEBOOK, SAMPLE_NOTEBOOK_ARTIFACT, SAMPLE_NOTEBOOK_SAYING, sampleHistory, sampleSaying, sampleToolLine, stateOfPose, } from './assistantGallery';
 /** The plugins the gallery enables: Datalayer's characters and the owl's. */
 const reactor = buildReactorFromPlugins([
     AssistantCharactersPlugin,
@@ -127,6 +128,13 @@ export const GALLERY_NOTEBOOK_HEIGHT = 160;
 export function GalleryNotebook({ onOpen, }) {
     return (_jsx(NotebookPreview, { notebook: SAMPLE_NOTEBOOK, title: "Accounting\u2019s notebook", maxHeight: GALLERY_NOTEBOOK_HEIGHT, onOpen: onOpen }));
 }
+/**
+ * The sample notebook as the balloon's large visual: expanded, the notebook
+ * that runs and is edited on the browser sandbox (`TeamNotebook`).
+ */
+export function galleryNotebookVisual() {
+    return notebookBalloonVisual(SAMPLE_NOTEBOOK_ARTIFACT, 'Accounting’s notebook', 420);
+}
 /** One balloon display, pictured: a character with what its balloon says. */
 function BalloonCell({ character, label, display, balloon, height, }) {
     const stageRef = useRef(null);
@@ -147,18 +155,23 @@ function BalloonCell({ character, label, display, balloon, height, }) {
                 }, children: label }), _jsx(AssistantStage, { character: character.character, state: balloon.tool ? 'working' : 'speaking', size: 48, place: { position: 'absolute', left: '12px', bottom: '8px' }, stageRef: stageRef, onDragStart: () => undefined, open: false, onToggle: () => undefined, onDismiss: () => undefined, balloon: balloon, balloonDisplay: display, insist: true })] }));
 }
 /**
- * The balloon's displays (T-23), one character: a peek of the history, the
+ * The balloon's displays (T-23), one character: the history, every message listed, the
  * current balloon with a tool line, and with a notebook given — the same
  * read-only jupyter-react notebook as in the stage, loaded when drawn.
  */
 export function GalleryBalloons({ character, }) {
-    return (_jsxs(Box, { "data-gallery-balloons": "", sx: { display: 'flex', gap: 3, flexWrap: 'wrap', mt: 3 }, children: [_jsx(BalloonCell, { character: character, label: "History", display: "history", height: 180, balloon: { ...sampleSaying(0), onDismiss: () => undefined } }), _jsx(BalloonCell, { character: character, label: "Current \u00B7 tool", display: "current", height: 180, balloon: {
+    return (_jsxs(Box, { "data-gallery-balloons": "", sx: { display: 'flex', gap: 3, flexWrap: 'wrap', mt: 3 }, children: [_jsx(BalloonCell, { character: character, label: "History", display: "history", height: 340, balloon: {
+                    ...sampleSaying(1),
+                    history: sampleHistory(2),
+                    onDismiss: () => undefined,
+                } }), _jsx(BalloonCell, { character: character, label: "Current \u00B7 tool", display: "current", height: 180, balloon: {
                     text: 'Using list_invoices…',
                     tool: sampleToolLine('running'),
                     busy: true,
                 } }), _jsx(BalloonCell, { character: character, label: "Current \u00B7 notebook", display: "current", height: GALLERY_NOTEBOOK_HEIGHT + 210, balloon: {
                     text: SAMPLE_NOTEBOOK_SAYING,
                     attachment: _jsx(GalleryNotebook, {}),
+                    visual: galleryNotebookVisual(),
                 } })] }));
 }
 export default AssistantGalleryGrid;