> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usechar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CharAgentElement

> Generated API reference for CharAgentElement.

# Interface: CharAgentElement

`<char-agent>` custom element.

Creates an iframe pointing to the SaaS app's /embed/ entrypoint and relays
auth, styles, dark mode, display mode, and MCP messages via postMessage.

Uses a unified `char-context` message with diffing (only changed fields
are sent) instead of separate messages per concern.

## Extends

* `HTMLElement`

## Properties

### apiBase?

> `optional` **apiBase**: `string`

React 19-friendly property form of `api-base`.
Read once during `connectedCallback`.

***

### publishableKey?

> `optional` **publishableKey**: `string`

Publishable key for org identification.
Set via `publishable-key` attribute or JS property.

## Methods

### attributeChangedCallback()

> **attributeChangedCallback**(`name`, `_oldValue`, `newValue`): `void`

Reacts to observed attribute updates after iframe readiness.
Attributes that affect iframe boot configuration are intentionally ignored
after mount (`enable-debug-tools`, `api-base`).

#### Parameters

##### name

`string`

##### \_oldValue

`string` | `null`

##### newValue

`string` | `null`

#### Returns

`void`

***

### connect()

> **connect**(`options`): `boolean`

Connect to the Char agent with authentication.

The token is stored as a JavaScript property (not as a DOM attribute),
preventing exposure to DOM inspection and session replay tools.

#### Parameters

##### options

`ConnectOptions`

Authentication payload.

#### Returns

`boolean`

`true` when the payload is accepted; `false` when validation fails.

***

### connectedCallback()

> **connectedCallback**(): `void`

Mount lifecycle: builds iframe runtime, starts proxying, and starts host observers.
The existing runtime is reused when reconnecting during fast detach/reattach cycles.

#### Returns

`void`

***

### disconnect()

> **disconnect**(): `boolean`

Disconnect from the Char agent.
Clears pending auth state and posts a disconnect message to the iframe.

#### Returns

`boolean`

`true` when the disconnect message was sent; `false` when the iframe was not ready.

***

### disconnectedCallback()

> **disconnectedCallback**(): `void`

Unmount lifecycle: requests iframe teardown and releases all host resources.

#### Returns

`void`

***

### setAuth()

> **setAuth**(`options`): `boolean`

Convenience method for declarative wrappers.
Applies auth when provided, otherwise clears auth.

#### Parameters

##### options

Auth payload to connect, or `null` to disconnect.

`ConnectOptions` | `null`

#### Returns

`boolean`

Result from `connect()` or `disconnect()`.

***

### setHostContext()

> **setHostContext**(`hostContext`): `void`

Update the host context sent to the iframe.
Only changed fields are transmitted (diffing pattern).

#### Parameters

##### hostContext

`CharHostContext`

Partial host context patch to merge and emit.

#### Returns

`void`