@agno-hq/chat-react 0.1.1 → 0.3.1

package/README.md

@@ -1,7 +1,17 @@
 # @agno-hq/chat-react
 
-Headless React hook (`useAgnoChat`) plus drop-in UI components for streaming **any
-Agno agent, team, or workflow** from an [AgentOS](https://docs.agno.com) backend.
+Composable, embeddable React components for [AgentOS](https://docs.agno.com) —
+a headless hook, a provider for building your own layout, and drop-in embeds for
+streaming **any Agno agent, team, or workflow**.
+
+| Subpath | Contents |
+| --- | --- |
+| `@agno-hq/chat-react` | Everything below. |
+| `@agno-hq/chat-react/core` | `AgnoClient`, run streaming, event helpers, types. No React rendering. |
+| `@agno-hq/chat-react/chat` | `useAgnoChat`, `ChatProvider`, `AgnoChat`, and every building block. |
+| `@agno-hq/chat-react/styles.css` | Tokens + component styles. |
+| `@agno-hq/chat-react/tokens.css` | CSS variables only. |
+| `@agno-hq/chat-react/fonts.css` | Inter + DM Mono (optional). |
 
 It speaks the AgentOS HTTP run protocol directly: it POSTs to the run endpoint,
 parses the streamed events, and accumulates them into render-ready messages —
@@ -9,16 +19,69 @@ content, tool calls, reasoning, citations, media — while exposing the raw even
 feed, live status, and human-in-the-loop pauses.
 
 ```tsx
-import { AgnoChat } from '@agno-hq/chat-react'
+import { AgnoChat } from '@agno-hq/chat-react/chat'
 import '@agno-hq/chat-react/styles.css'
+import '@agno-hq/chat-react/fonts.css' // optional — Inter + DM Mono
 
 export default function Page() {
-  return <AgnoChat baseUrl="http://localhost:7777" showEventLog allowFiles />
+  return <AgnoChat baseUrl="http://localhost:7777" allowFiles />
 }
 ```
 
-That's the zero-wiring widget: it discovers the agents/teams/workflows on your
-AgentOS, shows a selector, and runs a full chat. For full control, use the hook.
+That's the zero-wiring embed: it discovers the agents/teams/workflows on your
+AgentOS and runs a full chat. It renders **no header** and fills its container,
+so it drops into a page, a card, a drawer or a modal without fighting your
+layout — put your own chrome in the `header` slot.
+
+Support chat on every page is the same component in launcher mode:
+
+```tsx
+<AgnoChat mode="launcher" baseUrl="..." launcherLabel="Chat with us" />
+```
+
+### Compose it instead
+
+`<ChatProvider>` runs the chat and shares it through context, so every component
+below reads it with no props:
+
+```tsx
+import { ChatProvider, MessageList, ChatInput } from '@agno-hq/chat-react/chat'
+
+<ChatProvider baseUrl="http://localhost:7777" entity={agent}>
+  <MyOwnHeader />
+  <MessageList />
+  <ChatInput />
+</ChatProvider>
+```
+
+Reach for `useChatContext()` to drive it from your own components, or call
+`useAgnoChat` directly and render nothing of ours.
+
+### Customize it
+
+Three independent levers:
+
+```tsx
+/* 1. Tokens — palette, radii and shadows from agno-os/globals.css */
+:root { --color-brand-brand: 99, 102, 241; --agno-radius-lg: 1.25rem; }
+
+/* 2. Slots — every element is addressable by name */
+<AgnoChat classNames={{ root: 'rounded-2xl', textarea: 'font-mono' }} />
+
+/* 3. Replacement — swap any piece for your own */
+<ChatWindow composer={<MyComposer />} header={<MyBar />} />
+```
+
+The built-in classes stay on the elements, so Tailwind utilities layer on top
+rather than replacing them. Import only `tokens.css` (or nothing) to style from
+scratch.
+
+### Storybook
+
+`npm run storybook` runs the component gallery locally; every story streams
+against a scripted in-memory backend, so it exercises the real hook and the real
+event reducers without an AgentOS running. Pushes to `main` publish it to GitHub
+Pages via `.github/workflows/storybook.yml`.
 
 ---
 
@@ -89,32 +152,330 @@ agent/team/workflow id — the same hook drives all three.
 
 ## Components
 
-All components are styled by `@agno-hq/chat-react/styles.css` (dark by default; add
-the `agno-light` class on a wrapper for light mode). Every piece is exported so
-you can compose your own layout.
+All components are styled by `@agno-hq/chat-react/styles.css`, which carries the
+Agno OS design system — the same colour tokens, radii, Inter/DM Mono type scale
+and chat layout as the AgentOS chat page. It is dark by default; add the
+`agno-light` class on a wrapper for light mode (`agno-dark` is accepted too, for
+apps that toggle both). Every piece is exported so you can compose your own
+layout.
+
+Theme it by overriding the tokens on your wrapper — they are the AgentOS ones,
+as `R, G, B` triples:
+
+```css
+.agno-root.my-brand {
+  --color-brand-brand: 255, 64, 23;
+  --color-background: 17, 17, 19;
+  --color-background-secondary: 39, 39, 42;
+}
+```
 
 | Component | Purpose |
 |---|---|
-| `<AgnoChat>` | All-in-one widget: discovery, selector, chat, optional event log. |
+| `<AgnoChat>` | All-in-one widget: discovery, selector, chat, optional per-run event feed. |
 | `<ChatWindow chat={chat}>` | Full chat surface built from a `useAgnoChat` result. |
+| `<ChatLauncher>` | Floating support-widget shell: a corner bubble that opens any chat surface. |
+| `<QuickPrompts>` | Suggested-prompt chips. |
 | `<MessageList>` | Auto-scrolling transcript with live status + footer slot. |
-| `<Message>` | A single message: content, tools, reasoning, media, citations. |
-| `<ChatInput>` | Multiline input with file attach, send, and stop. |
+| `<Message>` | A single message: content, behind-the-scenes panel, media, citations, follow-ups. |
+| `<BehindTheScenes>` | One collapsible timeline over a run's reasoning, tools, member turns, steps and events — doubles as the live status line. |
+| `<ChatInput>` | Multiline input with file attach, send, and stop; opens up for @mentions, context chips and a custom textarea. |
 | `<ToolCalls>` | Collapsible tool-call cards (name, args, result, status). |
 | `<Reasoning>` | Collapsible reasoning-steps panel. |
-| `<Citations>` | References / source URLs. |
+| `<Citations>` | The sources behind an answer, as linked cards. |
+| `<Followups>` | "Related questions" — the follow-up prompts an agent suggests after its answer. |
 | `<Multimedia>` | Images, video, and audio attachments. |
 | `<StatusIndicator>` | Animated "what is it doing now" line. |
-| `<EventLog>` | Developer feed of every raw run event. |
+| `<EventLog>` | Developer feed of raw run events — render it yourself from `chat.events`. |
 | `<HumanInput>` | Human-in-the-loop panel (confirm / reject / input). |
 | `<EntitySelector>` | Dropdown of agents, teams, and workflows. |
 | `<SessionList>` | Sidebar of past sessions — click to load, trash to delete. |
-| `<Markdown>` | The built-in lightweight Markdown renderer. |
+| `<Markdown>` | Markdown, rendered by Streamdown — GFM, and repair for half-written text mid-stream. |
+
+### Inline, or a floating support widget
+
+`<AgnoChat>` renders inline by default — a panel wherever you put it, sized by
+`width` and `height`:
+
+```tsx
+<AgnoChat baseUrl="http://localhost:7777" width={720} height={560} />
+```
+
+`mode="launcher"` turns it into the support-chat layout instead: a bubble pinned
+to a corner of the viewport that opens the chat. Mount it once, anywhere in your
+app — it renders into `document.body`, so no wrapper can clip it.
 
-### Bring your own Markdown
+```tsx
+<AgnoChat
+  baseUrl="http://localhost:7777"
+  mode="launcher"
+  position="bottom-right"
+  launcherLabel="Chat with us"
+  width={400}
+  height={620}
+/>
+```
+
+| Prop | Default | Description |
+|---|---|---|
+| `mode` | `'inline'` | `'inline'` renders in place; `'launcher'` pins a bubble to a corner. |
+| `position` | `'bottom-right'` | Corner to pin to: also `bottom-left`, `top-right`, `top-left`. |
+| `offset` | `24` | Distance from both edges of that corner. Number means px. |
+| `panel` | `'popover'` | How far it opens: a corner popover, or `'fullscreen'` over the page. |
+| `width` / `height` | `400` / `620` | Size of the popover (and of the inline panel). |
+| `launcherLabel` | — | Text beside the bubble glyph. Icon-only without it. |
+| `launcherIcon` | speech bubble | Replaces the default glyph. |
+| `defaultOpen` | `false` | Open on first render. |
+| `open` / `onOpenChange` | — | Control the open state yourself (e.g. from your own "Help" button). |
+
+A `'fullscreen'` panel covers the page and closes from an X in the chat header;
+a popover closes from the bubble, which becomes an X. Escape closes either, and
+below 480px wide a popover goes full-screen on its own. The conversation is kept
+across close/open — a run that is still streaming keeps streaming.
+
+To give your own layout the same behaviour, wrap it in `<ChatLauncher>`:
+
+```tsx
+<ChatLauncher position="bottom-left" panel="fullscreen" label="Support">
+  <ChatWindow chat={chat} />
+</ChatLauncher>
+```
+
+### Errors
+
+A failed run leaves its message on `chat.error`, but nothing is rendered by
+default — raw backend errors are long, and they crowd a narrow window. Opt in
+with `showErrors` on `<AgnoChat>` or `<ChatWindow>`:
+
+```tsx
+<AgnoChat baseUrl="http://localhost:7777" showErrors />
+```
+
+Or render it wherever suits your layout — a toast, say:
+
+```tsx
+{chat.error && <Toast>{chat.error}</Toast>}
+```
+
+### Quick prompts
+
+`quickPrompts` offers suggested prompts while the transcript is empty. Clicking
+one sends it. A chip is either the prompt itself, or a short label that sends
+something longer:
+
+```tsx
+<AgnoChat
+  baseUrl="http://localhost:7777"
+  quickPrompts={[
+    'What can you do?',
+    { label: 'Pricing', prompt: 'How does pricing work?' },
+    { label: 'Talk to a human', prompt: 'I would like to talk to a human.' },
+  ]}
+/>
+```
+
+`<ChatWindow>` takes the same prop, plus `onQuickPrompt` to do something other
+than send the text. Render `<QuickPrompts>` yourself to place the chips
+elsewhere.
+
+### Building on the composer
+
+`<ChatInput>` is the AgentOS dock: an auto-growing textarea, attach, send and
+stop. `compact` trades the dock for one row — the field with the buttons beside
+it — for a launcher, a sidebar, anywhere narrow; `compactInput` on `<AgnoChat>`
+and `<ChatWindow>` switches their built-in composer to it:
+
+```tsx
+<AgnoChat baseUrl="http://localhost:7777" mode="launcher" compactInput />
+<ChatInput compact placeholder="Send a message" />
+```
 
-The built-in renderer covers code blocks, inline code, bold/italic, links,
-headings and lists. For full GFM (tables, etc.), pass `renderMarkdown`:
+When a product needs more from the composer — an @mention menu, context
+chips, a highlighted draft — it opens up rather than being replaced:
+
+```tsx
+<ChatInput
+  value={draft}                           // own the draft
+  onValueChange={setDraft}
+  textareaRef={inputRef}
+  textareaProps={{                        // reach the textarea itself
+    onKeyDown: (e) => { if (menu.handles(e)) e.preventDefault() },  // claims the key
+    role: 'combobox',
+    'aria-expanded': menuOpen,
+  }}
+  renderTextarea={(props) => <HighlightedTextarea {...props} />}  // or swap it
+  above={menuOpen && <MentionMenu />}     // inside the dock, over the field
+  below={contextError && <p>{contextError}</p>}
+  allowFiles
+  accept=".md,.py,image/*"                // dropped files obey this too
+  maxFiles={8}
+  maxFileSize={20 * 1024 * 1024}
+  onSend={async (text, files) => {
+    const ok = await prepare(text)
+    if (!ok) return false                 // keep the draft
+    chat.sendMessage(text, files ? { files } : undefined)
+  }}
+/>
+```
+
+A key handler in `textareaProps` runs before Enter-to-send; `preventDefault()`
+there claims the key. Files can be dropped anywhere on the dock; the first
+reason one was refused shows under the attachment chips (`admitFiles` is the
+same check, exported).
+
+### Links
+
+Every link the components render — in an answer, on a `[1]` chip, on a source
+card — is a plain `<a target="_blank">`. Inside an app with a router, hand the
+provider a `linkComponent` and in-app URLs stay client-side:
+
+```tsx
+<ChatProvider linkComponent={DocsLink}>…</ChatProvider>
+<AgnoChat linkComponent={DocsLink} />
+```
+
+It receives `href`, `children` and the anchor attributes the component would
+have set, and decides how to navigate — nothing sets `target` for it, so a
+link opens in the same page unless the component says otherwise. The usual
+shape routes your own origin through the router and pops everything else out:
+
+```tsx
+import { Link } from 'react-router-dom'
+import type { LinkComponent } from '@agno-hq/chat-react/chat'
+
+const DocsLink: LinkComponent = ({ href, children, ...rest }) => {
+  const url = new URL(href, window.location.href)
+  return url.origin === window.location.origin ? (
+    <Link to={url.pathname + url.search + url.hash} {...rest}>
+      {children}
+    </Link>
+  ) : (
+    <a href={href} target="_blank" rel="noreferrer noopener" {...rest}>
+      {children}
+    </a>
+  )
+}
+```
+
+Sources with no URL — retrieved knowledge-base chunks — are never links; their
+`[1]` chip points at the card below the answer.
+
+### Run events
+
+Every run keeps the events that produced it on its own message
+(`message.events`) — live, and for runs restored from session history when the
+agent stores them. `<BehindTheScenes>` builds its steps from those events the
+way the AgentOS chat does: content deltas, model-request and reasoning-delta
+events are dropped, started/completed pairs collapse into one step, and run
+lifecycle events read as "Run Started" / "Run Completed" with the reported
+duration. A message with no events falls back to what it does carry (tools,
+reasoning, member turns, workflow steps).
+
+The raw feed is not part of that panel. `chat.events` holds the latest run's
+events, and every message keeps its own in `message.events` — render either
+with `<EventLog>` wherever you want it:
+
+```tsx
+<EventLog events={chat.events} maxHeight={240} />
+```
+
+### Citations, sources and link previews
+
+Whatever a run cites — knowledge-base chunks in `references`, browsed links in
+`citations.urls` — is flattened into one numbered list and rendered as cards
+under the answer: the site's favicon and the title, linking to the source. A
+`[1]` in the answer text becomes a chip pointing at card one, and hovering
+either the chip or a link opens a preview with the URL and the cited passage:
+
+```tsx
+<Message message={message} />           // markers, cards and previews, no props
+<Message message={message} hideSources />   // just the answer
+```
+
+The hostname and favicon come from the URL itself, and the title and passage
+from the citation payload, so previews need no network of their own. To fill in
+OpenGraph metadata, hand the provider a `resolveLinkPreview` — the browser can't
+read another origin's meta tags, so back it with an endpoint of your own. It is
+called once per URL, on first hover:
+
+```tsx
+<ChatProvider
+  baseUrl="http://localhost:7777"
+  resolveLinkPreview={async (url) => {
+    const res = await fetch(`/api/og?url=${encodeURIComponent(url)}`)
+    return res.ok ? res.json() : null   // { title, description, image, siteName, favicon }
+  }}
+>
+  <ChatWindow />
+</ChatProvider>
+```
+
+Plenty of runs carry no `references` or `citations` at all — the model cites in
+the answer itself, as numbered links, and lists the titles at the end:
+
+```text
+Call `Agent.run()` in production. [1](https://docs.agno.com/agents/building-agents)
+
+Sources: [Building Agents](https://docs.agno.com/agents/building-agents)
+```
+
+That reads the same way: the numbered link becomes the chip, the labelled link
+names the card, and the numbering stays exactly as the model wrote it. Links in
+prose are left alone — only numbered ones count as citations.
+
+Rendering sources yourself? `collectSources(references, citations)` and
+`sourcesFromMarkdown(content)` are the same numbering the components use, and
+`<SourceCard>`, `<LinkPreviewCard>` and `<HoverPreview>` are exported to build
+with.
+
+### Follow-ups
+
+An agent built with `followups=True` suggests what to ask next once it has
+answered. They sit above the composer as "Related questions", one line each —
+the full text is on hover — and clicking one sends it:
+
+```tsx
+<AgnoChat baseUrl="http://localhost:7777" />                          // on by default
+<AgnoChat baseUrl="http://localhost:7777" hideFollowups />            // off
+<AgnoChat baseUrl="http://localhost:7777" followupsTitle="Ask next" /> // your own heading
+```
+
+Only the latest answer offers them; earlier ones have been answered by the
+conversation moving on. They arrive as a `FollowupsCompleted` event and are
+stored on the run, so a reloaded session still shows them. To put them under
+the answer instead, pass `<Message onFollowup={chat.sendMessage}>`; to place
+them anywhere else, render `<Followups>` yourself from `message.followups` —
+`lines` lets them wrap instead of clamping.
+
+### Markdown
+
+Answers are rendered by [Streamdown](https://streamdown.ai), which is built for
+text that arrives a token at a time: mid-stream it repairs the unterminated
+bold, the half-written link and the unclosed fence instead of showing you the
+raw characters. GFM comes with it — tables, task lists, strikethrough — along
+with a sanitising pass over the HTML.
+
+Streamdown styles itself with Tailwind utility classes. Every element is mapped
+back onto this package's own `agno-md-*` classes, so **Tailwind is not
+required** and the shipped stylesheet and tokens still govern the look.
+
+Fenced code blocks get a header naming the language, a line-number gutter and
+syntax highlighting by [Shiki](https://shiki.style). The highlighter loads on
+the first fenced block, not before, and grammars load one at a time as
+languages appear; a language Shiki doesn't know renders plain. Colours follow
+the theme class like everything else. `--agno-code-max-height` (default `32rem`)
+caps a block before it scrolls.
+
+The header also holds a copy button. Turn it off per-renderer or for a whole
+tree:
+
+```tsx
+<Markdown content={answer} codeCopy={false} />
+<ChatProvider codeCopy={false}>…</ChatProvider>
+<AgnoChat codeCopy={false} />
+```
+
+Prefer a different renderer? `renderMarkdown` replaces it entirely:
 
 ```tsx
 import ReactMarkdown from 'react-markdown'
@@ -126,6 +487,10 @@ import remarkGfm from 'remark-gfm'
 />
 ```
 
+Note that `streamdown` is ESM-only, as is the remark/rehype ecosystem under it.
+Bundlers resolve that fine; a bare `require()` of the CJS entry needs Node
+22.12+.
+
 ---
 
 ## Human-in-the-loop
@@ -161,12 +526,20 @@ await chat.loadSession(sessionId) // load a transcript into the chat
 await chat.deleteSession(sessionId)
 ```
 
+The list updates optimistically, as the AgentOS chat does: the moment a run
+reports its session id, that session moves to the top of `chat.sessions` —
+created on the spot, named after the message that started it, if the backend
+just made it — rather than only appearing after the next `refreshSessions()`.
+A later refresh keeps the in-flight session even if the backend has not
+persisted it yet.
+
 Render them with `<SessionList>`:
 
 ```tsx
 <SessionList
   sessions={chat.sessions}
   activeSessionId={chat.sessionId}
+  streamingSessionIds={chat.streamingSessionIds}
   loading={chat.sessionsLoading}
   onSelect={chat.loadSession}
   onDelete={chat.deleteSession}
@@ -174,10 +547,22 @@ Render them with `<SessionList>`:
 />
 ```
 
+`streamingSessionIds` marks the sessions with a run in flight — each shows a
+spinner in place of the delete button.
+
+### Switching session does not stop the run
+
+Selecting another session (or starting a new chat) while a run is streaming
+*parks* that run instead of cancelling it, as the AgentOS chat does: it keeps
+streaming in the background, stays listed in `chat.streamingSessionIds`, and
+`loadSession` restores it — mid-stream or finished — when you switch back,
+rather than refetching a transcript that is still being written. Only
+`chat.cancel()` stops a run.
+
 The all-in-one widget shows this sidebar with `showSessions`:
 
 ```tsx
-<AgnoChat baseUrl="http://localhost:7777" showSessions showEventLog />
+<AgnoChat baseUrl="http://localhost:7777" showSessions />
 ```
 
 ---
@@ -202,8 +587,9 @@ normalised events) if you want to bypass the hook entirely.
 
 ## Running the example
 
-The `example/` folder is a Vite app demonstrating both the widget and the hook
-(with a live status panel + event log). It imports the library from source.
+The `example/` folder is a Vite app demonstrating the widget, the floating
+launcher, every component, and the hook (with a live status panel + event log).
+It imports the library from source.
 
 ```bash
 cd example