# ArlopassProvider

The root context provider. Wrap your app (or the subtree that needs AI) with `<ArlopassProvider>` to enable all hooks and guard components.

```tsx
import { ArlopassProvider } from "@arlopass/react";
```

### Props

| Prop               | Type                           | Default | Description                                                                                                 |
|--------------------|--------------------------------|---------|-------------------------------------------------------------------------------------------------------------|
| `appId`            | `string`                       | —       | Full reverse-domain app identifier. Auto-derived from the page origin if omitted.                          |
| `appSuffix`        | `string`                       | —       | Suffix appended to the auto-derived domain prefix. Ignored when appId is set.                              |
| `appName`          | `string`                       | —       | Human-readable app name sent during the connect handshake.                                                  |
| `appDescription`   | `string`                       | —       | Short app description sent during the connect handshake.                                                   |
| `appIcon`          | `string`                       | —       | URL to a square icon/logo (https:// or data: URI).                                                         |
| `defaultProvider`  | `string`                       | —       | Provider ID to auto-select after connecting. Must be paired with defaultModel.                             |
| `defaultModel`     | `string`                       | —       | Model ID to auto-select after connecting. Must be paired with defaultProvider.                             |
| `autoConnect`      | `boolean`                      | `true`  | Connect to the Arlopass extension automatically on mount.                                                  |
| `onError`          | `(error: ArlopassSDKError) => void` | — | Called when a connection or auto-select error occurs.                                                     |
| `children`<br>**required** | `ReactNode`                   | —       | Child components that consume the Arlopass context.                                                        |

### Mount sequence

1. Detects the injected transport from `window.arlopass` (set by the browser extension).
2. Creates a `ArlopassClient` instance bound to that transport.
3. If `autoConnect` is `true` and the transport is available, calls `client.connect()` with the configured app identity.
4. If `defaultProvider` and `defaultModel` are set, calls `client.selectProvider()` after connecting.
5. Publishes the store via React context so child hooks can read snapshot state.

### Unmount / cleanup

On unmount the provider calls `client.disconnect()` and destroys the internal store. Any in-flight operations are cancelled.

### Examples

**Basic usage**

```tsx
import { ArlopassProvider } from "@arlopass/react";

function App() {
  return (
    <ArlopassProvider>
      <MyChat />
    </ArlopassProvider>
  );
}
```

**Auto-select provider and model**

```tsx
<ArlopassProvider defaultProvider="openai" defaultModel="gpt-4o">
  <MyChat />
</ArlopassProvider>
```

**App identity**

```tsx
<ArlopassProvider
  appSuffix="my-chat"
  appName="My Chat App"
  appDescription="A demo chat application"
  appIcon="https://example.com/icon.png"
>
  <MyChat />
</ArlopassProvider>
```

**Manual connect with error callback**

```tsx
<ArlopassProvider
  onError={(err) => console.error(err.machineCode, err.message)}
  autoConnect={false}
>
  <MyChat />
</ArlopassProvider>
```