@datalayer/agent-runtimes 1.3.28 → 1.3.30

package/lib/chat/assistant/AssistantStage.js

@@ -0,0 +1,192 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef, useState } from 'react';
+import { ActionList, ActionMenu, IconButton } 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';
+/** The motions, by the state the stage is in. */
+const MOTIONS = {
+    '@keyframes assistantFloat': {
+        '0%, 100%': { transform: 'translateY(0)' },
+        '50%': { transform: 'translateY(-3px)' },
+    },
+    '@keyframes assistantBlink': {
+        '0%, 94%, 100%': { transform: 'scaleY(0)' },
+        '97%': { transform: 'scaleY(1)' },
+    },
+    '@keyframes assistantTilt': {
+        '0%, 100%': { transform: 'rotate(-5deg)' },
+        '50%': { transform: 'rotate(-8deg) translateY(-2px)' },
+    },
+    '@keyframes assistantWork': {
+        '0%, 100%': { transform: 'rotate(-3deg) translateY(0)' },
+        '50%': { transform: 'rotate(3deg) translateY(-4px)' },
+    },
+    '@keyframes assistantAttention': {
+        '0%, 100%': { transform: 'scale(1) rotate(0)' },
+        '20%': { transform: 'scale(1.08) rotate(-6deg)' },
+        '40%': { transform: 'scale(1.08) rotate(6deg)' },
+        '60%': { transform: 'scale(1)' },
+    },
+    '@keyframes assistantHop': {
+        '0%, 100%': { transform: 'translateY(0)' },
+        '30%': { transform: 'translateY(-14px)' },
+        '55%': { transform: 'translateY(0)' },
+        '75%': { transform: 'translateY(-6px)' },
+    },
+    '@keyframes assistantTalk': {
+        '0%, 100%': { transform: 'scaleY(1)' },
+        '50%': { transform: 'scaleY(2.2)' },
+    },
+    '@keyframes assistantLeave': {
+        from: { transform: 'scale(1)', opacity: 1 },
+        to: { transform: 'scale(0.2) translateY(20px)', opacity: 0 },
+    },
+};
+const BODY = '& .assistant-body';
+/** How long it may be sent away for, in the menu's words (T-27). */
+const AWAY_CHOICES = [
+    { away: 'page', label: 'Hide for now' },
+    { away: 'session', label: 'Hide for this session' },
+    { away: 'always', label: 'Don\u2019t show again' },
+];
+/** Room the balloon needs above the character before it goes below. */
+const BALLOON_ROOM = 200;
+/**
+ * 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
+ * below it when it stands too near the top.
+ */
+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 align = left !== undefined
+        ? left < viewport.width / 2
+            ? 'left'
+            : 'right'
+        : place.left !== undefined && place.right === undefined
+            ? 'left'
+            : 'right';
+    const side = top !== undefined
+        ? top < BALLOON_ROOM
+            ? 'below'
+            : 'above'
+        : place.top !== undefined && place.bottom === undefined
+            ? 'below'
+            : 'above';
+    return { side, align };
+}
+export function AssistantStage({ character, state, size = 88, place, stageRef, onDragStart, open, onToggle, balloon, insist = false, onDismiss, }) {
+    // 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'
+        ? assistantCharacter(character)
+        : 'Drawing' in character
+            ? character
+            : undefined;
+    const name = shipped
+        ? shipped.name
+        : character.name;
+    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: {
+            position: 'fixed',
+            zIndex: 1002,
+            ...place,
+            width: size,
+            height: size,
+            ...MOTIONS,
+            '& .assistant-lids ellipse': {
+                transformBox: 'fill-box',
+                transformOrigin: 'top',
+                transform: 'scaleY(0)',
+                animation: 'assistantBlink 5.2s ease-in-out infinite',
+            },
+            [BODY]: {
+                transformBox: 'fill-box',
+                transformOrigin: '50% 100%',
+            },
+            '& .assistant-pupils': {
+                transition: 'transform var(--theme-motion-status, 120ms) var(--theme-motion-easing, ease)',
+            },
+            '& .assistant-mouth': {
+                transformBox: 'fill-box',
+                transformOrigin: 'center',
+            },
+            '&[data-assistant-state="idle"] .assistant-body': {
+                animation: 'assistantFloat 3.2s ease-in-out infinite',
+            },
+            '&[data-assistant-state="thinking"] .assistant-body': {
+                animation: 'assistantTilt 2.4s ease-in-out infinite',
+            },
+            '&[data-assistant-state="thinking"] .assistant-pupils': {
+                transform: 'translate(-1px, -3px)',
+            },
+            '&[data-assistant-state="working"] .assistant-body': {
+                animation: 'assistantWork 0.7s ease-in-out infinite',
+            },
+            '&[data-assistant-state="working"] .assistant-pupils': {
+                transform: 'translate(2px, 2px)',
+            },
+            '&[data-assistant-state="waiting"] .assistant-body': {
+                animation: 'assistantAttention 1.4s ease-in-out infinite',
+            },
+            '&[data-assistant-state="greeting"] .assistant-body': {
+                animation: 'assistantHop 0.9s ease-out 2',
+            },
+            '&[data-assistant-state="speaking"] .assistant-mouth': {
+                animation: 'assistantTalk 0.24s ease-in-out infinite',
+            },
+            '&[data-assistant-state="speaking"] .assistant-body': {
+                animation: 'assistantFloat 1.6s ease-in-out infinite',
+            },
+            '&[data-assistant-state="goodbye"] .assistant-body': {
+                animation: 'assistantLeave 0.6s ease-in forwards',
+            },
+            // One still frame per state for a reader who asks for no motion.
+            '@media (prefers-reduced-motion: reduce)': {
+                '& *': { animation: 'none !important' },
+            },
+        }, onMouseEnter: () => setHovered(true), onMouseLeave: () => setHovered(false), children: [showBalloon && balloon && (_jsx(SpeechBalloon, { text: balloon.text, more: balloon.more, onOpen: onToggle, above: size + 8, side: balloonSide(place).side, align: balloonSide(place).align, tailAt: size / 2 })), _jsx(Box, { as: "button", type: "button", "aria-label": open ? `Close the conversation with ${name}` : `Talk to ${name}`, "aria-expanded": open, onPointerDown: (event) => {
+                    pressedAt.current = { x: event.clientX, y: event.clientY };
+                    onDragStart(event);
+                }, onClick: (event) => {
+                    const from = pressedAt.current;
+                    pressedAt.current = null;
+                    if (from &&
+                        Math.hypot(event.clientX - from.x, event.clientY - from.y) > 4) {
+                        return;
+                    }
+                    onToggle();
+                }, sx: {
+                    display: 'block',
+                    width: size,
+                    height: size,
+                    p: 0,
+                    border: 0,
+                    bg: 'transparent',
+                    cursor: 'grab',
+                    touchAction: 'none',
+                    filter: 'drop-shadow(0 6px 10px rgba(0, 0, 0, 0.18))',
+                    '&:active': { cursor: 'grabbing' },
+                    '&:focus-visible': {
+                        outline: '2px solid',
+                        outlineColor: 'var(--focus-outlineColor, var(--fgColor-accent))',
+                        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: {
+                                    bg: 'canvas.default',
+                                    borderRadius: '50%',
+                                    boxShadow: 'shadow.small',
+                                } }) }), _jsx(ActionMenu.Overlay, { width: "auto", children: _jsx(ActionList, { children: AWAY_CHOICES.map(choice => (_jsx(ActionList.Item, { "data-assistant-away": choice.away, onSelect: () => onDismiss(choice.away), children: choice.label }, choice.away))) }) })] }) }))] }));
+}
+export default AssistantStage;

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

@@ -0,0 +1,26 @@
+/**
+ * A speech balloon over something that stands for the agent — the floating
+ * assistant's character, or the floating popup's button while the chat is
+ * closed: the agent's newest words, as the Office Assistant said them
+ * (LOOP T-23), with *Open the conversation* when there is more.
+ *
+ * @module chat/assistant/SpeechBalloon
+ */
+import type { JSX } from 'react';
+export interface SpeechBalloonProps {
+    text: string;
+    /** There is more than the balloon holds. */
+    more?: boolean;
+    /** Opens the conversation. */
+    onOpen: () => void;
+    /** How far from what it stands over, in pixels: above it, or below. */
+    above: number;
+    /** Above what speaks (the default), or below it when it sits at the top. */
+    side?: 'above' | 'below';
+    /** Which edge it is aligned to, toward the page's inside. */
+    align: 'left' | 'right';
+    /** Where the tail points, from that edge, in pixels. */
+    tailAt: number;
+}
+export declare function SpeechBalloon({ text, more, onOpen, above, side, align, tailAt, }: SpeechBalloonProps): JSX.Element;
+export default SpeechBalloon;

package/lib/chat/assistant/SpeechBalloon.js

@@ -0,0 +1,46 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Text } from '@primer/react';
+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 }),
+            [align]: 0,
+            maxWidth: 280,
+            width: 'max-content',
+            px: 3,
+            py: 2,
+            bg: 'canvas.default',
+            color: 'fg.default',
+            border: '1px solid',
+            borderColor: 'border.default',
+            borderRadius: 'var(--theme-radius-bubble, 16px)',
+            boxShadow: 'shadow.medium',
+            fontSize: 1,
+            textAlign: 'left',
+            // The tail, toward what speaks.
+            '&::after': {
+                content: '""',
+                position: 'absolute',
+                ...(side === 'above' ? { bottom: -7 } : { top: -7 }),
+                [align]: tailAt - 6,
+                width: 12,
+                height: 12,
+                bg: 'canvas.default',
+                borderRight: '1px solid',
+                borderBottom: '1px solid',
+                borderColor: 'border.default',
+                transform: side === 'above' ? 'rotate(45deg)' : 'rotate(225deg)',
+            },
+        }, children: [_jsx(Text, { as: "p", sx: { m: 0 }, children: text }), more && (_jsx(Box, { as: "button", type: "button", onClick: onOpen, sx: {
+                    mt: 1,
+                    p: 0,
+                    border: 0,
+                    bg: 'transparent',
+                    color: 'accent.fg',
+                    textDecoration: 'underline',
+                    cursor: 'pointer',
+                    fontSize: 1,
+                }, children: "Open the conversation" }))] }));
+}
+export default SpeechBalloon;

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

@@ -0,0 +1,26 @@
+/**
+ * A character one brings, played (LOOP T-26): the frames of a character file
+ * read by `formats` — clippy.js or Microsoft Agent — drawn from its sprite
+ * sheet and stepped as the character authored them, its branches included,
+ * the animation chosen by the state the stage acts (T-22). Nothing plays for
+ * a reader who asks for reduced motion: the first frame of the state stands.
+ *
+ * @module chat/assistant/SpriteCharacter
+ */
+import type { JSX } from 'react';
+import type { AssistantCharacterAnimation, AssistantCharacterData } from './formats/types';
+import type { AssistantState } from './state';
+/**
+ * The frame after `index`: a branch, when the frame has some and the draw
+ * falls in one (weights are percents; what is left over goes on), else the
+ * next frame; `undefined` at the end of the animation.
+ */
+export declare function nextFrameIndex(animation: AssistantCharacterAnimation, index: number, draw?: number): number | undefined;
+/** One of the animations offered for a state, drawn at random. */
+export declare function animationFor(character: AssistantCharacterData, state: AssistantState, draw?: number): string;
+export declare function SpriteCharacter({ character, state, size, }: {
+    character: AssistantCharacterData;
+    state: AssistantState;
+    size: number;
+}): JSX.Element;
+export default SpriteCharacter;

package/lib/chat/assistant/SpriteCharacter.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from 'react';
+import { stateAnimations } from './formats/stateAnimations';
+/**
+ * The frame after `index`: a branch, when the frame has some and the draw
+ * falls in one (weights are percents; what is left over goes on), else the
+ * next frame; `undefined` at the end of the animation.
+ */
+export function nextFrameIndex(animation, index, draw = Math.random()) {
+    const frame = animation.frames[index];
+    let at = draw * 100;
+    for (const branch of frame?.branching ?? []) {
+        if (at < branch.weight) {
+            return branch.frameIndex;
+        }
+        at -= branch.weight;
+    }
+    return index + 1 < animation.frames.length ? index + 1 : undefined;
+}
+/** One of the animations offered for a state, drawn at random. */
+export function animationFor(character, state, draw = Math.random()) {
+    const names = stateAnimations(character)[state];
+    return names[Math.min(names.length - 1, Math.floor(draw * names.length))];
+}
+const reducedMotion = () => typeof window !== 'undefined' &&
+    !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+export function SpriteCharacter({ character, state, size, }) {
+    const [play, setPlay] = useState(() => ({
+        name: animationFor(character, state),
+        index: 0,
+    }));
+    // A new state starts one of its own animations from the first frame.
+    useEffect(() => {
+        setPlay({ name: animationFor(character, state), index: 0 });
+    }, [character, state]);
+    const animation = character.animations[play.name];
+    const frame = animation?.frames[play.index];
+    const still = useMemo(reducedMotion, []);
+    useEffect(() => {
+        if (!animation || !frame || still) {
+            return;
+        }
+        const timer = setTimeout(() => {
+            const next = nextFrameIndex(animation, play.index);
+            // At its end an animation gives way to another of the same state.
+            setPlay(next === undefined
+                ? { name: animationFor(character, state), index: 0 }
+                : { name: play.name, index: next });
+        }, Math.max(frame.duration, 16));
+        return () => clearTimeout(timer);
+    }, [animation, frame, play, character, state, still]);
+    const { width, height } = character.frameSize;
+    const scale = size / Math.max(width, height);
+    return (_jsx("span", { role: "img", "aria-label": character.name, "data-sprite-animation": play.name, style: {
+            position: 'relative',
+            display: 'block',
+            width: size,
+            height: size,
+        }, children: (frame?.images ?? []).map((image, layer) => (_jsx("span", { "aria-hidden": true, style: {
+                position: 'absolute',
+                left: (size - width * scale) / 2,
+                top: (size - height * scale) / 2,
+                width,
+                height,
+                transform: `scale(${scale})`,
+                transformOrigin: 'top left',
+                backgroundImage: `url(${character.sprite})`,
+                backgroundPosition: `-${image.x}px -${image.y}px`,
+                backgroundRepeat: 'no-repeat',
+                imageRendering: 'pixelated',
+            } }, layer))) }));
+}
+export default SpriteCharacter;

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

@@ -0,0 +1,30 @@
+/**
+ * Datalayer's own characters for the floating assistant (LOOP T-25): drawn
+ * for LOOP and owned by Datalayer, in the spirit of the Office Assistant —
+ * a paper clip of our own, a wizard, a cat and the L👀P eyes. The characters
+ * of Office are Microsoft's and are never bundled (§6.9); a person loads
+ * one they hold the rights to (T-26).
+ *
+ * Each drawing names its moving parts with classes the stage animates by
+ * state — `assistant-body`, `assistant-pupils`, `assistant-lids`,
+ * `assistant-mouth` — so one set of motions serves every character.
+ *
+ * @module chat/assistant/characters
+ */
+import type { JSX } from 'react';
+/** 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. */
+    Drawing: (props: {
+        size: number;
+    }) => JSX.Element;
+}
+/** The characters Datalayer ships, in the order a picker shows them. */
+export declare const ASSISTANT_CHARACTERS: readonly AssistantCharacter[];
+/** The character an assistant shows when none is chosen. */
+export declare const DEFAULT_ASSISTANT_CHARACTER = "paperclip";
+/** A shipped character by id; an unknown id is an error, said plainly. */
+export declare function assistantCharacter(id: string): AssistantCharacter;

package/lib/chat/assistant/characters.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const INK = '#1D1D1F';
+/** Two eyes with lids that blink and pupils that look about. */
+function Eyes({ cx, cy, gap, r, }) {
+    const left = cx - gap / 2;
+    const right = cx + gap / 2;
+    return (_jsxs("g", { children: [_jsx("circle", { cx: left, cy: cy, r: r, fill: "#FFFFFF", stroke: INK, strokeWidth: 1.5 }), _jsx("circle", { cx: right, cy: cy, r: r, fill: "#FFFFFF", stroke: INK, strokeWidth: 1.5 }), _jsxs("g", { className: "assistant-pupils", children: [_jsx("circle", { cx: left + r * 0.15, cy: cy + r * 0.1, r: r * 0.45, fill: INK }), _jsx("circle", { cx: right + r * 0.15, cy: cy + r * 0.1, r: r * 0.45, fill: INK }), _jsx("circle", { cx: left + r * 0.3, cy: cy - r * 0.1, r: r * 0.14, fill: "#FFFFFF" }), _jsx("circle", { cx: right + r * 0.3, cy: cy - r * 0.1, r: r * 0.14, fill: "#FFFFFF" })] }), _jsxs("g", { className: "assistant-lids", children: [_jsx("ellipse", { cx: left, cy: cy, rx: r + 0.5, ry: r + 0.5, fill: "currentColor" }), _jsx("ellipse", { cx: right, cy: cy, rx: r + 0.5, ry: r + 0.5, fill: "currentColor" })] })] }));
+}
+/** A paper clip of our own: a bent wire with eyes on its upper loop. */
+function PaperClip({ size }) {
+    return (_jsx("svg", { width: size, height: size, viewBox: "0 0 96 96", role: "img", "aria-label": "Paper clip", style: { color: '#B8BDC6' }, children: _jsxs("g", { className: "assistant-body", children: [_jsx("path", { d: "M40 86 L40 30 Q40 14 52 14 Q64 14 64 30 L64 74 Q64 82 56 82 Q48 82 48 74 L48 36", fill: "none", stroke: "#9AA0AA", strokeWidth: 6, strokeLinecap: "round", strokeLinejoin: "round" }), _jsx("path", { d: "M40 86 L40 30 Q40 14 52 14 Q64 14 64 30 L64 74 Q64 82 56 82 Q48 82 48 74 L48 36", fill: "none", stroke: "#E3E6EB", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round" }), _jsx("path", { d: "M36 22 Q42 18 47 21", stroke: INK, strokeWidth: 2, fill: "none", strokeLinecap: "round" }), _jsx("path", { d: "M57 21 Q62 18 68 22", stroke: INK, strokeWidth: 2, fill: "none", strokeLinecap: "round" }), _jsx(Eyes, { cx: 52, cy: 30, gap: 16, r: 6.5 }), _jsx("path", { className: "assistant-mouth", d: "M48 44 Q52 47 56 44", stroke: INK, strokeWidth: 2, fill: "none", strokeLinecap: "round" })] }) }));
+}
+/** A wizard: a starred hat, a white beard, kind eyes. */
+function Wizard({ size }) {
+    return (_jsx("svg", { width: size, height: size, viewBox: "0 0 96 96", role: "img", "aria-label": "Wizard", style: { color: '#F2D3B3' }, children: _jsxs("g", { className: "assistant-body", children: [_jsx("path", { d: "M24 92 Q48 58 72 92 Z", fill: "#5B4BB7" }), _jsx("circle", { cx: 48, cy: 48, r: 17, fill: "#F2D3B3" }), _jsx("path", { d: "M31 50 Q48 92 65 50 Q57 60 48 60 Q39 60 31 50 Z", fill: "#F4F4F6", stroke: "#D9DAE0", strokeWidth: 1 }), _jsx("path", { d: "M22 36 L48 2 L74 36 Q48 30 22 36 Z", fill: "#6E5CD6" }), _jsx("path", { d: "M20 37 Q48 29 76 37 Q48 43 20 37 Z", fill: "#4A3C9E" }), _jsx("path", { d: "M52 14 l2 4 4 1 -3 3 1 4 -4 -2 -4 2 1 -4 -3 -3 4 -1 Z", fill: "#F8D469" }), _jsx("circle", { cx: 40, cy: 26, r: 1.8, fill: "#F8D469" }), _jsx(Eyes, { cx: 48, cy: 46, gap: 13, r: 5 }), _jsx("path", { className: "assistant-mouth", d: "M44 58 Q48 61 52 58", stroke: INK, strokeWidth: 2, fill: "none", strokeLinecap: "round" })] }) }));
+}
+/** A cat: round, two ears, whiskers, a tail. */
+function Cat({ size }) {
+    return (_jsx("svg", { width: size, height: size, viewBox: "0 0 96 96", role: "img", "aria-label": "Cat", style: { color: '#F4A261' }, children: _jsxs("g", { className: "assistant-body", children: [_jsx("path", { d: "M70 84 Q90 78 84 58", stroke: "#E08A45", strokeWidth: 6, fill: "none", strokeLinecap: "round" }), _jsx("ellipse", { cx: 48, cy: 78, rx: 24, ry: 14, fill: "#F4A261" }), _jsx("path", { d: "M24 30 L28 8 L42 22 Z", fill: "#F4A261" }), _jsx("path", { d: "M72 30 L68 8 L54 22 Z", fill: "#F4A261" }), _jsx("path", { d: "M28 26 L30 14 L38 22 Z", fill: "#F6A5C1" }), _jsx("path", { d: "M68 26 L66 14 L58 22 Z", fill: "#F6A5C1" }), _jsx("circle", { cx: 48, cy: 42, r: 24, fill: "#F4A261" }), _jsx(Eyes, { cx: 48, cy: 38, gap: 18, r: 6.5 }), _jsx("path", { d: "M45 48 L51 48 L48 52 Z", fill: "#B83A6B" }), _jsx("path", { className: "assistant-mouth", d: "M43 55 Q48 58 53 55", stroke: INK, strokeWidth: 2, fill: "none", strokeLinecap: "round" }), _jsx("path", { d: "M30 48 L18 46 M30 52 L18 54 M66 48 L78 46 M66 52 L78 54", stroke: INK, strokeWidth: 1.2, strokeLinecap: "round" })] }) }));
+}
+/** The L👀P eyes: the product's own face, two eyes and nothing else. */
+function LoopEyes({ size }) {
+    return (_jsx("svg", { width: size, height: size, viewBox: "0 0 96 96", role: "img", "aria-label": "L\uD83D\uDC40P eyes", style: { color: '#FFFFFF' }, children: _jsxs("g", { className: "assistant-body", children: [_jsx(Eyes, { cx: 48, cy: 50, gap: 40, r: 18 }), _jsx("path", { className: "assistant-mouth", d: "M42 80 Q48 84 54 80", stroke: INK, strokeWidth: 2.5, fill: "none", strokeLinecap: "round", opacity: 0 })] }) }));
+}
+/** The characters Datalayer ships, in the order a picker shows them. */
+export const ASSISTANT_CHARACTERS = [
+    { id: 'paperclip', name: 'Paper clip', Drawing: PaperClip },
+    { id: 'wizard', name: 'Wizard', Drawing: Wizard },
+    { id: 'cat', name: 'Cat', Drawing: Cat },
+    { id: 'eyes', name: 'L👀P eyes', Drawing: LoopEyes },
+];
+/** The character an assistant shows when none is chosen. */
+export const DEFAULT_ASSISTANT_CHARACTER = 'paperclip';
+/** A shipped character by id; an unknown id is an error, said plainly. */
+export function assistantCharacter(id) {
+    const found = ASSISTANT_CHARACTERS.find(character => character.id === id);
+    if (!found) {
+        throw new Error(`There is no assistant character "${id}"; the characters are ${ASSISTANT_CHARACTERS.map(c => c.id).join(', ')}.`);
+    }
+    return found;
+}

package/lib/chat/assistant/formats/acs.d.ts

@@ -0,0 +1,88 @@
+import { type AssistantCharacterData } from './types';
+export declare const ACS_SIGNATURE = 2882382787;
+export declare const ACF_SIGNATURE = 2882382788;
+export interface AcsLocator {
+    offset: number;
+    size: number;
+}
+export interface AcsFrameImage {
+    image: number;
+    x: number;
+    y: number;
+}
+export interface AcsFrame {
+    /** Images, as stored: the first is drawn on top. */
+    images: AcsFrameImage[];
+    /** Index into the audio list, or -1. */
+    sound: number;
+    /** In 1/100 s. */
+    duration: number;
+    /** Frame index, or a negative value for none. */
+    exitBranch: number;
+    branches: {
+        frameIndex: number;
+        probability: number;
+    }[];
+}
+export interface AcsAnimation {
+    name: string;
+    transition: number;
+    returnAnimation: string;
+    frames: AcsFrame[];
+}
+export interface AcsImageEntry {
+    locator: AcsLocator;
+}
+/** An `.acs` read into its tables, the images not yet decoded. */
+export interface AcsFile {
+    version: {
+        major: number;
+        minor: number;
+    };
+    name: string;
+    width: number;
+    height: number;
+    transparentIndex: number;
+    /** RGBA, one entry per palette index. */
+    palette: Uint32Array;
+    states: Record<string, string[]>;
+    animations: AcsAnimation[];
+    images: AcsImageEntry[];
+    sounds: AcsLocator[];
+    bytes: Uint8Array;
+}
+/** A decoded image: palette indices, top row first, no padding. */
+export interface AcsImage {
+    width: number;
+    height: number;
+    pixels: Uint8Array;
+}
+/**
+ * Read the tables of an `.acs`: the character, its animations and frames,
+ * where its images and sounds are. Images are decoded by `decodeAcsImage`.
+ */
+export declare function parseAcs(buffer: ArrayBuffer): AcsFile;
+/** Decode one image of an `.acs` into palette indices, top row first. */
+export declare function decodeAcsImage(file: AcsFile, index: number): AcsImage;
+/** One cell of the sprite sheet: the frames that look the same share it. */
+export interface AcsSpriteLayout {
+    columns: number;
+    rows: number;
+    /** The images of each cell, as stored in the frame (first on top). */
+    cells: AcsFrameImage[][];
+    /** For each animation, for each frame, its cell, or -1 for an empty frame. */
+    frameCells: number[][];
+}
+/** Assign a cell to each distinct, non-empty frame. */
+export declare function layoutAcsSprite(file: AcsFile): AcsSpriteLayout;
+/**
+ * Composite a cell as Agent draws a frame: its images from last to first,
+ * each at its offset, the transparent colour left clear. RGBA, frame-sized.
+ */
+export declare function composeAcsCell(file: AcsFile, images: AcsFrameImage[], decode?: (index: number) => AcsImage): Uint8ClampedArray;
+/**
+ * Read a Microsoft Agent character (`.acs`) a person picked: its animations,
+ * a sprite sheet drawn in the page (an object URL), its sounds as object
+ * URLs. Nothing leaves the page.
+ */
+export declare function readAcsCharacter(buffer: ArrayBuffer): Promise<AssistantCharacterData>;