The open-source agent harness - the runtime layer that turns an LLM into a working agent.
UI SDK Docs Improvements (#150)
qaifi-tfebaeb9f135d4
diff --git a/docs/ui-sdk/concepts/agent-modes.mdx b/docs/ui-sdk/concepts/agent-modes.mdxnew file mode 100644index 000000000..8d91226ef--- /dev/null+++ b/docs/ui-sdk/concepts/agent-modes.mdx@@ -0,0 +1,65 @@+---+title: "Agent modes"+description: "Choose between a fixed agent, a library, a composer, or both."+---++`agentConfig` decides which agent-selection affordances the shell exposes.++```ts+type AgentConfig =+ | { mode: "SingleAgent"; name: string }+ | { mode: "AgentLibrary" }+ | { mode: "AgentComposer"; defaultAgentSpec?: AgentSpec }+ | { mode: "AgentLibraryWithComposer"; defaultAgentSpec?: AgentSpec };+```++The default is `{ mode: "AgentLibraryWithComposer" }`.++| Mode | Library | Composer | New chat |+| --- | --- | --- | --- |+| `SingleAgent` | — | — | yes |+| `AgentLibrary` | yes | — | no |+| `AgentComposer` | — | yes | yes |+| `AgentLibraryWithComposer` | yes | yes | yes |++<AccordionGroup>+ <Accordion title="SingleAgent">+ Pins the UI to one named agent. All selection controls are hidden and the user cannot switch agents or open the composer.+ </Accordion>++ <Accordion title="AgentLibrary">+ Users pick from agents your `searchAgents` implementation returns, but cannot author a new one. Note that "new chat" is disabled in this mode only.++ <Frame caption="The Agents Library: users pick from the agents your `searchAgents` returns.">+ + </Frame>+ </Accordion>++ <Accordion title="AgentComposer">+ Users assemble an ad-hoc agent — model, skills, MCP servers — without browsing a library, and can save it back to the library.++ <Frame caption="Composing an agent — pick a model, add connectors and skills, then save it to the library.">+ <div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.46", padding: "40px 0" }}>+ <iframe src="https://app.supademo.com/embed/cmsk13xio00k81p0j1wj6amj6?embed_v=2&utm_source=embed" loading="lazy" title="Compose an agent in TrueForge" allow="clipboard-write" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }} />+</div>+ </Frame>+ </Accordion>++ <Accordion title="AgentLibraryWithComposer">+ Both surfaces, and the default. Users can pick an existing agent or author a new one.+ </Accordion>+</AccordionGroup>++## Gotchas++<Warning>+ `defaultAgentSpec` seeds a new draft rather than binding to the current one. Changing it does not alter the conversation on screen, and it does not apply on **clear chat** either — that path deliberately preserves the spec already bound to the draft. The new value is picked up when a **new chat** starts. To apply it immediately, remount the component with a new `key`. It is ignored entirely in `SingleAgent` mode.+</Warning>++<Warning>+ Always pass an explicit `defaultAgentSpec` in composer modes. Omitting it falls back to `{ model: { name: "openai-main/gpt-4.1" } }`, and requests fail if your backend does not expose a model under that exact name.+</Warning>++## Settings++The settings panel appears only when your server exposes a `catalog`. Without one it is silently absent — there is no error, so an unexpectedly missing settings button usually means the catalog is not attached. Note that `useCatalogServer()` throws when there is no catalog; use `useOptionalCatalogServer()` in code that must tolerate its absence.\ No newline at end of filediff --git a/docs/ui-sdk/get-started/quickstart.mdx b/docs/ui-sdk/get-started/quickstart.mdxindex df1c3ece3..a98825a27 100644--- a/docs/ui-sdk/get-started/quickstart.mdx+++ b/docs/ui-sdk/get-started/quickstart.mdx@@ -1,13 +1,13 @@---title: "Quickstart"-description: "Render a working agent chat UI against one of three backends."+description: "Render a working agent chat UI"---## Installation<CodeGroup>-```text npm+```shellscript npmnpm install @truefoundry/trueforge-ui```@@ -16,11 +16,12 @@ pnpm add @truefoundry/trueforge-ui``````text yarn+yarn add @truefoundry/agent-ui-sdk```</CodeGroup>-`react` and `react-dom` are required peer dependencies and must be version 18 or 19. `@assistant-ui/core`, `@assistant-ui/react`, and `@types/react` are optional peers, you need to install them yourself only if you use their APIs directly or need to pin a version.+`react` and `react-dom` are required peer dependencies and must be version 18 or 19.## Connect with TrueForge Server@@ -36,62 +37,12 @@ Typed for hosts adopting the harness adapter./>```+## Rendered UI+<Frame caption="What `TrueforgeUI` renders — a full agent chat with streaming, history, and tool calls."></Frame>--## Troubleshooting--<AccordionGroup>- <Accordion title="Error: requires an AuiProvider">- Deduplicate the assistant-ui singletons `react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of _"requires an AuiProvider"_.-- <CodeGroup>-- ```ts vite.config.ts- export default defineConfig({- resolve: {- dedupe: [- "react",- "react-dom",- "@assistant-ui/core",- "@assistant-ui/react",- "@assistant-ui/store",- ],- },- });- ```-- ```json package.json- {- "resolutions": {- "@assistant-ui/core": "<version>",- "@assistant-ui/store": "<version>"- }- }- ```-- </CodeGroup>-- The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.-- Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves `@assistant-ui/core` against.- </Accordion>-- <Accordion title="The UI renders but is collapsed to zero height">- The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.-- ```tsx- <div className="flex h-dvh min-h-0 w-full flex-1 flex-col">- <TrueforgeUI /* ... */ className="h-full min-h-0" />- </div>- ```-- The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.- </Accordion>-</AccordionGroup>-## Where to go next<CardGroup cols={2}>diff --git a/docs/ui-sdk/guides/layouts.mdx b/docs/ui-sdk/guides/layouts.mdxindex 17fcbfe27..0f46facfc 100644--- a/docs/ui-sdk/guides/layouts.mdx+++ b/docs/ui-sdk/guides/layouts.mdx@@ -3,42 +3,40 @@ title: "Layouts"description: "The four built-in layouts, and how to supply your own."----`layout` is required. Pass one of the built-in names or your own component.+The sidebar view is the default option. You can pass predefined values - sidebar, drawer, dock, or widget to change the layout.<Tabs>- <Tab title="sidebar">- Full-page chat with a persistent thread list on the left. The default choice for a- dedicated chat surface.+ <Tab title="sidebar(default)">+ Full-page chat with a persistent chat history on the left. The default choice for a dedicated chat surface.```tsx<TrueforgeUI server={server} layout="sidebar" />```<Frame caption="Sidebar: full-page chat with the thread list pinned on the left.">- <img src="/images/sidebar.png" alt="Sidebar layout — a persistent thread list on the left beside a full-page chat" />+ </Frame></Tab><Tab title="drawer">- Thread list collapses into an overlay drawer. Suited to narrower viewports.+ Chat history list collapses into an overlay drawer. Click on the history icon to view the past conversations. Suited to narrower viewports.```tsx<TrueforgeUI server={server} layout="drawer" />```<Frame caption="Drawer: the thread list collapses into an overlay for narrow viewports.">- <img src="/images/drawer.png" alt="Drawer layout — the thread list collapsed into an overlay drawer" />+ </Frame></Tab><Tab title="dock">- A panel pinned to the right edge, filling the available width up to a 400px cap. The side is- not configurable.+ A panel pinned to the right edge, filling the available width up to a 400px cap.```tsx<TrueforgeUI server={server} layout="dock" />```<Frame caption="Dock: a compact panel pinned to the right edge, up to a 400px cap.">- <img src="/images/dock.png" alt="Dock layout — a compact chat panel pinned to the right edge of the app" />+ </Frame></Tab><Tab title="widget">@@ -49,73 +47,9 @@ description: "The four built-in layouts, and how to supply your own."```<Frame caption="Widget: a floating launcher that expands into a compact chat panel.">- <img src="/images/widget.png" alt="Widget layout — a floating launcher expanded into a compact chat panel" />+ </Frame></Tab></Tabs>-Built-in layouts are code-split, so naming one does not pull the other three into your bundle.-A placeholder renders for the moment it takes to load.--`dock` and `widget` are compact layouts: rather than showing the thread list beside the-conversation, they stack the two and let the user switch between them from a history control.-`sidebar` and `drawer` keep the list available alongside the chat.--## Custom layouts--Pass a component instead of a string. It renders inside the full provider stack, so every-container hook and `useSlot` lookup works normally.--```tsx-import { Thread, ThreadListContainer, TrueforgeUI } from "@truefoundry/trueforge-ui";--function MyLayout() {- return (- <div className="flex h-full min-h-0">- <aside className="w-72 shrink-0 border-r">- <ThreadListContainer />- </aside>- <main className="min-h-0 flex-1">- <Thread />- </main>- </div>- );-}--<TrueforgeUI server={server} layout={MyLayout} />;-```--<Frame caption="A custom layout renders inside the full provider stack, so every container hook still works.">- <img src="/images/custom.png" alt="A custom TrueForge layout composed from a thread list and a chat pane" />-</Frame>--`Thread` is a convenience wrapper equal to-`<ThreadContainer composer={<ComposerContainer />} />`. Split them apart when you need the-composer somewhere other than directly beneath the transcript.--<Warning>- The settings panel is part of the built-in layouts, so a custom layout does not get one. If- you need settings, either stay on a built-in layout or build your own panel against the- `catalog` server — see [Server](/ui-sdk/reference/server).-</Warning>--## Composing without TrueforgeUI--For maximum control, mount the providers yourself. Order matters — `SlotsProvider` must be-outside `TrueFoundryChatProvider`.--```tsx-<SlotsProvider overrides={overrides} theme={theme}>- <ServerProvider server={server}>- <ShellModeProvider agentConfig={{ mode: "AgentLibrary" }}>- <TrueFoundryChatProvider server={server}>- <MyLayout />- </TrueFoundryChatProvider>- </ShellModeProvider>- </ServerProvider>-</SlotsProvider>-```--This path gives up the automatic runtime reset that `TrueforgeUI` performs when the selected-agent changes, so you become responsible for remounting `TrueFoundryChatProvider` — change its-`key` — at those moments.+Built-in layouts are code-split, so using one does not pull the other three into your bundle. A placeholder renders for the moment it takes to load.\ No newline at end of filediff --git a/docs/ui-sdk/guides/theming.mdx b/docs/ui-sdk/guides/theming.mdxindex c47ffde82..d3dbbbdf1 100644--- a/docs/ui-sdk/guides/theming.mdx+++ b/docs/ui-sdk/guides/theming.mdx@@ -1,11 +1,9 @@----title: "Theming"-description: "Presets, semantic tokens, branding, and dark mode."+title: "Preset Themes"+description: "Presets, branding, and dark mode."----Theming works the way shadcn/ui theming works: semantic tokens compiled to CSS custom-properties. `ThemeProvider` writes them as inline styles on a wrapper `div.aui-theme-root`,-tagged with `data-theme` and `data-preset`.+You can choose from four preset themes - Claude, ChaptGPT, Gemini, or TrueFoundry## The theme object@@ -13,22 +11,24 @@ tagged with `data-theme` and `data-preset`.type ThemeConfig = {preset?: "truefoundry" | "claude" | "chatgpt" | "gemini"; // default "truefoundry"mode?: "light" | "dark" | "system";- tokens?: Partial<SemanticTokens>;- brand?: BrandConfig;- className?: string;- icons?: IconMap;- classNames?: ContentClassNames;+ brand?: {+ name?: string;+ logo?: string | BrandLogo;+ },+ ...};```-```tsx+```tsx App.tsx<TrueforgeUI- server={server}- layout="sidebar"+ ...theme={{preset: "claude",- tokens: { primary: "#0B5FFF", composerRadius: "1rem" },- brand: { name: "Acme", icon: { src: "/logo.svg", alt: "Acme" } },+ mode: "system",+ brand: {+ name: "TrueForge",+ logo: "/logo.svg",+ }}}/>```@@ -37,116 +37,43 @@ The `chatgpt`, `claude`, and `gemini` presets (the default is `truefoundry`):<Columns cols={3}><Frame caption="chatgpt">- <img src="/images/theme-chatgpt.png" alt="TrueForge UI with the chatgpt theme preset" />+ </Frame>+<Frame caption="claude">- <img src="/images/theme-claude.png" alt="TrueForge UI with the claude theme preset" />+ </Frame>+<Frame caption="gemini">- <img src="/images/theme-gemini.png" alt="TrueForge UI with the gemini theme preset" />+ </Frame></Columns>-## Precedence--The provider resolves the preset for the current mode, merges your `theme.tokens` over it, and-writes the result as **inline styles** on the theme root. So within `theme.tokens`, your entries-beat the preset — that part is straightforward.--<Warning>- Because those tokens land as inline styles, a `:root { --primary: … }` rule in your own CSS- will **not** override them. This applies to every token a preset defines, whether or not you- passed `theme.tokens`. Use `theme.tokens` to change these, not CSS.-</Warning>--A few tokens are absent from the presets — `scrollbarThumb`, `assistantBubble`, and-`assistantBubbleForeground`. Those are not written inline unless you set them, so they fall-through to the stylesheet's low-precedence layer and a host `:root` rule does take effect.--`theme.className` is applied to the theme root, for utility-class adjustments alongside the-tokens.--<Note>- `brand`, `icons`, and `classNames` are not part of this cascade — they are separate context- values, not tokens that layer over one another.-</Note>-## Light and dark mode-Omit `theme.mode` and the provider is uncontrolled: it resolves `system`, lets the user-toggle, and persists the choice to `localStorage` under `aui-theme-preference`. Pass-`theme.mode` and the provider becomes controlled — `setTheme` from `useTheme()` becomes a-no-op and you own the state.+Skip means defaults to system theme. User can choose via UI.-<Warning>- Dark mode toggles the `dark` class on `document.documentElement`. If your app already- manages dark mode by the same mechanism, the two will fight. Pass a controlled- `theme.mode` derived from your own state to keep them in sync.-</Warning>+Pass to set a theme to light, dark or system. User CANNOT update it. This is useful when you want to control the theme based on the main/top level app theme.<Frame caption="Dark mode applied to the chat UI.">- <img src="/images/dark_theme.png" alt="The TrueForge UI SDK rendered in dark mode" />+ </Frame>-## Reading theme state--```tsx-import { useTheme, useThemeMode, useBrand } from "@truefoundry/trueforge-ui";--const { preset, mode, preference, isDark, setTheme } = useTheme();-const resolved = useThemeMode(); // "light" | "dark", defaults to "light" outside a provider-const brand = useBrand();-```--`BrandLogo` and `BrandIcon` render `theme.brand.logo` and `theme.brand.icon`. Their fallbacks-differ: `BrandLogo` falls back to a default mark plus the brand name (default `"TrueFoundry"`),-while `BrandIcon` falls back to the bare mark with no name.--## Token naming--`SemanticTokens` keys map to the kebab-cased CSS variable of the same name — `cardForeground`-becomes `--card-foreground`, `composerRadius` becomes `--composer-radius`, `scrollbarThumb`-becomes `--scrollbar-thumb`.--One token breaks that rule:--| Token | CSS variable |-| --- | --- |-| `fontFamily` | `--font-agent-ui` |--Alongside the usual surface and text tokens, the palette includes status pairs for-`destructive`, `success`, and `warning`, each with a matching `*Foreground`.+### Set separate logo for light and dark theme-<Note>- `theme.tokens` is a `Partial`, so you only supply the tokens you want to change and the preset- fills in the rest. The status pairs matter only if you construct a complete `SemanticTokens`- object — for instance when building your own preset — in which case all four of `success`,- `successForeground`, `warning`, and `warningForeground` are required.-</Note>--## Styling rendered content--`theme.classNames` targets the content renderers:--```ts-type ContentClassNames = {- markdown?: string;- inlineCode?: string;- syntaxHighlighter?: { root?: string; pre?: string; code?: string; lineNumber?: string };- openui?: { root?: string; scope?: string };- monaco?: { root?: string };-};-```--For CSS-only adjustments you can instead target the stable class names directly:-`.aui-markdown`, `.aui-syntax-highlighter`, `.aui-openui`, `.aui-monaco`.--## Presets--```ts-import { PRESETS, resolvePresetTokens } from "@truefoundry/trueforge-ui";--const tokens = resolvePresetTokens("gemini", "dark");-```--`PRESETS` is a `Record<ThemePreset, { light, dark }>` — useful for building a preset picker.+```tsx App.tsx+<TrueforgeUI+ ...+ theme={{+ ...+ brand: {+ name: "TrueForge",+ logo: {+ "light": "/logo/light.svg",+ "dark": "/logo/dark.svg",+ "href": "https://trueforge.dev" //URL to redirect on logo click+ },+ }+ }}+/>+```\ No newline at end of filediff --git a/docs/ui-sdk/guides/troubleshooting.mdx b/docs/ui-sdk/guides/troubleshooting.mdxindex 3c245cce3..ff4f88bef 100644--- a/docs/ui-sdk/guides/troubleshooting.mdx+++ b/docs/ui-sdk/guides/troubleshooting.mdx@@ -5,78 +5,91 @@ description: "Common failure modes and their causes."<AccordionGroup><Accordion title="Error: requires an AuiProvider">- Two copies of an assistant-ui package are in the bundle. Deduplicate `react`,- `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` — see- [Installation](/ui-sdk/get-started/installation).+ Deduplicate the assistant-ui singletons `react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of _"requires an AuiProvider"_.++ <CodeGroup>++ ```ts vite.config.ts+ export default defineConfig({+ resolve: {+ dedupe: [+ "react",+ "react-dom",+ "@assistant-ui/core",+ "@assistant-ui/react",+ "@assistant-ui/store",+ ],+ },+ });+ ```++ ```json package.json+ {+ "resolutions": {+ "@assistant-ui/core": "<version>",+ "@assistant-ui/store": "<version>"+ }+ }+ ```++ </CodeGroup>++ The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.++ Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves `@assistant-ui/core` against.</Accordion><Accordion title="The UI renders but is collapsed to zero height">- The SDK fills its parent and sets no height of its own. Give the wrapper a resolved- height (`h-dvh` plus `min-h-0`, or an explicit pixel height) and pass- `className="h-full min-h-0"`.+ The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.++ ```tsx+ <div className="flex h-dvh min-h-0 w-full flex-1 flex-col">+ <TrueforgeUI /* ... */ className="h-full min-h-0" />+ </div>+ ```++ The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.</Accordion><Accordion title="The SDK renders unstyled">- Check that `@import "@truefoundry/trueforge-ui/styles.css";` is actually reaching the- browser — that single import is the entire styling setup, and the stylesheet is- self-contained. You do not need Tailwind in your own app for the SDK to look right.+ Check that `@import "@truefoundry/trueforge-ui/styles.css";` is actually reaching the browser — that single import is the entire styling setup, and the stylesheet is self-contained. You do not need Tailwind in your own app for the SDK to look right.</Accordion><Accordion title="Your app's own base styles changed after installing">- The SDK's stylesheet deliberately omits Tailwind preflight so it cannot reset your styles,- so this is unlikely to come from the import itself. Look instead at whether you added- `@import "tailwindcss";` at the same time — that one does ship preflight, and it resets- host styles by design.+ The SDK's stylesheet deliberately omits Tailwind preflight so it cannot reset your styles, so this is unlikely to come from the import itself. Look instead at whether you added `@import "tailwindcss";` at the same time — that one does ship preflight, and it resets host styles by design.</Accordion><Accordion title="An error alert appears immediately on mount">- If you passed `type: "trueforge"`, that is expected — the harness adapter has not shipped,- so it resolves to a not-implemented error. Use `type: "truefoundry"` or a- [custom server](/ui-sdk/guides/custom-server) instead.+ If you passed `type: "trueforge"`, that is expected — the harness adapter has not shipped, so it resolves to a not-implemented error. Use `type: "truefoundry"` or a [custom server](/ui-sdk/guides/custom-server) instead.- Otherwise the server failed to resolve: check that `apiKey` and `controlPlaneURL` are set- and reachable. Attach an `onError` handler to see the underlying error.+ Otherwise the server failed to resolve: check that `apiKey` and `controlPlaneURL` are set and reachable. Attach an `onError` handler to see the underlying error.</Accordion><Accordion title="Requests fail in composer mode with an unknown model">- Without an explicit `defaultAgentSpec`, drafts default to `openai-main/gpt-4.1`. Pass a- spec naming a model your backend actually exposes:- `agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "..." } } }}`.+ Without an explicit `defaultAgentSpec`, drafts default to `openai-main/gpt-4.1`. Pass a spec naming a model your backend actually exposes: `agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "..." } } }}`.</Accordion><Accordion title="Changing defaultAgentSpec did not affect the open conversation">- It seeds a new draft rather than binding to the current one, so the change lands on the next- **new chat**. Clear chat will not pick it up — that path preserves the spec already bound to- the draft. To apply it to the conversation on screen, remount the component with a new- `key`. It is ignored entirely in `SingleAgent` mode.+ It seeds a new draft rather than binding to the current one, so the change lands on the next **new chat**. Clear chat will not pick it up — that path preserves the spec already bound to the draft. To apply it to the conversation on screen, remount the component with a new `key`. It is ignored entirely in `SingleAgent` mode.</Accordion><Accordion title="The settings button is missing">- Settings render only when your server exposes a `catalog`, so attach one to enable the- panel. If you are on a custom layout, that is the other cause — the panel ships with the- built-in layouts only.+ Settings render only when your server exposes a `catalog`, so attach one to enable the panel. If you are on a custom layout, that is the other cause — the panel ships with the built-in layouts only.</Accordion><Accordion title="Only the OAuth screen renders — no chat">- A `screenType=mcp-auth` query parameter is present on the URL. `TrueforgeUI` renders the- OAuth completion screen exclusively in that case. Keep the callback on its own route; see- [MCP OAuth](/ui-sdk/guides/mcp-oauth).+ A `screenType=mcp-auth` query parameter is present on the URL. `TrueforgeUI` renders the OAuth completion screen exclusively in that case. Keep the callback on its own route; see [MCP OAuth](/ui-sdk/guides/mcp-oauth).</Accordion><Accordion title="Dark mode fights with the host application">- The provider toggles the `dark` class on `document.documentElement`. Pass a controlled- `theme.mode` derived from your own state so the two stay aligned.+ The provider toggles the `dark` class on `document.documentElement`. Pass a controlled `theme.mode` derived from your own state so the two stay aligned.</Accordion><Accordion title="Import of Button or AskUserPrompt fails">- A few names are published as types only, so importing them as values fails. `Button` and- `IconButton` are restyled through [theme tokens](/ui-sdk/guides/theming) rather than replaced.- `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` are override-only — supply your own- component typed with the published props.+ A few names are published as types only, so importing them as values fails. `Button` and `IconButton` are restyled through [theme tokens](/ui-sdk/guides/theming) rather than replaced. `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` are override-only — supply your own component typed with the published props.</Accordion><Accordion title="SSR or React Server Components errors">- The package is ESM-only and client-only. Mount `TrueforgeUI` from a client component — in- Next.js App Router, a file with `"use client"` at the top.+ The package is ESM-only and client-only. Mount `TrueforgeUI` from a client component — in Next.js App Router, a file with `"use client"` at the top.</Accordion>-</AccordionGroup>+</AccordionGroup>\ No newline at end of filediff --git a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx b/docs/ui-sdk/setup-custom-ui/custom-theme.mdxindex a43be2a9d..1c8acc125 100644--- a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx+++ b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx@@ -3,109 +3,119 @@ title: "Custom Theme"description: "Build your own custom theme"----Pass an `overrides` object to replace a built-in component. Your version is used everywhere-that component appears, without you having to find each place it is rendered.+## The Theme Object++Theme object supports params to pass `tokens` to override styles of UI components. You can also override app level classes++```jsx App.jsx+type ThemeConfig = {+ ...+ tokens?: Partial<SemanticTokens>;+ className?: string;+ icons?: IconMap;+ classNames?: ContentClassNames;+};+```-```tsx-import { TrueforgeUI, type AssistantMessageBubbleProps } from "@truefoundry/trueforge-ui";--function MyBubble({ children, error, actionBar, className }: AssistantMessageBubbleProps) {- return (- <div className={className} data-testid="my-bubble">- {error}- <div className="prose">{children}</div>- {actionBar}- </div>- );-}--<TrueforgeUI- server={server}- layout="sidebar"- overrides={{ AssistantMessageBubble: MyBubble }}-/>;+## The Token Object++```json Token Object+{+ background: "#c18585",+ foreground: "#1f1f1f",+ card: "#ffffff",+ cardForeground: "#1f1f1f",+ popover: "#f0f4f9",+ popoverForeground: "#1f1f1f",+ primary: "#1f3b9b",+ primaryForeground: "#ffffff",+ secondary: "#e8eaed",+ secondaryForeground: "#1f1f1f",+ muted: "#f8fafd",+ mutedForeground: "#444746",+ accent: "#e9eef6",+ accentForeground: "#1f1f1f",+ destructive: "#b3261e",+ destructiveForeground: "#ffffff",+ border: "#dadce0",+ input: "#dadce0",+ ring: "#1f3b9b",+ userBubble: "#f3f6fc",+ userBubbleForeground: "#1f1f1f",+ radius: "1rem",+ composerRadius: "2rem",+ fontSans: "\"GeistSans\", \"GeistSans Fallback\", ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif",+ }```-`SlotOverrides` is `Partial<AtomSlots>`, so overrides are type-checked against the default-component's signature. Import the exported `*Props` type for the slot you are replacing and-honor the props you receive — several are rendered nodes (`actionBar`, `error`,-`approvalSlot`) that the container supplies and expects you to place.--## Commonly overridden slots--<AccordionGroup>- <Accordion title="Messages and content">- `AssistantMessageBubble`, `UserMessageBubble`, `UserMessageEdit`,- `UserMessageActionBar`, `MessageActionBar`, `MessageErrorBanner`, `MessageIndicator`,- `MessageTimestamp`, `MessageGroup`, `Markdown`, `SyntaxHighlighter`, `OpenUiFenceBlock`,- `CodeEditor`, `MonacoEditorCore`, `WelcomeScreen`.- </Accordion>- <Accordion title="Composer">- `ComposerShell`, `ComposerLeftSection`, `ComposerRightSection`, `ComposerSendButton`,- `AttachmentCard`, `AttachmentPickerButton`, `AttachmentPreviewDialog`.-- The draft composer has its own slots — `DraftComposerLeftSection`,- `DraftComposerRightSection`, `DraftModelSelector`, and `DraftCompositeSelector` — so you can- restyle the draft chrome without touching the standard composer.-- The two sets interact. In a mutable draft the container substitutes the draft sections- behind `ComposerLeftSection` / `ComposerRightSection`, but only while those slots are still- at their defaults. Override either one and yours wins in draft mode too, which means the- model and composite selectors disappear unless you render them yourself.- </Accordion>- <Accordion title="Thread shell and list">- `ThreadRootShell`, `ThreadViewportShell`, `ThreadComposerAreaShell`,- `ScrollToBottomButton`, `MessageListSkeleton`, `HistoryLoader`, `ThreadListShell`,- `ThreadListNewButton`, `ThreadListRow`, `ThreadListRowSkeleton`,- `ThreadListEmptyState`.- </Accordion>- <Accordion title="Tools and prompts">- `ToolCallCard`, `ToolCallContentBlock`, `ToolApprovalBar`, `ToolGroupCard`,- `SubAgentCard`, `SandboxToolCallCard`, `SandboxArtifactDownload`, `ChatFileDownload`,- `AgentStepsCard`, and the prompt slots `AskUserPrompt`, `McpAuthPrompt`, `ReasoningCard`.- </Accordion>- <Accordion title="Agent library and shell">- `AgentsLibrary`, `AgentsLibraryButton`, `SaveAgentButton`, `SelectAgentEmptyState`,- `ClearChatButton`, `ShellActionsActionSlot`, `Toast`, `ToastStack`, `Accordion`,- `AccordionSummary`, `AccordionDetails`.-- `ShellActionsActionSlot` exists purely to be overridden — it renders nothing by default and- is the supported place to add your own chrome, such as a logout control, beside the theme- and settings buttons. Layouts keep it mounted while Settings is open, so state in your- component survives.- </Accordion>-</AccordionGroup>+## Precedence-<Note>- `SlotOverrides` is derived directly from the SDK's default slot table, so autocomplete on the- `overrides` object is an exact list of what can be overridden — nothing more, nothing less.-</Note>+The provider resolves the preset for the current mode, merges your `theme.tokens` over it, and writes the result as **inline styles** on the theme root. So within `theme.tokens`, your entries beat the preset — that part is straightforward.++<Warning>+ Because those tokens land as inline styles, a `:root { --primary: … }` rule in your own CSS will **not** override them. This applies to every token a preset defines, whether or not you passed `theme.tokens`. Use `theme.tokens` to change these, not CSS.+</Warning>++A few tokens are absent from the presets — `scrollbarThumb`, `assistantBubble`, and `assistantBubbleForeground`. Those are not written inline unless you set them, so they fall through to the stylesheet's low-precedence layer and a host `:root` rule does take effect.++`theme.className` is applied to the theme root, for utility-class adjustments alongside the tokens.<Note>- Some slots are override-only, meaning you supply your own component rather than wrapping a- default: `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` publish their prop types but- not the components, and `Accordion`, `AccordionSummary`, and `AccordionDetails` publish- neither.+ `brand`, `icons`, and `classNames` are not part of this cascade — they are separate context values, not tokens that layer over one another.</Note>+## Reading theme state++```tsx+import { useTheme, useThemeMode, useBrand } from "@truefoundry/trueforge-ui";++const { preset, mode, preference, isDark, setTheme } = useTheme();+const resolved = useThemeMode(); // "light" | "dark", defaults to "light" outside a provider+const brand = useBrand();+```++`BrandLogo` and `BrandIcon` render `theme.brand.logo` and `theme.brand.icon`. Their fallbacks differ: `BrandLogo` falls back to a default mark plus the brand name (default `"TrueFoundry"`), while `BrandIcon` falls back to the bare mark with no name.++## Token naming++`SemanticTokens` keys map to the kebab-cased CSS variable of the same name — `cardForeground` becomes `--card-foreground`, `composerRadius` becomes `--composer-radius`, `scrollbarThumb` becomes `--scrollbar-thumb`.++One token breaks that rule:++| Token | CSS variable |+| --- | --- |+| `fontFamily` | `--font-agent-ui` |++Alongside the usual surface and text tokens, the palette includes status pairs for `destructive`, `success`, and `warning`, each with a matching `*Foreground`.+<Note>- `Button` and `IconButton` publish their prop types for typing your own components. The- buttons themselves are restyled through semantic tokens and CSS rather than replaced — see- [Theming](/ui-sdk/guides/theming).+ `theme.tokens` is a `Partial`, so you only supply the tokens you want to change and the preset fills in the rest. The status pairs matter only if you construct a complete `SemanticTokens` object — for instance when building your own preset — in which case all four of `success`, `successForeground`, `warning`, and `warningForeground` are required.</Note>-## Discovering slot names+## Styling rendered content-`SlotOverrides` is a mapped type over every slot, so your editor autocompletes the available-names as you type inside the `overrides` object, and hovering a name shows the component-signature you need to match. That is the fastest way to find a slot. The groups above list the-ones most applications touch.+`theme.classNames` targets the content renderers:-## Overriding outside TrueforgeUI+```ts+type ContentClassNames = {+ markdown?: string;+ inlineCode?: string;+ syntaxHighlighter?: { root?: string; pre?: string; code?: string; lineNumber?: string };+ openui?: { root?: string; scope?: string };+ monaco?: { root?: string };+};+```-If you compose providers manually, pass overrides to `SlotsProvider` and keep it outside-`TrueFoundryChatProvider`:+For CSS-only adjustments you can instead target the stable class names directly: `.aui-markdown`, `.aui-syntax-highlighter`, `.aui-openui`, `.aui-monaco`.-```tsx-<SlotsProvider overrides={{ ThreadListRow: MyRow }}>{/* ... */}</SlotsProvider>+## Presets++```ts+import { PRESETS, resolvePresetTokens } from "@truefoundry/trueforge-ui";++const tokens = resolvePresetTokens("gemini", "dark");```++`PRESETS` is a `Record<ThemePreset, { light, dark }>` — useful for building a preset picker.++Refer to [Building custom theme](/ui-sdk/setup-custom-ui/custom-theme) to build a theme from scratch\ No newline at end of filediff --git a/docs/ui-sdk/setup-custom-ui/untitled-page.mdx b/docs/ui-sdk/setup-custom-ui/untitled-page.mdxnew file mode 100644index 000000000..172e777df--- /dev/null+++ b/docs/ui-sdk/setup-custom-ui/untitled-page.mdx@@ -0,0 +1,54 @@+---+title: "Custom Layout"+---++Define a custom layout but still use the existing components++Pass a component instead of a string. It renders inside the full provider stack, so every container hook and `useSlot` lookup works normally.++```tsx App.tsx+import { Thread, ThreadListContainer, TrueforgeUI } from "@truefoundry/trueforge-ui";++function MyLayout() {+ return (+ <div className="flex h-full min-h-0">+ <aside className="w-72 shrink-0 border-r">+ <ThreadListContainer />+ </aside>+ <main className="min-h-0 flex-1">+ <Thread />+ </main>+ </div>+ );+}++<TrueforgeUI server={server} layout={MyLayout} />;+```++<Frame caption="A custom layout renders inside the full provider stack, so every container hook still works.">+ +</Frame>++`Thread` is a convenience wrapper equal to `<ThreadContainer composer={<ComposerContainer />} />`. Split them apart when you need the composer somewhere other than directly beneath the transcript.++<Warning>+ The settings panel is part of the built-in layouts, so a custom layout does not get one. If you need settings, either stay on a built-in layout or build your own panel against the `catalog` server — see [Server](/ui-sdk/reference/server).+</Warning>++## Composing without TrueforgeUI++For maximum control, mount the providers yourself. Order matters — `SlotsProvider` must be outside `TrueFoundryChatProvider`.++```tsx+<SlotsProvider overrides={overrides} theme={theme}>+ <ServerProvider server={server}>+ <ShellModeProvider agentConfig={{ mode: "AgentLibrary" }}>+ <TrueFoundryChatProvider server={server}>+ <MyLayout />+ </TrueFoundryChatProvider>+ </ShellModeProvider>+ </ServerProvider>+</SlotsProvider>+```++This path gives up the automatic runtime reset that `TrueforgeUI` performs when the selected agent changes, so you become responsible for remounting `TrueFoundryChatProvider` — change its `key` — at those moments.\ No newline at end of file