@mcp-b/char

Framework-agnostic custom elements for embedding Char.

This package is zero-dependency at runtime and ships two elements:

• <char-agent>: low-level iframe + bridge primitive
• <char-agent-shell>: opinionated host shell (PIP composer, desktop push panel, responsive fullscreen)

Install

npm i @mcp-b/char

Element registration

import '@mcp-b/char/web-component' // registers <char-agent>
import '@mcp-b/char/shell-component' // registers <char-agent-shell>

Importing @mcp-b/char root also registers both.

Low-level primitive: <char-agent>

Use this when your app already owns all host chrome/layout.

<char-agent
  id="assistant"
  publishable-key="pk_live_your_key_here"
  style="width: 420px; height: 100vh"
  display-mode="inline"
></char-agent>
<script type="module">
  import '@mcp-b/char/web-component'

  /** @type {import('@mcp-b/char/web-component').CharAgentElement | null} */
  const agent = document.querySelector('#assistant')

  agent?.connect({
    publishableKey: 'pk_live_your_key_here',
    // Optional per-user identity token:
    idToken: '<id-token>',
  })
</script>

display-mode values:

• pip: collapsed
• inline: expanded side panel
• fullscreen: expanded fullscreen

Opinionated shell: <char-agent-shell>

Use this when you want built-in host behavior and responsive policy.

<char-agent-shell id="assistant-shell"></char-agent-shell>
<script type="module">
  import '@mcp-b/char/shell-component'

  /** @type {import('@mcp-b/char/shell-component').CharAgentShellElement | null} */
  const shell = document.querySelector('#assistant-shell')

  shell?.setAuth({ publishableKey: 'pk_live_your_key_here', idToken: '<id-token>' })
</script>

Shell mode policy:

• closed -> pip
• open desktop -> inline
• open on narrow viewport -> fullscreen

Availability policy:

• 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.

API summary

<char-agent> methods:

• connect(options)
• disconnect()
• setAuth(options | null) (connect when provided, disconnect when null)
• setHostContext(partialContext)

<char-agent-shell> methods:

• connect(options)
• disconnect()
• setAuth(options | null) (connect when provided, disconnect when null)
• setHostContext(partialContext)
• setOpen(open)
• toggleOpen()

<char-agent-shell> events:

• char-shell-open-change ({ open: boolean })
• pass-through char-* events from inner <char-agent>

Shared mode-policy helpers

import {
  DEFAULT_AVAILABLE_DISPLAY_MODES,
  isDisplayMode,
  isExpandedDisplayMode,
  resolvePolicyDisplayMode,
  resolveSupportedDisplayMode,
} from '@mcp-b/char/display-mode-policy'