@convai/web-widget 0.1.4 → 0.2.0

package/ui/vanilla/styles.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Vanilla Styles - Port of React theme system for vanilla implementations
+ */
+export declare const aeroTheme: {
+    colors: {
+        primary: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        convai: {
+            light: string;
+            medium: string;
+            dark: string;
+        };
+        neutral: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        glass: {
+            light: string;
+            medium: string;
+            dark: string;
+            backdrop: string;
+            card: string;
+            backdropLight: string;
+            borderLight: string;
+        };
+        accent: {
+            purple: string;
+            green: string;
+            blue: string;
+            orange: string;
+            red: string;
+        };
+        error: {
+            50: string;
+            100: string;
+            200: string;
+            300: string;
+            400: string;
+            500: string;
+            600: string;
+            700: string;
+            800: string;
+            900: string;
+        };
+        text: {
+            primary: string;
+            secondary: string;
+            tertiary: string;
+            inverse: string;
+        };
+    };
+    typography: {
+        fontFamily: {
+            primary: string;
+            body: string;
+            mono: string;
+        };
+        fontSize: {
+            xs: string;
+            sm: string;
+            base: string;
+            lg: string;
+            xl: string;
+            "2xl": string;
+            "3xl": string;
+            "4xl": string;
+        };
+        fontWeight: {
+            normal: number;
+            medium: number;
+            semibold: number;
+            bold: number;
+        };
+    };
+    spacing: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        "2xl": string;
+        "3xl": string;
+    };
+    borderRadius: {
+        none: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        "2xl": string;
+        full: string;
+    };
+    shadows: {
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+        glass: string;
+    };
+    glass: {
+        backdrop: string;
+        backdropLight: string;
+        backdropHeavy: string;
+        border: string;
+        borderLight: string;
+    };
+    transitions: {
+        fast: string;
+        normal: string;
+        slow: string;
+        spring: string;
+        snappy: string;
+    };
+    zIndex: {
+        base: number;
+        dropdown: number;
+        sticky: number;
+        fixed: number;
+        modal: number;
+        popover: number;
+        tooltip: number;
+    };
+};
+/**
+ * Global CSS styles for the Convai widget
+ * This should be injected once into the document head
+ */
+export declare const getGlobalStyles: () => string;
+/**
+ * A document (the default) or a shadow root the widget is mounted inside.
+ * `@keyframes` and global styles must be injected per-target because
+ * shadow trees do not resolve rules defined in the document head.
+ */
+export type StyleTarget = Document | ShadowRoot;
+/**
+ * Inject the widget's global styles into a document or a shadow root.
+ * Defaults to the document, so existing callers are unaffected.
+ */
+export declare const injectGlobalStyles: (target?: StyleTarget) => void;
+/**
+ * Inject the widget's `@keyframes` (e.g. the settings tray's `popIn`)
+ * into a document or a shadow root. `@keyframes` defined in the document
+ * do not resolve for shadow content, so they must be injected into each
+ * shadow root that uses them.
+ */
+export declare const injectKeyframes: (target?: StyleTarget) => void;
+/**
+ * Helper to create inline styles object from theme
+ */
+export declare const createStyles: (styles: Record<string, any>) => string;

package/ui/vanilla/types.d.ts

@@ -0,0 +1,170 @@
+import type { IConvaiClient, ChatMessage, PublishedChatConnectOptions } from '@convai/web-sdk/core';
+import type { PublishedChatDescriptor } from '@convai/web-sdk/embed';
+import type { LinkPreviewResolver } from "@convai/web-sdk/core";
+/** Where the widget anchors itself. `inline` renders it in normal document flow. */
+export type WidgetPlacement = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'inline';
+/**
+ * Options for creating a vanilla ConvaiWidget
+ *
+ * You can either:
+ * 1. Pass an existing convaiClient instance, OR
+ * 2. Pass connection config (apiKey, characterId, etc.) directly
+ */
+export interface VanillaWidgetOptions {
+    /**
+     * Option 1: Pass an existing Convai client instance.
+     * Should be initialized with config: new ConvaiClient({ apiKey, characterId, ... })
+     * The widget will auto-connect on first click.
+     */
+    convaiClient?: IConvaiClient & {
+        activity?: string;
+        chatMessages: ChatMessage[];
+        /**
+         * Present on the real `ConvaiClient` (it extends `EventEmitter`) and on
+         * the test stubs; absent only if a caller hand-rolls a minimal
+         * `IConvaiClient`. Optional so that case still type-checks -- the widget
+         * calls it defensively (`client.emit?.(...)`) to surface mic-permission
+         * failures on the same `error` channel `ConvaiClient` already uses.
+         */
+        emit?: (event: string, ...args: any[]) => void;
+    };
+    /** Option 2: Pass connection config directly (convenience shortcut). Either apiKey or authToken is required. */
+    apiKey?: string;
+    /** Auth token for realtime API (alternative to apiKey). See https://realtime-api.convai.com/docs */
+    authToken?: string;
+    characterId?: string;
+    enableVideo?: boolean;
+    startWithVideoOn?: boolean;
+    /** Enable lipsync/facial animation blendshapes (default: false) */
+    enableLipsync?: boolean;
+    /** Enable emotion detection and bot-emotion updates (default: false) */
+    enableEmotion?: boolean;
+    /** Log incoming and outgoing decoded RTVI data messages to the browser console (default: true) */
+    logRtviMessages?: boolean;
+    /** Blendshape configuration for facial animation format */
+    blendshapeConfig?: {
+        /** Format of blendshapes: "arkit" or "mha" (Meta Human Animation, default: "mha") */
+        format?: "arkit" | "mha";
+        /** Custom mapper function to transform incoming blendshapes */
+        customMapper?: (input: number[] | Float32Array) => Float32Array;
+        /** Indexed NeuroSync ahead-delivery. Defaults to true; set false for the legacy paced path. */
+        deliver_chunks_ahead?: boolean;
+        /** Ahead-delivery timeline FPS override; ignored when deliver_chunks_ahead is false. */
+        output_fps?: number;
+        /** Seconds the server buffers blendshapes before releasing them. */
+        frames_buffer_duration?: number;
+    };
+    /**
+     * Show video toggle button in settings (default: true).
+     * Only works if connection type is "video". If false, hides the video button.
+     */
+    showVideo?: boolean;
+    /**
+     * Show screen share toggle button in settings (default: true).
+     * Only works if connection type is "video". If false, hides the screen share button.
+     */
+    showScreenShare?: boolean;
+    /**
+     * Start in voice mode by default when widget opens (default: true).
+     * When true, the widget will open directly in voice mode with microphone enabled.
+     */
+    defaultVoiceMode?: boolean;
+    /**
+     * Open Graph lookup for plain web links the character sends. Supply a
+     * function that asks your backend for a page's metadata and each such link
+     * gets a site card (favicon, site name, title, description, image) once it
+     * resolves. Omit it and links render as before. See
+     * docs/convai_link_previews.md, "Site cards".
+     */
+    linkPreviewResolver?: LinkPreviewResolver;
+    /** Mint a fresh single-use grant when a published-chat session is reopened. */
+    requestPublicationGrant?: () => Promise<string>;
+    /** Core endpoint override used with requestPublicationGrant. */
+    publishedChatConnectOptions?: PublishedChatConnectOptions;
+    /** Public descriptor used to label a credential-free published session. */
+    publishedChatDescriptor?: Pick<PublishedChatDescriptor, 'display_name' | 'image_url'>;
+    /**
+     * Where the widget's `<style>` and `@keyframes` nodes are injected.
+     *
+     * Omit it and the target is derived from `container.getRootNode()` at
+     * construction time — correct only when the container is *already* inside
+     * its final root. A custom element that builds its subtree first and appends
+     * it to its shadow root afterwards (the usual pattern) constructs the widget
+     * while the container is still detached, so the derivation sees the
+     * document and the shadow root never receives the stylesheet or the `popIn`
+     * keyframes — silently, with no error. Pass the shadow root here in that
+     * case; when supplied it is used verbatim and no derivation happens.
+     */
+    styleTarget?: Document | ShadowRoot;
+    /** Corner to anchor to, or `inline` for normal flow. Default `bottom-right`. */
+    placement?: WidgetPlacement;
+    /** Optional callbacks */
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+    onMessage?: (message: ChatMessage) => void;
+}
+/**
+ * Vanilla ConvaiWidget instance with cleanup method
+ */
+export interface VanillaWidget {
+    /** Root DOM element of the widget */
+    element: HTMLElement;
+    /** Cleanup and destroy the widget */
+    destroy: () => void;
+    /** The Convai client instance */
+    client: IConvaiClient & {
+        activity?: string;
+        chatMessages: ChatMessage[];
+        emit?: (event: string, ...args: any[]) => void;
+    };
+    /** Update widget state (for future extensions) */
+    update?: (options: Partial<VanillaWidgetOptions>) => void;
+    /**
+     * Open the panel. Drives the same internal open path as the launcher
+     * click (connect-on-first-open, then the morph to the panel). Idempotent:
+     * calling `open()` while already open — or while a first open is still
+     * waiting on `connect()` — is a no-op. It will not re-run the morph
+     * animation, and it will not start a second connect.
+     */
+    open: () => void;
+    /**
+     * Close the panel. Drives the same internal path as the header's close
+     * button. Idempotent: calling `close()` while already closed is a no-op.
+     *
+     * Called while a first open is still connecting, it *cancels* that open:
+     * the connect completes (the client ends up connected) but the panel stays
+     * collapsed rather than popping open once the promise resolves.
+     */
+    close: () => void;
+    /**
+     * Toggle the panel open or closed, per the current {@link isOpen} state.
+     * Mid-connect this closes — i.e. a second click cancels the open in flight,
+     * rather than queueing a second one.
+     */
+    toggle: () => void;
+    /**
+     * Whether the panel is open, or is opening. This is *requested* state, and
+     * it updates synchronously: `widget.open(); widget.isOpen` is always `true`,
+     * including on a cold client where the panel is only committed once
+     * `connect()` resolves seconds later. Cancelling that open (via `close()`,
+     * `toggle()`, or a second launcher click) returns it to `false`
+     * immediately.
+     *
+     * The distinction matters only for the first open on a disconnected client;
+     * every other transition is synchronous, so rendered and requested state
+     * coincide. Consumers reconciling their own open/close events against this
+     * flag get the answer that matches the user's last instruction, not the
+     * animation frame.
+     */
+    readonly isOpen: boolean;
+    /**
+     * Insert a message into the transcript locally, without sending it to the
+     * character. Use this for client-side lines — e.g. a greeting — that must
+     * appear in the chat but must never reach the LLM and must never be billed
+     * as a turn. This is not `sendUserTextMessage`: nothing is transmitted.
+     */
+    appendMessage: (message: {
+        sender: "user" | "bot";
+        content: string;
+    }) => void;
+}

package/vanilla.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `@convai/web-widget/vanilla` — the chat UI without a framework.
+ *
+ * This moved here from `@convai/web-sdk/vanilla`, which keeps the client side:
+ * `ConvaiClient`, `AudioRenderer` and the WebSocket transport. Take the client
+ * from there and the interface from here:
+ *
+ * ```ts
+ * import { ConvaiClient } from '@convai/web-sdk/core'
+ * import { createConvaiWidget } from '@convai/web-widget/vanilla'
+ *
+ * const client = new ConvaiClient({ apiKey, characterId })
+ * createConvaiWidget(document.body, { convaiClient: client })
+ * ```
+ *
+ * No React, no styled-components, no framer-motion: the vanilla widget is
+ * hand-written DOM and CSS, so this entry pulls in none of the React UI's
+ * dependencies. Importing it has no side effects.
+ */
+export { createConvaiWidget, destroyConvaiWidget } from './ui/vanilla/ConvaiWidget';
+export type { VanillaWidget, VanillaWidgetOptions, WidgetPlacement } from './ui/vanilla/types';