The open-source agent harness - the runtime layer that turns an LLM into a working agent.
updated brand config spec (#174)
sajal-truefoundryde3d9c6f1ebf
diff --git a/docs/ui-sdk/guides/layouts-and-theme.mdx b/docs/ui-sdk/guides/layouts-and-theme.mdxindex fab0e6fa1..da436db30 100644--- a/docs/ui-sdk/guides/layouts-and-theme.mdx+++ b/docs/ui-sdk/guides/layouts-and-theme.mdx@@ -67,8 +67,8 @@ type ThemeConfig = {preset?: "truefoundry" | "claude" | "chatgpt" | "gemini"; // default "truefoundry"mode?: "light" | "dark" | "system";brand?: {- name?: string;- logo?: string | BrandLogo;+ name: string; // required when `brand` is set+ logo?: string | BrandLogoConfig;},...};@@ -122,13 +122,24 @@ Pass to set a theme to light, dark or system. User CANNOT update it. This is usetheme={{...brand: {- name: "TrueForge",- logo: {- "light": "/logo/light.svg",- "dark": "/logo/dark.svg",- "href": "https://trueforge.dev" //URL to redirect on logo click- },+ name: "TrueForge",+ logo: {+ light: "/logo/light.svg",+ dark: "/logo/dark.svg",+ href: "https://trueforge.dev", // URL to redirect on logo click+ },}}}/>+```++The source is picked from the resolved mode, so this follows the system theme when `mode` is+omitted. Set only one of `light` / `dark` and it is used for both modes; use `src` for a+mode-agnostic mark. `name` labels the image, and the link when `href` is set.++To render a component instead of an image — an inline SVG, an animated mark — override the+`BrandLogo` slot rather than passing a node through `theme`:++```tsx App.tsx+<TrueforgeUI ... overrides={{ BrandLogo: MyMark }} />```\ No newline at end of filediff --git a/docs/ui-sdk/reference/theme.mdx b/docs/ui-sdk/reference/theme.mdxindex c6770e9ee..fdcc4bfba 100644--- a/docs/ui-sdk/reference/theme.mdx+++ b/docs/ui-sdk/reference/theme.mdx@@ -9,8 +9,7 @@ description: "Theme provider, hooks, presets, brand, and slots."| --- | --- || `ThemeProvider` | Owns light/dark/system state and injects token CSS variables on a wrapper `div.aui-theme-root`. || `SlotsProvider` | Slot override registry. Must sit outside `TrueFoundryChatProvider`. |-| `BrandLogo` | Renders `theme.brand.logo`; falls back to a default mark plus brand name. Props: `{ className? }`. |-| `BrandIcon` | Renders `theme.brand.icon`, falling back to the bare default mark — no name. Props: `{ className? }`. |+| `BrandLogo` | The product mark: renders `theme.brand.logo` for the active mode as an image labelled with `theme.brand.name`, linked when the config sets `href`. Falls back to the default mark. Overridable slot. Props: `{ className? }`. || `Icon` | Renders a built-in icon by name, or your replacement when `theme.icons` maps that name. Props: `{ name: string \| readonly string[] } & IconProps`. An array resolves to its **last** element, accommodating Font Awesome-style `["far", "clone"]` tuples; it is not a fallback chain. An unresolved name renders nothing. |## Hooks@@ -20,6 +19,7 @@ description: "Theme provider, hooks, presets, brand, and slots."| `useTheme()` | `{ preset, mode, preference, isDark, setTheme }`. `setTheme` is a no-op when `theme.mode` is controlled. || `useThemeMode()` | Resolved `"light" \| "dark"`. Reads the mode published by `SlotsProvider`, so it returns `"light"` when no `SlotsProvider` is above it — even in dark mode. || `useBrand()` | The active `BrandConfig`. |+| `useBrandName()` | `theme.brand.name`, or `"TrueForge"` when unset. Safe outside a provider. || `useThemeIcons()` | The `IconMap` from `theme.icons`. || `useContentClassNames()` | `theme.classNames`; throws outside a provider. || `useOptionalContentClassNames()` | Same, but returns `{}` outside a provider instead of throwing — no null check needed. |@@ -35,7 +35,7 @@ description: "Theme provider, hooks, presets, brand, and slots."## Types-`ThemeConfig`, `ThemeMode`, `ThemePreset`, `SemanticTokens`, `BrandConfig`, `BrandImage`,+`ThemeConfig`, `ThemeMode`, `ThemePreset`, `SemanticTokens`, `BrandConfig`, `BrandLogoConfig`,`ContentClassNames`, `IconMap`, `ThemeIconProps`, `IconProps`, `LayoutProp`, `AtomSlots`,`SlotOverrides`.diff --git a/docs/ui-sdk/reference/trueforge-ui.mdx b/docs/ui-sdk/reference/trueforge-ui.mdxindex d03b03a6c..419f83c0c 100644--- a/docs/ui-sdk/reference/trueforge-ui.mdx+++ b/docs/ui-sdk/reference/trueforge-ui.mdx@@ -116,19 +116,36 @@ import { TrueforgeUI } from "@truefoundry/trueforge-ui";</Expandable></ParamField><ParamField path="brand" type="BrandConfig">+ Optional. Omit it to keep the default mark and the `"TrueForge"` name; setting it+ requires a `name`.+<Expandable title="BrandConfig">- <ParamField path="logo" type="BrandImage">- Falls back to the default mark plus the brand name.+ <ParamField path="name" type="string" required>+ Shown beside the mark, and used as the logo's accessible label.+ </ParamField>+ <ParamField path="logo" type="string | BrandLogoConfig">+ Image URL, or per-mode sources. Omit to pair your name with the default mark.+ </ParamField>+ </Expandable>++ <Expandable title="BrandLogoConfig">+ <ParamField path="light" type="string">+ Source used when the resolved mode is light.+ </ParamField>+ <ParamField path="dark" type="string">+ Source used when the resolved mode is dark.</ParamField>- <ParamField path="icon" type="BrandImage">- Falls back to the bare mark — no name.+ <ParamField path="src" type="string">+ Mode-agnostic source, used when neither `light` nor `dark` is set.</ParamField>- <ParamField path="name" type="string" default='"TrueFoundry"'>- Shown beside the default logo.+ <ParamField path="href" type="string">+ Wraps the logo in a same-tab link, labelled with `name`.</ParamField></Expandable>- `BrandImage` accepts `{ src, alt? }`, a React node, or a render function.+ A single configured mode is used for both modes, so `{ light }` alone never renders a+ missing image. To render a component rather than an image, override the `BrandLogo` slot+ through `overrides`.</ParamField><ParamField path="icons" type="IconMap">Replace registry icons by name. Values are Lucide components, React nodes, render@@ -194,7 +211,7 @@ Persisted sessions remain available through the thread list.server={{ type: "truefoundry", apiKey, controlPlaneURL }}layout="sidebar"agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "openai-main/gpt-4.1" } } }}- theme={{ preset: "claude", brand: { name: "Acme" } }}+ theme={{ preset: "claude", brand: { name: "Acme", logo: "/logo.svg" } }}overrides={{ ClearChatButton: MyClearButton }}className="h-full min-h-0"onError={(e) => reportError(e)}diff --git a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx b/docs/ui-sdk/setup-custom-ui/custom-theme.mdxindex 1c8acc125..82b29c314 100644--- a/docs/ui-sdk/setup-custom-ui/custom-theme.mdx+++ b/docs/ui-sdk/setup-custom-ui/custom-theme.mdx@@ -67,14 +67,15 @@ A few tokens are absent from the presets — `scrollbarThumb`, `assistantBubble`## Reading theme state```tsx-import { useTheme, useThemeMode, useBrand } from "@truefoundry/trueforge-ui";+import { useTheme, useThemeMode, useBrand, useBrandName } from "@truefoundry/trueforge-ui";const { preset, mode, preference, isDark, setTheme } = useTheme();const resolved = useThemeMode(); // "light" | "dark", defaults to "light" outside a providerconst brand = useBrand();+const brandName = useBrandName(); // brand.name, or "TrueForge"```-`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.+`BrandLogo` renders `theme.brand.logo`, resolved against the active mode and labelled with `theme.brand.name`. Omit `logo` — or `brand` entirely — and it falls back to the default mark; `brand` is optional, but setting it requires a `name`. Pair it with `useBrandName()` when you also want the name as text. It is an overridable slot — use `overrides` to render a component instead of an image.## Token namingdiff --git a/packages/frontend/src/AuthErrorScreen.tsx b/packages/frontend/src/AuthErrorScreen.tsxindex 8ed1f51d9..e559580d0 100644--- a/packages/frontend/src/AuthErrorScreen.tsx+++ b/packages/frontend/src/AuthErrorScreen.tsx@@ -1,4 +1,4 @@-import { BrandIcon } from '@truefoundry/trueforge-ui';+import { BrandLogo } from '@truefoundry/trueforge-ui';import { AUTH_LOGIN_HREF } from './authFetch';import './authScreens.css';@@ -8,7 +8,7 @@ export function AuthErrorScreen({ reason }: { reason: string }) {return (<main className="auth-screen"><div className="auth-screen-card">- <BrandIcon className="auth-screen-logo" />+ <BrandLogo className="auth-screen-logo" /><h1 className="auth-screen-title">Sign-in failed</h1><p className="auth-screen-message">{message}</p><a className="auth-screen-button" href={AUTH_LOGIN_HREF}>diff --git a/packages/frontend/src/GetStartedScreen.tsx b/packages/frontend/src/GetStartedScreen.tsxindex 3439b585a..b5d4ce10a 100644--- a/packages/frontend/src/GetStartedScreen.tsx+++ b/packages/frontend/src/GetStartedScreen.tsx@@ -1,4 +1,4 @@-import { BrandIcon } from '@truefoundry/trueforge-ui';+import { BrandLogo } from '@truefoundry/trueforge-ui';import { AUTH_LOGIN_HREF } from './authFetch';import './authScreens.css';@@ -10,7 +10,7 @@ export function GetStartedScreen() {return (<main className="auth-screen"><div className="auth-screen-card">- <BrandIcon className="auth-screen-logo" />+ <BrandLogo className="auth-screen-logo" /><h1 className="auth-screen-title">Welcome to TrueForge</h1><buttontype="button"diff --git a/packages/trueforge-ui-sdk/CHANGELOG.md b/packages/trueforge-ui-sdk/CHANGELOG.mdindex 4d02a69e8..eda612b8e 100644--- a/packages/trueforge-ui-sdk/CHANGELOG.md+++ b/packages/trueforge-ui-sdk/CHANGELOG.md@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added++- **Light/dark brand logo** — `theme.brand.logo` accepts a `BrandLogoConfig`+ (`{ src?, light?, dark?, href? }`). The source is picked from the resolved theme+ mode, falling back to the other mode and then `src`, so a single configured mode+ covers both and `{ light }` alone never renders a missing image. `href` wraps the+ logo in a same-tab link. A bare string (`logo: '/logo.svg'`) is shorthand for a+ mode-agnostic source. A config with no usable source falls back to the default+ mark rather than an empty `<img>`.+- **`BrandLogo` slot** — now in the slot table and resolved through `useSlot` by+ every layout, so `overrides={{ BrandLogo: MyMark }}` reaches the sidebar header,+ widget FAB, and welcome screen.+- **`useBrandName()`** — the configured brand name or the default, so layouts no+ longer inline the fallback string.+### Changed- **Styles auto-inject** — `ThemeProvider` injects the SDK stylesheet at runtime.@@ -40,6 +55,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0- **`AgentUIServer` / mounts follow the runtime contract** — composed port matchesruntime `AgentUIServerPort`; `SkillMount` / `McpServerMount` stay opaque `object`(hosts widen via generics). Implement `getCapabilities()` on every builder host.+- **One brand component** — removed the `BrandIcon` export; `BrandLogo` is the only+ product mark and renders the mark alone. Callers that also want the name as text+ pair it with `useBrandName()` (as the sidebar header does), rather than relying on+ a second component that hard-codes one arrangement. Replace `<BrandIcon />` with+ `<BrandLogo />`, and `overrides={{ BrandIcon }}` with `overrides={{ BrandLogo }}`.+- **`brand.name` is required** — `theme.brand` stays optional, but setting it now+ requires `name`, since it labels the logo and a logo with no name has no accessible+ name. `logo` remains optional, so `brand: { name: 'Acme' }` still pairs host text+ with the default mark. `useBrand()` returns `Partial<BrandConfig>`, since `brand`+ may be absent entirely.+- **`theme.brand` is images-only** — removed `brand.icon`; there is one logo source.+ Removed the `ReactNode` and render-function variants of the logo value (and with+ them the `BrandImage` type export), so `brand.logo` is now+ `string | BrandLogoConfig`. Component-valued marks move to the slot table:+ `overrides={{ BrandLogo: MyMark }}`, which is how every other atom is replaced.+ Also removed `alt` — the logo is labelled with `brand.name`, so there is one place+ to set the accessible name.+- **Default brand name is `"TrueForge"`** (was `"TrueFoundry"`), used by+ `BrandLogo`, the sidebar header, and `useBrandName()`.- **`ShellMode` shape** — replaced `type: 'idle' | 'named' | 'draft'` with`status: 'idle' | 'active'` plus `isMutable` on active bindings. Composer /Save Agent / welcome chrome key off `isMutable`, not draft|named.diff --git a/packages/trueforge-ui-sdk/README.md b/packages/trueforge-ui-sdk/README.mdindex 42de12ebe..7a4e8be39 100644--- a/packages/trueforge-ui-sdk/README.md+++ b/packages/trueforge-ui-sdk/README.md@@ -166,7 +166,7 @@ export default function App() {}}theme={{preset: 'claude',- brand: { name: 'Acme', icon: { src: '/logo.svg', alt: 'Acme' } },+ brand: { name: 'Acme', logo: '/logo.svg' },}}overrides={{/* slot overrides */}}className="h-full"@@ -234,7 +234,7 @@ See [docs/theming.md](./docs/theming.md) for presets, controlled vs uncontrolled## Brand / logo-**Base layouts** — pass `theme.brand` and the SDK positions name + icon in the default slots:+**Base layouts** — pass `theme.brand` and the SDK positions the mark + name in the default slots:```tsx<TrueforgeUI@@ -243,14 +243,38 @@ See [docs/theming.md](./docs/theming.md) for presets, controlled vs uncontrolledtheme={{brand: {name: 'Acme',- icon: { src: '/brand/icon.svg', alt: 'Acme' },- logo: { src: '/brand/logo.svg', alt: 'Acme' },+ logo: '/brand/logo.svg',},}}/>```-**Custom layouts** — import `BrandLogo` / `BrandIcon` and place them anywhere (see [Custom layouts](#custom-layouts)).+**Light / dark marks** — pass `light` / `dark` sources instead and the SDK picks the one matching+the resolved mode. `href` wraps the logo in a same-tab link:++```tsx+<TrueforgeUI+ server={server}+ layout="sidebar"+ theme={{+ brand: {+ name: 'Acme',+ logo: { light: '/brand/logo-light.svg', dark: '/brand/logo-dark.svg', href: '/' },+ },+ }}+/>+```++Set only one mode and it is used for both. `name` labels the image, so no `alt` is needed.++**Component marks** — `theme.brand` takes image URLs only. To render an inline SVG or a custom+component, override the `BrandLogo` slot, the same way you replace any other atom:++```tsx+<TrueforgeUI server={server} layout="sidebar" overrides={{ BrandLogo: MyMark }} />+```++**Custom layouts** — import `BrandLogo` and place it anywhere; pair it with `useBrandName()` when you also want the name as text (see [Custom layouts](#custom-layouts)).> _Screenshot: external brand mark rendered in the base layout header._@@ -322,15 +346,17 @@ The [example app](./example/) switches between these four modes.For full control, pass a React component as `layout`. The SDK still wires server, shell mode, slots, and runtime behind it.```tsx-import { Thread, ThreadListContainer, BrandIcon, useTheme } from '@truefoundry/trueforge-ui';+import { Thread, ThreadListContainer, BrandLogo, useBrandName, useTheme } from '@truefoundry/trueforge-ui';function Layout({ className }: { className?: string }) {const { mode, setTheme } = useTheme();+ const brandName = useBrandName();return (<div className={className} style={{ display: 'flex', height: '100%' }}><aside style={{ width: 256 }}>- <BrandIcon className="size-6" />+ <BrandLogo className="size-6" />+ <span>{brandName}</span><ThreadListContainer /></aside><main style={{ flex: 1, minWidth: 0 }}>@@ -348,7 +374,7 @@ function Layout({ className }: { className?: string }) {For deeper composition without `TrueforgeUI`, nest `SlotsProvider` outside `TrueFoundryChatProvider` — see [docs/customization.md](./docs/customization.md).-> _Screenshot: a custom layout assembled from_ `BrandIcon`_,_ `ThreadListContainer`_, and_ `Thread`_._+> _Screenshot: a custom layout assembled from_ `BrandLogo`_,_ `ThreadListContainer`_, and_ `Thread`_._---@@ -467,7 +493,7 @@ See [docs/server.md](./docs/server.md) for the full method list and BYO guidance| `TrueforgeUI` | Component | Root component — accepts all props above || `TrueforgeServerConfig` | Type | `server` prop: `truefoundry` / `trueforge` / `AgentUIServer` || `createTrueFoundryServer` | Function | Compose chat + builder into `AgentUIServer` |-| `Thread`, `ThreadListContainer`, `BrandLogo`, `BrandIcon` | Components | Layout primitives for custom layouts |+| `Thread`, `ThreadListContainer`, `BrandLogo` | Components | Layout primitives for custom layouts || Composer / message / tool atoms | Components | Overridable, themeable building blocks || `SlotsProvider`, `useSlot`, `useTheme` | API | Overrides + theme mode || `AgentUIServer`, `AgentChatServer`, `AgentBuilderServer` | Types | Resolved server contract |diff --git a/packages/trueforge-ui-sdk/docs/customization.md b/packages/trueforge-ui-sdk/docs/customization.mdindex af2f8fe58..c91503e10 100644--- a/packages/trueforge-ui-sdk/docs/customization.md+++ b/packages/trueforge-ui-sdk/docs/customization.md@@ -29,7 +29,7 @@ over hacking third-party CSS:preset: 'claude',mode: 'dark',tokens: { primary: '#e11d48' },- brand: { name: 'Acme', icon: MyMark },+ brand: { name: 'Acme', logo: '/brand/logo.svg' },icons: { send: MySendSvg },classNames: {markdown: 'prose max-w-none',diff --git a/packages/trueforge-ui-sdk/docs/server.md b/packages/trueforge-ui-sdk/docs/server.mdindex 768cbc9f8..2e7e21318 100644--- a/packages/trueforge-ui-sdk/docs/server.md+++ b/packages/trueforge-ui-sdk/docs/server.md@@ -802,7 +802,6 @@ export function App() {brand: {name: 'MyCo',logo: { src: '/myco-wordmark.svg' },- icon: { src: '/myco-mark.svg' },},}}/>diff --git a/packages/trueforge-ui-sdk/docs/theming.md b/packages/trueforge-ui-sdk/docs/theming.mdindex 0b11fc3bc..ba0683814 100644--- a/packages/trueforge-ui-sdk/docs/theming.md+++ b/packages/trueforge-ui-sdk/docs/theming.md@@ -16,7 +16,7 @@ the SDK. Layers (each independently overridable):| ------------------ | -------------------------------------------- | --------------------------------------------- || Preset | Baseline look | `theme.preset` || Tokens | Colors, radius, fonts, bubble colors | `theme.tokens` + CSS vars |-| Brand | Logo + brand mark / icon | `theme.brand` |+| Brand | Logo image + 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` |@@ -41,7 +41,7 @@ track (orthogonal to [`docs/server.md`](./server.md)).| 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 | Replacable via `theme.brand` (logo URL/node + brand icon URL/node/SVG) |+| Brand | Logo URL (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: `truefoundry` (default), `claude`, `chatgpt`, `gemini` || Custom styles | CSS tokens + `className`; host may also import CSS (documented). No “load CSS file” prop |@@ -84,12 +84,12 @@ props):### 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` (logo + brand icon) consumed by header, welcome, widget FAB, avatar fallbacks |+| 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.logo` consumed by header, welcome, widget FAB, avatar fallbacks |### Code surfaces (Monaco + syntax highlighter)@@ -156,30 +156,41 @@ type IconMap = Record<| React.FC<React.SVGProps<SVGSVGElement>>>;-type BrandImage =- | { src: string; alt?: string }- | React.ReactNode- | ((props: { className?: string }) => React.ReactNode);+/**+ * Logo sources. `light` / `dark` pick per resolved theme mode and fall back to+ * each other, then to `src`. `href` wraps the logo in a same-tab link labelled+ * with the brand name.+ */+type BrandLogoConfig = {+ src?: string;+ light?: string;+ dark?: string;+ href?: string;+};/*** Product branding — distinct from `icons` (UI chrome).- * Used anywhere a product mark appears today (header, welcome, widget FAB,+ * 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.+ *+ * `theme.brand` is optional; setting it requires a `name` (it labels the logo).+ * `logo` is optional — omit it to pair host text with the stock mark.*/type BrandConfig = {- /** Wordmark / wide logo (sidebar header, welcome). */- logo?: BrandImage;- /** Square brand mark / app icon (FAB, avatar fallback, compact chrome). */- icon?: BrandImage;- /** Optional display name next to logo. */- name?: string;+ /** Display name beside the mark, and the logo's accessible label. */+ name: string;+ /** Image URL, or per-mode sources. Omit to keep the default mark. */+ logo?: string | BrandLogoConfig;};type ThemeConfig = {preset?: ThemePreset; // default: "truefoundry"mode?: ThemeMode; // omit = uncontrolled (useTheme().setTheme)tokens?: Partial<SemanticTokens>;- brand?: BrandConfig; // logo + brand icon replacement+ brand?: BrandConfig; // logo image + display nameclassName?: string; // applied on .aui-root (or theme root)icons?: IconMap; // full/partial UI icon replace + SVG transforms/** Per-surface className hooks for content renderers */@@ -245,8 +256,7 @@ function MyLayout({ className }: { className?: string }) {tokens: { primary: '#…', fontFamily: '"My Font", system-ui' },brand: {name: 'Acme Agent',- logo: { src: '/acme-wordmark.svg', alt: 'Acme' },- icon: MyAcmeMark,+ logo: { light: '/acme-wordmark.svg', dark: '/acme-wordmark-dark.svg' },},className: 'my-chat',icons: { send: MySendSvg, paperclip: MyAttachSvg },@@ -299,15 +309,24 @@ as `children`.## Brand system-1. All product marks render through `useBrand()` / `<BrandLogo />` /- `<BrandIcon />` — never hard-coded TFY assets in layouts or atoms.-2. `BrandLogo` resolves `theme.brand.logo` first. Its default wordmark combines- the configured name with the resolved `BrandIcon`.-3. `BrandIcon` resolves `theme.brand.icon`, then `theme.icons.robot`, then the- registry's Lucide robot fallback.-4. `theme.brand.name` → accessible labels / text next to logo when provided.-5. Omitting `brand` keeps the default `TrueFoundry` name and robot mark; hosts- replace the logo and icon independently.+1. All product marks render through `<BrandLogo />` — one component, never+ hard-coded TFY assets in layouts or atoms. Layouts resolve it via `useSlot`, so+ a host override reaches every call site.+2. `BrandLogo` renders the mark only. Callers that also want the name as text pair+ it with `useBrandName()`, so each layout owns its own arrangement (the sidebar+ sets mark + name; the widget FAB and welcome screen show the mark alone). A+ second "wordmark" component would only re-encode one caller's arrangement.+3. `theme.brand` carries **image sources only** (URL or `{ src, light, dark, href }`).+ Component-valued marks go through the `BrandLogo` slot, so brand replacement+ uses the same mechanism as every other atom instead of a second node-shaped+ escape hatch in the theme config.+4. `theme.brand.name` → the accessible label for a configured logo (and its link,+ when `href` is set), plus whatever text a caller renders alongside.+5. Omitting `brand` keeps the default `TrueForge` name and robot mark.+6. `{ light, dark }` sources resolve against the provider's mode, so a host mark+ tracks light/dark without a custom component. A single configured mode 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@@ -321,7 +340,7 @@ as `children`.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+robot is also the final brand fallback, so `theme.brand.logo` still takesprecedence 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.@@ -341,7 +360,7 @@ compose path), for example:- `Thread` / `ThreadContainer`- `ThreadListContainer`- `Composer` pieces / slot-backed atoms as needed-- Brand helpers (`BrandLogo`, `BrandIcon`) and `useTheme`+- Brand helpers (`BrandLogo`, `useBrandName`) and `useTheme`The shell still wraps the custom layout with theme + slots + chat provider;only the chrome tree is replaced. Equivalent to skipping built-in layouts@@ -412,7 +431,7 @@ TrueforgeUI({ layout, theme, overrides, … })├─ merge theme.tokens / brand / icons / classNames / className├─ layout = built-in | <HostLayout />└─ defaultSlots → local shadcn primitives + feature atoms- ├─ BrandLogo / BrandIcon wherever product mark appears+ ├─ BrandLogo wherever the product mark appears└─ Markdown / OpenUI / syntax-highlighter / Monaco(classNames from theme)```@@ -434,11 +453,11 @@ TrueforgeUI({ layout, theme, overrides, … })3. Own `ThemeProvider` / `useTheme` (mode light/dark/system); wire`SlotsProvider` to it.4. Apply `theme.className` + CSS vars from `theme.tokens` / `preset` on root.-5. Introduce `BrandConfig` plumbing (`useBrand`, `<BrandLogo />`,- `<BrandIcon />`) even if defaults still point at TFY assets.+5. Introduce `BrandConfig` plumbing (`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` and swap `theme.brand.icon` / `logo`.+host can override `--primary` and swap `theme.brand.logo`.### Phase 2 — shadcn primitives + icon + brand registry@@ -500,8 +519,8 @@ no longer depends on tfy.- Prefer`theme={{ preset, tokens, brand, icons, className, classNames }}`over hacking a third-party theme.-- Replace product marks with `theme.brand.logo` / `theme.brand.icon` (URL,- React node, or SVG component).+- Replace product marks with `theme.brand.logo` (URL or per-mode sources), or+ override the `BrandLogo` slot for component marks.- Pass `layout={MyLayout}` to own chrome; compose `Thread` /`ThreadListContainer` / etc.- Style content engines via `theme.classNames` or `.aui-markdown` /@@ -532,8 +551,8 @@ no longer depends on tfy.- Host can pass `layout={MyLayout}` built from `Thread` + thread list exports- Host can override classes on Markdown, syntax-highlighter, OpenUI, and Monacovia `theme.classNames` and/or stable `aui-*` CSS hooks-- Host can fully rebrand (colors, fonts, logo, brand icon, action icons)- without slot overrides+- Host can fully rebrand (colors, fonts, logo image, action icons) without slot+ overrides; component-valued marks use the `BrandLogo` slot- Host can still replace any component via `overrides` when needed- Light/dark controlled + uncontrolled both work- Slot override of `Button` works with new APIdiff --git a/packages/trueforge-ui-sdk/example/src/App.tsx b/packages/trueforge-ui-sdk/example/src/App.tsxindex 0bf28749d..a18a8b3c6 100644--- a/packages/trueforge-ui-sdk/example/src/App.tsx+++ b/packages/trueforge-ui-sdk/example/src/App.tsx@@ -271,11 +271,10 @@ export default function App() {theme={{preset: 'claude',brand: {- icon: {+ logo: {src: 'https://media.licdn.com/dms/image/v2/C560BAQGQ9Tfeof4MbA/company-logo_200_200/company-logo_200_200/0/1644494262340/truefoundry_logo?e=2147483647&v=beta&t=Xm6c1LGNbVPD2Ehtj21Z5OcuSCGLhYwlJ763oEYb92M',- alt: 'TrueFoundry',},- name: 'TFY',+ name: 'TrueForge',},}}layout="sidebar"diff --git a/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx b/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsxindex 04dee15ed..dff6a20a5 100644--- a/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx+++ b/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx@@ -1,7 +1,7 @@import type { ReactNode } from 'react';import { Icon } from '../icons/Icon.js';-import { BrandIcon } from '../theme/brand.js';+import { useSlot } from '../theme/SlotsProvider.js';import { useOptionalThemePreset } from '../theme/ThemeProvider.js';import { cn } from './lib/cn.js';@@ -13,13 +13,14 @@ export type WelcomeScreenProps = {export function WelcomeScreen({ heading = 'How can I help you today?', icon, className }: WelcomeScreenProps) {const preset = useOptionalThemePreset();+ const BrandLogo = useSlot('BrandLogo');const resolvedIcon =icon !== undefined ? (icon) : preset === 'chatgpt' ? null : preset === 'claude' ? (<Icon name="welcome-sparkle" className="size-5 fill-current text-primary" />) : (- <BrandIcon className={'size-10'} />+ <BrandLogo className={'size-10'} />);return (diff --git a/packages/trueforge-ui-sdk/src/index.ts b/packages/trueforge-ui-sdk/src/index.tsindex a6ca71920..23fb5a41f 100644--- a/packages/trueforge-ui-sdk/src/index.ts+++ b/packages/trueforge-ui-sdk/src/index.ts@@ -2,7 +2,7 @@import './icons/registerAgentIcons.js';-export { BrandIcon, BrandLogo } from './theme/brand.js';+export { BrandLogo, useBrandName } from './theme/brand.js';export { defaultSlots } from './theme/defaultSlots.js';export { PRESETS, resolvePresetTokens } from './theme/presets/index.js';export type { PublicAtomSlots as AtomSlots, SlotOverrides } from './theme/publicSlots.js';@@ -17,7 +17,7 @@ export {} from './theme/ThemeProvider.js';export type {BrandConfig,- BrandImage,+ BrandLogoConfig,ContentClassNames,IconMap,LayoutProp,diff --git a/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsxindex 26eb31efb..f32b60c6c 100644--- a/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx+++ b/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx@@ -12,9 +12,8 @@ import { Thread } from '../containers/Thread.js';import { ThreadListContainer } from '../containers/ThreadListContainer.js';import { Icon } from '../icons/Icon.js';import { useOptionalShellMode } from '../server/ShellModeContext.js';-import { BrandIcon } from '../theme/brand.js';+import { useBrandName } from '../theme/brand.js';import { useSlot } from '../theme/SlotsProvider.js';-import { useBrand } from '../theme/ThemeProvider.js';const TruefoundrySettingsBuilder = lazy(() => import('../containers/SettingsBuilder/index.js'));@@ -24,7 +23,8 @@ let desktopCollapsed = false;export function SidebarLayout({ className }: { className?: string }) {const aui = useAui();const shell = useOptionalShellMode();- const brand = useBrand();+ const brandName = useBrandName();+ const BrandLogo = useSlot('BrandLogo');const AgentsLibraryButton = useSlot('AgentsLibraryButton');const ClearChatButton = useSlot('ClearChatButton');const SaveAgentButton = useSlot('SaveAgentButton');@@ -91,10 +91,8 @@ export function SidebarLayout({ className }: { className?: string }) {className={cn('flex shrink-0 items-center px-3 py-3', collapsed ? 'flex-col gap-3' : 'justify-between gap-2')}><div className={cn('flex min-w-0 items-center text-foreground', collapsed ? 'justify-center' : 'gap-2')}>- <BrandIcon className="size-6 shrink-0 object-contain" />- {!collapsed ? (- <span className="truncate text-lg font-semibold tracking-tight">{brand.name ?? 'TrueFoundry'}</span>- ) : null}+ <BrandLogo className="size-6 shrink-0 object-contain" />+ {!collapsed ? <span className="truncate text-lg font-semibold tracking-tight">{brandName}</span> : null}</div><buttontype="button"@@ -214,8 +212,8 @@ export function SidebarLayout({ className }: { className?: string }) {tabIndex={-1}><div className="flex shrink-0 items-center gap-2 border-b border-border px-3 py-3 text-foreground">- <BrandIcon className="size-6 shrink-0 object-contain" />- <span className="truncate text-lg font-semibold tracking-tight">{brand.name ?? 'TrueFoundry'}</span>+ <BrandLogo className="size-6 shrink-0 object-contain" />+ <span className="truncate text-lg font-semibold tracking-tight">{brandName}</span></div><ThreadListContainer onThreadOpen={() => setMobileNavOpen(false)} /></div>diff --git a/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsxindex 97e004888..5ae19d32d 100644--- a/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx+++ b/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx@@ -6,11 +6,12 @@ import { auiButtonClass } from '../atoms/lib/buttonClasses.js';import { cn } from '../atoms/lib/cn.js';import { CompactLayoutProvider } from '../atoms/lib/CompactLayoutContext.js';import { Icon } from '../icons/Icon.js';-import { BrandIcon } from '../theme/brand.js';+import { useSlot } from '../theme/SlotsProvider.js';import { StackChatPanel } from './StackChatPanel.js';/** FAB-anchored panel with the same list ↔ thread stack as `dock`. */export function WidgetLayout({ className }: { className?: string }) {+ const BrandLogo = useSlot('BrandLogo');const [open, setOpen] = useState(false);const fabRef = useRef<HTMLButtonElement>(null);const dialogRef = useRef<HTMLDivElement>(null);@@ -86,7 +87,7 @@ export function WidgetLayout({ className }: { className?: string }) {×</span>) : (- <BrandIcon className="size-6" />+ <BrandLogo className="size-6" />)}</button></div>diff --git a/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx b/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsxindex 758817c52..2e8e60bfd 100644--- a/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx+++ b/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx@@ -34,7 +34,8 @@ export type ThemeContextValue = {preference: ThemeMode;isDark: boolean;setTheme: (mode: ThemeMode) => void;- brand: BrandConfig;+ /** Partial: `theme.brand` is optional, so consumers fall back to SDK defaults. */+ brand: Partial<BrandConfig>;icons: IconMap;classNames: ContentClassNames;tokens: Partial<SemanticTokens>;@@ -174,7 +175,8 @@ export function useTheme(): Pick<ThemeContextValue, 'preset' | 'mode' | 'preferereturn { preset, mode, preference, isDark, setTheme };}-export function useBrand(): BrandConfig {+/** Configured branding. Fields are optional — `theme.brand` may be omitted entirely. */+export function useBrand(): Partial<BrandConfig> {return useThemeContext().brand;}diff --git a/packages/trueforge-ui-sdk/src/theme/brand.tsx b/packages/trueforge-ui-sdk/src/theme/brand.tsxindex 35f144a08..9fc815550 100644--- a/packages/trueforge-ui-sdk/src/theme/brand.tsx+++ b/packages/trueforge-ui-sdk/src/theme/brand.tsx@@ -1,47 +1,61 @@'use client';-import type { ReactNode } from 'react';-import { useContext } from 'react';-import { cn } from '../atoms/lib/cn.js';import { Icon } from '../icons/Icon.js';import { ThemeContext } from './ThemeProvider.js';-import type { BrandConfig, BrandImage } from './types.js';--function DefaultBrandIcon({ className }: { className?: string }) {- return <Icon name="robot" className={className} />;+import type { BrandLogoConfig } from './types.js';++const DEFAULT_BRAND_NAME = 'TrueForge';++/** Mode-matched source, falling back to the other mode then the mode-agnostic `src`. */+function resolveLogoSrc({+ logo,+ mode,+}: {+ logo: string | BrandLogoConfig;+ mode: 'light' | 'dark';+}): string | undefined {+ if (typeof logo === 'string') return logo;+ const preferred = mode === 'dark' ? logo.dark : logo.light;+ return preferred ?? logo.light ?? logo.dark ?? logo.src;}-function DefaultBrandLogo({ className, name }: { className?: string; name: string }) {- return (- <span className={cn('inline-flex items-center gap-2 font-semibold tracking-tight', className)}>- <BrandIcon className="size-5" />- <span>{name}</span>- </span>- );+/** Configured brand name, or the SDK default. Safe outside a `ThemeProvider`. */+export function useBrandName(): string {+ return useContext(ThemeContext)?.brand.name ?? DEFAULT_BRAND_NAME;}-function renderBrandImage(image: BrandImage | undefined, fallback: ReactNode, className?: string): ReactNode {- if (image == null) return fallback;- if (typeof image === 'function') return image({ className });- if (typeof image === 'object' && image !== null && 'src' in image) {- return <img src={image.src} alt={image.alt ?? ''} className={className} />;- }- return image;-}+/**+ * The product mark: `theme.brand.logo` resolved against the active theme mode,+ * labelled with the brand name, and linked when the config carries an `href`.+ * Falls back to the default mark when no logo is configured.+ *+ * Callers that also want the name as text render it themselves — the SDK layouts+ * pair this with `useBrandName()` so each one controls its own arrangement.+ */+export function BrandLogo({ className }: { className?: string }) {+ const theme = useContext(ThemeContext);+ const logo = theme?.brand.logo;+ const name = theme?.brand.name ?? DEFAULT_BRAND_NAME;-function useOptionalBrand(): BrandConfig {- return useContext(ThemeContext)?.brand ?? {};-}+ const src = logo == null ? undefined : resolveLogoSrc({ logo, mode: theme?.mode ?? 'light' });+ if (src == null) return <Icon name="robot" className={className} />;-export function BrandLogo({ className }: { className?: string }) {- const brand = useOptionalBrand();- const name = brand.name ?? 'TrueFoundry';- return <>{renderBrandImage(brand.logo, <DefaultBrandLogo className={className} name={name} />, className)}</>;+ // `name` is the accessible label: the image itself carries no text alternative.+ const image = <img src={src} alt={name} className={className} />;+ const href = typeof logo === 'string' ? undefined : logo?.href;+ if (href == null) return image;++ return (+ <a href={href} aria-label={name} className="inline-flex items-center">+ {image}+ </a>+ );}-export function BrandIcon({ className }: { className?: string }) {- const brand = useOptionalBrand();- return <>{renderBrandImage(brand.icon, <DefaultBrandIcon className={className} />, className)}</>;+declare module './SlotsProvider.js' {+ interface AtomSlots {+ BrandLogo: typeof BrandLogo;+ }}diff --git a/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts b/packages/trueforge-ui-sdk/src/theme/defaultSlots.tsindex f2071d4f5..0e212fbfd 100644--- a/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts+++ b/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts@@ -53,6 +53,7 @@ import { UserMessageActionBar } from '../atoms/UserMessageActionBar.js';import { UserMessageBubble } from '../atoms/UserMessageBubble.js';import { UserMessageEdit } from '../atoms/UserMessageEdit.js';import { WelcomeScreen } from '../atoms/WelcomeScreen.js';+import { BrandLogo } from './brand.js';import type { AtomSlots } from './SlotsProvider.js';// ponytail: primitives stay CSS/token-styled (not slots) — see docs/customization.md.@@ -68,6 +69,7 @@ export const defaultSlots = {Accordion,AccordionSummary,AccordionDetails,+ BrandLogo,ComposerShell,ComposerLeftSection,ComposerRightSection,diff --git a/packages/trueforge-ui-sdk/src/theme/types.ts b/packages/trueforge-ui-sdk/src/theme/types.tsindex e64f6a723..cfd4339f7 100644--- a/packages/trueforge-ui-sdk/src/theme/types.ts+++ b/packages/trueforge-ui-sdk/src/theme/types.ts@@ -55,12 +55,29 @@ export type IconEntry = IconComponent | ReactNode;export type IconMap = Record<string, IconEntry>;-export type BrandImage = { src: string; alt?: string } | ReactNode | ((props: { className?: string }) => ReactNode);+/**+ * Logo sources. `light` / `dark` pick per resolved theme mode and fall back to+ * each other, then to `src`. `href` wraps the logo in a same-tab link. The logo+ * is labelled with `name`; replace the mark itself through the slot table when+ * an image URL is not enough.+ */+export type BrandLogoConfig = {+ src?: string;+ light?: string;+ dark?: string;+ href?: string;+};+/**+ * Setting `brand` requires a `name`: it labels the logo, so a logo without one has+ * no accessible name. `logo` is optional — omit it to pair host text with the stock+ * mark.+ */export type BrandConfig = {- logo?: BrandImage;- icon?: BrandImage;- name?: string;+ /** Display name, and the logo's accessible label. */+ name: string;+ /** Image URL, or per-mode sources. Omit to keep the default mark. */+ logo?: string | BrandLogoConfig;};export type ContentClassNames = {diff --git a/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx b/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsxindex ef9d1feea..98358063b 100644--- a/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx+++ b/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx@@ -243,7 +243,7 @@ describe('StackChatPanel', () => {describe('SidebarLayout', () => {it('shows the app brand in the mobile sessions drawer', () => {render(- <SlotsProvider theme={{ brand: { name: 'Acme', icon: { src: '/acme.svg', alt: 'Acme logo' } } }}>+ <SlotsProvider theme={{ brand: { name: 'Acme', logo: { src: '/acme.svg' } } }}><RuntimeHarness messages={[]}><div className="h-96"><SidebarLayout />@@ -256,12 +256,12 @@ describe('SidebarLayout', () => {const drawer = screen.getByRole('dialog', { name: 'Sessions' });expect(within(drawer).getByText('Acme')).toBeInTheDocument();- expect(within(drawer).getByAltText('Acme logo')).toBeInTheDocument();+ expect(within(drawer).getByAltText('Acme')).toHaveAttribute('src', '/acme.svg');});it('shows the brand and toggles the desktop sidebar rail', () => {const { unmount } = render(- <SlotsProvider theme={{ brand: { name: 'Acme' } }}>+ <SlotsProvider theme={{ brand: { name: 'Acme', logo: '/acme.svg' } }}><RuntimeHarness messages={[]}><div className="h-96"><SidebarLayout />@@ -280,7 +280,7 @@ describe('SidebarLayout', () => {// New Chat / Agents remount ChatProvider via runtimeKey; collapse must survive.unmount();render(- <SlotsProvider theme={{ brand: { name: 'Acme' } }}>+ <SlotsProvider theme={{ brand: { name: 'Acme', logo: '/acme.svg' } }}><RuntimeHarness messages={[]}><div className="h-96"><SidebarLayout />diff --git a/packages/trueforge-ui-sdk/test/publicUiExports.test.ts b/packages/trueforge-ui-sdk/test/publicUiExports.test.tsindex f226003c7..51b6c67bd 100644--- a/packages/trueforge-ui-sdk/test/publicUiExports.test.ts+++ b/packages/trueforge-ui-sdk/test/publicUiExports.test.ts@@ -18,7 +18,6 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = ['AvatarFallback','AvatarImage','BottomSheet',- 'BrandIcon','BrandLogo','CenteredModal','ChatFileDownload',@@ -113,6 +112,7 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = ['useAui','useAuiState','useBrand',+ 'useBrandName','useCatalogServer','useComposerBusyState','useComposerPauseView',diff --git a/packages/trueforge-ui-sdk/test/theme/ThemeProvider.test.tsx b/packages/trueforge-ui-sdk/test/theme/ThemeProvider.test.tsxindex 067d5e16e..dad4f5f9d 100644--- a/packages/trueforge-ui-sdk/test/theme/ThemeProvider.test.tsx+++ b/packages/trueforge-ui-sdk/test/theme/ThemeProvider.test.tsx@@ -3,7 +3,7 @@ import { act, render, renderHook, screen } from '@testing-library/react';import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';import { WelcomeScreen } from '@/atoms/WelcomeScreen.js';-import { BrandIcon, BrandLogo } from '@/theme/brand.js';+import { BrandLogo } from '@/theme/brand.js';import { ThemeProvider, useBrand, useTheme } from '@/theme/ThemeProvider.js';function ModeProbe() {@@ -136,16 +136,15 @@ describe('ThemeProvider', () => {expect(removeEventListener).toHaveBeenCalledWith('change', expect.any(Function));});- it('exposes brand config and BrandLogo / BrandIcon', () => {+ it('exposes brand config and labels BrandLogo with the brand name', () => {render(- <ThemeProvider theme={{ brand: { name: 'Acme' } }}>+ <ThemeProvider theme={{ brand: { name: 'Acme', logo: '/acme.svg' } }}><BrandProbe />- <BrandLogo />- <BrandIcon className="size-4" />+ <BrandLogo className="size-4" /></ThemeProvider>,);expect(screen.getByTestId('brand-name')).toHaveTextContent('Acme');- expect(screen.getAllByText('Acme').length).toBeGreaterThanOrEqual(1);+ expect(screen.getByRole('img', { name: 'Acme' })).toHaveAttribute('src', '/acme.svg');});it('writes token CSS vars on the theme root', () => {diff --git a/packages/trueforge-ui-sdk/test/theme/brand.test.tsx b/packages/trueforge-ui-sdk/test/theme/brand.test.tsxindex 48f7c795c..cf9404835 100644--- a/packages/trueforge-ui-sdk/test/theme/brand.test.tsx+++ b/packages/trueforge-ui-sdk/test/theme/brand.test.tsx@@ -1,61 +1,140 @@import { render, screen } from '@testing-library/react';import { describe, expect, it } from 'vitest';-import { BrandIcon, BrandLogo } from '@/theme/brand.js';+import { WelcomeScreen } from '@/atoms/WelcomeScreen.js';+import { BrandLogo, useBrandName } from '@/theme/brand.js';+import { SlotsProvider } from '@/theme/SlotsProvider.js';import { ThemeProvider } from '@/theme/ThemeProvider.js';-describe('BrandIcon and BrandLogo', () => {- it('renders accessible default branding without a provider', () => {+function BrandNameProbe() {+ return <output data-testid="brand-name">{useBrandName()}</output>;+}++describe('BrandLogo', () => {+ it('renders the default mark without a provider', () => {+ const { container } = render(<BrandLogo className="host-logo" />);++ const icon = container.querySelector('svg[aria-hidden="true"]');+ expect(icon).toHaveClass('host-logo');+ });++ it('labels the configured logo with the brand name', () => {+ render(+ <ThemeProvider theme={{ brand: { name: 'Acme', logo: { src: '/acme-logo.svg' } } }}>+ <BrandLogo className="logo-image" />+ </ThemeProvider>,+ );++ const logo = screen.getByRole('img', { name: 'Acme' });+ expect(logo).toHaveAttribute('src', '/acme-logo.svg');+ expect(logo).toHaveClass('logo-image');+ });++ it('renders the default mark and name when brand is omitted', () => {+ const { container } = render(+ <ThemeProvider theme={{ preset: 'claude' }}>+ <BrandNameProbe />+ <BrandLogo className="host-logo" />+ </ThemeProvider>,+ );++ expect(container.querySelector('img')).toBeNull();+ expect(container.querySelector('svg[aria-hidden="true"]')).toHaveClass('host-logo');+ expect(screen.getByTestId('brand-name')).toHaveTextContent('TrueForge');+ });++ it('pairs a host name with the default mark when logo is omitted', () => {const { container } = render(- <>+ <ThemeProvider theme={{ brand: { name: 'Acme' } }}>+ <BrandNameProbe /><BrandLogo className="host-logo" />- <BrandIcon className="host-icon" />- </>,+ </ThemeProvider>,);- expect(screen.getByText('TrueFoundry').parentElement).toHaveClass('host-logo');- const icons = container.querySelectorAll('svg[aria-hidden="true"]');- expect(icons).toHaveLength(2);- expect(icons[1]).toHaveClass('host-icon');+ expect(container.querySelector('img')).toBeNull();+ expect(container.querySelector('svg[aria-hidden="true"]')).toHaveClass('host-logo');+ expect(screen.getByTestId('brand-name')).toHaveTextContent('Acme');});- it('renders configured image descriptors with alt text and classes', () => {+ it('treats a bare string as an image source', () => {render(- <ThemeProvider- theme={{- brand: {- logo: { src: '/acme-logo.svg', alt: 'Acme logo' },- icon: { src: '/acme-icon.svg', alt: 'Acme icon' },- },- }}- >+ <ThemeProvider theme={{ brand: { logo: '/acme-logo.svg', name: 'Acme' } }}><BrandLogo className="logo-image" />- <BrandIcon className="icon-image" /></ThemeProvider>,);- expect(screen.getByRole('img', { name: 'Acme logo' })).toHaveAttribute('src', '/acme-logo.svg');- expect(screen.getByRole('img', { name: 'Acme logo' })).toHaveClass('logo-image');- expect(screen.getByRole('img', { name: 'Acme icon' })).toHaveAttribute('src', '/acme-icon.svg');- expect(screen.getByRole('img', { name: 'Acme icon' })).toHaveClass('icon-image');+ const img = screen.getByRole('img', { name: 'Acme' });+ expect(img).toHaveAttribute('src', '/acme-logo.svg');+ expect(img).toHaveClass('logo-image');+ });++ it('picks the light source in light mode and the dark source in dark mode', () => {+ const logo = { light: '/logo/light.svg', dark: '/logo/dark.svg' };++ const { rerender } = render(+ <ThemeProvider theme={{ mode: 'light', brand: { name: 'Acme', logo } }}>+ <BrandLogo />+ </ThemeProvider>,+ );+ expect(screen.getByRole('img', { name: 'Acme' })).toHaveAttribute('src', '/logo/light.svg');++ rerender(+ <ThemeProvider theme={{ mode: 'dark', brand: { name: 'Acme', logo } }}>+ <BrandLogo />+ </ThemeProvider>,+ );+ expect(screen.getByRole('img', { name: 'Acme' })).toHaveAttribute('src', '/logo/dark.svg');+ });++ it('falls back to the other mode when only one source is configured', () => {+ render(+ <ThemeProvider theme={{ mode: 'dark', brand: { name: 'Acme', logo: { light: '/logo/light.svg' } } }}>+ <BrandLogo />+ </ThemeProvider>,+ );++ expect(screen.getByRole('img', { name: 'Acme' })).toHaveAttribute('src', '/logo/light.svg');});- it('supports render callbacks and passes through the requested class', () => {+ it('wraps the logo in a same-tab link when href is set', () => {render(<ThemeProvider- theme={{- brand: {- logo: ({ className }) => <span className={className}>Callback logo</span>,- icon: ({ className }) => <span className={className}>Callback icon</span>,- },- }}+ theme={{ brand: { name: 'Acme', logo: { light: '/logo/light.svg', href: 'https://trueforge.dev' } } }}>- <BrandLogo className="custom-logo" />- <BrandIcon className="custom-icon" />+ <BrandLogo />+ </ThemeProvider>,+ );++ const link = screen.getByRole('link', { name: 'Acme' });+ expect(link).toHaveAttribute('href', 'https://trueforge.dev');+ expect(link).not.toHaveAttribute('target');+ expect(link.querySelector('img')).toHaveAttribute('src', '/logo/light.svg');+ });++ it('lets a slot override replace the mark with a component', () => {+ function CustomMark({ className }: { className?: string }) {+ return <span className={className}>custom mark</span>;+ }++ render(+ <SlotsProvider overrides={{ BrandLogo: CustomMark }} theme={{ brand: { name: 'Acme', logo: '/logo.svg' } }}>+ <WelcomeScreen />+ </SlotsProvider>,+ );++ expect(screen.getByText('custom mark')).toBeInTheDocument();+ expect(screen.queryByRole('img', { name: 'Acme' })).toBeNull();+ });++ it('falls back to the default mark when a logo config resolves to no source', () => {+ const { container } = render(+ <ThemeProvider theme={{ brand: { name: 'Acme', logo: { href: '/' } } }}>+ <BrandLogo className="host-logo" /></ThemeProvider>,);- expect(screen.getByText('Callback logo')).toHaveClass('custom-logo');- expect(screen.getByText('Callback icon')).toHaveClass('custom-icon');+ expect(container.querySelector('img')).toBeNull();+ expect(container.querySelector('a')).toBeNull();+ expect(container.querySelector('svg[aria-hidden="true"]')).toHaveClass('host-logo');});});