The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Plan: Remove tfy-web-components, own shadcn primitives + themes
Hard-cut tfy-web-components. Own primitives (shadcn-style, in-repo),
Markdown/OpenUI/syntax-highlighter/Monaco, Lucide icons (swappable map +
SVG transform), and a theme object with presets
(trueforge | claude | chatgpt | gemini) plus full token / className /
icon / brand / content classNames customization. Shell also accepts a
custom layout React component built from Thread, thread list, etc.
Principle: everything customizable
Hosts must be able to restyle, rebrand, and rearrange chrome without forking the SDK. Layers (each independently overridable):
| Layer | What it customizes | How |
|---|---|---|
| Preset | Baseline look | theme.preset |
| Tokens | Colors, radius, fonts, bubble colors | theme.tokens + CSS vars |
| Brand | Square icon, wide logo, and display name | theme.brand (marks via slots) |
| Icons | Action / UI icon set | theme.icons (Lucide + SVG transforms) |
| Content classNames | Markdown, syntax-highlighter, OpenUI, Monaco | theme.classNames |
| Root class | Arbitrary host utilities | theme.className |
| Host CSS | Any token / layout tweak | documented :root / .aui-root overrides |
| Slots | Replace any React piece | overrides / SlotsProvider |
| Layout | Entire chrome arrangement | layout string or custom React component |
No visual or chrome element should be hard-wired to TrueFoundry branding. Defaults may ship TFY look; every surface must accept a host override.
Constraint
All work in @truefoundry/trueforge-ui. No runtime package changes for this
track (orthogonal to docs/server.md).
Locked decisions
| Decision | Choice |
|---|---|
| Cutover | Hard cut — remove dep + peer |
| Primitives | shadcn components copied into this repo |
| Coverage | Everything currently pulled from tfy |
| Slot API | Breaking — drop Button.Primary / icon-string contracts; new shadcn-aligned props |
| Icons | Lucide defaults; host can replace map + supply SVG transforms |
| Brand | Icon/logo URLs (per-mode) via theme.brand; component marks via the BrandLogo slot |
| Theme API | Object (not string-only); every look aspect customizable |
| Presets | Inspired-by packs: trueforge (default), claude, chatgpt, gemini |
| Custom styles | CSS tokens + className; host may also import CSS (documented). No “load CSS file” prop |
| Light / dark | Controlled mode on the theme object or omit → uncontrolled useTheme().setTheme |
| React overrides | Structural pieces via overrides / slots; full chrome via layout component |
| Markdown | In-repo; OpenUI kept; code fences via syntax-highlighter |
| Monaco | In-repo (code artifacts / rich code surfaces); classNames overridable |
| Content styling | theme.classNames for markdown, highlighter, OpenUI, Monaco |
| Layout | Built-in presets or host React layout using exported building blocks |
| Release | Breaking 0.x (slot API + styles + drop tfy) |
Inventory → replacements
Primitives (slot defaults today)
| Current (tfy) | Target (in-repo shadcn-style) |
|---|---|
Button |
Button (variants: default, secondary, ghost, destructive, outline, size) |
IconButton |
Button size=icon or thin IconButton wrapper |
Modal / Dialog |
Dialog (+ sheet if drawer needs it) |
Accordion* |
Accordion |
LightTooltip |
Tooltip |
Skeleton |
Skeleton |
Avatar* |
Avatar |
Spinner |
small Spinner / loader (FA or inline SVG) |
DropdownMenu |
DropdownMenu |
Feature atoms that wrap tfy molecules
Rebuild in-repo (keep existing atom names / slots where possible, change props):
- Bubbles:
AssistantMessageBubble,UserMessageBubble,UserMessageEdit - Tools:
ToolCallCard,ToolCallContentBlock,ToolApprovalBar,ToolGroupCard,SubAgentCard,SandboxToolCallCard,AgentStepsCard,ReasoningCard - Prompts:
AskUserPrompt,McpAuthPrompt,ResumeUnavailable Markdown(OpenUI + highlighter)- Layout helpers using
IconProvider→ local icon resolver
Theme / icons / brand infra
| Remove | Replace with |
|---|---|
tfy-web-components/theme.css |
Own palette + semantic tokens in styles.css |
tfy ThemeProvider / useTheme |
SDK ThemeProvider owned here |
IconProvider + registerIcons |
IconRegistry + theme.icons / setIcons |
| Hard-coded TFY marks | theme.brand.icon / logo consumed by header, welcome, and widget FAB |
Code surfaces (Monaco + syntax highlighter)
Not currently imported anywhere in src/ — dormant tfy surface, but real:
tfy's own Markdown fenced-code rendering depends on it, so dropping tfy
loses it silently unless ported explicitly.
| Current (tfy) | Target (in-repo) |
|---|---|
molecules/monacoEditorCore/MonacoEditorCore (thin monaco-editor wrapper: onMount/beforeMount/theme/options) |
Local MonacoEditorCore atom, same prop surface, direct monaco-editor dependency |
molecules/SimpleCodeEditor (copy/download/expand/fullscreen/line-numbers atop MonacoEditorCore) |
Local CodeEditor atom (rebuilt on local MonacoEditorCore, same feature set) |
molecules/CopyField / CopyFieldHighlighted (copy affordance used by SimpleCodeEditor) |
Fold into local CodeEditor copy button; no separate primitive needed |
react-syntax-highlighter used internally by tfy Markdown/MarkdownWithOpenUI for non-OpenUI fenced code |
Local SyntaxHighlighter atom, called from the in-repo Markdown atom for non-openui fences (same line-numbers / light-dark theme mapping) |
New direct dependencies this implies: monaco-editor, react-syntax-highlighter
(+ @types/react-syntax-highlighter).
Theme API (target)
type ThemeMode = "light" | "dark" | "system";
type ThemePreset = "trueforge" | "claude" | "chatgpt" | "gemini";
type SemanticTokens = {
// Across product
sidebarBg: string;
topbarBg: string;
primaryBg: string;
secondaryBg: string;
border: string;
fontFamily: string; // maps to --font-agent-ui
// Building blocks
inputBoxBg: string;
inputBorder: string;
textPrimary: string;
textSecondary: string;
cardBg: string;
dropdownSelectedItemBg: string;
dropdownSelectedItemText: string;
// Chat
userMessageBg: string;
userMessageText: string;
assistantMessageBg: string;
assistantMessageText: string;
// Buttons
primaryButtonBg: string;
primaryButtonHover: string;
primaryButtonText: string;
secondaryButtonBg: string;
secondaryButtonHover: string;
secondaryButtonText: string;
ghostButtonBg: string;
ghostButtonHover: string;
ghostButtonText: string;
// Status
successBg: string;
successText: string;
failureBg: string;
failureText: string;
warningBg: string;
warningText: string;
// Kept internals
focusRing: string;
radius: string;
composerRadius: string;
overlay: string;
shadowColor: string;
scrollbarThumb: string;
};
/** UI action icons (send, attach, copy, …) — Lucide, React nodes, or SVG wrappers */
type IconMap = Record<
string,
| LucideIcon
| React.ReactNode
| ((props: IconProps) => React.ReactNode)
| React.FC<React.SVGProps<SVGSVGElement>>
>;
/**
* Brand image sources. `light` / `dark` pick per resolved theme mode and fall
* back to each other, then to `src`.
*/
type BrandLogoConfig = {
src?: string;
light?: string;
dark?: string;
};
type BrandImage = string | BrandLogoConfig;
/**
* Product branding — distinct from `icons` (UI chrome).
* Consumed wherever a product mark appears (header, welcome, widget FAB,
* empty states, assistant avatar fallback).
*
* Images only: to render a component, override the `BrandLogo` slot instead, so
* brand marks follow the same replacement path as every other atom.
*
* Set `mode`, then pass the fields that mode requires:
* - omit `brand`: TrueForge wordmark / square mark
* - `icon-title`: `name` + optional `icon`
* - `icon-only`: `name` + `icon`
* - `logo`: `name` + `icon` + `logo`
*/
type BrandMode = "icon-title" | "icon-only" | "logo";
type BrandConfig =
| { mode: "icon-title"; name: string; icon?: BrandImage; logo?: never; href?: string }
| { mode: "icon-only"; name: string; icon: BrandImage; logo?: never; href?: string }
| { mode: "logo"; name: string; icon: BrandImage; logo: BrandImage; href?: string };
type ThemeConfig = {
preset?: ThemePreset; // default: "trueforge"
mode?: ThemeMode; // omit = uncontrolled (useTheme().setTheme)
tokens?: Partial<SemanticTokens>;
brand?: BrandConfig; // set brand.mode, then required fields
className?: string; // applied on .aui-root (or theme root)
icons?: IconMap; // full/partial UI icon replace + SVG transforms
/** Per-surface className hooks for content renderers */
classNames?: ContentClassNames;
};
/**
* Override CSS classes (and optional style props) on content engines.
* All fields optional; merge with defaults via `cn()`.
*/
type ContentClassNames = {
/** Wrapper / prose root for rendered markdown */
markdown?: string;
inlineCode?: string; // Inline code rendered by Markdown
/** Non-openui fenced code blocks (syntax-highlighter root / pre / code) */
syntaxHighlighter?: {
root?: string;
pre?: string;
code?: string;
lineNumber?: string;
};
/** OpenUI fenced-block host + common child hooks */
openui?: {
root?: string;
scope?: string;
};
/** Monaco editor / diff surfaces */
monaco?: {
root?: string;
editor?: string;
/** Optional Monaco `theme` id or defineTheme hook name — styling adjacent */
monacoTheme?: string;
};
};
type BuiltInLayout = "sidebar" | "drawer" | "dock" | "widget";
/**
* Shell layout: built-in string **or** a host component that composes
* exported building blocks (`Thread`, `ThreadListContainer`, …).
*/
type LayoutProp = BuiltInLayout | React.ComponentType<{ className?: string }>;
// Usage — theme + custom layout
function MyLayout({ className }: { className?: string }) {
return (
<div className={cn("flex h-full", className)}>
<aside className="w-64 border-r">
<ThreadListContainer />
</aside>
<main className="flex min-w-0 flex-1 flex-col">
<Thread />
</main>
</div>
);
}
<TrueForgeUI
layout={MyLayout} // or 'sidebar' | 'drawer' | 'dock' | 'widget'
theme={{
preset: 'claude',
mode: 'dark',
tokens: { primaryButtonBg: '#…', fontFamily: '"My Font", system-ui' },
brand: {
mode: 'logo',
name: 'Acme Agent',
icon: { light: '/acme-icon.svg', dark: '/acme-icon-dark.svg' },
logo: { light: '/acme-wordmark.svg', dark: '/acme-wordmark-dark.svg' },
},
className: 'my-chat',
icons: { send: MySendSvg, paperclip: MyAttachSvg },
classNames: {
markdown: 'prose prose-neutral dark:prose-invert max-w-none',
inlineCode: 'font-semibold',
syntaxHighlighter: {
root: 'my-code-block rounded-lg',
pre: 'bg-zinc-950 p-4',
code: 'text-sm font-mono',
lineNumber: 'opacity-60',
},
openui: { root: 'my-openui-host', scope: 'p-2' },
monaco: { root: 'my-monaco h-64', editor: 'rounded-lg', monacoTheme: 'vs-dark' },
},
}}
/>
Resolution order: preset defaults → tokens → brand / icons →
classNames → host CSS variables (documented) → className utilities.
Component resolution is separate: the nearest SlotsProvider override wins,
then a parent override, then defaultSlots. An override receives the exact
props object for that atom; do not assume container-composed content is passed
as children.
Custom styles without the object: host CSS still works:
.aui-theme-root {
--primary-button-bg: #e11d48;
--font-agent-ui: 'My Font', system-ui, sans-serif;
}
/* Or target documented content hooks */
.aui-root .aui-markdown {
/* … */
}
.aui-root .aui-syntax-highlighter {
/* … */
}
.aui-root .aui-openui {
/* … */
}
.aui-root .aui-monaco {
/* … */
}
Brand system
- All product marks render through
<BrandLogo />— one component, never hard-coded TFY assets in layouts or atoms. Layouts resolve it viauseSlot, so a host override reaches every call site. - Hosts pick chrome with
brand.mode(icon-title|icon-only|logo). Layout chrome usesresolveBrandChrome(brand)for expanded/collapsed mark variant and whether to show the text title. Custom layouts should call the same helper instead of re-deriving fields. BrandLogorendersiconfor compact surfaces. Withvariant="logo", it renders the optional wider logo and falls back to the square icon.theme.brandcarries image sources only (URL or{ src, light, dark }). Component-valued marks go through theBrandLogoslot, so brand replacement uses the same mechanism as every other atom instead of a second node-shaped escape hatch in the theme config.theme.brand.nameis required with every mode and always labels configured images. Visible title text only appears formode: 'icon-title'. Foricon-onlyandlogo,nameis alt-only.- Omitting
brandkeeps the default TrueForge wordmark in expanded chrome and the square mark when collapsed.hrefwraps configured images in a same-tab link. { light, dark }sources resolve against the provider's theme mode, so a host mark tracks light/dark without a custom component. A single configured source covers both, so{ light }alone never renders a missing image; a config with no usable source falls back to the default mark rather than an empty<img>.
Icon system
- Ship default Lucide map (stable FA-style keys via
IconRegistry). theme.iconsmerges over defaults (partial or full replace).- Allow React SVG / SVGR transform wrappers as values.
- Custom agent SVGs stay on the SVGR pipeline (
registerAgentIcons). useIcon(name)/<Icon name="paperclip" />for all call sites (breaking vs string props on tfyIconButton).- Brand marks are not mixed into
icons— usetheme.brandso product identity stays separate from action icons.
For named UI icons the order is theme.icons[name] → registry default. The
robot is also the final brand fallback, so theme.brand.icon still takes
precedence over theme.icons.robot. Preset-specific icons such as
welcome-sparkle and OAuth state icons (oauth-loading, oauth-success,
oauth-error) use the same lookup order.
Layout override
TrueForgeUI / chat shell layout prop:
| Value | Behavior |
|---|---|
"sidebar" | "drawer" | "dock" | "widget" |
Built-in layouts (unchanged) |
React.ComponentType<{ className?: string }> |
Host-owned chrome |
Custom layouts compose exported building blocks (same as today’s advanced compose path), for example:
Thread/ThreadContainerThreadListContainerComposerpieces / slot-backed atoms as needed- Brand helpers (
BrandLogo,resolveBrandChrome,useBrandName) anduseTheme
The shell still wraps the custom layout with theme + slots + chat provider; only the chrome tree is replaced. Equivalent to skipping built-in layouts without dropping providers.
import { TrueForgeUI, Thread, ThreadListContainer } from '@truefoundry/trueforge-ui';
function CenteredLayout() {
return (
<div className="mx-auto flex h-full max-w-3xl flex-col">
<ThreadListContainer />
<Thread />
</div>
);
}
<TrueForgeUI
server={server}
agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
layout={CenteredLayout}
theme={{ preset: 'gemini' }}
/>;
Presets (inspired-by)
Ship as CSS variable maps under e.g. src/theme/presets/:
| Preset | Intent (not a clone) |
|---|---|
trueforge |
Current indigo semantic look |
claude |
Warm paper bg, soft borders, restrained accent |
chatgpt |
Cool gray chrome, green/teal send accent, flat bubbles |
gemini |
Light airy surface, blue accent, slightly larger radius |
Each preset defines light + dark token sets. Document that these are stylistic homages, not product replicas.
Markdown / OpenUI / syntax-highlighter / Monaco
- Replace
MarkdownWithOpenUIwith in-repoMarkdownatom. - Keep
@openuidev/*(already viaopenui.css) as first-party styling surface; theme tokens should flow into OpenUI where possible. - Fenced code (non-openui): syntax-highlighter themed from semantic tokens
and
theme.classNames.syntaxHighlighter. - Monaco in-repo for rich code / artifact surfaces; style via
theme.classNames.monaco(+ optionalmonacoThemeid). - Stable DOM hooks (
aui-markdown,aui-syntax-highlighter,aui-openui,aui-monaco) so host CSS works without the theme object. - Preload path: replace
preloadMarkdownOpenUIwith local equivalent. - Pass
theme.classNames.markdown/openuiinto the Markdown/OpenUI hosts.
Supported hooks are markdown, inlineCode,
syntaxHighlighter.{root,pre,code,lineNumber},
openui.{root,scope}, and monaco.{root,editor,monacoTheme}.
The standalone MCP OAuth callback selected by TrueForgeUI skips server
resolution, but remains inside the same theme and slot provider boundary as the
main shell.
Call flow
TrueForgeUI({ layout, theme, overrides, … })
└─ SlotsProvider / ThemeProvider
├─ apply preset → CSS variables on .aui-root
├─ merge theme.tokens / brand / icons / classNames / className
├─ layout = built-in | <HostLayout />
└─ defaultSlots → local shadcn primitives + feature atoms
├─ BrandLogo wherever the product mark appears
└─ Markdown / OpenUI / syntax-highlighter / Monaco
(classNames from theme)
Phases
Phase 0 — Spec freeze
- Keep this doc as the source of truth.
- List every tfy import → owner file → replacement (use inventory above).
- Final
ThemeConfig+ new primitive prop types.
Done when: interfaces agreed; inventory complete.
Phase 1 — Token foundation (no full visual rewrite yet)
- Stop importing
tfy-web-components/theme.css. - Inline a minimal palette + keep existing semantic
@layertokens. - Own
ThemeProvider/useTheme(mode light/dark/system); wireSlotsProviderto it. - Apply
theme.className+ CSS vars fromtheme.tokens/preseton root. - Introduce
BrandConfigplumbing (useBrand,useBrandName,<BrandLogo />) even if defaults still point at TFY assets.
Done when: app runs with owned tokens (tfy components may still be present);
host can override --primary-button-bg and swap theme.brand.icon / logo.
Phase 2 — shadcn primitives + icon + brand registry
- Add in-repo primitives under
src/atoms/primitives/(orsrc/ui/). - New slot defaults; break compound Button / icon-string APIs.
- Lucide
IconRegistry; migrate call sites; supporttheme.icons. - Wire layouts / welcome / widget FAB / avatar fallbacks to
theme.brand. - Update
docs/customization.mdfor new override contracts (tokens, brand, icons, slots).
Done when: no primitive imports from tfy; slots resolve to local components; brand logo/icon replaceable via theme.
Phase 3 — Rebuild feature atoms / molecules
- Replace each tfy agent-chat wrapper with local Tailwind + primitives.
- Keep slot names stable where possible (
AssistantMessageBubble, …) so overrides still work after prop migration. - Layouts: remove
IconProvider; supportlayout={MyComponent}on the shell (built-ins unchanged).
Done when: rg tfy-web-components src is empty; custom layout component
renders inside providers.
Phase 4 — Markdown + OpenUI + highlighter + Monaco
- In-repo Markdown + OpenUI fences.
- Port
react-syntax-highlighter-based fenced-code rendering out of tfy'sMarkdowninto a localSyntaxHighlighteratom (add direct deps:react-syntax-highlighter,@types/react-syntax-highlighter). - Port
MonacoEditorCore+SimpleCodeEditor(copy/download/expand/ fullscreen/line-numbers) into localMonacoEditorCore+CodeEditoratoms for rich code / artifact surfaces (lazy-load where possible; add direct depmonaco-editor). - Wire
theme.classNames(markdown,syntaxHighlighter,openui,monaco) + stableaui-*hooks for host CSS. - Fix tests that mock
tfy-markdown-openui.
Done when: OpenUI / code fences / Monaco render without tfy; classNames overrides apply in the example app.
Phase 5 — Presets + polish
- Ship
claude/chatgpt/gemini/trueforgepacks. - Example app: theme switcher + custom layout demo + content classNames demo.
- Drop
tfy-web-componentsfromdependencies/peerDependencies. - CHANGELOG + migration guide (slot props, styles, brand, layout, classNames).
Done when: presets + custom layout + content classNames demos work; package no longer depends on tfy.
Migration notes (for consumers)
- Remove
@import "tfy-web-components/theme.css". - Styles auto-inject from
ThemeProvider(optional@import "@truefoundry/trueforge-ui/styles.css"for SSR). Tokens are scoped to.aui-theme-root— the host document is not rethemed. - Revisit
overridesforButton/IconButton/ bubbles (new props). - Prefer
theme={{ preset, tokens, brand, icons, className, classNames }}over hacking a third-party theme. - Replace product marks with
theme.brand.iconand optional widelogo(URLs or per-mode sources), or override theBrandLogoslot for component marks. - Pass
layout={MyLayout}to own chrome; composeThread/ThreadListContainer/ etc. - Style content engines via
theme.classNamesor.aui-markdown/.aui-syntax-highlighter/.aui-openui/.aui-monaco.
Non-goals (v1)
- Pixel-perfect Claude / ChatGPT / Gemini clones
- Dual-running tfy + shadcn
- Moving structural atom overrides into
theme(those stay inoverrides; full chrome useslayoutinstead) - Runtime / Server abstraction work (see
docs/server.md)
PR sequence
- Tokens + owned ThemeProvider (still on tfy components if needed mid-migration)
- Primitives + IconRegistry + slot API break
- Feature atoms migration (can split by domain: chrome → tools → messages)
- Custom
layoutcomponent support - Markdown / OpenUI / syntax-highlighter / Monaco +
theme.classNames - Presets + remove tfy dep + example + docs
Success criteria
rg tfy-web-components src→ empty- Four presets + custom
tokens/brand/icons/className/classNamesdemo in example - Host can pass
layout={MyLayout}built fromThread+ thread list exports - Host can override classes on Markdown, syntax-highlighter, OpenUI, and Monaco
via
theme.classNamesand/or stableaui-*CSS hooks - Host can fully rebrand (colors, fonts, logo image, action icons) without slot
overrides; component-valued marks use the
BrandLogoslot - Host can still replace any component via
overrideswhen needed - Light/dark controlled + uncontrolled both work
- Slot override of
Buttonworks with new API - OpenUI fenced blocks still render
- No hard-coded TrueFoundry logo/mark outside default
theme.brandassets