@jskit-ai/assistant-voice 0.1.3 → 0.1.5

package/src/client/VoiceConversationSettings.vue

@@ -0,0 +1,52 @@
+<script setup>
+import { mdiCog } from "@mdi/js";
+import { useSlots } from "vue";
+
+const props = defineProps({
+  voice: { type: Object, default: null },
+  compact: Boolean
+});
+const emit = defineEmits(["error"]);
+const slots = useSlots();
+function selectVoice(value) {
+  const selectedVoice = props.voice.selectedVoice;
+  selectedVoice.value = value;
+}
+async function openSettings(open) {
+  if (!open || slots.default || !props.voice) return;
+  try { await props.voice.connect(); }
+  catch (error) { emit("error", error); }
+}
+</script>
+
+<template>
+  <v-menu :close-on-content-click="false" location="bottom end" @update:model-value="openSettings">
+    <template #activator="{ props: settingsButton }">
+      <v-btn
+        v-bind="settingsButton" :icon="mdiCog" variant="text" :color="compact ? 'primary' : undefined"
+        :width="compact ? 40 : undefined" :min-width="compact ? 40 : 48" :min-height="compact ? 44 : 48" :disabled="!voice && !$slots.default"
+        aria-label="Voice settings" title="Voice settings"
+      >
+        <template v-if="compact" #default><span class="voice-settings__disc"><v-icon size="20" :icon="mdiCog" /></span></template>
+      </v-btn>
+    </template>
+    <v-card class="voice-settings__menu" role="region" aria-label="Voice settings">
+      <v-card-text>
+        <slot :voice="voice">
+          <v-select
+            v-if="voice" :model-value="voice.selectedVoice.value" @update:model-value="selectVoice"
+            :items="voice.availableVoices.value" item-title="label" item-value="id"
+            :disabled="voice.availableVoices.value.length < 2"
+            label="Speaking voice" density="comfortable"
+            hint="Applies to the next spoken reply" persistent-hint
+          />
+        </slot>
+      </v-card-text>
+    </v-card>
+  </v-menu>
+</template>
+
+<style scoped>
+.voice-settings__menu { width: 320px; max-width: calc(100vw - 32px); }
+.voice-settings__disc { display: inline-flex; align-items: center; justify-content: center; width: 32px; height: 32px; border-radius: 50%; background: rgba(var(--v-theme-primary), .12); }
+</style>

package/src/client/index.js

@@ -4,6 +4,7 @@ export { default as VoiceConversationHost } from "./VoiceConversationHost.vue";
 export { default as ConversationDialog } from "./ConversationDialog.vue";
 export { default as VoiceConversation } from "./VoiceConversation.vue";
 export { default as VoiceConversationControls } from "./VoiceConversationControls.vue";
+export { default as VoiceConversationSettings } from "./VoiceConversationSettings.vue";
 
 export { useVoiceLauncher } from "./voiceLauncher.js";
 export { useVoiceAvatar } from "./voiceAvatar.js";

package/src/client/voiceConversation.js

@@ -6,12 +6,16 @@ import { takeStreamingSpeech } from "../shared/protocol.js";
 export function useVoiceConversation(binding, { socketUrl, createTransport = useVoiceTransport } = {}) {
   const oneOffTalkMode = computed(() => binding.defaults?.talkMode === "hold" ? "hold" : "tap");
   const targetLabel = computed(() => binding.label || "Assistant");
-  const readAloud = ref(false);
+  const readAloud = ref(binding.defaults?.readAloud === true);
+  const soundPreparing = ref(false);
+  let soundRevision = 0;
+  const conversationId = binding.conversationId || binding.id;
   const error = ref("");
   const pendingTranscript = ref(null);
   const heldReview = ref(false);
   const holding = ref(false);
   const sending = ref(false);
+  const takingTranscript = ref(false);
   const live = ref(false);
   const starting = ref(false);
   const callMode = ref(binding.defaults?.mode === "hands-free" ? "hands-free" : "push-to-talk");
@@ -27,7 +31,8 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     voiceId: binding.defaults?.voiceId || "",
     speechEnabled: readAloud,
     interruptSpeechOnListen: false,
-    autoReconnect: true
+    autoReconnect: true,
+    onPlayback: receivePlayback
   });
   watch([() => binding.defaults?.voiceId, voice.availableVoices], ([voiceId, voices]) => {
     if (voiceId === undefined) return;
@@ -106,12 +111,42 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
   let speechInvitation = "";
   let lastStreamingId = "";
 
-  function stopSpeech() {
-    for (const reply of speechQueue) reply.cancelled = true;
+  function observe(callback, value) {
+    try {
+      Promise.resolve(callback?.(value)).catch(() => {});
+    } catch {
+      // Observers cannot take ownership of scheduling or cleanup.
+    }
+  }
+  function emitReply(reply, phase, reason) {
+    if (reply.terminal || (phase === "started" && reply.audible)) return;
+    if (phase === "started") reply.audible = true;
+    else reply.terminal = true;
+    observe(binding.onPlayback, {
+      conversationId, outputId: reply.outputId, phase, ...(reason ? { reason } : {})
+    });
+  }
+  function receivePlayback(event) {
+    const reply = [...replies.values()].find(reply => reply.turnId === event.turnId);
+    if (!reply) return;
+    if (event.phase === "completed") {
+      reply.drained = true;
+      if (reply.canonicalFinal) emitReply(reply, "completed");
+    } else emitReply(reply, event.phase, event.reason);
+  }
+  function cancelReply(reply, reason = "cancelled", phase = "interrupted") {
+    reply.cancelled = true;
+    emitReply(reply, phase, reason);
+  }
+  function stopSpeech() { cancelSpeech(); }
+  function cancelSpeech(reason = "cancelled", phase = "interrupted") {
+    for (const reply of replies.values()) {
+      if (!reply.terminal) cancelReply(reply, reason, phase);
+    }
     speechQueue.length = 0;
     speechSuppressed = true;
     speechInvitation = "";
-    voice.stopSpeaking();
+    voice.stopSpeaking(reason);
   }
   function inviteSpeech(messageId) {
     // Only a new request from this page can lift silence. A delayed admission,
@@ -121,7 +156,7 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     speechInvitation = messageId;
   }
   async function drainSpeech() {
-    if (draining || disposed || !readAloud.value || speechSuppressed) return;
+    if (draining || disposed || !readAloud.value || speechSuppressed || soundPreparing.value || voice.playbackBlocked?.value) return;
     draining = true;
     try {
       while (speechQueue.length) {
@@ -133,15 +168,24 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
         const chunk = takeStreamingSpeech(reply.raw.slice(reply.consumed), reply.final, reply.started ? 140 : 64);
         if (!chunk) {
           if (reply.final && reply.started) voice.endSpeech();
-          else if (reply.final) { speechQueue.shift(); continue; }
+          else if (reply.final) {
+            cancelReply(reply, "no-audio");
+            speechQueue.shift();
+            continue;
+          }
           return;
         }
         reply.consumed += chunk.consumed;
         if (!chunk.text) continue;
         if (!reply.started) {
           reply.started = true;
-          await voice.speak(chunk.text, crypto.randomUUID(), { stream: true });
+          reply.turnId = crypto.randomUUID();
+          const accepted = await voice.speak(chunk.text, reply.turnId, { stream: true });
           if (reply.cancelled || disposed) return;
+          if (accepted === false) {
+            cancelReply(reply, "no-audio");
+            continue;
+          }
         } else if (!voice.appendSpeech(chunk.text)) return;
         if (reply.final && reply.consumed >= reply.raw.length) { voice.endSpeech(); return; }
       }
@@ -152,7 +196,10 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     let reply = replies.get(message.id);
     if (!reply) {
       if (!primed || !readAloud.value || speechSuppressed || seen.has(message.id) || (!final && message.autonomous)) return;
-      reply = { id: message.id, streamId: message.streamId, raw: "", consumed: 0, final: false, started: false };
+      reply = {
+        id: message.id, outputId: message.outputId || message.id, streamId: message.streamId,
+        raw: "", consumed: 0, final: false, canonicalFinal: false, started: false
+      };
       replies.set(message.id, reply);
       speechQueue.push(reply);
     }
@@ -162,25 +209,43 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     if (!text.startsWith(spokenPrefix) && !(final && text.trimEnd() === spokenPrefix.trimEnd())) {
       // A model revision cannot unsay words. Retire that projection; never splice
       // its old prefix onto a different answer or replay it as a second answer.
-      reply.cancelled = true;
+      cancelReply(reply);
       if (speechQueue[0] === reply) voice.stopSpeaking();
       return;
     }
     reply.consumed = Math.min(reply.consumed, text.length);
     reply.raw = text;
+    reply.canonicalFinal ||= final;
     reply.final = final || text.length >= 4000;
+    if (reply.canonicalFinal && reply.drained) emitReply(reply, "completed");
   }
-  async function enableSpeech() {
-    speechSuppressed = false;
-    speechInvitation = "";
-    await voice.preparePlayback();
-    readAloud.value = true;
+  async function enableSound() {
+    const revision = ++soundRevision;
+    soundPreparing.value = true;
+    try {
+      await voice.preparePlayback();
+    } catch {
+      // Requested sound stays on; its recovery control remains available.
+    } finally {
+      if (revision === soundRevision && !disposed) {
+        soundPreparing.value = false;
+        void drainSpeech();
+      }
+    }
   }
   async function toggleReadAloud() {
     error.value = "";
-    if (readAloud.value) { readAloud.value = false; stopSpeech(); return; }
-    try { await enableSpeech(); }
-    catch (cause) { error.value = cause.message; }
+    readAloud.value = !readAloud.value;
+    observe(binding.onReadAloudChange, readAloud.value);
+    if (!readAloud.value) {
+      ++soundRevision;
+      soundPreparing.value = false;
+      cancelSpeech("muted");
+      return;
+    }
+    speechSuppressed = false;
+    speechInvitation = "";
+    await enableSound();
   }
   async function deliverTranscript() {
     const pending = pendingTranscript.value;
@@ -199,6 +264,7 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     startupAbort?.abort();
     startupAbort = null;
     starting.value = false;
+    releaseEditCapturePause();
     recording = null;
     await voice.cancelListening();
   }
@@ -209,11 +275,21 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     await cancelRecording();
   }
   function dismissTranscript() {
+    releaseEditCapturePause();
     pendingTranscript.value = null;
     heldReview.value = false;
     holding.value = false;
     error.value = "";
   }
+  function releaseEditCapturePause() {
+    const pending = pendingTranscript.value;
+    const captureId = pending?.editPausedCaptureId;
+    if (!captureId) return;
+    delete pending.editPausedCaptureId;
+    if (recording?.messageId === captureId && !disposed && live.value && callMode.value === "hands-free") {
+      voice.setMicrophoneMuted(false);
+    }
+  }
   async function talk() {
     error.value = "";
     try {
@@ -224,7 +300,8 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     } catch (cause) { recording = null; error.value = cause.message; }
   }
   async function startRecording(reviewBeforeSend, continuous = false) {
-    if (disposed || starting.value || microphoneMuted.value || capturing.value || pendingTranscript.value || sending.value) return;
+    if (disposed || starting.value || microphoneMuted.value || capturing.value || committing ||
+        (pendingTranscript.value || sending.value) && !(continuous && live.value && (callMode.value === "hands-free" || pushHolding.value))) return;
     error.value = "";
     reviewBeforeSend ||= binding.defaults?.reviewBeforeSend === true;
     heldReview.value = reviewBeforeSend;
@@ -232,20 +309,19 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     // Keep the starting target even if navigation changes during this utterance.
     const next = { focus: { ...(binding.captureContext?.() || {}) }, messageId: crypto.randomUUID(), started: false, reviewBeforeSend, continuous };
     recording = next;
-    if (!reviewBeforeSend && !live.value) {
-      readAloud.value = true;
-      void voice.preparePlayback().catch((cause) => { error.value = cause.message; });
-    }
     try {
       const started = await voice.startListening({ continuous });
       if (recording === next) { next.started = started; if (!started) recording = null; }
     } catch (cause) { if (recording === next) { recording = null; error.value = cause.message; } }
   }
   async function toggleMicrophoneMuted() {
+    // A person's explicit microphone choice supersedes an Edit-owned pause.
+    if (pendingTranscript.value) delete pendingTranscript.value.editPausedCaptureId;
     voice.setMicrophoneMuted(!microphoneMuted.value);
+    if (!microphoneMuted.value && recording) delete recording.finishAfterPending;
     clearTimeout(stopTimer);
     if (microphoneMuted.value && starting.value) await cancelRecording();
-    else if (!microphoneMuted.value && live.value && callMode.value === "hands-free" && !capturing.value && !pendingTranscript.value && !sending.value) await startRecording(false, true);
+    else if (!microphoneMuted.value && live.value && callMode.value === "hands-free" && !capturing.value) await startRecording(false, true);
   }
   async function changeCallMode(mode) {
     if (!["push-to-talk", "hands-free"].includes(mode) || mode === callMode.value || callModeBusy.value || committing) return;
@@ -258,13 +334,13 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
   }
   async function startPushToTalk(event) {
     if (event?.repeat || event?.isPrimary === false || event?.button !== undefined && event.button !== 0 || pushHolding.value || disposed || starting.value
-      || capturing.value && !voice.listening.value || pendingTranscript.value || sending.value || committing) return;
+      || capturing.value && !voice.listening.value || committing) return;
     if (event?.pointerId !== undefined) event.currentTarget.setPointerCapture(event.pointerId);
     pushInput = event?.pointerId ?? event?.key ?? null;
     pushHolding.value = true;
     callMode.value = "push-to-talk";
     voice.setMicrophoneMuted(false);
-    retireAnswer(true);
+    if (recording) delete recording.finishAfterPending;
     if (!live.value) await toggleLive();
     if (!pushHolding.value || !live.value || disposed) return;
     // A hold can take over an open hands-free microphone without throwing away
@@ -273,7 +349,7 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
       recording.continuous = false;
       return;
     }
-    await startRecording(false);
+    await startRecording(false, Boolean(pendingTranscript.value || sending.value));
     if (!recording) pushHolding.value = false;
   }
   async function finishPushToTalk(event) {
@@ -281,6 +357,11 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     pushHolding.value = false;
     pushInput = null;
     try {
+      if (voice.listening.value && (pendingTranscript.value || sending.value || committing)) {
+        if (recording) recording.finishAfterPending = true;
+        voice.setMicrophoneMuted(true);
+        return;
+      }
       if (voice.listening.value) await voice.stopListening();
       else await cancelRecording();
     } catch (cause) { await cancelRecording(); error.value = cause.message; }
@@ -292,7 +373,15 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     await cancelRecording();
   }
   async function toggleHandsFree() {
-    if (disposed || pushHolding.value || pendingTranscript.value || sending.value || committing) return;
+    if (disposed || pushHolding.value) return;
+    if (live.value && callMode.value === "hands-free" && voice.listening.value && (pendingTranscript.value || sending.value || committing)) {
+      // Pause must finish the newer recording after the existing admission,
+      // without replacing the one pending transcript or stopping output.
+      if (!microphoneMuted.value && recording) recording.finishAfterPending = true;
+      await toggleMicrophoneMuted();
+      return;
+    }
+    if (committing) return;
     if (starting.value) { await cancelRecording(); return; }
     if (capturing.value && !voice.listening.value) return;
     if (live.value && callMode.value === "hands-free") {
@@ -301,10 +390,16 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
         // final sound is included; resuming starts a fresh recording.
         await voice.stopListening();
         voice.setMicrophoneMuted(true);
-      } else await toggleMicrophoneMuted();
+      } else if (microphoneMuted.value) await toggleMicrophoneMuted();
+      else await startRecording(false, true);
+      return;
+    }
+    if (callMode.value === "hands-free" && (pendingTranscript.value || sending.value)) {
+      voice.setMicrophoneMuted(false);
+      await toggleLive();
       return;
     }
-    if (callModeBusy.value) return;
+    if (pendingTranscript.value || sending.value || callModeBusy.value) return;
     voice.setMicrophoneMuted(false);
     await changeCallMode("hands-free");
     if (!live.value) await toggleLive();
@@ -318,27 +413,23 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
       committing = null;
       clearTimeout(stopTimer);
       await cancelRecording();
-      stopSpeech();
-      readAloud.value = false;
-      void voice.close().catch(cause => { if (!live.value) error.value = cause.message; });
       return;
     }
-    if (disposed || microphoneMuted.value || capturing.value || pendingTranscript.value || sending.value) return;
+    if (disposed || microphoneMuted.value || capturing.value || committing ||
+        (pendingTranscript.value || sending.value) && callMode.value !== "hands-free" && !pushHolding.value) return;
     const controller = new AbortController();
     startupAbort = controller;
     starting.value = true;
     const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(10000)]);
     try {
-      // Unlock playback in the click gesture. Live capture uses the same model
-      // admission as typed chat and does not need a separate Helper connection.
-      await voice.preparePlayback();
+      // Unlock requested sound in the gesture without delaying microphone startup.
+      if (readAloud.value) void enableSound();
       signal.throwIfAborted();
       await voice.connect();
       signal.throwIfAborted();
       if (disposed) return;
       starting.value = false;
       live.value = true;
-      readAloud.value = true;
       if (callMode.value === "hands-free") {
         await startRecording(false, true);
         if (startupAbort === controller && !recording?.started) live.value = false;
@@ -352,12 +443,6 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
       if (startupAbort === controller) { startupAbort = null; starting.value = false; }
     }
   }
-  function retireAnswer(smooth = false) {
-    for (const reply of speechQueue) reply.cancelled = true;
-    speechQueue.length = 0;
-    if (smooth) voice.finishCurrentPhrase();
-    else voice.stopSpeaking();
-  }
   function currentSpokenText() {
     const reply = speechQueue[0];
     return reply ? reply.raw.slice(0, reply.consumed).slice(-2000) : "";
@@ -367,7 +452,7 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
   }
   function decideTurn() {
     const candidate = voice.endpoint.value;
-    if (!live.value || callMode.value !== "hands-free" || !voice.listening.value || microphoneMuted.value || pendingTranscript.value || sending.value || !candidate) return;
+    if (takingTranscript.value || !live.value || callMode.value !== "hands-free" || !voice.listening.value || microphoneMuted.value || pendingTranscript.value || sending.value || !candidate) return;
     const key = `${candidate.turnId}:${candidate.revision}`;
     if (decidedCandidate === key) return;
     decidedCandidate = key;
@@ -393,9 +478,9 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
       }
       committing = { ...captured, turnId: candidate.turnId, revision: candidate.revision };
       if (!voice.finishUtterance(candidate)) { committing = null; return; }
+      publishTranscript();
       // The daemon rechecks the endpoint revision before returning final text.
-      // Continue the current phrase while the ordinary request steers the conversation.
-      retireAnswer(true);
+      // Ordinary steering leaves the current answer and queued audio intact.
     } catch (cause) {
       if (live.value && candidate === voice.endpoint.value) {
         live.value = false;
@@ -404,7 +489,7 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
       }
     }
   }
-  watch([voice.endpoint, pendingTranscript, sending], decideTurn);
+  watch([voice.endpoint, pendingTranscript, sending, takingTranscript], decideTurn);
   watch(voice.completedUtterance, (utterance) => {
     if (!utterance || !live.value || !committing || committing.turnId !== utterance.turnId || committing.revision !== utterance.revision) return;
     pendingTranscript.value = { ...committing, text: utterance.text };
@@ -415,7 +500,8 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     // A discard can lose a race with resumed speech. Keep this utterance's
     // identity and destination until the daemon acknowledges the boundary.
     if (reset?.turnId !== voice.activeListenTurnId.value || !live.value || !recording) return;
-    recording = { focus: { ...(binding.captureContext?.() || {}) }, messageId: crypto.randomUUID(), started: true, continuous: true };
+    recording = { focus: { ...(binding.captureContext?.() || {}) }, messageId: crypto.randomUUID(), started: true, continuous: true,
+      ...(recording.finishAfterPending ? { finishAfterPending: true } : {}) };
   });
   watch(voice.partialTranscript, (text, previous) => {
     clearTimeout(stopTimer);
@@ -426,7 +512,16 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
       if (live.value && !microphoneMuted.value && voice.partialTranscript.value === text) stopSpeech();
     }, 120);
   });
-  watch([pendingTranscript, sending], () => {
+  watch([pendingTranscript, sending, voice.utteranceReset], () => {
+    if (!disposed && live.value && !pushHolding.value && !changingCallMode.value &&
+        !pendingTranscript.value && !sending.value && !committing && microphoneMuted.value &&
+        recording?.finishAfterPending && voice.listening.value) {
+      // Retire intent before the asynchronous PCM drain so a receipt/reset
+      // cannot finalize this capture twice. Its original final watcher sends B.
+      delete recording.finishAfterPending;
+      void voice.stopListening().catch(cause => { error.value = cause.message; });
+      return;
+    }
     if (live.value && callMode.value === "hands-free" && !changingCallMode.value && !microphoneMuted.value && !capturing.value && !pendingTranscript.value && !sending.value && !voice.error.value) void startRecording(false, true);
   });
   async function startHeldRecording() { await startRecording(true); }
@@ -477,10 +572,12 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     text: binding.state.streamingReply?.text }), ({ messages = [], reply }) => {
     if (!binding.id) return;
     // Reconcile an uncertain send by identity, never by equal transcript text.
-    if (pendingTranscript.value && messages.some((message) => message.role === "user" && message.id === pendingTranscript.value.messageId)) {
+    if (pendingTranscript.value && messages.some((message) => message.role === "user" && message.id === pendingTranscript.value.messageId && message.receipt !== false)) {
       dismissTranscript();
     }
     for (const message of messages) {
+      // Unadmitted local records do not acknowledge a request or lift speech silence.
+      if (message.role === "user" && message.receipt === false) continue;
       if (seen.has(message.id)) continue;
       if (message.role === "user" && message.id === speechInvitation) {
         speechSuppressed = false;
@@ -491,8 +588,8 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     }
     if (lastStreamingId && lastStreamingId !== reply?.id && !messages.some(message => message.id === lastStreamingId)) {
       const retired = replies.get(lastStreamingId);
-      if (retired && !retired.final && !retired.cancelled) {
-        retired.cancelled = true;
+      if (retired && !retired.canonicalFinal && !retired.cancelled) {
+        cancelReply(retired);
         if (speechQueue[0] === retired) voice.finishCurrentPhrase();
       }
     }
@@ -502,22 +599,79 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
       if (!readAloud.value || !primed || reply.autonomous) seen.add(reply.id);
     }
     // Keep only the visible history plus active playback receipts in memory.
-    const retained = new Set([...messages.map((message) => message.id), reply?.id, ...speechQueue.map((item) => item.id)]);
+    const retained = new Set([...messages.map((message) => message.id), reply?.id, ...speechQueue.map((item) => item.id),
+      ...[...replies.values()].filter(item => !item.terminal).map(item => item.id)]);
     for (const id of seen) if (!retained.has(id)) seen.delete(id);
     for (const id of replies.keys()) if (!retained.has(id)) replies.delete(id);
     primed = true;
     void drainSpeech();
   }, { immediate: true });
-  watch(voice.error, (message) => { if (message) stopSpeech(); });
+  watch(voice.error, (message) => { if (message) cancelSpeech("playback-error", "failed"); });
   watch(() => error.value || voice.error.value, (message) => { if (message) binding.onError?.(message); });
   watch([voice.activeSpeechTurnId, voice.canAppendSpeech], () => { void drainSpeech(); });
-  watch([pendingTranscript, voice.captureState, voice.partialTranscript], () => {
+  function currentTranscript() {
     const pending = pendingTranscript.value;
-    const transcript = pending ? { id: pending.messageId, text: pending.text }
-      : recording && ["listening", "transcribing"].includes(voice.captureState.value) && voice.partialTranscript.value
-        ? { id: recording.messageId, text: voice.partialTranscript.value } : null;
-    binding.onTranscript?.(transcript);
-  }, { immediate: true });
+    const currentWords = recording && ["listening", "transcribing"].includes(voice.captureState.value)
+      && voice.partialTranscript.value && recording.messageId !== pending?.messageId;
+    return currentWords ? { id: recording.messageId, text: voice.partialTranscript.value }
+      : pending ? { id: pending.messageId, text: pending.text } : null;
+  }
+  function canTakeTranscript(messageId) {
+    return !disposed && !starting.value && !sending.value && !committing && !takingTranscript.value
+      && (pendingTranscript.value?.messageId === messageId || currentTranscript()?.id === messageId)
+      && !binding.state.messages?.some(message => message.role === "user" && message.id === messageId && message.receipt !== false);
+  }
+  async function beginTranscriptEdit(messageId) {
+    if (!canTakeTranscript(messageId)) return false;
+    const pending = pendingTranscript.value;
+    if (pending && pending.messageId !== messageId) return false;
+    const selected = pending ? { id: pending.messageId, text: pending.text } : currentTranscript();
+    const capture = recording;
+    takingTranscript.value = true;
+    try {
+      // Retain the selected words and destination before cancelling capture.
+      // The existing pending-clear watcher resumes hands-free after resolution.
+      pendingTranscript.value = {
+        ...(pending?.messageId === messageId ? pending : capture),
+        messageId, text: selected.text, reviewBeforeSend: true, editing: true
+      };
+      if (capture) {
+        if (capture.messageId !== messageId && live.value && callMode.value === "hands-free") {
+          // Newer continuous words retain their recording identity and endpoint.
+          if (!microphoneMuted.value) {
+            pendingTranscript.value.editPausedCaptureId = capture.messageId;
+            voice.setMicrophoneMuted(true);
+          }
+        } else if (pushHolding.value) await cancelPushToTalk();
+        else await cancelRecording();
+      }
+      return true;
+    } finally { takingTranscript.value = false; }
+  }
+  async function takeTranscript(messageId, transfer) {
+    if (!canTakeTranscript(messageId)) return false;
+    const pending = pendingTranscript.value;
+    const selected = pending?.messageId === messageId ? { id: messageId, text: pending.text } : currentTranscript();
+    takingTranscript.value = true;
+    try {
+      // The host rechecks its draft and transfers synchronously before cancellation.
+      if (transfer && transfer(selected.text) !== true) return false;
+      if (pendingTranscript.value?.messageId === messageId) dismissTranscript();
+      else if (recording?.messageId === messageId) {
+        if (pushHolding.value) await cancelPushToTalk();
+        else await cancelRecording();
+        if (!disposed && live.value && callMode.value === "hands-free" && !microphoneMuted.value) {
+          await startRecording(false, true);
+        }
+      }
+      return true;
+    } finally { takingTranscript.value = false; }
+  }
+  function publishTranscript() {
+    const transcript = currentTranscript();
+    binding.onTranscript?.(transcript, { canTake: Boolean(transcript && canTakeTranscript(transcript.id)) });
+  }
+  watch([pendingTranscript, voice.captureState, voice.partialTranscript, voice.endpoint, sending, starting, takingTranscript], publishTranscript, { immediate: true });
   watch(avatarVisual, (visual) => binding.onVisual?.(visual), { immediate: true });
   const page = globalThis.window || globalThis;
   const cancelStartup = () => { if (starting.value) void discardRecording(); else void cancelPushToTalk(); };
@@ -527,6 +681,7 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     page.removeEventListener?.("pagehide", cancelStartup);
     page.removeEventListener?.("blur", cancelPushToTalk);
     startupAbort?.abort(); startupAbort = null;
+    stopSpeech();
     binding.onTranscript?.(null); binding.onVisual?.(null); disposed = true; live.value = false; clearTimeout(stopTimer); recording = null; speechQueue.length = 0;
   });
 
@@ -540,18 +695,21 @@ export function useVoiceConversation(binding, { socketUrl, createTransport = use
     stopSpeech();
     await voice.close();
   }
-  function editTranscript(text) {
-    if (pendingTranscript.value && !sending.value) pendingTranscript.value = { ...pendingTranscript.value, text: String(text) };
+  function editTranscript(text, messageId = pendingTranscript.value?.messageId) {
+    if (pendingTranscript.value && pendingTranscript.value.messageId === messageId && !sending.value) pendingTranscript.value = { ...pendingTranscript.value, text: String(text) };
   }
+  const composerBlocked = computed(() => starting.value ||
+    (!live.value || callMode.value !== "hands-free") &&
+      (sending.value || Boolean(pendingTranscript.value) || capturing.value));
   const hasUnsentSpeech = computed(() => capturing.value || starting.value || sending.value || Boolean(pendingTranscript.value));
   return {
     oneOffTalkMode, targetLabel, voice, readAloud, error, pendingTranscript, heldReview, holding, sending,
     live, starting, callMode, changingCallMode, pushHolding, microphoneMuted, capturing,
     speechActive, talkLabel, liveLabel, callConnection, callStatus, callDetail, callModeBusy,
     microphoneStatus, avatarVisual, callAudioLevel, status, heldTranscript, voiceWords, voiceAnswer,
-    stopSpeech, inviteSpeech, toggleReadAloud, deliverTranscript, cancelRecording,
+    stopSpeech, inviteSpeech, toggleReadAloud, enableSound, soundPreparing, deliverTranscript, cancelRecording,
     discardRecording, dismissTranscript, talk, toggleMicrophoneMuted, changeCallMode,
     startPushToTalk, finishPushToTalk, cancelPushToTalk, toggleLive, toggleHandsFree, startHeldRecording,
-    finishHeldRecording, discardHeldRecording, close, editTranscript, hasUnsentSpeech
+    finishHeldRecording, discardHeldRecording, close, editTranscript, canTakeTranscript, beginTranscriptEdit, takeTranscript, hasUnsentSpeech, composerBlocked
   };
 }