@mcp-b/char 0.0.5 → 0.1.0

package/README.md

@@ -1,405 +1,119 @@
 # @mcp-b/char
 
-An Intercom-like AI chat widget with MCP tool support and voice mode. Drop it into your app and you're done.
+Framework-agnostic custom elements for embedding Char.
 
-Styles are isolated using Shadow DOM. Customize appearance by setting CSS variables on the host page.
+This package is zero-dependency at runtime and ships two elements:
 
-## Build Architecture
+- `<char-agent>`: low-level iframe + bridge primitive
+- `<char-agent-shell>`: opinionated host shell (PIP composer, desktop push panel, responsive fullscreen)
 
-This package provides the `<char-agent>` custom element in two formats:
-
-| Export | Format | Use Case |
-|--------|--------|----------|
-| `@mcp-b/char` / `@mcp-b/char/web-component` | ESM web component | Bundlers, monorepo dev |
-| `@mcp-b/char/standalone` | IIFE web component | `<script>` tag embeds |
-
-### Bundle Sizes
-
-| Build | Size | Gzipped | Use Case |
-|-------|------|---------|----------|
-| ESM | ~560 KB | ~115 KB | Bundlers (React externalized) |
-| Standalone IIFE | ~2.2 MB | ~400 KB | Script tag embeds |
-
-The standalone IIFE includes React, so it's larger but works on any website without dependencies.
-
-### Why Two Builds?
-
-**ESM Build** (root export or `/web-component`)
-- Web component entrypoint for bundlers
-- React is externalized via `peerDependencies` (install `react` and `react-dom`)
-- Smaller bundle; no duplicate React if the host already uses it
-- Uses Shadow DOM for style isolation
-- Use for: bundlers, monorepo consumers
-
-**Standalone IIFE Build** (`/standalone`)
-- Web component via `<script>` tag
-- React is bundled inside the package
-- Uses Shadow DOM for complete JS/CSS isolation
-- Separate React instances in separate DOM trees = no conflict
-- Use for: `<script>` tag embedding on any website (React or not)
-
-### The "Two Reacts" Problem
-
-When a React app loads the standalone bundle, you get duplicate React instances which causes the infamous "hooks can only be called inside a function component" error.
-
-**Shadow DOM solves this**: Each React instance manages its own separate DOM tree inside the shadow boundary, so they never conflict.
-
-```
-Host Page (React 18)
-├── <div id="root">  ← Host's React
-│   └── ... host app ...
-│
-└── <char-agent>
-    └── #shadow-root  ← Isolation boundary
-        └── <div>  ← Bundled React 19
-            └── ... widget ...
-```
-
-## Installation
+## Install
 
 ```bash
-npm install @mcp-b/char
-```
-
-## Usage
-
-`<char-agent>` renders as a full-viewport overlay.
-
-### Recommended: Imperative Authentication (Secure)
-
-The `connect()` method is the recommended way to authenticate. It keeps tokens out of DOM attributes, preventing exposure to session replay tools, error reporters, and DOM inspectors.
-
-```tsx
-import { useRef, useEffect } from "react";
-import "@mcp-b/char/web-component";
-import type { CharAgentElement } from "@mcp-b/char/web-component";
-
-function App() {
-  const { session } = useOktaAuth(); // or Azure, Auth0, Google, etc.
-  const agentRef = useRef<CharAgentElement>(null);
-
-  useEffect(() => {
-    if (agentRef.current && session?.idToken) {
-      agentRef.current.connect({ idToken: session.idToken });
-    }
-  }, [session?.idToken]);
-
-  return <char-agent ref={agentRef} />;
-}
-```
-
-### Vanilla JavaScript
-
-```html
-<char-agent></char-agent>
-
-<script type="module">
-  import "@mcp-b/char/web-component";
-
-  const agent = document.querySelector("char-agent");
-  // Call connect() when you have the token
-  agent.connect({ idToken: "eyJhbGciOi..." });
-</script>
+npm i @mcp-b/char
 ```
 
-### Monorepo Dogfooding
-
-```tsx
-import { useRef, useEffect } from "react";
-import "@mcp-b/char/web-component";
-import type { CharAgentElement } from "@mcp-b/char/web-component";
-
-const authToken = session?.idToken ?? "";
-const agentRef = useRef<CharAgentElement>(null);
-
-useEffect(() => {
-  const agent = agentRef.current ?? document.querySelector("char-agent");
-
-  if (!agent) {
-    const newAgent = document.createElement("char-agent");
-    document.body.appendChild(newAgent);
-    // Connect after element is in DOM
-    (newAgent as CharAgentElement).connect({ idToken: authToken });
-  } else if (authToken) {
-    (agent as CharAgentElement).connect({ idToken: authToken });
-  }
+## Element registration
 
-  // Set other attributes (these don't contain sensitive data)
-  agent?.setAttribute("dev-mode", JSON.stringify({ useLocalApi: true }));
-  agent?.setAttribute("enable-debug-tools", String(import.meta.env.DEV));
-}, [authToken]);
-
-return <char-agent ref={agentRef} />;
+```ts
+import '@mcp-b/char/web-component' // registers <char-agent>
+import '@mcp-b/char/shell-component' // registers <char-agent-shell>
 ```
 
-### Script Tag (Any Website)
-
-Use `defer` for best performance - it loads the script without blocking page rendering:
+Importing `@mcp-b/char` root also registers both.
 
-```html
-<!-- Recommended: defer loads async, executes after DOM ready -->
-<script src="https://unpkg.com/@mcp-b/char/dist/web-component-standalone.iife.js" defer></script>
-<char-agent></char-agent>
-
-<script>
-  // Authenticate after the page loads (tokens not in DOM attributes)
-  document.addEventListener('DOMContentLoaded', () => {
-    const agent = document.querySelector('char-agent');
-    // Get your token from your auth provider
-    agent.connect({ idToken: yourIdpToken });
-  });
-</script>
-```
+## Low-level primitive: `<char-agent>`
 
-Alternative CDN (jsdelivr):
+Use this when your app already owns all host chrome/layout.
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@mcp-b/char/dist/web-component-standalone.iife.js" defer></script>
-```
-
-Pin to a specific version for production:
-
-```html
-<script src="https://unpkg.com/@mcp-b/char@0.0.2/dist/web-component-standalone.iife.js" defer></script>
-```
+<char-agent id="assistant" style="width: 420px; height: 100vh" display-mode="inline"></char-agent>
+<script type="module">
+  import '@mcp-b/char/web-component'
 
-### Web Component Attributes
+  /** @type {import('@mcp-b/char/web-component').CharAgentElement | null} */
+  const agent = document.querySelector('#assistant')
 
-```html
-<!-- PREFERRED: Use connect() method instead of auth-token attribute -->
-<char-agent
-  dev-mode='{"anthropicApiKey": "sk-ant-..."}'
-  enable-debug-tools="true"
-></char-agent>
-
-<script>
-  const agent = document.querySelector('char-agent');
-  agent.connect({ idToken: 'eyJhbGciOi...' });
+  agent?.connect({
+    idToken: '<id-token>',
+    clientId: '<oidc-client-id>',
+  })
 </script>
 ```
 
-## SSR Frameworks (Astro, Next.js, etc.)
-
-Char requires a browser environment — it uses Shadow DOM, custom elements, and other browser APIs. In SSR frameworks, you must ensure Char only renders on the client.
-
-### Astro
-
-Use `client:only="react"` to skip server-side rendering entirely:
-
-```astro
----
-import { Char } from '@mcp-b/char'
----
-
-<Char
-  client:only="react"
-  devMode={{ anthropicApiKey: import.meta.env.PUBLIC_ANTHROPIC_API_KEY }}
-  open={true}
-/>
-```
-
-`client:load` or `client:visible` will not work because Astro still attempts to render the component on the server first. `client:only="react"` skips SSR entirely and renders only in the browser.
-
-### Next.js
+`display-mode` values:
 
-Use dynamic imports with `ssr: false`:
+- `pip`: collapsed
+- `inline`: expanded side panel
+- `fullscreen`: expanded fullscreen
 
-```tsx
-import dynamic from 'next/dynamic'
-
-const Char = dynamic(() => import('@mcp-b/char').then(m => ({ default: m.Char })), {
-  ssr: false,
-})
-
-export default function Page() {
-  return <Char open={true} devMode={{ anthropicApiKey: process.env.NEXT_PUBLIC_ANTHROPIC_API_KEY }} />
-}
-```
-
-## Props / Attributes
-
-| Prop | Attribute | Type | Description |
-|------|-----------|------|-------------|
-| - | - | method | `connect({ idToken })` - Secure authentication (token not in DOM) |
-| - | - | method | `connect({ ticketAuth })` - SSR-friendly authentication (pre-fetched ticket) |
-| - | - | method | `disconnect()` - Clear authentication |
-| `open` | `open` | boolean | Controlled open state (optional) |
-| `devMode` | `dev-mode` | object/JSON | Development mode config (optional) |
-| `enableDebugTools` | `enable-debug-tools` | boolean | Enable debug tools (default: false) |
-
-## Customization
-
-Customize appearance by setting CSS variables on the host page:
-
-```css
-char-agent {
-  /* Brand colors */
-  --wm-color-primary: #8b5cf6;
-  --wm-color-primary-foreground: #ffffff;
-
-  /* Layout */
-  --wm-radius: 12px;
-  --wm-font-sans: 'Inter', sans-serif;
-
-  /* Backgrounds */
-  --wm-color-background: #ffffff;
-  --wm-color-foreground: #1a1a1a;
-  --wm-color-muted: #f5f5f5;
-
-  /* Messages */
-  --wm-user-bubble-bg: #8b5cf6;
-  --wm-user-bubble-text: #ffffff;
-  --wm-assistant-bubble-bg: #f5f5f5;
-  --wm-assistant-bubble-text: #1a1a1a;
-
-  /* Composer */
-  --wm-composer-bg: #ffffff;
-  --wm-composer-border: #e5e5e5;
-  --wm-composer-button-bg: #8b5cf6;
-
-  /* Tools */
-  --wm-tool-bg: #f9fafb;
-  --wm-tool-border: #e5e7eb;
-  --wm-tool-approve-bg: #10b981;
-  --wm-tool-deny-bg: #ef4444;
-
-  /* Code blocks */
-  --wm-code-bg: #1e1e1e;
-  --wm-code-text: #d4d4d4;
-
-  /* Font sizes */
-  --wm-font-size-xs: 0.75rem;
-  --wm-font-size-sm: 0.875rem;
-  --wm-font-size-base: 1rem;
-  --wm-font-size-lg: 1.125rem;
-}
-
-/* Dark mode */
-char-agent.dark {
-  --wm-color-background: #1a1a1a;
-  --wm-color-foreground: #ffffff;
-  --wm-color-muted: #2a2a2a;
-  /* ... other dark mode overrides */
-}
-```
+## Opinionated shell: `<char-agent-shell>`
 
-## Development Mode
-
-Use your own API keys during development (stateless):
-
-```html
-<char-agent
-  dev-mode='{"anthropicApiKey":"sk-ant-...","openaiApiKey":"sk-...","useLocalApi":true}'
-></char-agent>
-```
-
-**Development modes:**
-- `anthropicApiKey`: Use your own Anthropic API key (falls back to Gemini if not provided)
-- `openaiApiKey`: Enable voice mode with your OpenAI key
-- `useLocalApi`: Point to localhost instead of production API
-
-Common combinations:
-- `{ useLocalApi: true }` - Internal monorepo development
-- `{ anthropicApiKey: "sk-ant-..." }` - External dev with your own key
-- `{ anthropicApiKey: "...", openaiApiKey: "...", useLocalApi: true }` - Full stack local dev
-
-## Performance
-
-### Script Loading
-
-Always use `defer` or `async` when embedding the standalone script to avoid blocking page rendering:
+Use this when you want built-in host behavior and responsive policy.
 
 ```html
-<!-- GOOD: defer - loads in parallel, executes after DOM ready -->
-<script src="https://unpkg.com/@mcp-b/char/dist/web-component-standalone.iife.js" defer></script>
+<char-agent-shell
+  id="assistant-shell"
+  panel-width="420"
+  pip-position="bottom-center"
+  fullscreen-breakpoint="1024"
+></char-agent-shell>
+<script type="module">
+  import '@mcp-b/char/shell-component'
 
-<!-- GOOD: async - loads in parallel, executes ASAP -->
-<script src="https://unpkg.com/@mcp-b/char/dist/web-component-standalone.iife.js" async></script>
+  /** @type {import('@mcp-b/char/shell-component').CharAgentShellElement | null} */
+  const shell = document.querySelector('#assistant-shell')
 
-<!-- BAD: blocks page rendering until script loads -->
-<script src="https://unpkg.com/@mcp-b/char/dist/web-component-standalone.iife.js"></script>
+  shell?.connect({
+    idToken: '<id-token>',
+    clientId: '<oidc-client-id>',
+  })
+</script>
 ```
 
-**When to use which:**
-- `defer` (recommended) - Script executes after HTML is parsed, preserves execution order
-- `async` - Script executes as soon as it loads, good for independent widgets
+Shell mode policy:
 
-### Preconnect Hint
+- closed -> `pip`
+- open desktop -> `inline`
+- open below breakpoint -> `fullscreen`
 
-Speed up loading by adding a preconnect hint in your `<head>`:
+Availability policy:
 
-```html
-<link rel="preconnect" href="https://unpkg.com" crossorigin>
-```
+- `char-agent-shell` is fail-closed by default.
+- If iframe initialization fails or times out, the shell hides fully (no host chrome footprint).
+- Observability remains available via `char-error`.
 
-## Features
+## API summary
 
-- **MCP Tool Support** - Connect to any MCP server
-- **Voice Mode** - Talk to your AI assistant
-- **Action-First UI** - Shows what the AI is doing
-- **Shadow DOM Isolation** - Styles don't leak in or out
-- **Stateful Sessions** - Messages persist across page refreshes (when authToken is provided)
-- **CSS Variable Theming** - Customize appearance without JavaScript
+`<char-agent>` methods:
 
-## Migration Guide
+- `connect(options)`
+- `disconnect()`
+- `setAuth(options | null)` (connect when provided, disconnect when null)
+- `setHostContext(partialContext)`
 
-### Upgrading from Previous Versions
+`<char-agent-shell>` methods:
 
-**Removed props:**
-- `apiKey` / `userId` - Replaced by `authToken` (use your existing IDP token)
-- `appId` - No longer needed (removed dead code)
-- `siteId` - Org-level routing in SSO-first mode (no site scoping)
-- `theme` - Use CSS variables instead (see Customization section)
-- `isolateStyles` - Always enabled (Shadow DOM is always used)
-- `disableShadowDOM` - Removed (Shadow DOM is always enabled)
+- `connect(options)`
+- `disconnect()`
+- `setAuth(options | null)` (connect when provided, disconnect when null)
+- `setHostContext(partialContext)`
+- `setOpen(open)`
+- `toggleOpen()`
 
-**Migration examples:**
+`<char-agent-shell>` events:
 
-```html
-<!-- OLD: -->
-<char-agent
-  app-id="app_123"
-  site-id="site_123"
-  api-key="sk_live_xxx"
-  theme='{"primaryColor":"#ff0000","mode":"dark"}'
-  isolate-styles="false"
-></char-agent>
-
-<!-- NEW (SSO-first with connect method): -->
-<char-agent></char-agent>
-<script>
-  const agent = document.querySelector('char-agent');
-  agent.connect({ idToken: 'eyJhbGciOi...' });
-</script>
+- `char-shell-open-change` (`{ open: boolean }`)
+- pass-through `char-*` events from inner `<char-agent>`
 
-<!-- NEW (anonymous dev mode): -->
-<char-agent dev-mode='{"anthropicApiKey":"sk-ant-..."}'></char-agent>
-
-<!-- Customize via CSS: -->
-<style>
-  char-agent {
-    --wm-color-primary: #ff0000;
-  }
-  char-agent.dark {
-    --wm-color-background: #1a1a1a;
-  }
-</style>
-```
-
-**Benefits:**
-- Smaller bundle size (~200 lines removed)
-- Simpler API (fewer required attributes)
-- More flexible styling (CSS variables work everywhere)
-- Consistent Shadow DOM isolation (no edge cases)
-- No API keys to manage (uses existing IDP tokens)
+## Shared mode-policy helpers
 
-## Development
-
-```bash
-pnpm --filter @mcp-b/char dev        # Watch TS build
-pnpm --filter @mcp-b/char dev:css    # Watch Tailwind CSS
-pnpm --filter @mcp-b/char storybook  # http://localhost:6006
-pnpm --filter @mcp-b/char build
-pnpm --filter @mcp-b/char check:types
-pnpm --filter @mcp-b/char test
+```ts
+import {
+  DEFAULT_AVAILABLE_DISPLAY_MODES,
+  isDisplayMode,
+  isExpandedDisplayMode,
+  resolvePolicyDisplayMode,
+  resolveSupportedDisplayMode,
+} from '@mcp-b/char/display-mode-policy'
 ```