@timbal-ai/timbal-react 0.1.1 → 0.2.1

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,74 @@ import "katex/dist/katex.min.css";
 
 ---
 
-## Usage
+## Quick start
 
-### Drop-in chat
+### Basic usage
 
-Wrap `TimbalRuntimeProvider` with a `workforceId` and render `<Thread />` inside it:
+`TimbalChat` is a single component that handles everything — runtime, streaming, messages, and the composer:
+
+```tsx
+import { TimbalChat } from "@timbal-ai/timbal-react";
+
+export default function App() {
+  return (
+    <div style={{ height: "100vh" }}>
+      <TimbalChat workforceId="your-workforce-id" />
+    </div>
+  );
+}
+```
+
+> `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
+  workforceId="your-workforce-id"
+  welcome={{
+    heading: "Hi, I'm your assistant",
+    subheading: "Ask me anything about your data.",
+  }}
+  suggestions={[
+    { title: "Summarize this week", description: "Get a quick overview of recent activity" },
+    { title: "What can you help with?" },
+    { title: "Show me the latest report" },
+  ]}
+/>
+```
+
+### Placeholder and width
+
+```tsx
+<TimbalChat
+  workforceId="your-workforce-id"
+  composerPlaceholder="Type a question..."
+  maxWidth="60rem"
+  className="my-custom-class"
+/>
+```
+
+### Switching agents dynamically
+
+Pass `key` to fully reset the chat when the workforce changes:
+
+```tsx
+const [workforceId, setWorkforceId] = useState("agent-a");
+
+<select onChange={(e) => setWorkforceId(e.target.value)}>
+  <option value="agent-a">Agent A</option>
+  <option value="agent-b">Agent B</option>
+</select>
+
+<TimbalChat workforceId={workforceId} key={workforceId} />
+```
+
+---
+
+## Splitting the runtime and UI
+
+`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";
@@ -53,89 +116,292 @@ import { TimbalRuntimeProvider, Thread } from "@timbal-ai/timbal-react";
 export default function App() {
   return (
     <TimbalRuntimeProvider workforceId="your-workforce-id">
-      <div style={{ height: "100vh" }}>
-        <Thread />
+      <div style={{ height: "100vh", display: "flex", flexDirection: "column" }}>
+        <header>My App</header>
+        <Thread
+          composerPlaceholder="Ask anything..."
+          className="flex-1 min-h-0"
+        />
       </div>
     </TimbalRuntimeProvider>
   );
 }
 ```
 
-### `TimbalRuntimeProvider` props
+### Custom API base URL
+
+Useful when your API is mounted at a subpath (e.g. behind a reverse proxy):
+
+```tsx
+<TimbalRuntimeProvider workforceId="your-workforce-id" baseUrl="/api">
+  <Thread />
+</TimbalRuntimeProvider>
+```
+
+### Custom fetch function
+
+Pass your own `fetch` to add headers, inject tokens, or proxy requests:
+
+```tsx
+const myFetch: typeof fetch = (url, options) => {
+  return fetch(url, {
+    ...options,
+    headers: { ...options?.headers, "X-My-Header": "value" },
+  });
+};
+
+<TimbalRuntimeProvider workforceId="your-workforce-id" fetch={myFetch}>
+  <Thread />
+</TimbalRuntimeProvider>
+```
+
+---
+
+## 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` | — | ID of the workforce to stream from |
+| `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 function. Defaults to the built-in auth-aware fetch (Bearer token + auto-refresh) |
+| `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` | **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
 
 Wrap your app with `SessionProvider` and protect routes with `AuthGuard`:
 
 ```tsx
+// src/App.tsx
 import { SessionProvider, AuthGuard, TooltipProvider } from "@timbal-ai/timbal-react";
+import { BrowserRouter, Routes, Route } from "react-router-dom";
+import Home from "./pages/Home";
 
 const isAuthEnabled = !!import.meta.env.VITE_TIMBAL_PROJECT_ID;
 
-function App() {
+export default function App() {
   return (
     <SessionProvider enabled={isAuthEnabled}>
       <TooltipProvider>
-        <AuthGuard requireAuth enabled={isAuthEnabled}>
-          <YourApp />
-        </AuthGuard>
+        <BrowserRouter>
+          <AuthGuard requireAuth enabled={isAuthEnabled}>
+            <Routes>
+              <Route path="/" element={<Home />} />
+            </Routes>
+          </AuthGuard>
+        </BrowserRouter>
       </TooltipProvider>
     </SessionProvider>
   );
 }
 ```
 
-### `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
 
+Access the current session anywhere inside `SessionProvider`:
+
 ```tsx
 import { useSession } from "@timbal-ai/timbal-react";
 
 function Header() {
   const { user, isAuthenticated, loading, logout } = useSession();
-  // ...
+  if (loading) return null;
+  return (
+    <header>
+      {isAuthenticated ? (
+        <>
+          <span>{user?.email}</span>
+          <button onClick={logout}>Log out</button>
+        </>
+      ) : (
+        <a href="/login">Log in</a>
+      )}
+    </header>
+  );
 }
 ```
 
 ### `authFetch`
 
-A drop-in replacement for `fetch` that attaches the Bearer token 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";
 
 const res = await authFetch("/api/workforce");
+if (res.ok) {
+  const agents = await res.json();
+}
 ```
 
+### 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 |
 |---|---|
@@ -156,12 +422,71 @@ Re-exported Radix UI wrappers pre-styled to match the Timbal design system:
 
 ---
 
+## Full example
+
+A complete page with agent switching, auth, and a custom header:
+
+```tsx
+// 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 { LogOut } from "lucide-react";
+
+const isAuthEnabled = !!import.meta.env.VITE_TIMBAL_PROJECT_ID;
+
+export default function Home() {
+  const { logout } = useSession();
+  const [workforces, setWorkforces] = useState<WorkforceItem[]>([]);
+  const [selectedId, setSelectedId] = useState("");
+
+  useEffect(() => {
+    authFetch("/api/workforce")
+      .then((r) => r.json())
+      .then((data: WorkforceItem[]) => {
+        setWorkforces(data);
+        const agent = data.find((w) => w.type === "agent") ?? data[0];
+        if (agent) setSelectedId(agent.id ?? agent.name ?? "");
+      })
+      .catch(() => {});
+  }, []);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+      <header style={{ display: "flex", justifyContent: "space-between", padding: "0.5rem 1.25rem" }}>
+        <select value={selectedId} onChange={(e) => setSelectedId(e.target.value)}>
+          {workforces.map((w) => (
+            <option key={w.id ?? w.name} value={w.id ?? w.name ?? ""}>
+              {w.name}
+            </option>
+          ))}
+        </select>
+
+        {isAuthEnabled && (
+          <Button variant="ghost" size="icon" onClick={logout}>
+            <LogOut />
+          </Button>
+        )}
+      </header>
+
+      <TimbalChat
+        workforceId={selectedId}
+        key={selectedId}
+        className="flex-1 min-h-0"
+        welcome={{ heading: "How can I help you today?" }}
+      />
+    </div>
+  );
+}
+```
+
+---
+
 ## Local development
 
 Install via a local path reference:
 
 ```json
-// package.json
 {
   "dependencies": {
     "@timbal-ai/timbal-react": "file:../../timbal-react"
@@ -171,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,13 @@ __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,
   Tooltip: () => Tooltip,
@@ -65,7 +70,11 @@ __export(index_exports, {
   getAccessToken: () => getAccessToken,
   getRefreshToken: () => getRefreshToken,
   refreshAccessToken: () => refreshAccessToken,
-  useSession: () => useSession
+  useComposerRuntime: () => import_react13.useComposerRuntime,
+  useMessageRuntime: () => import_react13.useMessageRuntime,
+  useSession: () => useSession,
+  useThread: () => import_react13.useThread,
+  useThreadRuntime: () => import_react13.useThreadRuntime
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1267,34 +1276,48 @@ ToolFallback.displayName = "ToolFallback";
 var import_react11 = require("@assistant-ui/react");
 var import_lucide_react5 = require("lucide-react");
 var import_jsx_runtime12 = require("react/jsx-runtime");
-var Thread = () => {
+var Thread = ({
+  className,
+  maxWidth = "44rem",
+  welcome,
+  suggestions,
+  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,
     {
-      className: "aui-root aui-thread-root @container flex h-full flex-col bg-background",
-      style: {
-        ["--thread-max-width"]: "44rem"
-      },
+      className: cn(
+        "aui-root aui-thread-root @container flex h-full flex-col bg-background",
+        className
+      ),
+      style: { ["--thread-max-width"]: maxWidth },
       children: /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)(
         import_react11.ThreadPrimitive.Viewport,
         {
           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, {}) }),
+            /* @__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, {})
+              /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ScrollToBottomSlot, {}),
+              /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ComposerSlot, { placeholder: composerPlaceholder })
             ] })
           ]
         }
@@ -1313,8 +1336,8 @@ var ThreadScrollToBottom = () => {
     }
   ) });
 };
-var ThreadWelcome = () => {
-  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: [
+var ThreadWelcome = ({ config, suggestions }) => {
+  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" }),
@@ -1334,42 +1357,40 @@ var ThreadWelcome = () => {
           }
         )
       ] }),
-      /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("h1", { className: "aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both font-semibold text-2xl duration-200", children: "How can I help you today?" }),
-      /* @__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: "Send a message to start a conversation." })
+      /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("h1", { className: "aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both font-semibold text-2xl duration-200", children: config?.heading ?? "How can I help you today?" }),
+      /* @__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." })
     ] }) }),
-    /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ThreadSuggestions, {})
-  ] });
+    suggestions && suggestions.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ThreadSuggestions, { suggestions })
+  ] }) });
 };
-var ThreadSuggestions = () => {
-  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: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
-    import_react11.ThreadPrimitive.Suggestions,
-    {
-      components: {
-        Suggestion: ThreadSuggestionItem
-      }
-    }
-  ) });
+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)) });
 };
-var ThreadSuggestionItem = () => {
-  return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("div", { className: "aui-thread-welcome-suggestion-display fade-in slide-in-from-bottom-2 @md:nth-[n+3]:block nth-[n+3]:hidden animate-in fill-mode-both duration-200", children: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(import_react11.SuggestionPrimitive.Trigger, { send: true, asChild: true, children: /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)(
+var ThreadSuggestionItem = ({ title, description }) => {
+  const runtime = (0, import_react11.useThreadRuntime)();
+  return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("div", { className: "aui-thread-welcome-suggestion-display fade-in slide-in-from-bottom-2 animate-in fill-mode-both duration-200", children: /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)(
     Button,
     {
       variant: "ghost",
       className: "aui-thread-welcome-suggestion h-auto w-full @md:flex-col flex-wrap items-start justify-start gap-1 rounded-2xl border px-4 py-3 text-left text-sm transition-colors hover:bg-muted",
+      onClick: () => runtime.append({
+        role: "user",
+        content: [{ type: "text", text: title }]
+      }),
       children: [
-        /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("span", { className: "aui-thread-welcome-suggestion-text-1 font-medium", children: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(import_react11.SuggestionPrimitive.Title, {}) }),
-        /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("span", { className: "aui-thread-welcome-suggestion-text-2 text-muted-foreground", children: /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(import_react11.SuggestionPrimitive.Description, {}) })
+        /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("span", { className: "aui-thread-welcome-suggestion-text-1 font-medium", children: title }),
+        description && /* @__PURE__ */ (0, import_jsx_runtime12.jsx)("span", { className: "aui-thread-welcome-suggestion-text-2 text-muted-foreground", children: description })
       ]
     }
-  ) }) });
+  ) });
 };
-var Composer = () => {
+var Composer = ({ placeholder }) => {
   return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(import_react11.ComposerPrimitive.Root, { className: "aui-composer-root relative mt-3 flex w-full flex-col", children: /* @__PURE__ */ (0, import_jsx_runtime12.jsxs)(import_react11.ComposerPrimitive.AttachmentDropzone, { className: "aui-composer-attachment-dropzone flex w-full flex-col rounded-2xl border border-input bg-background px-1 pt-2 outline-none transition-shadow has-[textarea:focus-visible]:border-ring has-[textarea:focus-visible]:ring-2 has-[textarea:focus-visible]:ring-ring/20 data-[dragging=true]:border-ring data-[dragging=true]:border-dashed data-[dragging=true]:bg-accent/50", children: [
     /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(ComposerAttachments, {}),
     /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
       import_react11.ComposerPrimitive.Input,
       {
-        placeholder: "Send a message...",
+        placeholder: placeholder ?? "Send a message...",
         className: "aui-composer-input mb-1 max-h-32 min-h-14 w-full resize-none bg-transparent px-4 pt-2 pb-3 text-sm outline-none placeholder:text-muted-foreground focus-visible:ring-0",
         rows: 1,
         autoFocus: true,
@@ -1517,9 +1538,23 @@ var EditComposer = () => {
   ] }) });
 };
 
+// src/components/chat.tsx
+var import_jsx_runtime13 = require("react/jsx-runtime");
+function TimbalChat({
+  workforceId,
+  baseUrl,
+  fetch: fetch2,
+  ...threadProps
+}) {
+  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_runtime13 = require("react/jsx-runtime");
+var import_jsx_runtime14 = require("react/jsx-runtime");
 var SessionContext = (0, import_react12.createContext)(void 0);
 var useSession = () => {
   const context = (0, import_react12.useContext)(SessionContext);
@@ -1583,7 +1618,7 @@ var SessionProvider = ({
       () => window.location.href = `/api/auth/login?return_to=${returnTo}`
     );
   }, []);
-  return /* @__PURE__ */ (0, import_jsx_runtime13.jsx)(
+  return /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(
     SessionContext.Provider,
     {
       value: {
@@ -1599,7 +1634,7 @@ var SessionProvider = ({
 
 // src/auth/guard.tsx
 var import_lucide_react6 = require("lucide-react");
-var import_jsx_runtime14 = require("react/jsx-runtime");
+var import_jsx_runtime15 = require("react/jsx-runtime");
 var AuthGuard = ({
   children,
   requireAuth = false,
@@ -1610,7 +1645,7 @@ var AuthGuard = ({
     return children;
   }
   if (loading) {
-    return /* @__PURE__ */ (0, import_jsx_runtime14.jsx)("div", { className: "flex items-center justify-center h-screen", children: /* @__PURE__ */ (0, import_jsx_runtime14.jsx)(import_lucide_react6.Loader2, { className: "w-8 h-8 animate-spin" }) });
+    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) {
     const returnTo = encodeURIComponent(
@@ -1623,6 +1658,7 @@ var AuthGuard = ({
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ActionBarPrimitive,
   AuthGuard,
   Avatar,
   AvatarFallback,
@@ -1630,6 +1666,7 @@ var AuthGuard = ({
   Button,
   ComposerAddAttachment,
   ComposerAttachments,
+  ComposerPrimitive,
   Dialog,
   DialogClose,
   DialogContent,
@@ -1638,10 +1675,13 @@ var AuthGuard = ({
   DialogTitle,
   DialogTrigger,
   MarkdownText,
+  MessagePrimitive,
   SessionProvider,
   Shimmer,
   SyntaxHighlighter,
   Thread,
+  ThreadPrimitive,
+  TimbalChat,
   TimbalRuntimeProvider,
   ToolFallback,
   Tooltip,
@@ -1658,5 +1698,9 @@ var AuthGuard = ({
   getAccessToken,
   getRefreshToken,
   refreshAccessToken,
-  useSession
+  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';
@@ -26,7 +27,52 @@ interface TimbalRuntimeProviderProps {
 }
 declare function TimbalRuntimeProvider({ workforceId, children, baseUrl, fetch: fetchFn, }: TimbalRuntimeProviderProps): react_jsx_runtime.JSX.Element;
 
-declare const Thread: FC;
+interface ThreadSuggestion {
+    title: string;
+    description?: string;
+}
+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" */
+    maxWidth?: string;
+    /** Welcome screen text */
+    welcome?: ThreadWelcomeConfig;
+    /** Suggestion chips shown on the welcome screen */
+    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>;
+
+interface TimbalChatProps extends Omit<TimbalRuntimeProviderProps, "children">, ThreadProps {
+}
+declare function TimbalChat({ workforceId, baseUrl, fetch, ...threadProps }: TimbalChatProps): react_jsx_runtime.JSX.Element;
 
 declare const MarkdownText: React.MemoExoticComponent<() => react_jsx_runtime.JSX.Element>;
 
@@ -113,4 +159,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, 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, 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';
@@ -26,7 +27,52 @@ interface TimbalRuntimeProviderProps {
 }
 declare function TimbalRuntimeProvider({ workforceId, children, baseUrl, fetch: fetchFn, }: TimbalRuntimeProviderProps): react_jsx_runtime.JSX.Element;
 
-declare const Thread: FC;
+interface ThreadSuggestion {
+    title: string;
+    description?: string;
+}
+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" */
+    maxWidth?: string;
+    /** Welcome screen text */
+    welcome?: ThreadWelcomeConfig;
+    /** Suggestion chips shown on the welcome screen */
+    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>;
+
+interface TimbalChatProps extends Omit<TimbalRuntimeProviderProps, "children">, ThreadProps {
+}
+declare function TimbalChat({ workforceId, baseUrl, fetch, ...threadProps }: TimbalChatProps): react_jsx_runtime.JSX.Element;
 
 declare const MarkdownText: React.MemoExoticComponent<() => react_jsx_runtime.JSX.Element>;
 
@@ -113,4 +159,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, 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, useSession };

package/dist/index.esm.js

@@ -1216,8 +1216,8 @@ import {
   ComposerPrimitive as ComposerPrimitive2,
   ErrorPrimitive,
   MessagePrimitive as MessagePrimitive2,
-  SuggestionPrimitive,
-  ThreadPrimitive
+  ThreadPrimitive,
+  useThreadRuntime
 } from "@assistant-ui/react";
 import {
   ArrowDownIcon,
@@ -1231,34 +1231,48 @@ import {
   SquareIcon
 } from "lucide-react";
 import { jsx as jsx12, jsxs as jsxs7 } from "react/jsx-runtime";
-var Thread = () => {
+var Thread = ({
+  className,
+  maxWidth = "44rem",
+  welcome,
+  suggestions,
+  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,
     {
-      className: "aui-root aui-thread-root @container flex h-full flex-col bg-background",
-      style: {
-        ["--thread-max-width"]: "44rem"
-      },
+      className: cn(
+        "aui-root aui-thread-root @container flex h-full flex-col bg-background",
+        className
+      ),
+      style: { ["--thread-max-width"]: maxWidth },
       children: /* @__PURE__ */ jsxs7(
         ThreadPrimitive.Viewport,
         {
           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, {}) }),
+            /* @__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, {})
+              /* @__PURE__ */ jsx12(ScrollToBottomSlot, {}),
+              /* @__PURE__ */ jsx12(ComposerSlot, { placeholder: composerPlaceholder })
             ] })
           ]
         }
@@ -1277,8 +1291,8 @@ var ThreadScrollToBottom = () => {
     }
   ) });
 };
-var ThreadWelcome = () => {
-  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: [
+var ThreadWelcome = ({ config, suggestions }) => {
+  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" }),
@@ -1298,42 +1312,40 @@ var ThreadWelcome = () => {
           }
         )
       ] }),
-      /* @__PURE__ */ jsx12("h1", { className: "aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both font-semibold text-2xl duration-200", children: "How can I help you today?" }),
-      /* @__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: "Send a message to start a conversation." })
+      /* @__PURE__ */ jsx12("h1", { className: "aui-thread-welcome-message-inner fade-in slide-in-from-bottom-1 animate-in fill-mode-both font-semibold text-2xl duration-200", children: config?.heading ?? "How can I help you today?" }),
+      /* @__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." })
     ] }) }),
-    /* @__PURE__ */ jsx12(ThreadSuggestions, {})
-  ] });
+    suggestions && suggestions.length > 0 && /* @__PURE__ */ jsx12(ThreadSuggestions, { suggestions })
+  ] }) });
 };
-var ThreadSuggestions = () => {
-  return /* @__PURE__ */ jsx12("div", { className: "aui-thread-welcome-suggestions grid w-full @md:grid-cols-2 gap-2 pb-4", children: /* @__PURE__ */ jsx12(
-    ThreadPrimitive.Suggestions,
-    {
-      components: {
-        Suggestion: ThreadSuggestionItem
-      }
-    }
-  ) });
+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)) });
 };
-var ThreadSuggestionItem = () => {
-  return /* @__PURE__ */ jsx12("div", { className: "aui-thread-welcome-suggestion-display fade-in slide-in-from-bottom-2 @md:nth-[n+3]:block nth-[n+3]:hidden animate-in fill-mode-both duration-200", children: /* @__PURE__ */ jsx12(SuggestionPrimitive.Trigger, { send: true, asChild: true, children: /* @__PURE__ */ jsxs7(
+var ThreadSuggestionItem = ({ title, description }) => {
+  const runtime = useThreadRuntime();
+  return /* @__PURE__ */ jsx12("div", { className: "aui-thread-welcome-suggestion-display fade-in slide-in-from-bottom-2 animate-in fill-mode-both duration-200", children: /* @__PURE__ */ jsxs7(
     Button,
     {
       variant: "ghost",
       className: "aui-thread-welcome-suggestion h-auto w-full @md:flex-col flex-wrap items-start justify-start gap-1 rounded-2xl border px-4 py-3 text-left text-sm transition-colors hover:bg-muted",
+      onClick: () => runtime.append({
+        role: "user",
+        content: [{ type: "text", text: title }]
+      }),
       children: [
-        /* @__PURE__ */ jsx12("span", { className: "aui-thread-welcome-suggestion-text-1 font-medium", children: /* @__PURE__ */ jsx12(SuggestionPrimitive.Title, {}) }),
-        /* @__PURE__ */ jsx12("span", { className: "aui-thread-welcome-suggestion-text-2 text-muted-foreground", children: /* @__PURE__ */ jsx12(SuggestionPrimitive.Description, {}) })
+        /* @__PURE__ */ jsx12("span", { className: "aui-thread-welcome-suggestion-text-1 font-medium", children: title }),
+        description && /* @__PURE__ */ jsx12("span", { className: "aui-thread-welcome-suggestion-text-2 text-muted-foreground", children: description })
       ]
     }
-  ) }) });
+  ) });
 };
-var Composer = () => {
+var Composer = ({ placeholder }) => {
   return /* @__PURE__ */ jsx12(ComposerPrimitive2.Root, { className: "aui-composer-root relative mt-3 flex w-full flex-col", children: /* @__PURE__ */ jsxs7(ComposerPrimitive2.AttachmentDropzone, { className: "aui-composer-attachment-dropzone flex w-full flex-col rounded-2xl border border-input bg-background px-1 pt-2 outline-none transition-shadow has-[textarea:focus-visible]:border-ring has-[textarea:focus-visible]:ring-2 has-[textarea:focus-visible]:ring-ring/20 data-[dragging=true]:border-ring data-[dragging=true]:border-dashed data-[dragging=true]:bg-accent/50", children: [
     /* @__PURE__ */ jsx12(ComposerAttachments, {}),
     /* @__PURE__ */ jsx12(
       ComposerPrimitive2.Input,
       {
-        placeholder: "Send a message...",
+        placeholder: placeholder ?? "Send a message...",
         className: "aui-composer-input mb-1 max-h-32 min-h-14 w-full resize-none bg-transparent px-4 pt-2 pb-3 text-sm outline-none placeholder:text-muted-foreground focus-visible:ring-0",
         rows: 1,
         autoFocus: true,
@@ -1481,6 +1493,29 @@ var EditComposer = () => {
   ] }) });
 };
 
+// src/components/chat.tsx
+import { jsx as jsx13 } from "react/jsx-runtime";
+function TimbalChat({
+  workforceId,
+  baseUrl,
+  fetch: fetch2,
+  ...threadProps
+}) {
+  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,
@@ -1489,7 +1524,7 @@ import {
   useEffect as useEffect4,
   useState as useState5
 } from "react";
-import { jsx as jsx13 } from "react/jsx-runtime";
+import { jsx as jsx14 } from "react/jsx-runtime";
 var SessionContext = createContext(void 0);
 var useSession = () => {
   const context = useContext(SessionContext);
@@ -1553,7 +1588,7 @@ var SessionProvider = ({
       () => window.location.href = `/api/auth/login?return_to=${returnTo}`
     );
   }, []);
-  return /* @__PURE__ */ jsx13(
+  return /* @__PURE__ */ jsx14(
     SessionContext.Provider,
     {
       value: {
@@ -1569,7 +1604,7 @@ var SessionProvider = ({
 
 // src/auth/guard.tsx
 import { Loader2 } from "lucide-react";
-import { jsx as jsx14 } from "react/jsx-runtime";
+import { jsx as jsx15 } from "react/jsx-runtime";
 var AuthGuard = ({
   children,
   requireAuth = false,
@@ -1580,7 +1615,7 @@ var AuthGuard = ({
     return children;
   }
   if (loading) {
-    return /* @__PURE__ */ jsx14("div", { className: "flex items-center justify-center h-screen", children: /* @__PURE__ */ jsx14(Loader2, { className: "w-8 h-8 animate-spin" }) });
+    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) {
     const returnTo = encodeURIComponent(
@@ -1592,6 +1627,7 @@ var AuthGuard = ({
   return children;
 };
 export {
+  ActionBarPrimitive2 as ActionBarPrimitive,
   AuthGuard,
   Avatar,
   AvatarFallback,
@@ -1599,6 +1635,7 @@ export {
   Button,
   ComposerAddAttachment,
   ComposerAttachments,
+  ComposerPrimitive3 as ComposerPrimitive,
   Dialog,
   DialogClose,
   DialogContent,
@@ -1607,10 +1644,13 @@ export {
   DialogTitle,
   DialogTrigger,
   MarkdownText,
+  MessagePrimitive3 as MessagePrimitive,
   SessionProvider,
   Shimmer,
   syntax_highlighter_default as SyntaxHighlighter,
   Thread,
+  ThreadPrimitive2 as ThreadPrimitive,
+  TimbalChat,
   TimbalRuntimeProvider,
   ToolFallback,
   Tooltip,
@@ -1627,5 +1667,9 @@ export {
   getAccessToken,
   getRefreshToken,
   refreshAccessToken,
-  useSession
+  useComposerRuntime,
+  useMessageRuntime,
+  useSession,
+  useThread,
+  useThreadRuntime2 as useThreadRuntime
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timbal-ai/timbal-react",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "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",