@mcp-b/char 0.0.6 → 0.1.1

package/dist/shell-component.d.ts

@@ -0,0 +1,379 @@
+
+//#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 {
+  anthropicApiKey?: string;
+  openaiApiKey?: string;
+  useLocalApi?: boolean;
+}
+/**
+ * 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
+ */
+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;
+}
+/**
+ * Lightweight device capability hints from the host environment.
+ *
+ * @public
+ */
+interface CharDeviceCapabilities {
+  touch?: boolean;
+  hover?: boolean;
+  pointerFine?: boolean;
+}
+/**
+ * Safe-area inset values detected on the host.
+ *
+ * @public
+ */
+interface CharSafeAreaInsets {
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+}
+/**
+ * Host shell capability flags advertised to the iframe runtime.
+ *
+ * @public
+ */
+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;
+}
+//#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;
+  /**
+   * Toggles shell open state.
+   */
+  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
+export { CharAgentShellElement, type CharContainerDimensions, type CharDeviceCapabilities, type CharDisplayMode, type CharHostCapabilities, type CharHostContext, type CharHostStyles, CharPipPosition, type CharPlatform, type CharSafeAreaInsets, CharShellOpenChangeDetail, type CharTheme, type ConnectOptions, type DevModeConfig, type TicketAuth, registerCharShell };
+//# sourceMappingURL=shell-component.d.ts.map

package/dist/shell-component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-component.d.ts","names":[],"sources":["../src/types.ts","../src/shell-component.ts"],"mappings":";;;AAMA;;;;;UAAiB,UAAA;EAMhB;EAJA,MAAA;EAIK;EAFL,MAAA;EAU6B;EAR7B,KAAA;AAAA;;;;;;UAQgB,aAAA;EAChB,eAAA;EACA,YAAA;EACA,WAAA;AAAA;;;;;;;;;;;AA0CD;;KA3BY,cAAA;EA2BS,+CAxBlB,OAAA,UA+BS;EA7BT,QAAA;EAEA,cAAA,WA2BwB;EAzBxB,UAAA;AAAA;4DAIA,UAAA,EAAY,UAAA,EA4BS;EA1BrB,OAAA,UAiC4B;EA/B5B,QAAA,UAgCgB;EA9BhB,cAAA;AAAA;;;;AAuCH;;KA/BY,SAAA;;;;;;KAOA,eAAA;;AAoCZ;;;;KA7BY,YAAA;;;;;AAwCZ;UAjCiB,cAAA;EAChB,SAAA,GAAY,MAAA;EACZ,KAAA;AAAA;;;;;;UAQgB,uBAAA;EAChB,KAAA;EACA,MAAA;EACA,QAAA;EACA,SAAA;AAAA;;;;;;UAQgB,sBAAA;EAChB,KAAA;EACA,KAAA;EACA,WAAA;AAAA;;;;;;UAQgB,kBAAA;EAChB,GAAA;EACA,KAAA;EACA,MAAA;EACA,IAAA;AAAA;;;;;;UAQgB,oBAAA;EAChB,qBAAA,GAAwB,eAAA;EACxB,gBAAA;EACA,gBAAA;EACA,iBAAA;AAAA;;;;;;UAQgB,eAAA;EAChB,KAAA,GAAQ,SAAA;EACR,MAAA,GAAS,cAAA;EACT,WAAA,GAAc,eAAA;EACd,qBAAA,GAAwB,eAAA;EACxB,mBAAA,GAAsB,uBAAA;EACtB,MAAA;EACA,QAAA;EACA,QAAA,GAAW,YAAA;EACX,kBAAA,GAAqB,sBAAA;EACrB,cAAA,GAAiB,kBAAA;EACjB,SAAA;EACA,gBAAA,GAAmB,oBAAA;AAAA;;;AArJpB;;;;;AAAA,KC6CY,eAAA;;;;AD/BZ;;UCsCiB,yBAAA;EAChB,IAAA;AAAA;;;;ADrBD;;;;;;;;;;;;cCwIa,qBAAA,SAA8B,WAAA;EAAA,OACnC,kBAAA;EAYC,OAAA,GAAU,aAAA;EACV,OAAA;EAAA,QAEA,MAAA;EAAA,QACA,KAAA;EAAA,QACA,qBAAA;EAAA,QACA,WAAA;EAAA,QACA,SAAA;EAAA,QACA,UAAA;EAAA,QACA,YAAA;EAAA,QACA,iBAAA;EAAA,QACA,WAAA;EAAA,QACA,kBAAA;EAAA,QACA,sBAAA;EAAA,QACA,mBAAA;EAAA,QACA,wBAAA;EAAA,QACA,2BAAA;EAAA,QACA,YAAA;EAAA,QACA,gBAAA;EAAA,QACA,kBAAA;EAAA,QACA,cAAA;EAAA,QACA,YAAA;EAAA,QACA,eAAA;EAAA,QACA,mBAAA;EAAA,QACA,gBAAA;EAAA,QACA,qBAAA;EAAA,QACA,aAAA;EAAA,QACA,sBAAA;EAAA,QACA,yBAAA;EAAA,QACA,mBAAA;EAAA,QACA,kBAAA;EAAA,QACA,eAAA;EAAA,QACA,YAAA;EAAA,QACA,aAAA;EAAA,QACA,cAAA;EAAA,QACA,YAAA;EAAA,QACA,iBAAA;EAAA,QACA,gBAAA;EAAA,QACA,mBAAA;EAAA,QACA,wBAAA;EAAA,QACA,sBAAA;EAAA,QACA,cAAA;EAAA,QACA,WAAA;EAAA,IAEJ,IAAA,CAAA;EAAA,IAIA,IAAA,CAAK,KAAA;EAAA,IAIL,oBAAA,CAAA;EAAA,IAIA,oBAAA,CAAqB,KAAA;EAAA,IAcrB,UAAA,CAAA;EAAA,IAIA,UAAA,CAAW,KAAA;EAAA,IAUX,QAAA,CAAA;EAAA,IAIA,QAAA,CAAS,KAAA;EAAA,IAUT,SAAA,CAAA;EAAA,IAIA,SAAA,CAAU,KAAA;EAAA,IAUV,WAAA,CAAA,GAAe,eAAA;EAAA,IAIf,WAAA,CAAY,KAAA,EAAO,eAAA;EAUvB,iBAAA,CAAA;EAmBA,oBAAA,CAAA;EAmBA,wBAAA,CACC,IAAA,UACA,SAAA,iBACA,QAAA;ED9NsC;;;;;;ECwSvC,OAAA,CAAQ,OAAA,EAAS,cAAA;EDrSA;AAQlB;;;;ECqTC,UAAA,CAAA;EDlTc;;;;;;;ECkUd,OAAA,CAAQ,OAAA,EAAS,cAAA;EDzTsB;;;;;;ECsUvC,cAAA,CAAe,WAAA,EAAa,eAAA;ED9U5B;;;;;ECkWA,OAAA,CAAQ,IAAA;ED9VR;;;ECkXA,UAAA,CAAA;EAAA,QAIQ,gBAAA;EAAA,QASA,YAAA;EAAA,QAoBA,qBAAA;EAAA,QAYA,yBAAA;EAAA,QAeA,yBAAA;EAAA,QAeA,yBAAA;EAAA,QAqBA,wBAAA;EAAA,QAiBA,sBAAA;EAAA,QAqBA,yBAAA;EAAA,QAQA,0BAAA;EAAA,QA2BA,gBAAA;EAAA,QA+BA,oBAAA;EAAA,QASA,iBAAA;EAAA,QA8HA,cAAA;EAAA,QAyBA,sBAAA;EAAA,QAsBA,oBAAA;EAAA,QAqBA,eAAA;EAAA,QA2BA,8BAAA;EAAA,QAUA,cAAA;EAAA,QAQA,8BAAA;EAAA,QAiBA,8BAAA;EAAA,QAsBA,oBAAA;EAAA,QAQA,sBAAA;EAAA,QAOA,yBAAA;EAAA,QAYA,yBAAA;EAAA,QAOA,sBAAA;EAAA,QAOA,sBAAA;EAAA,QAMA,yBAAA;EAAA,QA4BA,uBAAA;EAAA,QAwEA,yBAAA;EAAA,QAeA,4BAAA;EAAA,QAkDA,4BAAA;EAAA,QAYA,4BAAA;EAAA,QA0CA,4BAAA;EAAA,QAQA,gBAAA;EAAA,QAYA,kBAAA;EAAA,QAQA,YAAA;EAAA,QAOA,sBAAA;EAAA,QAiBA,uBAAA;EAAA,QAwBA,uBAAA;EAAA,QAkBA,oBAAA;EAAA,QAIA,gBAAA;EAAA,QAiBA,eAAA;EAAA,QAQA,YAAA;EAAA,QAQA,iBAAA;EAAA,QASA,gBAAA;EAAA,QAkBA,eAAA;EAAA,QAmBA,uBAAA;EAAA,QAwBA,gBAAA;EAAA,QAkCA,qBAAA;EAAA,QAMA,8BAAA;EAAA,QAgBA,yBAAA;EAAA,QAgBA,YAAA;EAAA,QAIA,kBAAA;EAAA,QAIA,iBAAA;EAAA,QAWA,uBAAA;AAAA;;;;;;;;iBA0CO,iBAAA,CAAkB,OAAA;AAAA,QAS1B,MAAA;EAAA,UACG,qBAAA;IACT,kBAAA,EAAoB,qBAAA;EAAA;EAAA,UAIX,GAAA;IAAA,UACC,iBAAA;MACT,kBAAA;QACC,IAAA;QACA,uBAAA;QACA,aAAA;QACA,cAAA,GAAiB,eAAA;QACjB,WAAA;QACA,YAAA;QACA,UAAA;QACA,OAAA,GAAU,aAAA;QACV,UAAA;QACA,OAAA;QACA,oBAAA;QACA,GAAA;QAAA,CACC,GAAA;MAAA;IAAA;EAAA;AAAA;AAAA;EAAA,UAQM,GAAA;IAAA,UACC,iBAAA;MACT,kBAAA;QACC,IAAA;QACA,uBAAA;QACA,aAAA;QACA,cAAA,GAAiB,eAAA;QACjB,WAAA;QACA,YAAA;QACA,UAAA;QACA,OAAA,GAAU,aAAA;QACV,UAAA;QACA,OAAA;QACA,oBAAA;QACA,GAAA;QAAA,CACC,GAAA;MAAA;IAAA;EAAA;AAAA"}