clay-server 4.3.1-beta.5 → 4.4.0-beta.1

package/lib/public/modules/stt-controller.js

@@ -0,0 +1,202 @@
+// Shared recognition lifecycle. Recognition callbacks belong to one immutable draft context.
+import { store } from './store.js';
+import { speechTrace } from './stt-debug.js';
+import { startBrowserSpeechSignal } from './stt-signal.js';
+
+export function speechConstructor() {
+  return window.SpeechRecognition || window.webkitSpeechRecognition || null;
+}
+
+export function speechContext() {
+  var s = store.snap();
+  return JSON.stringify([s.currentSlug, s.activeSessionId, s.dmMode, s.dmKey,
+    s.dmTargetUser && s.dmTargetUser.id, s.homePrimarySurface, s.homeSubSurface,
+    s.homeChatMateId, s.homeChatSessionId]);
+}
+
+export function setSpeechStatus(id, message, isError) {
+  var statuses = Object.assign({}, store.get('speechStatuses'));
+  var errors = Object.assign({}, store.get('speechErrors'));
+  statuses[id] = message;
+  errors[id] = isError ? { message: message } : null;
+  store.set({ speechStatuses: statuses, speechErrors: errors });
+}
+
+export function failSTT(message) {
+  var active = store.get('speechActive');
+  if (!active) return;
+  stopSTT(message);
+  setSpeechStatus(active.id, message, true);
+}
+
+export function usableSpeechInput(input) {
+  if (!(input && input.isConnected && !input.disabled && !input.readOnly &&
+      !input.closest('[hidden], .hidden, [aria-hidden="true"]') && input.getClientRects().length &&
+      !document.hidden)) return false;
+  try {
+    var frame = window.frameElement;
+    while (frame) {
+      if (!frame.isConnected || !frame.getClientRects().length ||
+          frame.closest('[hidden], .hidden, [aria-hidden="true"]')) return false;
+      frame = frame.ownerDocument.defaultView.frameElement;
+    }
+  } catch (error) { return false; }
+  return true;
+}
+
+export function stopSTT(message, reason) {
+  var active = store.get('speechActive');
+  if (!active) return;
+  speechTrace(active, 'stop', { reason: reason || (typeof message === 'string' ? message : 'unspecified caller'), bytes: active.bytes || 0 });
+  console.trace('[Clay voice] Stop caller · ' + (active.traceId || 'browser'));
+  // Invalidate before abort: late results and end events must never revive an old draft.
+  store.set({ speechActive: null });
+  clearTimeout(active.timeout);
+  if (active.visualCapture) active.visualCapture.abort();
+  try { active.recognition.abort(); } catch (error) { /* Already ended. */ }
+  setSpeechStatus(active.id, typeof message === 'string' ? message : 'Voice input stopped.');
+}
+
+export function currentSpeech(active) {
+  if (store.get('speechActive') !== active) return false;
+  if (active.context !== speechContext() || !usableSpeechInput(active.input) ||
+      active.input.value !== active.lastValue) {
+    stopSTT(undefined, active.context !== speechContext() ? 'draft context changed' :
+      active.input.value !== active.lastValue ? 'draft text changed outside voice input' : 'input hidden, disabled, detached or document hidden');
+    return false;
+  }
+  return true;
+}
+
+export function claimSpeech(id, input, recognition) {
+  try { window.top.document.dispatchEvent(new window.top.Event('clay:voice-claim')); }
+  catch (error) { stopSTT(); }
+  stopSTT();
+  var active = { id: id, input: input, recognition: recognition, context: speechContext(),
+    before: input.value, lastValue: input.value, writing: false, started: false, timeout: null };
+  active.traceId = Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 7);
+  active.traceStarted = Date.now();
+  store.set({ speechActive: active, speechRetry: null });
+  return active;
+}
+
+export function writeSpeech(active, transcript) {
+  if (!currentSpeech(active)) return false;
+  var separator = active.before && transcript && !/\s$/.test(active.before) ? ' ' : '';
+  active.lastValue = active.before + separator + transcript;
+  active.input.value = active.lastValue;
+  active.writing = true;
+  try { active.input.dispatchEvent(new Event('input', { bubbles: true })); }
+  finally { active.writing = false; }
+  return true;
+}
+
+export function startSTT(id, input) {
+  if (!usableSpeechInput(input)) return;
+  var Constructor = speechConstructor();
+  if (!window.isSecureContext || !Constructor) {
+    setSpeechStatus(id, !window.isSecureContext ? 'Voice input requires a secure HTTPS connection.' :
+      'Voice input is unavailable in this browser. You can still type your message.');
+    return;
+  }
+  // Same-origin split panes share the top document as a synchronous ownership signal.
+  // This event only stops recognition; it can never start a microphone.
+  try { window.top.document.dispatchEvent(new window.top.Event('clay:voice-claim')); }
+  catch (error) { stopSTT(); }
+  stopSTT();
+  var recognition;
+  try { recognition = new Constructor(); }
+  catch (error) { setSpeechStatus(id, 'Voice input could not start. You can still type your message.'); return; }
+  var active = { id: id, input: input, recognition: recognition, context: speechContext(),
+    before: input.value, lastValue: input.value, writing: false, started: false, timeout: null };
+  recognition.lang = store.get('speechLang') || 'en-US';
+  recognition.continuous = true;
+  recognition.interimResults = true;
+  recognition.onstart = function () {
+    if (!currentSpeech(active)) return;
+    clearTimeout(active.timeout);
+    active.started = true;
+    store.set({ speechActive: active });
+    setSpeechStatus(id, 'Listening. Select the microphone to stop.');
+  };
+  recognition.onresult = function (event) {
+    if (!currentSpeech(active)) return;
+    var parts = [];
+    for (var i = 0; i < event.results.length; i++) parts.push(event.results[i][0].transcript);
+    var transcript = parts.join('');
+    var separator = active.before && transcript && !/\s$/.test(active.before) ? ' ' : '';
+    active.lastValue = active.before + separator + transcript;
+    input.value = active.lastValue;
+    active.writing = true;
+    try { input.dispatchEvent(new Event('input', { bubbles: true })); }
+    finally { active.writing = false; }
+  };
+  recognition.onerror = function (event) {
+    if (store.get('speechActive') !== active) return;
+    var messages = {
+      'not-allowed': 'Microphone access was denied. Allow microphone access in your browser settings to try again.',
+      'service-not-allowed': 'Speech recognition is not allowed by this browser or device.',
+      'audio-capture': 'No microphone is available. Check your microphone connection and permissions.',
+      'no-speech': 'No speech detected. Select the microphone to try again.',
+      'network': 'The speech recognition service could not be reached. Check your connection or try another browser.',
+      'language-not-supported': 'This recognition language is unavailable. Choose another language.',
+      'aborted': 'Voice input stopped.'
+    };
+    if (event.error === 'aborted' || event.error === 'no-speech') stopSTT(messages[event.error]);
+    else failSTT(messages[event.error] || 'Voice input failed. You can still type your message.');
+  };
+  recognition.onend = function () {
+    if (store.get('speechActive') === active) stopSTT('Voice input finished. Review your draft before sending.');
+  };
+  store.set({ speechActive: active, speechRetry: null });
+  setSpeechStatus(id, 'Starting microphone… Your browser may ask for permission.');
+  active.timeout = setTimeout(function () {
+    if (store.get('speechActive') === active) stopSTT('Microphone did not start. Check browser permissions and try again.');
+  }, 15000);
+  try { startBrowserSpeechSignal(active); recognition.start(); }
+  catch (error) { if (store.get('speechActive') === active) stopSTT('Voice input could not start. Check microphone permissions and try again.'); }
+}
+
+export function initSpeechLifecycle() {
+  if (store.get('speechLifecycleBound')) return;
+  store.set({ speechLifecycleBound: true });
+  store.subscribe(function () {
+    var active = store.get('speechActive');
+    if (active) currentSpeech(active);
+    var retry = store.get('speechRetry');
+    if (retry && (retry.context !== speechContext() || !usableSpeechInput(retry.input) || retry.input.value !== retry.value)) store.set({ speechRetry: null });
+  });
+  document.addEventListener('visibilitychange', function () { if (document.hidden) stopSTT(undefined, 'document visibility changed to hidden'); });
+  document.addEventListener('focusin', function (event) {
+    var target = event.target;
+    var active = store.get('speechActive');
+    if (!target || !target.matches || !target.matches('textarea, input, [contenteditable="true"]') ||
+        (active && active.input === target)) return;
+    try { window.top.document.dispatchEvent(new window.top.Event('clay:voice-claim')); }
+    catch (error) { stopSTT(); }
+  });
+  var stopForClaim = function () { stopSTT(undefined, 'another composer or input claimed voice ownership'); };
+  function attachClaim() {
+    try { window.top.document.addEventListener('clay:voice-claim', stopForClaim); } catch (error) { /* Standalone cross-origin host. */ }
+  }
+  attachClaim();
+  window.addEventListener('pageshow', attachClaim);
+  window.addEventListener('pagehide', function () {
+    stopSTT();
+    observer.disconnect();
+    try { window.top.document.removeEventListener('clay:voice-claim', stopForClaim); } catch (error) { /* Host unavailable. */ }
+  });
+  var observer = new MutationObserver(function () {
+    var active = store.get('speechActive');
+    if (active) currentSpeech(active);
+  });
+  function observeVisibility() {
+    var options = { subtree: true, childList: true, attributes: true,
+      attributeFilter: ['class', 'style', 'hidden', 'disabled', 'readonly', 'aria-hidden'] };
+    observer.observe(document.body, options);
+    try { if (window.top !== window) observer.observe(window.top.document.body, options); }
+    catch (error) { /* Cross-origin host. */ }
+  }
+  observeVisibility();
+  window.addEventListener('pageshow', observeVisibility);
+}

package/lib/public/modules/stt-debug.js

@@ -0,0 +1,7 @@
+// Log lifecycle metadata only: never pass keys, audio, transcripts or draft text.
+export function speechTrace(active, event, details) {
+  var record = Object.assign({ version: 'voice-debug-v1', attempt: active && active.traceId || 'none', event: event,
+    elapsedMs: active && active.traceStarted ? Date.now() - active.traceStarted : 0,
+    phase: active && active.phase || 'idle', model: active && active.model && active.model.id || 'browser' }, details || {});
+  console.log('[Clay voice] ' + JSON.stringify(record));
+}

package/lib/public/modules/stt-meter.js

@@ -0,0 +1,55 @@
+import { store } from './store.js';
+
+export function createSpeechMeter(id) {
+  var element = document.createElement('span'); element.className = 'stt-meter';
+  element.setAttribute('aria-hidden', 'true');
+  var canvas = document.createElement('canvas'); element.appendChild(canvas);
+  var context = canvas.getContext('2d'); var frame = null; var paintedAt = 0; var heights = [];
+  var reduced = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  function paint(time) {
+    frame = null;
+    var active = store.get('speechActive');
+    if (!active || active.id !== id || !element.isConnected || !context) return;
+    frame = requestAnimationFrame(paint);
+    if (time - paintedAt < (reduced ? 100 : 32)) return;
+    paintedAt = time;
+    var width = element.clientWidth; var height = element.clientHeight;
+    var ratio = Math.min(window.devicePixelRatio || 1, 2);
+    if (canvas.width !== Math.round(width * ratio) || canvas.height !== Math.round(height * ratio)) {
+      canvas.width = Math.round(width * ratio); canvas.height = Math.round(height * ratio);
+    }
+    context.setTransform(ratio, 0, 0, ratio, 0, 0); context.clearRect(0, 0, width, height);
+    context.fillStyle = getComputedStyle(element).color;
+    var signal = active.audioSignal; var levels = signal ? signal.levels : [];
+    var age = signal ? Date.now() - signal.updatedAt : 0;
+    var fade = Math.max(0, 1 - Math.max(0, age - 250) / 900);
+    var columns = Math.max(2, Math.floor(width / 4));
+    var span = Math.round(Math.min(160, Math.max(80, columns)) * 1.25);
+    var drift = reduced ? 0 : Math.min(1, age / 20);
+    for (var x = 0; x < columns; x++) {
+      var position = levels.length - span + x / (columns - 1) * (span - 1) + drift;
+      var index = Math.floor(position); var fraction = position - index;
+      var a = levels[index] || 0; var b = levels[Math.min(index + 1, levels.length - 1)] || 0;
+      var target = (a + (b - a) * fraction) * fade;
+      var previous = heights[x] || 0;
+      var level = reduced ? target : previous + (target - previous) * (target > previous ? 0.5 : 0.24);
+      heights[x] = level;
+      var extent = 1 + level * (height * 0.46 - 1);
+      var edge = Math.min(1, (x + 1) / 8, (columns - x) / 8);
+      for (var y = 0; y <= height * 0.48; y += 3.2) {
+        var density = Math.exp(-Math.pow(y / extent, 2) * 1.7);
+        if (density < 0.035) continue;
+        var radius = 0.35 + density * 0.65;
+        context.globalAlpha = (0.12 + density * 0.78) * edge;
+        context.beginPath(); context.arc((x + 0.5) * width / columns, height / 2 + y, radius, 0, Math.PI * 2); context.fill();
+        if (y) { context.beginPath(); context.arc((x + 0.5) * width / columns, height / 2 - y, radius, 0, Math.PI * 2); context.fill(); }
+      }
+    }
+    context.globalAlpha = 1;
+  }
+  return { element: element, update: function (active) {
+    element.hidden = !active;
+    if (active && frame === null) frame = requestAnimationFrame(paint);
+    if (!active && frame !== null) { cancelAnimationFrame(frame); frame = null; heights = []; }
+  } };
+}

package/lib/public/modules/stt-picker.js

@@ -0,0 +1,123 @@
+import { store } from './store.js';
+import { escapeHtml } from './utils.js';
+import { iconHtml, refreshIcons } from './icons.js';
+import { speechLanguages, voiceModel, loadSpeechSettings, saveSpeechSettings, saveSpeechLanguage } from './stt-settings.js';
+import { stopSTT } from './stt-controller.js';
+
+export function closeSpeechPicker() {
+  var state = store.get('speechPopup');
+  store.set({ speechPopup: null });
+  if (state && state.anchor.isConnected) { state.anchor.setAttribute('aria-expanded', 'false'); state.anchor.focus(); }
+}
+function patch(values) { store.set({ speechPopup: Object.assign({}, store.get('speechPopup'), values) }); }
+async function save(change, close) {
+  patch({ busy: true, error: '' });
+  try { await saveSpeechSettings(change); if (close) closeSpeechPicker(); else if (store.get('speechPopup')) patch({ provider: null, busy: false }); }
+  catch (error) { if (store.get('speechPopup')) patch({ busy: false, error: error.message }); }
+}
+function render() {
+  var previous = document.getElementById('speech-picker');
+  var focusKey = previous && previous.contains(document.activeElement) && document.activeElement.dataset.focus;
+  var keyInput = previous && previous.querySelector('#speech-api-key');
+  var unsavedKey = keyInput ? keyInput.value : '';
+  var previousProvider = previous && previous.dataset.provider;
+  if (previous) previous.remove();
+  var state = store.get('speechPopup'); if (!state) return;
+  var settings = store.get('speechSettings');
+  var popup = document.createElement('div'); popup.id = 'speech-picker'; popup.className = 'stt-picker';
+  popup.dataset.provider = state.provider || '';
+  popup.setAttribute('role', 'dialog'); popup.setAttribute('aria-modal', 'true'); popup.setAttribute('aria-label', 'Voice input');
+  var html = '<div class="stt-picker-heading"><strong>Voice input</strong><button type="button" data-action="close" data-focus="close" aria-label="Close voice input settings">' + iconHtml('x') + '</button></div>';
+  html += '<div class="stt-mode-tabs" role="group" aria-label="Transcription mode"><button type="button" data-mode="live" aria-pressed="' + (state.mode === 'live') + '"><strong>Live</strong><span>Text appears as you speak.</span></button><button type="button" data-mode="recorded" aria-pressed="' + (state.mode === 'recorded') + '"><strong>After recording</strong><span>Stop recording to get text.</span></button></div>';
+  if (settings) {
+    html += '<div class="stt-model-list">';
+    settings.models.filter(function (model) { return model.mode === state.mode; }).sort(function (a, b) {
+      return Number(b.provider === 'openai') - Number(a.provider === 'openai');
+    }).forEach(function (model) {
+      var provider = settings.providers.find(function (item) { return item.id === model.provider; });
+      var connected = !provider || settings.configured.indexOf(provider.id) >= 0;
+      var mark = provider ? '<img src="' + provider.icon + '" alt="">' : '<span class="stt-browser-icon">' + iconHtml('mic') + '</span>';
+      var label = provider ? provider.name + ' · ' + model.name : model.name;
+      html += '<div class="stt-model-row"><button type="button" class="stt-model" data-model="' + model.id + '" data-focus="' + model.id + '" title="' + escapeHtml(label + ' — ' + model.description) + '" aria-label="' + escapeHtml(label) + '" aria-pressed="' + (model.id === settings.selected) + '">' + mark + '<span>' + escapeHtml(label) + '</span>' + (model.id === settings.selected ? '<span class="stt-model-check">' + iconHtml('check') + '</span>' : '') + '</button>';
+      if (provider) html += '<button type="button" class="stt-key-toggle" data-provider="' + provider.id + '" data-focus="key-' + model.id + '" aria-label="' + (connected ? 'Manage ' : 'Connect ') + escapeHtml(provider.name) + ' API key" title="' + escapeHtml(provider.name) + ' API key">' + (connected ? iconHtml('key-round') : 'Connect') + '</button>';
+      html += '</div>';
+      if (provider && state.provider === provider.id && state.keyModel === model.id) {
+        html += '<form class="stt-key-form"><label for="speech-api-key">' + escapeHtml(provider.name) + ' API key</label><input id="speech-api-key" name="key" type="password" autocomplete="off" spellcheck="false" placeholder="Enter API key" required maxlength="4096"><p>Stored privately on your Clay server. Audio is sent to ' + escapeHtml(provider.name) + '; usage is billed to your account.</p><div class="stt-key-actions"><a href="' + escapeHtml(provider.url) + '" target="_blank" rel="noopener noreferrer">Get key ↗</a><button type="button" data-action="remove"' + (!connected ? ' disabled' : '') + '>Remove</button><button type="submit">Save</button></div></form>';
+      }
+    });
+    html += '</div><div class="stt-picker-footer"><label>Language<select aria-label="Voice input language" data-focus="language">';
+    speechLanguages.forEach(function (lang) { html += '<option value="' + lang[0] + '"' + (lang[0] === store.get('speechLang') ? ' selected' : '') + '>' + lang[1] + '</option>'; });
+    html += '</select></label></div>';
+  } else html += '<p>Loading voice models…</p>';
+  if (state.error || store.get('speechSettingsError')) html += '<p role="alert" class="stt-picker-error">' + escapeHtml(state.error || store.get('speechSettingsError')) + '</p><button type="button" data-action="reload">Reload settings</button>';
+  popup.innerHTML = html;
+  document.body.appendChild(popup); refreshIcons();
+  if (state.busy) popup.querySelectorAll('button,input,select').forEach(function (el) { if (el.dataset.action !== 'close') el.disabled = true; });
+  var bounds = state.anchor.getBoundingClientRect();
+  popup.style.left = Math.max(8, Math.min(bounds.right - 324, window.innerWidth - 332)) + 'px';
+  popup.style.bottom = Math.max(8, window.innerHeight - bounds.top + 8) + 'px';
+  popup.style.maxHeight = Math.max(150, bounds.top - 16) + 'px';
+  popup.addEventListener('click', function (event) {
+    var button = event.target.closest('button'); if (!button || button.disabled) return;
+    if (button.dataset.mode) patch({ mode: button.dataset.mode, provider: null, keyModel: null });
+    else if (button.dataset.provider) {
+      var keyModel = button.parentElement.querySelector('[data-model]').dataset.model;
+      patch({ provider: state.provider === button.dataset.provider && state.keyModel === keyModel ? null : button.dataset.provider, keyModel: keyModel });
+    }
+    else if (button.dataset.model) {
+      var model = settings.models.find(function (item) { return item.id === button.dataset.model; });
+      if (model.provider !== 'browser' && settings.configured.indexOf(model.provider) < 0) patch({ provider: model.provider, keyModel: model.id });
+      else save({ selected: model.id }, true);
+    } else {
+      var action = button.dataset.action;
+      if (action === 'close') closeSpeechPicker();
+      if (action === 'remove') save({ provider: state.provider, key: null }, false);
+      if (action === 'reload') loadSpeechSettings();
+    }
+  });
+  var form = popup.querySelector('form');
+  if (form && previousProvider === state.provider) form.elements.key.value = unsavedKey;
+  if (form) form.addEventListener('submit', function (event) {
+    event.preventDefault(); var key = form.elements.key.value; form.elements.key.value = '';
+    save({ provider: state.provider, key: key }, false);
+  });
+  var select = popup.querySelector('select');
+  if (select) select.addEventListener('change', async function () {
+    var code = select.value; patch({ busy: true });
+    try { await saveSpeechLanguage(code); if (store.get('speechPopup')) patch({ busy: false, error: '' }); }
+    catch (error) { if (store.get('speechPopup')) patch({ busy: false, error: error.message }); }
+  });
+  var focus = Array.from(popup.querySelectorAll('[data-focus]')).find(function (el) { return el.dataset.focus === focusKey && !el.disabled; });
+  (form && previousProvider !== state.provider ? form.elements.key : (focus || popup.querySelector('input,button'))).focus();
+}
+export function openSpeechPicker(anchor) {
+  if (store.get('speechPopup')) { closeSpeechPicker(); return; }
+  stopSTT();
+  anchor.setAttribute('aria-expanded', 'true');
+  store.set({ speechPopup: { anchor: anchor, mode: voiceModel().mode, error: '', busy: false } });
+  loadSpeechSettings();
+}
+export function initSpeechPicker() {
+  store.subscribe(function (state, prev) {
+    if (state.speechPopup !== prev.speechPopup || state.speechSettings !== prev.speechSettings || state.speechSettingsError !== prev.speechSettingsError || state.speechLang !== prev.speechLang) render();
+    if (state.currentSlug !== prev.currentSlug || state.activeSessionId !== prev.activeSessionId || state.homeChatSessionId !== prev.homeChatSessionId) {
+      if (state.speechPopup) closeSpeechPicker();
+    }
+  });
+  document.addEventListener('pointerdown', function (event) {
+    var state = store.get('speechPopup'); var popup = document.getElementById('speech-picker');
+    if (state && popup && !popup.contains(event.target) && !state.anchor.contains(event.target)) closeSpeechPicker();
+  });
+  document.addEventListener('keydown', function (event) {
+    if (!store.get('speechPopup')) return;
+    if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); closeSpeechPicker(); }
+    if (event.key === 'Tab') {
+      var popup = document.getElementById('speech-picker');
+      var items = popup.querySelectorAll('button:not(:disabled),input:not(:disabled),select:not(:disabled),a[href]');
+      var first = items[0]; var last = items[items.length - 1];
+      if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last.focus(); }
+      else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first.focus(); }
+    }
+  }, true);
+  window.addEventListener('resize', function () { if (store.get('speechPopup')) closeSpeechPicker(); });
+}

package/lib/public/modules/stt-recording.js

@@ -0,0 +1,130 @@
+import { sampleSpeechSignal } from './stt-signal.js';
+import { store } from './store.js';
+import { speechTrace } from './stt-debug.js';
+import { captureSpeech, wavRecording } from './stt-audio.js';
+import { claimSpeech, currentSpeech, writeSpeech, usableSpeechInput, setSpeechStatus, stopSTT, failSTT, speechContext } from './stt-controller.js';
+
+async function upload(active, blob) {
+  if (!currentSpeech(active)) return;
+  active.phase = 'transcribing'; store.set({ speechActive: active });
+  setSpeechStatus(active.id, 'Transcribing…');
+  speechTrace(active, 'upload-start', { bytes: blob.size });
+  try {
+    var response = await fetch('/api/speech/transcribe', { method: 'POST', signal: active.abortController.signal,
+      headers: { 'Content-Type': 'audio/wav', 'X-Speech-Model': active.model.id, 'X-Speech-Language': active.language }, body: blob });
+    var result = await response.json();
+    speechTrace(active, 'upload-response', { status: response.status, transcriptCharacters: typeof result.text === 'string' ? result.text.length : 0 });
+    if (!response.ok) throw new Error(result.error || 'Transcription failed. Please try again.');
+    if (!currentSpeech(active)) return;
+    writeSpeech(active, result.text || '');
+    stopSTT(result.text ? 'Review your draft before sending.' : 'No speech detected. Try recording again.');
+  } catch (error) {
+    if (!currentSpeech(active)) return;
+    var retry = { id: active.id, input: active.input, context: active.context, value: active.lastValue,
+      model: active.model, language: active.language, blob: blob };
+    failSTT(error.name === 'AbortError' ? 'Transcription timed out. Please try again.' : error.message);
+    store.set({ speechRetry: retry });
+    setTimeout(function () { if (store.get('speechRetry') === retry) store.set({ speechRetry: null }); }, 300000);
+  }
+}
+function initialize(id, input, model, language) {
+  var controller = new AbortController();
+  var active = claimSpeech(id, input, { abort: function () {
+    controller.abort(); clearInterval(active.clock);
+    if (active.capture) active.capture.abort();
+    if (active.socket) active.socket.close();
+    active.chunks = [];
+  } });
+  active.model = model; active.language = language; active.abortController = controller;
+  active.phase = 'starting'; active.chunks = []; active.bytes = 0;
+  speechTrace(active, 'start', { language: language, mode: model.mode, secureContext: window.isSecureContext, documentHidden: document.hidden });
+  active.timeout = setTimeout(function () { if (currentSpeech(active)) failSTT('Microphone or provider did not start. Please try again.'); }, 20000);
+  return active;
+}
+function liveSocket(active) {
+  return new Promise(function (resolve, reject) {
+    speechTrace(active, 'websocket-connect');
+    var socket = new WebSocket((location.protocol === 'https:' ? 'wss://' : 'ws://') + location.host + '/api/speech/live');
+    active.socket = socket;
+    socket.onopen = function () { speechTrace(active, 'websocket-open'); socket.send(JSON.stringify({ type: 'start', model: active.model.id, language: active.language })); };
+    socket.onmessage = function (event) {
+      if (!currentSpeech(active)) return;
+      try {
+        var data = JSON.parse(event.data);
+        if (data.type === 'diagnostic') { speechTrace(active, 'server-stage', { stage: data.stage, status: data.status, audioChunks: data.audioChunks, bytes: data.bytes }); return; }
+        if (data.type !== 'text' || !active.receivedText) speechTrace(active, 'websocket-message', { type: data.type, transcriptCharacters: typeof data.text === 'string' ? data.text.length : 0 });
+        if (data.type === 'text') active.receivedText = true;
+        if (data.type === 'ready') resolve();
+        else if (data.type === 'text') writeSpeech(active, data.text);
+        else if (data.type === 'done') { writeSpeech(active, data.text); stopSTT('Review your draft before sending.'); }
+        else if (data.type === 'error') { reject(new Error(data.error)); failSTT(data.error); }
+      } catch (error) { reject(error); failSTT('Invalid transcription response. Your draft has been preserved.'); }
+    };
+    socket.onerror = function () { speechTrace(active, 'websocket-error', { readyState: socket.readyState }); reject(new Error('Could not connect to voice input.')); if (currentSpeech(active)) failSTT('Could not connect to voice input.'); };
+    socket.onclose = function (event) { speechTrace(active, 'websocket-close', { code: event && event.code, clean: event && event.wasClean, stillActive: store.get('speechActive') === active }); reject(new Error('Voice connection closed.')); if (currentSpeech(active)) failSTT('Voice connection closed. Your draft has been preserved.'); };
+  });
+}
+export async function startRecording(id, input, model) {
+  if (!usableSpeechInput(input)) { speechTrace(null, 'start-rejected', { reason: 'input not usable', selectedModel: model.id }); return; }
+  if (!window.isSecureContext) { setSpeechStatus(id, 'Voice input requires a secure HTTPS connection.'); return; }
+  var active = initialize(id, input, model, store.get('speechLang') || 'en-US');
+  setSpeechStatus(id, 'Starting microphone…');
+  try {
+    // Ask for the microphone from the user gesture before waiting on the network.
+    active.capture = await captureSpeech(function (pcm) {
+      sampleSpeechSignal(active, new Int16Array(pcm), 16000, 32768);
+      active.capturedChunks = (active.capturedChunks || 0) + 1;
+      if (active.capturedChunks === 1 || active.capturedChunks % 50 === 0) speechTrace(active, 'audio-chunks', { capturedChunks: active.capturedChunks, sentBytes: active.bytes, chunkBytes: pcm.byteLength });
+      if (!currentSpeech(active) || (active.phase !== 'recording' && active.phase !== 'finishing')) return;
+      active.bytes += pcm.byteLength;
+      if (active.bytes > 9600000) { finishRecording(); return; }
+      if (model.mode === 'live') {
+        if (active.socket.readyState !== 1 || active.socket.bufferedAmount > 1048576) { failSTT('The connection is too slow. Your draft has been preserved.'); return; }
+        active.socket.send(pcm);
+      } else active.chunks.push(pcm);
+    }, function (event, details) { speechTrace(active, event, details); });
+    if (!currentSpeech(active)) { active.capture.abort(); return; }
+    if (model.mode === 'live') await liveSocket(active);
+    if (!currentSpeech(active)) return;
+    clearTimeout(active.timeout); active.started = true; active.phase = 'recording'; active.startTime = Date.now();
+    speechTrace(active, 'recording-ready');
+    active.clock = setInterval(function () {
+      if (currentSpeech(active)) {
+        store.set({ speechActive: active });
+        if (Date.now() - active.startTime >= 300000) finishRecording();
+      }
+    }, 1000);
+    store.set({ speechActive: active });
+    setSpeechStatus(id, model.mode === 'live' ? 'Listening…' : 'Recording…');
+  } catch (error) {
+    speechTrace(active, 'startup-caught-error', { errorName: error.name, stillActive: store.get('speechActive') === active });
+    if (currentSpeech(active)) failSTT(error.name === 'NotAllowedError' ? 'Microphone access was denied. Allow it in your browser settings to try again.' : 'Voice input could not start. Check your microphone, API key and connection.');
+  }
+}
+export async function finishRecording() {
+  var active = store.get('speechActive');
+  if (!active || !active.model) { stopSTT(); return; }
+  if (active.phase !== 'recording') return;
+  speechTrace(active, 'finish-requested', { bytes: active.bytes });
+  active.phase = 'finishing'; clearInterval(active.clock); store.set({ speechActive: active });
+  await active.capture.finish();
+  if (!currentSpeech(active)) return;
+  active.phase = 'transcribing'; store.set({ speechActive: active });
+  if (active.model.mode === 'live') {
+    setSpeechStatus(active.id, 'Finishing transcription…');
+    active.socket.send(JSON.stringify({ type: 'finish' }));
+    active.timeout = setTimeout(function () { if (currentSpeech(active)) failSTT('Transcription timed out. Your draft has been preserved.'); }, 25000);
+  } else {
+    var blob = wavRecording(active.chunks); active.chunks = [];
+    active.timeout = setTimeout(function () { active.abortController.abort(); }, 125000);
+    await upload(active, blob);
+  }
+}
+export function retryRecording() {
+  var retry = store.get('speechRetry');
+  if (!retry || retry.context !== speechContext() || retry.input.value !== retry.value || !usableSpeechInput(retry.input)) { store.set({ speechRetry: null }); return; }
+  var active = initialize(retry.id, retry.input, retry.model, retry.language);
+  clearTimeout(active.timeout);
+  active.timeout = setTimeout(function () { active.abortController.abort(); }, 125000);
+  upload(active, retry.blob);
+}

package/lib/public/modules/stt-settings.js

@@ -0,0 +1,50 @@
+import { store } from './store.js';
+import { stopSTT } from './stt-controller.js';
+export var speechLanguages = [
+  ['en-US', 'English'], ['es-ES', 'Spanish'], ['fr-FR', 'French'], ['de-DE', 'German'],
+  ['pt-BR', 'Portuguese'], ['it-IT', 'Italian'], ['nl-NL', 'Dutch'], ['pl-PL', 'Polish'],
+  ['ru-RU', 'Russian'], ['uk-UA', 'Ukrainian'], ['tr-TR', 'Turkish'], ['ar-SA', 'Arabic'],
+  ['hi-IN', 'Hindi'], ['id-ID', 'Indonesian'], ['vi-VN', 'Vietnamese'], ['th-TH', 'Thai'],
+  ['ja-JP', 'Japanese'], ['ko-KR', 'Korean'], ['zh-CN', 'Chinese']
+];
+export function voiceModel() {
+  var settings = store.get('speechSettings');
+  return settings && settings.models.find(function (model) { return model.id === settings.selected; }) ||
+    { id: 'browser', provider: 'browser', name: 'Browser speech', mode: 'live' };
+}
+export function voiceProvider(id) {
+  var settings = store.get('speechSettings');
+  return settings && settings.providers.find(function (provider) { return provider.id === id; });
+}
+export async function loadSpeechSettings() {
+  if (store.get('speechSettingsSaving')) return;
+  var request = (store.get('speechSettingsRequest') || 0) + 1;
+  store.set({ speechSettingsRequest: request });
+  try {
+    var response = await fetch('/api/speech/settings');
+    if (!response.ok) throw new Error('Voice settings unavailable. Please try again.');
+    var settings = await response.json();
+    if (store.get('speechSettingsRequest') !== request) return;
+    var previous = store.get('speechSettings');
+    if ((previous && JSON.stringify(previous) !== JSON.stringify(settings)) ||
+        (!previous && settings.selected !== 'browser')) stopSTT();
+    if (!previous || JSON.stringify(previous) !== JSON.stringify(settings)) store.set({ speechSettings: settings, speechLang: settings.language || 'en-US', speechSettingsError: '' });
+    else if (store.get('speechSettingsError')) store.set({ speechSettingsError: '' });
+  } catch (error) { if (store.get('speechSettingsRequest') === request) store.set({ speechSettingsError: 'Voice settings unavailable. Please try again.' }); }
+}
+export async function saveSpeechSettings(change) {
+  if (store.get('speechSettingsSaving')) throw new Error('Voice settings are being saved. Please wait.');
+  stopSTT();
+  store.set({ speechRetry: null, speechSettingsSaving: true, speechSettingsRequest: (store.get('speechSettingsRequest') || 0) + 1 });
+  try {
+    var response = await fetch('/api/speech/settings', { method: 'PUT', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(change) });
+    var result = await response.json();
+    if (!response.ok) throw new Error(result.error || 'Could not save voice settings.');
+    store.set({ speechSettings: result, speechLang: result.language || 'en-US', speechSettingsError: '' });
+  } finally { store.set({ speechSettingsSaving: false }); }
+  try { window.top.document.dispatchEvent(new window.top.Event('clay:speech-settings-saved')); } catch (error) { /* Standalone host. */ }
+}
+export async function saveSpeechLanguage(code) {
+  await saveSpeechSettings({ language: code });
+  window.dispatchEvent(new CustomEvent('clay:speech-language-saved', { detail: code }));
+}

package/lib/public/modules/stt-signal.js

@@ -0,0 +1,57 @@
+import { store } from './store.js';
+
+// Keep only a short perceptual envelope, never microphone samples.
+export function sampleSpeechSignal(active, samples, sampleRate, divisor) {
+  if (store.get('speechActive') !== active) return;
+  var signal = active.audioSignal || (active.audioSignal = { levels: [], envelope: 0, updatedAt: 0 });
+  var step = Math.max(1, Math.round(sampleRate / 50));
+  for (var offset = 0; offset < samples.length; offset += step) {
+    var end = Math.min(samples.length, offset + step); var energy = 0; var peak = 0;
+    for (var i = offset; i < end; i++) {
+      var value = Math.abs(samples[i] / divisor); energy += value * value; peak = Math.max(peak, value);
+    }
+    var amplitude = Math.sqrt(energy / (end - offset)) * 0.8 + peak * 0.2;
+    var db = 20 * Math.log10(Math.max(0.000001, amplitude));
+    var target = Math.max(0, Math.min(1, (db + 58) / 46));
+    signal.envelope += (target - signal.envelope) * (target > signal.envelope ? 0.72 : 0.22);
+    signal.levels.push(signal.envelope);
+  }
+  if (signal.levels.length > 240) signal.levels.splice(0, signal.levels.length - 240);
+  signal.updatedAt = Date.now();
+}
+
+// Native recognition exposes no PCM; this local analyser supplies its visual feedback.
+export function startBrowserSpeechSignal(active) {
+  var Constructor = window.AudioContext || window.webkitAudioContext;
+  if (!Constructor || !navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) return;
+  var context; var source; var stream; var timer; var stopped = false; var closed = false;
+  function closeContext() {
+    if (context && !closed) { closed = true; context.close().catch(function () {}); }
+  }
+  function abort() {
+    stopped = true; clearInterval(timer);
+    if (source) { source.disconnect(); source = null; }
+    if (stream) { stream.getTracks().forEach(function (track) { track.stop(); }); stream = null; }
+    closeContext();
+  }
+  active.visualCapture = { abort: abort };
+  try {
+    context = new Constructor();
+    var permission = navigator.mediaDevices.getUserMedia({ audio: true });
+    permission.then(function (value) {
+      stream = value;
+      if (stopped || store.get('speechActive') !== active) abort();
+    }, function () {});
+    Promise.all([context.resume(), permission]).then(function () {
+      if (stopped || store.get('speechActive') !== active) { abort(); return; }
+      var analyser = context.createAnalyser(); analyser.fftSize = 2048;
+      source = context.createMediaStreamSource(stream); source.connect(analyser);
+      var samples = new Float32Array(analyser.fftSize);
+      timer = setInterval(function () {
+        if (store.get('speechActive') !== active) { abort(); return; }
+        analyser.getFloatTimeDomainData(samples);
+        sampleSpeechSignal(active, samples, samples.length * 50, 1);
+      }, 20);
+    }).catch(abort);
+  } catch (error) { abort(); }
+}