arcane-os 0.2.2 → 0.3.0

package/runtime/arcane/components/speech.html

@@ -146,18 +146,43 @@
 <button id="muteButton" type="button" class="mute" aria-pressed="true" aria-label="Voice unavailable" disabled>Voice unavailable</button>
 
 <script type="module">
+    const {
+        createArcaneEventSource,
+        projectArcaneDOMEvent
+    } = await import('arcane-os/event-manager');
+
     void import('../modules/DBLS.js').catch(
         function reportDBLSImportFailure(error) {
             console.error('The shared database runtime could not load.');
         }
     );
-    const aiModuleImport = import('../modules/AI.js?v=7');
+    const aiModuleImport = import('../modules/AI.js');
     const {
         requestAIRuntimeIntent,
         subscribeAIRuntimeState
     } = await import('../modules/AIRuntimeState.js');
+    const {
+        createSTTActivationController
+    } = await import('../modules/ComponentContracts.js');
 
     const host = this;
+    const events = createArcaneEventSource(
+        host,
+        {
+            source: 'arcane.component.speech',
+            eventTypes: [
+                'speech-ready',
+                'speech-transcription-complete',
+                'speech-transcription-error',
+                'speech-transcription-cancelled',
+                'speech-microphone-unavailable',
+                'speech-stt-activation-request',
+                'speech-stt-activation-error',
+                'speech-tts-lifecycle-error',
+                'speech-synthesis-error'
+            ]
+        }
+    );
     const shadowRoot = host.shadowRoot;
     const recordButton = shadowRoot.querySelector('#recordButton');
     const sttActivationButton = shadowRoot.querySelector('#sttActivationButton');
@@ -183,12 +208,99 @@
     let keyboardRecording = false;
     let localStatus = null;
     let pendingTTSIntent = null;
+    let activeTTSIntent = null;
+    let pendingUnmute = false;
     let ttsIntentGeneration = 0;
+    let eventOperationSequence = 0;
+    let transcriptionOperationId = null;
+    let ttsOperationId = null;
     let destroyed = false;
 
+    function nextSpeechOperationId(kind) {
+        eventOperationSequence += 1;
+        return `${events.descriptor.instanceId}:${kind}:${eventOperationSequence}`;
+    }
+
+    function dispatchSpeechEvent(
+        type,
+        compatibilityDetail = {},
+        {
+            publicDetail = {},
+            operationId = null,
+            bubbles = false,
+            composed = false,
+            cancelable = false
+        } = {}
+    ) {
+        if (destroyed && type !== 'speech-transcription-cancelled') {
+            return false;
+        }
+        const publication = events.dispatch(
+            type,
+            compatibilityDetail,
+            {
+                publicDetail,
+                operationId,
+                cancelable
+            }
+        );
+        if (!publication.accepted) {
+            return false;
+        }
+        return projectArcaneDOMEvent(
+            host,
+            publication.occurrence,
+            {
+                bubbles,
+                composed,
+                cancelable
+            }
+        );
+    }
+
+    function publicSpeechErrorFields(error, boundaryCode) {
+        let causeCode = '';
+        try {
+            causeCode = typeof error?.code === 'string'
+                ? error.code.trim()
+                : '';
+        } catch {}
+        return Object.freeze(
+            {
+                code: boundaryCode,
+                ...(causeCode && causeCode !== boundaryCode
+                    ? { causeCode }
+                    : {})
+            }
+        );
+    }
+
+    function microphoneFailureReason(error) {
+        if (error?.name === 'NotFoundError') {
+            return 'microphone-input-missing';
+        }
+        if (error?.name === 'NotReadableError') {
+            return 'microphone-input-unavailable';
+        }
+        if (['NotAllowedError', 'SecurityError'].includes(error?.name)) {
+            return 'microphone-capture-denied';
+        }
+        return 'microphone-capture-rejected';
+    }
+
+    function canonicalSTTCancellationReason(reason) {
+        if (reason === 'runtime-unready') {
+            return 'stt-role-unready';
+        }
+        if (reason === 'stt-provider-request-cancelled') {
+            return 'stt-provider-transcription-cancelled';
+        }
+        return String(reason || 'stt-transcription-cancelled');
+    }
+
     const initialMutedWasHydrated = typeof host.initialMuted === 'boolean';
     host.initialMuted = initialMutedWasHydrated ? host.initialMuted : true;
-    host.muted = host.initialMuted;
+    host.muted = true;
     host.configure = configure;
     host.destroy = destroy;
     host.reportTTSError = reportTTSError;
@@ -210,20 +322,29 @@
         {
             host,
             button: sttActivationButton,
-            onChange: renderSTTActivationState
+            onChange: renderSTTActivationState,
+            eventSource: events
         }
     );
 
-    recordButton.addEventListener('pointerdown', handleRecordPointerDown);
-    recordButton.addEventListener('pointerup', handleRecordPointerUp);
-    recordButton.addEventListener('pointercancel', handleRecordPointerCancel);
-    recordButton.addEventListener('lostpointercapture', handleLostPointerCapture);
-    recordButton.addEventListener('keydown', handleRecordKeyDown);
-    recordButton.addEventListener('keyup', handleRecordKeyUp);
-    recordButton.addEventListener('blur', handleRecordBlur);
-    muteButton.addEventListener('click', muteToggle);
-    endButton.addEventListener('click', submitCompletionCommand);
-    window.addEventListener('pagehide', destroy, { once: true });
+    const lifecycleListenerOptions = Object.freeze(
+        { signal: runtimeStateAbortController.signal }
+    );
+    recordButton.addEventListener('pointerdown', handleRecordPointerDown, lifecycleListenerOptions);
+    recordButton.addEventListener('pointerup', handleRecordPointerUp, lifecycleListenerOptions);
+    recordButton.addEventListener('pointercancel', handleRecordPointerCancel, lifecycleListenerOptions);
+    recordButton.addEventListener('lostpointercapture', handleLostPointerCapture, lifecycleListenerOptions);
+    recordButton.addEventListener('keydown', handleRecordKeyDown, lifecycleListenerOptions);
+    recordButton.addEventListener('keyup', handleRecordKeyUp, lifecycleListenerOptions);
+    recordButton.addEventListener('blur', handleRecordBlur, lifecycleListenerOptions);
+    stopButton.addEventListener('click', stop, lifecycleListenerOptions);
+    muteButton.addEventListener('click', muteToggle, lifecycleListenerOptions);
+    endButton.addEventListener('click', submitCompletionCommand, lifecycleListenerOptions);
+    window.addEventListener(
+        'pagehide',
+        destroy,
+        { once: true, signal: runtimeStateAbortController.signal }
+    );
 
     subscribeAIRuntimeState(
         synchronizeAIRuntimeState,
@@ -231,213 +352,37 @@
             signal: runtimeStateAbortController.signal
         }
     );
+    if (!host.initialMuted && ttsRole.state === 'ready') {
+        host.muted = false;
+    }
     synchronizeAIMutedState();
     renderControls();
     renderStatus();
     void observeMicrophonePermission();
     void aiModuleImport.then(
-        synchronizeAIMutedState,
-        function reportAIModuleImportFailure(error) {
-            console.error('The shared AI runtime could not load.');
-        }
-    );
-
-    host.componentReady = true;
-    host.dispatchEvent(
-        new CustomEvent(
-            'speech-ready',
-            {
-                bubbles: true,
-                composed: true,
-                detail: { speech: host }
-            }
-        )
-    );
-
-    function createSTTActivationController({
-        host,
-        button,
-        onChange,
-        EventClass = CustomEvent
-    }) {
-        let role = null;
-        let requestPending = false;
-        let requestError = '';
-        let requestGeneration = 0;
-        let destroyed = false;
-
-        function visibleError(error, fallback) {
-            const message = typeof error?.message === 'string'
-                ? error.message.trim()
-                : '';
-            return (message || fallback).slice(0, 240);
-        }
-
-        function cancellation(error) {
-            return error?.name === 'AbortError'
-                || [
-                    'ARCANE_AI_REQUEST_ABORTED',
-                    'ARCANE_AI_OPERATION_SUPERSEDED'
-                ]
-                    .includes(error?.code);
-        }
-
-        function selected() {
-            return typeof role?.providerId === 'string'
-                && role.providerId.length > 0
-                && typeof role?.modelId === 'string'
-                && role.modelId.length > 0;
-        }
-
-        function action() {
-            if (!selected()) {
-                return null;
-            }
-            if (role.state === 'loading') {
-                return 'unload';
-            }
-            if (!role.busy && ['unloaded', 'error'].includes(role.state)) {
-                return 'load';
-            }
-            return null;
-        }
-
-        async function request(nextAction) {
-            if (destroyed || requestPending || action() !== nextAction) {
-                return false;
+        function synchronizeMutedStateAfterAIImport() {
+            if (!destroyed) {
+                synchronizeAIMutedState();
             }
-            const generation = ++requestGeneration;
-            requestError = '';
-            const intent = Object.freeze(
-                {
-                    role: 'stt',
-                    action: nextAction,
-                    reason: 'user'
-                }
-            );
-            const activationRequest = Object.freeze({intent, state: role});
-            const activationEvent = new EventClass(
-                'speech-stt-activation-request',
-                {
-                    bubbles: true,
-                    composed: true,
-                    cancelable: true,
-                    detail: activationRequest
-                }
-            );
-            requestPending = true;
-            const accepted = host.dispatchEvent(activationEvent);
-            if (!accepted
-                || destroyed
-                || generation !== requestGeneration
-                || action() !== nextAction) {
-                if (!destroyed && generation === requestGeneration) {
-                    requestPending = false;
-                    onChange();
-                }
-                return false;
-            }
-            onChange();
-            try {
-                await host.requestSTTActivation(intent);
-                if (destroyed || generation !== requestGeneration) {
-                    return false;
-                }
-                return true;
-            } catch (error) {
-                if (destroyed || generation !== requestGeneration) {
-                    return false;
-                }
-                if (nextAction === 'load'
-                    && cancellation(error)
-                    && ['unloaded', 'unloading'].includes(role?.state)) {
-                    return false;
-                }
-                const message = visibleError(
-                    error,
-                    `The transcription ${nextAction} request failed.`
-                );
-                requestError = message;
-                host.dispatchEvent(
-                    new EventClass(
-                        'speech-stt-activation-error',
-                        {
-                            bubbles: true,
-                            composed: true,
-                            detail: Object.freeze(
-                                {
-                                    request: activationRequest,
-                                    error,
-                                    message
-                                }
-                            )
-                        }
-                    )
-                );
-                return false;
-            } finally {
-                if (!destroyed && generation === requestGeneration) {
-                    requestPending = false;
-                    onChange();
-                }
-            }
-        }
-
-        function activateSelectedSTT() {
-            const nextAction = action();
-            if (nextAction) {
-                void request(nextAction);
-            }
-        }
-
-        function synchronize(nextRole) {
+        },
+        function reportAIModuleImportFailure(error) {
             if (destroyed) {
                 return;
             }
-            if (role?.state !== nextRole.state
-                || role?.providerId !== nextRole.providerId
-                || role?.modelId !== nextRole.modelId
-                || role?.loaded !== nextRole.loaded
-                || role?.busy !== nextRole.busy
-                || role?.operationId !== nextRole.operationId) {
-                requestGeneration += 1;
-                requestError = '';
-                requestPending = false;
-            }
-            role = nextRole;
+            console.error('The shared AI runtime could not load.');
         }
+    );
 
-        function destroy() {
-            if (destroyed) {
-                return;
-            }
-            destroyed = true;
-            requestGeneration += 1;
-            requestPending = false;
-            button.removeEventListener('click', activateSelectedSTT);
+    host.componentReady = true;
+    dispatchSpeechEvent(
+        'speech-ready',
+        { speech: host },
+        {
+            bubbles: true,
+            composed: true,
+            publicDetail: { ready: true }
         }
-
-        button.addEventListener('click', activateSelectedSTT);
-        return Object.freeze(
-            {
-                get action() {
-                    return action();
-                },
-                get error() {
-                    return requestError;
-                },
-                get pending() {
-                    return requestPending;
-                },
-                get selected() {
-                    return selected();
-                },
-                request,
-                synchronize,
-                destroy
-            }
-        );
-    }
+    );
 
     function unavailableRole(role) {
         return Object.freeze(
@@ -464,6 +409,9 @@
     }
 
     function configure(options = {}) {
+        if (destroyed) {
+            return host;
+        }
         if (Object.prototype.hasOwnProperty.call(options, 'initialMuted')) {
             const configuredMuted = typeof options.initialMuted === 'boolean'
                 ? options.initialMuted
@@ -484,6 +432,9 @@
     }
 
     function setAvailability(input = {}) {
+        if (destroyed) {
+            return { ...host.availability };
+        }
         // Compatibility-only explicit adapter report. Canonical consumers use
         // the sticky AIRuntimeState role records instead of this wrapper.
         const previousSTTRole = sttRole;
@@ -512,6 +463,9 @@
     }
 
     function setMuted(muted) {
+        if (destroyed) {
+            return host;
+        }
         if (typeof muted !== 'boolean') {
             throw new TypeError('muted must be boolean');
         }
@@ -525,11 +479,11 @@
     }
 
     function applyConfiguredMutedState(muted) {
-        host.muted = muted;
-        pendingTTSIntent = null;
         if (muted) {
-            stopTTSPlayback();
+            requestUserMute();
         } else {
+            pendingUnmute = false;
+            host.muted = ttsRole.state !== 'ready';
             synchronizeAIMutedState();
         }
         renderControls();
@@ -559,14 +513,18 @@
             cancelSTTOperation('runtime-unready');
         }
         if (ttsBecameUnready) {
+            pendingUnmute = false;
             host.muted = true;
             stopTTSPlayback();
         }
-        if (ttsRole.state === 'error' && !host.muted) {
+        if (ttsRole.state === 'error' && (pendingUnmute || !host.muted)) {
+            pendingUnmute = false;
             host.muted = true;
             stopTTSPlayback();
         }
 
+        settleSuccessfulUnmute();
+
         synchronizeAIMutedState();
         renderControls();
         renderStatus();
@@ -597,18 +555,20 @@
 
     function renderControls() {
         const transcriptionReady = sttRole.state === 'ready';
-        const microphoneReady = host.availability.microphone;
-        const activationVisible = sttActivationController.selected
-            && sttRole.state !== 'ready'
-            && ['unloaded', 'loading', 'unloading', 'error']
-                .includes(sttRole.state);
+        const microphoneReady = host.availability.microphone
+            && typeof globalThis.MediaRecorder === 'function'
+            && typeof navigator.mediaDevices?.getUserMedia === 'function';
+        const activationVisible = sttActivationController.visible;
         recordButton.hidden = activationVisible;
         recordButton.disabled = !transcriptionReady
             || !microphoneReady
             || sttRole.busy
             || transcriptionActive
             || destroyed;
-        stopButton.disabled = recordButton.disabled;
+        stopButton.disabled = destroyed
+            || !transcriptionReady
+            || sttRole.busy
+            || captureSession?.recorder.state !== 'recording';
         recordButton.title = transcriptionButtonTitle();
         recordButton.setAttribute('aria-label', recordButton.title);
         recordButton.setAttribute(
@@ -620,8 +580,8 @@
             || sttActivationController.pending
             || sttRole.state === 'unloading'
             || sttActivationController.action === null;
-        sttActivationButton.textContent = transcriptionActivationLabel();
-        sttActivationButton.title = transcriptionActivationTitle();
+        sttActivationButton.textContent = sttActivationController.label;
+        sttActivationButton.title = sttActivationController.title;
         sttActivationButton.setAttribute(
             'aria-label',
             sttActivationButton.title
@@ -636,41 +596,6 @@
         renderTTSControl();
     }
 
-    function transcriptionActivationLabel() {
-        if (sttActivationController.pending) {
-            return 'Requesting…';
-        }
-        if (sttRole.state === 'loading') {
-            return 'Cancel loading';
-        }
-        if (sttRole.state === 'unloading') {
-            return 'Canceling…';
-        }
-        if (sttRole.state === 'error') {
-            return 'Try again';
-        }
-        return 'Start transcription';
-    }
-
-    function transcriptionActivationTitle() {
-        if (sttActivationController.pending) {
-            return 'Requesting transcription activation.';
-        }
-        if (sttRole.state === 'loading') {
-            return 'Cancel loading the selected transcription service.';
-        }
-        if (sttRole.state === 'unloading') {
-            return 'The selected transcription service is being released.';
-        }
-        if (sttRole.state === 'error') {
-            return sttActivationController.error || visibleErrorMessage(
-                sttRole.error,
-                'Retry loading the selected transcription service.'
-            );
-        }
-        return 'Start the selected transcription service.';
-    }
-
     function transcriptionButtonTitle() {
         if (destroyed || sttRole.state === 'disposed') {
             return 'Transcription is unavailable.';
@@ -776,34 +701,10 @@
     }
 
     function describeSTTRole() {
-        if (sttActivationController.error) {
-            return `Transcription activation error: ${sttActivationController.error}.`;
-        }
-        if (sttActivationController.pending) {
-            return 'Transcription activation requested.';
-        }
-        if (sttRole.state === 'ready') {
-            if (!host.availability.microphone) {
-                return 'Microphone unavailable.';
-            }
-            return sttRole.busy ? 'Transcription busy.' : 'Transcription ready.';
-        }
-        if (sttRole.state === 'loading') {
-            return `Transcription ${formatRoleProgress(sttRole.progress, 'loading')}; Cancel is available.`;
+        if (sttRole.state === 'ready' && !host.availability.microphone) {
+            return 'Microphone unavailable.';
         }
-        if (sttRole.state === 'unloading') {
-            return `Transcription ${formatRoleProgress(sttRole.progress, 'releasing')}.`;
-        }
-        if (sttRole.state === 'error') {
-            return `Transcription error: ${visibleErrorMessage(sttRole.error, 'Unknown error')}.`;
-        }
-        if (sttRole.state === 'disposed') {
-            return 'Transcription disposed.';
-        }
-        if (sttRole.state === 'unloaded' && sttActivationController.selected) {
-            return 'Transcription selected and waiting to load.';
-        }
-        return 'Transcription unavailable.';
+        return sttActivationController.status;
     }
 
     function describeTTSRole() {
@@ -862,13 +763,18 @@
         }
 
         try {
-            microphonePermissionStatus = await navigator.permissions.query(
+            const permissionStatus = await navigator.permissions.query(
                 { name: 'microphone' }
             );
+            if (destroyed) {
+                return;
+            }
+            microphonePermissionStatus = permissionStatus;
             microphonePermissionListener = synchronizeMicrophonePermission;
             microphonePermissionStatus.addEventListener?.(
                 'change',
-                microphonePermissionListener
+                microphonePermissionListener,
+                { signal: runtimeStateAbortController.signal }
             );
             synchronizeMicrophonePermission();
         } catch (error) {
@@ -878,6 +784,9 @@
     }
 
     function synchronizeMicrophonePermission() {
+        if (destroyed) {
+            return;
+        }
         setAvailability(
             {
                 microphone: microphonePermissionStatus?.state !== 'denied'
@@ -983,27 +892,49 @@
         }
 
         if (host.muted) {
-            requestUserUnmute();
+            void requestUserUnmute();
         } else {
             requestUserMute();
         }
     }
 
     function requestUserMute() {
+        if (destroyed) {
+            return false;
+        }
+        if (host.muted && activeTTSIntent?.action === 'unload') {
+            return false;
+        }
         const wasMuted = host.muted;
+        pendingUnmute = false;
         const shouldUnload = !wasMuted
             || pendingTTSIntent === 'load'
             || ['loading', 'ready', 'error'].includes(ttsRole.state);
         host.muted = true;
         stopTTSPlayback();
         if (shouldUnload) {
-            requestTTSIntent('unload', 'user');
+            void requestTTSIntent('unload', 'user');
         }
         renderControls();
         renderStatus();
     }
 
-    function requestUserUnmute() {
+    async function requestUserUnmute() {
+        if (destroyed) {
+            return false;
+        }
+        if (!host.muted && ttsRole.state === 'ready') {
+            return true;
+        }
+        if (activeTTSIntent?.action === 'load') {
+            return false;
+        }
+        if (
+            pendingUnmute
+            && (pendingTTSIntent === 'load' || ttsRole.state === 'loading')
+        ) {
+            return false;
+        }
         const providerSelected = typeof ttsRole.providerId === 'string'
             && ttsRole.providerId.length > 0
             && typeof ttsRole.modelId === 'string'
@@ -1023,60 +954,93 @@
             return false;
         }
 
-        host.muted = false;
-        synchronizeAIMutedState();
-        requestTTSIntent('load', 'user');
-        if (ttsRole.state === 'ready') {
-            resumeTTSPlayback();
+        pendingUnmute = true;
+        const requested = await requestTTSIntent('load', 'user');
+        if (!requested || destroyed) {
+            pendingUnmute = false;
+            host.muted = true;
+            stopTTSPlayback();
+            renderControls();
+            renderStatus();
+            return false;
         }
+        settleSuccessfulUnmute();
         renderControls();
         renderStatus();
+        return host.muted === false;
+    }
+
+    function settleSuccessfulUnmute() {
+        if (!pendingUnmute || ttsRole.state !== 'ready' || destroyed) {
+            return false;
+        }
+        pendingUnmute = false;
+        pendingTTSIntent = null;
+        host.muted = false;
+        synchronizeAIMutedState();
+        resumeTTSPlayback();
         return true;
     }
 
-    function requestTTSIntent(action, reason) {
+    async function requestTTSIntent(action, reason) {
+        if (destroyed) {
+            return false;
+        }
+        if (activeTTSIntent?.action === action) {
+            return false;
+        }
         const generation = ++ttsIntentGeneration;
+        const operationId = nextSpeechOperationId(`tts-${action}`);
+        const intent = Object.freeze({ action, generation, operationId });
+        activeTTSIntent = intent;
+        ttsOperationId = operationId;
         pendingTTSIntent = action === 'load' && ttsRole.state === 'ready'
             ? null
             : action;
-        let lifecycle = null;
+        let lifecycle;
         try {
             if (typeof globalThis.ai?.setSpeechMuted === 'function') {
                 lifecycle = globalThis.ai.setSpeechMuted(action === 'unload');
+            } else {
+                lifecycle = requestAIRuntimeIntent(
+                    {
+                        role: 'tts',
+                        action,
+                        reason
+                    }
+                );
             }
-            requestAIRuntimeIntent(
-                {
-                    role: 'tts',
-                    action,
-                    reason
-                }
-            );
+            await lifecycle;
         } catch (error) {
+            if (destroyed || generation !== ttsIntentGeneration) {
+                return false;
+            }
             pendingTTSIntent = null;
             if (action === 'load') {
+                pendingUnmute = false;
                 host.muted = true;
                 stopTTSPlayback();
             }
-            reportTTSLifecycleError(error, action);
+            reportTTSLifecycleError(error, action, operationId);
             return false;
-        }
-        void Promise.resolve(lifecycle).catch(
-            function reportCurrentTTSSpeechLifecycleFailure(error) {
-                if (destroyed || generation !== ttsIntentGeneration) {
-                    return;
-                }
-                pendingTTSIntent = null;
-                if (action === 'load') {
-                    host.muted = true;
-                    stopTTSPlayback();
-                }
-                reportTTSLifecycleError(error, action);
+        } finally {
+            if (activeTTSIntent === intent) {
+                activeTTSIntent = null;
             }
-        );
+        }
+        if (destroyed || generation !== ttsIntentGeneration) {
+            return false;
+        }
+        if (action === 'load') {
+            settleSuccessfulUnmute();
+        }
         return true;
     }
 
-    function reportTTSLifecycleError(error, action) {
+    function reportTTSLifecycleError(error, action, operationId = null) {
+        if (destroyed) {
+            return false;
+        }
         const message = visibleErrorMessage(
             error,
             `The voice ${action} request failed.`
@@ -1085,47 +1049,80 @@
             message,
             tone: 'error'
         };
-        host.dispatchEvent(
-            new CustomEvent(
-                'speech-tts-lifecycle-error',
-                {
-                    bubbles: true,
-                    composed: true,
-                    detail: {
-                        action,
-                        error,
-                        message
-                    }
+        const errorFields = publicSpeechErrorFields(
+            error,
+            `ARCANE_SPEECH_TTS_${action.toUpperCase()}_REJECTED`
+        );
+        const reason = `tts-${action}-rejected`;
+        dispatchSpeechEvent(
+            'speech-tts-lifecycle-error',
+            {
+                action,
+                ...errorFields,
+                error,
+                message,
+                reason
+            },
+            {
+                bubbles: true,
+                composed: true,
+                operationId: operationId || ttsOperationId
+                    || nextSpeechOperationId(`tts-${action}`),
+                publicDetail: {
+                    action,
+                    ...errorFields,
+                    reason
                 }
-            )
+            }
         );
         renderControls();
         renderStatus();
+        return false;
     }
 
-    function reportTTSError(error) {
+    function reportTTSError(error, boundary = 'synthesis') {
+        if (destroyed) {
+            return false;
+        }
+        const playbackRejected = boundary === 'playback';
         const message = visibleErrorMessage(
             error,
-            'Speech synthesis failed.'
+            playbackRejected
+                ? 'Speech playback failed.'
+                : 'Speech synthesis failed.'
         );
         host.muted = true;
         stopTTSPlayback();
         localStatus = {
-            message: `Speech synthesis failed: ${message}`,
+            message: `${playbackRejected ? 'Speech playback' : 'Speech synthesis'} failed: ${message}`,
             tone: 'error'
         };
-        host.dispatchEvent(
-            new CustomEvent(
-                'speech-synthesis-error',
-                {
-                    bubbles: true,
-                    composed: true,
-                    detail: {
-                        error,
-                        message
-                    }
+        const errorFields = publicSpeechErrorFields(
+            error,
+            playbackRejected
+                ? 'ARCANE_SPEECH_TTS_PLAYBACK_RESUME_REJECTED'
+                : 'ARCANE_SPEECH_TTS_SYNTHESIS_REQUEST_REJECTED'
+        );
+        const reason = playbackRejected
+            ? 'tts-playback-resume-rejected'
+            : 'tts-synthesis-rejected';
+        dispatchSpeechEvent(
+            'speech-synthesis-error',
+            {
+                ...errorFields,
+                error,
+                message,
+                reason
+            },
+            {
+                bubbles: true,
+                composed: true,
+                operationId: nextSpeechOperationId('synthesis'),
+                publicDetail: {
+                    ...errorFields,
+                    reason
                 }
-            )
+            }
         );
         renderControls();
         renderStatus();
@@ -1159,20 +1156,26 @@
 
         void Promise.resolve(aiRuntime.resumeAudio()).catch(
             function reportTTSResumeFailure(error) {
-                reportTTSError(error);
+                reportTTSError(error, 'playback');
             }
         );
     }
 
     async function transcribe(transcription = '') {
-        host.dispatchEvent(
-            new CustomEvent(
-                'speech-transcription-complete',
-                {
-                    detail: { text: transcription }
+        const operationId = transcriptionOperationId
+            || nextSpeechOperationId('transcription');
+        const accepted = dispatchSpeechEvent(
+            'speech-transcription-complete',
+            { text: transcription },
+            {
+                operationId,
+                publicDetail: {
+                    characterCount: transcription.length
                 }
-            )
+            }
         );
+        transcriptionOperationId = null;
+        return accepted;
     }
 
     async function record() {
@@ -1181,6 +1184,8 @@
             || sttRole.state !== 'ready'
             || sttRole.busy
             || !host.availability.microphone
+            || typeof globalThis.MediaRecorder !== 'function'
+            || typeof navigator.mediaDevices?.getUserMedia !== 'function'
             || recordingRequested
             || captureSession
             || transcriptionActive
@@ -1190,6 +1195,7 @@
         }
 
         const generation = ++recordingGeneration;
+        transcriptionOperationId = nextSpeechOperationId('transcription');
         recordingRequested = true;
         localStatus = {
             message: 'Recording. Release to transcribe.',
@@ -1213,16 +1219,23 @@
                     message: 'Microphone access is unavailable. Text chat is still available.',
                     tone: 'error'
                 };
-                host.dispatchEvent(
-                    new CustomEvent(
-                        'speech-microphone-unavailable',
-                        {
-                            bubbles: true,
-                            composed: true,
-                            detail: { reason: error.name }
+                dispatchSpeechEvent(
+                    'speech-microphone-unavailable',
+                    { reason: error.name },
+                    {
+                        bubbles: true,
+                        composed: true,
+                        operationId: transcriptionOperationId,
+                        publicDetail: {
+                            ...publicSpeechErrorFields(
+                                error,
+                                'ARCANE_SPEECH_MICROPHONE_CAPTURE_REJECTED'
+                            ),
+                            reason: microphoneFailureReason(error)
                         }
-                    )
+                    }
                 );
+                transcriptionOperationId = null;
             } else {
                 reportTranscriptionError(error);
             }
@@ -1235,6 +1248,7 @@
             !recordingRequested
             || generation !== recordingGeneration
             || sttRole.state !== 'ready'
+            || sttRole.busy
             || destroyed
         ) {
             stopMediaStream(stream);
@@ -1341,6 +1355,7 @@
             session.cancelled
             || session.generation !== recordingGeneration
             || sttRole.state !== 'ready'
+            || sttRole.busy
             || destroyed
         ) {
             renderControls();
@@ -1362,6 +1377,8 @@
 
     async function transcribeAudio(audioFile) {
         const generation = ++transcriptionGeneration;
+        transcriptionOperationId = transcriptionOperationId
+            || nextSpeechOperationId('transcription');
         const controller = new AbortController();
         transcriptionAbortController?.abort();
         transcriptionAbortController = controller;
@@ -1375,8 +1392,19 @@
 
         try {
             const aiRuntime = globalThis.ai;
-            if (sttRole.state !== 'ready' || typeof aiRuntime?.fetchSTT !== 'function') {
-                throw new Error('The selected transcription service is unavailable.');
+            if (sttRole.state !== 'ready' || sttRole.busy) {
+                reportTranscriptionCancellation(
+                    sttRole.busy ? 'stt-role-busy' : 'runtime-unready',
+                    sttRole.busy
+                        ? 'Transcription stopped because the selected service is busy.'
+                        : 'Transcription stopped because the selected service became unavailable.'
+                );
+                return false;
+            }
+            if (typeof aiRuntime?.fetchSTT !== 'function') {
+                const error = new Error('The selected transcription service is unavailable.');
+                error.code = 'ARCANE_SPEECH_STT_RUNTIME_METHOD_UNAVAILABLE';
+                throw error;
             }
 
             const transcription = await aiRuntime.fetchSTT(
@@ -1400,7 +1428,14 @@
             return true;
         } catch (error) {
             if (generation === transcriptionGeneration && !destroyed) {
-                reportTranscriptionError(error);
+                if (isTranscriptionCancellation(error, controller)) {
+                    reportTranscriptionCancellation(
+                        'stt-provider-request-cancelled',
+                        'The selected transcription request was cancelled.'
+                    );
+                } else {
+                    reportTranscriptionError(error);
+                }
             }
             return false;
         } finally {
@@ -1424,23 +1459,72 @@
             message: `Transcription failed: ${message}`,
             tone: 'error'
         };
-        host.dispatchEvent(
-            new CustomEvent(
-                'speech-transcription-error',
-                {
-                    bubbles: true,
-                    composed: true,
-                    detail: {
-                        error,
-                        message
-                    }
+        const operationId = transcriptionOperationId
+            || nextSpeechOperationId('transcription');
+        const errorFields = publicSpeechErrorFields(
+            error,
+            'ARCANE_SPEECH_STT_TRANSCRIPTION_REQUEST_REJECTED'
+        );
+        const reason = 'stt-transcription-rejected';
+        dispatchSpeechEvent(
+            'speech-transcription-error',
+            {
+                ...errorFields,
+                error,
+                message,
+                reason
+            },
+            {
+                bubbles: true,
+                composed: true,
+                operationId,
+                publicDetail: {
+                    ...errorFields,
+                    reason
                 }
-            )
+            }
         );
+        transcriptionOperationId = null;
         renderControls();
         renderStatus();
     }
 
+    function isTranscriptionCancellation(error, controller) {
+        return controller.signal.aborted
+            || error?.name === 'AbortError'
+            || [
+                'ARCANE_AI_REQUEST_ABORTED',
+                'ARCANE_AI_OPERATION_SUPERSEDED'
+            ].includes(error?.code);
+    }
+
+    function reportTranscriptionCancellation(reason, message) {
+        const operationId = transcriptionOperationId
+            || nextSpeechOperationId('transcription');
+        localStatus = {
+            message,
+            tone: ''
+        };
+        const accepted = dispatchSpeechEvent(
+            'speech-transcription-cancelled',
+            { reason },
+            {
+                bubbles: true,
+                composed: true,
+                operationId,
+                publicDetail: {
+                    reason: canonicalSTTCancellationReason(reason)
+                }
+            }
+        );
+        transcriptionOperationId = null;
+        if (!destroyed) {
+            renderControls();
+            renderStatus();
+        }
+        return accepted;
+    }
+
     function cancelSTTOperation(reason) {
         const hadActiveOperation = recordingRequested
             || Boolean(captureSession)
@@ -1465,21 +1549,14 @@
         }
 
         if (hadActiveOperation) {
-            localStatus = {
-                message: 'Transcription stopped because the selected service became unavailable.',
-                tone: 'error'
-            };
-            host.dispatchEvent(
-                new CustomEvent(
-                    'speech-transcription-cancelled',
-                    {
-                        bubbles: true,
-                        composed: true,
-                        detail: { reason }
-                    }
-                )
+            reportTranscriptionCancellation(
+                String(reason || 'stt-transcription-cancelled'),
+                reason === 'component-destroyed'
+                    ? 'Transcription stopped because the speech component was destroyed.'
+                    : 'Transcription stopped because the selected service became unavailable.'
             );
         }
+        transcriptionOperationId = null;
     }
 
     function releaseCaptureSession(session) {
@@ -1530,6 +1607,7 @@
         );
         cancelSTTOperation('component-destroyed');
         stopTTSPlayback();
+        events.dispose();
         host.componentReady = false;
         renderControls();
         renderStatus();