@timbal-ai/timbal-react 0.2.2 → 0.3.0

package/README.md

@@ -29,6 +29,17 @@ The package ships pre-built Tailwind class names. Add this `@source` line to you
 
 > Adjust the path if your CSS file lives at a different depth relative to `node_modules`.
 
+### Companion stylesheet (optional)
+
+For blueprint-style polish (welcome animations, suggestion chips, tool indicators), import the shipped companion CSS once. Requires Tailwind v4 design tokens (`--primary`, etc.) in your app:
+
+```ts
+// src/main.tsx
+import "@timbal-ai/timbal-react/styles.css";
+```
+
+You can omit this entirely and style components yourself — the package does not bundle mandatory CSS beyond what Tailwind scans from `dist/`.
+
 ### CSS imports
 
 Import these stylesheets once in your app entry:
@@ -78,6 +89,20 @@ export default function App() {
 />
 ```
 
+Suggestions also accept a function (sync or async) for per-user or server-driven chips:
+
+```tsx
+<TimbalChat
+  workforceId="your-workforce-id"
+  suggestions={async () => {
+    const res = await authFetch("/api/suggestions");
+    return res.json(); // ThreadSuggestion[]
+  }}
+/>
+```
+
+Each chip supports `icon`, `description`, and `prompt` (sent instead of `title` when clicked).
+
 ### Placeholder and width
 
 ```tsx
@@ -104,6 +129,66 @@ const [workforceId, setWorkforceId] = useState("agent-a");
 <TimbalChat workforceId={workforceId} key={workforceId} />
 ```
 
+### Drop-in shell (header + agent picker)
+
+`TimbalChatShell` wraps the common blueprint layout: brand area, workforce selector, optional header actions, and a full-height chat. When `workforceId` is omitted, it fetches `{baseUrl}/workforce` and selects the first agent automatically:
+
+```tsx
+import { TimbalChatShell, Button, useSession } from "@timbal-ai/timbal-react";
+
+export default function App() {
+  const { logout, isAuthenticated } = useSession();
+
+  return (
+    <TimbalChatShell
+      brand={<span className="font-semibold">Acme AI</span>}
+      headerActions={
+        isAuthenticated ? (
+          <Button variant="ghost" size="sm" onClick={logout}>
+            Log out
+          </Button>
+        ) : null
+      }
+      welcome={{ heading: "How can I help you today?" }}
+      suggestions={[{ title: "Get started" }]}
+    />
+  );
+}
+```
+
+Pass `workforceId` to lock the agent and hide the built-in selector. Use `hideWorkforceSelector` when you render your own picker.
+
+### Workforce list hook
+
+For custom layouts (sidebar tree, command palette), use `useWorkforces` with the optional `WorkforceSelector`:
+
+```tsx
+import {
+  TimbalChat,
+  useWorkforces,
+  WorkforceSelector,
+} from "@timbal-ai/timbal-react";
+
+function ChatWithPicker() {
+  const { workforces, selectedId, setSelectedId, isLoading } = useWorkforces();
+
+  if (isLoading) return <div>Loading agents…</div>;
+
+  return (
+    <div className="flex h-screen flex-col">
+      <WorkforceSelector
+        workforces={workforces}
+        value={selectedId}
+        onChange={setSelectedId}
+      />
+      <TimbalChat workforceId={selectedId} key={selectedId} className="min-h-0 flex-1" />
+    </div>
+  );
+}
+```
+
+`useWorkforces` accepts `baseUrl`, `fetch`, and `pickInitial` (custom resolver for the default selection). It returns `selected`, `error`, and `refresh()` as well.
+
 ---
 
 ## Splitting the runtime and UI
@@ -138,6 +223,52 @@ Useful when your API is mounted at a subpath (e.g. behind a reverse proxy):
 </TimbalRuntimeProvider>
 ```
 
+### Attachments
+
+Attachments are **opt-in**. Pass `attachments` to enable the composer `+` button, drag-and-drop, and multimodal prompts:
+
+```tsx
+<TimbalChat workforceId="your-workforce-id" attachments />
+```
+
+When enabled, each file is uploaded via `POST` to `${baseUrl}/files/upload` (multipart `file` field). The response must include `{ url }` (or `{ signed_url }` / `{ id }`). That URL is sent to the workforce as `{ type: "file", file: "<url>" }` alongside `{ type: "text", text: "..." }` when the user typed a message.
+
+Your API must expose that upload route (the Timbal blueprint API includes it). `authFetch` is used by default and must **not** force a `Content-Type` header on `FormData` uploads.
+
+#### Variants
+
+```tsx
+// Default upload adapter
+<TimbalChat workforceId="..." attachments />
+
+// Custom endpoint or MIME whitelist
+<TimbalChat
+  workforceId="..."
+  attachments={{ uploadUrl: "/api/uploads", accept: "image/*,application/pdf" }}
+/>
+
+// Fully custom adapter (e.g. presigned S3)
+<TimbalChat workforceId="..." attachments={myAdapter} />
+
+// Explicitly off (default when prop is omitted)
+<TimbalChat workforceId="..." attachments={null} />
+```
+
+#### Power-user exports
+
+```tsx
+import {
+  createDefaultAttachmentAdapter,
+  createUploadAttachmentAdapter,
+  resolveAttachmentAdapter,
+  parseSSELine,
+  AssistantRuntimeProvider,
+  useTimbalStream,
+} from "@timbal-ai/timbal-react";
+```
+
+`parseSSELine` and `AssistantRuntimeProvider` are re-exported so custom runtimes do not need a second `@assistant-ui/react` import for those symbols. `useTimbalStream` exposes the same SSE reducer and `send` / `reload` / `cancel` API without mounting `<Thread>`.
+
 ### Custom fetch function
 
 Pass your own `fetch` to add headers, inject tokens, or proxy requests:
@@ -168,8 +299,9 @@ Use the `components` prop on `TimbalChat` or `Thread` to replace any part of the
 | `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 |
+| `Composer` | `placeholder` (+ full `ComposerProps`) | built-in composer bar |
+| `Welcome` | `config`, `suggestions`, `Suggestions` | built-in welcome screen |
+| `Suggestions` | `suggestions` | built-in suggestion chips |
 | `ScrollToBottom` | none | built-in scroll button |
 
 Custom slot components read their data via hooks — no props are passed automatically except where noted above.
@@ -281,6 +413,81 @@ These are re-exported from `@assistant-ui/react` for use inside custom slot comp
 
 ---
 
+## Artifacts
+
+Agents can return structured JSON **artifacts** — charts, tables, choice widgets, and interactive UI — instead of plain text. The chat UI renders them automatically from tool results or inline ` ```timbal-artifact ` fences.
+
+### Tell the agent about the schema
+
+Import the ready-made instruction block and append it to your workforce system prompt (or blueprint tool-result docs):
+
+```ts
+import { ARTIFACT_AGENT_INSTRUCTIONS } from "@timbal-ai/timbal-react";
+
+const systemPrompt = `${basePrompt}\n\n${ARTIFACT_AGENT_INSTRUCTIONS}`;
+```
+
+`ARTIFACT_AGENT_INSTRUCTIONS` documents every built-in `type` (`chart`, `table`, `question`, `html`, `json`, `ui`) and the full interactive **`ui` node palette** (hover tooltips, buttons, toggles, sliders, drag).
+
+### Subscribe to interactive events
+
+`ui` artifacts can fire `{ kind: "emit" }` actions (e.g. after a slider commit or drag). Handle them with `onArtifactEvent` on `Thread` or `TimbalChat`:
+
+```tsx
+<TimbalChat
+  workforceId="your-workforce-id"
+  onArtifactEvent={(event) => {
+    console.log(event.name, event.payload);
+    // e.g. refetch data, update local UI, call your API
+  }}
+/>
+```
+
+When using `Thread` directly:
+
+```tsx
+<TimbalRuntimeProvider workforceId="your-workforce-id">
+  <Thread
+    onArtifactEvent={(event) => console.log(event.name, event.payload)}
+  />
+</TimbalRuntimeProvider>
+```
+
+Built-in `{ kind: "message" }` actions already append a user message — you only need `onArtifactEvent` for host-side logic beyond that.
+
+### Custom artifact renderers
+
+Register extra `type` values or override defaults:
+
+```tsx
+<TimbalChat
+  workforceId="..."
+  artifacts={{
+    renderers: {
+      "my:widget": MyWidgetRenderer,
+    },
+  }}
+/>
+```
+
+Extend the interactive palette with host-registered `custom` nodes:
+
+```tsx
+import {
+  UiCustomNodeRegistryProvider,
+  TimbalRuntimeProvider,
+  Thread,
+} from "@timbal-ai/timbal-react";
+
+<UiCustomNodeRegistryProvider renderers={{ "price-card": PriceCard }}>
+  <TimbalRuntimeProvider workforceId="...">
+    <Thread />
+  </TimbalRuntimeProvider>
+</UiCustomNodeRegistryProvider>
+```
+
+---
+
 ## API reference
 
 ### `TimbalChat` props
@@ -292,11 +499,16 @@ These are re-exported from `@assistant-ui/react` for use inside custom slot comp
 | `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) |
+| `attachments` | `boolean \| { uploadUrl?, accept? } \| AttachmentAdapter \| null` | off | `true` or a config object enables the built-in upload adapter; `null` disables; omitted = off |
+| `attachmentsUploadUrl` | `string` | — | Shorthand: enables the default adapter with a custom upload URL |
+| `attachmentsAccept` | `string` | — | Shorthand: MIME `accept` for the default adapter |
+| `debug` | `boolean` | `false` | Log every parsed SSE event to the console with a `[timbal]` prefix |
 | `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 |
+| `onArtifactEvent` | `(event: UiEventEnvelope) => void` | — | Called when a `ui` artifact fires an `emit` action |
 | `maxWidth` | `string` | `"44rem"` | Max width of the message column |
 | `className` | `string` | — | Extra classes on the root element |
 
@@ -311,6 +523,23 @@ Same as `TimbalChat` minus `workforceId`, `baseUrl`, and `fetch` (those live on
 | `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 |
+| `attachments` | same as `TimbalChat` | off | Enable uploads on the runtime (usually set on `TimbalChat` instead) |
+| `attachmentsUploadUrl` | `string` | — | Shorthand upload URL for the default adapter |
+| `attachmentsAccept` | `string` | — | Shorthand MIME accept for the default adapter |
+| `debug` | `boolean` | `false` | SSE debug logging (see above) |
+
+### `TimbalChatShell` props
+
+Extends all `TimbalChat` props except `workforceId` is optional.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `workforceId` | `string` | auto from API | When set, skips fetching and hides the built-in selector |
+| `brand` | `ReactNode` | — | Logo or title at the start of the header |
+| `headerActions` | `ReactNode` | — | Trailing header content (logout, theme toggle, etc.) |
+| `hideWorkforceSelector` | `boolean` | `false` | Hide the built-in `<select>` even when multiple agents exist |
+| `className` | `string` | — | Classes on the outer `h-screen` flex container |
+| `headerClassName` | `string` | — | Classes on the header bar |
 
 ---
 
@@ -351,6 +580,30 @@ export default function App() {
 
 When `enabled` is `false`, both `SessionProvider` and `AuthGuard` are transparent — no redirects, no API calls.
 
+### Embedding in an iframe
+
+When the app runs inside an iframe, `SessionProvider` detects embedding and skips the normal cookie refresh flow. Instead:
+
+1. The child posts `{ type: "timbal:request-session" }` to `window.parent`.
+2. The parent responds with `{ type: "timbal:auth", token: "<access>", refreshToken?: "<refresh>" }`.
+3. Tokens are stored in localStorage and `fetchCurrentUser()` runs as usual.
+
+`useSession()` exposes `isEmbedded: boolean` so you can adjust UI (e.g. hide logout redirects that assume a top-level window).
+
+```tsx
+// Parent page
+iframe.contentWindow?.postMessage(
+  { type: "timbal:auth", token: accessToken, refreshToken },
+  "*",
+);
+
+window.addEventListener("message", (e) => {
+  if (e.data?.type === "timbal:request-session") {
+    // inject tokens as above
+  }
+});
+```
+
 ### `useSession` hook
 
 Access the current session anywhere inside `SessionProvider`:
@@ -359,7 +612,7 @@ Access the current session anywhere inside `SessionProvider`:
 import { useSession } from "@timbal-ai/timbal-react";
 
 function Header() {
-  const { user, isAuthenticated, loading, logout } = useSession();
+  const { user, isAuthenticated, isEmbedded, loading, logout } = useSession();
   if (loading) return null;
   return (
     <header>
@@ -405,15 +658,34 @@ if (res.ok) {
 
 | Export | Description |
 |---|---|
+| `TimbalChatShell` | Header + workforce picker + full-height `TimbalChat` |
 | `Thread` | Full chat UI — messages, composer, attachments, action bar |
+| `Composer` | Standalone composer bar (for custom thread layouts) |
+| `Suggestions` | Suggestion chip grid/row; use with `useResolvedSuggestions` |
+| `WorkforceSelector` | Styled native `<select>` for agent switching |
 | `MarkdownText` | Markdown renderer with GFM, math (KaTeX), and syntax highlighting |
 | `ToolFallback` | Animated "Using tool: …" indicator shown while a tool runs |
+| `ARTIFACT_AGENT_INSTRUCTIONS` | Markdown block to paste into agent system prompts |
+| `ArtifactRegistryProvider` | Scope custom artifact renderers |
+| `UiEventProvider` | Low-level provider for `ui` artifact `emit` actions |
+| `UiCustomNodeRegistryProvider` | Register `{ kind: "custom" }` node renderers |
+| `ArtifactView` | Render a single artifact object |
+| `parseArtifactFromToolResult` | Parse tool output into an artifact |
 | `SyntaxHighlighter` | Shiki-based code highlighter (vitesse-dark / vitesse-light themes) |
 | `UserMessageAttachments` | Attachment thumbnails in user messages |
 | `ComposerAttachments` | Attachment previews inside the composer |
 | `ComposerAddAttachment` | "+" button to add attachments |
 | `TooltipIconButton` | Icon button with a tooltip |
 
+### Hooks
+
+| Export | Description |
+|---|---|
+| `useWorkforces` | Fetch `{baseUrl}/workforce` and track selection |
+| `useTimbalStream` | Low-level SSE chat state without `<Thread>` |
+| `useTimbalRuntime` | Access runtime context inside custom providers |
+| `useResolvedSuggestions` | Resolve static/async `SuggestionsSource` to an array |
+
 ### UI primitives
 
 Re-exported Radix UI wrappers pre-styled to match the Timbal design system:
@@ -424,62 +696,72 @@ 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:
+App shell with optional auth, using `TimbalChatShell` (agent list + chat in one component):
+
+```tsx
+// src/App.tsx
+import {
+  SessionProvider,
+  AuthGuard,
+  TooltipProvider,
+  TimbalChatShell,
+} 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;
+
+export default function App() {
+  return (
+    <SessionProvider enabled={isAuthEnabled}>
+      <TooltipProvider>
+        <BrowserRouter>
+          <AuthGuard requireAuth enabled={isAuthEnabled}>
+            <Routes>
+              <Route path="/" element={<Home />} />
+            </Routes>
+          </AuthGuard>
+        </BrowserRouter>
+      </TooltipProvider>
+    </SessionProvider>
+  );
+}
+```
 
 ```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 { TimbalChatShell, Button, 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(() => {});
-  }, []);
+  const { logout, isAuthenticated } = useSession();
 
   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 />
+    <TimbalChatShell
+      brand={<span className="text-sm font-semibold">My App</span>}
+      headerActions={
+        isAuthEnabled && isAuthenticated ? (
+          <Button variant="ghost" size="icon" onClick={logout} aria-label="Log out">
+            <LogOut className="size-4" />
           </Button>
-        )}
-      </header>
-
-      <TimbalChat
-        workforceId={selectedId}
-        key={selectedId}
-        className="flex-1 min-h-0"
-        welcome={{ heading: "How can I help you today?" }}
-      />
-    </div>
+        ) : null
+      }
+      welcome={{ heading: "How can I help you today?" }}
+      suggestions={[
+        { title: "Summarize this week", description: "Recent activity at a glance" },
+        { title: "What can you help with?" },
+      ]}
+      attachments
+      debug={import.meta.env.DEV}
+    />
   );
 }
 ```
 
+For a fully custom header, combine `useWorkforces` with `TimbalChat` instead of `TimbalChatShell` (see [Workforce list hook](#workforce-list-hook)).
+
 ---
 
 ## Local development