The Open Standard for Generative UI
AgentInterface
A full, drop-in agent-chat UI shipped as a single compound React component. It renders the whole shell — sidebar with thread history, a streaming conversation thread (assistant / user / tool messages), a composer with conversation starters, an empty-state welcome screen, a global artifact browser, and a per-thread Workspace rail with a resizable detailed-view side panel.
This document is for contributors working inside AgentInterface/. It explains the mental
model, the public API, how data and state flow, the rendering pipeline, the styling system, and the
sharp edges you will hit. If you only want to use the component, the Storybook stories
(stories/AgentInterface.stories.tsx) are the fastest reference.
Table of contents
- Mental model
- Quick start
- The slot / compound-component model
- Public API reference
- Render tree & provider stack
- Composition modes (A / B / C)
- State & data model
- Navigation & routing
- Message rendering pipeline
- Artifacts, the Workspace rail & DetailedView
- Layout & responsiveness
- Styling & theming
- Directory guide
- Extending the component
- Gotchas & known rough edges
- Local development
Mental model
AgentInterface is a pure view layer. It owns zero chat business logic. Everything stateful comes from three external sources, all from sibling packages:
| Concern | Source package | How AgentInterface gets it |
|---|---|---|
| Threads, messages, streaming, artifacts | @openuidev/react-headless |
Mounts <ChatProvider>; reads via useThread, useThreadList, useArtifactList, useDetailedView, … |
| GenUI auto-rendering of assistant messages | @openuidev/react-lang |
Optional componentLibrary prop → GenUIAssistantMessage |
| Wire message shapes | @ag-ui/core (re-exported by react-headless) |
Message, AssistantMessage, UserMessage, ToolMessage, InputContent, … |
What AgentInterface itself adds on top:
- A slot-based composition API (
<AgentInterface.Sidebar>,.Composer,.Route, …). - Layout & chrome: sidebar collapse/expand, mobile vs. desktop, the workspace rail, the resizable detailed-view split.
- Navigation (
NavContext) including a reservedartifacts/…URL space. - A handful of small UI-only stores/contexts (sidebar/workspace open state, starters, layout breakpoint).
Rule of thumb: if it's data, it lives in react-headless. If it's layout/chrome/UI state, it lives here.
Quick start
The bare form renders everything from internal defaults:
import { AgentInterface } from "@openuidev/react-ui"; // or the local component path
<AgentInterface
storage={storage} // ChatStorage from react-headless
llm={llm} // LLM transport from react-headless
logoUrl={logoUrl}
agentName="OpenUI"
/>;
With GenUI auto-rendering of assistant messages:
<AgentInterface storage={storage} llm={llm} componentLibrary={myLibrary} />
See stories/AgentInterface.stories.tsx (Default, WithWelcome, Routing, ArtifactBrowser,
WithWorkspace, …) for runnable examples of every feature.
The slot / compound-component model
AgentInterface is a function component with ~21 static members attached
(AgentInterface.Sidebar, AgentInterface.Composer, …). At render time it walks
props.children once (extractSlots, in AgentInterface.tsx) and routes each child by the
identity of its element type:
const SLOT_KEY_BY_TYPE = new Map<unknown, SingleSlotKey>([
[SidebarSlot, "sidebar"],
[SidebarHeader, "sidebarHeader"],
[SidebarFooter, "sidebarFooter"],
[MobileHeader, "mobileHeader"],
[ThreadHeader, "threadHeader"],
[WelcomeScreen, "welcome"],
[Composer, "composer"],
[Workspace, "workspace"],
]);
// <AgentInterface.Route> is collected separately into `routes[]`.
// Anything else falls through to `rest[]` and is rendered as-is at the end.
⚠️ Slots are matched by reference, not by name
A child is recognized only if child.type === <the exact component reference>. That means:
- Wrapping a slot in
React.memo, an HOC, a styled wrapper, or re-exporting it through a second module instance silently breaks slot detection — the element lands inrest[]and the default is rendered instead. - You must use the canonical
AgentInterface.*members (e.g.<AgentInterface.Composer>), not a hand-rolled clone.
Single-slot rules (dev warnings)
- Passing the same slot twice keeps the first and
console.warns in dev (extractSlots). - A top-level
<AgentInterface.SidebarHeader>is ignored when<AgentInterface.Sidebar>is also present (put the header inside the Sidebar instead) — also a dev warning.
The full list of static members and whether each is a top-level slot:
| Member | Top-level slot? | Role |
|---|---|---|
AgentInterface.Sidebar |
✅ sidebar |
Replace the whole sidebar; you compose its insides |
AgentInterface.SidebarHeader |
✅ sidebarHeader¹ |
Default sidebar's header (logo + name + collapse) |
AgentInterface.SidebarFooter |
✅ sidebarFooter |
Pinned below the thread list (e.g. theme toggle) |
AgentInterface.MobileHeader |
✅ mobileHeader |
Top bar on mobile |
AgentInterface.ThreadHeader |
✅ threadHeader |
Floating desktop header: start/center/end, chat title, Rename/Delete menu, workspace toggle |
AgentInterface.Welcome |
✅ welcome |
Empty-state hero (WelcomeScreen) |
AgentInterface.Composer |
✅ composer |
Message input |
AgentInterface.Workspace |
✅ workspace |
Per-thread artifact rail |
AgentInterface.Route |
✅ routes[] |
Custom routable view (see Routing) |
AgentInterface.SidebarContent |
❌ building block | Scrollable region inside a custom Sidebar |
AgentInterface.SidebarSeparator |
❌ building block | Divider inside a custom Sidebar |
AgentInterface.SidebarItem |
❌ building block | Styled nav row (also exported standalone) |
AgentInterface.ArtifactNav |
❌ building block | Artifact-category nav rows |
AgentInterface.NewChatButton |
❌ building block | "New chat" affordance |
AgentInterface.HistoryButton |
❌ building block | Thread-history menu on the collapsed rail |
AgentInterface.ThemeModeToggle |
❌ building block | Light/dark toggle for SidebarFooter |
AgentInterface.ThreadList |
❌ building block | Date-grouped thread history |
AgentInterface.Messages |
❌ building block | The message list itself |
AgentInterface.MessageLoading |
❌ building block | Streaming loader row |
AgentInterface.ScrollArea |
❌ building block | Auto-scroll container |
¹ Only honored at top level when no Sidebar slot is present; otherwise nest it inside Sidebar.
Public API reference
<AgentInterface> props
Defined as AgentInterfaceProps in AgentInterface.tsx. It extends Omit<ChatProviderProps, "children">, so the data props below are forwarded to react-headless's <ChatProvider>.
Forwarded to ChatProvider (from @openuidev/react-headless):
| Prop | Type | Notes |
|---|---|---|
storage |
ChatStorage |
Thread persistence (listThreads, getMessages, …) and optional artifact storage for the browser |
llm |
LLM transport | The streaming send adapter |
artifactRenderers |
AppRenderer[] |
Tool-name → renderer (parser/preview/actual); drives inline previews + detailed view |
artifactCategories |
{ name; filter: { type: string[] } }[] |
Splits the artifact browser & workspace into sections |
⚠️ Only those four
ChatProviderPropsare actually forwarded (they're destructured explicitly inAgentInterface.tsx). OtherChatProviderPropsare accepted by the type but not passed through.
AgentInterface-specific:
| Prop | Type | Default | Notes |
|---|---|---|---|
componentLibrary |
Library (react-lang) |
— | Auto-derive assistant (and user) message rendering via GenUI when components.AssistantMessage is absent |
onAction |
(event: ActionEvent) => void |
— | GenUI actions the chat does not handle itself, such as custom actions from defineAction |
components |
{ AssistantMessage?; UserMessage?; ToolCallTimeline? } |
— | Explicit render overrides; ToolCallTimeline replaces the turn-level tool activity UI |
theme |
ThemeProps |
— | Passed to <ThemeProvider> |
disableThemeProvider |
boolean |
false |
Skip the internal <ThemeProvider> wrapper |
logoUrl |
string |
"" |
Brand logo (default SidebarHeader + MobileHeader) |
agentName |
string |
"" |
Agent display name |
starters |
ConversationStarterProps[] |
— | Global starters inherited by Welcome (if active) or the Composer |
starterVariant |
"short" | "long" | "card" |
— | Layout variant for inherited starters |
path |
string |
— | Controlled current path (pair with onNavigate); undefined = thread view |
defaultPath |
string |
— | Uncontrolled initial path (ignored when onNavigate is set) |
onNavigate |
(next: string | undefined) => void |
— | Presence selects controlled mode |
children |
ReactNode |
— | Slots (see above) |
Custom message components
type AssistantMessageComponent = React.ComponentType<{
message: AssistantMessage;
isStreaming: boolean;
}>;
type UserMessageComponent = React.ComponentType<{ message: UserMessage }>;
type ToolCallTimelineComponent = React.ComponentType<{
activities: ToolActivity[];
steps: TimelineStep[];
isLast: boolean;
awaitingResponse: boolean;
}>;
Provided via components, these fully replace the default rendering (including the container
and avatar). Resolution order, per message kind:
components.X → GenUI (if componentLibrary) → built-in default.
Named exports (from index.ts)
| Export | Kind | Purpose |
|---|---|---|
AgentInterface |
component | The compound root |
AgentInterfaceProps, AgentInterfaceComponents, ToolCallTimelineComponent |
types | Root props / override map |
SidebarItem, SidebarItemProps |
component + type | Standalone nav row |
ArtifactNav, ArtifactNavProps |
component + type | Artifact-category nav |
useNav, NavContextValue |
hook + type | Read/drive navigation from inside the tree |
RouteProps |
type | <AgentInterface.Route> props |
WorkspaceProps |
type | <AgentInterface.Workspace> props |
ThreadHeaderProps |
type | <AgentInterface.ThreadHeader> props |
ThemeModeToggle, ThemeModeToggleProps |
component + type | Light/dark toggle (pair with useThemeModePreference) |
artifactListPath, artifactViewPath |
functions | Build reserved artifacts/… paths |
Render tree & provider stack
AgentInterface.tsx mounts the providers; Container.tsx mounts the UI-state providers; the body
(AgentInterfaceBody) does the view switch.
<ThemeProvider> (skipped if disableThemeProvider)
└ <ChatProvider> react-headless: threads, artifacts, detailed-view stores
└ <NavProvider> path + navigate (controlled/uncontrolled)
└ <StartersProvider> global starters + variant
└ AgentInterfaceBody → <Container>
└ <AgentInterfaceStoreProvider> sidebar/workspace open, agentName, logoUrl
└ <ShellStoreProvider> library-wide shell store (see State model)
└ <LayoutContextProvider> "mobile" | "tray" | "fullscreen"
└ <Tooltip.Provider> single shared Radix tooltip provider (delay 250ms)
└ .openui-agent-container
├ <SidebarContainer> … (default sidebar OR your <Sidebar> slot)
└ view switch:
├ reserved `artifacts/…` → ArtifactBrowserPage | ArtifactViewPage
├ matched <Route> → route children
└ thread view (path===undefined):
<ThreadContainer>
MobileHeader · ThreadHeader · [Welcome] ·
<ScrollArea><Messages/></ScrollArea> · Composer
<Workspace/> (rail, thread view only)
└ slots.rest (unrecognized children, rendered as-is)
The view switch (in AgentInterfaceBody) has a strict priority:
- Reserved
artifacts/paths are matched before user routes (parseArtifactPath). - Then an exact-match user
<Route path="…">. - Otherwise (
path === undefined) the normal thread view, which is the only view that also renders theWorkspacerail.
Composition modes (A / B / C)
Most slots support three levels of customization (the codebase comments call them Modes A/B/C):
- Mode A — omit it. The default renders. (
Defaultstory.) - Mode B — pass props. Tweak the default without rebuilding it, e.g.
<AgentInterface.SidebarHeader logo={…} agentName={…} collapseButton={false} />(CustomSidebarHeaderstory). - Mode C — pass children. You own the entire inside; Mode B props are ignored (and dev-warns if
both are passed). e.g.
<AgentInterface.Sidebar>…</AgentInterface.Sidebar>(FullSidebarOverride),<AgentInterface.Workspace>…</AgentInterface.Workspace>(WorkspaceCustomChildren),<AgentInterface.Welcome>…</AgentInterface.Welcome>(WelcomeCustomChildren).
When you go Mode C on the Sidebar, compose it from the building-block members:
SidebarHeader, SidebarContent, SidebarSeparator, SidebarItem, ArtifactNav, NewChatButton,
HistoryButton, ThreadList, and SidebarFooter + ThemeModeToggle at the bottom.
State & data model
External (react-headless) — the data
Mounted by <ChatProvider>. Read via hooks:
useThread(selector)—messages,isRunning,isLoadingMessages,threadError,processMessage,cancelMessage.useThreadList(selector)— thread history +selectThread.useArtifactList()/useArtifactCategories()/useArtifactRendererRegistry()/useArtifactStorage()— the artifact registry & config.useDetailedView(viewId)/useDetailedViewStore()/useActiveDetailedView()— the side-panel open/active state.MessageProviderwraps each message so deep children can read it.
Internal — UI/chrome state
Two separate zustand stores are mounted in Container.tsx. They are not the same store and
serve different consumers:
| Store | File | Holds | Read with | Used by |
|---|---|---|---|---|
| AgentInterfaceStore | _shared/store/store.tsx |
isSidebarOpen (default false), isHydrated, isWorkspaceOpen (default false), agentName, logoUrl |
useAgentInterfaceStore |
All AgentInterface chrome (sidebar, workspace toggles, header) |
| ShellStore | ../_shared/store/store.tsx (library-wide, shared with OpenUIChat) |
isSidebarOpen, isWorkspaceOpen (default true), agentName, logoUrl, showAssistantLogo |
useShellStore |
The GenUI assistant-message components, which read agentName/logoUrl/showAssistantLogo from here |
Both are seeded from the same logoUrl/agentName and kept in sync to props via effects, but
their isWorkspaceOpen defaults differ and they are not cross-synced. See
Gotchas.
Saved preferences & server rendering
Saved UI preferences go through one helper, utils/preferences.ts (readPreference /
writePreference: JSON values, never throws, so blocked or full storage just means nothing is
kept). Each is read once after hydration, before paint, so server HTML and the client's first
render match.
- Sidebar open (
openui-agent-sidebar-open): read and written bySidebarContainer(desktop only, so opening the drawer on mobile isn't remembered on desktop). The store holds just the liveisSidebarOpen; onceisHydratedis set,SidebarContainerrestores the saved choice without animating. - Sidebar width (
openui-agent-sidebar-width): read and written bySidebarResizeEdge, which sets it straight on the container as a CSS variable. - Theme (
openui-theme-mode):ThemeProvider/useThemeModePreference.ts. - Reveal: until
isHydratedis set,Containerhides its contents (visibility, so layout still measures) under a fading loader, and keeps transitions off until the restored styles settle.
Plus three React contexts:
NavContext(_shared/navContext.tsx) —{ path, navigate }.useNav()(throws outside the tree) anduseOptionalNav()(returnsnull).StartersContext(_shared/startersContext.tsx) — inheritedstarters+starterVariant.LayoutContext(../../context/LayoutContext) —"mobile" | "tray" | "fullscreen", derived from the container's measured width.SidebarVisualStateContext(Sidebar.tsx) — the sidebar's animation state machine (expanded/collapsing/collapsed/expanding) so items know when to show collapsed tooltips.
Navigation & routing
Navigation is a single path: string | undefined string held by NavProvider, with the standard
controlled/uncontrolled split:
- Uncontrolled (default): internal state starts at
defaultPath. - Controlled: pass
onNavigate(its presence flips the switch) and ownpathyourself. (RoutingandControlledRoutingstories.)
path === undefined ⇒ the thread view. Any other string is matched in this order:
- Reserved artifact paths (
_shared/artifactPaths.ts), matched first:artifacts/{category}→ searchable list (ArtifactBrowserPage)artifacts/{category}/{id}→ full-page view (ArtifactViewPage){category}is URI-encoded, or the literalallwhen no categories are configured.- Build them with
artifactListPath(name?)/artifactViewPath(name, id); parse withparseArtifactPath. Controlled consumers must round-trip these paths verbatim.
- User
<AgentInterface.Route path="…">— exact match only (no params/wildcards in v1). The route's children replace the entire thread region (header, messages, composer all hidden). MultipleRoutesiblings are supported.
SidebarItem integrates with nav: give it a path and it calls navigate(path) on click and
auto-selects when nav.path === path (override with the selected prop). On mobile it also closes
the sidebar after navigating.
Message rendering pipeline
Entry point is <Messages> (in Thread.tsx), rendered inside <ScrollArea>:
<Messages>
messages.map → <MessageProvider><RenderMessage …/></MessageProvider>
if isRunning → loader (<MessageLoading/>)
else if threadError → <ThreadError/> (Callout, "Something went wrong")
RenderMessage (memoized) switches on message.role:
tool→ rendersnull(tool output is rendered inline under its parent assistant message).assistant→components.AssistantMessageif provided, elseAssistantMessageContainer › AssistantMessageContent.user→components.UserMessageif provided, elseUserMessageContainer › UserMessageContent.- other roles (
system/developer/reasoning/activity) → skipped.
Assistant content + tool calls
AssistantMessageContent:
- Renders
message.contentvia<MarkDownRenderer>. - Renders each
message.toolCalls[]as a<ToolCallComponent>(the call bubble). - Pairs tool results: scans
allMessagesfor the run of consecutiverole: "tool"messages immediately after this assistant message, matches eachtoolMessage.toolCallIdback to atoolCall, and dispatches to<ToolMessageRenderer>(falling back to<ToolResult>when no renderer matches). (This pairing is O(n) per message and is a known cleanup target — see Gotchas.)
Tool → artifact renderer dispatch
ToolMessageRenderer (_shared/tool-renderer/) looks up toolCall.function.name in the
artifactRenderers registry:
- No match → renders the
fallback(<ToolResult>). - Match →
<RendererInstance>, which:- runs
renderer.parser({ args, response }, { isStreaming })→{ props, meta } | null, - if
metais present, registers the artifact in ThreadContext (so it appears in the Workspace rail) and unregisters on unmount, - renders
renderer.preview(props, controls)inline + a<DetailedViewPanel>containingrenderer.actual(props, controls)for the side panel.
- runs
RendererInstance carefully keeps an open detailed view alive as a streamed artifact's viewId
transitions from a temporary useId() to its real ${id}:${version}, and re-points the active view
when an edit bumps the version onto a new instance.
User content
UserMessageContent.tsx handles the full AG-UI InputContent union (text | image | audio | video | document | binary):
- String content → stripped of
<content>/<context>sentinel wrappers (separateContentAndContext). - Array content → each part resolved by
resolveInputPart()into a render-ready descriptor, then rendered in array order (preserving text/media interleave). - Security is built in: every URL is vetted by
sanitizeUrl(onlyhttp(s):+ allowlisteddata:), base64data:URIs bybuildDataUri(ALLOWED_DATA_MIME= image/audio/video + PDF only —text/htmland arbitraryapplication/*are deliberately excluded as XSS surface). - Media renders as
<img>/<audio>/<video>(lazy, withonError→ file chip); everything else, or any failed/blocked source, degrades to a downloadable file chip rather than being dropped. - A
default: neverexhaustiveness guard makes any new union member a compile error.
Artifacts, the Workspace rail & DetailedView
There are two distinct artifact surfaces, easy to confuse:
- Workspace rail (
Workspace.tsx) — a per-thread, right-edge list of artifacts registered by the current thread's tool calls (viaRendererInstance→ ThreadContext). Renders nothing while the registry is empty, so drop-in users withoutartifactRenderersnever see it. It has All / Artifacts / Apps tabs (an "Apps" category is detected bycategory.name.toLowerCase() === "apps"), an animated tab indicator, and a mobile drawer. Clicking an item opens its DetailedView; the rail auto-closes while a DetailedView is open. Shown only in the thread view; hidden on mobile and on Route/artifact pages. - Artifact browser (
ArtifactBrowserPage/ArtifactViewPage) — a global, storage-backed, searchable browser at the reservedartifacts/…paths, driven bystorage.artifact. TheArtifactNavsidebar entries link into it.
DetailedView is the resizable side panel. On desktop, ThreadContainer splits into a chat panel
- a
ResizableSeparator+ the detailed-view panel (useDetailedViewResizedrives the drag and writes width directly to the panel ref). On mobile it becomes an overlay (DetailedViewOverlay).DetailedViewPanelportals its content intoDetailedViewPortalTarget.
An AppRenderer (consumer-defined) is the unit that powers all of this:
{
type: "th_dashboard",
toolName: "th_dashboard:create", // matched against toolCall.function.name
parser: ({ args, response }, { isStreaming }) =>
response ? { props, meta: { id, version, heading } } : null,
preview: (props, controls) => <InlineCard …/>, // shown inline in the thread
actual: (props, controls) => <FullView …/>, // shown in the detailed-view panel
}
The
typestrings (th_dashboard/th_report/th_presentation) and the${type}:createtool-name convention are consumer conventions mirrored on the agent side — they are documented by the stories, not enforced by the library.
Layout & responsiveness
Container.tsx measures its own width (useElementSize) and derives a layout mode:
width < 768 → "mobile" (.openui-agent-container--mobile)
width > 768 → "fullscreen"
width === 768 (exact) → "tray" (only a 1px window; rarely hit, has no CSS; see Gotchas)
The breakpoint is currently a hardcoded 768 with a // TODO: revisit this logic.
Responsiveness is class-driven, not media-query-driven. The dominant mechanism is the ancestor
selector .openui-agent-container--mobile & (plus --detailed-view-active), used throughout the
SCSS. There are only two real @media queries in the whole component (and one of them is currently
a no-op). If you need responsive behavior, prefer the layout class over adding a breakpoint.
Styling & theming
Tokens
Every SCSS partial starts with @use "../../cssUtils" as cssUtils; and references design tokens
as Sass aliases that compile to CSS custom properties:
padding: cssUtils.$space-m; // → var(--openui-space-m)
color: cssUtils.$text-neutral-primary; // → var(--openui-...)
border-radius: cssUtils.$radius-xl;
@include cssUtils.typography($family, $variant); // font shorthand
- The token prefix is
openui(notcrayon).cssUtils.scss+openui-defaults.scssare auto-generated — don't hand-edit them. They emit:rootcustom properties (including aprefers-color-scheme: darkblock) plus the$aliasSass layer. - Color discipline is total: there are zero hardcoded hex/rgb/oklch values in the component. Always go through a token. Radii, shadows, and most spacing are tokenized too.
- Theme consumers override
--openui-*custom properties (viatheme→<ThemeProvider>, or their own CSS).
Build / aggregation
AgentInterface/agentInterface.scss @use's the 11 root + components/ partials (sidebar, threadlist,
thread, mobileHeader, resizableSeparator, conversationStarter,
welcomeScreen, components/composer, components/desktopWelcomeComposer,
artifactBrowser, workspaceSidebar) + the .openui-agent-container rules
→ components/index.scss @forward "./AgentInterface/agentInterface.scss"; (line 44)
→ components/index.css the shipped aggregate
Two things that chain does not include:
- The detailed-view styles (
_shared/detailed-view/*.scss) actually ship via the library-widecomponents/_shared/shared.scss(forwarded atcomponents/index.scssline 61), not viaagentInterface.scss. AgentInterface/_shared/shared.scssis currently orphaned — nothing@uses /@forwards it.
There is no src/styles/agentInterface.scss entry, so AgentInterface ships only inside the
aggregate components/index.css — it has no granular per-component CSS twin, and is therefore not
importable on its own via the ./layered/styles/* granular paths. (See Gotchas.)
Layered CSS opt-in
The @layer openui { … } wrapping is applied at build time by cp-css.js (it mirrors the
unlayered output into dist/layered/**). Do not write @layer in source SCSS — none exists
today, and that's correct.
Conventions when adding styles
- State via BEM modifiers (
--collapsed,--selected,--active,--animating) and data-attributes ([data-sidebar-visual-state],[data-drafting],[data-overflow-*]). :has()is used for cross-component layout coordination.- Hoist local layout/motion constants as
$varsat the top of the partial (seesidebar.scss,workspaceSidebar.scss,composer.scssfor the pattern). - New partial? Add a
@use "./yourFile.scss";line toagentInterface.scss.
Directory guide
AgentInterface/
├ AgentInterface.tsx Root: props, extractSlots, provider stack, AgentInterfaceBody view switch
├ Container.tsx Flex shell; width→layout mode; mounts the two stores + LayoutContext + Tooltip.Provider
├ Route.tsx Slot marker for routable views (renders null; consumed by parent)
├ Sidebar.tsx SidebarContainer/Header/Content/Separator/Footer + collapse/expand state machine
├ SidebarResizeEdge.tsx Draggable sidebar edge (220–420px, snaps shut below 150px; width saved in the store)
├ HistoryButton.tsx Collapsed-rail thread-history menu
├ ThemeModeToggle.tsx Light/dark toggle for SidebarFooter
├ SidebarItem.tsx Styled, nav-aware clickable row (exported)
├ SidebarSlot.tsx The <AgentInterface.Sidebar> slot marker
├ SidebarTooltip.tsx Collapsed-sidebar tooltip (right/center, fixed offset)
├ ThreadList.tsx Date-grouped thread history + per-thread menu (Rename/Delete)
├ RenameChatDialog.tsx Rename dialog shared by ThreadList and ThreadHeader
├ Thread.tsx ThreadContainer, ScrollArea, Messages, RenderMessage, WorkspaceToggleButton, ThreadError, loader
├ ThreadHeader.tsx Floating desktop header (start/center/end, chat title, actions menu)
├ UserMessageContent.tsx Full AG-UI InputContent union renderer (+ URL/data allowlists, file chips)
├ MobileHeader.tsx Mobile top bar
├ NewChatButton.tsx New-chat affordance
├ Composer.tsx Thin re-export of components/Composer
├ ConversationStarter.tsx Starters ("short" | "long" | "card" variant)
├ WelcomeScreen.tsx Empty-state hero (title/description/image/starters, prompt-template tabs, or children)
├ Workspace.tsx Per-thread artifact rail (tabs, sections, mobile drawer)
├ ArtifactBrowserPage.tsx Global searchable artifact list (also exports preview/format helpers)
├ ArtifactNav.tsx Sidebar category nav into the browser (exported)
├ ArtifactViewPage.tsx Full-page artifact view
├ ResizableSeparator.tsx Keyboard+ARIA resize handle for the detailed-view split
├ useDetailedViewResize.ts Drag/keyboard resize logic (writes panel width imperatively)
├ components/ Composer, DesktopWelcomeComposer, AmbientLoader, Mascot/MascotLoader, WelcomeMascot (and their SCSS)
├ _shared/
│ ├ store/ AgentInterfaceStore (sidebar + saved preferences/workspace/agentName/logoUrl)
│ ├ navContext.tsx NavProvider / useNav / useOptionalNav
│ ├ startersContext.tsx StartersProvider / useStartersFromContext
│ ├ artifactPaths.ts Reserved artifacts/… path build+parse
│ ├ tool-renderer/ ToolMessageRenderer + RendererInstance
│ ├ detailed-view/ DetailedViewOverlay/Panel/PortalTarget
│ ├ types/ AssistantMessageComponent / UserMessageComponent
│ ├ utils/ misc helpers
│ └ AgentInterfaceTooltip.tsx, GalleryHorizontalEndIcon.tsx
├ *.scss Co-located styles (aggregated by agentInterface.scss)
└ stories/ Storybook — the de-facto usage reference
Note:
_shared/here is AgentInterface-local. The siblingcomponents/_shared/is a library-wide shared dir (used byOpenUIChattoo). Container pulls theShellStorefrom the library-wide one; everything else AgentInterface uses comes from its own local_shared.
Extending the component
Add a new top-level slot
- Create the component and export it.
- Attach it as a static member at the bottom of
AgentInterface.tsx(AgentInterface.MyThing = MyThing;) and add it to theAgentInterfaceComponentinterface. - Add
[MyThing, "myThing"]toSLOT_KEY_BY_TYPEand amyThing?: ReactElementfield toExtractedSlots. - Render
slots.myThing ?? <Default/>in the appropriate branch ofAgentInterfaceBody.
Add a custom message renderer — pass components={{ AssistantMessage, UserMessage }} (replaces
default rendering entirely), or a componentLibrary for GenUI auto-derivation.
Add an artifact type — define an AppRenderer (type + toolName + parser/preview/actual),
pass it in artifactRenderers, and optionally group it via artifactCategories. The agent emits a
tool call named toolName; the rest is automatic (inline preview, workspace entry, detailed view).
Add a route — drop <AgentInterface.Route path="/x">…</AgentInterface.Route> as a child and
navigate to /x (e.g. a SidebarItem path="/x").
Gotchas & known rough edges
These are real, current sharp edges — worth knowing before you touch the area. Deeper analysis and
prioritization live in .workspace/2026-06-21-agentinterface-study.md and
.workspace/2026-06-21-usermessagecontent-research.md.
- Slot identity — see the warning above;
memo/HOC/duplicate-module wrapping silently drops a slot. Use the canonicalAgentInterface.*members. - Two stores —
AgentInterfaceStorevs libraryShellStoreare mounted side by side with divergingisWorkspaceOpendefaults and no cross-sync. Read from the right one (chrome →useAgentInterfaceStore; assistant-message logo/name →useShellStore). - Local vs library
_shared—tool-renderer,detailed-view,types,utilsexist in bothAgentInterface/_shared/and the library-widecomponents/_shared/. They overlap; confirm which one you're importing. - Hardcoded values — the
768breakpoint (Container.tsx), the "reading column" widths (880/800px repeated across several partials), chat-resize clamps (useDetailedViewResize.ts, whereMIN === INITIALso the panel can't shrink below its initial width), motion durations/ easings, the z-index ladder, and a duplicated scrollbar block are all candidates to lift into shared tokens/props. - English-only strings & aria-labels — placeholders,
"New Chat", workspace tab labels, date groups, and many aria-labels are baked English with no i18n surface.ArtifactNaveven derives a category's icon-background class by matching the English label. logoUrl/agentNamedefault to""— omitting them yields an empty-looking header.prefers-reduced-motionis not honored anywhere despite heavy animation.traylayout (exact integer width768) adds no CSS class and is only reachable in a 1px window —widthiselement.clientWidth(an integer), so768is attainable but rare. Treat with care.- Typography token (fixed in
4c801739) — earlier code passed the invalidtypography(primary, default)(there is noprimarycategory, so it emitted nofont).thread.scssandartifactBrowser.scssnow correctly usetypography(body, default). Other components outside AgentInterface may still carry the invalid call — a separate per-site sweep.
⚠️ Historical note: an earlier study claimed
UserMessageContentwas incomplete (text+binary only). That is no longer true —UserMessageContent.tsxnow implements the fullInputContentunion with allowlists and chip fallbacks, and it is wired intoThread.tsx. Trust the code.
Local development
- Stories / visual reference:
stories/AgentInterface.stories.tsx(run the package's Storybook). The stories use mock LLM/storage helpers from__test-helpers/mockChat. - Styles: edit the co-located
*.scss; new partials must be@used fromagentInterface.scss. Never edit the generatedcssUtils.scss/openui-defaults.scss. - Tokens: if you need a value, check for an existing
$space-*/$radius-*/$text-*token before introducing a literal.