glirastes 0.3.0 → 0.3.1

package/skills/building-glirastes-chat-ui/SKILL.md

@@ -0,0 +1,378 @@
+---
+name: building-glirastes-chat-ui
+description: Customizing the Glirastes chat UI — VercelAiChat / LangGraphAiChat, AiChatProvider + AiChatPanel composition, theming, mentions, voice input, approval cards, ChatWindow portal, useAiClientAction. Use when going beyond the zero-config chat widget.
+version: 1.0.0
+tags:
+  - glirastes
+  - react
+  - chat-ui
+  - components
+triggers:
+  - chat panel
+  - chat window
+  - VercelAiChat
+  - LangGraphAiChat
+  - AiChatProvider
+  - AiChatPanel
+  - useAiChat
+  - useAiClientAction
+  - chat theming
+  - chat mentions
+  - voice input
+  - approval card
+  - suggestion chips
+  - pipeline timeline
+---
+
+# Building the Glirastes Chat UI
+
+> **Scope:** customizing the chat UI beyond `<VercelAiChat endpoint="/api/chat" />`. For the initial integration (install, wire the route, drop the widget), see [integrating-glirastes-nextjs](../integrating-glirastes-nextjs/SKILL.md) or [integrating-glirastes-nestjs](../integrating-glirastes-nestjs/SKILL.md).
+
+## Component map
+
+```
+AiChatProvider (state + transport + config)
+ └─ AiChatPanel (the panel layout — header, body, input)
+     ├─ MessageList → MessageBubble (text, mentions, tool results, approvals, pipeline timeline)
+     ├─ SuggestionBar (Pro: contextual followup chips)
+     └─ ChatInput / RichMentionInput (input box)
+         └─ VoiceInputAddon (optional: live waveform + STT)
+
+VercelAiChat = AiChatProvider + ChatWindow (floating, draggable, resizable) + AiTriggerButton (the floating launcher)
+LangGraphAiChat = same shape but talks LangGraph instead of Vercel AI SDK
+```
+
+`<VercelAiChat />` is the zero-config wrapper. For full control, drop down to `AiChatProvider` + `AiChatPanel`.
+
+## Three integration levels
+
+### Level 1 — VercelAiChat (zero config)
+
+```tsx
+'use client';
+import { VercelAiChat } from 'glirastes/react/vercel';
+import 'glirastes/react/styles.css';
+
+export function ChatWidget() {
+  return <VercelAiChat endpoint="/api/chat" />;
+}
+```
+
+This gives you the floating trigger button (bottom-right), draggable+resizable chat window, message rendering, mentions, voice input, approval cards. Everything wired up. ~80% of apps stop here.
+
+### Level 2 — VercelAiChat with props
+
+`VercelAiChat` (and `LangGraphAiChat`) accept layout + behaviour props:
+
+```tsx
+<VercelAiChat
+  endpoint="/api/chat"
+  headers={() => ({ Authorization: `Bearer ${getToken()}` })}
+  bodyExtras={() => ({ tenantId: getTenantId() })}
+  title="Assistant"
+  defaultOpen={false}
+  draggable
+  resizable
+  size={{ width: 400, height: 640 }}
+  hideTriggerWhenOpen
+  shortcut={{ key: 'k', meta: true }}
+  showMic={true}
+  showClearButton
+  confirmClear
+  showSessionSwitcher
+  welcomeMessage="Hi! Ask me about your tasks."
+  triggerIcon={<MyCustomIcon />}
+  headerActions={<MySettingsButton />}
+  sessions={{ storage: 'localStorage', maxHistory: 30 }}
+  autoResumeOnApproval
+/>
+```
+
+Highlights:
+
+| Prop | What it does |
+|---|---|
+| `headers` | Function returning request headers — refreshed on every request, ideal for JWT |
+| `bodyExtras` | Extra fields merged into the chat request body — tenant ID, locale, etc. |
+| `shortcut` | Keyboard shortcut to toggle the chat (e.g. `⌘K`) |
+| `showMic` | Voice input toggle. Set `false` to drop `wavesurfer.js` from the bundle entirely |
+| `sessions` | Multi-session history — switches between conversations, persists across reloads |
+| `autoResumeOnApproval` | After an approval card is approved, the LLM continues without manual nudge |
+
+### Level 3 — AiChatProvider + AiChatPanel (full control)
+
+When you need a non-floating layout (sidebar, full-page, embedded), compose manually:
+
+```tsx
+'use client';
+import { AiChatProvider, AiChatPanel, useAiChat } from 'glirastes/react';
+import { useVercelAiChatTransport } from 'glirastes/react/vercel';
+
+export function FullPageChat() {
+  const transport = useVercelAiChatTransport({
+    endpoint: '/api/chat',
+    headers: () => ({ Authorization: `Bearer ${getToken()}` }),
+  });
+
+  return (
+    <AiChatProvider transport={transport}>
+      <div className="h-full flex">
+        <Sidebar />
+        <AiChatPanel className="flex-1" />
+      </div>
+    </AiChatProvider>
+  );
+}
+```
+
+Inside any descendant of `AiChatProvider`, `useAiChat()` exposes the full state — messages, sending, current pipeline state, etc. Useful when you want to render messages elsewhere or add custom controls.
+
+## UI Action Bus — frontend reactions to tool results
+
+Tool results that carry a `uiAction` payload (from `uiPattern` or `uiActionOnSuccess`) are dispatched through `UiActionBus`. Register handlers anywhere in the component tree:
+
+```tsx
+'use client';
+import { useAiClientAction } from 'glirastes/react';
+import { useRouter } from 'next/navigation';
+import { toast } from 'sonner';
+
+export function TaskList() {
+  const router = useRouter();
+
+  // Open the detail view when the LLM picks a task
+  useAiClientAction('task-details.open', (payload) => {
+    router.push(`/tasks/${payload?.taskId}`);
+  });
+
+  // Refresh the list after a mutation
+  useAiClientAction('tasks.refresh', () => {
+    queryClient.invalidateQueries({ queryKey: ['tasks'] });
+  });
+
+  // Open a custom dialog
+  useAiClientAction('task-create-dialog.open', () => {
+    setCreateDialogOpen(true);
+  });
+
+  return /* ... */;
+}
+```
+
+Action IDs follow conventions derived from `uiPattern`:
+
+| `uiPattern.type` | Derived action ID |
+|---|---|
+| `open-detail`, `entity: 'task'` | `task-details.open` |
+| `open-dialog`, `dialog: 'create-task'` | `task-create-dialog.open` |
+| `refresh`, `target: 'tasks'` | `tasks.refresh` |
+| `toast` | dispatched directly to your toast lib via the SDK's toast handler config |
+
+For raw `uiActionOnSuccess: { type: 'run-client-action', actionId: 'X' }` you choose any string for `actionId`.
+
+`glirastes coverage` reports any action ID declared in tools but not handled (or vice versa).
+
+## Approval cards
+
+Mutations with `needsApproval: true` (default for POST/PATCH/PUT/DELETE) render an approval card before executing. The default card shows:
+
+- Tool name and description
+- Input parameters
+- Approve / Cancel buttons
+
+Customize per-tool with optional `approvalCard` config:
+
+```ts
+defineEndpointTool({
+  // ...
+  approvalCard: {
+    title: 'Create task',
+    description: (input) => `Create task "${input.title}"?`,
+    severity: 'info', // or 'warning' | 'danger' for destructive ops
+  },
+})
+```
+
+For full UI control, pass a custom component to `AiChatProvider`:
+
+```tsx
+<AiChatProvider
+  components={{ ApprovalCard: MyCustomApprovalCard }}
+>
+  ...
+</AiChatProvider>
+```
+
+## Mentions (`@user`, `#tag`)
+
+Mentions let users reference entities the LLM can resolve to IDs. Configure on the provider or on `VercelAiChat`:
+
+```tsx
+<VercelAiChat
+  endpoint="/api/chat"
+  mentions={{
+    triggers: {
+      '@': {
+        label: 'User',
+        search: async (query) => {
+          const users = await fetch(`/api/users/search?q=${query}`).then(r => r.json());
+          return users.map(u => ({ id: u.id, label: u.name, hint: u.email }));
+        },
+      },
+      '#': {
+        label: 'Tag',
+        search: async (query) => fetch(`/api/tags?q=${query}`).then(r => r.json()),
+      },
+    },
+  }}
+/>
+```
+
+Mentions in the input get serialized into the user message — your tools see structured references the LLM can pass back as IDs:
+
+```
+Input:  "assign @Alice the task #urgent"
+Wire:   "assign user_123 the task with tag tag_456"
+```
+
+## Theming
+
+The chat UI is styled with a small token system. Override at the provider level:
+
+```tsx
+<VercelAiChat
+  endpoint="/api/chat"
+  theme={{
+    colors: {
+      primary: '#6366f1',
+      background: '#0a0a0a',
+      foreground: '#ffffff',
+      muted: '#262626',
+      border: '#404040',
+    },
+    radius: '12px',
+    fontFamily: 'Inter, sans-serif',
+  }}
+/>
+```
+
+For deeper customization, swap the default `glirastes/react/styles.css` for your own:
+
+1. Don't import `glirastes/react/styles.css`
+2. Inspect the DOM (every component has stable `data-*` attributes) — e.g. `[data-glirastes='chat-panel']`, `[data-part='message-bubble']`
+3. Write your own CSS targeting those selectors
+
+## Voice input (Deepgram speech-to-text)
+
+The trigger button has a built-in mic mode. When the user holds the mic:
+
+1. Browser captures audio
+2. `wavesurfer.js` renders a live waveform
+3. Audio frames stream to your backend's `/api/ai/speech-stream` WebSocket
+4. Backend proxies to Deepgram, streams transcriptions back
+5. On release, the final transcript becomes the chat input
+
+**Frontend setup:**
+
+```bash
+npm install wavesurfer.js
+```
+
+```tsx
+<VercelAiChat
+  endpoint="/api/chat"
+  showMic={true}
+  voiceInput={{
+    websocketUrl: '/api/ai/speech-stream',
+    language: 'en', // or 'de', etc.
+  }}
+/>
+```
+
+**Backend setup:** see [integrating-glirastes-nestjs](../integrating-glirastes-nestjs/SKILL.md) → "Speech-to-text WebSocket". For Next.js standalone, you need a separate WebSocket server — Next.js Route Handlers don't support WS natively.
+
+If you don't want voice input at all, set `showMic={false}` and skip installing `wavesurfer.js`. The components are tree-shaken.
+
+### Content Security Policy and `wavesurfer.js`
+
+The optional-peer loader for `wavesurfer.js` uses `new Function('s', 'return import(s)')` to hide the specifier from bundlers (so apps that don't install the peer don't fail to build). This requires `script-src 'unsafe-eval'` in your CSP.
+
+If your deployment forbids `unsafe-eval` **and** you want voice input, install `wavesurfer.js` unconditionally:
+
+```bash
+npm install wavesurfer.js
+```
+
+With the peer present at install time, the bundler resolves the static path successfully and the runtime trick is bypassed entirely. Strict-CSP environments without voice can stay on `showMic={false}` and never need `wavesurfer.js`.
+
+## ChatWindow — portal, draggable, resizable
+
+`VercelAiChat` already wraps the panel in a `ChatWindow`. If you compose manually, you can use the window separately:
+
+```tsx
+import { ChatWindow, AiChatPanel } from 'glirastes/react';
+
+<ChatWindow
+  open={open}
+  onOpenChange={setOpen}
+  draggable
+  resizable
+  size={{ width: 400, height: 640 }}
+  defaultPosition={{ x: 'right', y: 'bottom', offset: 24 }}
+>
+  <AiChatPanel />
+</ChatWindow>
+```
+
+The window portals to `document.body` by default — no z-index fights with your app shell.
+
+## Sessions (multi-conversation)
+
+Enable conversation history with the `sessions` prop:
+
+```tsx
+<VercelAiChat
+  endpoint="/api/chat"
+  sessions={{
+    storage: 'localStorage', // or a custom adapter implementing { load, save, clear }
+    maxHistory: 30,
+    onCreate: (session) => trackEvent('chat:new-session'),
+  }}
+  showSessionSwitcher
+/>
+```
+
+A session switcher renders in the header (with `showSessionSwitcher`); users can name, switch, or delete sessions. Custom adapters let you persist server-side instead of localStorage.
+
+## Pipeline timeline (Pro)
+
+When `GLIRASTES_API_KEY` is set, the chat shows per-request pipeline steps inline (intent classification, guardrails, tool calls, model selection):
+
+```
+↳ Intent: task_query (0.94)
+↳ Tools available: 3
+↳ Model: gpt-4o-mini
+↳ Tool call: list_tasks (124ms)
+```
+
+No setup beyond having the key — the timeline auto-renders inside the message bubble of the corresponding assistant turn.
+
+## Common pitfalls
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Widget unstyled | `styles.css` not imported | Add `import 'glirastes/react/styles.css'` near the root |
+| Floating button overlaps a sticky footer | Default position bottom-right | Pass `defaultPosition={{ x: 'right', y: 'bottom', offset: 80 }}` |
+| `useAiClientAction` doesn't fire | Component not mounted when the action arrives | Mount the handler in a layout that's always rendered |
+| Mentions search runs on every keystroke | No debounce | Wrap your `search` fn with `lodash.debounce` (300ms typical) |
+| Voice input fails silently | WebSocket URL wrong / `DEEPGRAM_API_KEY` missing | Check browser DevTools → WS frame; check backend logs |
+| Approval card not shown for a mutation | Tool sets `needsApproval: false` explicitly | Either remove the override or set `autoApproveTools` per-user |
+| Approval card shown for a benign GET | Tool overrides `needsApproval: true` | GETs default to `false` — drop the override |
+| Multiple chat instances on the page | Mounted `<VercelAiChat />` more than once | Render exactly one in your root layout |
+| Bundle includes `wavesurfer.js` despite `showMic={false}` | Direct import of voice components elsewhere | Remove any `import` from `glirastes/react/components/recording-bar` etc. |
+
+## What this skill does NOT cover
+
+- **Initial integration** (install, route handler, widget mount) — see [integrating-glirastes-nextjs](../integrating-glirastes-nextjs/SKILL.md) or [integrating-glirastes-nestjs](../integrating-glirastes-nestjs/SKILL.md)
+- **Tool authoring** (`uiPattern` / `uiActionOnSuccess` semantics, `actionId` derivation, approval flag) — see [maintaining-glirastes-tools](../maintaining-glirastes-tools/SKILL.md)
+- **LangGraph transport differences** — replace `useVercelAiChatTransport` / `VercelAiChat` with `useLangGraphAiChatTransport` / `LangGraphAiChat`; everything else in this skill applies unchanged