@oshara/voice-sdk 0.1.0

package/src/ui/index.ts

@@ -0,0 +1,507 @@
+/**
+ * @oshara/voice-sdk/ui — the prebuilt widget UI.
+ *
+ * `mountVoiceUI(client, opts)` builds the shadow-DOM widget (FAB + panel +
+ * call/form screens + audio drawer), subscribes it to the headless client's
+ * events, and wires DOM interactions back to the client's methods. It's the
+ * exact UI the embeddable widget ships — now an optional layer over the core.
+ */
+
+import type { VoiceAgentClient } from "../core";
+import { saveConsent } from "../core";
+import type { AudioStateSnapshot } from "../core";
+import {
+  applyAppearance,
+  appendOrUpdateTranscriptSegment,
+  buildUI,
+  clearFieldErrors,
+  clearTranscript,
+  populateAudioDeviceSelect,
+  readFormValues,
+  renderForm,
+  setAgentStatusLine,
+  setAudioDrawerOpen,
+  setAudioMeterLevel,
+  setCallStatus,
+  setCallTimer,
+  setFieldErrors,
+  setFormBusy,
+  setFormCallControlsVisible,
+  setFormError,
+  setFormSuccess,
+  setFormTranscriptVisible,
+  setMuteVisual,
+  setOrbState,
+  setScreen,
+  showAgentTransition,
+  Screen,
+  UIRefs,
+} from "./ui";
+
+export interface MountVoiceUIOptions {
+  /** Where to mount. Default document.body. */
+  target?: HTMLElement;
+  /** Fill the parent container instead of floating (hides FAB). */
+  inline?: boolean;
+  /** Open the panel on mount. */
+  openChat?: boolean;
+  /** Hide the panel close button. */
+  closeButtonHide?: boolean;
+  /** Host element id. Default "voice-agent-widget-root". */
+  rootId?: string;
+}
+
+export interface VoiceUIHandle {
+  destroy: () => void;
+  /** The shadow-DOM refs, for advanced host integrations. */
+  refs: UIRefs;
+}
+
+export function mountVoiceUI(
+  client: VoiceAgentClient,
+  opts: MountVoiceUIOptions = {},
+): VoiceUIHandle {
+  const parent = opts.target ?? document.body;
+  const refs = buildUI(opts.rootId ?? "voice-agent-widget-root", {
+    inline: opts.inline,
+    parent,
+    closeButtonHide: opts.closeButtonHide,
+  });
+  applyAppearance(refs, client.getAppearance());
+  setScreen(refs, "welcome");
+
+  const audioCaps = client.getAudioCapabilities();
+  const unsubs: Array<() => void> = [];
+  const timers: number[] = [];
+  let panelOpen = false;
+  let formOpen = false;
+  let audioDrawerOpen = false;
+  let audioStatsTimer: number | null = null;
+  let audioMeterCtx: AudioContext | null = null;
+  let audioMeterRaf: number | null = null;
+
+  const trackedSetInterval = (handler: () => void, ms: number): number => {
+    const id = window.setInterval(handler, ms);
+    timers.push(id);
+    return id;
+  };
+
+  const togglePanel = (show: boolean) => {
+    panelOpen = show;
+    refs.panel.style.display = show ? "flex" : "none";
+  };
+  const ensurePanelOpen = () => {
+    if (!panelOpen) togglePanel(true);
+  };
+  const returnTo = (): Screen => (client.isActive() ? "call" : "welcome");
+
+  // ── event subscriptions (replace the controller's old direct UI calls) ──
+  unsubs.push(
+    client.on("appearance", (a) => applyAppearance(refs, a)),
+    client.on("state", ({ orb, statusLabel }) => {
+      setOrbState(refs, orb);
+      setAgentStatusLine(refs, orb === "thinking" ? statusLabel : null);
+    }),
+    client.on("call:status", ({ status }) => setCallStatus(refs, status)),
+    client.on("call:timer", ({ remainingMs }) => setCallTimer(refs, remainingMs)),
+    client.on("mute", ({ muted }) => setMuteVisual(refs, muted)),
+    client.on("controls", ({ canStart, canMute, canEnd }) => {
+      refs.startBtn.disabled = !canStart;
+      refs.muteBtn.disabled = !canMute;
+      refs.endBtn.disabled = !canEnd;
+    }),
+    client.on("connection", ({ phase }) => {
+      if (phase === "connecting") {
+        if (!formOpen) setScreen(refs, "call");
+      } else if (phase === "disconnected" || phase === "failed") {
+        if (!formOpen) setScreen(refs, "welcome");
+      }
+    }),
+    client.on("transcript", ({ role, segmentId, text, isFinal }) =>
+      appendOrUpdateTranscriptSegment(refs, role, segmentId, text, isFinal),
+    ),
+    client.on("transcript:clear", () => clearTranscript(refs)),
+    client.on("agent:handoff", ({ agentName }) =>
+      showAgentTransition(refs, agentName),
+    ),
+    client.on("audio", (state: AudioStateSnapshot) =>
+      syncDrawerToState(refs, state, audioCaps),
+    ),
+  );
+
+  // ── forms ──
+  const renderActiveForm = () => {
+    const active = client.getActiveForm();
+    if (!active) return;
+    renderForm(refs, {
+      definition: active.definition,
+      values: active.values,
+      stepIndex: active.stepIndex,
+      cancelLabel: client.isActive() ? "Back to call" : "Cancel",
+      onFieldChange: () => client.updateFormValues(readFormValues(refs)),
+    });
+  };
+
+  unsubs.push(
+    client.on("form:show", ({ inCall, transcriptionEnabled }) => {
+      formOpen = true;
+      ensurePanelOpen();
+      setScreen(refs, "form");
+      setFormCallControlsVisible(refs, inCall);
+      setFormTranscriptVisible(refs, inCall && transcriptionEnabled);
+      renderActiveForm();
+    }),
+    client.on("form:update", () => renderActiveForm()),
+    client.on("form:validation", ({ errors }) => {
+      setFormError(refs, "");
+      setFieldErrors(refs, errors);
+    }),
+    client.on("form:submitting", () => {
+      setFormError(refs, "");
+      setFormSuccess(refs, "");
+      clearFieldErrors(refs);
+      setFormBusy(refs, true);
+    }),
+    client.on("form:submitted", ({ successMessage }) => {
+      setFormSuccess(refs, successMessage);
+      setFormBusy(refs, false);
+    }),
+    client.on("form:error", ({ message }) => {
+      setFormError(refs, message);
+      setFormBusy(refs, false);
+    }),
+    client.on("form:close", () => {
+      formOpen = false;
+      setFormCallControlsVisible(refs, false);
+      setFormTranscriptVisible(refs, false);
+      setScreen(refs, returnTo());
+    }),
+  );
+
+  // Form buttons → client (capture on-screen values before submit/step).
+  const captureValues = () => client.updateFormValues(readFormValues(refs));
+  refs.formBackBtn.addEventListener("click", () => client.closeForm());
+  refs.formCancelBtn.addEventListener("click", () => client.closeForm());
+  refs.formStepBackBtn.addEventListener("click", () => {
+    captureValues();
+    client.stepForm("back");
+  });
+  refs.formSubmitBtn.addEventListener("click", () => {
+    captureValues();
+    client.submitForm();
+  });
+
+  // ── audio drawer + meters + stats (ported from the widget) ──
+  const refreshAudioDevices = async () => {
+    try {
+      const { inputs, outputs } = await client.enumerateAudioDevices();
+      const state = client.getAudioState();
+      populateAudioDeviceSelect(
+        refs.audioMicSelect,
+        inputs,
+        state.prefs.micDeviceId,
+        "System default",
+      );
+      populateAudioDeviceSelect(
+        refs.audioSpeakerSelect,
+        outputs,
+        state.prefs.speakerDeviceId,
+        "System default",
+      );
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn("[voice-agent] device enumeration failed:", err);
+    }
+  };
+
+  const stopMeter = () => {
+    if (audioMeterRaf !== null) {
+      cancelAnimationFrame(audioMeterRaf);
+      audioMeterRaf = null;
+    }
+    if (audioMeterCtx) {
+      void audioMeterCtx.close().catch(() => undefined);
+      audioMeterCtx = null;
+    }
+    setAudioMeterLevel(refs, 0);
+  };
+
+  const startMeter = async () => {
+    stopMeter();
+    if (!client.isActive()) return;
+    try {
+      const state = client.getAudioState();
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: state.prefs.micDeviceId
+          ? { deviceId: { exact: state.prefs.micDeviceId } }
+          : true,
+        video: false,
+      });
+      const ctx = new (window.AudioContext ||
+        (window as unknown as { webkitAudioContext: typeof AudioContext })
+          .webkitAudioContext)();
+      audioMeterCtx = ctx;
+      const source = ctx.createMediaStreamSource(stream);
+      const analyser = ctx.createAnalyser();
+      analyser.fftSize = 1024;
+      source.connect(analyser);
+      const buffer = new Float32Array(analyser.fftSize);
+      const tick = () => {
+        if (!audioMeterCtx) return;
+        analyser.getFloatTimeDomainData(buffer);
+        let sum = 0;
+        for (let i = 0; i < buffer.length; i++) sum += buffer[i] * buffer[i];
+        const rms = Math.sqrt(sum / buffer.length);
+        const db = 20 * Math.log10(Math.max(rms, 1e-6));
+        const norm = Math.max(0, Math.min(1, (db + 50) / 50));
+        setAudioMeterLevel(refs, norm);
+        audioMeterRaf = requestAnimationFrame(tick);
+      };
+      audioMeterRaf = requestAnimationFrame(tick);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn("[voice-agent] mic-level meter unavailable:", err);
+    }
+  };
+
+  const stopAudioStatsPoll = () => {
+    if (audioStatsTimer !== null) {
+      window.clearInterval(audioStatsTimer);
+      audioStatsTimer = null;
+    }
+  };
+
+  const startAudioStatsPoll = () => {
+    stopAudioStatsPoll();
+    const tick = async () => {
+      const stats = await client.getAudioStats();
+      if (!stats) {
+        refs.audioDiagLoss.textContent = "—";
+        refs.audioDiagJitter.textContent = "—";
+        refs.audioDiagRtt.textContent = "—";
+        return;
+      }
+      refs.audioDiagLoss.textContent = String(stats.packetsLost);
+      refs.audioDiagJitter.textContent = `${stats.jitter.toFixed(1)} ms`;
+      refs.audioDiagRtt.textContent = stats.roundTripTime
+        ? `${stats.roundTripTime.toFixed(0)} ms`
+        : "—";
+    };
+    void tick();
+    audioStatsTimer = trackedSetInterval(() => void tick(), 2000);
+  };
+
+  const openAudioDrawer = async () => {
+    audioDrawerOpen = true;
+    setAudioDrawerOpen(refs, true);
+    syncDrawerToState(refs, client.getAudioState(), audioCaps);
+    await refreshAudioDevices();
+    await startMeter();
+    startAudioStatsPoll();
+  };
+
+  const closeAudioDrawer = () => {
+    audioDrawerOpen = false;
+    setAudioDrawerOpen(refs, false);
+    stopMeter();
+    stopAudioStatsPoll();
+  };
+
+  // Auto-close the drawer when the call ends.
+  trackedSetInterval(() => {
+    if (audioDrawerOpen && !client.isActive()) closeAudioDrawer();
+  }, 1000);
+
+  // ── top-level DOM wiring ──
+  refs.fab.addEventListener("click", () => {
+    if (!panelOpen) client.trackEvent("bubble_clicked");
+    togglePanel(!panelOpen);
+  });
+  refs.closeBtn.addEventListener("click", () => {
+    if (client.isActive()) void client.end();
+    client.closeForm();
+    togglePanel(false);
+  });
+  if (opts.openChat || opts.inline) ensurePanelOpen();
+
+  refs.startBtn.addEventListener("click", () => {
+    const termsUrl = refs.appearance.terms_url;
+    if (termsUrl) saveConsent(client.agentSlug || "default", termsUrl);
+    void client.start();
+  });
+  refs.endBtn.addEventListener("click", () => void client.end());
+  refs.muteBtn.addEventListener("click", () => void client.toggleMute());
+  refs.formMuteBtn.addEventListener("click", () => void client.toggleMute());
+  refs.formEndBtn.addEventListener("click", () => {
+    client.closeForm();
+    void client.end();
+  });
+
+  refs.settingsBtn.addEventListener("click", () => {
+    if (!client.isActive()) return;
+    if (audioDrawerOpen) closeAudioDrawer();
+    else void openAudioDrawer();
+  });
+  refs.audioDrawerClose.addEventListener("click", closeAudioDrawer);
+
+  refs.audioMicSelect.addEventListener("change", () => {
+    void client.updateAudioSettings({ micDeviceId: refs.audioMicSelect.value });
+    void startMeter();
+  });
+  refs.audioSpeakerSelect.addEventListener("change", () => {
+    void client.updateAudioSettings({
+      speakerDeviceId: refs.audioSpeakerSelect.value,
+    });
+  });
+  refs.audioVolume.addEventListener("input", () => {
+    const value = Number(refs.audioVolume.value);
+    refs.audioVolumeValue.textContent = `${value}%`;
+    void client.updateAudioSettings({ outputVolume: value });
+  });
+  refs.audioNcEngine.addEventListener("change", () => {
+    const engine = refs.audioNcEngine.value as "off" | "krisp" | "deepfilter";
+    void client.updateAudioSettings({ noiseFilter: engine });
+    refs.audioDfStrengthRow.hidden = engine !== "deepfilter";
+  });
+  refs.audioDfStrength.addEventListener("input", () => {
+    const value = Number(refs.audioDfStrength.value);
+    refs.audioDfStrengthValue.textContent = String(value);
+    void client.updateAudioSettings({ deepFilterStrength: value });
+  });
+  refs.audioTogAec.addEventListener("change", () =>
+    void client.updateAudioSettings({ echoCancellation: refs.audioTogAec.checked }),
+  );
+  refs.audioTogNs.addEventListener("change", () =>
+    void client.updateAudioSettings({ noiseSuppression: refs.audioTogNs.checked }),
+  );
+  refs.audioTogAgc.addEventListener("change", () =>
+    void client.updateAudioSettings({ autoGainControl: refs.audioTogAgc.checked }),
+  );
+  refs.audioTogVi.addEventListener("change", () =>
+    void client.updateAudioSettings({ voiceIsolation: refs.audioTogVi.checked }),
+  );
+  refs.audioTogHp.addEventListener("change", () =>
+    void client.updateAudioSettings({ headphonesMode: refs.audioTogHp.checked }),
+  );
+  refs.audioTogTranscription.addEventListener("change", () =>
+    void client.updateAudioSettings({
+      transcriptionEnabled: refs.audioTogTranscription.checked,
+    }),
+  );
+  refs.audioTogTextInput.addEventListener("change", () =>
+    void client.updateAudioSettings({
+      textInputEnabled: refs.audioTogTextInput.checked,
+    }),
+  );
+
+  // Gear / text-input visibility tied to call state + prefs.
+  trackedSetInterval(() => {
+    const active = client.isActive();
+    refs.settingsBtn.hidden = !active || !refs.appearance.show_audio_settings;
+    const showText = active && client.getAudioState().prefs.textInputEnabled;
+    refs.textInputRow.hidden = !showText;
+    refs.textSendBtn.disabled = !showText;
+  }, 500);
+
+  refs.textInput.addEventListener("input", () => {
+    refs.textInput.style.height = "auto";
+    refs.textInput.style.height = `${refs.textInput.scrollHeight}px`;
+  });
+  const sendTextMessage = () => {
+    const text = refs.textInput.value.trim();
+    if (!text || !client.isActive()) return;
+    refs.textInput.value = "";
+    refs.textInput.style.height = "auto";
+    void client.sendText(text);
+  };
+  refs.textSendBtn.addEventListener("click", sendTextMessage);
+  refs.textInput.addEventListener("keydown", (e) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      sendTextMessage();
+    }
+  });
+
+  const destroy = () => {
+    for (const u of unsubs.splice(0)) {
+      try {
+        u();
+      } catch {
+        /* best-effort */
+      }
+    }
+    for (const id of timers.splice(0)) window.clearInterval(id);
+    stopMeter();
+    stopAudioStatsPoll();
+    refs.host.remove();
+  };
+
+  return { destroy, refs };
+}
+
+// ── audio drawer sync (ported from widget.ts) ──
+function syncDrawerToState(
+  refs: UIRefs,
+  state: AudioStateSnapshot,
+  caps: { setSinkIdSupported: boolean; voiceIsolationSupported: boolean },
+) {
+  const { prefs, applied, noiseFilter } = state;
+
+  refs.audioNcEngine.value = prefs.noiseFilter;
+  refs.audioDfStrength.value = String(prefs.deepFilterStrength);
+  refs.audioDfStrengthValue.textContent = String(prefs.deepFilterStrength);
+  refs.audioDfStrengthRow.hidden = prefs.noiseFilter !== "deepfilter";
+
+  refs.audioTogAec.checked = prefs.echoCancellation;
+  refs.audioTogNs.checked = prefs.noiseSuppression;
+  refs.audioTogAgc.checked = prefs.autoGainControl;
+  refs.audioTogVi.checked = prefs.voiceIsolation;
+  refs.audioTogHp.checked = prefs.headphonesMode;
+  refs.audioTogTranscription.checked = prefs.transcriptionEnabled;
+  refs.audioTogTextInput.checked = prefs.textInputEnabled;
+  refs.transcript.style.display = prefs.transcriptionEnabled ? "flex" : "none";
+  if (prefs.transcriptionEnabled) {
+    refs.panel.classList.add("with-transcript");
+  } else {
+    refs.panel.classList.remove("with-transcript");
+  }
+  refs.audioVolume.value = String(prefs.outputVolume);
+  refs.audioVolumeValue.textContent = `${prefs.outputVolume}%`;
+
+  refs.audioTogViRow.style.display = caps.voiceIsolationSupported ? "" : "none";
+  refs.audioSpeakerRow.style.display = caps.setSinkIdSupported ? "" : "none";
+
+  refs.audioDiagEngine.textContent = formatEngineStatus(noiseFilter);
+  refs.audioDiagAec.textContent = boolLabel(applied.echoCancellation);
+  refs.audioDiagNs.textContent = boolLabel(applied.noiseSuppression);
+  refs.audioDiagAgc.textContent = boolLabel(applied.autoGainControl);
+  refs.audioDiagVi.textContent =
+    applied.voiceIsolation === undefined
+      ? "Unsupported"
+      : applied.voiceIsolation
+        ? "On"
+        : "Off";
+  refs.audioDiagSr.textContent =
+    applied.sampleRate !== undefined ? `${applied.sampleRate} Hz` : "—";
+}
+
+function boolLabel(v: boolean | undefined): string {
+  if (v === undefined) return "—";
+  return v ? "On" : "Off";
+}
+
+function formatEngineStatus(nf: AudioStateSnapshot["noiseFilter"]): string {
+  const engineLabel =
+    nf.engine === "krisp"
+      ? "Krisp"
+      : nf.engine === "deepfilter"
+        ? "DeepFilterNet3"
+        : "Off";
+  if (nf.engine === "off") return "Off";
+  if (nf.status === "active") return `${engineLabel} (active)`;
+  if (nf.status === "unsupported") return `${engineLabel} (unsupported)`;
+  if (nf.status === "failed") return `${engineLabel} (failed)`;
+  return engineLabel;
+}
+
+export type { UIRefs } from "./ui";