@mcp-b/char 0.0.6 → 0.1.1

package/dist/index.d.ts

@@ -1,379 +1,760 @@
 
-import { FC, ReactNode } from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
-import { CallToolResult, GetPromptResult, Prompt } from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
-
-//#region src/utils/dev-mode.d.ts
+//#region src/types.d.ts
+/**
+ * Server-issued ticket auth payload.
+ * Used for SSR-friendly authentication flows.
+ *
+ * @public
+ */
+interface TicketAuth {
+  /** Short-lived server-issued ticket used to start an authenticated session. */
+  ticket: string;
+  /** End-user identifier associated with the issued ticket. */
+  userId: string;
+  /** Organization identifier used to scope the authenticated session. */
+  orgId: string;
+}
+/**
+ * Development-only embed controls used by local host integrations.
+ *
+ * @public
+ */
 interface DevModeConfig {
-  /**
-   * Your Anthropic API key for chat.
-   * Required for anonymous mode (no authToken).
-   */
   anthropicApiKey?: string;
-  /** Your OpenAI API key for voice mode (optional) */
   openaiApiKey?: string;
-  /** Use window.location.origin instead of production API (for internal development) */
   useLocalApi?: boolean;
 }
-//#endregion
-//#region ../auth/dist/security/ticket.d.ts
 /**
- * Client-side ticket auth data.
- * This is what the embedded widget uses for WebSocket authentication.
+ * Connection options for the imperative connect() method.
+ *
+ * Supports two mutually exclusive authentication strategies:
+ * - `idToken` + `clientId`: Direct IDP token authentication (SPA-friendly)
+ * - `ticketAuth`: Pre-fetched ticket authentication (SSR-friendly)
+ *
+ * Exactly one strategy must be provided. The discriminated union prevents
+ * combining `idToken` and `ticketAuth` at the type level.
+ *
+ * @public
  */
-interface TicketAuth {
-  /** The opaque ticket string */
-  ticket: string;
-  /** User ID (from token's sub claim) - needed for DO routing */
-  userId: string;
-  /** Organization ID - needed for DO routing */
-  orgId: string;
+type ConnectOptions = {
+  /** IDP token (ID token) for authentication. */idToken: string; /** OIDC client ID for audience validation. Required with `idToken`. */
+  clientId?: string; /** Optional organization context for multi-tenant same-origin dashboards. */
+  organizationId?: string; /** Must not be provided when using `idToken` authentication. */
+  ticketAuth?: never;
+} | {
+  /** Pre-fetched ticket for SSR-friendly authentication. */ticketAuth: TicketAuth; /** Must not be provided when using `ticketAuth` authentication. */
+  idToken?: never; /** Must not be provided when using `ticketAuth` authentication. */
+  clientId?: never; /** Must not be provided when using `ticketAuth` authentication. */
+  organizationId?: never;
+};
+/**
+ * Host visual theme hint.
+ *
+ * @public
+ */
+type CharTheme = 'light' | 'dark';
+/**
+ * Allowed display modes for the host shell and embedded runtime.
+ *
+ * @public
+ */
+type CharDisplayMode = 'inline' | 'fullscreen' | 'pip';
+/**
+ * Host platform hint for embedded UI adaptations.
+ *
+ * @public
+ */
+type CharPlatform = 'web' | 'desktop' | 'mobile';
+/**
+ * Host-provided style payload applied inside the iframe.
+ *
+ * @public
+ */
+interface CharHostStyles {
+  variables?: Record<string, string>;
+  fonts?: string;
+}
+/**
+ * Host container size constraints.
+ *
+ * @public
+ */
+interface CharContainerDimensions {
+  width?: number;
+  height?: number;
+  maxWidth?: number;
+  maxHeight?: number;
 }
-//#endregion
-//#region ../shared-types/dist/schemas/mcp-client.d.ts
 /**
- * Unified configuration for MCP sources
+ * Lightweight device capability hints from the host environment.
+ *
+ * @public
  */
-declare const MCPSourceConfigSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-  type: z.ZodLiteral<"tab">; /** Target origin for postMessage security (default: window.location.origin for same-tab) */
-  targetOrigin: z.ZodOptional<z.ZodString>; /** Channel ID for the TabClientTransport (default: 'mcp-default') */
-  channelId: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-  type: "tab";
-  targetOrigin?: string | undefined;
-  channelId?: string | undefined;
-}, {
-  type: "tab";
-  targetOrigin?: string | undefined;
-  channelId?: string | undefined;
-}>, z.ZodObject<{
-  type: z.ZodLiteral<"http">; /** Server URL */
-  url: z.ZodString; /** Optional authentication token (Bearer) */
-  authToken: z.ZodOptional<z.ZodString>; /** Connection timeout in milliseconds (default: 30000) */
-  timeout: z.ZodOptional<z.ZodNumber>; /** Auto-reconnect on disconnect (default: true) */
-  autoReconnect: z.ZodOptional<z.ZodBoolean>;
-  /**
-   * Transport type preference:
-   * - 'auto': Try HTTP first, fallback to SSE (default)
-   * - 'http': HTTP Streamable transport only
-   * - 'sse': Server-Sent Events transport only
-   */
-  transportType: z.ZodOptional<z.ZodEnum<["auto", "http", "sse"]>>; /** Custom headers to include in requests */
-  customHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-}, "strip", z.ZodTypeAny, {
-  type: "http";
-  url: string;
-  authToken?: string | undefined;
-  timeout?: number | undefined;
-  autoReconnect?: boolean | undefined;
-  transportType?: "auto" | "http" | "sse" | undefined;
-  customHeaders?: Record<string, string> | undefined;
-}, {
-  type: "http";
-  url: string;
-  authToken?: string | undefined;
-  timeout?: number | undefined;
-  autoReconnect?: boolean | undefined;
-  transportType?: "auto" | "http" | "sse" | undefined;
-  customHeaders?: Record<string, string> | undefined;
-}>]>;
-type MCPSourceConfig = z.infer<typeof MCPSourceConfigSchema>;
+interface CharDeviceCapabilities {
+  touch?: boolean;
+  hover?: boolean;
+  pointerFine?: boolean;
+}
 /**
- * Tool with source tracking for multi-source tool management.
- * The _sourceId identifies which client to route tool calls to.
+ * Safe-area inset values detected on the host.
  *
- * This extends the MCP SDK Tool interface shape.
+ * @public
  */
-declare const ToolWithSourceSchema: z.ZodObject<{
-  name: z.ZodString;
-  description: z.ZodOptional<z.ZodString>;
-  inputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-  annotations: z.ZodOptional<z.ZodObject<{
-    title: z.ZodOptional<z.ZodString>;
-    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-    destructiveHint: z.ZodOptional<z.ZodBoolean>;
-    idempotentHint: z.ZodOptional<z.ZodBoolean>;
-    openWorldHint: z.ZodOptional<z.ZodBoolean>;
-  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
-    title: z.ZodOptional<z.ZodString>;
-    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-    destructiveHint: z.ZodOptional<z.ZodBoolean>;
-    idempotentHint: z.ZodOptional<z.ZodBoolean>;
-    openWorldHint: z.ZodOptional<z.ZodBoolean>;
-  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
-    title: z.ZodOptional<z.ZodString>;
-    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-    destructiveHint: z.ZodOptional<z.ZodBoolean>;
-    idempotentHint: z.ZodOptional<z.ZodBoolean>;
-    openWorldHint: z.ZodOptional<z.ZodBoolean>;
-  }, z.ZodTypeAny, "passthrough">>>; /** Source identifier - 'local' for useWebMCP, 'remote' for remote MCP, or iframe/tab ID */
-  _sourceId: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-  name: string;
-  _sourceId: string;
-  description?: string | undefined;
-  inputSchema?: Record<string, unknown> | undefined;
-  annotations?: z.objectOutputType<{
-    title: z.ZodOptional<z.ZodString>;
-    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-    destructiveHint: z.ZodOptional<z.ZodBoolean>;
-    idempotentHint: z.ZodOptional<z.ZodBoolean>;
-    openWorldHint: z.ZodOptional<z.ZodBoolean>;
-  }, z.ZodTypeAny, "passthrough"> | undefined;
-}, {
-  name: string;
-  _sourceId: string;
-  description?: string | undefined;
-  inputSchema?: Record<string, unknown> | undefined;
-  annotations?: z.objectInputType<{
-    title: z.ZodOptional<z.ZodString>;
-    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-    destructiveHint: z.ZodOptional<z.ZodBoolean>;
-    idempotentHint: z.ZodOptional<z.ZodBoolean>;
-    openWorldHint: z.ZodOptional<z.ZodBoolean>;
-  }, z.ZodTypeAny, "passthrough"> | undefined;
-}>;
-type ToolWithSource = z.infer<typeof ToolWithSourceSchema>;
+interface CharSafeAreaInsets {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
 /**
- * State of an MCP source connection.
+ * Host shell capability flags advertised to the iframe runtime.
  *
- * Note: This schema uses z.unknown() for arrays of SDK types (Tool, Resource, etc.)
- * because we don't want to re-define those schemas here. Runtime validation
- * of these arrays should be done at the boundary where SDK types are received.
+ * @public
  */
-declare const MCPSourceSchema: z.ZodObject<{
-  /** Unique identifier for this source */id: z.ZodString; /** Configuration used to create this source */
-  config: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
-    type: z.ZodLiteral<"tab">; /** Target origin for postMessage security (default: window.location.origin for same-tab) */
-    targetOrigin: z.ZodOptional<z.ZodString>; /** Channel ID for the TabClientTransport (default: 'mcp-default') */
-    channelId: z.ZodOptional<z.ZodString>;
-  }, "strip", z.ZodTypeAny, {
-    type: "tab";
-    targetOrigin?: string | undefined;
-    channelId?: string | undefined;
-  }, {
-    type: "tab";
-    targetOrigin?: string | undefined;
-    channelId?: string | undefined;
-  }>, z.ZodObject<{
-    type: z.ZodLiteral<"http">; /** Server URL */
-    url: z.ZodString; /** Optional authentication token (Bearer) */
-    authToken: z.ZodOptional<z.ZodString>; /** Connection timeout in milliseconds (default: 30000) */
-    timeout: z.ZodOptional<z.ZodNumber>; /** Auto-reconnect on disconnect (default: true) */
-    autoReconnect: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Transport type preference:
-     * - 'auto': Try HTTP first, fallback to SSE (default)
-     * - 'http': HTTP Streamable transport only
-     * - 'sse': Server-Sent Events transport only
-     */
-    transportType: z.ZodOptional<z.ZodEnum<["auto", "http", "sse"]>>; /** Custom headers to include in requests */
-    customHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  }, "strip", z.ZodTypeAny, {
-    type: "http";
-    url: string;
-    authToken?: string | undefined;
-    timeout?: number | undefined;
-    autoReconnect?: boolean | undefined;
-    transportType?: "auto" | "http" | "sse" | undefined;
-    customHeaders?: Record<string, string> | undefined;
-  }, {
-    type: "http";
-    url: string;
-    authToken?: string | undefined;
-    timeout?: number | undefined;
-    autoReconnect?: boolean | undefined;
-    transportType?: "auto" | "http" | "sse" | undefined;
-    customHeaders?: Record<string, string> | undefined;
-  }>]>; /** Connection state */
-  state: z.ZodEnum<["idle", "connecting", "connected", "error"]>; /** Connection error message (if any) */
-  error: z.ZodNullable<z.ZodString>; /** Tools available from this source */
-  tools: z.ZodArray<z.ZodUnknown, "many">; /** Resources available from this source */
-  resources: z.ZodArray<z.ZodUnknown, "many">; /** Resource templates available from this source */
-  resourceTemplates: z.ZodArray<z.ZodUnknown, "many">; /** Prompts available from this source */
-  prompts: z.ZodArray<z.ZodUnknown, "many">;
-}, "strip", z.ZodTypeAny, {
-  id: string;
-  error: string | null;
-  config: {
-    type: "tab";
-    targetOrigin?: string | undefined;
-    channelId?: string | undefined;
-  } | {
-    type: "http";
-    url: string;
-    authToken?: string | undefined;
-    timeout?: number | undefined;
-    autoReconnect?: boolean | undefined;
-    transportType?: "auto" | "http" | "sse" | undefined;
-    customHeaders?: Record<string, string> | undefined;
-  };
-  state: "idle" | "connecting" | "connected" | "error";
-  tools: unknown[];
-  resources: unknown[];
-  resourceTemplates: unknown[];
-  prompts: unknown[];
-}, {
-  id: string;
-  error: string | null;
-  config: {
-    type: "tab";
-    targetOrigin?: string | undefined;
-    channelId?: string | undefined;
-  } | {
-    type: "http";
-    url: string;
-    authToken?: string | undefined;
-    timeout?: number | undefined;
-    autoReconnect?: boolean | undefined;
-    transportType?: "auto" | "http" | "sse" | undefined;
-    customHeaders?: Record<string, string> | undefined;
-  };
-  state: "idle" | "connecting" | "connected" | "error";
-  tools: unknown[];
-  resources: unknown[];
-  resourceTemplates: unknown[];
-  prompts: unknown[];
-}>;
-type MCPSource = z.infer<typeof MCPSourceSchema>;
-//#endregion
-//#region src/providers/MCPToolsProvider.d.ts
+interface CharHostCapabilities {
+  supportedDisplayModes?: CharDisplayMode[];
+  supportsOpenLink?: boolean;
+  supportsTeardown?: boolean;
+  maxContainerWidth?: number;
+}
+/**
+ * Host context payload sent from the embedding page to the iframe runtime.
+ *
+ * @public
+ */
+interface CharHostContext {
+  theme?: CharTheme;
+  styles?: CharHostStyles;
+  displayMode?: CharDisplayMode;
+  availableDisplayModes?: CharDisplayMode[];
+  containerDimensions?: CharContainerDimensions;
+  locale?: string;
+  timeZone?: string;
+  platform?: CharPlatform;
+  deviceCapabilities?: CharDeviceCapabilities;
+  safeAreaInsets?: CharSafeAreaInsets;
+  userAgent?: string;
+  hostCapabilities?: CharHostCapabilities;
+}
+/**
+ * Payload for the `char-size-changed` event.
+ *
+ * @public
+ */
+interface CharSizeChangedDetail {
+  width?: number;
+  height?: number;
+  displayMode?: CharDisplayMode;
+}
 /**
- * MCP Tools Context Value
+ * Payload for the `char-request-display-mode` event.
+ *
+ * @public
  */
-interface MCPToolsContextValue {
-  /** All tools from all sources, tagged with _sourceId */
-  tools: ToolWithSource[];
-  /** All prompts from all sources */
-  prompts: Prompt[];
-  /** All sources and their states */
-  sources: Map<string, MCPSource>;
-  /** Add a new source */
-  addSource: (id: string, config: MCPSourceConfig) => Promise<void>;
-  /** Remove a source */
-  removeSource: (id: string) => Promise<void>;
-  /** Get a specific source */
-  getSource: (id: string) => MCPSource | undefined;
-  /** Check if a source is connected */
-  isConnected: (id: string) => boolean;
-  /** Call a tool (auto-routes based on tool name lookup) */
-  callTool: (name: string, args: Record<string, unknown>) => Promise<CallToolResult>;
-  /** Call a tool on a specific source */
-  callToolOnSource: (sourceId: string, name: string, args: Record<string, unknown>) => Promise<CallToolResult>;
-  /** Get a prompt's expanded content (auto-routes based on prompt name lookup) */
-  getPrompt: (name: string, args?: Record<string, string>) => Promise<GetPromptResult>;
-  /**
-   * Refresh tools from all connected sources.
-   * Call this after dynamically registering tools via useWebMCP inside the provider tree.
-   */
-  refreshTools: () => Promise<void>;
+interface CharRequestDisplayModeDetail {
+  mode?: CharDisplayMode;
 }
-interface MCPToolsProviderProps {
-  children: ReactNode;
-  /** Auto-connect to same-tab source on mount (default: true) */
-  autoConnectLocal?: boolean;
-  /** Callback when tools change */
-  onToolsChange?: (tools: ToolWithSource[]) => void;
-  /** Callback when prompts change */
-  onPromptsChange?: (prompts: Prompt[]) => void;
+/**
+ * Payload for the `char-error` event.
+ *
+ * @public
+ */
+interface CharErrorDetail {
+  code: string;
+  message?: string;
 }
-declare function MCPToolsProvider({
-  children,
-  autoConnectLocal,
-  onToolsChange,
-  onPromptsChange
-}: MCPToolsProviderProps): react_jsx_runtime0.JSX.Element;
 /**
- * Hook to access MCP Tools context
+ * Payload for the `char-open-link` event.
+ *
+ * @public
  */
-declare function useMCPTools(): MCPToolsContextValue;
+interface CharOpenLinkDetail {
+  requestId: string;
+  url: string;
+  ok: boolean;
+}
 //#endregion
-//#region src/index.d.ts
+//#region src/web-component.d.ts
 /**
- * Props for the Char component
+ * `<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.
+ *
+ * @public
  */
-interface CharProps {
+declare class CharAgentElement extends HTMLElement {
+  static observedAttributes: string[];
+  /**
+   * React 19-friendly property form of `dev-mode`.
+   * Read once during `connectedCallback`.
+   */
+  devMode?: DevModeConfig;
+  /**
+   * React 19-friendly property form of `api-base`.
+   * Read once during `connectedCallback`.
+   */
+  apiBase?: string;
+  /** Active iframe element owned by this custom element instance. */
+  private _iframe;
+  /** MCP relay between host window and embed iframe. */
+  private _proxy;
+  /** Indicates whether the iframe has emitted `char-ready`. */
+  private _iframeReady;
+  /** Bound window message handler for iframe-originated events. */
+  private _messageListener;
+  /** Observer that tracks host theme mutations. */
+  private _darkModeObserver;
+  /** Media query object for `prefers-color-scheme`. */
+  private _darkModeMediaQuery;
+  /** Registered media query callback. */
+  private _darkModeMediaHandler;
+  /** Observer that tracks host style/class mutations. */
+  private _styleObserver;
+  /** Observer that tracks container size changes. */
+  private _containerResizeObserver;
+  /** In-flight teardown request waiting for iframe acknowledgement. */
+  private _teardownPending;
+  /** Monotonic sequence used to construct teardown request IDs. */
+  private _teardownSequence;
+  /** Re-entrancy guard used during disconnect lifecycle. */
+  private _isDisconnecting;
+  /** Last host context snapshot used for delta emission. */
+  private _hostContext;
+  /** Pending credentials that are flushed when the iframe is ready. */
+  private _pendingAuth;
+  /**
+   * Mount lifecycle: builds iframe runtime, starts proxying, and starts host observers.
+   * The existing runtime is reused when reconnecting during fast detach/reattach cycles.
+   */
+  connectedCallback(): void;
+  /**
+   * Determines whether this instance already has an initialized runtime.
+   */
+  private _hasActiveRuntime;
+  /**
+   * Parses and validates the iframe origin from the configured API base URL.
+   *
+   * @throws Error When `apiBase` is not a valid URL.
+   */
+  private _resolveIframeOrigin;
+  /**
+   * Creates a fully configured iframe element for the embed runtime.
+   */
+  private _createIframe;
+  /**
+   * Creates the message listener that filters by source/origin and dispatches typed events.
+   */
+  private _createMessageListener;
+  /**
+   * Routes validated iframe messages to local handlers and host DOM events.
+   */
+  private _handleIframeMessage;
+  /**
+   * Emits a host-facing custom event without detail payload.
+   */
+  private _emitCharEvent;
+  /**
+   * Emits a host-facing custom event with detail payload.
+   */
+  private _emitCharEventWithDetail;
+  /**
+   * Emits a standardized `char-error` event.
+   */
+  private _emitCharError;
+  /**
+   * Unmount lifecycle: requests iframe teardown and releases all host resources.
+   */
+  disconnectedCallback(): void;
+  /**
+   * Releases iframe, observers, listeners, and pending teardown state.
+   */
+  private _finalizeDisconnect;
+  /**
+   * Reacts to observed attribute updates after iframe readiness.
+   * Attributes that affect iframe boot configuration are intentionally ignored
+   * after mount (`dev-mode`, `enable-debug-tools`, `api-base`).
+   */
+  attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+  /**
+   * 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.
+   *
+   * @param options - Authentication payload for either ID token or ticket auth.
+   * @returns `true` when the payload is accepted; `false` when validation fails.
+   */
+  connect(options: ConnectOptions): boolean;
+  /**
+   * Convenience method for declarative wrappers.
+   * Applies auth when provided, otherwise clears auth.
+   *
+   * @param options - Auth payload to connect, or `null` to disconnect.
+   * @returns Result from `connect()` or `disconnect()`.
+   */
+  setAuth(options: ConnectOptions | null): boolean;
+  /**
+   * Disconnect from the Char agent.
+   * Clears the authentication token.
+   *
+   * @returns `true` when the disconnect message was sent; `false` when the iframe was not ready.
+   */
+  disconnect(): boolean;
+  /**
+   * Resolves the current iframe origin when mounted.
+   */
+  private _getIframeOrigin;
+  /**
+   * Update the host context sent to the iframe.
+   * Only changed fields are transmitted (diffing pattern).
+   *
+   * @param hostContext - Partial host context patch to merge and emit.
+   */
+  setHostContext(hostContext: CharHostContext): void;
+  /**
+   * Build and send the full initial context after iframe signals char-ready.
+   *
+   * @param iframeOrigin - Trusted origin used for postMessage target filtering.
+   */
+  private _sendInitialContext;
   /**
-   * IDP token for SSO-first authentication.
+   * Send a context delta to the iframe.
    *
-   * Pass your existing IDP token (from Okta, Azure AD, Auth0, Google, etc.)
-   * and the backend will validate it against your organization's configured IDP.
+   * @param changes - Minimal context patch derived from diffing.
+   */
+  private _sendContextDelta;
+  /**
+   * Post authentication credentials to the iframe.
    *
-   * When provided:
-   * - Messages persist across refreshes (Cloudflare Durable Objects)
-   * - User ID extracted from token's sub claim
-   * - Tools shared across all your organization's apps
+   * @param iframeOrigin - Trusted origin used for postMessage target filtering.
+   */
+  private _postAuth;
+  /**
+   * Requests graceful iframe teardown and resolves once acknowledged or timed out.
    *
-   * When NOT provided:
-   * - Anonymous mode with Durable Objects
-   * - Requires anthropicApiKey for AI calls
-   * - Localhost-only for security
+   * @param iframeOrigin - Trusted origin used for postMessage target filtering.
+   * @param reason - Lifecycle reason for teardown.
+   * @returns Promise resolved when teardown flow completes.
    */
-  authToken?: string;
+  private _requestTeardown;
   /**
-   * OIDC client ID for audience validation.
-   * Required when using `authToken` authentication.
+   * Completes an in-flight teardown promise when the iframe acknowledges it.
    *
-   * This must match the token's `aud` claim and be in the organization's
-   * `allowed_audiences` list (configured in the Char dashboard).
+   * @param requestId - Optional request identifier to match against pending teardown.
    */
-  clientId?: string;
+  private _resolvePendingTeardown;
   /**
-   * Pre-fetched ticket for SSR-friendly authentication.
+   * Handles open-link requests from the iframe with protocol allowlisting.
+   * This allowlist intentionally mirrors the iframe-side pre-filter.
    *
-   * Benefits:
-   * - IDP token never exposed to browser (in SSR mode)
-   * - No JWKS fetch on every connection (validation done once)
-   * - Ticket is short-lived (60s default) and single-use
+   * @param requestId - Link request identifier supplied by the iframe.
+   * @param url - Requested URL string.
+   * @param iframeOrigin - Trusted origin used for postMessage target filtering.
+   */
+  private _handleOpenLinkRequest;
+  /**
+   * Observe dark mode changes and forward to iframe via unified context.
    */
-  ticketAuth?: TicketAuth;
+  private _observeDarkMode;
   /**
-   * Controlled open state.
-   * When provided, the host controls whether the agent UI is open or collapsed.
+   * Observe style attribute changes on <char-agent> to detect CSS variable updates.
+   * Re-extracts variables and sends delta via unified context.
    */
-  open?: boolean;
+  private _observeStyleChanges;
   /**
-   * Additional CSS class name for the container.
-   * Useful for applying custom container styles.
+   * Observe host element dimensions to provide containerDimensions context.
    */
-  className?: string;
+  private _observeContainerDimensions;
   /**
-   * Callback when the close button is clicked.
-   * Use this to control visibility from the host app.
+   * Resolve devMode from property (React 19) or attribute.
+   *
+   * @returns Parsed dev-mode configuration when valid.
    */
-  onClose?: () => void;
+  private _resolveDevMode;
   /**
-   * Development mode - use your own API keys for testing.
-   * In production, leave this undefined to use your WebMCP plan.
+   * Resolve apiBase override from property (React 19) or attribute.
+   *
+   * @returns Sanitized API base URL without trailing slash.
    */
+  private _resolveApiBaseOverride;
+}
+/**
+ * Type declaration for the Char custom element.
+ * Useful for TypeScript consumers using refs.
+ *
+ * @public
+ */
+/**
+ * Legacy alias for `CharAgentElement`.
+ *
+ * @public
+ */
+type CharElement = CharAgentElement;
+/**
+ * Backward-compatible alias for `CharAgentElement`.
+ *
+ * @public
+ */
+type WebMCPAgentElement = CharAgentElement;
+/**
+ * Register the <char-agent> custom element.
+ * Called automatically when importing this module.
+ *
+ * @param tagName - Optional custom tag name override.
+ *
+ * @public
+ */
+declare function registerChar(tagName?: string): void;
+declare global {
+  interface HTMLElementTagNameMap {
+    'char-agent': CharAgentElement;
+  }
+  namespace JSX {
+    interface IntrinsicElements {
+      'char-agent': {
+        /** Development mode configuration (JSON string for HTML attributes). */'dev-mode'?: string; /** Property form of dev mode config. */
+        devMode?: DevModeConfig; /** Explicit API base override, e.g. `https://staging-app.usechar.ai`. */
+        'api-base'?: string; /** Property form of API base override. */
+        apiBase?: string; /** Enable debug tools for inspecting embedded agent internal state. */
+        'enable-debug-tools'?: boolean; /** Display mode for host orchestration: `pip` is collapsed launcher mode. */
+        'display-mode'?: CharDisplayMode; /** Callback when the close button inside the agent panel is clicked. */
+        onClose?: () => void; /** Imperative ref to the custom element instance. */
+        ref?: unknown;
+        [key: string]: unknown;
+      };
+    }
+  }
+}
+declare module 'react/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'char-agent': {
+        'dev-mode'?: string;
+        devMode?: DevModeConfig;
+        'api-base'?: string;
+        apiBase?: string;
+        'enable-debug-tools'?: boolean;
+        'display-mode'?: CharDisplayMode;
+        onClose?: () => void;
+        ref?: unknown;
+        [key: string]: unknown;
+      };
+    }
+  }
+} //# sourceMappingURL=web-component.d.ts.map
+//#endregion
+//#region src/shell-component.d.ts
+/**
+ * Allowed positions for the collapsed PIP composer surface.
+ *
+ * @public
+ */
+type CharPipPosition = 'bottom-center' | 'bottom-right' | 'bottom-left';
+/**
+ * Payload for `char-shell-open-change`.
+ *
+ * @public
+ */
+interface CharShellOpenChangeDetail {
+  open: boolean;
+}
+/**
+ * `<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`
+ *
+ * @public
+ */
+declare class CharAgentShellElement extends HTMLElement {
+  static observedAttributes: string[];
   devMode?: DevModeConfig;
+  apiBase?: string;
+  private _agent;
+  private _open;
+  private _fullscreenBreakpoint;
+  private _panelWidth;
+  private _pipWidth;
+  private _pipHeight;
+  private _pipPosition;
+  private _isNarrowViewport;
+  private _mediaQuery;
+  private _mediaQueryHandler;
+  private _pendingConnectOptions;
+  private _pendingHostContext;
+  private _isApplyingOpenAttribute;
+  private _forwardedListenersAttached;
+  private _healthState;
+  private _healthTimeoutId;
+  private _pipMeasuredHeight;
+  private _revealFrameId;
+  private _pipExpanded;
+  private _pipPillElement;
+  private _pipCollapseTimerId;
+  private _hoverMediaQuery;
+  private _pipListenersAttached;
+  private _pipAnimating;
+  private _pipAnimationTimeoutId;
+  private _pendingPipMeasuredHeight;
+  private _tapOutsideListener;
+  private _pipHiddenByScroll;
+  private _scrollListener;
+  private _scrollRafId;
+  private _lastScrollEl;
+  private _lastScrollTop;
+  private _scrollDelta;
+  private _swipeTouchStartY;
+  private _swipeStartAtTop;
+  private _swipeStartAtBottom;
+  private _swipeTouchStartListener;
+  private _swipeTouchEndListener;
+  private _wheelListener;
+  private _wheelDelta;
+  get open(): boolean;
+  set open(value: boolean);
+  get fullscreenBreakpoint(): number;
+  set fullscreenBreakpoint(value: number);
+  get panelWidth(): number;
+  set panelWidth(value: number);
+  get pipWidth(): number;
+  set pipWidth(value: number);
+  get pipHeight(): number;
+  set pipHeight(value: number);
+  get pipPosition(): CharPipPosition;
+  set pipPosition(value: CharPipPosition);
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+  /**
+   * Connects shell authentication and starts availability health checks.
+   *
+   * @param options - Authentication payload for either ID token or ticket auth.
+   * @returns `true` when connect is accepted by the inner element.
+   */
+  connect(options: ConnectOptions): boolean;
+  /**
+   * Clears authentication and disconnects the inner `<char-agent>`.
+   *
+   * @returns `true` when disconnect dispatch succeeds.
+   */
+  disconnect(): boolean;
+  /**
+   * Convenience method for declarative wrappers.
+   * Applies auth when provided, otherwise clears auth.
+   *
+   * @param options - Auth payload to connect, or `null` to disconnect.
+   * @returns Result from `connect()` or `disconnect()`.
+   */
+  setAuth(options: ConnectOptions | null): boolean;
+  /**
+   * Merges and forwards host context to the inner `<char-agent>`.
+   * Shell-owned fields (`displayMode`, `availableDisplayModes`) are ignored.
+   *
+   * @param hostContext - Partial host context patch to forward.
+   */
+  setHostContext(hostContext: CharHostContext): void;
+  /**
+   * Sets shell open state.
+   *
+   * @param open - Next desired open state.
+   */
+  setOpen(open: boolean): void;
   /**
-   * Enable debug tools for inspecting embedded agent internal state.
-   * @default false
+   * Toggles shell open state.
    */
-  enableDebugTools?: boolean;
+  toggleOpen(): void;
+  private _upgradeProperty;
+  private _ensureAgent;
+  private _primeAgentBootConfig;
+  private _attachForwardedListeners;
+  private _detachForwardedListeners;
+  private _readConfigFromAttributes;
+  private _syncForwardedAttributes;
+  private _setupViewportObserver;
+  private _teardownViewportObserver;
+  private _applyDisplayModeAndLayout;
+  private _applyHostLayout;
+  private _composePipTransform;
+  private _applyAgentLayout;
+  private _ensurePipPill;
+  private _updatePipPillPosition;
+  private _applyPipVisualState;
+  private _setPipExpanded;
+  private _flushPendingPipMeasuredHeight;
+  private _isHoverDevice;
+  private _attachPipInteractionListeners;
+  private _detachPipInteractionListeners;
+  private _schedulePipCollapse;
+  private _clearPipCollapseTimer;
+  private _attachTapOutsideListener;
+  private _detachTapOutsideListener;
+  private _handlePipPointerEnter;
+  private _handlePipPointerLeave;
+  private _attachScrollHideListener;
+  private _evaluateScrollPosition;
+  private _detachScrollHideListener;
+  private _attachSwipeGestureListeners;
+  private _detachSwipeGestureListeners;
+  private _attachWheelFallbackListener;
+  private _detachWheelFallbackListener;
+  private _handlePillClick;
+  private _handlePillKeydown;
+  private _hidePipPill;
+  private _resetHostLayoutStyles;
+  private _resetAgentLayoutStyles;
+  private _applyUnavailableLayout;
+  private _applyPreReadyLayout;
+  private _startHealthWait;
+  private _stopHealthWait;
+  private _markHealthy;
+  private _cancelRevealFade;
+  private _startRevealFade;
+  private _setUnavailable;
+  private _recoverFromUnavailable;
+  private _setOpenInternal;
+  private _reflectOpenAttribute;
+  private _flushPendingConnectAndContext;
+  private _handleRequestDisplayMode;
+  private _handleClose;
+  private _handleInitialized;
+  private _handleInnerError;
+  private _handleInnerSizeChanged;
+}
+/**
+ * Registers the `<char-agent-shell>` custom element.
+ *
+ * @param tagName - Optional custom tag name override.
+ *
+ * @public
+ */
+declare function registerCharShell(tagName?: string): void;
+declare global {
+  interface HTMLElementTagNameMap {
+    'char-agent-shell': CharAgentShellElement;
+  }
+  namespace JSX {
+    interface IntrinsicElements {
+      'char-agent-shell': {
+        open?: boolean;
+        'fullscreen-breakpoint'?: number;
+        'panel-width'?: number;
+        'pip-position'?: CharPipPosition;
+        'pip-width'?: number;
+        'pip-height'?: number;
+        'dev-mode'?: string;
+        devMode?: DevModeConfig;
+        'api-base'?: string;
+        apiBase?: string;
+        'enable-debug-tools'?: boolean;
+        ref?: unknown;
+        [key: string]: unknown;
+      };
+    }
+  }
 }
+declare module 'react/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'char-agent-shell': {
+        open?: boolean;
+        'fullscreen-breakpoint'?: number;
+        'panel-width'?: number;
+        'pip-position'?: CharPipPosition;
+        'pip-width'?: number;
+        'pip-height'?: number;
+        'dev-mode'?: string;
+        devMode?: DevModeConfig;
+        'api-base'?: string;
+        apiBase?: string;
+        'enable-debug-tools'?: boolean;
+        ref?: unknown;
+        [key: string]: unknown;
+      };
+    }
+  }
+} //# sourceMappingURL=shell-component.d.ts.map
+//#endregion
+//#region src/display-mode-policy.d.ts
+/**
+ * Default display modes advertised by Char hosts.
+ *
+ * Order matters for fallback behavior. When a preferred mode is unavailable,
+ * the first available mode is selected.
+ *
+ * @public
+ */
+declare const DEFAULT_AVAILABLE_DISPLAY_MODES: readonly ["inline", "fullscreen", "pip"];
+/**
+ * Runtime guard for Char display mode values.
+ *
+ * @param value - Raw value from host attributes, events, or external input.
+ * @returns `true` when the value is one of `inline`, `fullscreen`, or `pip`.
+ *
+ * @public
+ */
+declare function isDisplayMode(value: string | null | undefined): value is CharDisplayMode;
+/**
+ * Checks whether a display mode represents an expanded agent surface.
+ *
+ * Expanded modes are:
+ * - `inline` (panel-style)
+ * - `fullscreen` (viewport-filling)
+ *
+ * Collapsed mode is:
+ * - `pip` (launcher-only)
+ *
+ * @param mode - Current display mode from host context.
+ * @returns `true` for expanded modes and `false` for collapsed/undefined modes.
+ *
+ * @public
+ */
+declare function isExpandedDisplayMode(mode: CharDisplayMode | undefined): boolean;
+/**
+ * Resolves a preferred display mode against host-supported modes.
+ *
+ * An empty `availableModes` array means "no constraint" — the preferred mode
+ * is returned unconditionally. This is intentional: it allows callers to opt
+ * out of mode filtering without a separate code path.
+ *
+ * @param preferred - Preferred mode requested by host policy.
+ * @param availableModes - Supported modes advertised by the host.
+ * @returns Preferred mode when supported, otherwise the first available mode.
+ *
+ * @public
+ */
+declare function resolveSupportedDisplayMode(preferred: CharDisplayMode, availableModes?: readonly CharDisplayMode[]): CharDisplayMode;
 /**
- * Char - Drop-in AI chat widget for React
- *
- * A fully self-contained chat widget with:
- * - SSO-first authentication (use your existing IDP token)
- * - MCP tool support (connect to any MCP server)
- * - Voice mode (talk to your AI assistant)
- * - Action-first UI (shows what the AI is doing, not just typing)
- * - Shadow DOM isolation (styles don't leak in or out)
- *
- * @example
- * ```tsx
- * <Char
- *   ticketAuth={{ ticket, userId, orgId }}
- *   open={isOpen}
- *   onClose={() => setIsOpen(false)}
- * />
- * ```
+ * Resolves Char's standard host display-mode policy.
+ *
+ * Policy:
+ * - Closed state to `pip`
+ * - Open on desktop to `inline`
+ * - Open on narrow viewport to `fullscreen`
+ *
+ * The resolved mode is then constrained to `availableModes`.
+ *
+ * @param options - Host orchestration inputs: `open`, `isNarrowViewport`,
+ * and optional `availableModes`.
+ * @returns Final mode that satisfies policy and availability constraints.
+ *
+ * @public
  */
-declare const Char: FC<CharProps>;
+declare function resolvePolicyDisplayMode(options: {
+  open: boolean;
+  isNarrowViewport: boolean;
+  availableModes?: readonly CharDisplayMode[];
+}): CharDisplayMode;
 //#endregion
-export { Char, Char as default, CharProps, type DevModeConfig, type MCPToolsContextValue, MCPToolsProvider, type MCPToolsProviderProps, type TicketAuth, useMCPTools };
+export { type CharAgentElement, type CharAgentShellElement, type CharContainerDimensions, type CharDeviceCapabilities, type CharDisplayMode, type CharElement, type CharErrorDetail, type CharHostCapabilities, type CharHostContext, type CharHostStyles, type CharOpenLinkDetail, type CharPipPosition, type CharPlatform, type CharRequestDisplayModeDetail, type CharSafeAreaInsets, type CharShellOpenChangeDetail, type CharSizeChangedDetail, type CharTheme, type ConnectOptions, DEFAULT_AVAILABLE_DISPLAY_MODES, type DevModeConfig, type TicketAuth, type WebMCPAgentElement, isDisplayMode, isExpandedDisplayMode, registerChar, registerCharShell, resolvePolicyDisplayMode, resolveSupportedDisplayMode };
 //# sourceMappingURL=index.d.ts.map