@adea-ai/app-framework 0.47.0 → 0.48.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,354 @@
1
+ /**
2
+ * The shared voice controls: a dictation button for a composer and a read-aloud action for a
3
+ * message. Both talk to a `VoiceClient` and read its capabilities, so an engine that cannot run
4
+ * here shows a disabled control with the reason instead of failing on click.
5
+ */
6
+ import { ActionButton } from '@adea-ai/ui/components/composites/action-button'
7
+ import type { ButtonProps } from '@adea-ai/ui/components/ui/button'
8
+ import { VoiceError, type VoiceRoutingDecision } from '@adea-ai/voice/contract'
9
+ import { Mic, Square, Volume2 } from '@lucide/solid'
10
+ import { createEffect, createSignal, onCleanup, Show, type Accessor } from 'solid-js'
11
+ import type {
12
+ DictationHandle,
13
+ SpeechHandle,
14
+ VoiceCapabilitiesView,
15
+ VoiceClient,
16
+ VoicePlatformKind,
17
+ } from './voice-client'
18
+
19
+ const DESKTOP_ONLY_REASONS = new Set([
20
+ 'unsupportedPlatform',
21
+ 'unsupportedOperatingSystem',
22
+ 'unsupportedDevice',
23
+ 'providerNotRegistered',
24
+ ])
25
+
26
+ /** Why a decision cannot run, in words for a tooltip; undefined when it can. */
27
+ function decisionReason(
28
+ decision: VoiceRoutingDecision,
29
+ platform: VoicePlatformKind,
30
+ desktopOnly: string
31
+ ): string | undefined {
32
+ if (decision.route && decision.availability.status === 'available') return undefined
33
+ if (decision.availability.status === 'available') return desktopOnly
34
+ const { reason, message } = decision.availability.unavailable
35
+ return platform === 'web' && DESKTOP_ONLY_REASONS.has(reason) ? desktopOnly : message
36
+ }
37
+
38
+ /**
39
+ * One capabilities request per client, shared by every control on screen (a read-aloud action
40
+ * on each message must not probe the engines once per message). A settings change drops it.
41
+ */
42
+ const sharedCapabilities = new WeakMap<VoiceClient, Promise<VoiceCapabilitiesView>>()
43
+ const watched = new WeakSet<VoiceClient>()
44
+
45
+ function capabilitiesOf(client: VoiceClient): Promise<VoiceCapabilitiesView> {
46
+ if (!watched.has(client)) {
47
+ watched.add(client)
48
+ client.settings.subscribe(() => sharedCapabilities.delete(client))
49
+ }
50
+ let pending = sharedCapabilities.get(client)
51
+ if (!pending) {
52
+ pending = client.capabilities()
53
+ pending.catch(() => sharedCapabilities.delete(client))
54
+ sharedCapabilities.set(client, pending)
55
+ }
56
+ return pending
57
+ }
58
+
59
+ /** Tracks whether a kind can run with the client's current settings. */
60
+ function createAvailability(
61
+ client: Accessor<VoiceClient | undefined>,
62
+ kind: 'speechToText' | 'textToSpeech',
63
+ desktopOnly: string
64
+ ): Accessor<{ ready: boolean; reason?: string }> {
65
+ const [state, setState] = createSignal<{ ready: boolean; reason?: string }>({ ready: false })
66
+ createEffect(client, (current) => {
67
+ if (!current) {
68
+ setState({ ready: true, reason: desktopOnly })
69
+ return
70
+ }
71
+ let generation = 0
72
+ let alive = true
73
+ const check = () => {
74
+ const mine = ++generation
75
+ capabilitiesOf(current).then(
76
+ (view) => {
77
+ if (!alive || mine !== generation) return
78
+ setState({ ready: true, reason: decisionReason(view[kind], view.platform, desktopOnly) })
79
+ },
80
+ (error: unknown) => {
81
+ if (!alive || mine !== generation) return
82
+ setState({ ready: true, reason: VoiceError.wrapping(error).message })
83
+ }
84
+ )
85
+ }
86
+ check()
87
+ const unsubscribe = current.settings.subscribe(check)
88
+ return () => {
89
+ alive = false
90
+ unsubscribe()
91
+ }
92
+ })
93
+ return state
94
+ }
95
+
96
+ export type DictationState = 'idle' | 'starting' | 'listening' | 'stopping'
97
+
98
+ export type DictationCallbacks = Readonly<{
99
+ /** Every partial (`final` false) and the final text (`final` true). */
100
+ onText?(text: string, final: boolean): void
101
+ /** The final text, when the person chose to send after dictating. */
102
+ onFinal?(text: string): void
103
+ }>
104
+
105
+ export type Dictation = Readonly<{
106
+ state: Accessor<DictationState>
107
+ /** The latest partial, then the final text. */
108
+ partial: Accessor<string>
109
+ /** A short message for the last failure; cleared when a dictation starts. */
110
+ error: Accessor<string | undefined>
111
+ /** Asks for permission when needed, then dictates. Resolves with the final text, if any. */
112
+ start(callbacks?: DictationCallbacks): Promise<string | undefined>
113
+ /** Finishes listening and keeps what was said. */
114
+ stop(): Promise<void>
115
+ /** Stops listening and drops the text, silently. */
116
+ cancel(): Promise<void>
117
+ }>
118
+
119
+ /** The dictation state machine behind `DictationButton`, for apps that draw their own status. */
120
+ export function createDictation(client: VoiceClient | undefined): Dictation {
121
+ const [state, setState] = createSignal<DictationState>('idle')
122
+ const [partial, setPartial] = createSignal('')
123
+ const [error, setError] = createSignal<string>()
124
+ let handle: DictationHandle | undefined
125
+ let cancelled = false
126
+
127
+ const start = async (callbacks: DictationCallbacks = {}) => {
128
+ if (!client || state() !== 'idle') return undefined
129
+ cancelled = false
130
+ setError(undefined)
131
+ setPartial('')
132
+ setState('starting')
133
+ try {
134
+ const permission = await client.permission(false)
135
+ const granted = permission.state === 'prompt' ? await client.permission(true) : permission
136
+ if (granted.state === 'denied') throw new VoiceError('denied')
137
+ if (cancelled) throw new VoiceError('cancelled')
138
+ const started = await client.dictate({
139
+ onPartial: (text) => {
140
+ if (cancelled) return
141
+ setPartial(text)
142
+ callbacks.onText?.(text, false)
143
+ },
144
+ })
145
+ handle = started
146
+ if (cancelled) void started.cancel().catch(() => undefined)
147
+ else setState((current) => (current === 'starting' ? 'listening' : current))
148
+ const text = await started.result
149
+ setPartial(text)
150
+ callbacks.onText?.(text, true)
151
+ if (client.settings.read().settings.dictation.autoSend) callbacks.onFinal?.(text)
152
+ return text
153
+ } catch (failure) {
154
+ const typed = VoiceError.wrapping(failure)
155
+ if (typed.code === 'no_speech') setError("Didn't catch that")
156
+ else if (typed.code !== 'cancelled') setError(typed.message)
157
+ return undefined
158
+ } finally {
159
+ handle = undefined
160
+ setState('idle')
161
+ }
162
+ }
163
+
164
+ const stop = async () => {
165
+ const current = handle
166
+ if (!current || state() !== 'listening') return
167
+ setState('stopping')
168
+ try {
169
+ await current.end()
170
+ } catch (failure) {
171
+ setError(VoiceError.wrapping(failure).message)
172
+ }
173
+ }
174
+
175
+ const cancel = async () => {
176
+ if (state() === 'idle') return
177
+ cancelled = true
178
+ try {
179
+ await handle?.cancel()
180
+ } catch {
181
+ // Cancelling is best effort: the session ends either way.
182
+ }
183
+ }
184
+
185
+ onCleanup(() => void cancel())
186
+ return { state, partial, error, start, stop, cancel }
187
+ }
188
+
189
+ export type DictationButtonProps = {
190
+ client?: VoiceClient
191
+ onText(text: string, final: boolean): void
192
+ onFinal?(text: string): void
193
+ disabled?: boolean
194
+ size?: ButtonProps['size']
195
+ /** Share a dictation made with `createDictation` to draw its status elsewhere. */
196
+ dictation?: Dictation
197
+ }
198
+
199
+ /** A microphone button: click to dictate, click again to finish, Escape to cancel. */
200
+ export function DictationButton(props: DictationButtonProps) {
201
+ const dictation = props.dictation ?? createDictation(props.client)
202
+ const availability = createAvailability(
203
+ () => props.client,
204
+ 'speechToText',
205
+ 'Dictation is available in ADEA Desktop'
206
+ )
207
+ const active = () => dictation.state() !== 'idle'
208
+ const unavailable = () => !active() && availability().reason
209
+ const disabled = () =>
210
+ !active() &&
211
+ (Boolean(props.disabled) || !availability().ready || Boolean(availability().reason))
212
+
213
+ const onKey = (event: KeyboardEvent) => {
214
+ if (event.key !== 'Escape') return
215
+ event.preventDefault()
216
+ void dictation.cancel()
217
+ }
218
+ createEffect(active, (isActive) => {
219
+ if (!isActive) return
220
+ document.addEventListener('keydown', onKey)
221
+ return () => document.removeEventListener('keydown', onKey)
222
+ })
223
+
224
+ const tooltip = () => {
225
+ const state = dictation.state()
226
+ if (state === 'listening') return 'Stop dictation'
227
+ if (state === 'starting') return 'Starting dictation'
228
+ if (state === 'stopping') return 'Finishing dictation'
229
+ return unavailable() || dictation.error() || 'Dictate'
230
+ }
231
+
232
+ const click = () => {
233
+ const state = dictation.state()
234
+ if (state === 'listening') return void dictation.stop()
235
+ if (state !== 'idle') return
236
+ void dictation.start({
237
+ onText: (text, final) => props.onText(text, final),
238
+ onFinal: (text) => props.onFinal?.(text),
239
+ })
240
+ }
241
+
242
+ return (
243
+ <>
244
+ <ActionButton
245
+ type="button"
246
+ variant={dictation.state() === 'listening' ? 'subtle' : 'ghost'}
247
+ size={props.size ?? 'icon-sm'}
248
+ aria-label={dictation.state() === 'listening' ? 'Stop dictation' : 'Dictate'}
249
+ aria-pressed={dictation.state() === 'listening' ? 'true' : 'false'}
250
+ tooltip={tooltip()}
251
+ busy={dictation.state() === 'starting' || dictation.state() === 'stopping'}
252
+ busyLabel={dictation.state() === 'starting' ? 'Starting dictation' : 'Finishing dictation'}
253
+ disabled={disabled()}
254
+ data-state={dictation.state()}
255
+ onClick={click}
256
+ >
257
+ <Show when={dictation.state() === 'listening'} fallback={<Mic aria-hidden="true" />}>
258
+ <Square aria-hidden="true" />
259
+ </Show>
260
+ </ActionButton>
261
+ <span class="sr-only" role="status">
262
+ {dictation.error() ?? ''}
263
+ </span>
264
+ </>
265
+ )
266
+ }
267
+
268
+ /** The read-aloud playing anywhere in the app: starting another one stops it first. */
269
+ let currentReading: { stop(): Promise<void> } | undefined
270
+
271
+ export type ReadAloudButtonProps = {
272
+ client?: VoiceClient
273
+ text: string | (() => string)
274
+ locale?: string
275
+ }
276
+
277
+ /** A message action that reads its text aloud, and stops it on a second click. */
278
+ export function ReadAloudButton(props: ReadAloudButtonProps) {
279
+ const availability = createAvailability(
280
+ () => props.client,
281
+ 'textToSpeech',
282
+ 'Read aloud is available in ADEA Desktop'
283
+ )
284
+ const [speaking, setSpeaking] = createSignal(false)
285
+ const [error, setError] = createSignal<string>()
286
+ let handle: SpeechHandle | undefined
287
+ let mine: { stop(): Promise<void> } | undefined
288
+
289
+ const stop = async () => {
290
+ const current = handle
291
+ setSpeaking(false)
292
+ if (current) await current.cancel().catch(() => undefined)
293
+ }
294
+
295
+ const start = async () => {
296
+ const client = props.client
297
+ const text = (typeof props.text === 'function' ? props.text() : props.text).trim()
298
+ if (!client || !text) return
299
+ setError(undefined)
300
+ const previous = currentReading
301
+ const self = { stop }
302
+ mine = self
303
+ currentReading = self
304
+ setSpeaking(true)
305
+ try {
306
+ if (previous && previous !== self) await previous.stop()
307
+ if (currentReading !== self) return
308
+ const started = await client.speak(text, props.locale ? { locale: props.locale } : {})
309
+ handle = started
310
+ if (currentReading !== self || !speaking()) {
311
+ await started.cancel().catch(() => undefined)
312
+ return
313
+ }
314
+ await started.done
315
+ } catch (failure) {
316
+ const typed = VoiceError.wrapping(failure)
317
+ if (typed.code !== 'cancelled') setError(typed.message)
318
+ } finally {
319
+ if (currentReading === self) currentReading = undefined
320
+ if (mine === self) {
321
+ handle = undefined
322
+ setSpeaking(false)
323
+ }
324
+ }
325
+ }
326
+
327
+ onCleanup(() => {
328
+ if (mine && currentReading === mine) {
329
+ currentReading = undefined
330
+ void mine.stop()
331
+ }
332
+ })
333
+
334
+ const reason = () => availability().reason
335
+ const label = () => (speaking() ? 'Stop reading' : 'Read aloud')
336
+ return (
337
+ <ActionButton
338
+ type="button"
339
+ variant="ghost"
340
+ size="icon-xs"
341
+ data-slot="message-action"
342
+ aria-label={label()}
343
+ aria-pressed={speaking() ? 'true' : 'false'}
344
+ tooltip={speaking() ? label() : (reason() ?? error() ?? label())}
345
+ tooltipSide="bottom"
346
+ disabled={!speaking() && (!availability().ready || Boolean(reason()))}
347
+ onClick={() => void (speaking() ? stop() : start())}
348
+ >
349
+ <Show when={speaking()} fallback={<Volume2 aria-hidden="true" />}>
350
+ <Square aria-hidden="true" />
351
+ </Show>
352
+ </ActionButton>
353
+ )
354
+ }
@@ -0,0 +1,189 @@
1
+ /**
2
+ * The framework's voice service boundary: the names, inputs and events a renderer and a desktop
3
+ * shell exchange, whatever transport carries them (the framework service registry in Cortana,
4
+ * Adea's own command channel). The speech engines, routing, error vocabulary and privacy rules
5
+ * are `@adea-ai/voice`'s; this file only fixes the shape of the conversation and validates every
6
+ * value that crosses it.
7
+ */
8
+ import { VoiceError, type VoiceErrorCode } from '@adea-ai/voice/contract'
9
+ import { validateVoiceSettings, type VoiceSettings } from '@adea-ai/voice/settings'
10
+
11
+ export const VOICE_SERVICES = {
12
+ capabilities: 'voice.capabilities',
13
+ permission: 'voice.permission',
14
+ dictateStart: 'voice.dictate-start',
15
+ dictateEnd: 'voice.dictate-end',
16
+ dictateCancel: 'voice.dictate-cancel',
17
+ speak: 'voice.speak',
18
+ speakStop: 'voice.speak-stop',
19
+ voices: 'voice.voices',
20
+ locales: 'voice.locales',
21
+ installAssets: 'voice.install-assets',
22
+ installCancel: 'voice.install-cancel',
23
+ releaseAssets: 'voice.release-assets',
24
+ events: 'voice.events',
25
+ } as const
26
+ export type VoiceServiceName = (typeof VOICE_SERVICES)[keyof typeof VOICE_SERVICES]
27
+
28
+ /** The system voice reading an utterance aloud, as the helper resolved it. */
29
+ export type VoiceSpeechVoice = Readonly<{
30
+ /** The voice identifier (what the settings' `tts.voice` can pin). */
31
+ id: string
32
+ name: string
33
+ /** The voice's own locale, e.g. `es-MX` when `es-419` was asked for. */
34
+ language: string
35
+ /** The same value as `language`, as the voice list items name it (helpers after 0.3.0). */
36
+ locale?: string
37
+ quality: 'default' | 'enhanced' | 'premium' | 'unknown'
38
+ }>
39
+
40
+ /** Pushed from the shell to the renderer through `voice.events` (a long poll with a cursor). */
41
+ export type VoiceEvent =
42
+ | { readonly type: 'dictation-partial'; readonly id: string; readonly text: string }
43
+ | { readonly type: 'dictation-final'; readonly id: string; readonly text: string }
44
+ | {
45
+ readonly type: 'dictation-failed'
46
+ readonly id: string
47
+ readonly code: VoiceErrorCode
48
+ readonly message: string
49
+ }
50
+ | { readonly type: 'dictation-cancelled'; readonly id: string }
51
+ | {
52
+ readonly type: 'speech-started'
53
+ readonly id: string
54
+ /** The voice speaking, when the helper reports it (helpers after 0.2.0). */
55
+ readonly voice?: VoiceSpeechVoice
56
+ }
57
+ | { readonly type: 'speech-finished'; readonly id: string }
58
+ | { readonly type: 'speech-cancelled'; readonly id: string }
59
+ | {
60
+ readonly type: 'speech-failed'
61
+ readonly id: string
62
+ readonly code: VoiceErrorCode
63
+ readonly message: string
64
+ }
65
+ | { readonly type: 'install-progress'; readonly id: string; readonly fraction: number | null }
66
+ | { readonly type: 'install-finished'; readonly id: string }
67
+ | {
68
+ readonly type: 'install-failed'
69
+ readonly id: string
70
+ readonly code: VoiceErrorCode
71
+ readonly message: string
72
+ }
73
+
74
+ export type VoiceEventBatch = Readonly<{ cursor: number; events: readonly VoiceEvent[] }>
75
+
76
+ /** Largest text one read-aloud request may carry (about 30 minutes of speech). */
77
+ export const MAX_SPEAK_CHARACTERS = 20_000
78
+ /** A long poll returns after this long with no events, so a transport never idles out. */
79
+ export const EVENTS_WAIT_MS = 25_000
80
+
81
+ /** Malformed input is the caller's mistake: a typed `bad_request`, never a bare failure. */
82
+ const bad = (message: string) => new VoiceError('bad_request', message)
83
+
84
+ const isRecord = (value: unknown): value is Record<string, unknown> =>
85
+ value !== null && typeof value === 'object' && !Array.isArray(value)
86
+
87
+ function onlyKeys(value: Record<string, unknown>, allowed: readonly string[]): void {
88
+ for (const key of Object.keys(value))
89
+ if (!allowed.includes(key)) throw bad(`Unexpected field ${key}`)
90
+ }
91
+
92
+ function optionalLocale(value: unknown): string | undefined {
93
+ if (value === undefined) return undefined
94
+ if (typeof value !== 'string' || value.length === 0 || value.length > 64)
95
+ throw bad('Invalid locale')
96
+ const [canonical] = Intl.getCanonicalLocales(value)
97
+ if (!canonical) throw bad('Invalid locale')
98
+ return canonical
99
+ }
100
+
101
+ /** Settings always cross the boundary whole and are re-validated on the shell side. */
102
+ function settings(value: unknown): VoiceSettings {
103
+ const read = validateVoiceSettings(value)
104
+ if (read.issues.length > 0) throw bad(`Invalid voice settings: ${read.issues.join('; ')}`)
105
+ return read.settings
106
+ }
107
+
108
+ const id = (value: unknown): string => {
109
+ if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) throw bad('Invalid id')
110
+ return value
111
+ }
112
+
113
+ export const parseVoiceInput = {
114
+ capabilities(value: unknown): { settings: VoiceSettings; locale?: string } {
115
+ if (!isRecord(value)) throw bad('Invalid request')
116
+ onlyKeys(value, ['settings', 'locale'])
117
+ const locale = optionalLocale(value.locale)
118
+ return { settings: settings(value.settings), ...(locale ? { locale } : {}) }
119
+ },
120
+ permission(value: unknown): { request: boolean } {
121
+ if (!isRecord(value)) throw bad('Invalid request')
122
+ onlyKeys(value, ['request'])
123
+ if (value.request !== undefined && typeof value.request !== 'boolean')
124
+ throw bad('Invalid request')
125
+ return { request: value.request === true }
126
+ },
127
+ dictateStart(value: unknown): { settings: VoiceSettings; locale?: string } {
128
+ return parseVoiceInput.capabilities(value)
129
+ },
130
+ dictation(value: unknown): { id: string } {
131
+ if (!isRecord(value)) throw bad('Invalid request')
132
+ onlyKeys(value, ['id'])
133
+ return { id: id(value.id) }
134
+ },
135
+ speak(value: unknown): {
136
+ settings: VoiceSettings
137
+ text: string
138
+ locale?: string
139
+ queue: 'replace' | 'after-current'
140
+ } {
141
+ if (!isRecord(value)) throw bad('Invalid request')
142
+ onlyKeys(value, ['settings', 'text', 'locale', 'queue'])
143
+ if (
144
+ typeof value.text !== 'string' ||
145
+ value.text.trim().length === 0 ||
146
+ value.text.length > MAX_SPEAK_CHARACTERS
147
+ )
148
+ throw bad('Invalid text')
149
+ if (value.queue !== undefined && value.queue !== 'replace' && value.queue !== 'after-current')
150
+ throw bad('Invalid queue')
151
+ const locale = optionalLocale(value.locale)
152
+ return {
153
+ settings: settings(value.settings),
154
+ text: value.text,
155
+ ...(locale ? { locale } : {}),
156
+ queue: (value.queue as 'replace' | 'after-current' | undefined) ?? 'replace',
157
+ }
158
+ },
159
+ none(value: unknown): null {
160
+ if (
161
+ value !== null &&
162
+ value !== undefined &&
163
+ !(isRecord(value) && Object.keys(value).length === 0)
164
+ )
165
+ throw bad('Invalid request')
166
+ return null
167
+ },
168
+ voices(value: unknown): { settings: VoiceSettings; locale?: string } {
169
+ return parseVoiceInput.capabilities(value)
170
+ },
171
+ installAssets(value: unknown): { locale: string } {
172
+ if (!isRecord(value)) throw bad('Invalid request')
173
+ onlyKeys(value, ['locale'])
174
+ const locale = optionalLocale(value.locale)
175
+ if (!locale) throw bad('Invalid locale')
176
+ return { locale }
177
+ },
178
+ /** Removing a model names one locale, like an install. */
179
+ releaseAssets(value: unknown): { locale: string } {
180
+ return parseVoiceInput.installAssets(value)
181
+ },
182
+ events(value: unknown): { after: number } {
183
+ if (!isRecord(value)) throw bad('Invalid request')
184
+ onlyKeys(value, ['after'])
185
+ if (!Number.isSafeInteger(value.after) || (value.after as number) < 0)
186
+ throw bad('Invalid cursor')
187
+ return { after: value.after as number }
188
+ },
189
+ }