@convai/web-widget 0.2.1 → 0.3.0

package/README.md

@@ -13,7 +13,7 @@ production** — [step two](#before-you-ship) moves it to your server.
 
 ```html
 <convai-widget character-id="YOUR_CHARACTER_ID" api-key="YOUR_API_KEY"></convai-widget>
-<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.2.1/v1.js" async></script>
+<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.3.0/v1.js" async></script>
 ```
 
 A launcher bubble appears in the bottom-right corner. Click it: the runtime
@@ -26,7 +26,7 @@ The script tag goes in your HTML shell; the element is ordinary JSX.
 
 ```html
 <!-- index.html -->
-<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.2.1/v1.js" async></script>
+<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.3.0/v1.js" async></script>
 ```
 
 ```jsx
@@ -65,6 +65,28 @@ export function Chat() {
 }
 ```
 
+`convaiClient` takes any `ConvaiClient`, not only `useConvaiClient`'s: one you
+built with `new ConvaiClient(...)`, or the character's own client from
+`@convai/embody`. The widget subscribes to its events itself and never opens a
+second connection.
+
+```tsx
+import { useState } from 'react'
+import type { ConvaiClient } from '@convai/web-sdk/core'
+import { ConvaiCharacter } from '@convai/embody/react'
+import { ConvaiWidget } from '@convai/web-widget/react'
+
+export function CharacterWithChat() {
+  const [client, setClient] = useState<ConvaiClient | null>(null)
+  return (
+    <>
+      <ConvaiCharacter apiKey={API_KEY} characterId={CHARACTER_ID} onReady={(c) => setClient(c.client)} />
+      {client && <ConvaiWidget convaiClient={client} />}
+    </>
+  )
+}
+```
+
 **No framework**
 
 ```ts
@@ -145,16 +167,16 @@ guide; theming and `::part()` hooks; CSP requirements; and guidance on
 
 ## Versioning
 
-`0.2.1` is a stable release: `npm install @convai/web-widget` and
+`0.3.0` is a stable release: `npm install @convai/web-widget` and
 jsDelivr's unversioned URL both resolve it. Pin the exact version anyway for
 reproducible deploys —
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.2.1/v1.js" async></script>
+<script src="https://cdn.jsdelivr.net/npm/@convai/web-widget@0.3.0/v1.js" async></script>
 ```
 
 ```bash
-npm install @convai/web-widget@0.2.1   # only needed to self-host the two files
+npm install @convai/web-widget@0.3.0   # only needed to self-host the two files
 ```
 
 This package is early, and it bundles a prerelease of `@convai/web-sdk`. The

package/index.js

@@ -1,4 +1,4 @@
-const VERSION = "0.2.1";
+const VERSION = "0.3.0";
 export {
   VERSION
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@convai/web-widget",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Two-line script-tag embed for the Convai chat widget. A <convai-widget> custom element with a closed shadow root and a lazily loaded runtime.",
   "homepage": "https://docs.convai.com/embed",
   "repository": {

package/react.js

@@ -1,5 +1,5 @@
 import { jsxs, jsx, Fragment } from "react/jsx-runtime";
-import React, { useState, useEffect, useRef, useCallback, useMemo } from "react";
+import React, { useMemo, useReducer, useEffect, useState, useRef, useCallback } from "react";
 import { motion, AnimatePresence } from "framer-motion";
 import { useLocalParticipant, useRoomContext, RoomContext, VideoTrack } from "@livekit/components-react";
 import { RoomContext as RoomContext2, RoomAudioRenderer } from "@livekit/components-react";
@@ -9,6 +9,91 @@ import { freshPublicationGrantOptions } from "@convai/web-sdk/embed";
 import styled from "styled-components";
 import { p as presentationStyles, M as MAX_CARDS_PER_MESSAGE, i as injectKeyframes, P as PREVIEW_TIMEOUT_MS, g as glyph, o as openLightbox } from "./chunks/lightbox-Dxfdw3VU.js";
 import { Track } from "livekit-client";
+function listen(target, event, fn) {
+  if (!(target == null ? void 0 : target.on)) return () => {
+  };
+  const result = target.on(event, fn);
+  if (typeof result === "function") return result;
+  return () => {
+    var _a;
+    return (_a = target.off) == null ? void 0 : _a.call(target, event, fn);
+  };
+}
+function activityOf(state) {
+  if (!state) return "Idle";
+  if (state.isSpeaking) return "Speaking";
+  if (state.isListening) return "Listening";
+  if (state.isThinking) return "Thinking";
+  if (state.isConnected) return "Connected";
+  return "Idle";
+}
+function isManagedClient(client) {
+  return typeof client.isAudioMuted === "boolean";
+}
+function useLiveClientView(client) {
+  const { fields, version, managed } = useLiveClientState(client);
+  return useMemo(() => {
+    if (managed) return client;
+    return new Proxy(client, {
+      get(target, prop, receiver) {
+        if (typeof prop === "string" && prop in fields) return fields[prop];
+        const value = Reflect.get(target, prop, target);
+        return typeof value === "function" ? value.bind(target) : value;
+      },
+      has(target, prop) {
+        return typeof prop === "string" && prop in fields || Reflect.has(target, prop);
+      }
+    });
+  }, [client, managed, version]);
+}
+function useLiveClientState(client) {
+  var _a, _b, _c, _d, _e, _f, _g;
+  const managed = isManagedClient(client);
+  const [version, rerender] = useReducer((n) => n + 1, 0);
+  useEffect(() => {
+    if (managed) return;
+    const c = client;
+    const unsubs = [
+      ...[
+        "stateChange",
+        "messagesChange",
+        "userTranscriptionChange",
+        "speakingChange",
+        "botReady",
+        "connect",
+        "disconnect"
+      ].map((event) => listen(c, event, rerender)),
+      listen(c.audioControls, "audioStateChange", rerender),
+      listen(c.videoControls, "videoStateChange", rerender),
+      listen(c.screenShareControls, "screenShareStateChange", rerender)
+    ];
+    rerender();
+    return () => unsubs.forEach((unsubscribe) => unsubscribe());
+  }, [client, managed]);
+  if (managed) {
+    return {
+      managed,
+      version,
+      fields: {
+        activity: (_a = client.activity) != null ? _a : activityOf(client.state),
+        isAudioMuted: client.isAudioMuted,
+        isVideoEnabled: Boolean(client.isVideoEnabled),
+        isScreenShareActive: Boolean(client.isScreenShareActive)
+      }
+    };
+  }
+  const controls = client;
+  return {
+    managed,
+    version,
+    fields: {
+      activity: activityOf(client.state),
+      isAudioMuted: (_c = (_b = controls.audioControls) == null ? void 0 : _b.isAudioMuted) != null ? _c : true,
+      isVideoEnabled: (_e = (_d = controls.videoControls) == null ? void 0 : _d.isVideoEnabled) != null ? _e : false,
+      isScreenShareActive: (_g = (_f = controls.screenShareControls) == null ? void 0 : _f.isScreenShareActive) != null ? _g : false
+    }
+  };
+}
 function renderTree(tree) {
   return tree.map(
     (node, i) => React.createElement(node.tag, { key: i, ...node.attr }, renderTree(node.child))
@@ -2702,7 +2787,7 @@ const VoiceModeOverlay = ({
   );
 };
 const ConvaiWidget = ({
-  convaiClient,
+  convaiClient: givenClient,
   showVideo = true,
   showScreenShare = true,
   defaultVoiceMode = true,
@@ -2712,6 +2797,7 @@ const ConvaiWidget = ({
   linkPreviewResolver
 }) => {
   var _a, _b, _c, _d;
+  const convaiClient = useLiveClientView(givenClient);
   const isTextOnly = Boolean(requestPublicationGrant) || convaiClient.connectionType === "text";
   const {
     name: fetchedCharacterName,

package/ui/react/components/ConvaiWidget.d.ts

@@ -1,14 +1,15 @@
+import { type LiveClientFields } from "../hooks/useLiveClient";
 import type { LinkPreviewResolver } from "@convai/web-sdk/core";
 import type { IConvaiClient, PublishedChatConnectOptions } from "@convai/web-sdk/core";
 import type { PublishedChatDescriptor } from "@convai/web-sdk/embed";
 interface ConvaiWidgetProps {
-    /** Convai client instance (required) */
-    convaiClient: IConvaiClient & {
-        activity?: string;
-        isAudioMuted: boolean;
-        isVideoEnabled: boolean;
-        isScreenShareActive: boolean;
-    };
+    /**
+     * The Convai client (required). Either `useConvaiClient`'s result, or any
+     * `ConvaiClient` — one built with `new ConvaiClient(...)`, or the character's
+     * own client from `@convai/embody`. The widget subscribes to a bare client's
+     * events itself and never opens a second connection.
+     */
+    convaiClient: IConvaiClient & Partial<LiveClientFields>;
     /**
      * Show video toggle button in settings (default: true).
      * Only works if connection type is "video". If false, hides the video button.

package/ui/react/hooks/useLiveClient.d.ts

@@ -0,0 +1,26 @@
+import type { IConvaiClient } from "@convai/web-sdk/core";
+/** The fields `useConvaiClient` adds on top of the client. */
+export interface LiveClientFields {
+    activity: string;
+    isAudioMuted: boolean;
+    isVideoEnabled: boolean;
+    isScreenShareActive: boolean;
+}
+/** True for a `useConvaiClient` result, which carries the UI fields itself. */
+export declare function isManagedClient(client: object): boolean;
+/**
+ * The four UI fields for `client`: its own when `useConvaiClient` supplied
+ * them, otherwise read live from the client, re-rendering on every change.
+ */
+export declare function useLiveClient(client: IConvaiClient & Partial<LiveClientFields>): LiveClientFields;
+/**
+ * The client as the widget should see it: a `useConvaiClient` result as-is,
+ * otherwise a view that adds the four UI fields and changes identity on every
+ * client event — exactly how a `useConvaiClient` result behaves, so the widget
+ * and its children re-render and re-run their effects the same way.
+ *
+ * A Proxy, not a copy: reads, writes and `this` inside methods all reach the
+ * real client, and only the four fields are answered here. The app's own
+ * reference to the client is never modified.
+ */
+export declare function useLiveClientView<C extends IConvaiClient & Partial<LiveClientFields>>(client: C): C & LiveClientFields;