arcane-os 0.2.2 → 0.3.0

package/runtime/arcane/components/voice-transcription.html

@@ -50,16 +50,39 @@
 <section class="voice-transcription">
     <p id="description" class="description"></p>
     <section id="transcript" class="transcript"></section>
-    <p id="status" class="status" aria-live="polite"></p>
+    <p id="status" class="status" role="status" aria-live="polite"></p>
     <section class="controls">
         <button id="start" type="button" disabled></button>
+        <button id="sttActivation" type="button" hidden disabled>Start transcription</button>
         <button id="stop" type="button" disabled></button>
         <button id="complete" type="button" disabled></button>
     </section>
 </section>
 
 <script type="module">
+    const {
+        createArcaneEventSource,
+        projectArcaneDOMEvent
+    }=await import('arcane-os/event-manager');
+
     const host=this;
+    const events=createArcaneEventSource(
+        host,
+        {
+            source:'arcane.component.voice-transcription',
+            eventTypes:[
+                'voice-transcription-ready',
+                'voice-transcription-state',
+                'voice-transcription-segment',
+                'voice-transcription-change',
+                'voice-transcription-complete',
+                'speech-transcription-complete',
+                'speech-transcription-cancelled',
+                'speech-stt-activation-request',
+                'speech-stt-activation-error'
+            ]
+        }
+    );
     const componentURL=new URL(
         host.getAttribute('href')||'./arcane/components/voice-transcription.html',
         document.baseURI
@@ -68,23 +91,97 @@
     const {default:MD}=await import(moduleURL('MD.js?v=2'));
     const {
         appendTranscription,
+        createSTTActivationController,
         normalizeVoiceOptions
     }=await import(moduleURL('ComponentContracts.js'));
+    const {
+        requestAIRuntimeIntent,
+        subscribeAIRuntimeState
+    }=await import(moduleURL('AIRuntimeState.js'));
     const description=host.shadowRoot.querySelector('#description');
     const transcriptElement=host.shadowRoot.querySelector('#transcript');
     const status=host.shadowRoot.querySelector('#status');
     const startButton=host.shadowRoot.querySelector('#start');
+    const sttActivationButton=host.shadowRoot.querySelector('#sttActivation');
     const stopButton=host.shadowRoot.querySelector('#stop');
     const completeButton=host.shadowRoot.querySelector('#complete');
+    const runtimeStateAbortController=new AbortController();
 
     let chunks=[];
     let mediaStream=null;
     let recorder=null;
     let state='idle';
+    let stateMessage='';
+    let sttRole=unavailableRole('stt');
     let transcript='';
     let sessionGeneration=0;
+    let transcriptionAbortController=null;
+    let eventOperationSequence=0;
+    let voiceOperationId=null;
+    let destroyed=false;
     let options=normalizeVoiceOptions(optionsFromDataset());
 
+    function nextVoiceOperationId(kind){
+        eventOperationSequence+=1;
+        return `${events.descriptor.instanceId}:${kind}:${eventOperationSequence}`;
+    }
+
+    function currentVoiceOperationId(kind='transcription'){
+        voiceOperationId=voiceOperationId||nextVoiceOperationId(kind);
+        return voiceOperationId;
+    }
+
+    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');
+    }
+
+    function dispatchVoiceEvent(
+        type,
+        compatibilityDetail={},
+        {
+            publicDetail={},
+            operationId=null,
+            beginOperation=null,
+            bubbles=false,
+            composed=false,
+            cancelable=false
+        }={}
+    ){
+        if(destroyed&&type!=='speech-transcription-cancelled'){
+            return false;
+        }
+        if(beginOperation!==null){
+            voiceOperationId=nextVoiceOperationId(beginOperation);
+        }
+        const publication=events.dispatch(
+            type,
+            compatibilityDetail,
+            {
+                publicDetail,
+                operationId:operationId||currentVoiceOperationId(),
+                cancelable
+            }
+        );
+        if(!publication.accepted){
+            return false;
+        }
+        return projectArcaneDOMEvent(
+            host,
+            publication.occurrence,
+            {
+                bubbles,
+                composed,
+                cancelable
+            }
+        );
+    }
+
     host.clear=clear;
     host.completeTranscription=completeStream;
     host.configure=configure;
@@ -92,6 +189,10 @@
     host.reset=clear;
     host.startRecording=startRecording;
     host.stopRecording=stopRecording;
+    host.requestSTTActivation=host.requestSTTActivation
+        ||function requestSTTActivation(intent){
+            return requestAIRuntimeIntent(intent);
+        };
 
     Object.defineProperties(
         host,
@@ -102,9 +203,50 @@
         }
     );
 
-    startButton.addEventListener('click',startRecording);
-    stopButton.addEventListener('click',stopRecording);
-    completeButton.addEventListener('click',completeStream);
+    const lifecycleListenerOptions=Object.freeze(
+        {signal:runtimeStateAbortController.signal}
+    );
+    startButton.addEventListener('click',startRecording,lifecycleListenerOptions);
+    stopButton.addEventListener('click',stopRecording,lifecycleListenerOptions);
+    completeButton.addEventListener('click',completeStream,lifecycleListenerOptions);
+    window.addEventListener(
+        'pagehide',
+        destroy,
+        {once:true,signal:runtimeStateAbortController.signal}
+    );
+
+    const sttActivationController=createSTTActivationController(
+        {
+            host,
+            button:sttActivationButton,
+            onChange:renderState,
+            eventSource:events
+        }
+    );
+
+    function unavailableRole(role){
+        return Object.freeze(
+            {
+                role,
+                state:'unavailable',
+                providerId:null,
+                modelId:null,
+                localOnly:null,
+                loaded:false,
+                busy:false,
+                operationId:null,
+                progress:null,
+                error:null
+            }
+        );
+    }
+
+    function canStartVoiceRecording(role,workflowState,componentDestroyed){
+        return !componentDestroyed
+            &&role?.state==='ready'
+            &&!role.busy
+            &&['idle','error'].includes(workflowState);
+    }
 
     function optionsFromDataset(){
         const dataset=host.dataset||{};
@@ -129,19 +271,31 @@
     }
 
     function configure(input={}){
+        if(destroyed){
+            return getOptions();
+        }
         const setInitial=Object.prototype.hasOwnProperty.call(input||{},'initialValue');
-        options=normalizeVoiceOptions(input,options);
+        const nextOptions=normalizeVoiceOptions(input,options);
+        if(!setInitial){
+            if(supersedeForConfigurationReplacement()){
+                reportSTTCancellation(
+                    'configuration-replaced',
+                    'Transcription configuration replaced.'
+                );
+            }
+        }
+        options=nextOptions;
         renderOptions();
         if(setInitial){
             setValue(options.initialValue);
         }else{
-            setState(state,status.innerText);
+            renderState();
         }
         return getOptions();
     }
 
     async function startRecording(){
-        if(!['idle','error'].includes(state)){
+        if(!canStartVoiceRecording(sttRole,state,destroyed)){
             return false;
         }
         if(
@@ -152,41 +306,84 @@
             return false;
         }
 
-        setState('starting',options.messages.requesting);
-        chunks=[];
         const generation=++sessionGeneration;
+        chunks=[];
+        setState('starting',options.messages.requesting,{
+            beginOperation:'transcription'
+        });
+        if(!recordingStartIsCurrent(generation,'starting')){
+            return rejectRecordingStart(generation);
+        }
         try{
             const stream=await navigator.mediaDevices.getUserMedia(
                 options.mediaConstraints
             );
-            if(generation!==sessionGeneration){
-                for(const track of stream.getTracks()){
-                    track.stop();
-                }
-                return false;
+            if(!recordingStartIsCurrent(generation,'starting')){
+                return rejectRecordingStart(generation,stream);
             }
             mediaStream=stream;
-            recorder=createRecorder(mediaStream);
-            recorder.addEventListener('dataavailable',collectAudio);
-            recorder.addEventListener('stop',finishRecording,{once:true});
-            recorder.addEventListener('error',recordingError,{once:true});
+            const activeRecorder=createRecorder(mediaStream);
+            recorder=activeRecorder;
+            activeRecorder.addEventListener('dataavailable',collectAudio);
+            activeRecorder.addEventListener('stop',finishRecording,{once:true});
+            activeRecorder.addEventListener('error',recordingError,{once:true});
             for(const track of mediaStream.getAudioTracks()){
                 track.addEventListener('ended',recordingInterrupted,{once:true});
             }
-            recorder.start();
+            activeRecorder.start();
+            if(!recordingStartIsCurrent(generation,'starting')
+                ||recorder!==activeRecorder){
+                return rejectAssignedRecordingStart(generation,stream);
+            }
             setState('recording',options.messages.recording);
+            if(!recordingStartIsCurrent(generation,'recording')
+                ||recorder!==activeRecorder){
+                return rejectAssignedRecordingStart(generation,stream);
+            }
             return true;
         }catch(error){
-            if(generation!==sessionGeneration){
+            if(generation!==sessionGeneration||destroyed){
                 return false;
             }
             releaseMicrophone();
-            setState('error',options.messages.startError);
             console.error('Unable to start recording:',error);
+            setState('error',options.messages.startError);
             return false;
         }
     }
 
+    function recordingStartIsCurrent(generation,expectedState){
+        return isCurrentVoiceOperation(generation,expectedState)
+            &&sttRole.state==='ready'
+            &&!sttRole.busy;
+    }
+
+    function isCurrentVoiceOperation(generation,expectedState){
+        return !destroyed
+            &&generation===sessionGeneration
+            &&state===expectedState;
+    }
+
+    function rejectRecordingStart(generation,stream=null){
+        if(mediaStream===stream){
+            releaseMicrophone();
+        }else{
+            stopMediaStream(stream);
+        }
+        if(generation===sessionGeneration
+            &&!destroyed
+            &&['starting','recording'].includes(state)){
+            setState('idle',options.messages.ready);
+        }
+        return false;
+    }
+
+    function rejectAssignedRecordingStart(generation,stream){
+        return mediaStream===stream
+            ?rejectRecordingStart(generation,stream)
+            :false;
+    }
+
     function createRecorder(stream){
         for(const mimeType of options.mimeTypes){
             if(MediaRecorder.isTypeSupported?.(mimeType)){
@@ -203,38 +400,71 @@
     }
 
     function stopRecording(){
-        if(state!=='recording'||recorder?.state!=='recording'){
+        if(destroyed||state!=='recording'||recorder?.state!=='recording'){
             return false;
         }
+        const generation=sessionGeneration;
+        const activeRecorder=recorder;
         setState('transcribing',options.messages.transcribing);
-        recorder.stop();
-        return true;
+        if(!isCurrentVoiceOperation(generation,'transcribing')
+            ||recorder!==activeRecorder
+            ||activeRecorder.state!=='recording'){
+            return false;
+        }
+        activeRecorder.stop();
+        return isCurrentVoiceOperation(generation,'transcribing');
     }
 
     async function finishRecording(){
+        const generation=sessionGeneration;
+        if(!isCurrentVoiceOperation(generation,'transcribing')){
+            return false;
+        }
         const mimeType=recorder?.mimeType||chunks[0]?.type||'audio/webm';
         const audio=new Blob(chunks,{type:mimeType});
+        let controller=null;
         releaseMicrophone();
         if(!audio.size){
             setState('error',options.messages.emptyAudio);
             return false;
         }
+        if(sttRole.state!=='ready'||sttRole.busy){
+            reportSTTCancellation(
+                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;
+        }
 
         try{
+            controller=new AbortController();
+            transcriptionAbortController?.abort();
+            transcriptionAbortController=controller;
             const file=new File(
                 [audio],
                 `audio.${fileExtension(mimeType)}`,
                 {type:mimeType}
             );
-            const transcribe=await getTranscriber();
-            const result=await transcribe(
+            const result=await transcribeAudio(
                 file,
                 {
                     audio,
                     mimeType,
-                    transcript
-                }
+                    transcript,
+                    signal:controller.signal
+                },
+                controller.signal
             );
+            releaseTranscriptionController(controller);
+            if(controller.signal.aborted
+                ||generation!==sessionGeneration
+                ||sttRole.state!=='ready'
+                ||sttRole.busy
+                ||destroyed){
+                return false;
+            }
             const segment=typeof result==='string'?result.trim():'';
             if(!segment){
                 setState('idle',options.messages.noSpeech);
@@ -257,51 +487,128 @@
                     return false;
                 }
                 setState('saving',options.messages.saving);
+                if(!isCurrentVoiceOperation(generation,'saving')){
+                    return false;
+                }
                 try{
                     await save({transcript,segment});
                 }catch(error){
-                    setState('error',options.messages.saveError);
+                    if(!isCurrentVoiceOperation(generation,'saving')){
+                        return false;
+                    }
                     console.error('Unable to save transcription:',error);
+                    setState('error',options.messages.saveError);
                     return false;
                 }
             }
 
+            const successState=options.persist?'saving':'transcribing';
             const detail={text:segment,transcript};
-            host.dispatchEvent(
-                new CustomEvent(
-                    'speech-transcription-complete',
-                    {bubbles:true,composed:true,detail}
-                )
-            );
-            host.dispatchEvent(
-                new CustomEvent(
-                    'voice-transcription-segment',
-                    {bubbles:true,composed:true,detail}
-                )
-            );
-            setState(
-                'idle',
-                options.persist?options.messages.saved:options.messages.transcribed
+            return reportTranscriptionSuccess(
+                generation,
+                successState,
+                detail,
+                options.persist
+                    ?options.messages.saved
+                    :options.messages.transcribed,
+                currentVoiceOperationId()
             );
-            return true;
         }catch(error){
-            setState('error',options.messages.transcribeError);
+            if(generation!==sessionGeneration||destroyed){
+                return false;
+            }
+            if(isTranscriptionCancellation(error,controller)){
+                releaseTranscriptionController(controller);
+                reportSTTCancellation(
+                    'stt-provider-request-cancelled',
+                    options.messages.cancelled
+                );
+                return false;
+            }
             console.error('Unable to transcribe recording:',error);
+            setState('error',options.messages.transcribeError);
             return false;
+        }finally{
+            releaseTranscriptionController(controller);
         }
     }
 
-    async function getTranscriber(){
+    function reportTranscriptionSuccess(
+        generation,
+        expectedState,
+        detail,
+        message,
+        operationId=null
+    ){
+        if(!isCurrentVoiceOperation(generation,expectedState)){
+            return false;
+        }
+        dispatchVoiceEvent(
+            'speech-transcription-complete',
+            detail,
+            {
+                bubbles:true,
+                composed:true,
+                operationId,
+                publicDetail:{
+                    segmentCharacterCount:detail.text.length,
+                    transcriptCharacterCount:detail.transcript.length
+                }
+            }
+        );
+        if(!isCurrentVoiceOperation(generation,expectedState)){
+            return false;
+        }
+        dispatchVoiceEvent(
+            'voice-transcription-segment',
+            detail,
+            {
+                bubbles:true,
+                composed:true,
+                operationId,
+                publicDetail:{
+                    segmentCharacterCount:detail.text.length,
+                    transcriptCharacterCount:detail.transcript.length
+                }
+            }
+        );
+        if(!isCurrentVoiceOperation(generation,expectedState)){
+            return false;
+        }
+        setState('idle',message);
+        return isCurrentVoiceOperation(generation,'idle');
+    }
+
+    function releaseTranscriptionController(controller){
+        if(transcriptionAbortController!==controller){
+            return false;
+        }
+        transcriptionAbortController=null;
+        return true;
+    }
+
+    async function transcribeAudio(file,context,signal){
         if(options.transcribe){
-            return options.transcribe;
+            return options.transcribe(file,context);
         }
         if(typeof globalThis.ai?.fetchSTT!=='function'){
-            await import(moduleURL('AI.js?v=7'));
+            await import(moduleURL('AI.js'));
         }
         if(typeof globalThis.ai?.fetchSTT!=='function'){
-            throw new Error('Speech transcription is not configured.');
+            const error=new Error('Speech transcription is not configured.');
+            error.code='ARCANE_VOICE_TRANSCRIPTION_STT_RUNTIME_METHOD_UNAVAILABLE';
+            throw error;
         }
-        return globalThis.ai.fetchSTT.bind(globalThis.ai);
+        return globalThis.ai.fetchSTT(file,undefined,signal);
+    }
+
+    function isTranscriptionCancellation(error,controller){
+        return controller?.signal.aborted
+            ||error?.name==='AbortError'
+            ||[
+                'ARCANE_AI_REQUEST_ABORTED',
+                'ARCANE_AI_OPERATION_SUPERSEDED'
+            ].includes(error?.code);
     }
 
     function fileExtension(mimeType=''){
@@ -330,57 +637,121 @@
     }
 
     async function completeStream(){
-        if(!transcript.trim()||!['idle','error'].includes(state)){
+        if(destroyed||!transcript.trim()||!['idle','error'].includes(state)){
+            return false;
+        }
+        const generation=sessionGeneration;
+        const completionTranscript=transcript;
+        const complete=options.onComplete||(
+            typeof host.complete==='function'?host.complete.bind(host):null
+        );
+        setState('completing',options.messages.completing,{
+            beginOperation:'completion'
+        });
+        if(!isCurrentVoiceOperation(generation,'completing')){
             return false;
         }
-        setState('completing',options.messages.completing);
         try{
-            const complete=options.onComplete||(
-                typeof host.complete==='function'?host.complete.bind(host):null
-            );
             if(complete){
-                await complete({transcript});
+                await complete({transcript:completionTranscript});
             }
-            host.dispatchEvent(
-                new CustomEvent(
-                    'voice-transcription-complete',
-                    {
-                        bubbles:true,
-                        composed:true,
-                        detail:{transcript}
+            if(!isCurrentVoiceOperation(generation,'completing')){
+                return false;
+            }
+            dispatchVoiceEvent(
+                'voice-transcription-complete',
+                {transcript:completionTranscript},
+                {
+                    bubbles:true,
+                    composed:true,
+                    publicDetail:{
+                        transcriptCharacterCount:completionTranscript.length
                     }
-                )
+                }
             );
+            if(!isCurrentVoiceOperation(generation,'completing')){
+                return false;
+            }
             setState('complete',options.messages.complete);
-            return true;
+            return isCurrentVoiceOperation(generation,'complete');
         }catch(error){
-            setState('error',options.messages.completeError);
+            if(!isCurrentVoiceOperation(generation,'completing')){
+                return false;
+            }
             console.error('Unable to complete transcription:',error);
+            setState('error',options.messages.completeError);
             return false;
         }
     }
 
+    function supersedeForTranscriptReplacement(){
+        const hadActiveOperation=[
+            'starting',
+            'transcribing',
+            'saving',
+            'completing'
+        ].includes(state)||Boolean(transcriptionAbortController);
+        if(!hadActiveOperation){
+            return false;
+        }
+        sessionGeneration+=1;
+        transcriptionAbortController?.abort();
+        transcriptionAbortController=null;
+        releaseMicrophone();
+        return true;
+    }
+
+    function supersedeForConfigurationReplacement(){
+        const hadActiveOperation=[
+            'starting',
+            'recording',
+            'transcribing',
+            'saving',
+            'completing'
+        ].includes(state)||Boolean(transcriptionAbortController);
+        if(!hadActiveOperation){
+            return false;
+        }
+        sessionGeneration+=1;
+        transcriptionAbortController?.abort();
+        transcriptionAbortController=null;
+        releaseMicrophone();
+        return true;
+    }
+
     function setValue(value=''){
+        if(destroyed){
+            return transcript;
+        }
+        const operationSuperseded=
+            supersedeForTranscriptReplacement();
         transcript=`${value??''}`;
         renderTranscript();
-        if(state!=='recording'){
+        if(operationSuperseded){
+            reportSTTCancellation(
+                'transcript-replaced',
+                options.messages.transcriptReplaced
+            );
+        }else if(state!=='recording'){
             setState('idle',options.messages.ready);
         }
-        host.dispatchEvent(
-            new CustomEvent(
-                'voice-transcription-change',
-                {
-                    bubbles:true,
-                    composed:true,
-                    detail:{transcript}
+        dispatchVoiceEvent(
+            'voice-transcription-change',
+            {transcript},
+            {
+                beginOperation:'transcript-change',
+                bubbles:true,
+                composed:true,
+                publicDetail:{
+                    transcriptCharacterCount:transcript.length
                 }
-            )
+            }
         );
         return transcript;
     }
 
     function clear(){
-        if(!['complete','error','idle'].includes(state)){
+        if(destroyed||!['complete','error','idle'].includes(state)){
             return false;
         }
         transcript='';
@@ -412,39 +783,185 @@
     }
 
     function releaseMicrophone(){
-        const tracks=mediaStream?.getTracks?.()||[];
+        const stream=mediaStream;
         recorder?.removeEventListener('dataavailable',collectAudio);
         recorder?.removeEventListener('stop',finishRecording);
         recorder?.removeEventListener('error',recordingError);
+        if(recorder?.state==='recording'){
+            recorder.stop();
+        }
         mediaStream=null;
         recorder=null;
         chunks=[];
+        stopMediaStream(stream);
+    }
+
+    function stopMediaStream(stream){
+        const tracks=stream?.getTracks?.()||[];
         for(const track of tracks){
             track.removeEventListener('ended',recordingInterrupted);
             track.stop();
         }
     }
 
-    function setState(nextState,message=''){
+    function setState(nextState,message='',{beginOperation=null}={}){
+        if(destroyed){
+            return false;
+        }
+        if(beginOperation!==null){
+            voiceOperationId=nextVoiceOperationId(beginOperation);
+        }
         state=nextState;
-        status.innerText=message||nextState;
+        stateMessage=message||nextState;
+        renderState();
+        return true;
+    }
+
+    function synchronizeAIRuntimeState(snapshot){
+        const previousRole=sttRole;
+        sttRole=snapshot.roles.stt;
+        sttActivationController.synchronize(sttRole);
+        if(previousRole.state==='ready'&&sttRole.state!=='ready'){
+            if(cancelSTTOperation('runtime-unready')){
+                return;
+            }
+        }
+        renderState();
+    }
+
+    function cancelSTTOperation(reason){
+        const hadActiveOperation=['starting','recording','transcribing'].includes(state)
+            ||Boolean(mediaStream)
+            ||Boolean(recorder)
+            ||Boolean(transcriptionAbortController);
+        if(!hadActiveOperation){
+            return false;
+        }
+        sessionGeneration+=1;
+        transcriptionAbortController?.abort();
+        transcriptionAbortController=null;
+        releaseMicrophone();
+        reportSTTCancellation(
+            reason,
+            'Transcription stopped because the selected service became unavailable.'
+        );
+        return true;
+    }
+
+    function reportSTTCancellation(reason,message,operationId=null){
+        state='idle';
+        stateMessage=message;
+        dispatchVoiceEvent(
+            'speech-transcription-cancelled',
+            Object.freeze({reason}),
+            {
+                bubbles:true,
+                composed:true,
+                operationId:operationId||currentVoiceOperationId(),
+                publicDetail:{reason:canonicalSTTCancellationReason(reason)}
+            }
+        );
+        if(!destroyed){
+            renderState();
+        }
+    }
+
+    function renderState(){
+        status.innerText=runtimeStatusMessage();
         status.classList.toggle('recording',state==='recording');
-        startButton.disabled=!['idle','error'].includes(state);
+        status.setAttribute(
+            'aria-busy',
+            String(
+                !destroyed
+                &&(
+                    sttActivationController.pending
+                    ||['loading','unloading'].includes(sttRole.state)
+                    ||sttRole.busy
+                    ||['starting','transcribing','saving','completing'].includes(state)
+                )
+            )
+        );
+        startButton.disabled=!canStartVoiceRecording(sttRole,state,destroyed);
+        startButton.title=recordingButtonTitle();
+        startButton.setAttribute('aria-label',startButton.title);
         stopButton.disabled=state!=='recording';
-        completeButton.disabled=!transcript.trim()
+        completeButton.disabled=destroyed
+            ||!transcript.trim()
             ||!['idle','error'].includes(state);
-        host.dispatchEvent(
-            new CustomEvent(
-                'voice-transcription-state',
+        sttActivationButton.hidden=destroyed||!sttActivationController.visible;
+        sttActivationButton.disabled=destroyed
+            ||sttActivationController.pending
+            ||sttRole.state==='unloading'
+            ||sttActivationController.action===null;
+        sttActivationButton.textContent=sttActivationController.label;
+        sttActivationButton.title=sttActivationController.title;
+        sttActivationButton.setAttribute('aria-label',sttActivationButton.title);
+        sttActivationButton.setAttribute(
+            'aria-busy',
+            String(
+                sttActivationController.pending
+                ||['loading','unloading'].includes(sttRole.state)
+            )
+        );
+        dispatchVoiceEvent(
+            'voice-transcription-state',
+            Object.freeze(
                 {
-                    bubbles:true,
-                    composed:true,
-                    detail:{message:status.innerText,state}
+                    message:status.innerText,
+                    state,
+                    stt:sttRole
                 }
-            )
+            ),
+            {
+                bubbles:true,
+                composed:true,
+                publicDetail:{
+                    state,
+                    sttState:sttRole.state
+                }
+            }
         );
     }
 
+    function recordingButtonTitle(){
+        if(destroyed||sttRole.state==='disposed'){
+            return 'Transcription is unavailable.';
+        }
+        if(sttRole.state==='loading'){
+            return 'The selected transcription service is loading.';
+        }
+        if(sttRole.state==='error'){
+            return visibleErrorMessage(
+                sttRole.error,
+                'The selected transcription service reported an error.'
+            );
+        }
+        if(sttRole.state!=='ready'){
+            return 'The selected transcription service is unavailable.';
+        }
+        if(sttRole.busy){
+            return 'The selected transcription service is busy.';
+        }
+        return options.labels.start;
+    }
+
+    function runtimeStatusMessage(){
+        if(destroyed){
+            return 'Transcription unavailable.';
+        }
+        return sttRole.state==='ready'
+            &&!sttRole.busy
+            &&!sttActivationController.pending
+            &&!sttActivationController.error
+                ?stateMessage
+                :sttActivationController.status;
+    }
+
+    function visibleErrorMessage(error,fallback){
+        const message=typeof error?.message==='string'?error.message.trim():'';
+        return (message||fallback).slice(0,240);
+    }
+
     function getOptions(){
         return {
             ...options,
@@ -456,9 +973,21 @@
     }
 
     function destroy(){
-        sessionGeneration++;
-        releaseMicrophone();
-        setState('idle',options.messages.ready);
+        if(destroyed){
+            return true;
+        }
+        destroyed=true;
+        runtimeStateAbortController.abort();
+        sttActivationController.destroy();
+        window.removeEventListener('pagehide',destroy);
+        if(!cancelSTTOperation('component-destroyed')){
+            sessionGeneration++;
+        }
+        state='idle';
+        stateMessage='Transcription unavailable.';
+        host.ready=false;
+        renderState();
+        events.dispose();
         return true;
     }
 
@@ -466,11 +995,23 @@
     transcript=options.initialValue;
     renderTranscript();
     setState('idle',options.messages.ready);
-    host.ready=true;
-    host.dispatchEvent(
-        new CustomEvent(
+    if(!destroyed){
+        subscribeAIRuntimeState(
+            synchronizeAIRuntimeState,
+            {signal:runtimeStateAbortController.signal}
+        );
+    }
+    if(!destroyed){
+        host.ready=true;
+        dispatchVoiceEvent(
             'voice-transcription-ready',
-            {bubbles:true,composed:true}
-        )
-    );
+            {},
+            {
+                beginOperation:'ready',
+                bubbles:true,
+                composed:true,
+                publicDetail:{ready:true}
+            }
+        );
+    }
 </script>