@datalayer/agent-runtimes 1.5.20 → 1.5.21

package/lib/apps/embed/visitorApp.d.ts

@@ -35,7 +35,7 @@
 import type { AppSpec } from '../../types/agentspecs';
 import type { DatalayerVisitors } from '../apps/visitorToken';
 /** Where the visitors' runtime is published, on ai-agents' host (its chart). */
-export declare const VISITORS_PATH = "/api/loop-visitors";
+export declare const VISITORS_PATH = "/api/runtime-visitors";
 /** The examples the visitors' runtime keeps warm (its chart's `AGENT_RUNTIMES_VISITORS`). */
 export declare const VISITOR_EXAMPLES: readonly string[];
 /** The key of an application at its address, as a visitor's token names it. */

package/lib/apps/embed/visitorApp.js

@@ -6,7 +6,7 @@ import { getApp } from '../../specs/apps';
 import { parseAppspec } from '../apps/appspec';
 import { runnable } from './embedConfig';
 /** Where the visitors' runtime is published, on ai-agents' host (its chart). */
-export const VISITORS_PATH = '/api/loop-visitors';
+export const VISITORS_PATH = '/api/runtime-visitors';
 /** The examples the visitors' runtime keeps warm (its chart's `AGENT_RUNTIMES_VISITORS`). */
 export const VISITOR_EXAMPLES = [
     'web-research',

package/lib/apps/plugins/chat/ChatView.js

@@ -56,6 +56,7 @@ import { latestSaying, newestIsAnswer, } from '../../../chat/assistant/state';
 import { useChatWords } from '../../../chat/ChatLanguage';
 import { ComposerVoice } from '../../../voice/ComposerVoice';
 import { settledVoice, voiceAskedAs } from '../../../voice/chatVoice';
+import { useVoiceSettings } from '../../../voice/useVoiceSettings';
 /** No editor: the conversation on its own. */
 const NO_SURFACE = '';
 /**
@@ -1177,7 +1178,11 @@ export default function ChatView({ workspace }) {
      * workspace's composer, which this view holds — the words written in it as
      * they are heard. The chat speaks its answers itself (`voice` below).
      */
-    const voice = useMemo(() => (config?.voice ? settledVoice(config.voice) : undefined), [config?.voice]);
+    // The person's own settings, followed as the voice menu changes them (VO-30).
+    const [personVoice] = useVoiceSettings();
+    const voice = useMemo(() => (config?.voice ? settledVoice(config.voice, personVoice) : undefined), [config?.voice, personVoice]);
+    // The words in the box are still being heard: greyed until final (VO-11).
+    const [voiceInterim, setVoiceInterim] = useState(false);
     /*
      * The model this conversation is on.
      *
@@ -1672,6 +1677,7 @@ export default function ChatView({ workspace }) {
         suggestions: chatSuggestions,
         disableInputPrompt: chatDisabled,
         connectionConfirmed: !chatDisabled,
+        interim: voiceInterim,
         // Tighter on top: every pixel of the composer is a pixel of the editor
         // under it pushed down, and the bar reads as a command line at this size.
         // Both of the page layout's placements are that bar — one floating over
@@ -1693,7 +1699,12 @@ export default function ChatView({ workspace }) {
         footerExtras: promptActions.length > 0 || (voice && voice.input !== 'off') ? (_jsxs(_Fragment, { children: [promptActions.length > 0 ? (_jsx(ReactorSlot, { slot: LoopSlots.promptAction, props: { workspace } })) : null, voice && voice.input !== 'off' ? (_jsx(ComposerVoice, { voice: voice, input: draft, setInput: setDraft, disabled: chatDisabled, 
                     // The chat's own speaker, never a second one: the microphone
                     // opening stops it, and *Stop speaking* while it speaks.
-                    speaking: speaking, onStopSpeaking: () => controlsRef.current?.stopSpeaking?.(), onSpoken: metadata => {
+                    speaking: speaking, onStopSpeaking: () => controlsRef.current?.stopSpeaking?.(), onInterimChange: setVoiceInterim, 
+                    // The menu offers when answers are heard where the
+                    // application lets them be (VO-21, VO-30).
+                    answers: Boolean(config?.voice?.output &&
+                        config.voice.output !== 'off' &&
+                        config.voice.speechUrl), onSpoken: metadata => {
                         spokenRef.current = metadata;
                     }, send: (text, metadata) => {
                         spokenRef.current = metadata;

package/lib/chat/ChatFloating.js

@@ -36,6 +36,7 @@ import { DecisionAsk } from './assistant/DecisionAsk';
 import { useSpokenAnswers } from '../voice/useSpokenAnswers';
 import { useVoiceSpeaker } from '../voice/useVoiceSpeaker';
 import { settledVoice } from '../voice/chatVoice';
+import { useVoiceSettings } from '../voice/useVoiceSettings';
 import { BalloonApprovalMessage, CONVERSATION_BALLOON_WIDTH, ConversationBalloonClose, balloonTailAt, conversationBalloonHeight, conversationBalloonSx, CURRENT_BALLOON_HEIGHT, peekLine, } from './assistant/ConversationBalloon';
 import { ConversationBalloonHeader, CurrentBalloonBody, } from './assistant/BalloonParts';
 import { DEFAULT_BALLOON_DISPLAY, conversationCount, newestToolLine, toolLineText, } from './assistant/toolLine';
@@ -163,7 +164,9 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
      * they are written (VO-20), the state following the sound (VO-22).
      */
     const [voiceItems, setVoiceItems] = useState([]);
-    const settledVoiceOf = useMemo(() => (voice ? settledVoice(voice) : undefined), [voice]);
+    // The person's own settings, followed as the voice menu changes them (VO-30).
+    const [personVoice] = useVoiceSettings();
+    const settledVoiceOf = useMemo(() => (voice ? settledVoice(voice, personVoice) : undefined), [voice, personVoice]);
     const { speaker, state: speakerState, stop: stopSpeaking, read: readAnswerAloud, level: mouthLevel, } = useVoiceSpeaker(settledVoiceOf);
     // `always`: each answer heard as it is written; `on_request`: a *Read
     // aloud* under each (VO-21).

package/lib/chat/base/ChatBase.js

@@ -51,6 +51,7 @@ import { InputPrompt } from '../prompt/InputPrompt';
 import { ComposerVoice, spokenOf } from '../../voice/ComposerVoice';
 import { ReadAloud, readsAloud } from '../../voice/ReadAloud';
 import { settledVoice } from '../../voice/chatVoice';
+import { useVoiceSettings } from '../../voice/useVoiceSettings';
 import { useVoiceSpeaker } from '../../voice/useVoiceSpeaker';
 import { useSpokenAnswers } from '../../voice/useSpokenAnswers';
 import { isFloatingChatViewMode } from '../viewModes';
@@ -3014,7 +3015,11 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     // Voice (VOICE.md V1): what was said and put in the composer, until sent.
     const spokenRef = useRef(undefined);
     // Its voice with what it leaves unsaid filled in: Datalayer's models and packages.
-    const settled = useMemo(() => (voice ? settledVoice(voice) : undefined), [voice]);
+    // The person's own settings, followed as the voice menu changes them (VO-30).
+    const [personVoice] = useVoiceSettings();
+    const settled = useMemo(() => (voice ? settledVoice(voice, personVoice) : undefined), [voice, personVoice]);
+    // The words in the box are still being heard: greyed until final (VO-11).
+    const [voiceInterim, setVoiceInterim] = useState(false);
     /*
      * Its answers heard (VO-20, VO-21), by Datalayer's speech service: the
      * host's speaker when it gives one (`ChatFloating`, whose assistant's mouth
@@ -3802,12 +3807,15 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                 // so every chat with a headless notebook gets the same transcript.
                 notebookToolSurfacesId: notebookToolSurfacesId, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, showTurnFooters: showTurnFooter, renderMessageFooter: readAloudFooter, agentUsage: agentUsage, onRemoveItems: handleRemoveItems, mcpServers: filteredMcpServers, emptyContent: launching ? null : (_jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: resolvedDescription, suggestions: resolvedSuggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill })) }), trailingContent] }));
     // The microphone, in the composer's footer (VO-10, VO-11).
-    const voiceControl = settled && settled.input !== 'off' ? (_jsx(ComposerVoice, { voice: settled, input: input, setInput: setInput, disabled: disabled || launching, speaking: speakingNow, onStopSpeaking: stopSpeaking, onSpoken: metadata => {
+    const voiceControl = settled && settled.input !== 'off' ? (_jsx(ComposerVoice, { voice: settled, input: input, setInput: setInput, disabled: disabled || launching, speaking: speakingNow, onStopSpeaking: stopSpeaking, onInterimChange: setVoiceInterim, 
+        // The menu offers when answers are heard where the application
+        // lets them be (VO-21, VO-30).
+        answers: Boolean(voice?.output && voice.output !== 'off' && voice.speechUrl), onSpoken: metadata => {
             spokenRef.current = metadata;
         }, send: (text, metadata) => void handleSend(text, undefined, metadata) })) : undefined;
     // Why an answer could not be heard, in a sentence, by the composer.
     const voiceRefused = !hostSpeaks && ownVoice.state.refused ? (_jsx(Text, { role: "alert", sx: { fontSize: 0, color: 'danger.fg', maxWidth: 260 }, "data-voice-refused": "", children: ownVoice.state.refused })) : null;
-    const inputToolbar = showInput ? (_jsx(InputPrompt, { footerExtras: voiceRefused ? (_jsxs(_Fragment, { children: [voiceRefused, voiceControl] })) : (voiceControl), input: input, setInput: setInput, isLoading: isLoading, kernelStatus: liveKernelStatus, connectionConfirmed: connectionConfirmed, placeholder: placeholder, 
+    const inputToolbar = showInput ? (_jsx(InputPrompt, { footerExtras: voiceRefused ? (_jsxs(_Fragment, { children: [voiceRefused, voiceControl] })) : (voiceControl), interim: voiceInterim, input: input, setInput: setInput, isLoading: isLoading, kernelStatus: liveKernelStatus, connectionConfirmed: connectionConfirmed, placeholder: placeholder, 
         /*
           The same openers the empty state offers, typed into the box they would
           be typed into.

package/lib/chat/prompt/InputPrompt.d.ts

@@ -50,6 +50,11 @@ export interface InputPromptProps {
      * additions rather than reshuffling the controls people know.
      */
     footerExtras?: ReactNode;
+    /**
+     * The words in the box are still being heard by the microphone (VOICE.md
+     * VO-11): shown greyed, in italics, until they are final.
+     */
+    interim?: boolean;
     /**
      * Panels inside the prompt's card, above and below the composer itself.
      *
@@ -226,4 +231,4 @@ export interface InputPromptProps {
     /** Pre-fetched MCP status from WebSocket — bypasses REST polling */
     mcpStatusData?: McpToolsetsStatusResponse | null;
 }
-export declare function InputPrompt({ input, setInput, isLoading, kernelStatus, connectionConfirmed, placeholder, typingSuggestions, autoFocus, focusTrigger, padding, placement, floatingAnchor, draggable, container, footerExtras, leadingPanel, trailingPanel, onSend, onStop, disableInputPrompt, promptVariant, mentionableAgents, promptCommands, promptHistory, headerContent, showAgentsMenu, showInlineAgentsMenu, agents, selectedAgentId, onSelectAgent, showTokenUsage, showContextRing, agentUsage, showModelSelector, showToolsMenu, showSkillsMenu, showSuggestionsMenu, suggestions, codemodeEnabled, onToggleCodemode, isA2AProtocol, hasConfigData, hasSkillsData, configLoading, models, decisions, selectedModel, onModelSelect, availableTools, availableFrontendTools, mcpServers, enabledMcpTools, enabledMcpToolCount, onToggleMcpTool, onToggleAllMcpServerTools, approvedMcpTools, onToggleMcpToolApproval, skills, skillsLoading, enabledSkills, onToggleSkill, onToggleAllSkills, approvedSkills, onToggleSkillApproval, apiBase, authToken, mcpStatusData, }: InputPromptProps): import("react").JSX.Element;
+export declare function InputPrompt({ input, setInput, isLoading, kernelStatus, connectionConfirmed, placeholder, typingSuggestions, autoFocus, focusTrigger, padding, placement, floatingAnchor, draggable, container, footerExtras, interim, leadingPanel, trailingPanel, onSend, onStop, disableInputPrompt, promptVariant, mentionableAgents, promptCommands, promptHistory, headerContent, showAgentsMenu, showInlineAgentsMenu, agents, selectedAgentId, onSelectAgent, showTokenUsage, showContextRing, agentUsage, showModelSelector, showToolsMenu, showSkillsMenu, showSuggestionsMenu, suggestions, codemodeEnabled, onToggleCodemode, isA2AProtocol, hasConfigData, hasSkillsData, configLoading, models, decisions, selectedModel, onModelSelect, availableTools, availableFrontendTools, mcpServers, enabledMcpTools, enabledMcpToolCount, onToggleMcpTool, onToggleAllMcpServerTools, approvedMcpTools, onToggleMcpToolApproval, skills, skillsLoading, enabledSkills, onToggleSkill, onToggleAllSkills, approvedSkills, onToggleSkillApproval, apiBase, authToken, mcpStatusData, }: InputPromptProps): import("react").JSX.Element;

package/lib/chat/prompt/InputPrompt.js

@@ -30,7 +30,7 @@ const EMPTY_ID_SET = new Set();
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export function InputPrompt({ input, setInput, isLoading, kernelStatus, connectionConfirmed, placeholder, typingSuggestions, autoFocus, focusTrigger, padding, placement, floatingAnchor = 'bottom', draggable = false, container, footerExtras, leadingPanel, trailingPanel, onSend, onStop, disableInputPrompt = false, promptVariant, mentionableAgents, promptCommands, promptHistory, headerContent, showAgentsMenu = false, showInlineAgentsMenu = true, agents = [], selectedAgentId, onSelectAgent, showTokenUsage, showContextRing = false, agentUsage, showModelSelector, showToolsMenu, showSkillsMenu, showSuggestionsMenu = true, suggestions, codemodeEnabled, onToggleCodemode, isA2AProtocol, hasConfigData, hasSkillsData, configLoading = false, models = [], decisions, selectedModel = '', onModelSelect = () => { }, availableTools = [], availableFrontendTools = [], mcpServers = [], enabledMcpTools = EMPTY_TOOL_MAP, enabledMcpToolCount = 0, onToggleMcpTool = () => { }, onToggleAllMcpServerTools = () => { }, approvedMcpTools = EMPTY_TOOL_MAP, onToggleMcpToolApproval = () => { }, skills = [], skillsLoading = false, enabledSkills = EMPTY_ID_SET, onToggleSkill = () => { }, onToggleAllSkills = () => { }, approvedSkills = EMPTY_ID_SET, onToggleSkillApproval = () => { }, apiBase, authToken, mcpStatusData, }) {
+export function InputPrompt({ input, setInput, isLoading, kernelStatus, connectionConfirmed, placeholder, typingSuggestions, autoFocus, focusTrigger, padding, placement, floatingAnchor = 'bottom', draggable = false, container, footerExtras, interim = false, leadingPanel, trailingPanel, onSend, onStop, disableInputPrompt = false, promptVariant, mentionableAgents, promptCommands, promptHistory, headerContent, showAgentsMenu = false, showInlineAgentsMenu = true, agents = [], selectedAgentId, onSelectAgent, showTokenUsage, showContextRing = false, agentUsage, showModelSelector, showToolsMenu, showSkillsMenu, showSuggestionsMenu = true, suggestions, codemodeEnabled, onToggleCodemode, isA2AProtocol, hasConfigData, hasSkillsData, configLoading = false, models = [], decisions, selectedModel = '', onModelSelect = () => { }, availableTools = [], availableFrontendTools = [], mcpServers = [], enabledMcpTools = EMPTY_TOOL_MAP, enabledMcpToolCount = 0, onToggleMcpTool = () => { }, onToggleAllMcpServerTools = () => { }, approvedMcpTools = EMPTY_TOOL_MAP, onToggleMcpToolApproval = () => { }, skills = [], skillsLoading = false, enabledSkills = EMPTY_ID_SET, onToggleSkill = () => { }, onToggleAllSkills = () => { }, approvedSkills = EMPTY_ID_SET, onToggleSkillApproval = () => { }, apiBase, authToken, mcpStatusData, }) {
     const chatText = useChatWords();
     const isKernelBusy = kernelStatus === 'busy';
     /*
@@ -107,7 +107,17 @@ export function InputPrompt({ input, setInput, isLoading, kernelStatus, connecti
      * from the start; this shows it.
      */
     const hasContext = Boolean(agentUsage && !agentUsage.error);
-    const body = (_jsxs(Box, { children: [leadingPanel, _jsx(InputPromptBase, { variant: promptVariant, mentionableAgents: mentionableAgents, promptCommands: promptCommands, promptHistory: promptHistory, 
+    const body = (_jsxs(Box
+    // Words still being heard, greyed until final (VO-11); the same Box
+    // either way, so the editor is never mounted again.
+    , { "data-voice-interim": interim ? '' : undefined, sx: interim
+            ? {
+                '& [contenteditable="true"], & textarea': {
+                    color: 'fg.muted',
+                    fontStyle: 'italic',
+                },
+            }
+            : undefined, children: [leadingPanel, _jsx(InputPromptBase, { variant: promptVariant, mentionableAgents: mentionableAgents, promptCommands: promptCommands, promptHistory: promptHistory, 
                 /*
                   Whatever the host puts inside the prompt, and the agent chip beside
                   it. Both, rather than either: a host contributing its own controls

package/lib/voice/ComposerVoice.d.ts

@@ -4,7 +4,10 @@
  * whose composer is a plugin of its own). What the box held when the
  * microphone opened stays; the words heard go after it as they come, and the
  * whole of what was heard replaces them once it stops. Put there for the
- * person to edit and send — or sent at once with *Send what I say*.
+ * person to edit and send — or sent at once with *Send what I say*. While
+ * the words are still being heard the host is told (`onInterimChange`), to
+ * grey them until they are final (VO-11). Beside the microphone, the
+ * person's voice menu (`VoiceMenu`, VO-30).
  *
  * @module voice/ComposerVoice
  */
@@ -26,8 +29,18 @@ export interface ComposerVoiceProps {
     speaking?: boolean;
     /** Stops the agent's voice, also when the microphone opens (VO-13). */
     onStopSpeaking?: () => void;
+    /**
+     * The words in the box are still being heard (`true`), or final
+     * (`false`): the host greys them until they are (VO-11).
+     */
+    onInterimChange?: (interim: boolean) => void;
+    /**
+     * The application lets its answers be heard: the voice menu offers when,
+     * the voice, its speed and loudness (VO-21, VO-25, VO-30).
+     */
+    answers?: boolean;
 }
 /** Whether something rides on a run as a spoken message's metadata (VO-27). */
 export declare function spokenOf(value: unknown): SpokenMetadata | undefined;
-export declare function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled, speaking, onStopSpeaking, }: ComposerVoiceProps): JSX.Element | null;
+export declare function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled, speaking, onStopSpeaking, onInterimChange, answers, }: ComposerVoiceProps): JSX.Element | null;
 export default ComposerVoice;

package/lib/voice/ComposerVoice.js

@@ -1,7 +1,8 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo, useRef } from 'react';
 import { DeviceHearing } from './hearing';
 import { VoiceInput } from './VoiceInput';
+import { VoiceMenu } from './VoiceMenu';
 /** Whether something rides on a run as a spoken message's metadata (VO-27). */
 export function spokenOf(value) {
     const said = value;
@@ -12,7 +13,7 @@ export function spokenOf(value) {
         ? said
         : undefined;
 }
-export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled = false, speaking = false, onStopSpeaking, }) {
+export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled = false, speaking = false, onStopSpeaking, onInterimChange, answers = false, }) {
     const hearing = useMemo(() => voice.input !== 'off'
         ? new DeviceHearing(voice.modelsUrl, voice.engines)
         : undefined, [voice.input, voice.modelsUrl, voice.engines]);
@@ -22,20 +23,25 @@ export function ComposerVoice({ voice, input, setInput, onSpoken, send, disabled
     if (!hearing) {
         return null;
     }
-    return (_jsx(VoiceInput, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', silenceMs: voice.silenceMs, microphoneId: voice.microphoneId, disabled: disabled, speaking: speaking, onStopSpeaking: onStopSpeaking, onListen: () => {
-            base.current = input.trim();
-            onStopSpeaking?.();
-        }, 
-        // The words as they are heard, in the box (VO-11); '' gives it back.
-        onInterim: (words) => setInput(afterBase(words)), onTranscript: (transcript) => {
-            if (voice.sendWhatISay) {
-                setInput(base.current);
-                send(transcript.text, transcript.metadata);
-                return;
-            }
-            // In the box, for the person to edit and send: never sent here.
-            onSpoken(transcript.metadata);
-            setInput(afterBase(transcript.text));
-        } }));
+    return (_jsxs("span", { "data-composer-voice": "", style: { display: 'inline-flex', alignItems: 'center', gap: 2 }, children: [_jsx(VoiceMenu, { voice: voice, answers: answers, disabled: disabled }), _jsx(VoiceInput, { hearing: hearing, language: voice.language, consentKey: voice.consentKey ?? 'chat', silenceMs: voice.silenceMs, microphoneId: voice.microphoneId, disabled: disabled, speaking: speaking, onStopSpeaking: onStopSpeaking, onListen: () => {
+                    base.current = input.trim();
+                    onStopSpeaking?.();
+                }, 
+                // The words as they are heard, in the box (VO-11), greyed until
+                // final; '' gives it back.
+                onInterim: (words) => {
+                    setInput(afterBase(words));
+                    onInterimChange?.(words !== '');
+                }, onTranscript: (transcript) => {
+                    onInterimChange?.(false);
+                    if (voice.sendWhatISay) {
+                        setInput(base.current);
+                        send(transcript.text, transcript.metadata);
+                        return;
+                    }
+                    // In the box, for the person to edit and send: never sent here.
+                    onSpoken(transcript.metadata);
+                    setInput(afterBase(transcript.text));
+                } })] }));
 }
 export default ComposerVoice;

package/lib/voice/VoiceMenu.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The composer's voice menu (VOICE.md VO-14, VO-21, VO-25, VO-30): beside
+ * the microphone, what a person chooses for themselves — the language they
+ * speak and hear, when answers are heard, the voice, its speed and loudness,
+ * *Send what I say*, the microphone, and *Keep speech on this device*. Each
+ * choice is kept in the person's settings and heard at once by every chat
+ * on the page; *Use the application's* forgets them all.
+ *
+ * When answers are heard is offered only where the application lets them be
+ * heard: a menu may not turn on what the application turned off.
+ *
+ * @module voice/VoiceMenu
+ */
+import type { JSX } from 'react';
+import type { SettledVoice } from './chatVoice';
+export interface VoiceMenuProps {
+    /** The chat's voice as it is heard now (`settledVoice`). */
+    voice: SettledVoice;
+    /**
+     * The application lets its answers be heard (its own `output` is not
+     * `off`, and it names the speech service): the menu offers when.
+     */
+    answers: boolean;
+    disabled?: boolean;
+}
+export declare function VoiceMenu({ voice, answers, disabled, }: VoiceMenuProps): JSX.Element;
+export default VoiceMenu;

package/lib/voice/VoiceMenu.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useState } from 'react';
+import { ActionList, ActionMenu, IconButton } from '@primer/react';
+import { GearIcon } from '@primer/octicons-react';
+import { OUTPUT_CHOICES, RATE_CHOICES, VOLUME_CHOICES, catalogueVoiceSpeaks, voiceLanguages, voicesSpeaking, } from './choices';
+import { withVoiceSetting } from './settings';
+import { useVoiceSettings } from './useVoiceSettings';
+/** The microphones the browser lists; named only once one was allowed. */
+async function microphones() {
+    try {
+        const devices = await navigator.mediaDevices.enumerateDevices();
+        return devices.filter(device => device.kind === 'audioinput');
+    }
+    catch {
+        return [];
+    }
+}
+export function VoiceMenu({ voice, answers, disabled = false, }) {
+    const [settings, keep] = useVoiceSettings();
+    const [devices, setDevices] = useState([]);
+    const choose = (key, value) => keep(withVoiceSetting(settings, key, value, catalogueVoiceSpeaks));
+    const onDevice = Boolean(settings.onDeviceOnly);
+    const voices = voicesSpeaking(voice.language);
+    const named = devices.filter(device => device.label);
+    return (_jsxs(ActionMenu, { onOpenChange: open => {
+            if (open) {
+                void microphones().then(setDevices);
+            }
+        }, children: [_jsx(ActionMenu.Anchor, { children: _jsx(IconButton, { icon: GearIcon, size: "small", variant: "invisible", "aria-label": "Voice settings", "data-voice-menu": "", disabled: disabled }) }), _jsx(ActionMenu.Overlay, { width: "medium", children: _jsxs(ActionList, { children: [_jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Language" }), voiceLanguages().map(language => (_jsx(ActionList.Item, { selected: language.value === voice.language, onSelect: () => choose('language', language.value), "data-voice-language": language.value, children: language.label }, language.value)))] }), answers && !onDevice ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Answers heard" }), OUTPUT_CHOICES.map(output => (_jsx(ActionList.Item, { selected: output.value === voice.output, onSelect: () => choose('output', output.value), "data-voice-output": output.value, children: output.label }, output.value)))] }), voices.length > 0 ? (_jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Voice" }), voices.map(spoken => (_jsx(ActionList.Item, { selected: spoken.id === voice.voice, onSelect: () => choose('voice', spoken.id), "data-voice-voice": spoken.id, children: spoken.name }, spoken.id)))] })) : null, _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Speed" }), RATE_CHOICES.map(rate => (_jsx(ActionList.Item, { selected: rate.value === (voice.rate ?? 1), onSelect: () => choose('rate', rate.value), "data-voice-rate": rate.value, children: rate.label }, rate.value)))] }), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Loudness" }), VOLUME_CHOICES.map(volume => (_jsx(ActionList.Item, { selected: volume.value === (voice.volume ?? 1), onSelect: () => choose('volume', volume.value), "data-voice-volume": volume.value, children: volume.label }, volume.value)))] })] })) : null, named.length > 1 ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "single", children: [_jsx(ActionList.GroupHeading, { children: "Microphone" }), named.map(device => (_jsx(ActionList.Item, { selected: device.deviceId ===
+                                                (voice.microphoneId ?? named[0].deviceId), onSelect: () => choose('microphoneId', device.deviceId), "data-voice-microphone": device.deviceId, children: device.label }, device.deviceId)))] })] })) : null, _jsx(ActionList.Divider, {}), _jsxs(ActionList.Group, { selectionVariant: "multiple", children: [_jsxs(ActionList.Item, { selected: Boolean(voice.sendWhatISay), onSelect: () => choose('sendWhatISay', !voice.sendWhatISay), "data-voice-send-what-i-say": "", children: ["Send what I say", _jsx(ActionList.Description, { variant: "block", children: "Sent as soon as it is heard, not left in the box." })] }), _jsxs(ActionList.Item, { selected: onDevice, onSelect: () => choose('onDeviceOnly', !onDevice), "data-voice-on-device": "", children: ["Keep speech on this device", _jsx(ActionList.Description, { variant: "block", children: "Nothing is sent to Datalayer\u2019s speech service: you are heard in the browser, answers are not spoken." })] })] }), Object.keys(settings).length > 0 ? (_jsxs(_Fragment, { children: [_jsx(ActionList.Divider, {}), _jsx(ActionList.Item, { onSelect: () => keep({}), "data-voice-settings-reset": "", children: "Use the application\u2019s" })] })) : null] }) })] }));
+}
+export default VoiceMenu;

package/lib/voice/chatVoice.js

@@ -11,7 +11,7 @@
  * @module voice/chatVoice
  */
 import { voiceFor } from '../specs/voices';
-import { keptVoiceSettings, voiceForPerson, } from './settings';
+import { heldVoiceSettings, voiceForPerson, } from './settings';
 /**
  * Datalayer's origin for the browser's speech models, as pinned
  * (`s3://datalayer-models-speech` behind its CDN; VO-48, VO-49): each model
@@ -88,7 +88,7 @@ export const SILENCE_MS = 1500;
  * Datalayer's models and packages, a silence of 1.5 s. Answers heard need
  * the speech service's address: refused without.
  */
-export function settledVoice(given, person = keptVoiceSettings()) {
+export function settledVoice(given, person = heldVoiceSettings()) {
     const voice = voiceForPerson(given, person);
     const output = voice.output ?? 'off';
     if (output !== 'off' && !voice.speechUrl) {

package/lib/voice/choices.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a person may choose for their voice (VOICE.md VO-14, VO-21, VO-25,
+ * VO-30), from the catalogue: the languages a voice speaks and the device
+ * hears, the voices of each, the speeds and loudnesses offered, and when
+ * answers are heard. Read by the composer's menu (`VoiceMenu`) and by a
+ * settings page, so both offer the same.
+ *
+ * @module voice/choices
+ */
+import { type VoiceSpec } from '../specs/voices';
+import type { ChatVoice } from './index';
+/** A choice as a menu or a page lists it. */
+export interface VoiceChoice<T> {
+    value: T;
+    label: string;
+}
+/** A language's name, in English, as the menu says it: `en-GB` is *British English*. */
+export declare function languageName(language: string): string;
+/**
+ * The languages a person may speak and hear: each a voice of the catalogue
+ * speaks and a model on the device hears, in the catalogue's order.
+ */
+export declare function voiceLanguages(): VoiceChoice<string>[];
+/** The voices that speak a language, in the catalogue's order. */
+export declare function voicesSpeaking(language: string): VoiceSpec[];
+/** Whether a voice of the catalogue speaks a language: what a new language keeps of a chosen voice. */
+export declare function catalogueVoiceSpeaks(voice: string, language: string): boolean;
+/** The speeds offered, as multipliers of the voice's own. */
+export declare const RATE_CHOICES: VoiceChoice<number>[];
+/** The loudnesses offered, 0 to 1. */
+export declare const VOLUME_CHOICES: VoiceChoice<number>[];
+/** When answers are heard (VO-21): what a person may choose where the application speaks. */
+export declare const OUTPUT_CHOICES: VoiceChoice<NonNullable<ChatVoice['output']>>[];

package/lib/voice/choices.js

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * What a person may choose for their voice (VOICE.md VO-14, VO-21, VO-25,
+ * VO-30), from the catalogue: the languages a voice speaks and the device
+ * hears, the voices of each, the speeds and loudnesses offered, and when
+ * answers are heard. Read by the composer's menu (`VoiceMenu`) and by a
+ * settings page, so both offer the same.
+ *
+ * @module voice/choices
+ */
+import { VOICE_CATALOGUE, transcriberFor, voiceSpeaks, } from '../specs/voices';
+/** A language's name, in English, as the menu says it: `en-GB` is *British English*. */
+export function languageName(language) {
+    try {
+        const names = new Intl.DisplayNames(['en'], { type: 'language' });
+        return names.of(language) ?? language;
+    }
+    catch {
+        return language;
+    }
+}
+/**
+ * The languages a person may speak and hear: each a voice of the catalogue
+ * speaks and a model on the device hears, in the catalogue's order.
+ */
+export function voiceLanguages() {
+    const seen = new Set();
+    const languages = [];
+    for (const voice of Object.values(VOICE_CATALOGUE)) {
+        for (const language of voice.languages) {
+            if (!seen.has(language) && transcriberFor(language)) {
+                seen.add(language);
+                languages.push({ value: language, label: languageName(language) });
+            }
+        }
+    }
+    return languages;
+}
+/** The voices that speak a language, in the catalogue's order. */
+export function voicesSpeaking(language) {
+    return Object.values(VOICE_CATALOGUE).filter(voice => voiceSpeaks(voice, language) ||
+        voiceSpeaks(voice, language.split('-')[0]));
+}
+/** Whether a voice of the catalogue speaks a language: what a new language keeps of a chosen voice. */
+export function catalogueVoiceSpeaks(voice, language) {
+    return voicesSpeaking(language).some(spoken => spoken.id === voice);
+}
+/** The speeds offered, as multipliers of the voice's own. */
+export const RATE_CHOICES = [
+    { value: 0.75, label: 'Slower' },
+    { value: 1, label: 'Normal' },
+    { value: 1.25, label: 'Faster' },
+    { value: 1.5, label: 'Fastest' },
+];
+/** The loudnesses offered, 0 to 1. */
+export const VOLUME_CHOICES = [
+    { value: 0.25, label: 'Quiet' },
+    { value: 0.5, label: 'Half' },
+    { value: 0.75, label: 'Loud' },
+    { value: 1, label: 'Full' },
+];
+/** When answers are heard (VO-21): what a person may choose where the application speaks. */
+export const OUTPUT_CHOICES = [
+    { value: 'off', label: 'Never' },
+    { value: 'on_request', label: 'When I ask (Read aloud)' },
+    { value: 'always', label: 'Always, as they are written' },
+];

package/lib/voice/index.d.ts

@@ -16,6 +16,10 @@ export * from './hearing';
 export * from './speaker';
 export * from './consent';
 export * from './settings';
+export * from './choices';
+export { useVoiceSettings } from './useVoiceSettings';
+export { VoiceMenu } from './VoiceMenu';
+export type { VoiceMenuProps } from './VoiceMenu';
 export * from './useSpokenAnswers';
 export { VoiceInput } from './VoiceInput';
 export type { VoiceInputProps, ListeningState } from './VoiceInput';

package/lib/voice/index.js

@@ -10,6 +10,9 @@ export * from './hearing';
 export * from './speaker';
 export * from './consent';
 export * from './settings';
+export * from './choices';
+export { useVoiceSettings } from './useVoiceSettings';
+export { VoiceMenu } from './VoiceMenu';
 export * from './useSpokenAnswers';
 export { VoiceInput } from './VoiceInput';
 export { ReadAloud, readAloud, readsAloud } from './ReadAloud';

package/lib/voice/settings.d.ts

@@ -62,8 +62,24 @@ export interface VoiceSettings {
 export declare function saneVoiceSettings(settings: VoiceSettings | null | undefined): VoiceSettings;
 /** What was kept, or nothing. Storage may be refused, or hold nonsense. */
 export declare function keptVoiceSettings(): VoiceSettings;
-/** Keep what the person chose; an empty choice forgets it. */
+/** The person's settings as the page holds them (VO-30). */
+export declare function heldVoiceSettings(): VoiceSettings;
+/**
+ * Be told when the person's settings change — from a menu on this page, or
+ * from another tab, whose storage event is read here. Returns the unsubscribe.
+ */
+export declare function onVoiceSettingsChange(listener: (settings: VoiceSettings) => void): () => void;
+/**
+ * Keep what the person chose; an empty choice forgets it. Every chat on the
+ * page is told, so the menu's choice is heard at once (VO-30).
+ */
 export declare function keepVoiceSettings(settings: VoiceSettings): VoiceSettings;
+/**
+ * The settings with one choice changed (VO-30): `undefined` forgets that
+ * choice, giving it back to the application. A new language drops a voice
+ * the person chose that does not speak it, for the language's own.
+ */
+export declare function withVoiceSetting<K extends keyof VoiceSettings>(settings: VoiceSettings, key: K, value: VoiceSettings[K] | undefined, speaks?: (voice: string, language: string) => boolean): VoiceSettings;
 /** The language the browser says the person reads, or nothing. */
 export declare function browserLanguage(): string | undefined;
 /**

package/lib/voice/settings.js

@@ -54,7 +54,47 @@ export function keptVoiceSettings() {
         return {};
     }
 }
-/** Keep what the person chose; an empty choice forgets it. */
+/**
+ * What the page holds: the kept settings, or the choice made on this page
+ * when storage refused it. Read once, then told of each change.
+ */
+let held;
+/** Who is told when the person's settings change: every chat on the page (VO-30). */
+const listeners = new Set();
+/** The person's settings as the page holds them (VO-30). */
+export function heldVoiceSettings() {
+    if (held === undefined) {
+        held = keptVoiceSettings();
+    }
+    return held;
+}
+/**
+ * Be told when the person's settings change — from a menu on this page, or
+ * from another tab, whose storage event is read here. Returns the unsubscribe.
+ */
+export function onVoiceSettingsChange(listener) {
+    listeners.add(listener);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+function told(settings) {
+    held = settings;
+    for (const listener of [...listeners]) {
+        listener(settings);
+    }
+}
+if (typeof window !== 'undefined') {
+    window.addEventListener('storage', event => {
+        if (event.key === VOICE_SETTINGS_KEY || event.key === null) {
+            told(keptVoiceSettings());
+        }
+    });
+}
+/**
+ * Keep what the person chose; an empty choice forgets it. Every chat on the
+ * page is told, so the menu's choice is heard at once (VO-30).
+ */
 export function keepVoiceSettings(settings) {
     const sane = saneVoiceSettings(settings);
     try {
@@ -68,8 +108,31 @@ export function keepVoiceSettings(settings) {
     catch {
         // Without storage the choice holds for the page.
     }
+    told(sane);
     return sane;
 }
+/**
+ * The settings with one choice changed (VO-30): `undefined` forgets that
+ * choice, giving it back to the application. A new language drops a voice
+ * the person chose that does not speak it, for the language's own.
+ */
+export function withVoiceSetting(settings, key, value, speaks) {
+    const next = { ...saneVoiceSettings(settings) };
+    if (value === undefined) {
+        delete next[key];
+    }
+    else {
+        next[key] = value;
+    }
+    if (key === 'language' &&
+        typeof value === 'string' &&
+        next.voice &&
+        speaks &&
+        !speaks(next.voice, value)) {
+        delete next.voice;
+    }
+    return saneVoiceSettings(next);
+}
 /** The language the browser says the person reads, or nothing. */
 export function browserLanguage() {
     try {

package/lib/voice/useVoiceSettings.d.ts

@@ -0,0 +1,6 @@
+import { type VoiceSettings } from './settings';
+/** The person's settings, and a setter that keeps them and tells every chat. */
+export declare function useVoiceSettings(): [
+    VoiceSettings,
+    (settings: VoiceSettings) => void
+];

package/lib/voice/useVoiceSettings.js

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A person's voice settings, as a React state that follows every change —
+ * the composer's menu, a settings page, another tab (VOICE.md VO-30).
+ *
+ * @module voice/useVoiceSettings
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { heldVoiceSettings, keepVoiceSettings, onVoiceSettingsChange, } from './settings';
+/** The person's settings, and a setter that keeps them and tells every chat. */
+export function useVoiceSettings() {
+    const [settings, setSettings] = useState(heldVoiceSettings);
+    useEffect(() => {
+        // A change between the first draw and this subscription is read here.
+        setSettings(heldVoiceSettings());
+        return onVoiceSettingsChange(setSettings);
+    }, []);
+    const keep = useCallback((next) => {
+        keepVoiceSettings(next);
+    }, []);
+    return [settings, keep];
+}