@truefoundry/trueforge-ui 0.0.0 → 0.1.0-rc.0

package/CHANGELOG.md

@@ -0,0 +1,340 @@
+# Changelog
+
+## 0.1.0-rc.0
+
+### Minor Changes
+
+- b56c003: Initial 0.1.0-rc.1 prerelease of all public packages.
+
+### Patch Changes
+
+- Updated dependencies [b56c003]
+  - @truefoundry/trueforge-sdk@0.1.0-rc.0
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **`type: "trueforge"` built-in server** — `<TrueforgeUI server={{ type: 'trueforge', baseUrl?, token?, fetch? }} />`
+  resolves a full Harness `AgentUIServer` via
+  `@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter`
+  (`createTrueForgeAgentUIServer`), including chat, builder, and default settings
+  catalogs. Depends on `@truefoundry/trueforge-sdk` (workspace:* in-monorepo; external in the bundle).
+- **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
+
+- **Theme preset rename** — default preset id `truefoundry` → `trueforge`
+  (`ThemePreset`, `PRESETS`, `data-preset`, docs).
+- **Styles auto-inject** — `ThemeProvider` injects the SDK stylesheet at runtime.
+  Hosts no longer need `@import '@truefoundry/trueforge-ui/styles.css'` (export
+  kept for SSR). Semantic tokens and dark mode are scoped to `.aui-theme-root`
+  (no `html.dark` / `:root` retheme of the host page).
+- **Dependency** — `@truefoundry/assistant-ui-runtime` pinned to `0.1.13`.
+  `ModelSelectorEntry` now requires `id`, nested `provider: ProviderEntry`, and
+  `properties: ModelProperties` (replacing flat `provider` / `providerLogo` /
+  `reasoningEfforts`). Re-exports `ProviderEntry` and `ModelProperties`.
+
+### Fixed
+
+- **History row mutability** — prefer `custom.isMutable` from the session (runtime
+  stamp) over inferring from `agentName`. Orphaned named refs (deleted agent, no
+  `agentName`) open as immutable. `openHistorySession` allows `isMutable: false`
+  without an agent name.
+- **Edit-bound draft history switch** — do not reuse the mutable shell via
+  `switchToThread` when the shell still carries an Edit `agentName`/`agentId`
+  and the row is a different session. Remount through `openHistorySession` so
+  Update Agent chrome cannot overwrite the wrong library agent.
+
+### Breaking
+
+- **Server-port types owned by `@truefoundry/assistant-ui-runtime`** — this package no
+  longer defines `AgentChatServer` / `AgentBuilderServer` / catalog DTOs locally.
+  Host-facing types are re-exported from `@truefoundry/assistant-ui-runtime/server`
+  via `src/server/types.ts`. Prefer importing types from `@truefoundry/trueforge-ui`
+  (hosts should not need the runtime package for types). Requires runtime `0.1.13`.
+- **Removed public pagination helpers** — `PageResult`, `TokenPagination`,
+  `ListSessionsResponse`, `ListTurnsResponse`, `ListSessionEventsResponse`, and
+  opaque `SessionEvent` are gone from this package. Chat list APIs use runtime
+  `ListResult<T>` (`{ data, nextPageToken? }`).
+- **`AgentUIServer` / mounts follow the runtime contract** — composed port matches
+  runtime `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.
+  Hosts that inspected `mode.type` must switch to `mode.status` /
+  `mode.isMutable` (see `shellIsMutable`).
+- **Renamed `TrueFoundryAssistantUI` → `TrueforgeUI`** (props type
+  `TrueFoundryAssistantUIProps` → `TrueforgeUIProps`). Update imports and JSX.
+- **`TrueforgeUI` agent props** — replaced top-level `agentName` and
+  `defaultAgentSpec` with a single discriminated `agentConfig`. There is no
+  compat shim; hosts must update call sites.
+- **Icons use Lucide** (`lucide-react`) instead of Font Awesome. Default
+  registry keys are unchanged (`paperclip`, `xmark`, …); `theme.icons` values
+  are Lucide components, React nodes, render fns, or SVGR SVGs — not
+  `IconDefinition`. Drop `@fortawesome/*` if you only used them for this SDK.
+- **Removed `tfy-web-components`** dependency and peer. Primitives, icons,
+  theme, Markdown, and agent-chat molecules are owned by this SDK.
+- `theme` prop is now `ThemeConfig` (object), not `"light" | "dark"`. Mode
+  lives at `theme.mode`. Example: `theme={{ mode: "dark", preset: "claude" }}`.
+- `AtomSlots` and `SlotOverrides` are derived from `defaultSlots`; consumer
+  module augmentation of `AtomSlots` no longer adds override keys.
+- `theme.classNames.openui` accepts only `root` and `scope`; arbitrary extra
+  keys are no longer supported.
+- Complete `SemanticTokens` objects must include `success`,
+  `successForeground`, `warning`, and `warningForeground`.
+- `Button`, `IconButton`, dialogs, sheets, avatars, and other low-level
+  primitives are customized through tokens/CSS rather than slots. Compound
+  APIs (`Button.Primary`, `icon=` string props) are gone.
+- Import styles with only `@import "@truefoundry/trueforge-ui/styles.css"`
+  (no `tfy-web-components/theme.css`).
+- `layout` accepts a built-in string **or** a host `React.ComponentType`.
+- **`server` prop no longer accepts `{ type: "custom", server }`.** Pass a ready
+  `AgentUIServer` directly (`server={agentServer}`). Built-in configs
+  (`truefoundry` / `trueforge`) are unchanged and now accept an optional
+  `catalog`.
+
+### Added
+
+- **Named agent header title** — when an immutable (named) agent chat is open,
+  the thread header shows the agent name on the left (sidebar / drawer / dock /
+  widget layouts). Hidden for idle and draft/mutable chats.
+- **`AgentLibraryEntry.agentId?` / `agentSpec?`** — optional listing fields.
+  Hosts that only return `{ name }` keep working; `agentSpec` enables Edit.
+- **Agents Library Edit** — when `isComposerEnabled` and the row has
+  `agentSpec`, Edit binds a mutable session seeded from that spec
+  (`isMutable: true`). Try Agent remains immutable (`isMutable: false`).
+- **`selectLibraryAgent` / `shellIsMutable` / `libraryAgentId`** on shell
+  context. `selectAgent` / `openDraft` remain as thin wrappers.
+- **Reasoning-effort selector** beside the model picker in the draft composer.
+  Shown only when the selected `ModelSelection` declares `reasoningEfforts`;
+  the effort is coerced into the spec on model change or explicit pick.
+- **Skills catalog** — `getSkillCatalog` with an Available/Selected split;
+  registry skills (`catalogId`) return to Available on remove, GitHub imports
+  are deleted for good. New types: `RegistrySkill`, `GithubSkill`,
+  `DefinedSkill`, `SkillConfigBase`, `SkillCatalogEntry`,
+  `CreateSkillRequestBase`, `SelectRegistrySkillRequest`,
+  `ImportGithubSkillRequest`, `SkillCatalogServer.getSkillCatalog`.
+- **Sandbox catalog** — list/create/update/delete of connected sandboxes from a
+  catalog. New types: `SandboxConfig`, `SandboxCatalogEntry`, `SandboxBase`,
+  `CreateSandboxRequest`, `UpdateSandboxRequest`, `SandboxCatalogServer`.
+  `apiKey` is never stored in the catalog and is optional on update (blank keeps
+  the existing key).
+- `TrueforgeBuiltInServerConfig` exported for hosts that build the built-in
+  config separately.
+
+- **`agentConfig` shell modes** on `TrueforgeUI` /
+  `ShellModeProvider`:
+  - `SingleAgent` — locked named agent (`name` required)
+  - `AgentLibrary` — Agents Library only; idle empty state until pick; no New Chat
+  - `AgentComposer` — draft composer only (no library)
+  - `AgentLibraryWithComposer` — library + draft (default when omitted)
+- **Clear Chat** control in thread headers (sidebar / drawer / dock / widget).
+  Resets the current named thread or opens a fresh draft.
+- `ClearChatButton`, `SelectAgentEmptyState`, `AgentConfig`,
+  `DEFAULT_AGENT_CONFIG` exported from the main barrel.
+- Owned `ThemeProvider` with light / dark / system, CSS token injection,
+  `theme.brand`, `theme.icons`, `theme.classNames`, `theme.className`.
+- Semantic success/warning and assistant-bubble tokens, plus complete Markdown,
+  syntax-highlighter, OpenUI, and Monaco class-name hooks.
+- Presets: `truefoundry`, `claude`, `chatgpt`, `gemini`.
+- `BrandLogo` / `BrandIcon` / `useBrand`; `Icon` / `IconRegistry`.
+- Registry-backed robot brand fallback and overridable welcome/OAuth state
+  icons. The standalone OAuth callback now inherits the shell theme and slots.
+- In-repo Markdown (OpenUI fences + syntax-highlighter), `MonacoEditorCore`,
+  `CodeEditor`.
+- Public slots for agent-library/save/select controls, draft composer
+  selectors, code/content renderers, and file-download UI; nested SDK
+  composition now honors those overrides.
+- Example app: preset switcher + custom layout demo; `VITE_TFY_AGENT_MODE` to
+  try shell modes.
+
+### Migration
+
+#### Component rename
+
+```tsx
+// Before
+import { TrueFoundryAssistantUI } from '@truefoundry/trueforge-ui';
+<TrueFoundryAssistantUI server={server} layout="sidebar" />;
+
+// After
+import { TrueforgeUI } from '@truefoundry/trueforge-ui';
+<TrueforgeUI server={server} layout="sidebar" />;
+```
+
+#### `agentConfig` (host must update)
+
+| Before                                           | After                                                                                         |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `agentName="support-agent"`                      | `agentConfig={{ mode: "SingleAgent", name: "support-agent" }}`                                |
+| omit `agentName` (+ optional `defaultAgentSpec`) | omit `agentConfig`, or `agentConfig={{ mode: "AgentLibraryWithComposer", defaultAgentSpec }}` |
+| —                                                | `agentConfig={{ mode: "AgentLibrary" }}` — library only, pick agent to start                  |
+| —                                                | `agentConfig={{ mode: "AgentComposer", defaultAgentSpec }}` — draft only                      |
+
+```tsx
+// Before
+<TrueFoundryAssistantUI server={server} layout="sidebar" agentName="support-agent" />
+<TrueFoundryAssistantUI
+  server={server}
+  layout="sidebar"
+  defaultAgentSpec={{ model: { name: "openai-main/gpt-4.1" } }}
+/>
+
+// After
+<TrueforgeUI
+  server={server}
+  layout="sidebar"
+  agentConfig={{ mode: "SingleAgent", name: "support-agent" }}
+/>
+<TrueforgeUI
+  server={server}
+  layout="sidebar"
+  agentConfig={{
+    mode: "AgentLibraryWithComposer",
+    defaultAgentSpec: { model: { name: "openai-main/gpt-4.1" } },
+  }}
+/>
+```
+
+`ShellModeProvider` likewise takes `agentConfig` instead of `agentName` /
+`defaultAgentSpec`.
+
+#### Other Unreleased migrations
+
+1. Drop `@import "tfy-web-components/theme.css"` and the `tfy-web-components`
+   package.
+2. Replace `theme="dark"` with `theme={{ mode: "dark" }}`.
+3. Update Button/IconButton overrides to the new prop surface.
+4. Replace product marks via `theme.brand`; action icons via `theme.icons`
+   (Lucide / SVG — not Font Awesome `IconDefinition`).
+5. Optionally set `layout={MyLayout}` and style content via
+   `theme.classNames` or `.aui-markdown` / `.aui-syntax-highlighter` /
+   `.aui-openui` / `.aui-monaco`.
+6. Remove consumer `AtomSlots` module augmentations and use the documented
+   `SlotOverrides` keys.
+7. Replace custom `theme.classNames.openui` keys with `root`, `scope`, or host
+   CSS targeting `.aui-openui`.
+8. Add success/warning pairs to any complete custom `SemanticTokens` maps.
+
+## [0.1.0]
+
+### Breaking
+
+- Main entry no longer re-exports tfy design-system **values** (`Button`,
+  `IconButton`, `IconProvider`, `Modal`, `Dialog`, `Accordion*`, `Skeleton`,
+  `LightTooltip`, `registerIcons`, …). Import those from `tfy-web-components`.
+  Override **types** `ButtonProps` / `ButtonSize` / `IconButtonProps` remain
+  on `@truefoundry/trueforge-ui`.
+- Peer dependency ranges aligned with supported versions (`@truefoundry/assistant-ui-runtime` `^0.1.4`, `truefoundry-gateway-sdk` `^0.4.0-rc.1`, `tfy-web-components` `^0.0.31`).
+- tfy/MUI peer stack (`@mui/material`, `@emotion/*`, Font Awesome, `@openuidev/*`) moved from `dependencies` to `peerDependencies`; hosts must install them.
+- `MessageTimestamp` is presentational and requires `createdAt`.
+- `UserMessageActionBar` is presentational (copy/edit/retry props); runtime wiring lives in containers.
+- `MessageActionBar` accepts optional `createdAt` and passes it to `MessageTimestamp`.
+- Default stylesheet no longer loads Google Fonts from the CDN; override `--font-agent-ui` in host CSS if needed.
+- `prepare` script replaced with `prepublishOnly` (install no longer builds automatically).
+
+### Added
+
+- `TrueforgeUI` quick-start component with `layout`: `sidebar` | `drawer` |
+  `dock` | `widget` (slots outside the chat provider so toast overrides apply).
+- Curated re-exports: `useAui`, `useAuiState`, `AssistantState` from the main
+  barrel and `@truefoundry/trueforge-ui/assistant-ui`; `useTheme` from the main
+  barrel.
+- Optional `onThreadOpen` on `ThreadListContainer` for stack/drawer chrome.
+- npm package metadata: `repository`, `homepage`, `bugs`, `keywords`.
+- Drawer / widget Escape-to-close; drawer backdrop dismiss; widget `aria-modal`.
+- Drawer / widget focus management (`inert` on background, focus dialog, restore).
+- `docs/api.md` curated public API reference.
+- CI coverage floor + example app build.
+- Apache-2.0 `LICENSE`, `NOTICE`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`.
+- GitHub issue/PR templates and CI workflow.
+- `docs/` (architecture, customization, compatibility).
+- ESLint + Prettier.
+- Unit tests for tool-call parsing helpers and `computeAgentStepsSplit`.
+
+### Changed
+
+- Required peers are only `react` / `react-dom`. `@assistant-ui/core`
+  (`^0.2.22`), `@assistant-ui/react` (`^0.14.24`), and
+  `tfy-web-components@^0.0.32` moved to `dependencies` (still listed as optional
+  peers for hosts that install them directly for customization). Happy path:
+  `yarn add @truefoundry/trueforge-ui`. Yarn `resolutions` pin a single
+  `@assistant-ui/core` / `store` / `tap` copy to avoid duplicate AuiProvider.
+- `tfy-web-components` resolves from npm (`^0.0.32`) instead of a local
+  `file:` tarball.
+- MUI / Emotion / OpenUI / Monaco / extra Font Awesome packages come from
+  `tfy-web-components` (not peers of this SDK).
+- Font Awesome packages this SDK imports (`fontawesome-svg-core`,
+  `free-solid-svg-icons`) moved to `dependencies`.
+- `SlotOverrides` is `Partial<AtomSlots>` only (no `Record<string, unknown>`).
+- `TrueforgeUI` lazy-layout `Suspense` fallback is a pulse skeleton
+  instead of blank.
+- README reordered: quick start (prefer `client`) before advanced sections.
+
+### Removed
+
+- Unused `TokensProvider` / `useTokens` / `defaultTokens` public API (and
+  related token types). Theme via CSS variables from `styles.css` instead.
+- `examples/vite-chat` sample app.
+- Unused `classnames` dependency (provided by `tfy-web-components@^0.0.32`).
+- Direct design-system `devDependencies` duplicated from web-components
+  (`@mui/material`, `@emotion/*`, `@openuidev/*`, `monaco-editor`,
+  `@fortawesome/free-regular-svg-icons`, `@fortawesome/react-fontawesome`).
+- Standalone `@truefoundry/trueforge-ui/openui.css` export — OpenUI styles ship
+  inside `styles.css`.
+- Unused packages: `lodash-es`, `react-markdown`, `remark-gfm`, `class-variance-authority`.
+- Broken `pack:dev` script.
+
+### Fixed
+
+- Error toasts stack (up to 5), use compact theme sizing, and include a copy action.
+- Atom/container architecture: atoms no longer import `@assistant-ui/*`.
+- Error toasts truncate large gateway response bodies.
+
+### Note
+
+- `github-markdown-css` remains a **devDependency** required to compile
+  `dist/styles.css` (pulled in via tfy Markdown CSS).
+
+## [0.0.8] - 2026-07-24
+
+### Changed
+
+- Package and dependency updates prior to the 0.1.0 open-source readiness pass.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 TrueFoundry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,17 @@
+@truefoundry/trueforge-ui
+Copyright 2024-2026 TrueFoundry
+
+This product includes software developed at TrueFoundry.
+
+This distribution may include or depend on third-party software. Notable
+dependencies and their licenses include (non-exhaustive):
+
+- @assistant-ui/react / @assistant-ui/core — see their respective LICENSE files
+- @openuidev/react-ui and related OpenUI packages — see their LICENSE files
+- @truefoundry/assistant-ui-runtime — see its LICENSE
+- lucide-react — ISC / Lucide license
+- monaco-editor — see its LICENSE
+- react-markdown / remark-gfm / react-syntax-highlighter — see their respective LICENSE files
+
+Full license texts for installed packages are available in node_modules under
+each package's LICENSE (or equivalent) file.