@navai/voice-frontend 0.1.1 → 0.1.3

package/dist/index.js

@@ -1,3 +1,8 @@
+import {
+  Orb,
+  useNavaiVoiceOrbStyles
+} from "./chunk-KBBRQQLK.js";
+
 // src/agent.ts
 import { RealtimeAgent, tool } from "@openai/agents/realtime";
 import { z } from "zod";
@@ -728,6 +733,7 @@ function emitWarnings(warnings) {
 }
 function useWebVoiceAgent(options) {
   const sessionRef = useRef(null);
+  const attachedRealtimeSessionRef = useRef(null);
   const runtimeConfigPromise = useMemo(
     () => resolveNavaiFrontendRuntimeConfig({
       moduleLoaders: options.moduleLoaders,
@@ -758,15 +764,61 @@ function useWebVoiceAgent(options) {
     [options.apiBaseUrl, options.env]
   );
   const [status, setStatus] = useState("idle");
+  const [agentVoiceState, setAgentVoiceState] = useState("idle");
   const [error, setError] = useState(null);
+  const setAgentVoiceStateIfChanged = useCallback((next) => {
+    setAgentVoiceState((current) => current === next ? current : next);
+  }, []);
+  const handleSessionAudioStart = useCallback(() => {
+    setAgentVoiceStateIfChanged("speaking");
+  }, [setAgentVoiceStateIfChanged]);
+  const handleSessionAudioStopped = useCallback(() => {
+    setAgentVoiceStateIfChanged("idle");
+  }, [setAgentVoiceStateIfChanged]);
+  const handleSessionAudioInterrupted = useCallback(() => {
+    setAgentVoiceStateIfChanged("idle");
+  }, [setAgentVoiceStateIfChanged]);
+  const handleSessionError = useCallback(() => {
+    setAgentVoiceStateIfChanged("idle");
+  }, [setAgentVoiceStateIfChanged]);
+  const detachSessionAudioListeners = useCallback(() => {
+    const attachedSession = attachedRealtimeSessionRef.current;
+    if (!attachedSession) {
+      return;
+    }
+    attachedSession.off("audio_start", handleSessionAudioStart);
+    attachedSession.off("audio_stopped", handleSessionAudioStopped);
+    attachedSession.off("audio_interrupted", handleSessionAudioInterrupted);
+    attachedSession.off("error", handleSessionError);
+    attachedRealtimeSessionRef.current = null;
+  }, [handleSessionAudioInterrupted, handleSessionAudioStart, handleSessionAudioStopped, handleSessionError]);
+  const attachSessionAudioListeners = useCallback(
+    (session) => {
+      detachSessionAudioListeners();
+      session.on("audio_start", handleSessionAudioStart);
+      session.on("audio_stopped", handleSessionAudioStopped);
+      session.on("audio_interrupted", handleSessionAudioInterrupted);
+      session.on("error", handleSessionError);
+      attachedRealtimeSessionRef.current = session;
+    },
+    [
+      detachSessionAudioListeners,
+      handleSessionAudioInterrupted,
+      handleSessionAudioStart,
+      handleSessionAudioStopped,
+      handleSessionError
+    ]
+  );
   const stop = useCallback(() => {
+    detachSessionAudioListeners();
     try {
       sessionRef.current?.close();
     } finally {
       sessionRef.current = null;
       setStatus("idle");
+      setAgentVoiceStateIfChanged("idle");
     }
-  }, []);
+  }, [detachSessionAudioListeners, setAgentVoiceStateIfChanged]);
   useEffect(() => {
     return () => {
       stop();
@@ -778,6 +830,7 @@ function useWebVoiceAgent(options) {
     }
     setError(null);
     setStatus("connecting");
+    setAgentVoiceStateIfChanged("idle");
     try {
       const runtimeConfig = await runtimeConfigPromise;
       const requestPayload = runtimeConfig.modelOverride ? { model: runtimeConfig.modelOverride } : {};
@@ -792,6 +845,7 @@ function useWebVoiceAgent(options) {
       });
       emitWarnings([...runtimeConfig.warnings, ...backendFunctionsResult.warnings, ...warnings]);
       const session = new RealtimeSession(agent);
+      attachSessionAudioListeners(session);
       if (runtimeConfig.modelOverride) {
         await session.connect({ apiKey: secretPayload.value, model: runtimeConfig.modelOverride });
       } else {
@@ -803,28 +857,389 @@ function useWebVoiceAgent(options) {
       const message = formatError(startError);
       setError(message);
       setStatus("error");
+      setAgentVoiceStateIfChanged("idle");
+      detachSessionAudioListeners();
       try {
         sessionRef.current?.close();
       } catch {
       }
       sessionRef.current = null;
     }
-  }, [backendClient, options.navigate, runtimeConfigPromise, status]);
+  }, [
+    attachSessionAudioListeners,
+    backendClient,
+    detachSessionAudioListeners,
+    options.navigate,
+    runtimeConfigPromise,
+    setAgentVoiceStateIfChanged,
+    status
+  ]);
   return {
     status,
+    agentVoiceState,
     error,
     isConnecting: status === "connecting",
     isConnected: status === "connected",
+    isAgentSpeaking: agentVoiceState === "speaking",
     start,
     stop
   };
 }
+
+// src/orb/NavaiHeroOrb.tsx
+import { useEffect as useEffect3, useMemo as useMemo2, useState as useState3 } from "react";
+
+// src/orb/dynamic.tsx
+import { lazy, Suspense, useEffect as useEffect2, useState as useState2 } from "react";
+import { jsx } from "react/jsx-runtime";
+function dynamic(loader, options = {}) {
+  const { ssr = true, loading: LoadingComponent } = options;
+  const LazyComponent = lazy(async () => {
+    const loaded = await loader();
+    if (typeof loaded === "function") {
+      return { default: loaded };
+    }
+    return loaded;
+  });
+  function DynamicComponent(props) {
+    const [isClientReady, setIsClientReady] = useState2(ssr);
+    useEffect2(() => {
+      if (!ssr) {
+        setIsClientReady(true);
+      }
+    }, [ssr]);
+    if (!isClientReady) {
+      return null;
+    }
+    const fallback = LoadingComponent ? /* @__PURE__ */ jsx(LoadingComponent, {}) : null;
+    return /* @__PURE__ */ jsx(Suspense, { fallback, children: /* @__PURE__ */ jsx(LazyComponent, { ...props }) });
+  }
+  DynamicComponent.displayName = "DynamicComponent";
+  return DynamicComponent;
+}
+
+// src/orb/NavaiHeroOrb.tsx
+import { jsx as jsx2 } from "react/jsx-runtime";
+var Orb2 = dynamic(() => import("./Orb-B4OSC3XR.js"), {
+  ssr: false
+});
+var ORB_DELAY_MS_MIN = 0;
+var ORB_DELAY_MS_MAX = 6e4;
+var DEFAULT_AUTOPLAY_DELAY_MS = 9e3;
+var DEFAULT_REVEAL_DELAY_MS = 5200;
+function clampNavaiOrbDelayMs(value, fallback) {
+  const numericValue = Number.isFinite(value) ? value : fallback;
+  return Math.min(ORB_DELAY_MS_MAX, Math.max(ORB_DELAY_MS_MIN, numericValue));
+}
+function NavaiHeroOrb({
+  className = "",
+  backgroundColor = "#000000",
+  isAgentSpeaking = false,
+  hoverIntensitySpeaking = 0.66,
+  hoverIntensityIdle = 0.08,
+  revealDelayMs = DEFAULT_REVEAL_DELAY_MS,
+  autoplayDelayMs = DEFAULT_AUTOPLAY_DELAY_MS
+}) {
+  useNavaiVoiceOrbStyles();
+  const resolvedRevealDelayMs = clampNavaiOrbDelayMs(revealDelayMs, DEFAULT_REVEAL_DELAY_MS);
+  const resolvedAutoplayDelayMs = clampNavaiOrbDelayMs(autoplayDelayMs, DEFAULT_AUTOPLAY_DELAY_MS);
+  const [isOrbReady, setIsOrbReady] = useState3(resolvedRevealDelayMs === 0);
+  const [isOrbAutoAnimating, setIsOrbAutoAnimating] = useState3(resolvedAutoplayDelayMs === 0);
+  useEffect3(() => {
+    if (typeof window === "undefined" || resolvedRevealDelayMs === 0) {
+      return;
+    }
+    const revealOrb = () => setIsOrbReady(true);
+    window.addEventListener("pointerdown", revealOrb, { passive: true, once: true });
+    window.addEventListener("touchstart", revealOrb, { passive: true, once: true });
+    window.addEventListener("keydown", revealOrb, { once: true });
+    const timeoutId = window.setTimeout(revealOrb, resolvedRevealDelayMs);
+    return () => {
+      window.removeEventListener("pointerdown", revealOrb);
+      window.removeEventListener("touchstart", revealOrb);
+      window.removeEventListener("keydown", revealOrb);
+      window.clearTimeout(timeoutId);
+    };
+  }, [resolvedRevealDelayMs]);
+  useEffect3(() => {
+    if (typeof window === "undefined" || resolvedAutoplayDelayMs === 0) {
+      return;
+    }
+    let started = false;
+    const startOrbAnimation = () => {
+      if (started) {
+        return;
+      }
+      started = true;
+      setIsOrbAutoAnimating(true);
+    };
+    if (navigator.userActivation?.hasBeenActive) {
+      startOrbAnimation();
+    }
+    window.addEventListener("pointerdown", startOrbAnimation, { passive: true, once: true });
+    window.addEventListener("touchstart", startOrbAnimation, { passive: true, once: true });
+    window.addEventListener("keydown", startOrbAnimation, { once: true });
+    const timeoutId = window.setTimeout(startOrbAnimation, resolvedAutoplayDelayMs);
+    return () => {
+      window.removeEventListener("pointerdown", startOrbAnimation);
+      window.removeEventListener("touchstart", startOrbAnimation);
+      window.removeEventListener("keydown", startOrbAnimation);
+      window.clearTimeout(timeoutId);
+    };
+  }, [resolvedAutoplayDelayMs]);
+  const orbHoverIntensity = useMemo2(() => {
+    return isAgentSpeaking ? hoverIntensitySpeaking : hoverIntensityIdle;
+  }, [hoverIntensityIdle, hoverIntensitySpeaking, isAgentSpeaking]);
+  if (!isOrbReady) {
+    return null;
+  }
+  return /* @__PURE__ */ jsx2("div", { className: ["navai-voice-orb-hero", className].filter(Boolean).join(" "), children: /* @__PURE__ */ jsx2(
+    Orb2,
+    {
+      hoverIntensity: orbHoverIntensity,
+      rotateOnHover: true,
+      forceHoverState: isAgentSpeaking,
+      enablePointerHover: false,
+      animate: isAgentSpeaking || isOrbAutoAnimating,
+      backgroundColor
+    }
+  ) });
+}
+
+// src/orb/NavaiMiniOrbDock.tsx
+import { jsx as jsx3, jsxs } from "react/jsx-runtime";
+var Orb3 = dynamic(() => import("./Orb-B4OSC3XR.js"), {
+  ssr: false
+});
+function NavaiMiniOrbDock({
+  className = "",
+  style,
+  themeMode = "dark",
+  placement = "bottom-right",
+  isActive = false,
+  isConnected = false,
+  isDisabled = false,
+  isAgentSpeaking = false,
+  animateOrb = true,
+  backgroundColor = "#060914",
+  buttonAriaLabel,
+  buttonIcon,
+  buttonType = "button",
+  onButtonClick,
+  statusMessage = "",
+  isError = false,
+  ariaMessage = ""
+}) {
+  useNavaiVoiceOrbStyles();
+  const dockClassName = ["navai-voice-orb-dock", `is-${placement}`, themeMode === "light" ? "is-light" : "", className].filter(Boolean).join(" ");
+  const shouldHighlightOrb = isAgentSpeaking || isActive;
+  const orbHoverIntensity = isAgentSpeaking ? 0.66 : 0.08;
+  return /* @__PURE__ */ jsxs("aside", { className: dockClassName, style, children: [
+    /* @__PURE__ */ jsxs("div", { className: "navai-voice-orb-wrap", children: [
+      /* @__PURE__ */ jsx3("div", { className: ["navai-voice-orb-surface", shouldHighlightOrb ? "is-highlighted" : ""].filter(Boolean).join(" "), children: /* @__PURE__ */ jsx3(
+        Orb3,
+        {
+          hoverIntensity: orbHoverIntensity,
+          rotateOnHover: true,
+          forceHoverState: isAgentSpeaking,
+          enablePointerHover: false,
+          animate: animateOrb,
+          backgroundColor
+        }
+      ) }),
+      /* @__PURE__ */ jsx3("div", { className: ["navai-voice-orb-button-shell", isConnected ? "is-active" : ""].filter(Boolean).join(" "), children: /* @__PURE__ */ jsx3(
+        "button",
+        {
+          type: buttonType,
+          className: [
+            "navai-voice-orb-button",
+            isConnected ? "is-active" : "",
+            isActive && !isConnected ? "is-connecting" : ""
+          ].filter(Boolean).join(" "),
+          onClick: onButtonClick,
+          disabled: isDisabled,
+          "aria-label": buttonAriaLabel,
+          children: buttonIcon
+        }
+      ) })
+    ] }),
+    statusMessage ? /* @__PURE__ */ jsx3("p", { className: ["navai-voice-orb-status", isError ? "is-error" : ""].filter(Boolean).join(" "), role: "status", children: statusMessage }) : null,
+    /* @__PURE__ */ jsx3("span", { className: "navai-voice-orb-live", "aria-live": "polite", children: ariaMessage })
+  ] });
+}
+
+// src/orb/NavaiVoiceHeroOrb.tsx
+import { useEffect as useEffect4 } from "react";
+
+// src/orb/NavaiVoiceOrbDock.tsx
+import { useCallback as useCallback2, useMemo as useMemo3 } from "react";
+
+// src/orb/NavaiVoiceOrbDockMicIcon.tsx
+import { jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
+function NavaiVoiceOrbDockMicIcon({
+  isActive = false,
+  size = 20
+}) {
+  return /* @__PURE__ */ jsxs2(
+    "svg",
+    {
+      width: size,
+      height: size,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: "2",
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true",
+      className: ["navai-voice-orb-icon", isActive ? "is-pulsing" : ""].filter(Boolean).join(" "),
+      children: [
+        /* @__PURE__ */ jsx4("path", { d: "M12 3a3 3 0 0 0-3 3v6a3 3 0 1 0 6 0V6a3 3 0 0 0-3-3Z" }),
+        /* @__PURE__ */ jsx4("path", { d: "M19 10v2a7 7 0 1 1-14 0v-2" }),
+        /* @__PURE__ */ jsx4("path", { d: "M12 19v3" })
+      ]
+    }
+  );
+}
+
+// src/orb/NavaiVoiceOrbDockSpinnerIcon.tsx
+import { jsx as jsx5 } from "react/jsx-runtime";
+function NavaiVoiceOrbDockSpinnerIcon({
+  size = 20
+}) {
+  const style = {
+    width: size,
+    height: size
+  };
+  return /* @__PURE__ */ jsx5("span", { "aria-hidden": "true", className: "navai-voice-orb-spinner", style });
+}
+
+// src/orb/NavaiVoiceOrbDock.tsx
+import { jsx as jsx6 } from "react/jsx-runtime";
+var DEFAULT_MESSAGES = {
+  ariaStart: "Activate NAVAI voice",
+  ariaStop: "Deactivate NAVAI voice",
+  idle: "NAVAI ready to start.",
+  connecting: "Connecting NAVAI voice...",
+  listening: "NAVAI is listening.",
+  speaking: "NAVAI is speaking.",
+  errorPrefix: "NAVAI error"
+};
+function resolveNavaiVoiceOrbRuntimeSnapshot(agent) {
+  return {
+    status: agent.status,
+    agentVoiceState: agent.agentVoiceState,
+    isAgentSpeaking: agent.isAgentSpeaking,
+    error: agent.error
+  };
+}
+function resolveStatusMessage(runtimeSnapshot, messages) {
+  if (runtimeSnapshot.error) {
+    return `${messages.errorPrefix}: ${runtimeSnapshot.error}`;
+  }
+  if (runtimeSnapshot.isAgentSpeaking) {
+    return messages.speaking;
+  }
+  if (runtimeSnapshot.status === "connecting") {
+    return messages.connecting;
+  }
+  if (runtimeSnapshot.status === "connected") {
+    return messages.listening;
+  }
+  return messages.idle;
+}
+function NavaiVoiceOrbDock({
+  agent,
+  className,
+  style,
+  themeMode = "dark",
+  placement = "bottom-right",
+  backgroundColorLight = "#f4f6fb",
+  backgroundColorDark = "#060914",
+  showStatus = true,
+  messages
+}) {
+  const resolvedMessages = useMemo3(() => ({ ...DEFAULT_MESSAGES, ...messages }), [messages]);
+  const runtimeSnapshot = useMemo3(() => resolveNavaiVoiceOrbRuntimeSnapshot(agent), [agent]);
+  const statusMessage = showStatus ? resolveStatusMessage(runtimeSnapshot, resolvedMessages) : "";
+  const isError = runtimeSnapshot.status === "error" || Boolean(runtimeSnapshot.error);
+  const isConnecting = runtimeSnapshot.status === "connecting";
+  const isActive = runtimeSnapshot.status === "connecting" || runtimeSnapshot.status === "connected";
+  const isDisabled = agent.isConnecting;
+  const shouldAnimateOrb = runtimeSnapshot.status !== "error";
+  const handleToggle = useCallback2(() => {
+    if (agent.isConnecting) {
+      return;
+    }
+    if (agent.isConnected) {
+      agent.stop();
+      return;
+    }
+    void agent.start();
+  }, [agent]);
+  return /* @__PURE__ */ jsx6(
+    NavaiMiniOrbDock,
+    {
+      className,
+      style,
+      themeMode,
+      placement,
+      isActive,
+      isConnected: agent.isConnected,
+      isDisabled,
+      isAgentSpeaking: agent.isAgentSpeaking,
+      animateOrb: shouldAnimateOrb,
+      backgroundColor: themeMode === "light" ? backgroundColorLight : backgroundColorDark,
+      buttonAriaLabel: isConnecting ? resolvedMessages.connecting : agent.isConnected ? resolvedMessages.ariaStop : resolvedMessages.ariaStart,
+      buttonIcon: isConnecting ? /* @__PURE__ */ jsx6(NavaiVoiceOrbDockSpinnerIcon, {}) : /* @__PURE__ */ jsx6(NavaiVoiceOrbDockMicIcon, { isActive: agent.isConnected || agent.isAgentSpeaking }),
+      onButtonClick: handleToggle,
+      statusMessage,
+      isError,
+      ariaMessage: statusMessage
+    }
+  );
+}
+
+// src/orb/NavaiVoiceHeroOrb.tsx
+import { jsx as jsx7 } from "react/jsx-runtime";
+function NavaiVoiceHeroOrb({
+  agent,
+  themeMode = "dark",
+  backgroundColorLight = "#ffffff",
+  backgroundColorDark = "#000000",
+  onRuntimeSnapshotChange,
+  ...orbProps
+}) {
+  const runtimeSnapshot = resolveNavaiVoiceOrbRuntimeSnapshot(agent);
+  useEffect4(() => {
+    if (typeof onRuntimeSnapshotChange === "function") {
+      onRuntimeSnapshotChange(runtimeSnapshot);
+    }
+  }, [onRuntimeSnapshotChange, runtimeSnapshot]);
+  return /* @__PURE__ */ jsx7(
+    NavaiHeroOrb,
+    {
+      ...orbProps,
+      isAgentSpeaking: runtimeSnapshot.isAgentSpeaking,
+      backgroundColor: themeMode === "light" ? backgroundColorLight : backgroundColorDark,
+      className: themeMode === "light" ? "is-light" : ""
+    }
+  );
+}
 export {
+  NavaiHeroOrb,
+  NavaiMiniOrbDock,
+  NavaiVoiceHeroOrb,
+  NavaiVoiceOrbDock,
+  NavaiVoiceOrbDockMicIcon,
+  Orb,
   buildNavaiAgent,
+  clampNavaiOrbDelayMs,
   createNavaiBackendClient,
   getNavaiRoutePromptLines,
   loadNavaiFunctions,
   resolveNavaiFrontendRuntimeConfig,
   resolveNavaiRoute,
+  resolveNavaiVoiceOrbRuntimeSnapshot,
   useWebVoiceAgent
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navai/voice-frontend",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Frontend helpers to build OpenAI Realtime voice agents",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -20,7 +20,9 @@
   "files": [
     "dist",
     "bin",
-    "README.md"
+    "README.md",
+    "README.es.md",
+    "README.en.md"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
@@ -30,6 +32,7 @@
   },
   "dependencies": {
     "@openai/agents": "^0.4.14",
+    "ogl": "^1.0.11",
     "zod": "^4.0.0"
   },
   "peerDependencies": {