@datalayer/agent-runtimes 1.3.79 → 1.3.81

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

@@ -13,7 +13,8 @@
  * (`AssistantContextMenu`): what the host passes applies — *Inspect the
  * agent…* (the Agent Inspector, in a dialog loaded then), the conversation,
  * the balloon's display, the suggestions, *Stop*, a new conversation,
- * another character, its voice, send it away, its place, about it — and
+ * another character, its voice, a brought character's sounds (off until
+ * *Play its sounds*), send it away, its place, about it — and
  * what a host or a plugin adds (`contextMenu`).
  *
  * Given suggestions, its balloon offers them while it waits for a question
@@ -36,7 +37,7 @@ import type { AssistantCharacterData } from './formats/types';
 import type { DecisionAsker } from './decisions';
 import { type BalloonDisplay, type BalloonToolLine } from './toolLine';
 import type { DisplayItem } from '../../types/chat';
-import { type AssistantAway, type AssistantState, type BalloonApproval } from './state';
+import { mouthOpening, type AssistantAway, type AssistantState, type BalloonApproval } from './state';
 /** What the assistant's *About* says. */
 export type AssistantAbout = {
     /** The agent's name, or its application's. */
@@ -90,6 +91,11 @@ export declare function assistantMenuItems(options: {
         muted: boolean;
         onToggle: () => void;
     };
+    /** The sounds of a character read from a file (T-26): off unless asked. */
+    characterSounds?: {
+        on: boolean;
+        onToggle: () => void;
+    };
     onResetPosition?: () => void;
     about?: () => void;
     extra?: readonly AssistantMenuItem[];
@@ -286,8 +292,7 @@ export interface AssistantStageProps {
      */
     label?: string;
 }
-/** The openings of the mouth, by level: shut, a little, half, wide. */
-export declare function mouthOpening(level: number): 0 | 1 | 2 | 3;
+export { mouthOpening };
 /**
  * Moves the mouth with the voice: the opening is written on the stage as
  * `data-assistant-mouth`, each frame, without drawing the character again.

package/lib/chat/assistant/AssistantStage.js

@@ -11,7 +11,7 @@ import { AssistantContextMenu, LONG_PRESS_MS, opensContextMenu, } from './Assist
 import { BalloonExpandContext, ExpandedVisual, focusExpanded, } from './BalloonVisual';
 import { SpriteCharacter } from './SpriteCharacter';
 import { conversationCount, } from './toolLine';
-import { ASSISTANT_OBSTACLES, POINTER_CALM_MS, boxesMeet, pointerNear, } from './state';
+import { ASSISTANT_OBSTACLES, POINTER_CALM_MS, mouthOpening, boxesMeet, pointerNear, } from './state';
 /** The motions, by the state the stage is in. */
 const MOTIONS = {
     '@keyframes assistantFloat': {
@@ -176,6 +176,14 @@ export function assistantMenuItems(options) {
             onSelect: options.speech.onToggle,
         });
     }
+    if (options.characterSounds) {
+        items.push({
+            id: 'character-sounds',
+            label: options.characterSounds.on ? 'Mute its sounds' : 'Play its sounds',
+            icon: options.characterSounds.on ? MuteIcon : UnmuteIcon,
+            onSelect: options.characterSounds.onToggle,
+        });
+    }
     if (options.onResetPosition) {
         items.push({
             id: 'reset-position',
@@ -327,10 +335,7 @@ export function useKeepClear(stageRef, own, paused) {
     }, [stageRef, own, paused]);
     return obstructed ? 'obstacle' : pointerBusy ? 'pointer' : undefined;
 }
-/** The openings of the mouth, by level: shut, a little, half, wide. */
-export function mouthOpening(level) {
-    return level < 0.08 ? 0 : level < 0.3 ? 1 : level < 0.6 ? 2 : 3;
-}
+export { mouthOpening };
 /**
  * Moves the mouth with the voice: the opening is written on the stage as
  * `data-assistant-mouth`, each frame, without drawing the character again.
@@ -385,6 +390,10 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
     const characterRef = useRef(null);
     const longPress = useRef(undefined);
     const closeMenu = useCallback(() => setMenuAt(null), []);
+    // A character read from a file plays its sounds only once asked (T-26).
+    const [soundsOn, setSoundsOn] = useState(false);
+    const hasSounds = !shipped &&
+        Object.keys(character.sounds ?? {}).length > 0;
     useEffect(() => () => clearTimeout(longPress.current), []);
     // Where the press began: a press that moves is a drag, not a click.
     const pressedAt = useRef(null);
@@ -423,6 +432,9 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
         onClear,
         onChangeCharacter,
         speech,
+        characterSounds: hasSounds
+            ? { on: soundsOn, onToggle: () => setSoundsOn(on => !on) }
+            : undefined,
         onResetPosition,
         about: about ? () => setTelling(true) : undefined,
         extra: contextMenu,
@@ -627,7 +639,7 @@ export function AssistantStage({ character, state, size = 88, place, stageRef, o
                             overflow: 'hidden',
                             clip: 'rect(0 0 0 0)',
                             whiteSpace: 'nowrap',
-                        }, children: `Its character: ${characterName}` })), 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: {
+                        }, children: `Its character: ${characterName}` })), shipped ? (_jsx(shipped.Drawing, { size: size, mode: colorMode })) : (_jsx(SpriteCharacter, { character: character, state: state, size: size, sounds: soundsOn, mouthLevel: mouthLevel }))] }), (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/SpriteCharacter.d.ts

@@ -5,11 +5,27 @@
  * 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.
  *
+ * While it speaks, a frame that has mouths (Microsoft Agent's overlays) is
+ * drawn with one: the one its voice's loudness opens (`mouthLevel`), else
+ * one after another as its words come. Its sounds are played only when the
+ * person asked for them (`sounds`, off unless said: the stage's menu has
+ * *Play its sounds* and *Mute its sounds*).
+ *
  * @module chat/assistant/SpriteCharacter
  */
 import type { JSX } from 'react';
-import type { AssistantCharacterAnimation, AssistantCharacterData } from './formats/types';
-import type { AssistantState } from './state';
+import type { AssistantCharacterAnimation, AssistantCharacterData, AssistantCharacterFrame, AssistantMouthShape } from './formats/types';
+import { type AssistantState } from './state';
+/** How often the mouth changes while the character speaks, in milliseconds. */
+export declare const MOUTH_STEP_MS = 110;
+/**
+ * The mouth a frame is drawn with: among the ones it has, the one the voice's
+ * `level` opens (any of the wide ones when wide, by `draw`), else, with no
+ * voice, one drawn at random; `undefined` when the frame has none.
+ */
+export declare function mouthFor(frame: Pick<AssistantCharacterFrame, 'mouths'> | undefined, level: number | undefined, draw?: number): AssistantMouthShape | undefined;
+/** Plays a sound of the character, in the page. */
+export declare function playCharacterSound(url: string): void;
 /**
  * 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
@@ -18,9 +34,15 @@ import type { AssistantState } from './state';
 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, }: {
+export declare function SpriteCharacter({ character, state, size, sounds, mouthLevel, playSound, }: {
     character: AssistantCharacterData;
     state: AssistantState;
     size: number;
+    /** Whether its sounds are played: off unless the person asked. */
+    sounds?: boolean;
+    /** How loud its voice is now, between 0 and 1, while it is heard. */
+    mouthLevel?: () => number;
+    /** How a sound is played; the page's `Audio` by default. */
+    playSound?: (url: string) => void;
 }): JSX.Element;
 export default SpriteCharacter;

package/lib/chat/assistant/SpriteCharacter.js

@@ -1,6 +1,46 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useMemo, useState } from 'react';
 import { stateAnimations } from './formats/stateAnimations';
+import { mouthOpening } from './state';
+/** How often the mouth changes while the character speaks, in milliseconds. */
+export const MOUTH_STEP_MS = 110;
+const WIDE = ['wide1', 'wide2', 'wide3', 'wide4'];
+/** The shapes to try, by opening (shut, a little, half, wide). */
+const BY_OPENING = {
+    0: ['closed', 'narrow'],
+    1: ['narrow', 'medium', 'closed'],
+    2: ['medium', 'narrow', ...WIDE],
+    3: [...WIDE, 'medium'],
+};
+/**
+ * The mouth a frame is drawn with: among the ones it has, the one the voice's
+ * `level` opens (any of the wide ones when wide, by `draw`), else, with no
+ * voice, one drawn at random; `undefined` when the frame has none.
+ */
+export function mouthFor(frame, level, draw = Math.random()) {
+    const has = Object.keys(frame?.mouths ?? {});
+    if (has.length === 0) {
+        return undefined;
+    }
+    if (level === undefined) {
+        return has[Math.min(has.length - 1, Math.floor(draw * has.length))];
+    }
+    const wanted = BY_OPENING[mouthOpening(level)];
+    const wide = WIDE.filter(shape => has.includes(shape));
+    if (mouthOpening(level) === 3 && wide.length > 0) {
+        return wide[Math.min(wide.length - 1, Math.floor(draw * wide.length))];
+    }
+    return wanted.find(shape => has.includes(shape)) ?? has[0];
+}
+/** Plays a sound of the character, in the page. */
+export function playCharacterSound(url) {
+    const audio = new Audio(url);
+    // A sound the browser will not play now (the page not yet interacted
+    // with) is skipped: the next frame's will be tried.
+    Promise.resolve(audio.play()).catch((error) => {
+        console.warn(`A sound of the character was not played: ${String(error)}`);
+    });
+}
 /**
  * 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
@@ -24,7 +64,7 @@ export function animationFor(character, state, draw = Math.random()) {
 }
 const reducedMotion = () => typeof window !== 'undefined' &&
     !!window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
-export function SpriteCharacter({ character, state, size, }) {
+export function SpriteCharacter({ character, state, size, sounds = false, mouthLevel, playSound = playCharacterSound, }) {
     const [play, setPlay] = useState(() => ({
         name: animationFor(character, state),
         index: 0,
@@ -49,14 +89,39 @@ export function SpriteCharacter({ character, state, size, }) {
         }, Math.max(frame.duration, 16));
         return () => clearTimeout(timer);
     }, [animation, frame, play, character, state, still]);
+    // Its sound, when the frame that has one shows and sounds were asked for.
+    const soundUrl = sounds && frame?.sound !== undefined
+        ? character.sounds?.[frame.sound]
+        : undefined;
+    useEffect(() => {
+        if (soundUrl) {
+            playSound(soundUrl);
+        }
+        // Each time a frame with a sound shows, the same sound again included.
+    }, [soundUrl, play, playSound]);
+    // While it speaks, the frame's mouths, one after another.
+    const speaking = state === 'speaking' && !still && Boolean(frame?.mouths);
+    const [mouth, setMouth] = useState();
+    useEffect(() => {
+        if (!speaking) {
+            setMouth(undefined);
+            return;
+        }
+        const step = () => setMouth(mouthFor(frame, mouthLevel?.()));
+        step();
+        const timer = setInterval(step, MOUTH_STEP_MS);
+        return () => clearInterval(timer);
+    }, [speaking, frame, mouthLevel]);
+    const withMouth = speaking && mouth ? frame?.mouths?.[mouth] : undefined;
+    const drawn = withMouth ? [withMouth] : (frame?.images ?? []);
     const { width, height } = character.frameSize;
     const scale = size / Math.max(width, height);
-    return (_jsx("span", { className: "assistant-sprite", role: "img", "aria-label": character.name, "data-sprite-animation": play.name, style: {
+    return (_jsx("span", { className: "assistant-sprite", role: "img", "aria-label": character.name, "data-sprite-animation": play.name, ...(withMouth ? { 'data-sprite-mouth': mouth } : {}), style: {
             position: 'relative',
             display: 'block',
             width: size,
             height: size,
-        }, children: (frame?.images ?? []).map((image, layer) => (_jsx("span", { "aria-hidden": true, style: {
+        }, children: drawn.map((image, layer) => (_jsx("span", { "aria-hidden": true, style: {
                 position: 'absolute',
                 left: (size - width * scale) / 2,
                 top: (size - height * scale) / 2,

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

@@ -0,0 +1,56 @@
+import { type AcsFrame, type AcsImage } from './acs';
+import { type AssistantCharacterData } from './types';
+/** An animation the `.acf` names, and the `.aca` file that holds it. */
+export interface AcfAnimationEntry {
+    name: string;
+    /** The `.aca` file's name, without a folder. */
+    file: string;
+    returnAnimation: string;
+    checksum: number;
+}
+/** An `.acf` read: the character, and where its animations are. */
+export interface AcfFile {
+    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: AcfAnimationEntry[];
+}
+/** One `.aca` read: its frames index its own images and sounds. */
+export interface AcaFile {
+    version: {
+        major: number;
+        minor: number;
+    };
+    checksum: number;
+    transition: number;
+    frames: AcsFrame[];
+    images: AcsImage[];
+    sounds: Uint8Array[];
+}
+/**
+ * Read an `.acf`: its header, its character data (compressed or not), the
+ * animations it names.
+ */
+export declare function parseAcf(buffer: ArrayBuffer): AcfFile;
+/**
+ * Read one `.aca`, for a character of `width`×`height`: its sounds, its
+ * images (frame-sized), its frames and their mouths. `file` names it in the
+ * sentences that refuse it.
+ */
+export declare function parseAca(buffer: ArrayBuffer, width: number, height: number, file: string): AcaFile;
+/**
+ * Read a Microsoft Agent character for the web: its `.acf` and the `.aca`
+ * files it names, picked together (`acas` by file name, any case). Every
+ * animation the `.acf` names has to be there, the one it names (by its
+ * checksum); otherwise it is refused in a sentence. Drawn in the page as an
+ * `.acs` is: a sprite sheet, its mouths, its sounds, all object URLs.
+ */
+export declare function readAcfCharacter(acf: ArrayBuffer, acas: Readonly<Record<string, ArrayBuffer>>): Promise<AssistantCharacterData>;

package/lib/chat/assistant/formats/acf.js

@@ -0,0 +1,317 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Microsoft Agent's character for the web (LOOP T-26): an `.acf` that holds
+ * the character — its size, palette, states, names — and names one `.aca`
+ * file per animation, each holding that animation's frames, images, sounds
+ * and mouths. Read in the page after Lebeau's public description (MSAgent
+ * Character Data Specification 1.3, "ACF Format", "ACA Format"), from the
+ * files a person picked together; nothing is fetched and nothing is sent.
+ *
+ * An `.aca` frame is one image, the frame's images composited when the
+ * file was compiled; its mouths are images of their own, drawn over the
+ * frame's image or over a base image that stands for the frame without its
+ * top image.
+ *
+ * Checked against hand-built files only, as the `.acs` reader was: no
+ * character of Microsoft's is in the repository.
+ *
+ * @module chat/assistant/formats/acf
+ */
+import { decompressAgentData } from './agentCompression';
+import { ACF_SIGNATURE, AgentReader, drawAgentCharacter, } from './acs';
+import { AssistantCharacterFormatError, } from './types';
+/** No image, or no sound, in an `.aca` frame. */
+const NONE = 0xffff;
+/** A bottom-up 8-bit bitmap, its rows padded to four bytes, top row first. */
+function topDown(bitmap, width, height) {
+    const stride = (width + 3) & ~3;
+    const pixels = new Uint8Array(width * height);
+    for (let y = 0; y < height; y++) {
+        const from = (height - 1 - y) * stride;
+        pixels.set(bitmap.subarray(from, from + width), y * width);
+    }
+    return pixels;
+}
+const strideSize = (width, height) => ((width + 3) & ~3) * height;
+/**
+ * Read an `.acf`: its header, its character data (compressed or not), the
+ * animations it names.
+ */
+export function parseAcf(buffer) {
+    const bytes = new Uint8Array(buffer);
+    if (bytes.length < 12) {
+        throw new AssistantCharacterFormatError(`This is not a Microsoft Agent .acf: the file is ${bytes.length} bytes, shorter than its header.`);
+    }
+    const header = new AgentReader(bytes, '.acf', false);
+    const signature = header.u32('the signature');
+    if (signature !== ACF_SIGNATURE) {
+        throw new AssistantCharacterFormatError(`This is not a Microsoft Agent .acf: it starts with 0x${signature.toString(16).padStart(8, '0')}, not 0xabcdabc4.`);
+    }
+    const size = header.u32('the header');
+    const compressed = header.u32('the header');
+    const data = compressed > 0
+        ? decompressAgentData(header.take(compressed, 'the character data'), size, 'The character data of this .acf')
+        : header.take(size, 'the character data');
+    const r = new AgentReader(data, '.acf', false);
+    const minor = r.u16('the version');
+    const major = r.u16('the version');
+    const animations = [];
+    const animationCount = r.u16('the animations');
+    for (let k = 0; k < animationCount; k++) {
+        const name = r.string('an animation name');
+        const file = r.string(`the file of ${name}`);
+        const returnAnimation = r.string(`the return animation of ${name}`);
+        const checksum = r.u32(`the checksum of ${name}`);
+        animations.push({ name, file, returnAnimation, checksum });
+    }
+    if (animations.length === 0) {
+        throw new AssistantCharacterFormatError('This .acf has no animations.');
+    }
+    r.u32('the character style');
+    r.skip(16, 'the character id');
+    const names = [];
+    const nameCount = r.u16('the character names');
+    for (let k = 0; k < nameCount; k++) {
+        const lang = r.u16('a name language');
+        const value = r.string('a character name');
+        r.string('a character description');
+        r.string('a character extra data');
+        names.push({ lang, name: value });
+    }
+    const width = r.u16('the character width');
+    const height = r.u16('the character height');
+    const transparentIndex = r.u8('the transparent colour');
+    if (width === 0 || height === 0) {
+        throw new AssistantCharacterFormatError(`This .acf is damaged: its character is ${width}×${height} pixels.`);
+    }
+    const colours = r.u32('the colour table');
+    if (colours === 0 || colours > 256) {
+        throw new AssistantCharacterFormatError(`This .acf is damaged or of an unknown version: its colour table says ${colours} colours, where 1 to 256 are expected.`);
+    }
+    const palette = new Uint32Array(256);
+    const table = r.take(colours * 4, 'the colour table');
+    for (let k = 0; k < colours; k++) {
+        // RGBQUAD is blue, green, red, reserved; kept as RGBA in little-endian order.
+        palette[k] =
+            (0xff << 24) |
+                (table[k * 4] << 16) |
+                (table[k * 4 + 1] << 8) |
+                table[k * 4 + 2];
+    }
+    const states = {};
+    const stateCount = r.u16('the states');
+    for (let s = 0; s < stateCount; s++) {
+        const state = r.string('a state name');
+        const count = r.u16('the animations of a state');
+        const list = [];
+        for (let k = 0; k < count; k++) {
+            list.push(r.string('an animation of a state'));
+        }
+        states[state] = list;
+    }
+    // English (0x09 primary language) when there is one, else the first.
+    const name = (names.find(n => (n.lang & 0x3ff) === 0x09) ?? names[0])?.name ?? '';
+    return {
+        version: { major, minor },
+        name: name.trim() || 'Character',
+        width,
+        height,
+        transparentIndex,
+        palette,
+        states,
+        animations,
+    };
+}
+/** A DATABLOCK: a ULONG size, then the bytes. */
+const dataBlock = (r, what) => r.take(r.u32(what), what);
+/**
+ * Read one `.aca`, for a character of `width`×`height`: its sounds, its
+ * images (frame-sized), its frames and their mouths. `file` names it in the
+ * sentences that refuse it.
+ */
+export function parseAca(buffer, width, height, file) {
+    const bytes = new Uint8Array(buffer);
+    const header = new AgentReader(bytes, file, false);
+    const minor = header.u16('the version');
+    const major = header.u16('the version');
+    const checksum = header.u32('the checksum');
+    const compressed = header.u8('the compression flag') !== 0;
+    let data;
+    if (compressed) {
+        const size = header.u32('the size of the animation');
+        const packed = header.u32('the size of the animation');
+        data = decompressAgentData(header.take(packed, 'the animation'), size, `The animation in ${file}`);
+    }
+    else {
+        data = bytes.subarray(header.pos);
+    }
+    const r = new AgentReader(data, file, false);
+    const sounds = [];
+    const soundCount = r.u16('the sounds');
+    for (let k = 0; k < soundCount; k++) {
+        sounds.push(dataBlock(r, `sound ${k}`));
+    }
+    const frameSize = strideSize(width, height);
+    const images = [];
+    const frameImage = (bitmap, what) => {
+        if (bitmap.length !== frameSize) {
+            throw new AssistantCharacterFormatError(`${file} is not of this character: ${what} holds ${bitmap.length} bytes, where a ${width}×${height} frame takes ${frameSize}.`);
+        }
+        return { width, height, pixels: topDown(bitmap, width, height) };
+    };
+    const imageCount = r.u16('the images');
+    for (let k = 0; k < imageCount; k++) {
+        const size = r.u32(`image ${k}`);
+        r.skip(1, `image ${k}`);
+        images.push(frameImage(r.take(size, `image ${k}`), `image ${k}`));
+        dataBlock(r, `the region of image ${k}`);
+    }
+    const transition = r.u8('the transition');
+    const frames = [];
+    const frameCount = r.u16('the frames');
+    for (let f = 0; f < frameCount; f++) {
+        const where = `frame ${f}`;
+        const image = r.u16(where);
+        const sound = r.u16(where);
+        const duration = r.u16(where);
+        r.skip(4, where);
+        const exitBranch = r.i16(where);
+        const branches = [];
+        const branchCount = r.u8(where);
+        for (let k = 0; k < branchCount; k++) {
+            branches.push({ frameIndex: r.u16(where), probability: r.u16(where) });
+        }
+        const overlays = [];
+        const overlayCount = r.u8(where);
+        for (let k = 0; k < overlayCount; k++) {
+            const what = `a mouth of frame ${f}`;
+            const replaceTop = r.u8(what) !== 0;
+            let base;
+            if (replaceTop) {
+                // The frame without its top image, which the mouth is drawn over.
+                images.push(frameImage(dataBlock(r, what), what));
+                base = images.length - 1;
+                dataBlock(r, what);
+            }
+            const type = r.u8(what);
+            const size = r.u32(what);
+            r.skip(1, what);
+            const hasRegion = r.u8(what) !== 0;
+            const x = r.i16(what);
+            const y = r.i16(what);
+            const halfWidth = r.u16(what);
+            const halfHeight = r.u16(what);
+            const bitmap = r.take(size, what);
+            if (hasRegion)
+                dataBlock(r, what);
+            // Its size is said halved: the bytes say which it is.
+            const [w, h] = strideSize(halfWidth * 2, halfHeight * 2) === size
+                ? [halfWidth * 2, halfHeight * 2]
+                : strideSize(halfWidth, halfHeight) === size
+                    ? [halfWidth, halfHeight]
+                    : [0, 0];
+            if (w === 0 || h === 0) {
+                throw new AssistantCharacterFormatError(`${file} is damaged: ${what} holds ${size} bytes, which an image of ${halfWidth * 2}×${halfHeight * 2} pixels does not.`);
+            }
+            images.push({ width: w, height: h, pixels: topDown(bitmap, w, h) });
+            overlays.push({
+                type,
+                replaceTop,
+                image: images.length - 1,
+                x,
+                y,
+                ...(base !== undefined ? { base: [{ image: base, x: 0, y: 0 }] } : {}),
+            });
+        }
+        if (image !== NONE && image >= imageCount) {
+            throw new AssistantCharacterFormatError(`${file} is damaged: frame ${f} draws image ${image}, and there are ${imageCount}.`);
+        }
+        if (sound !== NONE && sound >= soundCount) {
+            throw new AssistantCharacterFormatError(`${file} is damaged: frame ${f} plays sound ${sound}, and there are ${soundCount}.`);
+        }
+        frames.push({
+            images: image === NONE ? [] : [{ image, x: 0, y: 0 }],
+            sound: sound === NONE ? -1 : sound,
+            duration,
+            exitBranch,
+            branches,
+            overlays,
+        });
+    }
+    frames.forEach((frame, f) => {
+        for (const branch of frame.branches) {
+            if (branch.frameIndex >= frames.length) {
+                throw new AssistantCharacterFormatError(`${file} is damaged: frame ${f} branches to frame ${branch.frameIndex}, and there are ${frames.length}.`);
+            }
+        }
+    });
+    return {
+        version: { major, minor },
+        checksum,
+        transition,
+        frames,
+        images,
+        sounds,
+    };
+}
+/**
+ * Read a Microsoft Agent character for the web: its `.acf` and the `.aca`
+ * files it names, picked together (`acas` by file name, any case). Every
+ * animation the `.acf` names has to be there, the one it names (by its
+ * checksum); otherwise it is refused in a sentence. Drawn in the page as an
+ * `.acs` is: a sprite sheet, its mouths, its sounds, all object URLs.
+ */
+export async function readAcfCharacter(acf, acas) {
+    const file = parseAcf(acf);
+    const byName = new Map(Object.entries(acas).map(([name, buffer]) => [name.toLowerCase(), buffer]));
+    const missing = file.animations.filter(entry => !byName.has(entry.file.toLowerCase()));
+    if (missing.length > 0) {
+        const named = missing
+            .slice(0, 3)
+            .map(entry => entry.file)
+            .join(', ');
+        throw new AssistantCharacterFormatError(`This .acf names ${missing.length} animation file${missing.length === 1 ? '' : 's'} that ${missing.length === 1 ? 'was' : 'were'} not picked (${named}${missing.length > 3 ? '…' : ''}): pick the .acf with every .aca beside it.`);
+    }
+    const images = [];
+    const sounds = [];
+    const animations = file.animations.map(entry => {
+        const aca = parseAca(byName.get(entry.file.toLowerCase()), file.width, file.height, entry.file);
+        if (aca.checksum !== entry.checksum) {
+            throw new AssistantCharacterFormatError(`${entry.file} is not the one this .acf names for ${entry.name}: their checksums differ.`);
+        }
+        const imageBase = images.length;
+        const soundBase = sounds.length;
+        images.push(...aca.images);
+        sounds.push(...aca.sounds);
+        const shift = (list) => list.map(i => ({ ...i, image: i.image + imageBase }));
+        return {
+            name: entry.name,
+            transition: aca.transition,
+            returnAnimation: entry.returnAnimation,
+            frames: aca.frames.map(frame => ({
+                ...frame,
+                images: shift(frame.images),
+                sound: frame.sound < 0 ? -1 : frame.sound + soundBase,
+                overlays: frame.overlays.map(overlay => ({
+                    ...overlay,
+                    image: overlay.image + imageBase,
+                    ...(overlay.base ? { base: shift(overlay.base) } : {}),
+                })),
+            })),
+        };
+    });
+    return drawAgentCharacter({
+        name: file.name,
+        width: file.width,
+        height: file.height,
+        transparentIndex: file.transparentIndex,
+        palette: file.palette,
+        states: file.states,
+        animations,
+        decode: index => images[index],
+        sound: index => sounds[index],
+    });
+}