@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,313 @@
1
+ import { createComponent, insert, memo, template } from "@solidjs/web";
2
+ import { createEffect, createSignal, onCleanup } from "solid-js";
3
+ import { ActionButton } from "@adea-ai/ui/components/composites/action-button";
4
+ import { Mic, Square, Volume2 } from "@lucide/solid";
5
+ import { VoiceError } from "@adea-ai/voice/contract";
6
+ // src/voice/voice-controls.tsx
7
+ /**
8
+ * The shared voice controls: a dictation button for a composer and a read-aloud action for a
9
+ * message. Both talk to a `VoiceClient` and read its capabilities, so an engine that cannot run
10
+ * here shows a disabled control with the reason instead of failing on click.
11
+ */
12
+ var _tmpl$ = /* @__PURE__ */ template(`<span class=sr-only role=status>`);
13
+ var DESKTOP_ONLY_REASONS = /* @__PURE__ */ new Set([
14
+ "unsupportedPlatform",
15
+ "unsupportedOperatingSystem",
16
+ "unsupportedDevice",
17
+ "providerNotRegistered"
18
+ ]);
19
+ /** Why a decision cannot run, in words for a tooltip; undefined when it can. */
20
+ function decisionReason(decision, platform, desktopOnly) {
21
+ if (decision.route && decision.availability.status === "available") return void 0;
22
+ if (decision.availability.status === "available") return desktopOnly;
23
+ const { reason, message } = decision.availability.unavailable;
24
+ return platform === "web" && DESKTOP_ONLY_REASONS.has(reason) ? desktopOnly : message;
25
+ }
26
+ /**
27
+ * One capabilities request per client, shared by every control on screen (a read-aloud action
28
+ * on each message must not probe the engines once per message). A settings change drops it.
29
+ */
30
+ var sharedCapabilities = /* @__PURE__ */ new WeakMap();
31
+ var watched = /* @__PURE__ */ new WeakSet();
32
+ function capabilitiesOf(client) {
33
+ if (!watched.has(client)) {
34
+ watched.add(client);
35
+ client.settings.subscribe(() => sharedCapabilities.delete(client));
36
+ }
37
+ let pending = sharedCapabilities.get(client);
38
+ if (!pending) {
39
+ pending = client.capabilities();
40
+ pending.catch(() => sharedCapabilities.delete(client));
41
+ sharedCapabilities.set(client, pending);
42
+ }
43
+ return pending;
44
+ }
45
+ /** Tracks whether a kind can run with the client's current settings. */
46
+ function createAvailability(client, kind, desktopOnly) {
47
+ const [state, setState] = createSignal({ ready: false });
48
+ createEffect(client, (current) => {
49
+ if (!current) {
50
+ setState({
51
+ ready: true,
52
+ reason: desktopOnly
53
+ });
54
+ return;
55
+ }
56
+ let generation = 0;
57
+ let alive = true;
58
+ const check = () => {
59
+ const mine = ++generation;
60
+ capabilitiesOf(current).then((view) => {
61
+ if (!alive || mine !== generation) return;
62
+ setState({
63
+ ready: true,
64
+ reason: decisionReason(view[kind], view.platform, desktopOnly)
65
+ });
66
+ }, (error) => {
67
+ if (!alive || mine !== generation) return;
68
+ setState({
69
+ ready: true,
70
+ reason: VoiceError.wrapping(error).message
71
+ });
72
+ });
73
+ };
74
+ check();
75
+ const unsubscribe = current.settings.subscribe(check);
76
+ return () => {
77
+ alive = false;
78
+ unsubscribe();
79
+ };
80
+ });
81
+ return state;
82
+ }
83
+ /** The dictation state machine behind `DictationButton`, for apps that draw their own status. */
84
+ function createDictation(client) {
85
+ const [state, setState] = createSignal("idle");
86
+ const [partial, setPartial] = createSignal("");
87
+ const [error, setError] = createSignal();
88
+ let handle;
89
+ let cancelled = false;
90
+ const start = async (callbacks = {}) => {
91
+ if (!client || state() !== "idle") return void 0;
92
+ cancelled = false;
93
+ setError(void 0);
94
+ setPartial("");
95
+ setState("starting");
96
+ try {
97
+ const permission = await client.permission(false);
98
+ if ((permission.state === "prompt" ? await client.permission(true) : permission).state === "denied") throw new VoiceError("denied");
99
+ if (cancelled) throw new VoiceError("cancelled");
100
+ const started = await client.dictate({ onPartial: (text) => {
101
+ if (cancelled) return;
102
+ setPartial(text);
103
+ callbacks.onText?.(text, false);
104
+ } });
105
+ handle = started;
106
+ if (cancelled) started.cancel().catch(() => void 0);
107
+ else setState((current) => current === "starting" ? "listening" : current);
108
+ const text = await started.result;
109
+ setPartial(text);
110
+ callbacks.onText?.(text, true);
111
+ if (client.settings.read().settings.dictation.autoSend) callbacks.onFinal?.(text);
112
+ return text;
113
+ } catch (failure) {
114
+ const typed = VoiceError.wrapping(failure);
115
+ if (typed.code === "no_speech") setError("Didn't catch that");
116
+ else if (typed.code !== "cancelled") setError(typed.message);
117
+ return;
118
+ } finally {
119
+ handle = void 0;
120
+ setState("idle");
121
+ }
122
+ };
123
+ const stop = async () => {
124
+ const current = handle;
125
+ if (!current || state() !== "listening") return;
126
+ setState("stopping");
127
+ try {
128
+ await current.end();
129
+ } catch (failure) {
130
+ setError(VoiceError.wrapping(failure).message);
131
+ }
132
+ };
133
+ const cancel = async () => {
134
+ if (state() === "idle") return;
135
+ cancelled = true;
136
+ try {
137
+ await handle?.cancel();
138
+ } catch {}
139
+ };
140
+ onCleanup(() => void cancel());
141
+ return {
142
+ state,
143
+ partial,
144
+ error,
145
+ start,
146
+ stop,
147
+ cancel
148
+ };
149
+ }
150
+ /** A microphone button: click to dictate, click again to finish, Escape to cancel. */
151
+ function DictationButton(props) {
152
+ const dictation = props.dictation ?? createDictation(props.client);
153
+ const availability = createAvailability(() => props.client, "speechToText", "Dictation is available in ADEA Desktop");
154
+ const active = () => dictation.state() !== "idle";
155
+ const unavailable = () => !active() && availability().reason;
156
+ const disabled = () => !active() && (Boolean(props.disabled) || !availability().ready || Boolean(availability().reason));
157
+ const onKey = (event) => {
158
+ if (event.key !== "Escape") return;
159
+ event.preventDefault();
160
+ dictation.cancel();
161
+ };
162
+ createEffect(active, (isActive) => {
163
+ if (!isActive) return;
164
+ document.addEventListener("keydown", onKey);
165
+ return () => document.removeEventListener("keydown", onKey);
166
+ });
167
+ const tooltip = () => {
168
+ const state = dictation.state();
169
+ if (state === "listening") return "Stop dictation";
170
+ if (state === "starting") return "Starting dictation";
171
+ if (state === "stopping") return "Finishing dictation";
172
+ return unavailable() || dictation.error() || "Dictate";
173
+ };
174
+ const click = () => {
175
+ const state = dictation.state();
176
+ if (state === "listening") return void dictation.stop();
177
+ if (state !== "idle") return;
178
+ dictation.start({
179
+ onText: (text, final) => props.onText(text, final),
180
+ onFinal: (text) => props.onFinal?.(text)
181
+ });
182
+ };
183
+ return [createComponent(ActionButton, {
184
+ type: "button",
185
+ get variant() {
186
+ return dictation.state() === "listening" ? "subtle" : "ghost";
187
+ },
188
+ get size() {
189
+ return props.size ?? "icon-sm";
190
+ },
191
+ get "aria-label"() {
192
+ return dictation.state() === "listening" ? "Stop dictation" : "Dictate";
193
+ },
194
+ get "aria-pressed"() {
195
+ return dictation.state() === "listening" ? "true" : "false";
196
+ },
197
+ get tooltip() {
198
+ return tooltip();
199
+ },
200
+ get busy() {
201
+ return dictation.state() === "starting" || dictation.state() === "stopping";
202
+ },
203
+ get busyLabel() {
204
+ return dictation.state() === "starting" ? "Starting dictation" : "Finishing dictation";
205
+ },
206
+ get disabled() {
207
+ return disabled();
208
+ },
209
+ get "data-state"() {
210
+ return dictation.state();
211
+ },
212
+ onClick: click,
213
+ get children() {
214
+ return memo(() => {
215
+ return memo(() => {
216
+ return dictation.state() === "listening";
217
+ })() ? createComponent(Square, { "aria-hidden": "true" }) : createComponent(Mic, { "aria-hidden": "true" });
218
+ });
219
+ }
220
+ }), (() => {
221
+ var _el$ = _tmpl$();
222
+ insert(_el$, () => {
223
+ return dictation.error() ?? "";
224
+ });
225
+ return _el$;
226
+ })()];
227
+ }
228
+ /** The read-aloud playing anywhere in the app: starting another one stops it first. */
229
+ var currentReading;
230
+ /** A message action that reads its text aloud, and stops it on a second click. */
231
+ function ReadAloudButton(props) {
232
+ const availability = createAvailability(() => props.client, "textToSpeech", "Read aloud is available in ADEA Desktop");
233
+ const [speaking, setSpeaking] = createSignal(false);
234
+ const [error, setError] = createSignal();
235
+ let handle;
236
+ let mine;
237
+ const stop = async () => {
238
+ const current = handle;
239
+ setSpeaking(false);
240
+ if (current) await current.cancel().catch(() => void 0);
241
+ };
242
+ const start = async () => {
243
+ const client = props.client;
244
+ const text = (typeof props.text === "function" ? props.text() : props.text).trim();
245
+ if (!client || !text) return;
246
+ setError(void 0);
247
+ const previous = currentReading;
248
+ const self = { stop };
249
+ mine = self;
250
+ currentReading = self;
251
+ setSpeaking(true);
252
+ try {
253
+ if (previous && previous !== self) await previous.stop();
254
+ if (currentReading !== self) return;
255
+ const started = await client.speak(text, props.locale ? { locale: props.locale } : {});
256
+ handle = started;
257
+ if (currentReading !== self || !speaking()) {
258
+ await started.cancel().catch(() => void 0);
259
+ return;
260
+ }
261
+ await started.done;
262
+ } catch (failure) {
263
+ const typed = VoiceError.wrapping(failure);
264
+ if (typed.code !== "cancelled") setError(typed.message);
265
+ } finally {
266
+ if (currentReading === self) currentReading = void 0;
267
+ if (mine === self) {
268
+ handle = void 0;
269
+ setSpeaking(false);
270
+ }
271
+ }
272
+ };
273
+ onCleanup(() => {
274
+ if (mine && currentReading === mine) {
275
+ currentReading = void 0;
276
+ mine.stop();
277
+ }
278
+ });
279
+ const reason = () => availability().reason;
280
+ const label = () => speaking() ? "Stop reading" : "Read aloud";
281
+ return createComponent(ActionButton, {
282
+ type: "button",
283
+ variant: "ghost",
284
+ size: "icon-xs",
285
+ "data-slot": "message-action",
286
+ get "aria-label"() {
287
+ return label();
288
+ },
289
+ get "aria-pressed"() {
290
+ return speaking() ? "true" : "false";
291
+ },
292
+ get tooltip() {
293
+ return memo(() => {
294
+ return !!speaking();
295
+ })() ? label() : reason() ?? error() ?? label();
296
+ },
297
+ tooltipSide: "bottom",
298
+ get disabled() {
299
+ return memo(() => {
300
+ return !speaking();
301
+ })() && (!availability().ready || Boolean(reason()));
302
+ },
303
+ onClick: () => void (speaking() ? stop() : start()),
304
+ get children() {
305
+ return memo(() => {
306
+ return memo(() => {
307
+ return !!speaking();
308
+ })() ? createComponent(Square, { "aria-hidden": "true" }) : createComponent(Volume2, { "aria-hidden": "true" });
309
+ });
310
+ }
311
+ });
312
+ }
313
+ export { DictationButton, ReadAloudButton, createDictation };
@@ -0,0 +1,29 @@
1
+ import { type DesktopHelperPaths, type DesktopVoice, type DesktopVoiceOptions } from '@adea-ai/voice/desktop';
2
+ import { type createServiceRegistry } from '../app/service-registry';
3
+ import { type VoiceServiceName } from './voice-protocol';
4
+ export type VoiceHostOptions = Readonly<{
5
+ helpers: DesktopHelperPaths;
6
+ log?: (message: string) => void;
7
+ /** Test seam: a prepared client instead of one spawning the helpers. */
8
+ voice?: DesktopVoice;
9
+ spawn?: DesktopVoiceOptions['spawn'];
10
+ }>;
11
+ export type VoiceHost = Readonly<{
12
+ /** Runs one voice service. Throws `ServiceError` with a `VoiceErrorCode` on a typed failure. */
13
+ handle(name: VoiceServiceName, input: unknown): Promise<unknown>;
14
+ /** Whether a name is one of the voice services. */
15
+ handles(name: string): name is VoiceServiceName;
16
+ /** Which helpers this build bundles (for a status line without starting a process). */
17
+ bundled(): ReturnType<DesktopVoice['bundled']>;
18
+ dispose(): Promise<void>;
19
+ }>;
20
+ export declare function createVoiceHost(options: VoiceHostOptions): VoiceHost;
21
+ /**
22
+ * Registers every voice service in a framework service registry. `authorize` is the host's
23
+ * principal policy (the app window only, for example). Returns an unregister function.
24
+ */
25
+ export declare function registerVoiceServices<Principal>(options: {
26
+ services: ReturnType<typeof createServiceRegistry<Principal>>;
27
+ host: VoiceHost;
28
+ authorize(principal: Principal, service: VoiceServiceName): boolean | Promise<boolean>;
29
+ }): () => void;
@@ -0,0 +1,248 @@
1
+ import { ServiceError } from "../app/service-registry.js";
2
+ import { EVENTS_WAIT_MS, VOICE_SERVICES, parseVoiceInput } from "./voice-protocol.js";
3
+ import { createDesktopVoice } from "@adea-ai/voice/desktop";
4
+ import { VoiceError } from "@adea-ai/voice/contract";
5
+ // src/voice/voice-host.ts
6
+ /**
7
+ * The desktop shell's voice service: `@adea-ai/voice/desktop` behind the framework's voice
8
+ * protocol. One instance per shell process. It holds at most one dictation, the running
9
+ * read-aloud utterances and asset installs, and a bounded event log the renderer reads with the
10
+ * `voice.events` long poll, so any request/response transport can carry live partials.
11
+ *
12
+ * `registerVoiceServices` wires it into the framework service registry (Cortana). A shell with
13
+ * its own command channel (Adea) calls `host.handle(name, input)` from that channel instead.
14
+ */
15
+ /** Events kept for a renderer that reconnects; older ones are dropped (the cursor jumps). */
16
+ var EVENT_LOG_LIMIT = 512;
17
+ function typed(error) {
18
+ const voiceError = VoiceError.wrapping(error);
19
+ return new ServiceError(voiceError.code, voiceError.message);
20
+ }
21
+ async function run(body) {
22
+ try {
23
+ return await body();
24
+ } catch (error) {
25
+ if (error instanceof ServiceError) throw error;
26
+ throw typed(error);
27
+ }
28
+ }
29
+ function createVoiceHost(options) {
30
+ const voice = options.voice ?? createDesktopVoice({
31
+ helpers: options.helpers,
32
+ ...options.log ? { log: options.log } : {},
33
+ ...options.spawn ? { spawn: options.spawn } : {}
34
+ });
35
+ const log = [];
36
+ let cursor = 0;
37
+ let waiters = [];
38
+ let dictation;
39
+ const speeches = /* @__PURE__ */ new Map();
40
+ const installs = /* @__PURE__ */ new Map();
41
+ let counter = 0;
42
+ const nextId = (prefix) => `${prefix}${(++counter).toString(36)}`;
43
+ const emit = (event) => {
44
+ log.push(event);
45
+ cursor++;
46
+ if (log.length > EVENT_LOG_LIMIT) log.splice(0, log.length - EVENT_LOG_LIMIT);
47
+ const ready = waiters;
48
+ waiters = [];
49
+ for (const wake of ready) wake();
50
+ };
51
+ const services = {
52
+ [VOICE_SERVICES.capabilities]: (input) => run(async () => {
53
+ const { settings, locale } = parseVoiceInput.capabilities(input);
54
+ return await voice.capabilities(settings, locale);
55
+ }),
56
+ [VOICE_SERVICES.permission]: (input) => run(async () => voice.permission({ request: parseVoiceInput.permission(input).request })),
57
+ [VOICE_SERVICES.dictateStart]: (input) => run(async () => {
58
+ const { settings, locale } = parseVoiceInput.dictateStart(input);
59
+ if (dictation) throw new ServiceError("busy", "A dictation is already running.");
60
+ const id = nextId("d");
61
+ const session = await voice.listen({
62
+ settings,
63
+ ...locale ? { locale } : {},
64
+ onPartial: (partial) => emit({
65
+ type: "dictation-partial",
66
+ id,
67
+ text: partial.text
68
+ })
69
+ });
70
+ dictation = {
71
+ id,
72
+ session
73
+ };
74
+ session.result.then((text) => emit({
75
+ type: "dictation-final",
76
+ id,
77
+ text
78
+ }), (error) => {
79
+ const voiceError = VoiceError.wrapping(error);
80
+ emit(voiceError.code === "cancelled" ? {
81
+ type: "dictation-cancelled",
82
+ id
83
+ } : {
84
+ type: "dictation-failed",
85
+ id,
86
+ code: voiceError.code,
87
+ message: voiceError.message
88
+ });
89
+ }).finally(() => {
90
+ if (dictation?.id === id) dictation = void 0;
91
+ });
92
+ return {
93
+ id,
94
+ provider: session.provider,
95
+ locale: session.locale
96
+ };
97
+ }),
98
+ [VOICE_SERVICES.dictateEnd]: (input) => run(async () => {
99
+ const { id } = parseVoiceInput.dictation(input);
100
+ if (dictation?.id === id) await dictation.session.end();
101
+ return null;
102
+ }),
103
+ [VOICE_SERVICES.dictateCancel]: (input) => run(async () => {
104
+ const { id } = parseVoiceInput.dictation(input);
105
+ if (dictation?.id === id) await dictation.session.cancel();
106
+ return null;
107
+ }),
108
+ [VOICE_SERVICES.speak]: (input) => run(async () => {
109
+ const { settings, text, locale, queue } = parseVoiceInput.speak(input);
110
+ const speech = await voice.speak({
111
+ settings,
112
+ text,
113
+ ...locale ? { locale } : {},
114
+ queue
115
+ });
116
+ speeches.set(speech.id, speech);
117
+ speech.started.then((start) => {
118
+ if (start) emit({
119
+ type: "speech-started",
120
+ id: speech.id,
121
+ ...start.voice ? { voice: start.voice } : {}
122
+ });
123
+ });
124
+ speech.done.then((outcome) => emit({
125
+ type: outcome === "finished" ? "speech-finished" : "speech-cancelled",
126
+ id: speech.id
127
+ }), (error) => {
128
+ const voiceError = VoiceError.wrapping(error);
129
+ emit({
130
+ type: "speech-failed",
131
+ id: speech.id,
132
+ code: voiceError.code,
133
+ message: voiceError.message
134
+ });
135
+ }).finally(() => speeches.delete(speech.id));
136
+ return {
137
+ id: speech.id,
138
+ provider: speech.provider
139
+ };
140
+ }),
141
+ [VOICE_SERVICES.speakStop]: (input) => run(async () => {
142
+ parseVoiceInput.none(input);
143
+ await voice.stopSpeaking();
144
+ return null;
145
+ }),
146
+ [VOICE_SERVICES.voices]: (input) => run(async () => {
147
+ const { settings, locale } = parseVoiceInput.voices(input);
148
+ return { voices: await voice.voices(settings, locale) };
149
+ }),
150
+ [VOICE_SERVICES.locales]: (input) => run(async () => {
151
+ parseVoiceInput.none(input);
152
+ return { locales: await voice.locales() };
153
+ }),
154
+ [VOICE_SERVICES.installAssets]: (input) => run(async () => {
155
+ const { locale } = parseVoiceInput.installAssets(input);
156
+ const id = nextId("i");
157
+ const controller = new AbortController();
158
+ installs.set(id, controller);
159
+ voice.installAssets({
160
+ locale,
161
+ signal: controller.signal,
162
+ onProgress: (fraction) => emit({
163
+ type: "install-progress",
164
+ id,
165
+ fraction
166
+ })
167
+ }).then(() => emit({
168
+ type: "install-finished",
169
+ id
170
+ }), (error) => {
171
+ const voiceError = VoiceError.wrapping(error);
172
+ emit({
173
+ type: "install-failed",
174
+ id,
175
+ code: voiceError.code,
176
+ message: voiceError.message
177
+ });
178
+ }).finally(() => installs.delete(id));
179
+ return { id };
180
+ }),
181
+ [VOICE_SERVICES.installCancel]: (input) => run(async () => {
182
+ const { id } = parseVoiceInput.dictation(input);
183
+ installs.get(id)?.abort();
184
+ return null;
185
+ }),
186
+ [VOICE_SERVICES.releaseAssets]: (input) => run(async () => {
187
+ const { locale } = parseVoiceInput.releaseAssets(input);
188
+ return await voice.releaseAssets({ locale });
189
+ }),
190
+ [VOICE_SERVICES.events]: (input) => run(async () => {
191
+ const { after } = parseVoiceInput.events(input);
192
+ if (after === cursor) await new Promise((resolve) => {
193
+ const timer = setTimeout(() => {
194
+ waiters = waiters.filter((waiter) => waiter !== wake);
195
+ resolve();
196
+ }, EVENTS_WAIT_MS);
197
+ const wake = () => {
198
+ clearTimeout(timer);
199
+ resolve();
200
+ };
201
+ waiters.push(wake);
202
+ });
203
+ const first = cursor - log.length;
204
+ const from = after > cursor ? first : Math.max(after, first);
205
+ return {
206
+ cursor,
207
+ events: log.slice(from - first)
208
+ };
209
+ })
210
+ };
211
+ const names = new Set(Object.values(VOICE_SERVICES));
212
+ return {
213
+ handle: (name, input) => {
214
+ const service = services[name];
215
+ if (!service) return Promise.reject(new ServiceError("bad_request", `Unknown voice service ${name}`));
216
+ return service(input);
217
+ },
218
+ handles: (name) => names.has(name),
219
+ bundled: () => voice.bundled(),
220
+ async dispose() {
221
+ for (const controller of installs.values()) controller.abort();
222
+ for (const wake of waiters.splice(0)) wake();
223
+ await voice.dispose();
224
+ }
225
+ };
226
+ }
227
+ /**
228
+ * Registers every voice service in a framework service registry. `authorize` is the host's
229
+ * principal policy (the app window only, for example). Returns an unregister function.
230
+ */
231
+ function registerVoiceServices(options) {
232
+ const removers = [];
233
+ try {
234
+ for (const name of Object.values(VOICE_SERVICES)) removers.push(options.services.register(name, {
235
+ parse: (value) => value,
236
+ authorize: (principal) => options.authorize(principal, name),
237
+ run: (_principal, input) => options.host.handle(name, input),
238
+ maxBodyBytes: 524288
239
+ }));
240
+ } catch (error) {
241
+ for (const remove of removers.splice(0)) remove();
242
+ throw error;
243
+ }
244
+ return () => {
245
+ for (const remove of removers.splice(0)) remove();
246
+ };
247
+ }
248
+ export { createVoiceHost, registerVoiceServices };