@datalayer/agent-runtimes 1.3.29 → 1.3.32

package/lib/AgentNode.js

@@ -345,7 +345,8 @@ export function AgentNode() {
     ]);
     const [inferenceProvider, setInferenceProvider] = useState('datalayer');
     const [inferenceModels, setInferenceModels] = useState([]);
-    const [inferenceDefaultModel, setInferenceDefaultModel] = useState(null);
+    // The runtime's sentence about its models, or why it gave none.
+    const [inferenceModelsNote, setInferenceModelsNote] = useState(null);
     const [configurationLoaded, setConfigurationLoaded] = useState(false);
     const [isActiveAgentRunning, setIsActiveAgentRunning] = useState(false);
     // The protocol the active agent actually speaks, as reported by the node.
@@ -712,49 +713,26 @@ export function AgentNode() {
     useEffect(() => {
         if (inferenceProvider !== 'datalayer') {
             setInferenceModels([]);
-            setInferenceDefaultModel(null);
+            setInferenceModelsNote(null);
             return;
         }
+        // The runtime's answer, as it had it from ai-inference: no list of its
+        // own when that answer is empty or did not come — the sentence says why.
         const loadInferenceModels = async () => {
             try {
                 const response = await fetch(`${AGENT_RUNTIMES_BASE_URL}/api/v1/configure/inference/models`);
                 if (!response.ok) {
                     setInferenceModels([]);
-                    setInferenceDefaultModel(null);
+                    setInferenceModelsNote(`The runtime did not list its models (${response.status}).`);
                     return;
                 }
                 const payload = await response.json();
-                const fromModels = Array.isArray(payload.models)
-                    ? payload.models.filter(Boolean)
-                    : [];
-                const fromBedrock = Array.isArray(payload.bedrock_anthropic_models)
-                    ? payload.bedrock_anthropic_models.filter(Boolean)
-                    : [];
-                const fallback = [
-                    'bedrock/us.anthropic.claude-3-5-sonnet-20240620-v1:0',
-                    'bedrock/us.anthropic.claude-3-7-sonnet-20250219-v1:0',
-                    'bedrock/us.anthropic.claude-sonnet-4-20250514-v1:0',
-                ];
-                const models = fromModels.length > 0
-                    ? fromModels
-                    : fromBedrock.length > 0
-                        ? fromBedrock
-                        : fallback;
-                setInferenceModels(models);
-                const specDefault = Array.isArray(payload.bedrock_anthropic_model_specs)
-                    ? payload.bedrock_anthropic_model_specs.find(s => s?.default)?.id
-                    : undefined;
-                const selected = (specDefault && models.includes(specDefault) ? specDefault : null) ||
-                    (payload.default_model && models.includes(payload.default_model)
-                        ? payload.default_model
-                        : null) ||
-                    models[0] ||
-                    null;
-                setInferenceDefaultModel(selected);
+                setInferenceModels(Array.isArray(payload.models) ? payload.models.filter(Boolean) : []);
+                setInferenceModelsNote(payload.note ?? null);
             }
-            catch {
+            catch (error) {
                 setInferenceModels([]);
-                setInferenceDefaultModel(null);
+                setInferenceModelsNote(`The runtime did not list its models (${String(error)}).`);
             }
         };
         loadInferenceModels();
@@ -1280,7 +1258,10 @@ export function AgentNode() {
                                                                     display: 'flex',
                                                                     flexDirection: 'column',
                                                                     gap: 1,
-                                                                }, children: [_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Bedrock Anthropic model" }), inferenceModels.length === 0 ? (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "No model list available." })) : (_jsxs(ActionMenu, { children: [_jsx(ActionMenu.Button, { children: inferenceDefaultModel || inferenceModels[0] }), _jsx(ActionMenu.Overlay, { width: "large", children: _jsx(ActionList, { selectionVariant: "single", children: inferenceModels.map(model => (_jsx(ActionList.Item, { selected: inferenceDefaultModel === model, inactiveText: "Selection is locked", children: model }, model))) }) })] }))] }))] }), iamUser ? (_jsxs(Box, { sx: {
+                                                                }, children: [_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Models ai-inference serves" }), inferenceModels.length === 0 ? (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: inferenceModelsNote ??
+                                                                            'The runtime has not said which models ai-inference serves.' })) : (_jsxs(ActionMenu, { children: [_jsx(ActionMenu.Button, { children: inferenceModels.length === 1
+                                                                                    ? inferenceModels[0]
+                                                                                    : `${inferenceModels.length} models` }), _jsx(ActionMenu.Overlay, { width: "large", children: _jsx(ActionList, { children: inferenceModels.map(model => (_jsx(ActionList.Item, { inactiveText: "Selection is locked", children: model }, model))) }) })] }))] }))] }), iamUser ? (_jsxs(Box, { sx: {
                                                             border: '1px solid',
                                                             borderColor: 'border.default',
                                                             borderRadius: 2,

package/lib/chat/ChatFloating.js

@@ -48,6 +48,13 @@ function useIsMobile(breakpoint = 640) {
     }, [breakpoint]);
     return isMobile;
 }
+/**
+ * A length in pixels, as a string: a number in `sx` from 0 to 12 is read as
+ * the theme's space scale (`left: 8` is 64px).
+ */
+const px = (value) => `${Math.round(value)}px`;
+/** Kept between 8px from the window's start and `max`. */
+const clamp = (value, max) => Math.max(8, Math.min(value, Math.max(8, max)));
 /**
  * ChatFloating component
  * A floating chat window built on ChatBase
@@ -141,7 +148,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         }
     }, [isOpen, saying]);
     const stageRef = useRef(null);
-    const stageDrag = useViewportDrag(stageRef);
+    const stageDrag = useViewportDrag(stageRef, { whole: true });
     useEffect(() => {
         if (!assistantShown) {
             return;
@@ -387,9 +394,28 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
         const widthPx = typeof width === 'number' ? width : 400;
         const heightPx = typeof height === 'number' ? height : 550;
         if (stageDrag.position) {
+            // Toward the page's inside: above the character, below it, or beside
+            // it when the window is too short for either.
+            const { left, top } = stageDrag.position;
+            const onLeft = left + ASSISTANT_SIZE / 2 < window.innerWidth / 2;
+            const above = top - heightPx - 16;
+            const below = top + ASSISTANT_SIZE + 16;
+            const beside = above < 8 && below + heightPx > window.innerHeight - 8;
+            const x = beside
+                ? onLeft
+                    ? left + ASSISTANT_SIZE + 16
+                    : left - widthPx - 16
+                : onLeft
+                    ? left
+                    : left + ASSISTANT_SIZE - widthPx;
+            const y = beside
+                ? top + ASSISTANT_SIZE - heightPx
+                : above >= 8
+                    ? above
+                    : below;
             return {
-                left: Math.max(8, stageDrag.position.left + ASSISTANT_SIZE - widthPx),
-                top: Math.max(8, stageDrag.position.top - heightPx - 16),
+                left: px(clamp(x, window.innerWidth - widthPx - 8)),
+                top: px(clamp(y, window.innerHeight - heightPx - 8)),
                 right: 'auto',
                 bottom: 'auto',
             };
@@ -557,8 +583,8 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             ...(viewMode === 'floating-draggable' && !isMobile
                 ? drag.position
                     ? {
-                        left: drag.position.left,
-                        top: drag.position.top,
+                        left: px(drag.position.left),
+                        top: px(drag.position.top),
                         right: 'auto',
                         bottom: 'auto',
                     }
@@ -694,7 +720,10 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
      * person's attention, until the chat is opened; hovered, they show in a
      * balloon above it in place of the tooltip.
      */
-    const chatButton = (_jsx(IconButton, { icon: buttonIcon ? buttonIcon : CommentDiscussionIcon, "aria-label": buttonTooltip, onClick: assistantMode && assistantAway === 'page'
+    const chatButton = (_jsx(IconButton, { icon: buttonIcon ? buttonIcon : CommentDiscussionIcon, "aria-label": buttonTooltip, 
+        // With words to say, the balloon stands in for the tooltip: Primer's
+        // own would cover it.
+        unsafeDisableTooltip: !!saying, onClick: assistantMode && assistantAway === 'page'
             ? callAssistantBack
             : handleToggle, size: "large", sx: {
             width: 56,
@@ -729,8 +758,11 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
             },
         } }));
     return (_jsxs(_Fragment, { children: [assistantShown && (_jsx(AssistantStage, { character: assistantCharacter, state: assistantState, size: ASSISTANT_SIZE, place: stageDrag.position
-                    ? { left: stageDrag.position.left, top: stageDrag.position.top }
-                    : getPositionStyles(), stageRef: stageRef, onDragStart: stageDrag.onHandlePointerDown, open: isOpen, onToggle: handleToggle, balloon: assistantBalloon, insist: balloonInsists, onDismiss: dismissAssistant })), showButton && !isOpen && !assistantShown && (_jsx(Box, { sx: {
+                    ? {
+                        left: px(stageDrag.position.left),
+                        top: px(stageDrag.position.top),
+                    }
+                    : getPositionStyles(), stageRef: stageRef, onDragStart: stageDrag.onHandlePointerDown, open: isOpen, onToggle: handleToggle, balloon: assistantBalloon, insist: balloonInsists, onDismiss: dismissAssistant, ownRef: popupRef })), showButton && !isOpen && !assistantShown && (_jsx(Box, { sx: {
                     ...getPositionStyles(),
                 }, children: _jsxs(Box, { sx: {
                         position: 'relative',

package/lib/chat/assistant/AssistantStage.d.ts

@@ -3,7 +3,10 @@
  * a corner, acting out what the application is doing, with a balloon that
  * says a word while the conversation is closed. Clicked, it opens the
  * conversation; dragged, it moves, and the conversation follows; sent away,
- * it says goodbye and leaves a small way back.
+ * it says goodbye and leaves a small way back. It never sits over an open
+ * dialog, an overlay or another chat's composer, nor where the pointer is
+ * working: it steps aside — out of sight and out of the pointer's way — until
+ * the place is clear again.
  *
  * Its motions are one set for every character, by the parts each drawing
  * names (`assistant-body`, `-pupils`, `-lids`, `-mouth`), and nothing moves
@@ -14,7 +17,7 @@
 import type { JSX, RefObject } from 'react';
 import { type AssistantCharacter } from './characters';
 import type { AssistantCharacterData } from './formats/types';
-import type { AssistantAway, AssistantState } from './state';
+import { type AssistantAway, type AssistantState } from './state';
 /**
  * Where the balloon goes so that it stays inside the window (T-23): toward
  * the middle of the page from whichever half the character stands in, and
@@ -32,6 +35,20 @@ export declare function balloonSide(place: {
     side: 'above' | 'below';
     align: 'left' | 'right';
 };
+/** Why the assistant has stepped aside, if it has (T-27). */
+export type AssistantAside = 'obstacle' | 'pointer' | undefined;
+/**
+ * Whether the assistant steps aside (T-27): while an open dialog, an overlay
+ * or another chat's composer is under it (`obstacle`), and while the pointer
+ * works over or beside it — pressing, or dragging — until it has been away for
+ * `POINTER_CALM_MS` (`pointer`). Its own conversation, `own`, is neither, and
+ * nothing counts while `paused` (its own menu is open).
+ *
+ * The page is looked over on a short timer rather than watched: a dialog
+ * opens, a composer scrolls or a chat is dragged under it without a mutation
+ * this could hear, and a few rectangles every 400ms cost nothing.
+ */
+export declare function useKeepClear(stageRef: RefObject<HTMLElement | null>, own: RefObject<HTMLElement | null> | undefined, paused: boolean): AssistantAside;
 export interface AssistantStageProps {
     /** The character: one Datalayer ships, by id (T-25), or one loaded from a file (T-26). */
     character: string | AssistantCharacter | AssistantCharacterData;
@@ -40,10 +57,7 @@ export interface AssistantStageProps {
     /** Its size, in pixels. */
     size?: number;
     /** Where it sits once moved, or the corner it starts in. */
-    place: {
-        left: number;
-        top: number;
-    } | React.CSSProperties;
+    place: React.CSSProperties;
     /** The element the drag measures. */
     stageRef: RefObject<HTMLDivElement | null>;
     /** Starts a drag. */
@@ -65,6 +79,11 @@ export interface AssistantStageProps {
     insist?: boolean;
     /** Send it away (T-27): for the page, for the session, or for good. */
     onDismiss: (away: AssistantAway) => void;
+    /**
+     * Its own conversation's window: a dialog or composer there is not one it
+     * steps aside for, nor is the pointer working there (T-27).
+     */
+    ownRef?: RefObject<HTMLElement | null>;
 }
-export declare function AssistantStage({ character, state, size, place, stageRef, onDragStart, open, onToggle, balloon, insist, onDismiss, }: AssistantStageProps): JSX.Element;
+export declare function AssistantStage({ character, state, size, place, stageRef, onDragStart, open, onToggle, balloon, insist, onDismiss, ownRef, }: AssistantStageProps): JSX.Element;
 export default AssistantStage;

package/lib/chat/assistant/AssistantStage.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useRef, useState } from 'react';
-import { ActionList, ActionMenu, IconButton } from '@primer/react';
+import { useEffect, useRef, useState } from 'react';
+import { ActionList, ActionMenu, IconButton, useTheme } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { XIcon } from '@primer/octicons-react';
 import { assistantCharacter } from './characters';
 import { SpeechBalloon } from './SpeechBalloon';
 import { SpriteCharacter } from './SpriteCharacter';
+import { ASSISTANT_OBSTACLES, POINTER_CALM_MS, boxesMeet, pointerNear, } from './state';
 /** The motions, by the state the stage is in. */
 const MOTIONS = {
     '@keyframes assistantFloat': {
@@ -54,6 +55,14 @@ const AWAY_CHOICES = [
 ];
 /** Room the balloon needs above the character before it goes below. */
 const BALLOON_ROOM = 200;
+/** A place's length in pixels, given as a number or as `"<n>px"`. */
+function pixels(value) {
+    if (typeof value === 'number') {
+        return value;
+    }
+    const match = typeof value === 'string' ? /^(-?\d+(?:\.\d+)?)px$/.exec(value) : null;
+    return match ? Number(match[1]) : undefined;
+}
 /**
  * Where the balloon goes so that it stays inside the window (T-23): toward
  * the middle of the page from whichever half the character stands in, and
@@ -63,8 +72,8 @@ export function balloonSide(place, viewport = {
     width: typeof window === 'undefined' ? 1280 : window.innerWidth,
     height: typeof window === 'undefined' ? 800 : window.innerHeight,
 }) {
-    const left = typeof place.left === 'number' ? place.left : undefined;
-    const top = typeof place.top === 'number' ? place.top : undefined;
+    const left = pixels(place.left);
+    const top = pixels(place.top);
     const align = left !== undefined
         ? left < viewport.width / 2
             ? 'left'
@@ -81,7 +90,93 @@ export function balloonSide(place, viewport = {
             : 'above';
     return { side, align };
 }
-export function AssistantStage({ character, state, size = 88, place, stageRef, onDragStart, open, onToggle, balloon, insist = false, onDismiss, }) {
+/** How often the page is looked over for what the assistant must not cover. */
+const CLEAR_CHECK_MS = 400;
+/**
+ * Whether the assistant steps aside (T-27): while an open dialog, an overlay
+ * or another chat's composer is under it (`obstacle`), and while the pointer
+ * works over or beside it — pressing, or dragging — until it has been away for
+ * `POINTER_CALM_MS` (`pointer`). Its own conversation, `own`, is neither, and
+ * nothing counts while `paused` (its own menu is open).
+ *
+ * The page is looked over on a short timer rather than watched: a dialog
+ * opens, a composer scrolls or a chat is dragged under it without a mutation
+ * this could hear, and a few rectangles every 400ms cost nothing.
+ */
+export function useKeepClear(stageRef, own, paused) {
+    const [obstructed, setObstructed] = useState(false);
+    const [pointerBusy, setPointerBusy] = useState(false);
+    useEffect(() => {
+        if (paused) {
+            setObstructed(false);
+            return;
+        }
+        const check = () => {
+            const stage = stageRef.current;
+            if (!stage) {
+                return;
+            }
+            const box = stage.getBoundingClientRect();
+            const mine = own?.current;
+            const hit = Array.from(document.querySelectorAll(ASSISTANT_OBSTACLES)).some(element => {
+                if (stage.contains(element) ||
+                    element.contains(stage) ||
+                    mine?.contains(element)) {
+                    return false;
+                }
+                const other = element.getBoundingClientRect();
+                return other.width > 0 && other.height > 0 && boxesMeet(box, other);
+            });
+            setObstructed(hit);
+        };
+        check();
+        const timer = window.setInterval(check, CLEAR_CHECK_MS);
+        return () => window.clearInterval(timer);
+    }, [stageRef, own, paused]);
+    useEffect(() => {
+        if (paused) {
+            setPointerBusy(false);
+            return;
+        }
+        let calm;
+        let aside = false;
+        const onPointer = (event) => {
+            const stage = stageRef.current;
+            const target = event.target;
+            if (!stage ||
+                (target && (stage.contains(target) || own?.current?.contains(target)))) {
+                return;
+            }
+            // A pointer passing by is not working; once aside, any move near keeps
+            // it aside, so it does not come back under a pointer still there.
+            if (event.type === 'pointermove' && event.buttons === 0 && !aside) {
+                return;
+            }
+            if (!pointerNear(stage.getBoundingClientRect(), {
+                x: event.clientX,
+                y: event.clientY,
+            })) {
+                return;
+            }
+            aside = true;
+            setPointerBusy(true);
+            clearTimeout(calm);
+            calm = setTimeout(() => {
+                aside = false;
+                setPointerBusy(false);
+            }, POINTER_CALM_MS);
+        };
+        document.addEventListener('pointerdown', onPointer, true);
+        document.addEventListener('pointermove', onPointer, true);
+        return () => {
+            clearTimeout(calm);
+            document.removeEventListener('pointerdown', onPointer, true);
+            document.removeEventListener('pointermove', onPointer, true);
+        };
+    }, [stageRef, own, paused]);
+    return obstructed ? 'obstacle' : pointerBusy ? 'pointer' : undefined;
+}
+export function AssistantStage({ character, state, size = 88, place, stageRef, onDragStart, open, onToggle, balloon, insist = false, onDismiss, ownRef, }) {
     // A shipped one by id, a drawing contributed by a plugin (T-24), or a
     // character read from a file (T-26).
     const shipped = typeof character === 'string'
@@ -92,17 +187,29 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
     const name = shipped
         ? shipped.name
         : character.name;
+    // Drawn for the chat's colour mode: the dark drawing on a dark page (T-25).
+    const { colorScheme } = useTheme();
+    const colorMode = colorScheme?.startsWith('dark') ? 'dark' : 'light';
     const [hovered, setHovered] = useState(false);
     const [menuOpen, setMenuOpen] = useState(false);
     // Where the press began: a press that moves is a drag, not a click.
     const pressedAt = useRef(null);
-    const showBalloon = !open && !!balloon && (hovered || insist);
-    return (_jsxs(Box, { ref: stageRef, "data-assistant-state": state, sx: {
+    const aside = useKeepClear(stageRef, ownRef, menuOpen);
+    const showBalloon = !aside && !open && !!balloon && (hovered || insist);
+    return (_jsxs(Box, { ref: stageRef, "data-assistant-state": state, "data-assistant-aside": aside, sx: {
             position: 'fixed',
             zIndex: 1002,
             ...place,
             width: size,
             height: size,
+            // Aside (T-27): out of sight, out of the tab order and let through
+            // to what is under it; back as soon as the place is clear.
+            opacity: aside ? 0 : 1,
+            visibility: aside ? 'hidden' : 'visible',
+            pointerEvents: aside ? 'none' : undefined,
+            transition: aside
+                ? 'opacity 150ms ease, visibility 0s linear 150ms'
+                : 'opacity 150ms ease',
             ...MOTIONS,
             '& .assistant-lids ellipse': {
                 transformBox: 'fill-box',
@@ -183,7 +290,7 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
                         outlineOffset: 2,
                         borderRadius: '50%',
                     },
-                }, children: shipped ? (_jsx(shipped.Drawing, { size: size })) : (_jsx(SpriteCharacter, { character: character, state: state, size: size })) }), (hovered || menuOpen) && state !== 'goodbye' && (_jsx(Box, { sx: { position: 'absolute', top: -6, right: -6 }, children: _jsxs(ActionMenu, { open: menuOpen, onOpenChange: setMenuOpen, children: [_jsx(ActionMenu.Anchor, { children: _jsx(IconButton, { icon: XIcon, "aria-label": `Send ${name} away`, size: "small", variant: "invisible", "data-assistant-dismiss": "", sx: {
+                }, children: shipped ? (_jsx(shipped.Drawing, { size: size, mode: colorMode })) : (_jsx(SpriteCharacter, { character: character, state: state, size: size })) }), (hovered || menuOpen) && !aside && state !== 'goodbye' && (_jsx(Box, { sx: { position: 'absolute', top: '-6px', right: '-6px' }, children: _jsxs(ActionMenu, { open: menuOpen, onOpenChange: setMenuOpen, children: [_jsx(ActionMenu.Anchor, { children: _jsx(IconButton, { icon: XIcon, "aria-label": `Send ${name} away`, size: "small", variant: "invisible", "data-assistant-dismiss": "", sx: {
                                     bg: 'canvas.default',
                                     borderRadius: '50%',
                                     boxShadow: 'shadow.small',

package/lib/chat/assistant/SpeechBalloon.js

@@ -4,7 +4,11 @@ import { Box } from '@datalayer/primer-addons';
 export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above', align, tailAt, }) {
     return (_jsxs(Box, { role: "status", "aria-live": "polite", "data-speech-balloon": "", sx: {
             position: 'absolute',
-            ...(side === 'above' ? { bottom: above } : { top: above }),
+            // Pixels, as strings: a number here is read as the theme's space
+            // scale (`-7` would be `-space[7]`, 48px).
+            ...(side === 'above'
+                ? { bottom: `${above}px` }
+                : { top: `${above}px` }),
             [align]: 0,
             maxWidth: 280,
             width: 'max-content',
@@ -22,8 +26,8 @@ export function SpeechBalloon({ text, more = false, onOpen, above, side = 'above
             '&::after': {
                 content: '""',
                 position: 'absolute',
-                ...(side === 'above' ? { bottom: -7 } : { top: -7 }),
-                [align]: tailAt - 6,
+                ...(side === 'above' ? { bottom: '-7px' } : { top: '-7px' }),
+                [align]: `${tailAt - 6}px`,
                 width: 12,
                 height: 12,
                 bg: 'canvas.default',

package/lib/chat/assistant/characters.d.ts

@@ -9,18 +9,49 @@
  * state — `assistant-body`, `assistant-pupils`, `assistant-lids`,
  * `assistant-mouth` — so one set of motions serves every character.
  *
+ * Each is drawn twice, for the chat's colour mode: a light drawing for the
+ * light page and a dark one for the `loop` theme's dark page, by its dark
+ * tokens (`loopColors.inkDark`, `grayDark`, `black`). Their edges and eyes
+ * are held to 3 to 1 against both pages by a test (`keyColours`).
+ *
  * @module chat/assistant/characters
  */
 import type { JSX } from 'react';
+/** The colour mode a character is drawn for: the chat's own. */
+export type AssistantColorMode = 'light' | 'dark';
+/**
+ * What a drawing must keep readable, by mode (T-25, tested as T-15 tests the
+ * faces): the colours that meet the page along its edge, and its eyes.
+ */
+export interface AssistantCharacterKeyColours {
+    /** Every colour drawn along the character's edge, where it meets the page. */
+    edges: string[];
+    eye: {
+        /** The white of the eye. */
+        white: string;
+        /** The ring drawn round it. */
+        ring: string;
+        /** The pupil. */
+        pupil: string;
+        /** What the eye sits on: the page, or the face's colour. */
+        on: 'page' | string;
+    };
+}
 /** A character Datalayer ships. */
 export interface AssistantCharacter {
     id: string;
     /** Its name, as the picker shows it. */
     name: string;
-    /** The drawing, at the size asked; its parts animate by class. */
+    /**
+     * The drawing, at the size asked, for the chat's colour mode (light when
+     * unsaid); its parts animate by class.
+     */
     Drawing: (props: {
         size: number;
+        mode?: AssistantColorMode;
     }) => JSX.Element;
+    /** Its key colours in each mode, for the contrast test (T-25). */
+    keyColours?: Record<AssistantColorMode, AssistantCharacterKeyColours>;
 }
 /** The characters Datalayer ships, in the order a picker shows them. */
 export declare const ASSISTANT_CHARACTERS: readonly AssistantCharacter[];