@pinecall/skills 0.1.0

package/skills/pinecall-web-widget/references/web/widget/props.md

@@ -0,0 +1,291 @@
+---
+title: "Props"
+description: "Every prop the VoiceWidget accepts — including token security, tools, theming, and multi-language."
+---
+
+# Props
+
+Full reference for `<VoiceWidget />`.
+
+## All props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `agent` | `string` | **required** | Agent ID to connect to |
+| `server` | `string` | `"https://voice.pinecall.io"` | Pinecall API base URL (override for self-hosted) |
+| `name` | `string` | `"Agent"` | Display name shown in status label |
+| `label` | `string` | `"Talk to {name}"` | Tooltip shown on hover when idle |
+| `preset` | `VoiceWidgetPreset` | `"dark"` | Theme preset (`dark`, `midnight`, `aurora`, `sunset`, `light`) |
+| `theme` | `Partial<VoiceWidgetTheme>` | — | Custom theme overrides, merged on top of `preset` |
+| `config` | `Record<string, unknown>` | — | Session config overrides (voice, STT, language) |
+| `metadata` | `Record<string, unknown>` | — | Metadata passed to the agent (available as `call.metadata`) |
+| `languages` | `Record<string, LanguagePreset>` | — | Multi-language presets (see below) |
+| `defaultLanguage` | `string` | first key | Initial language selection |
+| `onLanguageChange` | `(lang, preset) => void` | — | Called when the user picks a language |
+| `tokenProvider` | `() => Promise<{token, server}>` | — | Custom token provider for WebRTC (keeps API keys server-side) |
+| `trackedTools` | `string[]` | — | Tool names to track in widget state for UI rendering |
+| `tools` | `Record<string, ToolRenderer>` | — | Map of tool names → render functions for inline tool UI |
+| `onStatusChange` | `(status) => void` | — | Called when connection status changes |
+| `className` | `string` | — | Extra CSS class on the root wrapper |
+
+## `tokenProvider` — token security
+
+Browser connections require **short-lived tokens**. Your backend generates them using `@pinecall/sdk`, and the widget fetches them via the `tokenProvider` callback. This keeps your API key server-side.
+
+### Backend setup
+
+```typescript
+// server.js
+import express from "express";
+import { Pinecall } from "@pinecall/sdk";
+
+const app = express();
+const pc = new Pinecall();
+
+const florencia = pc.agent("florencia", {
+  voice: "elevenlabs/sarah",
+  language: "es",
+  stt: "deepgram/flux-en",
+  llm: "openai/gpt-5-chat-latest",
+  prompt: "...",
+  greeting: "¡Hola!",
+});
+
+// Token endpoint — add your own auth in production
+app.get("/api/token", authMiddleware, async (req, res) => {
+  const token = await florencia.createToken("webrtc");
+  res.json(token);
+});
+
+app.listen(3000);
+```
+
+### Two ways to generate tokens
+
+| Method | When to use |
+|---|---|
+| `agent.createToken(channel)` | You have the `Agent` instance in the same process |
+| `pc.createToken(channel, agentId)` | The agent runs in a separate process; you only have the `Pinecall` client |
+
+```typescript
+// Option A: from the agent instance
+const token = await florencia.createToken("webrtc");
+
+// Option B: from the Pinecall client (agent in another process)
+const token = await pc.createToken("webrtc", "florencia");
+```
+
+Both return the same shape:
+
+```json
+{ "token": "tok_...", "server": "wss://voice.pinecall.io", "expires_in": 60 }
+```
+
+### Frontend
+
+```tsx
+<VoiceWidget
+  agent="florencia"
+  tokenProvider={async () => {
+    const res = await fetch("/api/token?channel=webrtc", {
+      credentials: "include", // send your session cookie
+    });
+    if (!res.ok) throw new Error(`Token failed: ${res.status}`);
+    return res.json();
+  }}
+/>
+```
+
+### `allowedOrigins` + `tokenProvider` — recommended combo
+
+Use **both** for the best experience:
+
+- `allowedOrigins` lets the widget auto-fetch tokens during **local development** (where your backend might not be running)
+- `tokenProvider` provides **production security** — tokens go through your backend with your auth
+
+```typescript
+// Backend — agent config
+const florencia = pc.agent("florencia", {
+  // Dev fallback — widget can auto-fetch tokens from matching origins
+  allowedOrigins: ["https://mysite.com", "http://localhost:*"],
+  // ...
+});
+```
+
+```tsx
+// Frontend — tokenProvider for production
+<VoiceWidget
+  agent="florencia"
+  tokenProvider={async () => {
+    const res = await fetch("/api/token");
+    if (!res.ok) throw new Error(`Token failed: ${res.status}`);
+    return res.json();
+  }}
+/>
+```
+
+When `tokenProvider` is set, the widget uses it. When it's not set (or fails), `@pinecall/web/core` falls back to fetching directly from the server using `allowedOrigins`.
+
+> **Security note:** `allowedOrigins` alone is origin-header based — real browsers can't spoof it, but scripts/curl can. Always pair it with `tokenProvider` in production.
+
+### How the token is used
+
+The token is consumed **once** during the WebRTC handshake. Here's the full flow:
+
+```
+1. Widget calls tokenProvider()
+   → returns { token: "tok_...", server: "wss://voice.pinecall.io" }
+
+2. Widget fetches ICE config
+   → GET {server}/webrtc/ice-servers → STUN/TURN servers
+
+3. Browser requests mic access
+   → navigator.mediaDevices.getUserMedia()
+
+4. Widget creates a WebRTC offer
+   → new RTCPeerConnection → addTrack(mic) → createOffer()
+
+5. Widget sends the offer + token to the server
+   → POST {server}/webrtc/offer
+     { sdp: "...", type: "offer", token: "tok_...", config, metadata }
+                                   ▲
+                                   └── token goes here, consumed on use
+
+6. Server validates the token, creates a session, returns the SDP answer
+   → { sdp: "...", type: "answer" }
+
+7. WebRTC connection established — audio flows peer-to-peer
+   → token is discarded, all communication is via PeerConnection
+```
+
+After step 5, the token is gone. It can't be reused, replayed, or shared. The WebRTC connection is secured by the PeerConnection itself.
+
+### Token properties
+
+| Property | Value | Effect |
+|---|---|---|
+| Single-use | Consumed on first connection | Can't be reused |
+| Short-lived | 60 second TTL | Expires quickly |
+| Scoped | Locked to agent + org | Can't be used elsewhere |
+
+> **Never** store API keys in frontend code. See [Security](/security) for the full token model.
+
+## `config` — session overrides
+
+Pass session-level overrides to the agent:
+
+```tsx
+<VoiceWidget
+  agent="mara"
+  config={{
+    voice: "elevenlabs/sarah",
+    stt: "deepgram/flux-en",
+    language: "es",
+  }}
+/>
+```
+
+## `metadata` — server-side context
+
+Whatever you pass shows up as `call.metadata` in your agent:
+
+```tsx
+<VoiceWidget
+  agent="mara"
+  metadata={{
+    userId: currentUser.id,
+    plan: currentUser.plan,
+  }}
+/>
+```
+
+On the server:
+
+```typescript
+agent.on("call.started", (call) => {
+  console.log("Call from user", call.metadata.userId);
+});
+```
+
+## `languages` — multi-language selector
+
+Enables a language pill bar that appears on hover and stays visible during calls.
+
+```tsx
+<VoiceWidget
+  agent="mara"
+  languages={{
+    en: {
+      label: "English",
+      flag: "🇬🇧",
+      voice: "elevenlabs/sarah",
+      stt: "deepgram/flux-en",
+      language: "en",
+    },
+    es: {
+      label: "Español",
+      flag: "🇪🇸",
+      voice: "elevenlabs/george",
+      stt: "deepgram/flux-en",
+      language: "es",
+    },
+  }}
+  defaultLanguage="en"
+/>
+```
+
+### `LanguagePreset` shape
+
+| Field | Type | Description |
+|---|---|---|
+| `label` | `string` | Display name (e.g. `"Español"`) |
+| `flag` | `string` | Flag emoji (e.g. `"🇪🇸"`) |
+| `voice` | `string` | Voice ID in `provider:id` format |
+| `stt` | `string \| object` | STT shortcut (`"deepgram/flux-en"`) or full config |
+| `language` | `string` | Language code for STT (`"es"`, `"en"`, etc.) |
+
+### Behavior
+
+- **Pre-call**: Pill bar appears on hover. Selecting a language updates the session config.
+- **Mid-call**: Pills stay visible. Selecting a language sends a `configure` message via DataChannel — voice, STT, and language hot-swap without disconnecting.
+
+## `tools` — inline tool renderers
+
+Map tool names to React render functions. When a server-side tool completes, the result renders inline:
+
+```tsx
+<VoiceWidget
+  agent="booking-demo"
+  tools={{
+    getAvailableSlots: (result, { respond, dismiss }) => (
+      <div className="slots">
+        {result.slots.map((slot: string) => (
+          <button key={slot} onClick={() => { respond(`I'd like ${slot}`); dismiss(); }}>
+            {slot}
+          </button>
+        ))}
+      </div>
+    ),
+  }}
+/>
+```
+
+See [Tools API](/web/widget/tools-api) for the full pattern.
+
+## `onStatusChange` — observability
+
+```tsx
+<VoiceWidget
+  agent="mara"
+  onStatusChange={(status) => {
+    if (status === "connected") analytics.track("call_started");
+    if (status === "idle") analytics.track("call_ended");
+  }}
+/>
+```
+
+## What's next
+
+- [Theming](/web/widget/theming) — all CSS variables and preset values
+- [Tools API](/web/widget/tools-api) — interactive UI from tool calls
+- [`useVoiceSession` hook](/web/widget/use-voice-session-hook) — bypass the orb, build custom UI

package/skills/pinecall-web-widget/references/web/widget/theming.md

@@ -0,0 +1,131 @@
+---
+title: "Theming"
+description: "Theme presets, CSS variables, and full customization of the orb and transcript UI."
+---
+
+# Theming
+
+Every visual aspect of the widget is controlled by CSS custom properties. You can pick a built-in preset, override individual values, or skip the props entirely and override variables with CSS.
+
+## Five built-in presets
+
+| Preset | Orb | Rings | Panels | Best for |
+|---|---|---|---|---|
+| `"dark"` | Pearl white | Warm red | Dark purple glass | Dark-themed sites (default) |
+| `"midnight"` | Deep sapphire | Ice blue | Navy glass | Corporate / professional |
+| `"aurora"` | Emerald / teal | Green | Forest dark | Nature / wellness brands |
+| `"sunset"` | Warm coral | Golden amber | Warm dark | Hospitality / warm brands |
+| `"light"` | Clean white | Soft blue | White glass | Light-themed sites |
+
+```tsx
+<VoiceWidget preset="midnight" agent="mara" />
+<VoiceWidget preset="aurora" agent="mara" />
+<VoiceWidget preset="sunset" agent="mara" />
+<VoiceWidget preset="light" agent="mara" />
+<VoiceWidget preset="dark" agent="mara" />     // default
+```
+
+Access preset values programmatically:
+
+```tsx
+import { PRESETS } from "@pinecall/web";
+console.log(PRESETS.midnight); // full theme object
+```
+
+## Custom themes via the `theme` prop
+
+Pass overrides — they merge on top of the chosen `preset`:
+
+```tsx
+<VoiceWidget
+  agent="mara"
+  preset="midnight"
+  theme={{
+    orbFrom: "200, 150, 255",
+    orbMid: "140, 80, 220",
+    orbTo: "80, 30, 160",
+    colorAccent: "124, 58, 237",
+    ringColor: "216, 65, 44",
+    panelBg: "rgba(16, 14, 20, .92)",
+    bubbleUserColor: "#e0d4f7",
+  }}
+/>
+```
+
+## All theme variables
+
+| Field | CSS variable | Type | Default (dark) | Controls |
+|---|---|---|---|---|
+| `orbFrom` | `--vw-orb-from` | RGB triplet | `255, 255, 255` | Idle orb gradient center |
+| `orbMid` | `--vw-orb-mid` | RGB triplet | `240, 238, 231` | Idle orb gradient midtone |
+| `orbTo` | `--vw-orb-to` | RGB triplet | `184, 181, 168` | Idle orb gradient edge |
+| `colorConnecting` | `--vw-color-connecting` | RGB triplet | `245, 158, 11` | Connecting state orb |
+| `colorActive` | `--vw-color-active` | RGB triplet | `76, 175, 80` | Connected / listening orb |
+| `colorUserSpeaking` | `--vw-color-user-speaking` | RGB triplet | `52, 211, 153` | User speaking orb |
+| `colorSpeaking` | `--vw-color-speaking` | RGB triplet | `248, 113, 113` | Agent speaking orb |
+| `colorThinking` | `--vw-color-thinking` | RGB triplet | `139, 92, 246` | Thinking / processing orb |
+| `colorWarning` | `--vw-color-warning` | RGB triplet | `255, 160, 0` | Idle warning blink |
+| `colorAccent` | `--vw-color-accent` | RGB triplet | `124, 58, 237` | User bubble accent |
+| `ringColor` | `--vw-ring-color` | RGB triplet | `216, 65, 44` | Idle ring glow |
+| `panelBg` | `--vw-panel-bg` | CSS color | `rgba(16,14,20,.92)` | Transcript panel bg |
+| `panelBorder` | `--vw-panel-border` | CSS color | `rgba(255,255,255,.08)` | Transcript panel border |
+| `bubbleBotBg` | `--vw-bubble-bot-bg` | CSS color | `rgba(18,16,22,.9)` | Bot bubble background |
+| `bubbleBotColor` | `--vw-bubble-bot-color` | CSS color | `#e8e4f0` | Bot bubble text |
+| `bubbleUserColor` | `--vw-bubble-user-color` | CSS color | `#e0d4f7` | User bubble text |
+| `labelBg` | `--vw-label-bg` | CSS color | `#181818` | Label tooltip background |
+| `labelColor` | `--vw-label-color` | CSS color | `#fff` | Label tooltip text |
+
+> **RGB triplet vs CSS color.** Variables that need alpha variants are stored as `"R, G, B"` strings (the widget uses `rgba(var(--vw-color-x), 0.3)` etc.). Plain CSS color values are used for backgrounds and text where alpha is baked into the value.
+
+## CSS-only override (no JS)
+
+Skip the `theme` prop entirely — override the CSS variables directly:
+
+```css
+.vw-wrap {
+  --vw-orb-from: 200, 150, 255;
+  --vw-ring-color: 100, 80, 200;
+  --vw-panel-bg: rgba(20, 10, 40, .95);
+}
+```
+
+This is handy when you want the theme to follow a parent context (e.g. dark/light mode toggle in your app's own CSS).
+
+## Orb visual states
+
+The orb gets a different look per phase:
+
+| State | Visual | CSS class | When |
+|---|---|---|---|
+| Idle | Pearl gradient, breathing rings | (default) | Not connected |
+| Connecting | Amber pulse | `.connecting` | Establishing WebRTC |
+| Active | Soft green glow | `.active` | Connected, listening |
+| User speaking | Emerald glow | `.user-speaking` | User is talking |
+| Agent speaking | Rose pulse | `.speaking` | Bot TTS playing |
+| Thinking | Violet pulse | `.thinking` | Waiting for LLM response |
+| **Idle warning** | **Orange blink** | `.idle-warning` | User silent — call will timeout soon |
+
+The idle warning state is driven by the server's `session.idleWarning` event and clears when the user speaks or the call ends.
+
+## Building on top of presets
+
+Start from a preset and modify selectively:
+
+```tsx
+import { PRESETS } from "@pinecall/web";
+import type { VoiceWidgetTheme } from "@pinecall/web";
+
+const brandTheme: Partial<VoiceWidgetTheme> = {
+  ...PRESETS.midnight,
+  colorAccent: "255, 87, 34",      // brand orange
+  ringColor: "255, 87, 34",
+  bubbleUserColor: "#ffccbc",
+};
+
+<VoiceWidget agent="mara" preset="midnight" theme={brandTheme} />;
+```
+
+## What's next
+
+- [Props reference](/web/widget/props) — everything else the widget accepts
+- [`useVoiceSession` hook](/web/widget/use-voice-session-hook) — for fully custom UIs that bypass the orb entirely