@datalayer/agent-runtimes 1.3.58 → 1.3.59

package/lib/examples/ChatAssistantGalleryExample.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every representation of the floating assistant, as a gallery (LOOP T-21
+ * to T-27): each character — Datalayer's four, the owl an example plugin
+ * contributes to `loop.assistant.character`, and a test sprite read through
+ * the clippy.js reader — in each state it acts, stepped aside, with its
+ * balloon, in light and dark, moving or still.
+ *
+ * Static data, no agent: it opens without a server or an account.
+ */
+import React from 'react';
+declare const ChatAssistantGalleryExample: React.FC;
+export default ChatAssistantGalleryExample;

package/lib/examples/ChatAssistantGalleryExample.js

@@ -0,0 +1,181 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Every representation of the floating assistant, as a gallery (LOOP T-21
+ * to T-27): each character — Datalayer's four, the owl an example plugin
+ * contributes to `loop.assistant.character`, and a test sprite read through
+ * the clippy.js reader — in each state it acts, stepped aside, with its
+ * balloon, in light and dark, moving or still.
+ *
+ * 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 { 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, GalleryObstacle, Still, useGalleryCharacters, } from './utils/AssistantGalleryGrid';
+import { GALLERY_POSES, GALLERY_POSE_LABELS, balloonForPose, sampleApproval, sampleSaying, stateOfPose, } from './utils/assistantGallery';
+const STAGE_SIZE = 96;
+const PANEL_HEIGHT = 420;
+const LEAVE_MS = 700;
+const ARRIVE_MS = 1900;
+const AWAY_WORDS = {
+    none: '',
+    page: 'for now',
+    session: 'for this session',
+    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, }) {
+    const panelRef = useRef(null);
+    const stageRef = useRef(null);
+    const drag = useViewportDrag(stageRef, { whole: true });
+    // Where it stands in the panel: the drag's viewport place, made the
+    // panel's own once, so a scroll does not move it.
+    const [spot, setSpot] = useState({ left: 48, top: PANEL_HEIGHT - 150 });
+    useEffect(() => {
+        const panel = panelRef.current;
+        if (drag.position && panel) {
+            const box = panel.getBoundingClientRect();
+            setSpot({
+                left: drag.position.left - box.left,
+                top: drag.position.top - box.top,
+            });
+        }
+    }, [drag.position]);
+    const state = presence === 'leaving'
+        ? 'goodbye'
+        : presence === 'arriving'
+            ? 'greeting'
+            : stateOfPose(pose);
+    return (_jsxs(Box, { ref: panelRef, "data-gallery-mode": mode, sx: {
+            position: 'relative',
+            flex: '1 1 320px',
+            minWidth: 0,
+            height: PANEL_HEIGHT,
+            bg: 'canvas.default',
+            color: 'fg.default',
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            overflow: 'visible',
+        }, children: [_jsx(Text, { sx: {
+                    position: 'absolute',
+                    top: 2,
+                    left: 3,
+                    fontSize: 0,
+                    fontWeight: 600,
+                    color: 'fg.muted',
+                    textTransform: 'uppercase',
+                    letterSpacing: '0.04em',
+                }, children: mode }), presence === 'away' ? (_jsxs(Box, { sx: {
+                    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, 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,
+                } }))] }));
+}
+/** The panels in the modes asked, each in the examples' theme. */
+function InModes({ modes, stacked = false, children, }) {
+    const { theme } = useExampleThemeStore();
+    const config = themeConfigs[theme] ?? themeConfigs.loop;
+    const shown = modes === 'both' ? ['light', 'dark'] : [modes];
+    return (_jsx(Box, { sx: {
+            display: 'flex',
+            flexDirection: stacked ? 'column' : 'row',
+            gap: 3,
+            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 { characters, problem } = useGalleryCharacters();
+    const [characterId, setCharacterId] = useState('paperclip');
+    const [pose, setPose] = useState('idle');
+    const [view, setView] = useState('stage');
+    const [modes, setModes] = useState('both');
+    const [still, setStill] = useState(false);
+    const [saying, setSaying] = useState();
+    const [said, setSaid] = useState(0);
+    const [decision, setDecision] = useState();
+    const [presence, setPresence] = useState('here');
+    const [away, setAway] = useState('none');
+    const [replay, setReplay] = useState(0);
+    const character = characters.find(entry => entry.id === characterId) ?? characters[0];
+    // Leaving takes the goodbye's length; arriving, the greeting's.
+    useEffect(() => {
+        if (presence !== 'leaving' && presence !== 'arriving') {
+            return;
+        }
+        const timer = window.setTimeout(() => setPresence(presence === 'leaving' ? 'away' : 'here'), presence === 'leaving' ? LEAVE_MS : ARRIVE_MS);
+        return () => window.clearTimeout(timer);
+    }, [presence]);
+    const sendAway = (choice) => {
+        setAway(choice);
+        setPresence('leaving');
+    };
+    const callBack = () => {
+        setAway('none');
+        setPresence('arriving');
+    };
+    const say = () => {
+        setSaying(said);
+        setSaid(said + 1);
+    };
+    const approval = sampleApproval(() => setDecision('Approved: send_reply.'), () => setDecision('Denied: send_reply.'));
+    const balloon = balloonForPose(pose, {
+        saying: saying === undefined ? undefined : sampleSaying(saying),
+        approval,
+    });
+    const insist = saying !== undefined || pose === 'waiting' || pose === 'paused';
+    return (_jsx(ThemedProvider, { children: _jsx(Box, { sx: {
+                minHeight: '100vh',
+                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: "Floating 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(Box, { as: "section", "aria-label": "Gallery controls", sx: {
+                            display: 'grid',
+                            gap: 3,
+                            mb: 4,
+                            p: 3,
+                            border: '1px solid',
+                            borderColor: 'border.default',
+                            borderRadius: 2,
+                            bg: 'canvas.subtle',
+                        }, children: [_jsxs(Box, { sx: {
+                                    display: 'flex',
+                                    gap: 3,
+                                    flexWrap: 'wrap',
+                                    alignItems: 'center',
+                                }, children: [_jsxs(SegmentedControl, { "aria-label": "View", children: [_jsx(SegmentedControl.Button, { selected: view === 'stage', onClick: () => setView('stage'), children: "One at a time" }), _jsx(SegmentedControl.Button, { selected: view === 'grid', onClick: () => setView('grid'), "data-gallery-view": "grid", children: "Grid" })] }), _jsx(SegmentedControl, { "aria-label": "Colour mode", children: ['light', 'dark', 'both'].map(option => (_jsx(SegmentedControl.Button, { selected: modes === option, onClick: () => setModes(option), children: option === 'both'
+                                                ? 'Side by side'
+                                                : option === 'light'
+                                                    ? 'Light'
+                                                    : 'Dark' }, option))) }), _jsxs(FormControl, { children: [_jsx(Checkbox, { checked: still, onChange: event => setStill(event.target.checked) }), _jsx(FormControl.Label, { children: "Reduced motion" })] }), _jsx(Button, { onClick: () => setReplay(replay + 1), children: "Replay the motions" })] }), view === 'stage' && (_jsxs(_Fragment, { children: [_jsx(Box, { role: "group", "aria-label": "Character", sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: characters.map(option => (_jsx(Button, { size: "small", variant: option.id === character.id ? 'primary' : 'default', "aria-pressed": option.id === character.id, "data-gallery-character": option.id, onClick: () => setCharacterId(option.id), children: option.name }, option.id))) }), _jsx(Box, { role: "group", "aria-label": "State", sx: { display: 'flex', gap: 2, flexWrap: 'wrap' }, children: GALLERY_POSES.map(option => (_jsx(Button, { size: "small", variant: option === pose ? 'primary' : 'default', "aria-pressed": option === pose, "data-gallery-pose": option, onClick: () => {
+                                                setPose(option);
+                                                setDecision(undefined);
+                                                setReplay(replay + 1);
+                                            }, children: GALLERY_POSE_LABELS[option] }, option))) }), _jsxs(Box, { sx: {
+                                            display: 'flex',
+                                            gap: 2,
+                                            flexWrap: 'wrap',
+                                            alignItems: 'center',
+                                        }, children: [_jsx(Button, { onClick: say, "data-gallery-say": "", children: "Say something" }), 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] })), _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 })) })) : (_jsx(InModes, { modes: modes, stacked: true, children: mode => (_jsx(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) })) })) })] }) }) }));
+};
+export default ChatAssistantGalleryExample;

package/lib/examples/example-selector.js

@@ -88,6 +88,7 @@ export const EXAMPLE_ENTRIES = [
     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('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('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/index.d.ts

@@ -15,6 +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 ChatStandaloneExample } from './ChatStandaloneExample';
 export { default as CopilotKitLexicalExample } from './CopilotKitLexicalExample';
 export { default as CopilotKitNotebookExample } from './CopilotKitNotebookExample';

package/lib/examples/index.js

@@ -21,6 +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 ChatStandaloneExample } from './ChatStandaloneExample';
 export { default as CopilotKitLexicalExample } from './CopilotKitLexicalExample';
 export { default as CopilotKitNotebookExample } from './CopilotKitNotebookExample';

package/lib/examples/main.js

@@ -83,6 +83,8 @@ const ANONYMOUS_EXAMPLES = new Set([
     // The floating assistant: the character, its balloon and its motions need
     // no runtime; a conversation does, and says so when there is none.
     'ChatAssistantExample',
+    // Every character in every state, from static data: no agent at all.
+    'ChatAssistantGalleryExample',
 ]);
 const getExampleGroup = (id) => {
     if (id === 'AgentspecsExample' ||

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

@@ -0,0 +1,53 @@
+/**
+ * The floating assistant's characters, every one in every pose, small, for
+ * a quick visual check (LOOP T-16, T-22, T-24 to T-27): Datalayer's four and
+ * the owl as the enabled plugins contribute them to
+ * `loop.assistant.character`, and a test sprite read through the clippy.js
+ * reader. Each cell is the real `AssistantStage`, set in the grid's flow
+ * rather than fixed to the window; stepped aside is the real `useKeepClear`
+ * stepping it aside from a composer laid over the cell.
+ *
+ * @module examples/utils/AssistantGalleryGrid
+ */
+import type { JSX, ReactNode } from 'react';
+import type { AssistantCharacter } from '../../chat/assistant/characters';
+import type { AssistantCharacterData } from '../../chat/assistant/formats/types';
+/** A character of the gallery: by id, with its name, as contributed. */
+export interface GalleryCharacter {
+    id: string;
+    name: string;
+    character: AssistantCharacter | AssistantCharacterData;
+    /** Where it comes from, as the gallery says it. */
+    from: string;
+}
+/** What the enabled plugins contribute, in contribution order. */
+export declare const CONTRIBUTED_CHARACTERS: readonly GalleryCharacter[];
+/** The id the test sprite is shown under. */
+export declare const SPRITE_CHARACTER_ID = "sprite";
+/**
+ * The gallery's characters: the contributed ones at once, and the test
+ * sprite once its files are read; `ready` once they all are.
+ */
+export declare function useGalleryCharacters(): {
+    characters: readonly GalleryCharacter[];
+    ready: boolean;
+    problem?: string;
+};
+/** Its children without motion, as a reader asking for reduced motion sees them. */
+export declare function Still({ still, children, }: {
+    still: boolean;
+    children: ReactNode;
+}): JSX.Element;
+/**
+ * What the assistant steps aside from (T-27): a composer laid over it. The
+ * stage's own `useKeepClear` finds it and steps aside.
+ */
+export declare function GalleryObstacle({ sx, }: {
+    sx?: Record<string, unknown>;
+}): JSX.Element;
+/** Every character in every pose: a row per character, a column per pose. */
+export declare function AssistantGalleryGrid({ characters, size, }: {
+    characters: readonly GalleryCharacter[];
+    size?: number;
+}): JSX.Element;
+export default AssistantGalleryGrid;

package/lib/examples/utils/AssistantGalleryGrid.js

@@ -0,0 +1,123 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { Text } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { buildReactorFromPlugins } from '@datalayer/reactor';
+import { AssistantStage } from '../../chat/assistant/AssistantStage';
+import { AssistantCharactersPlugin, assistantCharactersOf, } from '../../loop/plugins/assistant-characters';
+import { OWL_CHARACTER, OwlCharacterPlugin } from './owlCharacterPlugin';
+import { readTestSpriteCharacter } from './testSpriteCharacter';
+import { GALLERY_POSES, GALLERY_POSE_LABELS, stateOfPose, } from './assistantGallery';
+/** The plugins the gallery enables: Datalayer's characters and the owl's. */
+const reactor = buildReactorFromPlugins([
+    AssistantCharactersPlugin,
+    OwlCharacterPlugin,
+]);
+reactor.start();
+/** What the enabled plugins contribute, in contribution order. */
+export const CONTRIBUTED_CHARACTERS = assistantCharactersOf(reactor).map(entry => ({
+    id: entry.id,
+    name: entry.character.name,
+    character: entry.character,
+    from: entry.id === OWL_CHARACTER.id ? 'Example plugin' : 'Datalayer',
+}));
+/** The id the test sprite is shown under. */
+export const SPRITE_CHARACTER_ID = 'sprite';
+/**
+ * The gallery's characters: the contributed ones at once, and the test
+ * sprite once its files are read; `ready` once they all are.
+ */
+export function useGalleryCharacters() {
+    const [sprite, setSprite] = useState();
+    const [problem, setProblem] = useState();
+    useEffect(() => {
+        let cancelled = false;
+        readTestSpriteCharacter().then(read => {
+            if (!cancelled) {
+                setSprite(read);
+            }
+        }, error => {
+            if (!cancelled) {
+                setProblem(error instanceof Error ? error.message : String(error));
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    // The object URL lives as long as the gallery does.
+    useEffect(() => () => {
+        if (sprite) {
+            URL.revokeObjectURL(sprite.sprite);
+        }
+    }, [sprite]);
+    return {
+        characters: sprite
+            ? [
+                ...CONTRIBUTED_CHARACTERS,
+                {
+                    id: SPRITE_CHARACTER_ID,
+                    name: `${sprite.name} (sprite)`,
+                    character: sprite,
+                    from: 'clippy.js reader',
+                },
+            ]
+            : CONTRIBUTED_CHARACTERS,
+        ready: !!sprite || !!problem,
+        problem,
+    };
+}
+/** Its children without motion, as a reader asking for reduced motion sees them. */
+export function Still({ still, children, }) {
+    return (_jsx(Box, { "data-gallery-still": still ? '' : undefined, sx: still ? { '& *': { animation: 'none !important' } } : undefined, children: children }));
+}
+/**
+ * What the assistant steps aside from (T-27): a composer laid over it. The
+ * stage's own `useKeepClear` finds it and steps aside.
+ */
+export function GalleryObstacle({ sx, }) {
+    return (_jsx(Box, { "data-chat-composer": "", "aria-label": "A composer over the assistant", sx: {
+            position: 'absolute',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            border: '1px dashed',
+            borderColor: 'border.default',
+            borderRadius: 2,
+            bg: 'canvas.subtle',
+            color: 'fg.muted',
+            fontSize: 0,
+            textAlign: 'center',
+            p: 1,
+            ...sx,
+        }, children: "composer" }));
+}
+function GalleryCell({ character, pose, size, }) {
+    const stageRef = useRef(null);
+    return (_jsxs(Box, { "data-gallery-cell": `${character.id}-${pose}`, sx: {
+            position: 'relative',
+            width: size + 16,
+            height: size + 16,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+        }, children: [_jsx(AssistantStage, { character: character.character, state: stateOfPose(pose), size: size, place: { position: 'relative', zIndex: 0 }, stageRef: stageRef, onDragStart: () => undefined, open: false, onToggle: () => undefined, onDismiss: () => undefined }), pose === 'aside' && _jsx(GalleryObstacle, { sx: { inset: 0 } })] }));
+}
+/** Every character in every pose: a row per character, a column per pose. */
+export function AssistantGalleryGrid({ characters, size = 48, }) {
+    return (_jsxs(Box, { as: "table", "data-assistant-gallery-grid": "", sx: {
+            borderCollapse: 'collapse',
+            color: 'fg.default',
+            '& th': {
+                fontSize: 0,
+                fontWeight: 600,
+                color: 'fg.muted',
+                px: 1,
+                py: 1,
+                textAlign: 'center',
+                whiteSpace: 'nowrap',
+            },
+            '& td': { p: 0, textAlign: 'center' },
+        }, children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", {}), GALLERY_POSES.map(pose => (_jsx("th", { scope: "col", children: GALLERY_POSE_LABELS[pose] }, pose)))] }) }), _jsx("tbody", { children: characters.map(character => (_jsxs("tr", { children: [_jsxs(Box, { as: "th", scope: "row", sx: { textAlign: 'left !important', pr: '12px !important' }, children: [_jsx(Text, { sx: { display: 'block', color: 'fg.default' }, children: character.name }), _jsx(Text, { sx: { fontWeight: 400 }, children: character.from })] }), GALLERY_POSES.map(pose => (_jsx("td", { children: _jsx(GalleryCell, { character: character, pose: pose, size: size }) }, pose)))] }, character.id))) })] }));
+}
+export default AssistantGalleryGrid;

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

@@ -0,0 +1,42 @@
+/**
+ * What the floating assistant's gallery shows (LOOP T-21 to T-27): every
+ * state a character acts (T-22), and stepped aside (T-27), with the balloon
+ * each one says — the agent's latest saying (T-23), an approval to answer,
+ * or that it is paused. Static data only: no agent, no server.
+ *
+ * @module examples/utils/assistantGallery
+ */
+import type { AssistantStageProps } from '../../chat/assistant/AssistantStage';
+import { type AssistantState, type BalloonApproval } from '../../chat/assistant/state';
+/** What the gallery poses a character in: a state, or stepped aside. */
+export type GalleryPose = AssistantState | 'aside';
+/** Every state, in the order an assistant lives them, then stepped aside. */
+export declare const GALLERY_POSES: readonly ["idle", "greeting", "thinking", "working", "waiting", "speaking", "paused", "aside", "goodbye"];
+/** How the gallery names each pose. */
+export declare const GALLERY_POSE_LABELS: Record<GalleryPose, string>;
+/** The state the stage acts for a pose: aside, it is idle under what covers it. */
+export declare function stateOfPose(pose: GalleryPose): AssistantState;
+/**
+ * What the agent said, as a conversation would hold it: each entry is read
+ * by `latestSaying`, as the floating assistant reads the chat — Markdown made
+ * plain, a long answer cut with *Open the conversation*.
+ */
+export declare const SAMPLE_CONVERSATIONS: readonly (readonly unknown[])[];
+/** The saying of sample `index` (wrapping), as the balloon shows it. */
+export declare function sampleSaying(index: number): {
+    text: string;
+    more: boolean;
+};
+/** The approval the gallery waits on (T-23): answered in the balloon. */
+export declare function sampleApproval(onApprove: () => void, onDeny: () => void): BalloonApproval;
+/**
+ * The balloon for a pose: waiting holds the approval, paused says so, and
+ * any other pose says the sample's words when asked to (`saying`).
+ */
+export declare function balloonForPose(pose: GalleryPose, { saying, approval, }: {
+    saying?: {
+        text: string;
+        more: boolean;
+    };
+    approval: BalloonApproval;
+}): AssistantStageProps['balloon'];

package/lib/examples/utils/assistantGallery.js

@@ -0,0 +1,102 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { ASSISTANT_WORDS, latestSaying, } from '../../chat/assistant/state';
+/** Every state, in the order an assistant lives them, then stepped aside. */
+export const GALLERY_POSES = [
+    'idle',
+    'greeting',
+    'thinking',
+    'working',
+    'waiting',
+    'speaking',
+    'paused',
+    'aside',
+    'goodbye',
+];
+/** How the gallery names each pose. */
+export const GALLERY_POSE_LABELS = {
+    idle: 'Idle',
+    greeting: 'Greeting',
+    thinking: 'Thinking',
+    working: 'Working',
+    waiting: 'Waiting',
+    speaking: 'Speaking',
+    paused: 'Paused',
+    aside: 'Stepped aside',
+    goodbye: 'Goodbye',
+};
+/** The state the stage acts for a pose: aside, it is idle under what covers it. */
+export function stateOfPose(pose) {
+    return pose === 'aside' ? 'idle' : pose;
+}
+/**
+ * What the agent said, as a conversation would hold it: each entry is read
+ * by `latestSaying`, as the floating assistant reads the chat — Markdown made
+ * plain, a long answer cut with *Open the conversation*.
+ */
+export const SAMPLE_CONVERSATIONS = [
+    [
+        { id: 'u1', role: 'user', content: 'Who wrote about late deliveries?' },
+        {
+            id: 'a1',
+            role: 'assistant',
+            content: 'Three customers wrote about **late deliveries** this week: Ada, Grace and Alan.',
+        },
+    ],
+    [
+        { id: 'u2', role: 'user', content: 'Is the notebook up to date?' },
+        { id: 't2', role: 'assistant', toolName: 'readCell', content: '' },
+        {
+            id: 'a2',
+            role: 'assistant',
+            content: 'Yes — the last cell ran at 9:40 and its [chart](#chart) shows the new week.',
+        },
+    ],
+    [
+        { id: 'u3', role: 'user', content: 'Summarise the quarter.' },
+        {
+            id: 'a3',
+            role: 'assistant',
+            content: 'Revenue grew 12% on the quarter, carried by the renewals in March. Churn held at 2.1%, the same as the last two quarters, and the new plan took 140 accounts in its first six weeks. Support tickets fell by a fifth after the onboarding change, and the slowest region, the north, closed half its gap with the others. The full table, with each region and month, is in the notebook.',
+        },
+    ],
+];
+/** The saying of sample `index` (wrapping), as the balloon shows it. */
+export function sampleSaying(index) {
+    const conversation = SAMPLE_CONVERSATIONS[((index % SAMPLE_CONVERSATIONS.length) + SAMPLE_CONVERSATIONS.length) %
+        SAMPLE_CONVERSATIONS.length];
+    const saying = latestSaying(conversation);
+    if (!saying) {
+        throw new Error(`The sample conversation ${index} says nothing.`);
+    }
+    return { text: saying.text, more: saying.more };
+}
+/** The approval the gallery waits on (T-23): answered in the balloon. */
+export function sampleApproval(onApprove, onDeny) {
+    return {
+        id: 'gallery-approval',
+        asks: 'send_reply',
+        why: 'Send a reply to a customer: ask me first',
+        others: 1,
+        onApprove,
+        onDeny,
+    };
+}
+/**
+ * The balloon for a pose: waiting holds the approval, paused says so, and
+ * any other pose says the sample's words when asked to (`saying`).
+ */
+export function balloonForPose(pose, { saying, approval, }) {
+    if (pose === 'waiting') {
+        return { text: ASSISTANT_WORDS.approval, approval };
+    }
+    if (pose === 'paused') {
+        return { text: ASSISTANT_WORDS.paused };
+    }
+    if (pose === 'goodbye' || pose === 'aside') {
+        return undefined;
+    }
+    return saying;
+}

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

@@ -0,0 +1,9 @@
+import type { AssistantCharacterData } from '../../chat/assistant/formats/types';
+/** The character's `agent.js`, as clippy.js registers one. */
+export declare const TEST_SPRITE_AGENT_JS = "\nclippy.ready('Pixel', {\n  overlayCount: 1,\n  framesize: [48, 48],\n  animations: {\n    Idle1_1: { frames: [{ duration: 1200, images: [[0, 0]] }] },\n    Thinking: { frames: [{ duration: 1200, images: [[48, 0]] }] },\n    Processing: { frames: [\n      { duration: 240, images: [[96, 0]] },\n      { duration: 240, images: [[144, 0]] },\n    ] },\n    GetAttention: { frames: [{ duration: 900, images: [[192, 0]] }] },\n    Sleep: { frames: [{ duration: 1600, images: [[240, 0]] }] },\n    Greeting: { frames: [{ duration: 900, images: [[288, 0]] }] },\n    Explain: { frames: [\n      { duration: 200, images: [[336, 0]] },\n      { duration: 200, images: [[384, 0]] },\n    ] },\n    GoodBye: { frames: [{ duration: 900, images: [[432, 0]] }] },\n  },\n});\n";
+/** Its sprite sheet, `map.png` (480×48), base64. */
+export declare const TEST_SPRITE_MAP_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAeAAAAAwCAYAAADJnakOAAAF/klEQVR42u2dMW8rRRDHx5YfHd1LwfUgCwkKGgrQowuiCS3KB6CgokhhJATtFakooKChygeIKEgkiryWhvLEB/Ar/DoKJChCQdbcOzvnW9/u7M7e7ydZiqORPTf3v5n7r+/smQBAFNar5b37u6qbGRUBgDZzSgAAAKDPghJEcz8fisiliDwRkW+ruvmZqgAAAAM4Pt+JyGci8qeI3IkIAxgAABjAGgO4qps/1qvlayLyOuWAqbFeLb8Xkbcf+sz7Vd08oSoADODoVHXz08Of74rIb1QEJngMfPEwiL8WkV+pCAADWJtPReQHyjDJATT5K5/Xq+U7InImIh+gCAAGsDZvisg3lGGSw2fStyGtV8uFiPwoIp9XdfNP6Nd/evrsPtRrvbx9zm1iwAAukC+rurmnDDTQCfKViPxS1c3vueqm+5roCDRBbPFdwG1VN6dUIm4DZRBnqf2/5b/rH5z7/aSqm79C6aY6PwuX69U1OgJbA9i6gyF/3fxLa6A4+DRaD6mbPh3F3if0H/Q/S134HAYB+cfPv6QGioNPN4Bjaqerocf2xdPTZ/dj9hP9B/0fNYCtOxjyT5d/Tg0UB2/LwWhq55CG2jXz3Wb6T5z8j90nOej/qGQtOhjyT5d/Tg0UB2/PweQ6gH22l/4TN3+fi+hy0r/3VdCxD4Lq/GznbCj065N/uvytY7n+Gg4m9NXEKYZvez+0l5uPHb70H738+z4eyFH/s1wPgpAOhvzT5Z+qgVrfBhz88Nq333PItg2N7+6Dse6X/hM3/77hl6v+uQ8YkhOrgULZKyjufTY3d9v/nXz80aPb6Rvf5564WC5f+lxwbvqfD9mYFI3Ovd/Y9XryT5v/oQa6vrqWzc3d9uH+FyI+pHO0XH/tbdDQjqM9TPc9Hxs/djvoP3r5H1p6zlH/QRywdQdD/unY1xCdKwkRT/3LXTVxWjg5eeN/PWxebDXRrq1v/DGNnv6TT/5jbxXTYhGi8BpLQFGEc3H5yoF4MH/PeC3hW6x/uyHuG7J9DXRIPPVP72C6FzGVQMhtMd8/M8z/5e3zWdt55q7/+dg30lgCSunIQsdrOEjL9bcG9Ycp6yfn/DU+AhnL0QO4u6TjHq6o3c/lfOM1l032iWRf/j7xqR1kX/1zyL9LVxOh42PW36L+rVOdn23d02bzYvtwrqrreHzjNdyv9f6Za/6WVlzmUz6Iuwdi6HgY1kB3huuBBjokHqZBVxOHrgfwjQeICbchldKIOheWhI6P2UB9lqF846Hsk7juEO07EfONt+qqYPez4OIGsHMkm5u7nQbe52CGxms5sH3N/FD+OTgw6/nvNMT33vJroAPitepvUf8ir15UuLN9lxej47V1FCs+xvAtqX+i/+P1P3oJ2voSUGn5h47XOpjdI0Y8+oFcoX/Gy7/425A0l4CiOzDr+RtzkCVgXj+eZ+0pXS76oX+WqP9FyB0RK15LSOQP1B/QD/o34YABAHKl/Zkd7h1yZE4JAKDk4bvvOQADGAAg8vBlCEOusAQNJppnGyvLiSyBAvoBHDBA4hMJ3BegH4jugK07GPJPSwln+n1LoDgZP9w3Gq2vroffJ355sXcf+NTefTdxintJLeuHFSwcMGTWQNsNTe3gSdhAIb8TOU58IMcViEVs4Vs/cMkfptx4ctDYMS54TJ6cvE27/2iuQMyHiN+ygyH/9A5SextS5/7YQWplCTTr5hhZQ6Ff37p+WMGKC1dBg/qBFfObcHL5Xd3u55BWnEGuebZ/3cbt45A66uomdeO3qh/wY7DInPg1vkYsxtkP+ac/++z+PJilBmq5/pq5aziYmD8zF2vw0n9s6V/rIr7FMcWx7GDIP13+ToxdJ2OhgU7NwedMV0cWdEP/saV/rRUIL9FZdjDknz7/mE4mRb44eH33axn6D/ofNYBjNM4cGin56zuBkhqphfq3c9ZyMGiJ/oP+Iwxgqw6G/Bm8OHi7Dgz90H9K0z8HCQCN35QDAyhF/xwsiChJ87SePxqi9oD+x+qf+4ABJgpDE9B/WvguaAAAAAAAAJgG/wIobXrKXzNJZgAAAABJRU5ErkJggg==";
+/** The sprite sheet's bytes. */
+export declare function testSpriteMapPng(): Uint8Array;
+/** The test sprite, read as a person's clippy.js files are. */
+export declare function readTestSpriteCharacter(): Promise<AssistantCharacterData>;

package/lib/examples/utils/testSpriteCharacter.js

@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A small character of our own in the clippy.js shape (LOOP T-26), for the
+ * floating assistant's gallery: an `agent.js` and a `map.png` sprite sheet
+ * of ten 48×48 cells, read through the same reader a person's files go
+ * through (`readClippyCharacter`). It is a test sprite drawn for Datalayer —
+ * no file of Microsoft's is in the repository (§6.9).
+ *
+ * Its animations carry the names the Office characters use, so the reader's
+ * `stateAnimations` gives every state of the assistant one of its own:
+ * `Idle1_1` idles, `Thinking`, `Processing`, `GetAttention`, `Sleep`,
+ * `Greeting`, `Explain` and `GoodBye`.
+ *
+ * @module examples/utils/testSpriteCharacter
+ */
+import { readClippyCharacter } from '../../chat/assistant/formats/clippy';
+/** The character's `agent.js`, as clippy.js registers one. */
+export const TEST_SPRITE_AGENT_JS = `
+clippy.ready('Pixel', {
+  overlayCount: 1,
+  framesize: [48, 48],
+  animations: {
+    Idle1_1: { frames: [{ duration: 1200, images: [[0, 0]] }] },
+    Thinking: { frames: [{ duration: 1200, images: [[48, 0]] }] },
+    Processing: { frames: [
+      { duration: 240, images: [[96, 0]] },
+      { duration: 240, images: [[144, 0]] },
+    ] },
+    GetAttention: { frames: [{ duration: 900, images: [[192, 0]] }] },
+    Sleep: { frames: [{ duration: 1600, images: [[240, 0]] }] },
+    Greeting: { frames: [{ duration: 900, images: [[288, 0]] }] },
+    Explain: { frames: [
+      { duration: 200, images: [[336, 0]] },
+      { duration: 200, images: [[384, 0]] },
+    ] },
+    GoodBye: { frames: [{ duration: 900, images: [[432, 0]] }] },
+  },
+});
+`;
+/** Its sprite sheet, `map.png` (480×48), base64. */
+export const TEST_SPRITE_MAP_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAeAAAAAwCAYAAADJnakOAAAF/klEQVR42u2dMW8rRRDHx5YfHd1LwfUgCwkKGgrQowuiCS3KB6CgokhhJATtFakooKChygeIKEgkiryWhvLEB/Ar/DoKJChCQdbcOzvnW9/u7M7e7ydZiqORPTf3v5n7r+/smQBAFNar5b37u6qbGRUBgDZzSgAAAKDPghJEcz8fisiliDwRkW+ruvmZqgAAAAM4Pt+JyGci8qeI3IkIAxgAABjAGgO4qps/1qvlayLyOuWAqbFeLb8Xkbcf+sz7Vd08oSoADODoVHXz08Of74rIb1QEJngMfPEwiL8WkV+pCAADWJtPReQHyjDJATT5K5/Xq+U7InImIh+gCAAGsDZvisg3lGGSw2fStyGtV8uFiPwoIp9XdfNP6Nd/evrsPtRrvbx9zm1iwAAukC+rurmnDDTQCfKViPxS1c3vueqm+5roCDRBbPFdwG1VN6dUIm4DZRBnqf2/5b/rH5z7/aSqm79C6aY6PwuX69U1OgJbA9i6gyF/3fxLa6A4+DRaD6mbPh3F3if0H/Q/S134HAYB+cfPv6QGioNPN4Bjaqerocf2xdPTZ/dj9hP9B/0fNYCtOxjyT5d/Tg0UB2/LwWhq55CG2jXz3Wb6T5z8j90nOej/qGQtOhjyT5d/Tg0UB2/PweQ6gH22l/4TN3+fi+hy0r/3VdCxD4Lq/GznbCj065N/uvytY7n+Gg4m9NXEKYZvez+0l5uPHb70H738+z4eyFH/s1wPgpAOhvzT5Z+qgVrfBhz88Nq333PItg2N7+6Dse6X/hM3/77hl6v+uQ8YkhOrgULZKyjufTY3d9v/nXz80aPb6Rvf5564WC5f+lxwbvqfD9mYFI3Ovd/Y9XryT5v/oQa6vrqWzc3d9uH+FyI+pHO0XH/tbdDQjqM9TPc9Hxs/djvoP3r5H1p6zlH/QRywdQdD/unY1xCdKwkRT/3LXTVxWjg5eeN/PWxebDXRrq1v/DGNnv6TT/5jbxXTYhGi8BpLQFGEc3H5yoF4MH/PeC3hW6x/uyHuG7J9DXRIPPVP72C6FzGVQMhtMd8/M8z/5e3zWdt55q7/+dg30lgCSunIQsdrOEjL9bcG9Ycp6yfn/DU+AhnL0QO4u6TjHq6o3c/lfOM1l032iWRf/j7xqR1kX/1zyL9LVxOh42PW36L+rVOdn23d02bzYvtwrqrreHzjNdyv9f6Za/6WVlzmUz6Iuwdi6HgY1kB3huuBBjokHqZBVxOHrgfwjQeICbchldKIOheWhI6P2UB9lqF846Hsk7juEO07EfONt+qqYPez4OIGsHMkm5u7nQbe52CGxms5sH3N/FD+OTgw6/nvNMT33vJroAPitepvUf8ir15UuLN9lxej47V1FCs+xvAtqX+i/+P1P3oJ2voSUGn5h47XOpjdI0Y8+oFcoX/Gy7/425A0l4CiOzDr+RtzkCVgXj+eZ+0pXS76oX+WqP9FyB0RK15LSOQP1B/QD/o34YABAHKl/Zkd7h1yZE4JAKDk4bvvOQADGAAg8vBlCEOusAQNJppnGyvLiSyBAvoBHDBA4hMJ3BegH4jugK07GPJPSwln+n1LoDgZP9w3Gq2vroffJ355sXcf+NTefTdxintJLeuHFSwcMGTWQNsNTe3gSdhAIb8TOU58IMcViEVs4Vs/cMkfptx4ctDYMS54TJ6cvE27/2iuQMyHiN+ygyH/9A5SextS5/7YQWplCTTr5hhZQ6Ff37p+WMGKC1dBg/qBFfObcHL5Xd3u55BWnEGuebZ/3cbt45A66uomdeO3qh/wY7DInPg1vkYsxtkP+ac/++z+PJilBmq5/pq5aziYmD8zF2vw0n9s6V/rIr7FMcWx7GDIP13+ToxdJ2OhgU7NwedMV0cWdEP/saV/rRUIL9FZdjDknz7/mE4mRb44eH33axn6D/ofNYBjNM4cGin56zuBkhqphfq3c9ZyMGiJ/oP+Iwxgqw6G/Bm8OHi7Dgz90H9K0z8HCQCN35QDAyhF/xwsiChJ87SePxqi9oD+x+qf+4ABJgpDE9B/WvguaAAAAAAAAJgG/wIobXrKXzNJZgAAAABJRU5ErkJggg==';
+/** The sprite sheet's bytes. */
+export function testSpriteMapPng() {
+    const binary = atob(TEST_SPRITE_MAP_PNG_BASE64);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+/** The test sprite, read as a person's clippy.js files are. */
+export function readTestSpriteCharacter() {
+    return readClippyCharacter({
+        agentJs: TEST_SPRITE_AGENT_JS,
+        mapPng: new Blob([testSpriteMapPng()], { type: 'image/png' }),
+    });
+}

package/lib/stories/loop/pictures-main.js

@@ -8,7 +8,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * one state of the floating assistant, in one theme and one mode, chosen by
  * the address — `html/pictures.html?screen=approval&theme=loop&mode=dark`,
  * or `?assistant=thinking&mode=light`, or a character idle,
- * `?character=wizard&mode=dark` (Datalayer's, or the owl a plugin contributes).
+ * `?character=wizard&mode=dark` (Datalayer's, or the owl a plugin contributes),
+ * or the gallery's grid of every character in every pose, `?gallery=grid`.
  *
  * It sets `data-pictures-ready` on the document once the fonts are in — Inter
  * in its two weights, served by this page (T-04) — and two frames have
@@ -22,7 +23,9 @@ if (globals['__webpack_public_path__'] === undefined) {
 }
 import { useEffect } from 'react';
 import { createRoot } from 'react-dom/client';
+import { Box } from '@datalayer/primer-addons';
 import { ASSISTANT_PICTURES, AssistantScreen, CHARACTER_PICTURES, CharacterScreen, REFERENCE_SCREEN_COMPONENTS, REFERENCE_SCREENS, REFERENCE_THEMES, ReferenceTheme, } from './ReferenceScreens';
+import { AssistantGalleryGrid, useGalleryCharacters, } from '../../examples/utils/AssistantGalleryGrid';
 import '../../../style/primer-primitives.css';
 // The `loop` theme's face (LOOP T-04): Inter and its metric-matched fallback,
 // served by this page's own Vite, as the landing serves them from its build.
@@ -35,6 +38,7 @@ const mode = params.get('mode') === 'dark' ? 'dark' : 'light';
 const screen = params.get('screen');
 const assistant = params.get('assistant');
 const character = params.get('character');
+const gallery = params.get('gallery') === 'grid';
 function Ready() {
     useEffect(() => {
         let cancelled = false;
@@ -58,7 +62,18 @@ function Ready() {
     }, []);
     return null;
 }
+/**
+ * The floating assistant's gallery as a grid: every character — the test
+ * sprite read in the page included — in every pose; ready once it is read.
+ */
+function GalleryScreen() {
+    const { characters, ready } = useGalleryCharacters();
+    return (_jsxs(Box, { sx: { flex: 1, bg: 'canvas.default', p: 2, overflow: 'hidden' }, children: [_jsx(AssistantGalleryGrid, { characters: characters }), ready && _jsx(Ready, {})] }));
+}
 function Page() {
+    if (gallery) {
+        return (_jsx(ReferenceTheme, { theme: theme, mode: mode, children: _jsx(GalleryScreen, {}) }));
+    }
     if (character && CHARACTER_PICTURES.includes(character)) {
         return (_jsx(ReferenceTheme, { theme: theme, mode: mode, children: _jsx(CharacterScreen, { character: character, ready: _jsx(Ready, {}) }) }));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.3.58",
+    "version": "1.3.59",
     "type": "module",
     "workspaces": [
         ".",