npm - hanc-webrtc-widgets - Versions diffs - 2.0.1 → 2.1.0 - Mend

hanc-webrtc-widgets 2.0.1 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/README.md +130 -427
package/dist/hanc-webrtc-widgets.es.js +27790 -7696
package/dist/hanc-webrtc-widgets.umd.js +4599 -480
package/dist/src/components/floating-call/floating-call.d.ts +3 -60
package/dist/src/components/index.d.ts +3 -0
package/dist/src/components/inline-call/inline-call.d.ts +3 -52
package/dist/src/components/orb-widget.d.ts +59 -0
package/dist/src/components/pill-call/index.d.ts +1 -0
package/dist/src/components/pill-call/pill-call.d.ts +4 -0
package/dist/src/core/color-utils.d.ts +1 -0
package/dist/src/core/livekit-call-manager.d.ts +39 -0
package/dist/src/orb/components/HancAiWidget.d.ts +120 -0
package/dist/src/orb/components/index.d.ts +3 -0
package/dist/src/orb/core/AudioAnalyzer.d.ts +68 -0
package/dist/src/orb/core/LiveKitManager.d.ts +46 -0
package/dist/src/orb/core/OrbRenderer.d.ts +86 -0
package/dist/src/orb/core/SoundManager.d.ts +55 -0
package/dist/src/orb/core/index.d.ts +8 -0
package/dist/src/orb/index.d.ts +5 -0
package/dist/src/orb/shaders/glow.glsl.d.ts +4 -0
package/dist/src/orb/shaders/index.d.ts +3 -0
package/dist/src/orb/shaders/orb.frag.glsl.d.ts +1 -0
package/dist/src/orb/shaders/orb.vert.glsl.d.ts +1 -0
package/dist/src/renderers/base-renderer.d.ts +8 -2
package/dist/src/renderers/neural-network-renderer.d.ts +8 -0
package/package.json +4 -2
package/dist/src/components/floating-call/styles.d.ts +0 -6
package/dist/src/components/inline-call/styles.d.ts +0 -1

package/README.md CHANGED Viewed

@@ -1,463 +1,166 @@
-# Hanc-webrtc-widgets
+# Hanc WebRTC Widgets
-**Hanc-webrtc-widgets** is a Web Components library for easily integrating **Hanc AI call widgets** into your website or web application.
+Audio-reactive AI call widgets powered by the **hanc-ai-orb** renderer and LiveKit voice calls. Ship a glossy, stateful orb that reacts to voice, respects system themes, and exposes a full programmatic API.
-It provides ready-to-use, customizable, and lightweight UI widgets for initiating AI-driven voice calls, without the need for any frontend frameworks.
+## Highlights
+- Three.js + GLSL orb with real audio reactivity (agent voice, mic, or simulated)
+- LiveKit calling flow with start/end sounds and clear state handling
+- 3 display modes: inline (hero), float (docked), pill (compact CTA)
+- Theme-aware color presets, custom palettes, and advanced orb tuning via JSON
+- Web Components plus direct `HancAiWidget` class for low-level control
-You can use it in **plain HTML**, or integrate it with **React**, **Next.js**, or any other modern frontend stack.
-## Quick Start
-### HTML Example
+## Quick Start (Web Component)
 ```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <script
-      src="https://unpkg.com/hanc-webrtc-widgets"
-      async
-      type="text/javascript"
-    ></script>
-  </head>
-  <body>
-    <!-- Inline Call Widget -->
-    <hanc-ai-inline-call agent-id="YOUR_AGENT_ID"></hanc-ai-inline-call>
-    <!-- Floating Call Widget -->
-    <hanc-ai-floating-call agent-id="YOUR_AGENT_ID"></hanc-ai-floating-call>
-  </body>
-</html>
-```
-### React Example
-1. Installation lit/react & hanc-webrtc-widgets
-```bash
-npm i @lit/react hanc-webrtc-widgets
-```
-2. Creating a React wrapper and using
-```tsx
-import React from 'react';
-import { createComponent } from '@lit/react';
-import { InlineCall, FloatingCall } from 'hanc-webrtc-widgets';
-export const HancAiInlineCall = createComponent({
-  tagName: 'hanc-ai-inline-call',
-  elementClass: InlineCall,
-  react: React,
-  events: {
-    onCallStart: 'call-start',
-    onCallEnd: 'call-end',
-  },
-});
-export const HancAiFloatingCall = createComponent({
-  tagName: 'hanc-ai-floating-call',
-  elementClass: FloatingCall,
-  react: React,
-  events: {
-    onCallStart: 'call-start',
-    onCallEnd: 'call-end',
-  },
-});
-// An example of a component where both widgets are used
-export default function Example() {
-  return (
-    <>
-      <HancAiInlineCall agentId="YOUR_AGENT_ID" />
-      <HancAiFloatingCall agentId="YOUR_AGENT_ID" />
-    </>
-  );
-}
-```
-### Next.js Example
+<script type="module" src="https://unpkg.com/hanc-webrtc-widgets"></script>
-1. Installation lit/react & hanc-webrtc-widgets
-```bash
-npm i @lit/react hanc-webrtc-widgets
-```
-2. Creating a Next.js wrapper and using
-```tsx
-'use client';
-import React from 'react';
-import dynamic from 'next/dynamic';
-import { createComponent } from '@lit/react';
-export const HancAiInlineCall = dynamic(
-  async () => {
-    const { InlineCall } = await import('hanc-webrtc-widgets');
-    return createComponent({
-      tagName: 'hanc-ai-inline-call',
-      elementClass: InlineCall,
-      react: React,
-      events: {
-        onCallStart: 'call-start',
-        onCallEnd: 'call-end',
-      },
-    });
-  },
-  { ssr: false },
-);
-export const HancAiFloatingCall = dynamic(
-  async () => {
-    const { FloatingCall } = await import('hanc-webrtc-widgets');
-    return createComponent({
-      tagName: 'hanc-ai-floating-call',
-      elementClass: FloatingCall,
-      react: React,
-      events: {
-        onCallStart: 'call-start',
-        onCallEnd: 'call-end',
-      },
-    });
-  },
-  { ssr: false },
-);
-// An example of a component where both widgets are used
-export default function Example() {
-  return (
-    <>
-      <HancAiInlineCall agentId="YOUR_AGENT_ID" />
-      <HancAiFloatingCall agentId="YOUR_AGENT_ID" />
-    </>
-  );
-}
-```
-## Components props & styles
-### `<hanc-ai-inline-call>`
-**Description:**
-An “inline” widget that you embed directly in page content (often as a hero CTA). “Bubble” hints at the round, branded graphic.
-#### Available Attributes:
-| Attribute                | Type   | Description                                              |
-| ------------------------ | ------ | -------------------------------------------------------- |
-| `agent-id` (required)    | string | Agent ID for Twilio calls                                |
-| `button-start-text`      | string | Custom start button text (default: `Start Call with ai`) |
-| `button-connecting-text` | string | Custom connecting button text (default: `Connecting...`) |
-| `button-end-text`        | string | End button text (default: `End call`)                    |
-| `hide-button`            | bool   | Hide the button (orb click still toggles the call)       |
-| `button-position`        | string | Button placement: `top` or `bottom`                      |
-| `orb-color`              | string | Base orb color in idle state                             |
-| `active-orb-color`       | string | Orb color applied when the call becomes active           |
-| `button-color`           | string | Base button color (also used to derive hover/active)      |
-| `button-hover-color`     | string | Button hover color override                              |
-| `button-active-color`    | string | Button active color override                             |
-| `button-text-color`      | string | Button text color                                        |
-#### Available Events:
-| Event Name   | Description                                                  |
-| ------------ | ------------------------------------------------------------ |
-| `call-start` | Fired when a call is successfully connected and starts.      |
-| `call-end`   | Fired when a call ends, either by hangup or due to an error. |
-#### Available CSS Parts for Styling:
-| Part Name         | Description                       |
-| ----------------- | --------------------------------- |
-| `wrapper`         | Outer wrapper container           |
-| `filter-light`    | Light background filter           |
-| `filter-gradient` | Gradient overlay                  |
-| `filter-overlay`  | Active call overlay (state-based) |
-| `video`           | The avatar video element          |
-| `content-wrapper` | Button and content wrapper        |
-| `button`          | The main call button              |
-| `icon-button`     | The call icon inside the button   |
-| `call-off-icon`   | The "end call" icon               |
-| `button-text`     | Text inside the button            |
-#### Example:
-```html
 <hanc-ai-inline-call
-  agent-id="67c34fa38ef2105d28bb287c"
-  button-start-text="Call Agent"
+  agent-id="YOUR_AGENT_ID"
+  voice-service-url="https://voice.hanc.ai"
+  size="320"
+  color-preset="indigo"
+  theme="auto"
 ></hanc-ai-inline-call>
-<style>
-  hanc-ai-inline-call::part(button) {
-    /* your styles here */
-  }
-  hanc-ai-inline-call::part(button-text) {
-    /* your styles here */
-  }
-  hanc-ai-inline-call::part(filter-overlay)[data-calling='true'] {
-    /* your styles here */
-  }
-</style>
 ```
-## Additional customization options (append-only)
-Below are the new properties and examples you can add to the widgets.
-### Theme and visual style
-Themes: `liquid-purple` , `liquid-cyan`, `liquid-pink`, `neural-green`,
-`neural-blue`(default), `orbit-blue`, `synaptic-purple`, `minimal-dark`, `minimal-light`, `custom`.
-Visual styles: `liquid-glass` , `liquid-glass-premium`, `neural-liquid`,
-`neural-orbit`, `neural-network`(default), `synaptic-core`, `organic-sphere`, `morphing-blob`.
+### Other layouts
 ```html
-<hanc-ai-inline-call
+<!-- Floating orb -->
+<hanc-ai-floating-call
   agent-id="YOUR_AGENT_ID"
-  theme="liquid-cyan"
-  visual-style="neural-liquid"
-  orb-size="200"
-></hanc-ai-inline-call>
-```
-### Inline widget new attributes
-- `voice-service-url`
-- `theme`
-- `visual-style`
-- `orb-size`
-- `button-end-text`
-- `hide-button`
-- `button-position`
-- `orb-color`
-- `active-orb-color`
-- `button-color`
-- `button-hover-color`
-- `button-active-color`
-- `button-text-color`
+  voice-service-url="https://voice.hanc.ai"
+  color-preset="cyan"
+  theme="auto"
+></hanc-ai-floating-call>
-```html
-<hanc-ai-inline-call
+<!-- Pill CTA -->
+<hanc-ai-pill-call
   agent-id="YOUR_AGENT_ID"
-  voice-service-url="https://voice.example.com"
-  theme="minimal-light"
-  visual-style="morphing-blob"
-  orb-size="220"
-  button-end-text="Stop"
-></hanc-ai-inline-call>
+  voice-service-url="https://voice.hanc.ai"
+  button-text="Talk to AI"
+  active-button-text="End call"
+  color-preset="rose"
+></hanc-ai-pill-call>
 ```
-### Floating widget new attributes
-- `voice-service-url`
-- `theme`
-- `visual-style`
-- `position`
-- `offset-x`
-- `offset-y`
-- `orb-size`
-- `hide-button`
-- `button-position`
-- `orb-color`
-- `active-orb-color`
-- `button-color`
-- `button-hover-color`
-- `button-active-color`
-- `button-text-color`
-- `minimized`
+### Attributes (shared across widgets)
+- `agent-id` *(string, required for real calls)*
+- `voice-service-url` *(string, required for real calls)*
+- `size` *(number, default 280 — not used in pill mode)*
+- `mode` *(inline \| float \| pill — only on `<hanc-ai-orb>`)*
+- `position` *(center \| bottom-right \| bottom-left \| top-right \| top-left — used in float mode)*
+- `button-text` / `active-button-text` / `connecting-text` *(strings)*
+- `color-preset` *(indigo | cyan | emerald | rose | amber — uses dark/light versions automatically when `theme="auto"`)*
+- `colors` *(JSON string `{"primary":"#...","secondary":"#..."}` to override the preset)*
+- `orb-config` *(JSON string for advanced control: `morphStrength`, `glowIntensity`, `audioReactivity`, `idleGlowMultiplier`, etc.)*
+- `theme` *(`auto` | `dark` | `light`, default `auto` — adjusts palette and glow)*
+- `enable-sounds` *(boolean, default true)*
+- `sound-volume` *(number 0.0–1.0, default 0.3)*
+- Legacy aliases are still accepted: `button-start-text`, `button-end-text`, `button-connecting-text`.
+### Events
+- `call-start` — `{ agentId, timestamp }`
+- `call-end` — `{ agentId, duration, reason, timestamp }`
+- `state-change` — `{ state: 'idle' | 'connecting' | 'active' | 'ending' | 'error', previousState }`
+- `error` — `{ error }`
+```js
+const orb = document.querySelector('hanc-ai-inline-call');
+orb.addEventListener('state-change', e => {
+  console.log('state', e.detail.state);
+});
-```html
-<hanc-ai-floating-call
-  agent-id="YOUR_AGENT_ID"
-  voice-service-url="https://voice.example.com"
-  theme="neural-green"
-  visual-style="neural-network"
-  position="top-left"
-  offset-x="32"
-  offset-y="32"
-  orb-size="140"
-  minimized
-></hanc-ai-floating-call>
+orb.addEventListener('call-start', e => {
+  console.log('connected to', e.detail.agentId);
+});
 ```
-### CSS variables (when using theme="custom")
-```css
-hanc-ai-inline-call {
-  --hanc-button: linear-gradient(135deg, #0ea5e9 0%, #22d3ee 100%);
-  --hanc-button-hover: linear-gradient(135deg, #0284c7 0%, #0ea5e9 100%);
-  --hanc-button-active: linear-gradient(135deg, #ef4444 0%, #dc2626 100%);
-  --hanc-button-text: #ffffff;
-  --hanc-button-radius: 16px;
-  --hanc-button-shadow: rgba(14, 165, 233, 0.35);
-  --hanc-button-shadow-hover: rgba(14, 165, 233, 0.45);
-  --hanc-button-shadow-active: rgba(239, 68, 68, 0.45);
-  --hanc-orb-active-glow: rgba(14, 165, 233, 0.35);
-  --hanc-orb-z-index: 10000;
-  --hanc-widget-z-index: 9999;
-}
-hanc-ai-floating-call {
-  --hanc-background: rgba(10, 10, 20, 0.9);
-  --hanc-glow-shadow: rgba(14, 165, 233, 0.2);
-  --hanc-orb-size: 140px;
-  --hanc-orb-active-glow: rgba(14, 165, 233, 0.35);
-  --hanc-orb-z-index: 10000;
-  --hanc-widget-z-index: 9999;
-}
+## Direct API (HancAiWidget)
+Import the low-level class when you need manual control, external media streams, or custom placement.
+```ts
+import { HancAiWidget } from 'hanc-webrtc-widgets';
+const widget = new HancAiWidget('#container', {
+  agentId: 'YOUR_AGENT_ID',
+  voiceServiceUrl: 'https://voice.hanc.ai',
+  mode: 'float',
+  position: 'bottom-right',
+  size: 280,
+  buttonText: 'Start call',
+  activeButtonText: 'End call',
+  colors: { primary: '#38bdf8', accent: '#c084fc' },
+  orbConfig: { audioReactivity: 3.5, glowIntensity: 0.8 },
+  onStateChange: (state, prev) => console.log(state, prev),
+  onCallStart: e => console.log('started', e.agentId),
+  onCallEnd: e => console.log('ended after', e.duration, 'ms'),
+});
+// Control
+await widget.startCall();
+widget.setColors({ glow: '#c7d2fe' });
+widget.setGlowSettings(0.8, 0.4); // e.g. dark theme
+await widget.endCall();
+widget.destroy();
 ```
-#### Custom theme examples
+### Audio helpers
+- `connectAudioStream(stream: MediaStream)` — drive the orb from any audio stream
+- `connectMicrophone()` / `disconnectMicrophone()` — mic-driven visuals (demo mode)
+- `isConnected()` / `getState()` — quick state checks
-Tip: set `theme="custom"` and override only the variables you need. All other values fall back to defaults.
+## Voice Service Requirements
-```html
-<hanc-ai-inline-call
-  agent-id="YOUR_AGENT_ID"
-  theme="custom"
-  visual-style="neural-network"
-  active-orb-color="#22c55e"
-></hanc-ai-inline-call>
+The widget expects a `/connect` endpoint on your voice service:
-<style>
-  hanc-ai-inline-call {
-    --hanc-background: rgba(10, 15, 20, 0.8);
-    --hanc-orb-size: 220px;
-    --hanc-button: linear-gradient(135deg, #0ea5e9 0%, #22c55e 100%);
-    --hanc-button-hover: linear-gradient(135deg, #0284c7 0%, #16a34a 100%);
-    --hanc-button-active: linear-gradient(135deg, #ef4444 0%, #dc2626 100%);
-    --hanc-button-text: #ffffff;
-    --hanc-orb-active-glow: rgba(34, 197, 94, 0.4);
-  }
-</style>
+```
+POST /connect
+Body: { "agentId": "<your-agent-id>" }
+Response: { "token": "<livekit-token>", "url": "<wss://...>" }
 ```
-```html
-<hanc-ai-inline-call
-  agent-id="YOUR_AGENT_ID"
-  theme="custom"
-  visual-style="neural-orbit"
-  button-position="top"
-></hanc-ai-inline-call>
+Set `voice-service-url` (or `VITE_VOICE_SERVICE_URL`) to point at this service.
-<style>
-  hanc-ai-inline-call {
-    --hanc-orb-size: 260px;
-    --hanc-button-radius: 999px;
-    --hanc-button: linear-gradient(135deg, #111827 0%, #374151 100%);
-    --hanc-button-hover: linear-gradient(135deg, #1f2937 0%, #111827 100%);
-    --hanc-button-active: linear-gradient(135deg, #ef4444 0%, #b91c1c 100%);
-    --hanc-button-text: #f9fafb;
-    --hanc-orb-active-glow: rgba(59, 130, 246, 0.35);
-  }
-</style>
-```
+## Framework Usage
-```html
-<hanc-ai-floating-call
-  agent-id="YOUR_AGENT_ID"
-  theme="custom"
-  position="top-right"
-  button-position="top"
-  active-orb-color="#f97316"
-></hanc-ai-floating-call>
+Register the custom elements once and use them anywhere. Example for React with `@lit/react`:
-<style>
-  hanc-ai-floating-call {
-    --hanc-background: rgba(255, 255, 255, 0.92);
-    --hanc-text: rgba(24, 24, 27, 0.8);
-    --hanc-glow-shadow: rgba(249, 115, 22, 0.2);
-    --hanc-orb-size: 120px;
-    --hanc-button: linear-gradient(135deg, #f97316 0%, #f59e0b 100%);
-    --hanc-button-hover: linear-gradient(135deg, #ea580c 0%, #f97316 100%);
-    --hanc-button-active: linear-gradient(135deg, #b91c1c 0%, #991b1b 100%);
-    --hanc-button-text: #ffffff;
-  }
-</style>
-```
+```ts
+import React from 'react';
+import { createComponent } from '@lit/react';
+import { InlineCall, FloatingCall, PillCall } from 'hanc-webrtc-widgets';
----
-### `<hanc-ai-floating-call>`
-**Description:**
-A persistent, docked widget that floats in the corner and launches the same voice-call flow from anywhere on the page.
-#### Available Attributes:
-| Attribute                | Type   | Description                                              |
-| ------------------------ | ------ | -------------------------------------------------------- |
-| `agent-id` (required)    | string | Agent ID for Twilio calls                                |
-| `label-text`             | string | Label above the button (default: `Need a help?`)         |
-| `button-start-text`      | string | Start button text (default: `Start Call with ai`)        |
-| `button-connecting-text` | string | Custom connecting button text (default: `Connecting...`) |
-| `button-end-text`        | string | End button text (default: `End call`)                    |
-| `hide-button`            | bool   | Hide the button (orb click still toggles the call)       |
-| `button-position`        | string | Button placement: `top` or `bottom`                      |
-| `orb-color`              | string | Base orb color in idle state                             |
-| `active-orb-color`       | string | Orb color applied when the call becomes active           |
-| `button-color`           | string | Base button color (also used to derive hover/active)      |
-| `button-hover-color`     | string | Button hover color override                              |
-| `button-active-color`    | string | Button active color override                             |
-| `button-text-color`      | string | Button text color                                        |
-#### Available Events:
-| Event Name   | Description                                                  |
-| ------------ | ------------------------------------------------------------ |
-| `call-start` | Fired when a call is successfully connected and starts.      |
-| `call-end`   | Fired when a call ends, either by hangup or due to an error. |
-#### Available CSS Parts for Styling:
-| Part Name         | Description                       |
-| ----------------- | --------------------------------- |
-| `root`            | Outer container                   |
-| `avatar-wrapper`  | Wrapper for avatar/video          |
-| `filter-light`    | Light background filter           |
-| `filter-gradient` | Gradient overlay                  |
-| `filter-overlay`  | Active call overlay (state-based) |
-| `avatar-video`    | The avatar video element          |
-| `content`         | Container for label and button    |
-| `title`           | The label/title text              |
-| `button`          | The main call button              |
-| `icon-button`     | The call icon inside the button   |
-| `button-text`     | Text inside the button            |
-#### Example:
+export const HancInline = createComponent({
+  tagName: 'hanc-ai-inline-call',
+  elementClass: InlineCall,
+  react: React,
+  events: { onCallStart: 'call-start', onCallEnd: 'call-end' },
+});
-```html
-<hanc-ai-floating-call
-  agent-id="67c34fa38ef2105d28bb287c"
-  label-text="Need Assistance?"
-  button-start-text="Start Call"
-  button-end-text="End Call"
-></hanc-ai-floating-call>
+export const HancFloating = createComponent({
+  tagName: 'hanc-ai-floating-call',
+  elementClass: FloatingCall,
+  react: React,
+  events: { onCallStart: 'call-start', onCallEnd: 'call-end' },
+});
-<style>
-  hanc-ai-floating-call::part(root) {
-    /* your styles here */
-  }
+export const HancPill = createComponent({
+  tagName: 'hanc-ai-pill-call',
+  elementClass: PillCall,
+  react: React,
+  events: { onCallStart: 'call-start', onCallEnd: 'call-end' },
+});
+```
-  hanc-ai-floating-call::part(title) {
-    /* your styles here */
-  }
+## Theming Tips
+- `theme="auto"` listens to `prefers-color-scheme` and switches presets/glow for you.
+- Use `color-preset` for quick palettes (`indigo`, `cyan`, `emerald`, `rose`, `amber`).
+- Override any color with `colors='{"accent":"#8b5cf6","glow":"#c084fc"}'`.
+- For light themes, pair with `orb-config='{"idleGlowMultiplier":0.2,"glowIntensity":0.4}'`.
-  hanc-ai-floating-call::part(button) {
-    /* your styles here */
-  }
+## License
-  hanc-ai-floating-call::part(filter-overlay)[data-calling='true'] {
-    /* your styles here */
-  }
-</style>
-```
+MIT