@fusion.dev/helix-core 0.221.0 → 0.223.0

package/dist/index.d.ts

@@ -159,7 +159,7 @@ export { slotFilled, slotNamed } from './utils/slot-filled/slot-filled.js';
 export { SlottedGlyph } from './utils/slotted-glyph/slotted-glyph.js';
 export { slottedWords } from './utils/slotted-words/slotted-words.js';
 export { ChartSound, HIGH, LOW, panOf, pitchOf, type Sound, type SoundSeries, sweepPlan, TIMBRES, } from './utils/sonify/sonify.js';
-export { browserSpeech, pageSpeechEngine, registerSpeechEngine, type SpeechEngine, type SpeechListener, type SpeechSession, } from './utils/speech/speech.js';
+export { browserSpeech, pageSpeechEngine, recognizeSpeech, registerSpeechEngine, type SpeechEngine, type SpeechListener, type SpeechSession, } from './utils/speech/speech.js';
 export { splitValues } from './utils/split-values/split-values.js';
 export { captureState, type ElementState, elementAt, exposeState, type PageState, pathOf, type RestoreReport, restoreOn, restoreState, STATE_SLOT, snapshotOf, } from './utils/state/state.js';
 export { stopPress } from './utils/stop-press/stop-press.js';

package/dist/index.js

@@ -159,7 +159,7 @@ export { slotFilled, slotNamed } from './utils/slot-filled/slot-filled.js';
 export { SlottedGlyph } from './utils/slotted-glyph/slotted-glyph.js';
 export { slottedWords } from './utils/slotted-words/slotted-words.js';
 export { ChartSound, HIGH, LOW, panOf, pitchOf, sweepPlan, TIMBRES, } from './utils/sonify/sonify.js';
-export { browserSpeech, pageSpeechEngine, registerSpeechEngine, } from './utils/speech/speech.js';
+export { browserSpeech, pageSpeechEngine, recognizeSpeech, registerSpeechEngine, } from './utils/speech/speech.js';
 export { splitValues } from './utils/split-values/split-values.js';
 export { captureState, elementAt, exposeState, pathOf, restoreOn, restoreState, STATE_SLOT, snapshotOf, } from './utils/state/state.js';
 export { stopPress } from './utils/stop-press/stop-press.js';

package/dist/mixins/mixin-voice/mixin-voice.d.ts

@@ -3,6 +3,9 @@ import type { HelixElement } from '../../helix-element/helix-element.js';
 import { type SpeechEngine } from '../../utils/speech/speech.js';
 type Constructor<T> = new (...args: any[]) => T;
 export declare class VoiceElement {
+    dictationDeniedLabel: string;
+    dictationFailedLabel: string;
+    dictationUnreachableLabel: string;
     /** Whether the field is listening now. */
     readonly listening: boolean;
     listeningLabel: string;
@@ -17,6 +20,8 @@ export declare class VoiceElement {
     stopListening(): void;
     /** The dictation button and its status, behind a seam a tier can move. */
     protected renderVoice(): TemplateResult | typeof nothing;
+    /** What the dictation button draws: the microphone, or a level meter while listening. */
+    protected renderVoiceGlyph(): TemplateResult;
     /** The native field dictation types into. */
     protected voiceField(): HTMLInputElement | HTMLTextAreaElement | null;
     /** The type of the field dictation types into. Dictation listens only in `text`, `search`, `tel` and `url`. */

package/dist/mixins/mixin-voice/mixin-voice.js

@@ -1,7 +1,8 @@
 import { __decorate } from "tslib";
 import { microphone } from '@fusion.dev/helix-icons';
-import { html, nothing } from 'lit';
+import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { html } from 'lit/static-html.js';
 import { HelixBeforeListenEvent, HelixListenEvent } from '../../events/events.js';
 import { drawIcon } from '../../utils/draw-icon/draw-icon.js';
 import { pageSpeechEngine, } from '../../utils/speech/speech.js';
@@ -14,6 +15,9 @@ export const MixinVoice = (Base) => {
     class Voice extends Base {
         constructor() {
             super(...arguments);
+            this.dictationDeniedLabel = 'Dictation needs the microphone';
+            this.dictationFailedLabel = 'Dictation stopped with an error';
+            this.dictationUnreachableLabel = 'Dictation could not reach the speech service';
             this.listeningLabel = 'Listening';
             this.speechEngine = undefined;
             this.stoppedListeningLabel = 'Stopped listening';
@@ -89,35 +93,66 @@ export const MixinVoice = (Base) => {
             this.toggleState('listening', true);
             field.addEventListener('keydown', this.handleVoiceKey);
             field.addEventListener('pointerdown', this.handleVoicePointer);
-            this.session = this.engine.listen({
-                lang: wordsLocale(this),
-                listener: {
-                    end: () => this.ended(),
-                    final: (text) => this.place(text, true),
-                    level: (level) => {
-                        this.style.setProperty('--dictation-level', level.toFixed(3));
+            let session;
+            try {
+                session = this.engine.listen({
+                    lang: wordsLocale(this),
+                    listener: {
+                        end: (reason, message) => this.ended(reason, message),
+                        final: (text) => this.place(text, true),
+                        level: (level) => {
+                            this.style.setProperty('--dictation-level', level.toFixed(3));
+                            const meter = this.partNamed('voice-level');
+                            if (meter) {
+                                meter.level = level;
+                            }
+                        },
+                        partial: (text) => this.place(text, false),
                     },
-                    partial: (text) => this.place(text, false),
-                },
-            });
+                });
+            }
+            catch {
+                this.ended();
+                return false;
+            }
+            if (!this.heard) {
+                try {
+                    session.stop();
+                }
+                catch {
+                }
+                return false;
+            }
+            this.session = session;
             return true;
         }
         stopListening() {
             this.session?.stop();
             this.ended();
         }
-        ended() {
+        ended(reason, message) {
             if (!this.heard) {
                 return;
             }
             this.session = undefined;
             this.heard = false;
-            this.said = this.stoppedListeningLabel;
+            this.said = reason === 'error' ? this.failure(message) : this.stoppedListeningLabel;
             this.style.removeProperty('--dictation-level');
             this.toggleState('listening', false);
             this.voiceField()?.removeEventListener('keydown', this.handleVoiceKey);
             this.voiceField()?.removeEventListener('pointerdown', this.handleVoicePointer);
         }
+        failure(message) {
+            if (message === 'network') {
+                return this.dictationUnreachableLabel;
+            }
+            if (message === 'not-allowed' ||
+                message === 'service-not-allowed' ||
+                message === 'audio-capture') {
+                return this.dictationDeniedLabel;
+            }
+            return this.dictationFailedLabel;
+        }
         place(text, settled) {
             const field = this.voiceField();
             if (!field || !this.heard) {
@@ -140,6 +175,14 @@ export const MixinVoice = (Base) => {
                 this.dispatchEvent(new HelixListenEvent({ text }));
             }
         }
+        renderVoiceGlyph() {
+            const tier = this.constructor.tier;
+            if (this.heard && customElements.get(`${tier}voice-level`)) {
+                const meter = this.tag('voice-level');
+                return html `<${meter} part="voice-level" exportparts="canvas: voice-level-canvas" aria-hidden="true" variant="spectrum"></${meter}>`;
+            }
+            return drawIcon(microphone);
+        }
         renderVoice() {
             if (!this.voice || !this.voiceReady) {
                 return nothing;
@@ -161,11 +204,23 @@ export const MixinVoice = (Base) => {
                 }
             }}
         >
-          ${drawIcon(microphone)}
+          ${this.renderVoiceGlyph()}
         </button
         ><span part="voice-status" data-spoken role="status">${this.said}</span>`;
         }
     }
+    __decorate([
+        words,
+        property({ attribute: 'dictation-denied-label' })
+    ], Voice.prototype, "dictationDeniedLabel", void 0);
+    __decorate([
+        words,
+        property({ attribute: 'dictation-failed-label' })
+    ], Voice.prototype, "dictationFailedLabel", void 0);
+    __decorate([
+        words,
+        property({ attribute: 'dictation-unreachable-label' })
+    ], Voice.prototype, "dictationUnreachableLabel", void 0);
     __decorate([
         words,
         property({ attribute: 'listening-label' })

package/dist/utils/speech/speech.d.ts

@@ -32,13 +32,36 @@ export interface SpeechEngine {
         listener: SpeechListener;
     }): SpeechSession;
 }
+/**
+ * Listens with the browser's recognizer in this page, or in `scope`, a window
+ * of the same origin. A field in a sandboxed frame cannot: its origin is
+ * opaque, and the recognizer refuses it.
+ *
+ * **It recognizes on the device where the language is installed**, and
+ * through the browser's service where it is not. A press starts the install
+ * where the browser offers one. Chrome's service is Google's, and Chromium browsers without Google's
+ * keys, such as Brave, reach no service at all and end with `network`.
+ *
+ * `meter` reads loudness for the dictation button's level from a second
+ * capture of the microphone, opened on the recognizer's `audiostart`. Opened
+ * at the same time as the recognizer, that capture ended recognition after the
+ * permission prompt. Turn it off with `meter: false`.
+ */
+export declare const recognizeSpeech: (lang: string, listener: SpeechListener, options?: {
+    meter?: boolean;
+    scope?: Window;
+}) => SpeechSession;
 /**
  * The browser's own recognizer, `SpeechRecognition`, or `webkitSpeechRecognition`
  * in Safari. Not available in Firefox.
  *
- * **Chrome sends the audio to Google's servers to recognize it**, and Safari
- * to Apple's unless the device recognizes on the device. A page that cannot
- * send what is said registers an engine of its own.
+ * **It recognizes on the device where the browser can**, and Chrome downloads
+ * the language from the first press, which listens through the service. Where it cannot, Chrome sends the audio to
+ * Google's servers, and Safari to Apple's. A page that cannot send what is
+ * said registers an engine of its own.
+ *
+ * **A sandboxed frame has an opaque origin, and the recognizer refuses that.**
+ * The field asks the page that framed it to listen, and that page has an origin.
  */
 export declare const browserSpeech: SpeechEngine;
 /**

package/dist/utils/speech/speech.js

@@ -1,6 +1,6 @@
-const recognizer = () => {
-    const scope = globalThis;
-    return scope.SpeechRecognition ?? scope.webkitSpeechRecognition;
+const recognizer = (scope = globalThis) => {
+    const here = scope;
+    return here.SpeechRecognition ?? here.webkitSpeechRecognition;
 };
 const meter = (report) => {
     let stopped = false;
@@ -59,22 +59,75 @@ const meter = (report) => {
         release();
     };
 };
-export const browserSpeech = {
-    available: () => recognizer() !== undefined,
-    listen: ({ lang, listener }) => {
-        const Constructor = recognizer();
-        if (!Constructor) {
-            listener.end('error', 'This browser has no speech recognition.');
-            return { stop: () => { } };
-        }
-        const recognition = new Constructor();
-        recognition.continuous = true;
-        recognition.interimResults = true;
-        recognition.lang = lang;
-        let asked = false;
+const installing = new Set();
+const listenLocally = async (Constructor, lang) => {
+    const local = Constructor;
+    if (!local.available || !local.install) {
+        return false;
+    }
+    const options = { langs: [lang], processLocally: true };
+    try {
+        const state = await local.available(options);
+        if (state === 'available') {
+            return true;
+        }
+        if (state === 'unavailable') {
+            return false;
+        }
+        if (!installing.has(lang)) {
+            installing.add(lang);
+            void local
+                .install(options)
+                .catch(() => false)
+                .then(() => installing.delete(lang));
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+};
+export const recognizeSpeech = (lang, listener, options) => {
+    const Constructor = recognizer(options?.scope ?? globalThis);
+    if (!Constructor) {
+        listener.end('error', 'This browser has no speech recognition.');
+        return { stop: () => { } };
+    }
+    let asked = false;
+    let ended = false;
+    let recognition;
+    let quiet = () => { };
+    let metering = false;
+    const startMeter = () => {
+        if (options?.meter === false || metering || ended) {
+            return;
+        }
+        metering = true;
+        quiet = meter((level, bands) => listener.level?.(level, bands));
+    };
+    const end = (reason, message) => {
+        if (ended) {
+            return;
+        }
+        ended = true;
+        quiet();
+        listener.end(reason, message);
+    };
+    const listen = (locally) => {
+        const current = new Constructor();
+        recognition = current;
+        current.continuous = true;
+        current.interimResults = true;
+        current.lang = lang;
+        if (locally) {
+            ;
+            current.processLocally = true;
+        }
         let failed;
-        const quiet = meter((level, bands) => listener.level?.(level, bands));
-        recognition.onresult = (event) => {
+        let heard = false;
+        current.onaudiostart = startMeter;
+        current.onresult = (event) => {
+            heard = true;
             let guess = '';
             for (let at = event.resultIndex; at < event.results.length; at += 1) {
                 const result = event.results[at];
@@ -90,21 +143,94 @@ export const browserSpeech = {
                 listener.partial(guess.trim());
             }
         };
-        recognition.onerror = (event) => {
-            failed = event.error;
+        current.onerror = (event) => {
+            if (event.error !== 'no-speech' && event.error !== 'aborted') {
+                failed = event.error;
+            }
         };
-        recognition.onend = () => {
-            quiet();
-            listener.end(failed && failed !== 'aborted' ? 'error' : asked ? 'stopped' : 'ended', failed);
+        current.onend = () => {
+            if (locally && !asked && !heard && failed === 'language-not-supported') {
+                listen(false);
+                return;
+            }
+            end(failed ? 'error' : asked ? 'stopped' : 'ended', failed);
         };
-        recognition.start();
-        return {
-            stop: () => {
-                asked = true;
+        try {
+            current.start();
+        }
+        catch (error) {
+            end('error', error instanceof Error ? error.message : 'not-allowed');
+        }
+    };
+    void listenLocally(Constructor, lang).then((locally) => {
+        if (asked) {
+            end('stopped');
+            return;
+        }
+        listen(locally);
+    });
+    return {
+        stop: () => {
+            asked = true;
+            if (recognition) {
                 recognition.stop();
-            },
-        };
-    },
+            }
+        },
+    };
+};
+const opaqueFrame = () => {
+    const here = globalThis;
+    return here.origin === 'null' && here.parent !== undefined && here.parent !== here;
+};
+let relayId = 0;
+const relaySpeech = (lang, listener) => {
+    relayId += 1;
+    const id = relayId;
+    const parent = globalThis.parent;
+    const channel = new MessageChannel();
+    const take = (data) => {
+        if (data?.type !== 'helix-speech-heard' || data.id !== id) {
+            return;
+        }
+        if (data.kind === 'partial' && data.text) {
+            listener.partial(data.text);
+        }
+        else if (data.kind === 'level' && typeof data.level === 'number') {
+            listener.level?.(data.level);
+        }
+        else if (data.kind === 'final' && data.text) {
+            listener.final(data.text);
+        }
+        else if (data.kind === 'error' || data.kind === 'end' || data.kind === 'stopped') {
+            channel.port1.onmessage = null;
+            window.removeEventListener('message', onMessage);
+            listener.end(data.kind === 'error' ? 'error' : data.kind === 'stopped' ? 'stopped' : 'ended', data.error);
+        }
+    };
+    const onMessage = (event) => {
+        const data = event.data;
+        if (data?.type !== 'helix-speech-heard' || data.id !== id) {
+            return;
+        }
+        if (event.source !== parent && event.origin === 'null') {
+            return;
+        }
+        take(data);
+    };
+    channel.port1.onmessage = (event) => {
+        take(event.data);
+    };
+    window.addEventListener('message', onMessage);
+    parent.postMessage({ id, lang, type: 'helix-speech-start' }, '*', [channel.port2]);
+    return {
+        stop: () => {
+            parent.postMessage({ id, type: 'helix-speech-stop' }, '*');
+        },
+    };
+};
+export const browserSpeech = {
+    available: () => recognizer() !== undefined,
+    listen: ({ lang, listener }) => opaqueFrame() ? relaySpeech(lang, listener) : recognizeSpeech(lang, listener),
 };
 const KEY = Symbol.for('fusion.helix.speech');
 const globals = globalThis;

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.221.0";
+export declare const VERSION = "0.223.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.221.0';
+export const VERSION = '0.223.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.221.0",
+  "version": "0.223.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -81,12 +81,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.221.0",
+    "@fusion.dev/helix-icons": "0.223.0",
     "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.221.0",
-    "@fusion.dev/helix-testing": "0.221.0",
+    "@fusion.dev/helix-cem": "0.223.0",
+    "@fusion.dev/helix-testing": "0.223.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },