@timbal-ai/timbal-react 0.2.0 → 0.2.2

package/README.md

@@ -1,6 +1,6 @@
 # @timbal-ai/timbal-react
 
-React components and runtime for building Timbal chat UIs. Provides a streaming chat interface that connects to Timbal workforce agents out of the box.
+React components and runtime for building Timbal chat UIs. Drop in a single component to get a fully-featured streaming chat interface connected to a Timbal workforce agent.
 
 ## Installation
 
@@ -10,15 +10,15 @@ npm install @timbal-ai/timbal-react
 bun add @timbal-ai/timbal-react
 ```
 
-### Peer dependencies
+**Peer dependencies:**
 
 ```bash
 npm install react react-dom @assistant-ui/react @timbal-ai/timbal-sdk
 ```
 
-### Required: Tailwind setup
+### Tailwind setup
 
-The package ships pre-built class names that Tailwind must scan. Add this `@source` line to your CSS entry file — **without it the components will be unstyled**:
+The package ships pre-built Tailwind class names. Add this `@source` line to your CSS entry file — **without it the components will be unstyled**:
 
 ```css
 /* src/index.css */
@@ -29,7 +29,7 @@ The package ships pre-built class names that Tailwind must scan. Add this `@sour
 
 > Adjust the path if your CSS file lives at a different depth relative to `node_modules`.
 
-### Required: CSS imports
+### CSS imports
 
 Import these stylesheets once in your app entry:
 
@@ -41,11 +41,11 @@ import "katex/dist/katex.min.css";
 
 ---
 
-## Usage
+## Quick start
 
-### One-liner
+### Basic usage
 
-The simplest way to embed a chat UI. `TimbalChat` handles the runtime and the thread in one component:
+`TimbalChat` is a single component that handles everything — runtime, streaming, messages, and the composer:
 
 ```tsx
 import { TimbalChat } from "@timbal-ai/timbal-react";
@@ -59,7 +59,9 @@ export default function App() {
 }
 ```
 
-#### With welcome screen and suggestions
+> `TimbalChat` requires a fixed height parent. Use `height: "100vh"` or `flex-1 min-h-0` depending on your layout.
+
+### Welcome screen and suggestions
 
 ```tsx
 <TimbalChat
@@ -76,7 +78,7 @@ export default function App() {
 />
 ```
 
-#### With a custom placeholder and width
+### Placeholder and width
 
 ```tsx
 <TimbalChat
@@ -87,9 +89,9 @@ export default function App() {
 />
 ```
 
-#### Switching agents dynamically
+### Switching agents dynamically
 
-Use `key` to reset the chat when the workforce changes:
+Pass `key` to fully reset the chat when the workforce changes:
 
 ```tsx
 const [workforceId, setWorkforceId] = useState("agent-a");
@@ -104,9 +106,9 @@ const [workforceId, setWorkforceId] = useState("agent-a");
 
 ---
 
-### Compose manually
+## Splitting the runtime and UI
 
-Use `TimbalRuntimeProvider` + `Thread` separately when you need to place the runtime above the chat UI — for example, to build a custom header that reads or controls chat state:
+`TimbalChat` is a convenience wrapper around `TimbalRuntimeProvider` + `Thread`. Use them separately when you need to place the runtime above the chat — for example, to build a custom header that reads or controls chat state:
 
 ```tsx
 import { TimbalRuntimeProvider, Thread } from "@timbal-ai/timbal-react";
@@ -126,7 +128,7 @@ export default function App() {
 }
 ```
 
-#### With a custom API base URL
+### Custom API base URL
 
 Useful when your API is mounted at a subpath (e.g. behind a reverse proxy):
 
@@ -136,20 +138,15 @@ Useful when your API is mounted at a subpath (e.g. behind a reverse proxy):
 </TimbalRuntimeProvider>
 ```
 
-#### With a custom fetch function
+### Custom fetch function
 
 Pass your own `fetch` to add headers, inject tokens, or proxy requests:
 
 ```tsx
-import { TimbalRuntimeProvider, Thread } from "@timbal-ai/timbal-react";
-
 const myFetch: typeof fetch = (url, options) => {
   return fetch(url, {
     ...options,
-    headers: {
-      ...options?.headers,
-      "X-My-Header": "value",
-    },
+    headers: { ...options?.headers, "X-My-Header": "value" },
   });
 };
 
@@ -160,30 +157,168 @@ const myFetch: typeof fetch = (url, options) => {
 
 ---
 
-### `TimbalChat` / `Thread` props
+## Customizing the UI
+
+Use the `components` prop on `TimbalChat` or `Thread` to replace any part of the interface while keeping everything else as the default.
+
+### Available slots
+
+| Slot | Props forwarded | Default |
+|---|---|---|
+| `UserMessage` | none | built-in user bubble |
+| `AssistantMessage` | none | built-in assistant bubble |
+| `EditComposer` | none | built-in inline edit composer |
+| `Composer` | `placeholder` | built-in composer bar |
+| `Welcome` | `config`, `suggestions` | built-in welcome screen |
+| `ScrollToBottom` | none | built-in scroll button |
+
+Custom slot components read their data via hooks — no props are passed automatically except where noted above.
+
+### Custom user message
+
+```tsx
+import { TimbalChat, MessagePrimitive } from "@timbal-ai/timbal-react";
+
+const CompactUserMessage = () => (
+  <MessagePrimitive.Root className="flex justify-end px-4 py-2">
+    <div className="bg-primary text-primary-foreground rounded-2xl px-4 py-2 text-sm max-w-[75%]">
+      <MessagePrimitive.Parts />
+    </div>
+  </MessagePrimitive.Root>
+);
+
+<TimbalChat workforceId="..." components={{ UserMessage: CompactUserMessage }} />
+```
+
+### Custom composer
+
+The `Composer` slot receives `placeholder` from the `composerPlaceholder` prop:
+
+```tsx
+import { TimbalChat, ComposerPrimitive } from "@timbal-ai/timbal-react";
+
+const MinimalComposer = ({ placeholder }: { placeholder?: string }) => (
+  <ComposerPrimitive.Root className="flex items-center gap-2 border rounded-full px-4 py-2">
+    <ComposerPrimitive.Input
+      placeholder={placeholder ?? "Type here..."}
+      className="flex-1 bg-transparent text-sm outline-none"
+      rows={1}
+    />
+    <ComposerPrimitive.Send className="text-primary font-medium text-sm">
+      Send
+    </ComposerPrimitive.Send>
+  </ComposerPrimitive.Root>
+);
+
+<TimbalChat workforceId="..." components={{ Composer: MinimalComposer }} />
+```
+
+### Custom welcome screen
+
+The `Welcome` slot is always mounted and controls its own visibility. Use `useThread` to replicate the default "show only when the thread is empty" behaviour:
+
+```tsx
+import { TimbalChat, useThread, useThreadRuntime, type ThreadWelcomeProps } from "@timbal-ai/timbal-react";
+
+const BrandedWelcome = ({ suggestions }: ThreadWelcomeProps) => {
+  const isEmpty = useThread((s) => s.isEmpty);
+  const runtime = useThreadRuntime();
+  if (!isEmpty) return null;
+  return (
+    <div className="flex flex-col items-center justify-center h-full gap-4">
+      <img src="/logo.svg" className="h-12" />
+      <h2 className="text-xl font-semibold">Welcome to Acme AI</h2>
+      <div className="flex gap-2 flex-wrap justify-center">
+        {suggestions?.map((s) => (
+          <button
+            key={s.title}
+            onClick={() => runtime.append({ role: "user", content: [{ type: "text", text: s.title }] })}
+            className="border rounded-full px-4 py-1.5 text-sm hover:bg-muted"
+          >
+            {s.title}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+<TimbalChat
+  workforceId="..."
+  suggestions={[{ title: "Get started" }, { title: "Show me an example" }]}
+  components={{ Welcome: BrandedWelcome }}
+/>
+```
+
+### Mixing slots
+
+Override any combination — slots are independent of each other:
+
+```tsx
+<TimbalChat
+  workforceId="..."
+  components={{
+    UserMessage: CompactUserMessage,
+    Composer: MinimalComposer,
+  }}
+/>
+```
+
+### Hooks and primitives
+
+These are re-exported from `@assistant-ui/react` for use inside custom slot components:
+
+| Export | Use inside |
+|---|---|
+| `ThreadPrimitive` | Any slot |
+| `MessagePrimitive` | `UserMessage`, `AssistantMessage`, `EditComposer` |
+| `ComposerPrimitive` | `Composer`, `EditComposer` |
+| `ActionBarPrimitive` | `UserMessage`, `AssistantMessage` |
+| `useThread` | Any slot — subscribe to thread state (e.g. `isRunning`, `isEmpty`) |
+| `useThreadRuntime` | Any slot — call actions (e.g. `runtime.append(...)`) |
+| `useMessageRuntime` | `UserMessage`, `AssistantMessage` — edit, reload, branch |
+| `useComposerRuntime` | `Composer`, `EditComposer` — access composer state |
+
+---
+
+## API reference
+
+### `TimbalChat` props
+
+`TimbalChat` accepts all `TimbalRuntimeProvider` props plus all `Thread` props.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `workforceId` | `string` | **required** | ID of the workforce to stream from |
+| `baseUrl` | `string` | `"/api"` | Base URL for API calls. Posts to `{baseUrl}/workforce/{workforceId}/stream` |
+| `fetch` | `(url, options?) => Promise<Response>` | `authFetch` | Custom fetch. Defaults to the built-in auth-aware fetch (Bearer token + auto-refresh) |
 | `welcome.heading` | `string` | `"How can I help you today?"` | Welcome screen heading |
 | `welcome.subheading` | `string` | `"Send a message to start a conversation."` | Welcome screen subheading |
 | `suggestions` | `{ title: string; description?: string }[]` | — | Suggestion chips on the welcome screen |
 | `composerPlaceholder` | `string` | `"Send a message..."` | Composer input placeholder |
+| `components` | `ThreadComponents` | — | Override individual UI slots |
 | `maxWidth` | `string` | `"44rem"` | Max width of the message column |
 | `className` | `string` | — | Extra classes on the root element |
 
+### `Thread` props
+
+Same as `TimbalChat` minus `workforceId`, `baseUrl`, and `fetch` (those live on `TimbalRuntimeProvider`).
+
 ### `TimbalRuntimeProvider` props
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `workforceId` | `string` | — | ID of the workforce to stream from |
-| `baseUrl` | `string` | `"/api"` | Base URL for API calls. Posts to `{baseUrl}/workforce/{workforceId}/stream` |
-| `fetch` | `(url, options?) => Promise<Response>` | `authFetch` | Custom fetch function. Defaults to the built-in auth-aware fetch (Bearer token + auto-refresh) |
+| `workforceId` | `string` | **required** | ID of the workforce to stream from |
+| `baseUrl` | `string` | `"/api"` | Base URL for API calls |
+| `fetch` | `(url, options?) => Promise<Response>` | `authFetch` | Custom fetch function |
 
 ---
 
 ## Auth
 
-The package includes a session/auth system backed by localStorage tokens. The API is expected to expose `/api/auth/login`, `/api/auth/logout`, and `/api/auth/refresh`.
+The package includes an optional session/auth system backed by localStorage tokens. The API is expected to expose `/api/auth/login`, `/api/auth/logout`, and `/api/auth/refresh`.
+
+Auth is **opt-in** — it only activates when `VITE_TIMBAL_PROJECT_ID` is set in your environment.
 
 ### Setup
 
@@ -195,7 +330,6 @@ import { SessionProvider, AuthGuard, TooltipProvider } from "@timbal-ai/timbal-r
 import { BrowserRouter, Routes, Route } from "react-router-dom";
 import Home from "./pages/Home";
 
-// Auth is opt-in — only active when VITE_TIMBAL_PROJECT_ID is set
 const isAuthEnabled = !!import.meta.env.VITE_TIMBAL_PROJECT_ID;
 
 export default function App() {
@@ -215,20 +349,7 @@ export default function App() {
 }
 ```
 
-When `enabled` is `false` (no project ID configured), both `SessionProvider` and `AuthGuard` are transparent — no redirects, no API calls.
-
-### `SessionProvider` props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `enabled` | `boolean` | `true` | When `false`, session is always `null` and no API calls are made |
-
-### `AuthGuard` props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `requireAuth` | `boolean` | `false` | Redirect to login if not authenticated |
-| `enabled` | `boolean` | `true` | When `false`, renders children unconditionally |
+When `enabled` is `false`, both `SessionProvider` and `AuthGuard` are transparent — no redirects, no API calls.
 
 ### `useSession` hook
 
@@ -239,9 +360,7 @@ import { useSession } from "@timbal-ai/timbal-react";
 
 function Header() {
   const { user, isAuthenticated, loading, logout } = useSession();
-
   if (loading) return null;
-
   return (
     <header>
       {isAuthenticated ? (
@@ -259,25 +378,30 @@ function Header() {
 
 ### `authFetch`
 
-A drop-in replacement for `fetch` that attaches the Bearer token from localStorage and auto-refreshes on 401:
+A drop-in replacement for `fetch` that attaches the Bearer token from localStorage and auto-refreshes on 401. It's also the default `fetch` used by `TimbalRuntimeProvider`, so you only need to import it directly for your own API calls (e.g. loading workforce lists):
 
 ```tsx
 import { authFetch } from "@timbal-ai/timbal-react";
 
-// Fetch a list of workforce agents
 const res = await authFetch("/api/workforce");
 if (res.ok) {
   const agents = await res.json();
 }
 ```
 
-It's also the default `fetch` used by `TimbalRuntimeProvider` — you only need to import it directly for your own API calls (e.g. loading workforce lists, metadata, etc.).
+### Auth prop reference
+
+| Component | Prop | Type | Default | Description |
+|---|---|---|---|---|
+| `SessionProvider` | `enabled` | `boolean` | `true` | When `false`, session is always `null` and no API calls are made |
+| `AuthGuard` | `requireAuth` | `boolean` | `false` | Redirect to login if not authenticated |
+| `AuthGuard` | `enabled` | `boolean` | `true` | When `false`, renders children unconditionally |
 
 ---
 
-## Components
+## Other exports
 
-All components accept `className` for Tailwind overrides.
+### Components
 
 | Export | Description |
 |---|---|
@@ -306,12 +430,7 @@ A complete page with agent switching, auth, and a custom header:
 // src/pages/Home.tsx
 import { useEffect, useState } from "react";
 import type { WorkforceItem } from "@timbal-ai/timbal-sdk";
-import {
-  TimbalChat,
-  Button,
-  authFetch,
-  useSession,
-} from "@timbal-ai/timbal-react";
+import { TimbalChat, Button, authFetch, useSession } from "@timbal-ai/timbal-react";
 import { LogOut } from "lucide-react";
 
 const isAuthEnabled = !!import.meta.env.VITE_TIMBAL_PROJECT_ID;
@@ -368,7 +487,6 @@ export default function Home() {
 Install via a local path reference:
 
 ```json
-// package.json
 {
   "dependencies": {
     "@timbal-ai/timbal-react": "file:../../timbal-react"
@@ -378,7 +496,7 @@ Install via a local path reference:
 
 Adjust the relative path to where `timbal-react` lives on your machine.
 
-After editing source files, rebuild the package:
+After editing source files, rebuild:
 
 ```bash
 cd timbal-react

package/dist/index.cjs

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ActionBarPrimitive: () => import_react13.ActionBarPrimitive,
   AuthGuard: () => AuthGuard,
   Avatar: () => Avatar,
   AvatarFallback: () => AvatarFallback,
@@ -37,6 +38,7 @@ __export(index_exports, {
   Button: () => Button,
   ComposerAddAttachment: () => ComposerAddAttachment,
   ComposerAttachments: () => ComposerAttachments,
+  ComposerPrimitive: () => import_react13.ComposerPrimitive,
   Dialog: () => Dialog,
   DialogClose: () => DialogClose,
   DialogContent: () => DialogContent,
@@ -45,10 +47,12 @@ __export(index_exports, {
   DialogTitle: () => DialogTitle,
   DialogTrigger: () => DialogTrigger,
   MarkdownText: () => MarkdownText,
+  MessagePrimitive: () => import_react13.MessagePrimitive,
   SessionProvider: () => SessionProvider,
   Shimmer: () => Shimmer,
   SyntaxHighlighter: () => syntax_highlighter_default,
   Thread: () => Thread,
+  ThreadPrimitive: () => import_react13.ThreadPrimitive,
   TimbalChat: () => TimbalChat,
   TimbalRuntimeProvider: () => TimbalRuntimeProvider,
   ToolFallback: () => ToolFallback,
@@ -66,7 +70,13 @@ __export(index_exports, {
   getAccessToken: () => getAccessToken,
   getRefreshToken: () => getRefreshToken,
   refreshAccessToken: () => refreshAccessToken,
-  useSession: () => useSession
+  setAccessToken: () => setAccessToken,
+  setRefreshToken: () => setRefreshToken,
+  useComposerRuntime: () => import_react13.useComposerRuntime,
+  useMessageRuntime: () => import_react13.useMessageRuntime,
+  useSession: () => useSession,
+  useThread: () => import_react13.useThread,
+  useThreadRuntime: () => import_react13.useThreadRuntime
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -79,7 +89,9 @@ var import_timbal_sdk = require("@timbal-ai/timbal-sdk");
 var ACCESS_TOKEN_KEY = "timbal_project_access_token";
 var REFRESH_TOKEN_KEY = "timbal_project_refresh_token";
 var getAccessToken = () => localStorage.getItem(ACCESS_TOKEN_KEY);
+var setAccessToken = (token) => localStorage.setItem(ACCESS_TOKEN_KEY, token);
 var getRefreshToken = () => localStorage.getItem(REFRESH_TOKEN_KEY);
+var setRefreshToken = (token) => localStorage.setItem(REFRESH_TOKEN_KEY, token);
 var clearTokens = () => {
   localStorage.removeItem(ACCESS_TOKEN_KEY);
   localStorage.removeItem(REFRESH_TOKEN_KEY);
@@ -1273,8 +1285,15 @@ var Thread = ({
   maxWidth = "44rem",
   welcome,
   suggestions,
-  composerPlaceholder = "Send a message..."
+  composerPlaceholder = "Send a message...",
+  components
 }) => {
+  const WelcomeSlot = components?.Welcome ?? ThreadWelcome;
+  const ComposerSlot = components?.Composer ?? Composer;
+  const UserMessageSlot = components?.UserMessage ?? UserMessage;
+  const AssistantMessageSlot = components?.AssistantMessage ?? AssistantMessage;
+  const EditComposerSlot = components?.EditComposer ?? EditComposer;
+  const ScrollToBottomSlot = components?.ScrollToBottom ?? ThreadScrollToBottom;
   return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
     import_react11.ThreadPrimitive.Root,
     {
@@ -1289,20 +1308,20 @@ var Thread = ({
           turnAnchor: "bottom",
           className: "aui-thread-viewport relative flex flex-1 flex-col overflow-x-auto overflow-y-scroll px-4 pt-4",
           children: [
-            /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(import_react11.AuiIf, { condition: (s) => s.thread.isEmpty, children: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ThreadWelcome, { config: welcome, suggestions }) }),
+            /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(WelcomeSlot, { config: welcome, suggestions }),
             /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
               import_react11.ThreadPrimitive.Messages,
               {
                 components: {
-                  UserMessage,
-                  EditComposer,
-                  AssistantMessage
+                  UserMessage: UserMessageSlot,
+                  EditComposer: EditComposerSlot,
+                  AssistantMessage: AssistantMessageSlot
                 }
               }
             ),
             /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)(import_react11.ThreadPrimitive.ViewportFooter, { className: "aui-thread-viewport-footer sticky bottom-0 mx-auto mt-auto flex w-full max-w-(--thread-max-width) flex-col gap-4 overflow-visible rounded-t-3xl bg-background pb-4 md:pb-6", children: [
-              /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ThreadScrollToBottom, {}),
-              /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(Composer, { placeholder: composerPlaceholder })
+              /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ScrollToBottomSlot, {}),
+              /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ComposerSlot, { placeholder: composerPlaceholder })
             ] })
           ]
         }
@@ -1322,7 +1341,7 @@ var ThreadScrollToBottom = () => {
   ) });
 };
 var ThreadWelcome = ({ config, suggestions }) => {
-  return /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("div", { className: "aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col", children: [
+  return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(import_react11.AuiIf, { condition: (s) => s.thread.isEmpty, children: /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("div", { className: "aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col", children: [
     /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("div", { className: "aui-thread-welcome-center flex w-full grow flex-col items-center justify-center", children: /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("div", { className: "aui-thread-welcome-message flex size-full flex-col items-center justify-center px-4 text-center", children: [
       /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)("div", { className: "fade-in animate-in fill-mode-both relative mb-6 flex size-14 items-center justify-center duration-300", children: [
         /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("div", { className: "animate-ai-ring-glow absolute inset-0 rounded-2xl bg-gradient-to-br from-primary/15 to-primary/5 ring-1 ring-primary/15" }),
@@ -1346,7 +1365,7 @@ var ThreadWelcome = ({ config, suggestions }) => {
       /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("p", { className: "aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both text-muted-foreground mt-2 delay-75 duration-200", children: config?.subheading ?? "Send a message to start a conversation." })
     ] }) }),
     suggestions && suggestions.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ThreadSuggestions, { suggestions })
-  ] });
+  ] }) });
 };
 var ThreadSuggestions = ({ suggestions }) => {
   return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("div", { className: "aui-thread-welcome-suggestions grid w-full @md:grid-cols-2 gap-2 pb-4", children: suggestions.map((s, i) => /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ThreadSuggestionItem, { title: s.title, description: s.description }, i)) });
@@ -1534,9 +1553,19 @@ function TimbalChat({
   return /* @__PURE__ */ (0, import_jsx_runtime13.jsx)(TimbalRuntimeProvider, { workforceId, baseUrl, fetch: fetch2, children: /* @__PURE__ */ (0, import_jsx_runtime13.jsx)(Thread, { ...threadProps }) });
 }
 
+// src/index.ts
+var import_react13 = require("@assistant-ui/react");
+
 // src/auth/provider.tsx
 var import_react12 = require("react");
 var import_jsx_runtime14 = require("react/jsx-runtime");
+function isInsideIframe() {
+  try {
+    return typeof window !== "undefined" && window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
 var SessionContext = (0, import_react12.createContext)(void 0);
 var useSession = () => {
   const context = (0, import_react12.useContext)(SessionContext);
@@ -1551,6 +1580,7 @@ var SessionProvider = ({
 }) => {
   const [user, setUser] = (0, import_react12.useState)(null);
   const [loading, setLoading] = (0, import_react12.useState)(enabled);
+  const [embedded] = (0, import_react12.useState)(isInsideIframe);
   (0, import_react12.useEffect)(() => {
     if (!enabled) {
       setLoading(false);
@@ -1583,13 +1613,35 @@ var SessionProvider = ({
         if (ignore) return;
         clearTokens();
       }
-      setLoading(false);
+      if (!ignore && !embedded) {
+        setLoading(false);
+      }
     };
     restoreSession();
+    let messageCleanup;
+    if (embedded) {
+      const handleMessage = async (event) => {
+        if (ignore) return;
+        if (event.data?.type !== "timbal:auth" || !event.data.token) return;
+        setAccessToken(event.data.token);
+        if (event.data.refreshToken) {
+          setRefreshToken(event.data.refreshToken);
+        }
+        const u = await fetchCurrentUser();
+        if (!ignore) {
+          setUser(u);
+          setLoading(false);
+        }
+      };
+      window.addEventListener("message", handleMessage);
+      window.parent.postMessage({ type: "timbal:request-session" }, "*");
+      messageCleanup = () => window.removeEventListener("message", handleMessage);
+    }
     return () => {
       ignore = true;
+      messageCleanup?.();
     };
-  }, [enabled]);
+  }, [enabled, embedded]);
   const logout = (0, import_react12.useCallback)(() => {
     clearTokens();
     setUser(null);
@@ -1607,6 +1659,7 @@ var SessionProvider = ({
         user,
         loading,
         isAuthenticated: !!user,
+        isEmbedded: embedded,
         logout
       },
       children
@@ -1622,14 +1675,14 @@ var AuthGuard = ({
   requireAuth = false,
   enabled = true
 }) => {
-  const { isAuthenticated, loading } = useSession();
+  const { isAuthenticated, loading, isEmbedded } = useSession();
   if (!enabled) {
     return children;
   }
   if (loading) {
     return /* @__PURE__ */ (0, import_jsx_runtime15.jsx)("div", { className: "flex items-center justify-center h-screen", children: /* @__PURE__ */ (0, import_jsx_runtime15.jsx)(import_lucide_react6.Loader2, { className: "w-8 h-8 animate-spin" }) });
   }
-  if (requireAuth && !isAuthenticated) {
+  if (requireAuth && !isAuthenticated && !isEmbedded) {
     const returnTo = encodeURIComponent(
       window.location.pathname + window.location.search
     );
@@ -1640,6 +1693,7 @@ var AuthGuard = ({
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ActionBarPrimitive,
   AuthGuard,
   Avatar,
   AvatarFallback,
@@ -1647,6 +1701,7 @@ var AuthGuard = ({
   Button,
   ComposerAddAttachment,
   ComposerAttachments,
+  ComposerPrimitive,
   Dialog,
   DialogClose,
   DialogContent,
@@ -1655,10 +1710,12 @@ var AuthGuard = ({
   DialogTitle,
   DialogTrigger,
   MarkdownText,
+  MessagePrimitive,
   SessionProvider,
   Shimmer,
   SyntaxHighlighter,
   Thread,
+  ThreadPrimitive,
   TimbalChat,
   TimbalRuntimeProvider,
   ToolFallback,
@@ -1676,5 +1733,11 @@ var AuthGuard = ({
   getAccessToken,
   getRefreshToken,
   refreshAccessToken,
-  useSession
+  setAccessToken,
+  setRefreshToken,
+  useComposerRuntime,
+  useMessageRuntime,
+  useSession,
+  useThread,
+  useThreadRuntime
 });

package/dist/index.d.cts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import React__default, { ReactNode, FC, ComponentPropsWithRef, ElementType } from 'react';
+import React__default, { ReactNode, FC, ComponentType, ComponentPropsWithRef, ElementType } from 'react';
 import { ToolCallMessagePartComponent } from '@assistant-ui/react';
+export { ActionBarPrimitive, ComposerPrimitive, MessagePrimitive, ThreadPrimitive, useComposerRuntime, useMessageRuntime, useThread, useThreadRuntime } from '@assistant-ui/react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import { SyntaxHighlighterProps } from '@assistant-ui/react-markdown';
@@ -34,6 +35,26 @@ interface ThreadWelcomeConfig {
     heading?: string;
     subheading?: string;
 }
+interface ThreadWelcomeProps {
+    config?: ThreadWelcomeConfig;
+    suggestions?: ThreadSuggestion[];
+}
+interface ThreadComponents {
+    /** Replace the user message bubble. Access message content via `MessagePrimitive.Parts`. */
+    UserMessage?: ComponentType;
+    /** Replace the assistant message bubble. Access message content via `MessagePrimitive.Parts`. */
+    AssistantMessage?: ComponentType;
+    /** Replace the inline edit composer. */
+    EditComposer?: ComponentType;
+    /** Replace the composer (input bar). Receives `placeholder` from `composerPlaceholder`. */
+    Composer?: ComponentType<{
+        placeholder?: string;
+    }>;
+    /** Replace the welcome / empty state. Receives `config` and `suggestions` props. Controls its own visibility — use `useThread(s => s.isEmpty)` to replicate the default behaviour. */
+    Welcome?: ComponentType<ThreadWelcomeProps>;
+    /** Replace the scroll-to-bottom button. */
+    ScrollToBottom?: ComponentType;
+}
 interface ThreadProps {
     className?: string;
     /** Max width of the message column. Default: "44rem" */
@@ -44,6 +65,8 @@ interface ThreadProps {
     suggestions?: ThreadSuggestion[];
     /** Composer input placeholder. Default: "Send a message..." */
     composerPlaceholder?: string;
+    /** Override individual UI slots while keeping the rest as defaults. */
+    components?: ThreadComponents;
 }
 declare const Thread: FC<ThreadProps>;
 
@@ -79,6 +102,7 @@ interface SessionContextType {
     user: Session | null;
     loading: boolean;
     isAuthenticated: boolean;
+    isEmbedded: boolean;
     logout: () => void;
 }
 declare const useSession: () => SessionContextType;
@@ -98,7 +122,9 @@ interface AuthGuardProps {
 declare const AuthGuard: React__default.FC<AuthGuardProps>;
 
 declare const getAccessToken: () => string | null;
+declare const setAccessToken: (token: string) => void;
 declare const getRefreshToken: () => string | null;
+declare const setRefreshToken: (token: string) => void;
 declare const clearTokens: () => void;
 declare const refreshAccessToken: () => Promise<boolean>;
 declare const authFetch: (url: string, options?: RequestInit) => Promise<Response>;
@@ -136,4 +162,4 @@ declare const Shimmer: React.MemoExoticComponent<({ children, as: Component, cla
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { AuthGuard, Avatar, AvatarFallback, AvatarImage, Button, ComposerAddAttachment, ComposerAttachments, Dialog, DialogClose, DialogContent, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, MarkdownText, SessionProvider, Shimmer, ShikiSyntaxHighlighter as SyntaxHighlighter, type TextShimmerProps, Thread, type ThreadProps, type ThreadSuggestion, type ThreadWelcomeConfig, TimbalChat, type TimbalChatProps, TimbalRuntimeProvider, type TimbalRuntimeProviderProps, ToolFallback, Tooltip, TooltipContent, TooltipIconButton, type TooltipIconButtonProps, TooltipProvider, TooltipTrigger, UserMessageAttachments, authFetch, buttonVariants, clearTokens, cn, fetchCurrentUser, getAccessToken, getRefreshToken, refreshAccessToken, useSession };
+export { AuthGuard, Avatar, AvatarFallback, AvatarImage, Button, ComposerAddAttachment, ComposerAttachments, Dialog, DialogClose, DialogContent, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, MarkdownText, SessionProvider, Shimmer, ShikiSyntaxHighlighter as SyntaxHighlighter, type TextShimmerProps, Thread, type ThreadComponents, type ThreadProps, type ThreadSuggestion, type ThreadWelcomeConfig, type ThreadWelcomeProps, TimbalChat, type TimbalChatProps, TimbalRuntimeProvider, type TimbalRuntimeProviderProps, ToolFallback, Tooltip, TooltipContent, TooltipIconButton, type TooltipIconButtonProps, TooltipProvider, TooltipTrigger, UserMessageAttachments, authFetch, buttonVariants, clearTokens, cn, fetchCurrentUser, getAccessToken, getRefreshToken, refreshAccessToken, setAccessToken, setRefreshToken, useSession };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import React__default, { ReactNode, FC, ComponentPropsWithRef, ElementType } from 'react';
+import React__default, { ReactNode, FC, ComponentType, ComponentPropsWithRef, ElementType } from 'react';
 import { ToolCallMessagePartComponent } from '@assistant-ui/react';
+export { ActionBarPrimitive, ComposerPrimitive, MessagePrimitive, ThreadPrimitive, useComposerRuntime, useMessageRuntime, useThread, useThreadRuntime } from '@assistant-ui/react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import { SyntaxHighlighterProps } from '@assistant-ui/react-markdown';
@@ -34,6 +35,26 @@ interface ThreadWelcomeConfig {
     heading?: string;
     subheading?: string;
 }
+interface ThreadWelcomeProps {
+    config?: ThreadWelcomeConfig;
+    suggestions?: ThreadSuggestion[];
+}
+interface ThreadComponents {
+    /** Replace the user message bubble. Access message content via `MessagePrimitive.Parts`. */
+    UserMessage?: ComponentType;
+    /** Replace the assistant message bubble. Access message content via `MessagePrimitive.Parts`. */
+    AssistantMessage?: ComponentType;
+    /** Replace the inline edit composer. */
+    EditComposer?: ComponentType;
+    /** Replace the composer (input bar). Receives `placeholder` from `composerPlaceholder`. */
+    Composer?: ComponentType<{
+        placeholder?: string;
+    }>;
+    /** Replace the welcome / empty state. Receives `config` and `suggestions` props. Controls its own visibility — use `useThread(s => s.isEmpty)` to replicate the default behaviour. */
+    Welcome?: ComponentType<ThreadWelcomeProps>;
+    /** Replace the scroll-to-bottom button. */
+    ScrollToBottom?: ComponentType;
+}
 interface ThreadProps {
     className?: string;
     /** Max width of the message column. Default: "44rem" */
@@ -44,6 +65,8 @@ interface ThreadProps {
     suggestions?: ThreadSuggestion[];
     /** Composer input placeholder. Default: "Send a message..." */
     composerPlaceholder?: string;
+    /** Override individual UI slots while keeping the rest as defaults. */
+    components?: ThreadComponents;
 }
 declare const Thread: FC<ThreadProps>;
 
@@ -79,6 +102,7 @@ interface SessionContextType {
     user: Session | null;
     loading: boolean;
     isAuthenticated: boolean;
+    isEmbedded: boolean;
     logout: () => void;
 }
 declare const useSession: () => SessionContextType;
@@ -98,7 +122,9 @@ interface AuthGuardProps {
 declare const AuthGuard: React__default.FC<AuthGuardProps>;
 
 declare const getAccessToken: () => string | null;
+declare const setAccessToken: (token: string) => void;
 declare const getRefreshToken: () => string | null;
+declare const setRefreshToken: (token: string) => void;
 declare const clearTokens: () => void;
 declare const refreshAccessToken: () => Promise<boolean>;
 declare const authFetch: (url: string, options?: RequestInit) => Promise<Response>;
@@ -136,4 +162,4 @@ declare const Shimmer: React.MemoExoticComponent<({ children, as: Component, cla
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { AuthGuard, Avatar, AvatarFallback, AvatarImage, Button, ComposerAddAttachment, ComposerAttachments, Dialog, DialogClose, DialogContent, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, MarkdownText, SessionProvider, Shimmer, ShikiSyntaxHighlighter as SyntaxHighlighter, type TextShimmerProps, Thread, type ThreadProps, type ThreadSuggestion, type ThreadWelcomeConfig, TimbalChat, type TimbalChatProps, TimbalRuntimeProvider, type TimbalRuntimeProviderProps, ToolFallback, Tooltip, TooltipContent, TooltipIconButton, type TooltipIconButtonProps, TooltipProvider, TooltipTrigger, UserMessageAttachments, authFetch, buttonVariants, clearTokens, cn, fetchCurrentUser, getAccessToken, getRefreshToken, refreshAccessToken, useSession };
+export { AuthGuard, Avatar, AvatarFallback, AvatarImage, Button, ComposerAddAttachment, ComposerAttachments, Dialog, DialogClose, DialogContent, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, MarkdownText, SessionProvider, Shimmer, ShikiSyntaxHighlighter as SyntaxHighlighter, type TextShimmerProps, Thread, type ThreadComponents, type ThreadProps, type ThreadSuggestion, type ThreadWelcomeConfig, type ThreadWelcomeProps, TimbalChat, type TimbalChatProps, TimbalRuntimeProvider, type TimbalRuntimeProviderProps, ToolFallback, Tooltip, TooltipContent, TooltipIconButton, type TooltipIconButtonProps, TooltipProvider, TooltipTrigger, UserMessageAttachments, authFetch, buttonVariants, clearTokens, cn, fetchCurrentUser, getAccessToken, getRefreshToken, refreshAccessToken, setAccessToken, setRefreshToken, useSession };

package/dist/index.esm.js

@@ -10,7 +10,9 @@ import { parseSSELine } from "@timbal-ai/timbal-sdk";
 var ACCESS_TOKEN_KEY = "timbal_project_access_token";
 var REFRESH_TOKEN_KEY = "timbal_project_refresh_token";
 var getAccessToken = () => localStorage.getItem(ACCESS_TOKEN_KEY);
+var setAccessToken = (token) => localStorage.setItem(ACCESS_TOKEN_KEY, token);
 var getRefreshToken = () => localStorage.getItem(REFRESH_TOKEN_KEY);
+var setRefreshToken = (token) => localStorage.setItem(REFRESH_TOKEN_KEY, token);
 var clearTokens = () => {
   localStorage.removeItem(ACCESS_TOKEN_KEY);
   localStorage.removeItem(REFRESH_TOKEN_KEY);
@@ -1236,8 +1238,15 @@ var Thread = ({
   maxWidth = "44rem",
   welcome,
   suggestions,
-  composerPlaceholder = "Send a message..."
+  composerPlaceholder = "Send a message...",
+  components
 }) => {
+  const WelcomeSlot = components?.Welcome ?? ThreadWelcome;
+  const ComposerSlot = components?.Composer ?? Composer;
+  const UserMessageSlot = components?.UserMessage ?? UserMessage;
+  const AssistantMessageSlot = components?.AssistantMessage ?? AssistantMessage;
+  const EditComposerSlot = components?.EditComposer ?? EditComposer;
+  const ScrollToBottomSlot = components?.ScrollToBottom ?? ThreadScrollToBottom;
   return /* @__PURE__ */ jsx12(
     ThreadPrimitive.Root,
     {
@@ -1252,20 +1261,20 @@ var Thread = ({
           turnAnchor: "bottom",
           className: "aui-thread-viewport relative flex flex-1 flex-col overflow-x-auto overflow-y-scroll px-4 pt-4",
           children: [
-            /* @__PURE__ */ jsx12(AuiIf, { condition: (s) => s.thread.isEmpty, children: /* @__PURE__ */ jsx12(ThreadWelcome, { config: welcome, suggestions }) }),
+            /* @__PURE__ */ jsx12(WelcomeSlot, { config: welcome, suggestions }),
             /* @__PURE__ */ jsx12(
               ThreadPrimitive.Messages,
               {
                 components: {
-                  UserMessage,
-                  EditComposer,
-                  AssistantMessage
+                  UserMessage: UserMessageSlot,
+                  EditComposer: EditComposerSlot,
+                  AssistantMessage: AssistantMessageSlot
                 }
               }
             ),
             /* @__PURE__ */ jsxs7(ThreadPrimitive.ViewportFooter, { className: "aui-thread-viewport-footer sticky bottom-0 mx-auto mt-auto flex w-full max-w-(--thread-max-width) flex-col gap-4 overflow-visible rounded-t-3xl bg-background pb-4 md:pb-6", children: [
-              /* @__PURE__ */ jsx12(ThreadScrollToBottom, {}),
-              /* @__PURE__ */ jsx12(Composer, { placeholder: composerPlaceholder })
+              /* @__PURE__ */ jsx12(ScrollToBottomSlot, {}),
+              /* @__PURE__ */ jsx12(ComposerSlot, { placeholder: composerPlaceholder })
             ] })
           ]
         }
@@ -1285,7 +1294,7 @@ var ThreadScrollToBottom = () => {
   ) });
 };
 var ThreadWelcome = ({ config, suggestions }) => {
-  return /* @__PURE__ */ jsxs7("div", { className: "aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col", children: [
+  return /* @__PURE__ */ jsx12(AuiIf, { condition: (s) => s.thread.isEmpty, children: /* @__PURE__ */ jsxs7("div", { className: "aui-thread-welcome-root mx-auto my-auto flex w-full max-w-(--thread-max-width) grow flex-col", children: [
     /* @__PURE__ */ jsx12("div", { className: "aui-thread-welcome-center flex w-full grow flex-col items-center justify-center", children: /* @__PURE__ */ jsxs7("div", { className: "aui-thread-welcome-message flex size-full flex-col items-center justify-center px-4 text-center", children: [
       /* @__PURE__ */ jsxs7("div", { className: "fade-in animate-in fill-mode-both relative mb-6 flex size-14 items-center justify-center duration-300", children: [
         /* @__PURE__ */ jsx12("div", { className: "animate-ai-ring-glow absolute inset-0 rounded-2xl bg-gradient-to-br from-primary/15 to-primary/5 ring-1 ring-primary/15" }),
@@ -1309,7 +1318,7 @@ var ThreadWelcome = ({ config, suggestions }) => {
       /* @__PURE__ */ jsx12("p", { className: "aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both text-muted-foreground mt-2 delay-75 duration-200", children: config?.subheading ?? "Send a message to start a conversation." })
     ] }) }),
     suggestions && suggestions.length > 0 && /* @__PURE__ */ jsx12(ThreadSuggestions, { suggestions })
-  ] });
+  ] }) });
 };
 var ThreadSuggestions = ({ suggestions }) => {
   return /* @__PURE__ */ jsx12("div", { className: "aui-thread-welcome-suggestions grid w-full @md:grid-cols-2 gap-2 pb-4", children: suggestions.map((s, i) => /* @__PURE__ */ jsx12(ThreadSuggestionItem, { title: s.title, description: s.description }, i)) });
@@ -1497,6 +1506,18 @@ function TimbalChat({
   return /* @__PURE__ */ jsx13(TimbalRuntimeProvider, { workforceId, baseUrl, fetch: fetch2, children: /* @__PURE__ */ jsx13(Thread, { ...threadProps }) });
 }
 
+// src/index.ts
+import {
+  ThreadPrimitive as ThreadPrimitive2,
+  MessagePrimitive as MessagePrimitive3,
+  ComposerPrimitive as ComposerPrimitive3,
+  ActionBarPrimitive as ActionBarPrimitive2,
+  useThread,
+  useThreadRuntime as useThreadRuntime2,
+  useMessageRuntime,
+  useComposerRuntime
+} from "@assistant-ui/react";
+
 // src/auth/provider.tsx
 import {
   createContext,
@@ -1506,6 +1527,13 @@ import {
   useState as useState5
 } from "react";
 import { jsx as jsx14 } from "react/jsx-runtime";
+function isInsideIframe() {
+  try {
+    return typeof window !== "undefined" && window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
 var SessionContext = createContext(void 0);
 var useSession = () => {
   const context = useContext(SessionContext);
@@ -1520,6 +1548,7 @@ var SessionProvider = ({
 }) => {
   const [user, setUser] = useState5(null);
   const [loading, setLoading] = useState5(enabled);
+  const [embedded] = useState5(isInsideIframe);
   useEffect4(() => {
     if (!enabled) {
       setLoading(false);
@@ -1552,13 +1581,35 @@ var SessionProvider = ({
         if (ignore) return;
         clearTokens();
       }
-      setLoading(false);
+      if (!ignore && !embedded) {
+        setLoading(false);
+      }
     };
     restoreSession();
+    let messageCleanup;
+    if (embedded) {
+      const handleMessage = async (event) => {
+        if (ignore) return;
+        if (event.data?.type !== "timbal:auth" || !event.data.token) return;
+        setAccessToken(event.data.token);
+        if (event.data.refreshToken) {
+          setRefreshToken(event.data.refreshToken);
+        }
+        const u = await fetchCurrentUser();
+        if (!ignore) {
+          setUser(u);
+          setLoading(false);
+        }
+      };
+      window.addEventListener("message", handleMessage);
+      window.parent.postMessage({ type: "timbal:request-session" }, "*");
+      messageCleanup = () => window.removeEventListener("message", handleMessage);
+    }
     return () => {
       ignore = true;
+      messageCleanup?.();
     };
-  }, [enabled]);
+  }, [enabled, embedded]);
   const logout = useCallback2(() => {
     clearTokens();
     setUser(null);
@@ -1576,6 +1627,7 @@ var SessionProvider = ({
         user,
         loading,
         isAuthenticated: !!user,
+        isEmbedded: embedded,
         logout
       },
       children
@@ -1591,14 +1643,14 @@ var AuthGuard = ({
   requireAuth = false,
   enabled = true
 }) => {
-  const { isAuthenticated, loading } = useSession();
+  const { isAuthenticated, loading, isEmbedded } = useSession();
   if (!enabled) {
     return children;
   }
   if (loading) {
     return /* @__PURE__ */ jsx15("div", { className: "flex items-center justify-center h-screen", children: /* @__PURE__ */ jsx15(Loader2, { className: "w-8 h-8 animate-spin" }) });
   }
-  if (requireAuth && !isAuthenticated) {
+  if (requireAuth && !isAuthenticated && !isEmbedded) {
     const returnTo = encodeURIComponent(
       window.location.pathname + window.location.search
     );
@@ -1608,6 +1660,7 @@ var AuthGuard = ({
   return children;
 };
 export {
+  ActionBarPrimitive2 as ActionBarPrimitive,
   AuthGuard,
   Avatar,
   AvatarFallback,
@@ -1615,6 +1668,7 @@ export {
   Button,
   ComposerAddAttachment,
   ComposerAttachments,
+  ComposerPrimitive3 as ComposerPrimitive,
   Dialog,
   DialogClose,
   DialogContent,
@@ -1623,10 +1677,12 @@ export {
   DialogTitle,
   DialogTrigger,
   MarkdownText,
+  MessagePrimitive3 as MessagePrimitive,
   SessionProvider,
   Shimmer,
   syntax_highlighter_default as SyntaxHighlighter,
   Thread,
+  ThreadPrimitive2 as ThreadPrimitive,
   TimbalChat,
   TimbalRuntimeProvider,
   ToolFallback,
@@ -1644,5 +1700,11 @@ export {
   getAccessToken,
   getRefreshToken,
   refreshAccessToken,
-  useSession
+  setAccessToken,
+  setRefreshToken,
+  useComposerRuntime,
+  useMessageRuntime,
+  useSession,
+  useThread,
+  useThreadRuntime2 as useThreadRuntime
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timbal-ai/timbal-react",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "React components and runtime for building Timbal chat UIs",
   "type": "module",
   "main": "dist/index.cjs",
@@ -22,6 +22,8 @@
     "build": "tsup",
     "build:watch": "tsup --watch",
     "clean": "rm -rf dist",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "bun run build && bun run typecheck"
   },
@@ -52,9 +54,13 @@
   },
   "devDependencies": {
     "@assistant-ui/react": "^0.12.10",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@timbal-ai/timbal-sdk": "0.4.9",
     "@types/react": "^19.2.4",
     "@types/react-dom": "^19.2.3",
+    "happy-dom": "^20.8.9",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "tsup": "^8.5.0",