Skip to main content

​
<char-agent-shell>

<char-agent-shell> custom element. Opinionated host shell that composes a persistent inner <char-agent> and owns responsive mode policy plus host layout orchestration. This shell does not render chat controls, prompts, or composer UI. Visible assistant UI is always iframe-owned. Policy:
  • closed to pip
  • open desktop to inline
  • open narrow viewport to fullscreen

​
Registration and import

import '@mcp-b/char/shell-component'

import { registerCharShell } from '@mcp-b/char/shell-component'
registerCharShell()

​
Auth, open-state, and shell helpers

const shell = document.querySelector('char-agent-shell')

shell?.setAuth({ publishableKey, idToken }) // convenience wrapper
shell?.setOpen(true)                   // controlled open state
shell?.setHostContext({ locale: 'en-US' })
shell?.toggleOpen()

​
Attributes

AttributeTypeDefaultDescription
api-basestringhttps://app.usechar.aiForwarded API base override for the inner element.
enable-debug-toolsbooleanfalseForwarded debug-tool toggle for the iframe runtime.
openbooleanfalseOpen state for policy-resolved layout behavior.

​
Properties

PropertyTypeDescription
apiBasestring | undefinedReact-friendly property form of api-base.
openbooleanCurrent open/closed state for shell layout policy.

​
Methods

MethodReturnsSummary
setAuth()voidConvenience method for declarative wrappers. Applies auth when provided, otherwise clears auth.
connect()voidConnects shell authentication and starts availability health checks.
disconnect()voidClears authentication and disconnects the inner <char-agent>.
setHostContext()voidMerges and forwards host context to the inner <char-agent>. Shell-owned fields (displayMode, availableDisplayModes) are ignored.
setOpen()voidSets shell open state.
toggleOpen()voidToggles shell open state.

​
setAuth(options: ConnectOptions | null): void

Convenience method for declarative wrappers. Applies auth when provided, otherwise clears auth. Parameters:
  • options (ConnectOptions | null): Auth payload to connect, or null to disconnect.
Returns: void

​
connect(options: ConnectOptions): void

Connects shell authentication and starts availability health checks. Parameters:
  • options (ConnectOptions): Authentication payload (publishableKey + optional idToken).
Returns: void

​
disconnect(): void

Clears authentication and disconnects the inner <char-agent>. Returns: void

​
setHostContext(hostContext: CharHostContext): void

Merges and forwards host context to the inner <char-agent>. Shell-owned fields (displayMode, availableDisplayModes) are ignored. Parameters:
  • hostContext (CharHostContext): Partial host context patch to forward.
Returns: void

​
setOpen(open: boolean): void

Sets shell open state. Parameters:
  • open (boolean): Next desired open state.
Returns: void

​
toggleOpen(): void

Toggles shell open state. Returns: void

​
Events

EventDetailDescription
char-shell-open-change{ open: boolean }Emitted when the shell open state changes.
char-initializedvoidForwarded from the inner <char-agent> runtime.
char-closevoidForwarded when embedded UI requests close.
char-errorCharErrorDetailForwarded bridge/runtime errors.
char-size-changedCharSizeChangedDetailForwarded embedded content size updates.
char-request-display-modeCharRequestDisplayModeDetailForwarded mode-change requests from the iframe.
char-open-linkCharOpenLinkDetailBubbled link-open request from the inner element.

​
Slots

None.

​
CSS Custom Properties

Forwards styling to the inner <char-agent>. See CSS Variables Reference.

​
CSS Parts

None.