@truefoundry/agent-ui-sdk 0.0.1

package/README.md

@@ -0,0 +1,634 @@
+# @truefoundry/agent-ui-sdk
+
+A design-system-agnostic chat UI SDK for TrueFoundry agents, built on top of
+`[@assistant-ui/react](https://www.assistant-ui.com/)` and
+`@truefoundry/assistant-ui-runtime`.
+
+```
+truefoundry-gateway-sdk (AgentSessionClient)
+  → @truefoundry/assistant-ui-runtime (useTrueFoundryAgentRuntime)
+    → @assistant-ui/react (primitives, ExternalStoreRuntime)
+      → THIS SDK (Thread, ThreadListContainer, atoms + containers)
+```
+
+It exists to separate **presentation** from **state**, so the visual design
+can be replaced later without touching any data-fetching or runtime-wiring
+logic. You bring the runtime; the SDK renders it.
+
+## Contents
+
+- [Install](#install)
+- [Styling](#styling)
+- [Quick start](#quick-start)
+- [OpenUI blocks](#openui-blocks)
+- [Customizing the UI (examples)](#customizing-the-ui-examples)
+- [Architecture](#architecture)
+- [What's in the box](#whats-in-the-box)
+- [Known gaps](#known-gaps)
+- [Troubleshooting: "requires an AuiProvider"](#troubleshooting-requires-an-auiprovider)
+- [Development](#development)
+
+## Install
+
+```bash
+yarn add @truefoundry/agent-ui-sdk \
+  @assistant-ui/react @assistant-ui/core \
+  @truefoundry/assistant-ui-runtime truefoundry-gateway-sdk \
+  react react-dom
+```
+
+Every one of these peers must resolve to a **single instance** across your app.
+Two copies of `react` or `@assistant-ui/core` are the most likely source of a
+`"requires an AuiProvider"` error — see
+[Troubleshooting](#troubleshooting-requires-an-auiprovider).
+
+> `@truefoundry/assistant-ui-runtime` isn't on npm yet. Until it is, install it
+> from a prebuilt tarball, e.g. add to your `package.json`:
+> `"@truefoundry/assistant-ui-runtime": "@truefoundry/assistant-ui-runtime"`.
+
+## Styling
+
+SDK components use Tailwind utility classes. Import the SDK stylesheet in your
+**Tailwind entry CSS file** (for example `globals.css`) with a CSS `@import` so
+the SDK's own `@source` directive participates in the same Tailwind build:
+
+```css
+@import "tailwindcss";
+@import "@truefoundry/agent-ui-sdk/openui.css";
+```
+
+No manual `@source` pointing into `node_modules` is needed — the SDK stylesheet
+declares `@source "."` relative to its install location, so Tailwind scans the
+SDK's components automatically.
+
+**Use a CSS `@import`, not a JS import** (`import "@truefoundry/agent-ui-sdk/openui.css"`).
+A JS import may load OpenUI styles but will not activate Tailwind's content
+scanning for SDK utilities.
+
+Provide your own design tokens as CSS variables (`--primary`, `--background`,
+`--muted`, `--border`, …) in the consumer app — the SDK stays
+design-system-agnostic and references those variables rather than hardcoded
+colors or spacing.
+
+## Quick start
+
+```tsx
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import {
+  useTrueFoundryAgentRuntime,
+  trueFoundryAttachmentAdapter,
+} from "@truefoundry/assistant-ui-runtime";
+import { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+import {
+  Thread,
+  ThreadListContainer,
+  ErrorToasterProvider,
+  TooltipProvider,
+} from "@truefoundry/agent-ui-sdk";
+
+const client = new AgentSessionClient({
+  apiKey: process.env.TFY_API_KEY!,
+  environment: process.env.TFY_GATEWAY_URL!, // https://gateway.truefoundry.ai/<tenant>
+});
+
+export function App() {
+  const runtime = useTrueFoundryAgentRuntime({
+    client,
+    agentName: "my-agent",
+    adapters: { attachments: trueFoundryAttachmentAdapter }, // optional: enables file uploads
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <ErrorToasterProvider>
+        <TooltipProvider>
+          <main style={{ display: "flex", height: "100dvh" }}>
+            <aside style={{ width: 256 }}>
+              <ThreadListContainer />
+            </aside>
+            <div style={{ flex: 1 }}>
+              <Thread />
+            </div>
+          </main>
+        </TooltipProvider>
+      </ErrorToasterProvider>
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+That's the whole integration. Three things to know:
+
+- `**<Thread />**` is the fully-assembled message list + composer. It handles
+the welcome screen, loading skeleton, streaming, tool calls, reasoning
+blocks, attachments, and the ask-user / MCP-auth prompts automatically.
+- `**<ThreadListContainer />**` is the session sidebar (new / select / archive
+/ delete).
+- `**<ErrorToasterProvider>` / `<TooltipProvider>**` are required wrappers:
+gateway/runtime errors surface through the toaster, and tooltips on built-in
+buttons need the provider.
+
+Need a custom layout around the input? Compose the pieces yourself instead of
+`<Thread />`:
+
+```tsx
+import { ThreadContainer, ComposerContainer } from "@truefoundry/agent-ui-sdk";
+
+<ThreadContainer composer={<ComposerContainer />} />;
+```
+
+## OpenUI blocks
+
+Assistant messages that include an OpenUI Lang fenced block render
+automatically — no custom markdown wiring required:
+
+```markdown
+```openui
+Card() {
+  title: "Quarterly revenue"
+  TextContent() { text: "Revenue is up 12%." }
+}
+```
+```
+
+`<Thread />` routes assistant text through the SDK `Markdown` atom, which
+dispatches `language-openui` fences to `OpenUIBlock`. Streaming state is passed
+through while the message is still running.
+
+`OpenUIBlock` wraps output in OpenUI's `ThemeProvider` and syncs `mode` with a
+`.dark` class on `<html>` by default. Pass an explicit `mode` prop to override,
+or wrap a larger subtree in OpenUI's `ThemeProvider` yourself for custom token
+overrides (`lightTheme` / `darkTheme`).
+
+Make sure the SDK stylesheet is imported as CSS (see [Styling](#styling)) — the
+`@import` form is required for OpenUI's Tailwind utilities.
+
+## Customizing the UI (examples)
+
+Every feature-level atom is resolved through `useSlot`, so overriding one is
+just a prop on `<SlotsProvider>`. Nested `<SlotsProvider>`s fall through to the
+default, so you only ever override what actually changes.
+
+### The 60-second version
+
+`WelcomeScreen` renders immediately for a new/empty thread, so it's the fastest
+change to see:
+
+```tsx
+import { SlotsProvider, Thread } from "@truefoundry/agent-ui-sdk";
+
+function MyWelcome({ heading }: { heading?: string }) {
+  return <p className="px-4 py-6 text-center text-lg">{heading ?? "Hey 👋 what are we building today?"}</p>;
+}
+
+<SlotsProvider overrides={{ WelcomeScreen: MyWelcome }}>
+  <Thread />
+</SlotsProvider>;
+```
+
+Every other atom keeps rendering the SDK defaults. That's the whole pattern;
+the rest of this section applies it to harder cases.
+
+### Which names are actually resolved via `useSlot`?
+
+Not every name declared on `AtomSlots` is resolved via `useSlot` today.
+
+- **Feature-level atoms are** — `MessageBubble`, `ComposerShell`,
+`ToolCallCard`, `WelcomeScreen`, `ThreadListRow`, `Toast`, `ToastStack`,
+`AskUserPrompt`, `ScrollToBottomButton`, etc. Overriding these works exactly
+as documented here.
+- **Shared low-level primitives are not** — `Button`, `IconButton`, `Tooltip`*,
+`Dialog*`, `Avatar*`, `Collapsible*`, `Skeleton`, `CodeBlockHeader` are
+declared in `AtomSlots` and populated in `defaultSlots`, but the atoms that
+render them currently `import` them directly instead of going through
+`useSlot`. Overriding just `Button` will **not** change the Submit button
+inside `AskUserPrompt`.
+
+If you need to change a primitive everywhere, override the higher-level atom
+that embeds it (examples 4 and 6 do exactly this).
+
+### Restyling
+
+**1. Restyle the chat bubbles.** `MessageBubble` is a discriminated union on
+`variant`, so user and assistant messages can have completely different shells
+while still receiving the same slots (`children`, `error`, `branchIndicator`,
+`actionBar`/`attachments`):
+
+```tsx
+import { SlotsProvider, Thread, type MessageBubbleProps } from "@truefoundry/agent-ui-sdk";
+
+function BubbleV2(props: MessageBubbleProps) {
+  if (props.variant === "user") {
+    return (
+      <div className="ml-auto max-w-[75%] rounded-2xl bg-indigo-600 px-4 py-2 text-white">
+        {props.children}
+      </div>
+    );
+  }
+  return (
+    <div className="mr-auto max-w-[75%] rounded-2xl bg-neutral-100 px-4 py-2 dark:bg-neutral-800">
+      {props.children}
+      {props.error}
+      <div className="mt-1 flex gap-1 text-xs text-neutral-500">
+        {props.branchIndicator}
+        {props.actionBar}
+      </div>
+    </div>
+  );
+}
+
+<SlotsProvider overrides={{ MessageBubble: BubbleV2 }}>
+  <Thread />
+</SlotsProvider>;
+```
+
+**2. Give one part of your app a different look.** `SlotsProvider`s nest, and
+each `useSlot` falls back to the nearest ancestor — so an embedded widget can
+look different from the full-page app without a second theming system, and
+without its overrides leaking out:
+
+```tsx
+import { SlotsProvider, Thread } from "@truefoundry/agent-ui-sdk";
+
+function CompactWelcome({ heading }: { heading?: string }) {
+  return <p className="px-4 py-2 text-sm text-muted-foreground">{heading ?? "Ask me anything"}</p>;
+}
+
+// Only this subtree sees CompactWelcome. A <Thread /> elsewhere keeps the default.
+function EmbeddedWidget() {
+  return (
+    <SlotsProvider overrides={{ WelcomeScreen: CompactWelcome }}>
+      <Thread />
+    </SlotsProvider>
+  );
+}
+```
+
+**3. Decorate instead of replace.** An override can just wrap the default and
+add behavior — the cheapest way to bolt on analytics without owning markup:
+
+```tsx
+import { forwardRef } from "react";
+import {
+  SlotsProvider,
+  Thread,
+  ScrollToBottomButton as DefaultScrollButton,
+  type ScrollToBottomButtonProps,
+} from "@truefoundry/agent-ui-sdk";
+
+const TrackedScrollButton = forwardRef<HTMLButtonElement, ScrollToBottomButtonProps>((props, ref) => (
+  <DefaultScrollButton
+    {...props}
+    ref={ref}
+    onClick={(event) => {
+      analytics.track("scroll_to_bottom_clicked");
+      props.onClick?.(event);
+    }}
+  />
+));
+
+<SlotsProvider overrides={{ ScrollToBottomButton: TrackedScrollButton }}>
+  <Thread />
+</SlotsProvider>;
+```
+
+**4. Give specific tools their own visual treatment.** `ToolCallCard` receives
+`name`/`variant`/`status` on every call, so you can special-case one tool and
+fall through to the default (also exported) for everything else — sub-agents,
+mcp-listings, and every other tool:
+
+```tsx
+import { SlotsProvider, Thread, ToolCallCard as DefaultToolCallCard, type ToolCallCardProps } from "@truefoundry/agent-ui-sdk";
+import { SearchIcon } from "lucide-react";
+
+function CustomToolCallCard(props: ToolCallCardProps) {
+  if (props.variant === "tool" && props.name === "web_search") {
+    return (
+      <div className={props.isError ? "rounded-lg border border-destructive/40 p-2" : "rounded-lg border p-2"}>
+        <button onClick={props.onToggle} className="flex items-center gap-2 text-sm">
+          <SearchIcon className="size-4" />
+          Searching the web{props.durationText ? ` · ${props.durationText}` : ""}
+        </button>
+        {props.expanded && props.result && <pre className="mt-2 text-xs whitespace-pre-wrap">{props.result}</pre>}
+      </div>
+    );
+  }
+  return <DefaultToolCallCard {...props} />;
+}
+
+<SlotsProvider overrides={{ ToolCallCard: CustomToolCallCard }}>
+  <Thread />
+</SlotsProvider>;
+```
+
+### Changing behavior, not just looks
+
+**5. Turn ask-user into instant click-to-answer.** The shipped `AskUserPrompt`
+uses a select-then-submit radio flow (see [Known gaps](#known-gaps)). Slots
+only cover atoms, not containers — and the fix can't live in an atom override,
+because the shipped `AskUserContainer` computes `onSubmit` from state set by a
+*previous* `onSelectOption`. So skip the container and talk to the runtime hook
+it wraps directly:
+
+```tsx
+import { useTrueFoundryToolResponses } from "@truefoundry/assistant-ui-runtime";
+import { useThreadIsRunning } from "@assistant-ui/core/react";
+
+function InstantAskUser() {
+  const { pending, respond } = useTrueFoundryToolResponses();
+  const isRunning = useThreadIsRunning();
+  const item = pending[0];
+  if (item == null) return null;
+
+  return (
+    <div className="flex flex-wrap gap-2 rounded-xl border p-3">
+      <p className="w-full text-sm font-medium">{item.question ?? "Answer required"}</p>
+      {(item.options ?? []).map((label) => (
+        <button
+          key={label}
+          disabled={isRunning}
+          onClick={() => respond({ toolCallId: item.toolCallId, content: label })}
+          className="rounded-full border px-3 py-1 text-sm"
+        >
+          {label}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+Wire it in with a thin composer wrapper that renders `<InstantAskUser />` in
+place of `<AskUserContainer />` — mirror the branching in
+`[ComposerContainer](./src/containers/ComposerContainer.tsx)` (check
+`mcpPending`, then tool responses, then fall through to `<ComposerShell />`)
+and pass your wrapper to `<ThreadContainer composer={<YourComposer />} />`.
+
+**6. Replace the composer while keeping cancel.** `ComposerShell` receives
+`isRunning` and `onCancel` from `ComposerContainer` (the default renders a
+Cancel button while a turn streams), plus `value`/`placeholder`/`disabled`/
+`onValueChange`/`onSubmit`/`onAttach`/`attachments`. Your override owns all the
+markup but keeps the same wiring:
+
+```tsx
+import { SlotsProvider, Thread, IconButton, type ComposerShellProps } from "@truefoundry/agent-ui-sdk";
+import { ArrowUpIcon, SquareIcon } from "lucide-react";
+
+function CompactComposer({
+  value,
+  placeholder,
+  disabled,
+  isRunning,
+  onValueChange,
+  onSubmit,
+  onCancel,
+}: ComposerShellProps) {
+  return (
+    <div className="border-border/60 flex w-full flex-col gap-2 rounded-3xl border p-2">
+      <textarea
+        value={value}
+        placeholder={placeholder}
+        disabled={disabled}
+        onChange={(event) => onValueChange(event.target.value)}
+        className="w-full resize-none bg-transparent px-2 py-1 outline-none"
+      />
+      <div className="flex justify-end px-1">
+        {isRunning ? (
+          <IconButton tooltip="Stop generating" onClick={onCancel} disabled={!onCancel}>
+            <SquareIcon />
+          </IconButton>
+        ) : (
+          <IconButton tooltip="Send" onClick={onSubmit} disabled={disabled || value.trim().length === 0}>
+            <ArrowUpIcon />
+          </IconButton>
+        )}
+      </div>
+    </div>
+  );
+}
+
+<SlotsProvider overrides={{ ComposerShell: CompactComposer }}>
+  <Thread />
+</SlotsProvider>;
+```
+
+**7. Reroute a cross-cutting behavior.** `ErrorToasterProvider` resolves
+`Toast`/`ToastStack` via `useSlot`, so you can pipe every gateway/runtime error
+through a different toast library (e.g. `sonner`) without touching
+`useErrorToaster` or any `showError` call site:
+
+```tsx
+import { useEffect } from "react";
+import {
+  SlotsProvider,
+  ErrorToasterProvider,
+  Thread,
+  type ToastProps,
+  type ToastStackProps,
+} from "@truefoundry/agent-ui-sdk";
+import { Toaster, toast as sonnerToast } from "sonner";
+
+function SonnerToast({ title, description, open, onOpenChange }: ToastProps) {
+  useEffect(() => {
+    if (!open) return;
+    sonnerToast.error(title, { description });
+    onOpenChange(false); // sonner now owns the visible toast
+  }, [open, title, description, onOpenChange]);
+  return null;
+}
+
+function SonnerToastStack({ children }: ToastStackProps) {
+  return (
+    <>
+      {children}
+      <Toaster richColors />
+    </>
+  );
+}
+
+// SlotsProvider must be an ancestor of ErrorToasterProvider — the provider
+// resolves the slot at its own position in the tree.
+<SlotsProvider overrides={{ Toast: SonnerToast, ToastStack: SonnerToastStack }}>
+  <ErrorToasterProvider>
+    <Thread />
+  </ErrorToasterProvider>
+</SlotsProvider>;
+```
+
+**8. Layer local-only UI onto a row without touching the container.**
+`ThreadListRow`'s contract (`title`/`active`/`onSelect`/`onArchive`/`onDelete`)
+has no concept of "pinned" — nothing needs to. An override is just a component,
+so it can hold state the container never sees:
+
+```tsx
+import { useState } from "react";
+import {
+  SlotsProvider,
+  ThreadListContainer,
+  ThreadListRow as DefaultRow,
+  type ThreadListRowProps,
+} from "@truefoundry/agent-ui-sdk";
+import { PinIcon } from "lucide-react";
+
+function PinnableRow(props: ThreadListRowProps) {
+  const [pinned, setPinned] = useState(false);
+  return (
+    <div className="relative">
+      <DefaultRow {...props} />
+      <button
+        onClick={(event) => {
+          event.stopPropagation();
+          setPinned((prev) => !prev);
+        }}
+        className="absolute left-1.5 top-1/2 -translate-y-1/2"
+      >
+        <PinIcon className={pinned ? "size-3.5 fill-current" : "size-3.5"} />
+      </button>
+    </div>
+  );
+}
+
+<SlotsProvider overrides={{ ThreadListRow: PinnableRow }}>
+  <ThreadListContainer />
+</SlotsProvider>;
+```
+
+## Architecture
+
+Every piece of UI is split into two layers.
+
+### Atoms (`src/atoms/**`)
+
+Pure, stateless, prop-driven components. An atom:
+
+- Never imports from `@assistant-ui/*` or the TrueFoundry runtime.
+- Never calls a runtime/data hook — only local `useState`/`useMemo`/
+`useCallback` for purely visual concerns.
+- Owns **all** Tailwind classes and JSX for what it renders.
+- Only knows "render this data, call this callback."
+
+This is the swap point: replacing the design system later means writing new
+components that satisfy the same prop contracts — zero container changes.
+
+### Containers (`src/containers/`**)
+
+Stateful glue. A container:
+
+- Reads assistant-ui primitives/hooks (`ThreadPrimitive`, `MessagePrimitive`,
+`useAui`, `useAuiState`, `@assistant-ui/core/react` hooks) and TrueFoundry
+runtime hooks (`useTrueFoundryApprovals`, `useTrueFoundryToolResponses`,
+`useTrueFoundryCancel`, …).
+- Derives plain data and callbacks from that state.
+- Resolves every atom via `useSlot("AtomName")` — **never** imports an atom
+directly — and passes derived props straight through.
+- Contains no decorative styling of its own.
+
+### The slot registry (`src/theme/SlotsProvider.tsx`)
+
+`AtomSlots` is an interface that starts empty and gets augmented by every atom
+module via `declare module "../theme/SlotsProvider.js"` — so adding an atom
+never requires editing the registry. `defaultSlots.ts` supplies this SDK's own
+implementation for every slot; `useSlot` falls back through nested
+`<SlotsProvider>`s to those defaults.
+
+```tsx
+import { SlotsProvider, Thread } from "@truefoundry/agent-ui-sdk";
+import { MyBubble } from "./my-design-system/MessageBubble";
+
+<SlotsProvider overrides={{ MessageBubble: MyBubble }}>
+  <Thread />
+</SlotsProvider>;
+```
+
+### Token contract (`src/theme/tokens.ts`)
+
+`DesignTokens` is a semantic color/radius/spacing/typography contract exposed
+via `useTokens()` / `<TokensProvider>`. The shipped default atoms don't consume
+it yet (they port the reference app's Tailwind classes verbatim); it exists so
+a future design system has a token surface to bind to.
+
+## What's in the box
+
+
+| Area         | Containers                                                                                         | Notes                                                                                                                                                                                                                           |
+| ------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Thread shell | `ThreadContainer`, `Thread`                                                                        | Welcome screen, loading skeleton, scroll-to-bottom, message list                                                                                                                                                                |
+| Messages     | `AssistantMessageContainer`, `UserMessageContainer`, `AssistantTextContainer`                      | Text, branch picker, error banner, copy/export action bar; ````openui` fences render via `OpenUIBlock`                                                                                                                          |
+| Tools        | `ToolCallContainer`, `ToolGroupContainer`                                                          | Tool-call rendering, approval flow, sub-agent nesting (recursive)                                                                                                                                                               |
+| Reasoning    | `ReasoningContainer`                                                                               | Streaming-aware collapsible reasoning blocks                                                                                                                                                                                    |
+| Composer     | `ComposerContainer`, `AskUserContainer`, `McpAuthContainer`                                        | Message input with cancel-while-streaming; auto-swaps to ask-user / MCP-auth prompts when a turn is paused. `McpAuthContainer` renders a per-server "Authorize" link; the user confirms with "Continue" (no background polling) |
+| Attachments  | `ComposerAttachmentsContainer`, `MessageAttachmentsContainer`, `ComposerAttachmentPickerContainer` | Staging tray in composer; image/file chips in user bubbles                                                                                                                                                                      |
+| Thread list  | `ThreadListContainer`                                                                              | Flat list (not grouped by date): new / select / archive / delete                                                                                                                                                                |
+| Errors       | `ErrorToasterProvider`, `useErrorToaster`                                                          | Global toast for gateway/runtime errors                                                                                                                                                                                         |
+
+
+Every atom's prop type is exported from `[src/index.ts](./src/index.ts)` — that
+file is the definitive list of what's public.
+
+## Known gaps
+
+Deliberate deviations from the reference app, flagged rather than silently
+dropped:
+
+- `**AskUserPrompt**` uses a select-then-submit radio flow, not the reference
+app's immediate click-to-answer buttons. See example 5 to change this.
+- `**ToolCallCard**` ships an `mcp-listing` variant (type + atom) that no
+container currently selects — the runtime has no signal distinguishing
+"listing MCP tools" from any other tool call. Its `tool` variant also carries
+an `approvalSlot`/`durationText` beyond the originally-sketched contract,
+needed to keep the tool-approval flow working.
+- **Attachments**: image previews use a `contentType` fallback because the
+TrueFoundry attachment adapter tags all uploads as `type: "file"`.
+- `**ThreadListContainer`** renders one flat list, not grouped by
+Today/Yesterday/Earlier.
+- `**McpAuthContainer**` has no per-server auth status. `McpServerAuthInfo`
+(`{ id, name, authUrl }`) carries no authorized/pending flag, so multi-server
+auth is all-or-nothing: one shared Continue button.
+- Several `AtomSlots` entries (`Button`, `IconButton`, `Tooltip*`, `Dialog*`,
+`Avatar*`, `Collapsible*`, `Skeleton`, `CodeBlockHeader`) are declared and
+populated in `defaultSlots`, but no shipped atom resolves them via `useSlot`
+yet — the atoms import them directly. Override the higher-level atom instead
+(see "Which names are actually resolved via `useSlot`?").
+
+## Troubleshooting: "requires an AuiProvider"
+
+`@assistant-ui/core` (and `@assistant-ui/store`, which holds the React Context
+`AuiProvider` relies on) takes `react` as a peer dependency. If your app and
+this SDK resolve to two different `react` versions — even two patch versions
+apart — your package manager may install two physically separate copies of
+`@assistant-ui/core`/`@assistant-ui/store`. React Context identity is tied to
+the *module instance*, so hooks like `useAui`/`useAuiState` called inside this
+SDK read from a different Context than your `<AssistantRuntimeProvider>`,
+producing:
+
+```
+Uncaught Error: You are using a component or hook that requires an
+AuiProvider. Wrap your component in an <AuiProvider> component.
+```
+
+even though a provider **is** mounted. Diagnose with:
+
+```bash
+yarn why @assistant-ui/core
+yarn why @assistant-ui/store
+```
+
+If either reports more than one instance, align every `react`/`react-dom`
+version across the workspace (same range — don't mix pinned-exact and
+caret-ranged) and reinstall.
+
+## Development
+
+```bash
+yarn install
+yarn build       # tsup → dist/
+yarn typecheck   # tsc --noEmit
+yarn test        # vitest run
+```
+
+Tests render containers against a real (in-memory) assistant-ui runtime via
+`[src/containers/RuntimeHarness.tsx](./src/containers/RuntimeHarness.tsx)` — no
+network calls, no real gateway required.
+
+To produce a distributable tarball: `yarn pack:tgz` (installs, builds, then
+`yarn pack`).