@cuadra-ai/uikit 0.1.31 → 0.3.0

package/README.md

@@ -113,7 +113,104 @@ function App() {
 }
 ```
 
-#### Customization Options
+#### New V2 Props (Recommended)
+
+The new V2 props API groups related options for better organization:
+
+```tsx
+import { CuadraChat } from '@cuadra-ai/uikit';
+
+function App() {
+  return (
+    <div style={{ height: '100vh' }}>
+      <CuadraChat
+        connection={{
+          baseUrl: "https://api.cuadra.ai",
+          sessionToken: "your-session-token",
+        }}
+        chat={{
+          mode: "multiChat",
+          modelMode: "fixed",
+          modelId: "your-model-id",
+          enableReasoning: true,
+        }}
+        ui={{
+          theme: "system",
+          welcomeTitle: "Welcome to Chat",
+          welcomeSubtitle: "How can I help you today?",
+          suggestions: [
+            { prompt: "What is Cuadra AI?" },
+            { prompt: "How do I get started?" }
+          ],
+        }}
+        callbacks={{
+          onChatCreated: (chatId) => console.log('Chat:', chatId),
+          onError: (error) => console.error(error),
+        }}
+        className="my-custom-class"
+      />
+    </div>
+  );
+}
+```
+
+#### With Context Provider (External Control)
+
+Use `CuadraChatProvider` to control the chat from anywhere in your component tree:
+
+```tsx
+import { CuadraChat, CuadraChatProvider, useCuadraChat } from '@cuadra-ai/uikit';
+
+function ChatControls() {
+  const { controls, isReady } = useCuadraChat();
+  
+  return (
+    <button 
+      onClick={() => controls?.sendMessage('Hello!')}
+      disabled={!isReady}
+    >
+      Send Hello
+    </button>
+  );
+}
+
+function App() {
+  return (
+    <CuadraChatProvider>
+      <ChatControls />
+      <CuadraChat
+        connection={{ baseUrl: "https://api.cuadra.ai" }}
+        chat={{ modelId: "your-model-id" }}
+      />
+    </CuadraChatProvider>
+  );
+}
+```
+
+#### With Error Boundary
+
+CuadraChat includes built-in error handling:
+
+```tsx
+import { CuadraChat } from '@cuadra-ai/uikit';
+
+function App() {
+  return (
+    <CuadraChat
+      connection={{ baseUrl: "https://api.cuadra.ai" }}
+      chat={{ modelId: "your-model-id" }}
+      errorFallback={(error, reset) => (
+        <div>
+          <p>Something went wrong: {error.message}</p>
+          <button onClick={reset}>Retry</button>
+        </div>
+      )}
+    />
+  );
+}
+```
+
+#### Legacy Props (Still Supported)
 
 ```tsx
 import { CuadraChat } from '@cuadra-ai/uikit';
@@ -231,7 +328,50 @@ For detailed widget API documentation, see the [full documentation](https://docs
 
 ## API Reference
 
-### CuadraChat Props
+### V2 Props (Recommended)
+
+| Prop Group | Prop | Type | Description |
+|------------|------|------|-------------|
+| `connection` | `baseUrl` | `string` | Cuadra API base URL |
+| | `proxyUrl` | `string` | Proxy URL for backend auth |
+| | `sessionToken` | `string \| null` | Bearer token |
+| `chat` | `mode` | `'singleChat' \| 'multiChat'` | Chat mode (default: `'multiChat'`) |
+| | `modelMode` | `'fixed' \| 'selector'` | Model selection mode (default: `'fixed'`) |
+| | `modelId` | `string` | Model ID from dashboard |
+| | `systemPrompt` | `string` | System prompt |
+| | `ephemeral` | `boolean` | Auto-delete chats on close |
+| | `enableReasoning` | `boolean` | Enable thinking output |
+| | `enableAttachments` | `boolean` | Enable file attachments |
+| `ui` | `theme` | `'light' \| 'dark' \| 'system'` | Theme mode (default: `'system'`) |
+| | `showThemeToggle` | `boolean` | Show toggle (default: `true`) |
+| | `welcomeTitle` | `string` | Welcome screen title |
+| | `welcomeSubtitle` | `string` | Welcome screen subtitle |
+| | `suggestions` | `Array<Suggestion>` | Welcome screen suggestions |
+| | `inputPlaceholder` | `string` | Input field placeholder |
+| `callbacks` | `onChatCreated` | `(id: string) => void` | Called when chat created |
+| | `onError` | `(error: Error) => void` | Error callback |
+| | `onModelChange` | `(id: string) => void` | Model change callback |
+| `errorFallback` | | `ReactNode \| Function` | Custom error UI |
+| `className` | | `string` | Container CSS class |
+
+### Exported Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useCuadraChat()` | Access chat controls from context (requires `CuadraChatProvider`) |
+| `useCuadraChatOptional()` | Same as above, returns null if no provider |
+
+### Exported Utilities
+
+| Utility | Description |
+|---------|-------------|
+| `sanitizeSystemPrompt()` | Remove injection patterns from prompts |
+| `isValidUrl()` | Validate URL uses http/https |
+| `validateBaseUrl()` | Validate API base URL with details |
+| `generateSecureUUID()` | Crypto-secure UUID generation |
+| `createAttachmentAdapter()` | Create file attachment adapter with validation |
+
+### Legacy Props (Still Supported)
 
 | Prop | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|

package/dist/adapters/attachmentAdapter.d.ts

@@ -1,7 +1,66 @@
-import type { AttachmentAdapter } from '@assistant-ui/react';
+import type { AttachmentAdapter, PendingAttachment } from '@assistant-ui/react';
 /**
- * Simple attachment adapter that handles file attachments
- * Files are kept as File objects and sent with messages
+ * Attachment validation configuration
  */
-export declare function createAttachmentAdapter(): AttachmentAdapter;
+export interface AttachmentValidationConfig {
+    /**
+     * Maximum file size in bytes
+     * @default 10 * 1024 * 1024 (10MB)
+     */
+    maxFileSizeBytes?: number;
+    /**
+     * Allowed MIME types (e.g., ['image/png', 'image/jpeg'])
+     * If not provided, defaults to common document and image types
+     */
+    allowedMimeTypes?: string[];
+    /**
+     * Allowed file extensions (e.g., ['.pdf', '.docx'])
+     * If not provided, defaults to common document and image extensions
+     */
+    allowedExtensions?: string[];
+    /**
+     * Maximum number of attachments per message
+     * @default 5
+     */
+    maxAttachments?: number;
+    /**
+     * Whether to validate file content type matches extension
+     * @default true
+     */
+    validateContentType?: boolean;
+}
+/**
+ * Attachment validation error
+ */
+export declare class AttachmentValidationError extends Error {
+    readonly code: 'FILE_TOO_LARGE' | 'INVALID_TYPE' | 'TOO_MANY_FILES' | 'VALIDATION_FAILED';
+    readonly file?: File | undefined;
+    constructor(message: string, code: 'FILE_TOO_LARGE' | 'INVALID_TYPE' | 'TOO_MANY_FILES' | 'VALIDATION_FAILED', file?: File | undefined);
+}
+/**
+ * Attachment adapter options
+ */
+export interface AttachmentAdapterOptions {
+    /**
+     * Validation configuration
+     */
+    validation?: AttachmentValidationConfig;
+    /**
+     * Callback when validation fails
+     * Allows custom error handling (e.g., show toast notification)
+     */
+    onValidationError?: (error: AttachmentValidationError) => void;
+    /**
+     * Callback when attachment is added
+     */
+    onAttachmentAdded?: (attachment: PendingAttachment) => void;
+    /**
+     * Callback when attachment is removed
+     */
+    onAttachmentRemoved?: (attachmentId: string) => void;
+}
+/**
+ * Create an attachment adapter with enhanced validation
+ */
+export declare function createAttachmentAdapter(options?: AttachmentAdapterOptions): AttachmentAdapter;
 //# sourceMappingURL=attachmentAdapter.d.ts.map

package/dist/adapters/attachmentAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"attachmentAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/attachmentAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,qBAAqB,CAAC;AAE7B;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,CAoE3D"}
+{"version":3,"file":"attachmentAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/attachmentAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EAEjB,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE5B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;GAEG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;aAGhC,IAAI,EAAE,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,GAAG,mBAAmB;aAChF,IAAI,CAAC,EAAE,IAAI;gBAF3B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,gBAAgB,GAAG,cAAc,GAAG,gBAAgB,GAAG,mBAAmB,EAChF,IAAI,CAAC,EAAE,IAAI,YAAA;CAK9B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,UAAU,CAAC,EAAE,0BAA0B,CAAC;IAExC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,yBAAyB,KAAK,IAAI,CAAC;IAE/D;;OAEG;IACH,iBAAiB,CAAC,EAAE,CAAC,UAAU,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAE5D;;OAEG;IACH,mBAAmB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;CACtD;AAiHD;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,CAwJnB"}

package/dist/components/CuadraChat.d.ts

@@ -1,5 +1,4 @@
-import type { CuadraRuntimeProviderProps } from './CuadraRuntimeProvider';
-import type { CuadraTheme } from '../types/theme';
+import { type CuadraChatProps } from '../types/props';
 /**
  * Handle for controlling CuadraChat externally
  */
@@ -17,121 +16,68 @@ export interface CuadraChatHandle {
     /** Clear the current chat and start fresh */
     clearChat: () => void;
 }
-export interface CuadraChatProps extends Omit<CuadraRuntimeProviderProps, 'children' | 'isProxyMode'> {
-    /** Proxy URL for backend-handled authentication (e.g., '/api/chat' or 'http://localhost:3000') */
-    proxyUrl?: string;
-    /** Container className for styling */
-    className?: string;
-    /** Show theme toggle button */
-    showThemeToggle?: boolean;
-    /** Initial theme ('light' | 'dark' | 'system') */
-    theme?: 'light' | 'dark' | 'system';
-    /** Custom theme colors to override defaults */
-    customTheme?: CuadraTheme;
-    /** Language/locale for i18n (e.g., 'en', 'es', 'fr') */
-    language?: string;
-    /** Welcome screen title */
-    welcomeTitle?: string;
-    /** Welcome screen subtitle */
-    welcomeSubtitle?: string;
-    /** Extra top padding for thread viewport (e.g., '1rem', '2rem') */
-    extraTopPadding?: string;
-    /** Suggestions to show in welcome screen (with optional pre-made responses) */
-    suggestions?: Array<{
-        /** Suggestion prompt text */
-        prompt: string;
-        /** Pre-made response (optional) - if provided, response appears instantly with simulated streaming */
-        response?: string;
-        /** Delay before showing response in ms (overrides preMadeResponseDelay) */
-        responseDelay?: number;
-    }>;
-    /** Placeholder text for the input field */
-    inputPlaceholder?: string;
-    /** Default delay before pre-made responses in ms (default: 1000) */
-    preMadeResponseDelay?: number;
-    /** Speed of simulated streaming in ms per word (default: 50) */
-    streamingSpeed?: number;
-    /** Called when a user message is sent */
-    onUserMessage?: () => void;
-    /** Called when logout button is clicked */
-    onLogout?: () => void;
-    /** Enable file attachments in the chat input */
-    enableAttachments?: boolean;
-    /**
-     * Initial message to send automatically when chat loads
-     * (triggers normal API call after a short delay)
-     */
-    initialMessage?: string;
-    /**
-     * Initial pre-made Q&A to display when chat loads
-     * (instant display with simulated streaming, no API call)
-     */
-    initialPreMadeQA?: {
-        question: string;
-        answer: string;
-    };
-    /**
-     * Interceptor called before each outgoing API request.
-     * Return `true` to allow the request, `false` to block it.
-     * Can be async (e.g., to show a login modal).
-     * If not provided, all requests are allowed.
-     *
-     * @example
-     * // Block requests and show login modal
-     * onBeforeRequest={async () => {
-     *   if (!isLoggedIn) {
-     *     showLoginModal();
-     *     return false; // Block the request
-     *   }
-     *   return true; // Allow the request
-     * }}
-     */
-    onBeforeRequest?: () => boolean | Promise<boolean>;
-    /**
-     * Mock response to show when onBeforeRequest returns false.
-     * If set, instead of throwing an error, this message will be streamed as a response.
-     * Can be a string or a function that returns a string (called each time a request is blocked).
-     * Useful for showing helpful messages like "Complete setup before chatting".
-     *
-     * @example
-     * // Show friendly message when chat is not ready (static)
-     * mockResponseOnBlocked="Complete the setup on the left before we can start chatting!"
-     *
-     * @example
-     * // Show different messages each time (dynamic)
-     * const messages = ["First message", "Second message", "Third message"];
-     * let count = 0;
-     * mockResponseOnBlocked={() => messages[count++ % messages.length]}
-     */
-    mockResponseOnBlocked?: string | (() => string);
-}
+export type { CuadraChatProps, CuadraChatPropsV2, CuadraChatPropsLegacy, CuadraConnectionConfig, CuadraChatConfig, CuadraUIConfig, CuadraCallbacks, CuadraInterceptors, CuadraPreMadeConfig, CuadraInitialState, CuadraSuggestion, } from '../types/props';
 /**
  * All-in-one Cuadra Chat component
  *
- * This component uses the widget implementation internally, ensuring
- * consistent styling and behavior with the widget version.
+ * Supports both V2 grouped props (recommended) and legacy flat props.
  *
- * Styles are automatically bundled and injected. Users can optionally
- * import '@cuadra-ai/uikit/styles' if they need explicit control.
+ * ## V2 Props (Recommended)
  *
- * @example
- * // Basic usage
- * <CuadraChat baseUrl="https://api.cuadra.ai" modelId="model-123" />
+ * ```tsx
+ * <CuadraChat
+ *   connection={{
+ *     baseUrl: 'https://api.cuadra.ai',
+ *     sessionToken: 'your-token',
+ *   }}
+ *   chat={{
+ *     mode: 'multiChat',
+ *     modelId: 'your-model-id',
+ *     enableReasoning: true,
+ *   }}
+ *   ui={{
+ *     theme: 'dark',
+ *     welcomeTitle: 'Welcome!',
+ *     suggestions: [{ prompt: 'What can you do?' }],
+ *   }}
+ *   callbacks={{
+ *     onChatCreated: (id) => console.log('Chat:', id),
+ *   }}
+ * />
+ * ```
  *
- * @example
- * // With ref for external control
- * const chatRef = useRef<CuadraChatHandle>(null);
- * <CuadraChat ref={chatRef} ... />
- * chatRef.current?.sendMessage("Hello!");
+ * ## Legacy Props (Still Supported)
  *
- * @example
- * // With pre-made suggestions
+ * ```tsx
  * <CuadraChat
- *   suggestions={[
- *     { prompt: "What is Cuadra?", response: "Cuadra AI is..." },
- *     { prompt: "How do I start?" } // No response = normal API call
- *   ]}
+ *   baseUrl="https://api.cuadra.ai"
+ *   sessionToken="your-token"
+ *   mode="multiChat"
+ *   modelId="your-model-id"
+ *   enableReasoning={true}
+ *   theme="dark"
+ *   welcomeTitle="Welcome!"
  * />
+ * ```
+ *
+ * ## External Control
+ *
+ * Use `CuadraChatProvider` and `useCuadraChat()` hook for context-based control:
+ *
+ * ```tsx
+ * <CuadraChatProvider>
+ *   <CuadraChat connection={{ baseUrl: '...' }} />
+ *   <MyControlsComponent /> {/* Can use useCuadraChat() *\/}
+ * </CuadraChatProvider>
+ * ```
+ *
+ * Or use a ref for direct control:
+ *
+ * ```tsx
+ * const chatRef = useRef<CuadraChatHandle>(null);
+ * <CuadraChat ref={chatRef} connection={{ baseUrl: '...' }} />
+ * chatRef.current?.sendMessage('Hello!');
+ * ```
  */
 export declare const CuadraChat: import("react").ForwardRefExoticComponent<CuadraChatProps & import("react").RefAttributes<CuadraChatHandle>>;
 //# sourceMappingURL=CuadraChat.d.ts.map

package/dist/components/CuadraChat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CuadraChat.d.ts","sourceRoot":"","sources":["../../src/components/CuadraChat.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAGlD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;OAGG;IACH,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACjH,6CAA6C;IAC7C,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAGD,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,0BAA0B,EAAE,UAAU,GAAG,aAAa,CAAC;IACnG,kGAAkG;IAClG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+BAA+B;IAC/B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kDAAkD;IAClD,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IACpC,+CAA+C;IAC/C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2BAA2B;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,6BAA6B;QAC7B,MAAM,EAAE,MAAM,CAAC;QACf,sGAAsG;QACtG,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,2EAA2E;QAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC,CAAC;IACH,2CAA2C;IAC3C,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,gBAAgB,CAAC,EAAE;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IACF;;;;;;;;;;;;;;;OAeG;IACH,eAAe,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnD;;;;;;;;;;;;;;;OAeG;IACH,qBAAqB,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;CACjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,UAAU,8GA8EtB,CAAC"}
+{"version":3,"file":"CuadraChat.d.ts","sourceRoot":"","sources":["../../src/components/CuadraChat.tsx"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,eAAe,EAA6D,MAAM,gBAAgB,CAAC;AAEjH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;OAGG;IACH,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACjH,6CAA6C;IAC7C,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAGD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAkHxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,eAAO,MAAM,UAAU,8GAyBtB,CAAC"}

package/dist/components/CuadraChatContext.d.ts

@@ -0,0 +1,141 @@
+import { type ReactNode, type RefObject } from 'react';
+import type { CuadraChatHandle } from './CuadraChat';
+/**
+ * Context for accessing CuadraChat controls from any child component
+ *
+ * This provides a React-idiomatic way to control the chat component
+ * from anywhere in your component tree without prop drilling.
+ *
+ * @example Using in a parent component
+ * ```tsx
+ * import { CuadraChat, CuadraChatProvider, useCuadraChat } from '@cuadra-ai/uikit';
+ *
+ * function App() {
+ *   return (
+ *     <CuadraChatProvider>
+ *       <CuadraChat connection={{ baseUrl: '...' }} />
+ *       <MyCustomControls />
+ *     </CuadraChatProvider>
+ *   );
+ * }
+ *
+ * function MyCustomControls() {
+ *   const { controls } = useCuadraChat();
+ *
+ *   return (
+ *     <button onClick={() => controls?.sendMessage('Hello!')}>
+ *       Send Hello
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export interface CuadraChatContextValue {
+    /**
+     * Reference to the CuadraChat controls
+     * May be null before the CuadraChat component mounts
+     */
+    controls: CuadraChatHandle | null;
+    /**
+     * Internal: Reference setter for CuadraChat to register itself
+     * @internal
+     */
+    registerControls: (controls: CuadraChatHandle) => void;
+    /**
+     * Internal: Reference clearer for CuadraChat to unregister on unmount
+     * @internal
+     */
+    unregisterControls: () => void;
+}
+/**
+ * Context for CuadraChat controls
+ *
+ * Default value is null - use CuadraChatProvider to provide an actual value.
+ * Consumers can check if context is null to detect missing provider.
+ */
+export declare const CuadraChatContext: import("react").Context<CuadraChatContextValue | null>;
+/**
+ * Hook to access CuadraChat controls from any child component
+ *
+ * @returns Object containing `controls` (CuadraChatHandle | null) and `isReady` boolean
+ * @throws Error if used outside of CuadraChatProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { controls, isReady } = useCuadraChat();
+ *
+ *   if (!isReady) {
+ *     return <span>Chat is loading...</span>;
+ *   }
+ *
+ *   return (
+ *     <button onClick={() => controls.sendMessage('Hi!')}>
+ *       Send Message
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCuadraChat(): {
+    controls: CuadraChatHandle | null;
+    isReady: boolean;
+};
+/**
+ * Hook to optionally access CuadraChat controls
+ *
+ * Unlike useCuadraChat, this doesn't throw if the provider is missing.
+ * Returns null if CuadraChatProvider is not present.
+ *
+ * @returns Object with controls and isReady, or null if no provider
+ *
+ * @example
+ * ```tsx
+ * function OptionalChatControl() {
+ *   const chat = useCuadraChatOptional();
+ *
+ *   if (!chat) {
+ *     // No CuadraChatProvider in tree - gracefully handle
+ *     return null;
+ *   }
+ *
+ *   return chat.isReady ? (
+ *     <button onClick={() => chat.controls?.sendMessage('Hi!')}>Send</button>
+ *   ) : null;
+ * }
+ * ```
+ */
+export declare function useCuadraChatOptional(): {
+    controls: CuadraChatHandle | null;
+    isReady: boolean;
+} | null;
+/**
+ * Provider component for CuadraChat context
+ *
+ * Wrap your component tree with this to enable useCuadraChat hook
+ * access from any descendant component.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <CuadraChatProvider>
+ *       <Header />
+ *       <CuadraChat connection={{ baseUrl: '...' }} />
+ *       <Sidebar />
+ *     </CuadraChatProvider>
+ *   );
+ * }
+ * ```
+ */
+export interface CuadraChatProviderProps {
+    children: ReactNode;
+}
+export declare function CuadraChatProvider({ children }: CuadraChatProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Helper to create a ref object that syncs with context
+ * Used internally by CuadraChat to register itself with the context
+ * @internal
+ */
+export declare function createContextualRef(registerControls: (controls: CuadraChatHandle) => void, unregisterControls: () => void): RefObject<CuadraChatHandle | null>;
+//# sourceMappingURL=CuadraChatContext.d.ts.map

package/dist/components/CuadraChatContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CuadraChatContext.d.ts","sourceRoot":"","sources":["../../src/components/CuadraChatContext.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,SAAS,EAAqC,MAAM,OAAO,CAAC;AACzG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAElC;;;OAGG;IACH,gBAAgB,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAEvD;;;OAGG;IACH,kBAAkB,EAAE,MAAM,IAAI,CAAC;CAChC;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,wDAAqD,CAAC;AAIpF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,IAAI;IAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAcvF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,IAAI;IAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAWtG;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE,uBAAuB,2CAsBvE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,EACtD,kBAAkB,EAAE,MAAM,IAAI,GAC7B,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAgBpC"}

package/dist/components/ErrorBoundary.d.ts

@@ -0,0 +1,79 @@
+import { Component, type ErrorInfo, type ReactNode } from 'react';
+/**
+ * Props for CuadraErrorBoundary
+ */
+export interface CuadraErrorBoundaryProps {
+    /** Child components to wrap */
+    children: ReactNode;
+    /**
+     * Custom fallback UI or render function
+     * If not provided, DefaultErrorFallback is used
+     */
+    fallback?: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+    /**
+     * Callback when an error is caught
+     * Use for logging, analytics, etc.
+     */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * Error boundary component for CuadraChat
+ *
+ * Catches JavaScript errors in child component tree and displays
+ * a fallback UI instead of crashing the entire application.
+ *
+ * @example Basic usage (uses default fallback)
+ * ```tsx
+ * <CuadraErrorBoundary>
+ *   <CuadraChat {...props} />
+ * </CuadraErrorBoundary>
+ * ```
+ *
+ * @example With custom fallback
+ * ```tsx
+ * <CuadraErrorBoundary
+ *   fallback={<div>Oops! Something went wrong.</div>}
+ * >
+ *   <CuadraChat {...props} />
+ * </CuadraErrorBoundary>
+ * ```
+ *
+ * @example With render function fallback
+ * ```tsx
+ * <CuadraErrorBoundary
+ *   fallback={(error, reset) => (
+ *     <div>
+ *       <p>Error: {error.message}</p>
+ *       <button onClick={reset}>Retry</button>
+ *     </div>
+ *   )}
+ *   onError={(error, info) => {
+ *     console.error('Chat error:', error);
+ *     analytics.track('chat_error', { message: error.message });
+ *   }}
+ * >
+ *   <CuadraChat {...props} />
+ * </CuadraErrorBoundary>
+ * ```
+ */
+export declare class CuadraErrorBoundary extends Component<CuadraErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: CuadraErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    /**
+     * Reset the error state and attempt to re-render children
+     */
+    reset: () => void;
+    render(): ReactNode;
+}
+/**
+ * Hook-friendly wrapper for error boundary
+ * Use when you need to reset error boundary from a child component
+ */
+export declare function withErrorBoundary<P extends object>(WrappedComponent: React.ComponentType<P>, errorBoundaryProps?: Omit<CuadraErrorBoundaryProps, 'children'>): React.FC<P>;
+export {};
+//# sourceMappingURL=ErrorBoundary.d.ts.map

package/dist/components/ErrorBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorBoundary.d.ts","sourceRoot":"","sources":["../../src/components/ErrorBoundary.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,+BAA+B;IAC/B,QAAQ,EAAE,SAAS,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,IAAI,KAAK,SAAS,CAAC,CAAC;IACxE;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,KAAK,IAAI,CAAC;CACxD;AAED,UAAU,kBAAkB;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAiDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,mBAAoB,SAAQ,SAAS,CAAC,wBAAwB,EAAE,kBAAkB,CAAC;gBAClF,KAAK,EAAE,wBAAwB;IAK3C,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,KAAK,GAAG,kBAAkB;IAIjE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,IAAI;IAI3D;;OAEG;IACH,KAAK,QAAO,IAAI,CAEd;IAEF,MAAM,IAAI,SAAS;CAqBpB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAChD,gBAAgB,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,EACxC,kBAAkB,CAAC,EAAE,IAAI,CAAC,wBAAwB,EAAE,UAAU,CAAC,GAC9D,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAUb"}