@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental 1.33.0 → 1.33.2

package/README.md

@@ -0,0 +1,211 @@
+# Agentforce Conversation Client (React)
+
+React component for embedding the Agentforce Conversation Client — the Salesforce agent chat UI — into a web application. This is a wrapper around `@salesforce/agentforce-conversation-client` that handles authentication automatically and provides a declarative `<AgentforceConversationClient />` component.
+
+Use this when a user expects to add an agent, chat widget, chatbot, conversation client, Agentforce chat, employee agent, service agent, or any Salesforce agent to their React app.
+
+## How it works
+
+The component embeds the Agentforce chat experience using Lightning Out 2.0. Authentication is resolved automatically:
+
+- **Dev (localhost)**: fetches a `frontdoorUrl` from `/__lo/frontdoor`
+- **Prod (hosted in org)**: uses `window.location.origin` as `salesforceOrigin`
+
+## Step 1: Install dependencies
+
+```bash
+npm install @salesforce/agentforce-conversation-client
+npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
+```
+
+## Step 2: Embed in the app layout
+
+```tsx
+import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+
+export default function AppLayout() {
+  return (
+    <>
+      <Outlet />
+      <AgentforceConversationClient />
+    </>
+  );
+}
+```
+
+## Step 3: Configure (optional)
+
+### Props
+
+| Prop                     | Type                     | Required | Description                                                                                            |
+| ------------------------ | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
+| `agentforceClientConfig` | `AgentforceClientConfig` | No       | Configuration object passed through to the embed client (agent ID, rendering mode, style tokens, etc.) |
+| `salesforceOrigin`       | `string`                 | No       | Salesforce org origin URL. Resolved automatically if not provided.                                     |
+| `frontdoorUrl`           | `string`                 | No       | Frontdoor URL for authentication. Resolved automatically in dev if not provided.                       |
+
+### Rendering Modes
+
+#### Floating (default)
+
+A persistent chat widget overlay pinned to the bottom-right corner. No extra config needed.
+
+```tsx
+<AgentforceConversationClient />
+```
+
+#### Inline
+
+The chat renders within the page layout at a specific size.
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    renderingConfig: { mode: "inline", width: 420, height: 600 },
+  }}
+/>
+```
+
+### Agent Selection
+
+Pass `agentId` to load a specific agent (e.g. travel agent, HR agent). If not provided, the org's default agent is used.
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    agentId: "0Xx000000000000",
+  }}
+/>
+```
+
+### Theming with `styleTokens`
+
+Use `agentforceClientConfig.styleTokens` to theme the Agentforce Conversation Client. Only override the tokens you need.
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    styleTokens: {
+      headerBlockBackground: "#0176d3",
+      headerBlockTextColor: "#ffffff",
+      messageBlockInboundBackgroundColor: "#0176d3",
+    },
+  }}
+/>
+```
+
+#### Available Style Tokens
+
+##### Agentforce Header
+
+| Token name                    | UI area themed           |
+| ----------------------------- | ------------------------ |
+| `headerBlockBackground`       | Header background        |
+| `headerBlockBorderColor`      | Header border            |
+| `headerBlockFontFamily`       | Header font family       |
+| `headerBlockTextColor`        | Header text color        |
+| `headerBlockHoverBackground`  | Header hover background  |
+| `headerBlockActiveBackground` | Header active background |
+| `headerBlockFocusBorder`      | Header focus border      |
+
+##### Agentforce Messages
+
+| Token name                       | UI area themed                     |
+| -------------------------------- | ---------------------------------- |
+| `messageBlockBodyPaddingBottom`  | Message block body bottom padding  |
+| `messageBlockTextPadding`        | Message block text padding         |
+| `messageBlockPaddingContainer`   | Message block container padding    |
+| `messageBlockContainerMarginTop` | Message block container top margin |
+| `messageBlockPadding`            | Message block padding              |
+| `messageBlockBorderRadius`       | Message block border radius        |
+| `messageBlockFontSize`           | Message block font size            |
+| `messageBlockLineHeight`         | Message block line height          |
+| `messageBlockBackgroundColor`    | Message block background (base)    |
+| `messageBlockBodyWidth`          | Message block body width           |
+
+##### Inbound message (customer to agent)
+
+| Token name                                | UI area themed                   |
+| ----------------------------------------- | -------------------------------- |
+| `messageBlockInboundHoverBackgroundColor` | Inbound message hover background |
+| `messageBlockInboundBackgroundColor`      | Inbound message background       |
+| `messageBlockInboundTextColor`            | Inbound message text color       |
+| `messageBlockInboundWidth`                | Inbound message width            |
+| `messageBlockInboundTextAlign`            | Inbound message text alignment   |
+
+##### Outbound message (agent to customer)
+
+| Token name                            | UI area themed                  |
+| ------------------------------------- | ------------------------------- |
+| `messageBlockOutboundBackgroundColor` | Outbound message background     |
+| `messageBlockOutboundTextColor`       | Outbound message text color     |
+| `messageBlockOutboundWidth`           | Outbound message width          |
+| `messageBlockOutboundMarginLeft`      | Outbound message left margin    |
+| `messageBlockOutboundTextAlign`       | Outbound message text alignment |
+
+##### Agentforce Input
+
+| Token name                               | UI area themed                                 |
+| ---------------------------------------- | ---------------------------------------------- |
+| `messageInputPadding`                    | Message input container padding                |
+| `messageInputBorderRadius`               | Message input border radius                    |
+| `messageInputFooterBorderColor`          | Message input footer border color              |
+| `messageInputFooterBorderFocusColor`     | Message input footer focus border color        |
+| `messageInputBorderTransitionDuration`   | Message input border transition duration       |
+| `messageInputBorderTransitionEasing`     | Message input border transition easing         |
+| `messageInputTextColor`                  | Message input text color                       |
+| `messageInputTextBackgroundColor`        | Message input text background color            |
+| `messageInputFooterPlaceholderText`      | Message input placeholder text color           |
+| `messageInputErrorTextColor`             | Message input error text color                 |
+| `messageInputFontSize`                   | Message input font size                        |
+| `messageInputFontWeight`                 | Message input font weight                      |
+| `messageInputPlaceholderFontWeight`      | Placeholder font weight                        |
+| `messageInputLineHeight`                 | Message input line height                      |
+| `messageInputMaxHeight`                  | Message input max height                       |
+| `messageInputTextPadding`                | Message input text padding                     |
+| `messageInputActionsWidth`               | Message input actions width                    |
+| `messageInputActionsPaddingRight`        | Message input actions right padding            |
+| `messageInputActionsGap`                 | Message input actions gap                      |
+| `messageInputActionsPadding`             | Message input actions padding                  |
+| `messageInputOverflowY`                  | Message input overflow Y                       |
+| `messageInputScrollbarWidth`             | Message input scrollbar width                  |
+| `messageInputScrollbarColor`             | Message input scrollbar color                  |
+| `messageInputTextareaMaxHeight`          | Message input textarea max height              |
+| `messageInputTextareaWithImageMaxHeight` | Message input textarea max height (with image) |
+| `messageInputFilePreviewPadding`         | Message input file preview padding             |
+| `messageInputActionButtonSize`           | Message input action button size               |
+| `messageInputActionButtonRadius`         | Message input action button radius             |
+| `messageInputActionButtonFocusBorder`    | Message input action button focus border       |
+| `messageInputActionButtonHoverShadow`    | Message input action button hover shadow       |
+| `messageInputFooterSendButton`           | Message input send button color                |
+| `messageInputFooterSendButtonHoverColor` | Message input send button hover color          |
+| `messageInputSendButtonDisabledColor`    | Message input send button disabled color       |
+
+### Prerequisites
+
+- **One of `salesforceOrigin` or `frontdoorUrl` is required** (resolved automatically by the component).
+- Use `salesforceOrigin` when your app is hosted inside a Salesforce org and already has an authenticated session.
+- Use `frontdoorUrl` when embedding the chat client outside Salesforce (e.g. localhost or an external app).
+- The org must allow `localhost:<PORT>` in **Trusted Domains for Inline Frames** (session settings) for local development.
+
+### Underlying SDK
+
+This component wraps `@salesforce/agentforce-conversation-client`. For lower-level usage (vanilla JS, non-React frameworks), see the [Agentforce Conversation Client SDK](https://www.npmjs.com/package/@salesforce/agentforce-conversation-client).
+
+---
+
+## Rules and Skills
+
+This package includes coding-agent rules and skills for automated workflows:
+
+- **Rule** (`rules/embedded-agent-rule.md`): Conventions for which component to use, authentication, rendering modes, and placement. Copy into `.cursor/rules/` (Cursor) or `.clinerules/` (Cline).
+- **Skill** (`skills/embedded-agent/`): Step-by-step workflow for embedding the agent — install, add component, configure mode/theming/agent. Copy into `.cursor/skills/` (Cursor) or `.cline/skills/` (Cline).
+
+---
+
+## Development
+
+```bash
+npm run build   # apply patches -> dist
+npm run dev     # run from dist
+npm run watch   # watch and re-apply
+```

package/dist/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.33.2](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.33.1...v1.33.2) (2026-02-17)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+## [1.33.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.33.0...v1.33.1) (2026-02-17)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 # [1.33.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.32.0...v1.33.0) (2026-02-17)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/webapplications/feature-react-agentforce-conversation-client/package-lock.json

@@ -8,7 +8,7 @@
       "name": "base-react-app",
       "version": "1.0.0",
       "dependencies": {
-        "@salesforce/agentforce-conversation-client": "^1.32.0",
+        "@salesforce/agentforce-conversation-client": "^1.33.1",
         "@salesforce/webapp-experimental": "*",
         "@tailwindcss/vite": "^4.1.17",
         "react": "^19.2.0",
@@ -1863,9 +1863,9 @@
       ]
     },
     "node_modules/@salesforce/agentforce-conversation-client": {
-      "version": "1.32.0",
-      "resolved": "https://registry.npmjs.org/@salesforce/agentforce-conversation-client/-/agentforce-conversation-client-1.32.0.tgz",
-      "integrity": "sha512-0aBjEjh7cgnP+Ktp6TprYJpizcyzSPrSc5QdwBgaDzYnCfoAahgEIljOp7UGka3UakdGW9aj3RmyNPo+KKEbNQ==",
+      "version": "1.33.1",
+      "resolved": "https://registry.npmjs.org/@salesforce/agentforce-conversation-client/-/agentforce-conversation-client-1.33.1.tgz",
+      "integrity": "sha512-Su/L1lqsGZwh1ellGXNgoZYr6K2cwR2/dw+N0j3dC1KFW/essABmwb6W4fE2pjCdd5eVup3jvIjKkI/i2YGphg==",
       "license": "SEE LICENSE IN LICENSE.txt",
       "dependencies": {
         "@lightning-out/application": "2.1.1-rc.2"

package/dist/force-app/main/default/webapplications/feature-react-agentforce-conversation-client/package.json

@@ -12,7 +12,7 @@
     "test": "vitest"
   },
   "dependencies": {
-    "@salesforce/agentforce-conversation-client": "^1.32.0",
+    "@salesforce/agentforce-conversation-client": "^1.33.1",
     "@salesforce/webapp-experimental": "*",
     "@tailwindcss/vite": "^4.1.17",
     "react": "^19.2.0",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.33.0",
+  "version": "1.33.2",
   "description": "Base SFDX project template",
   "private": true,
   "files": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental",
-  "version": "1.33.0",
+  "version": "1.33.2",
   "description": "Embedded Agentforce conversation client feature for web applications",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",
@@ -16,7 +16,9 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "rules",
+    "skills"
   ],
   "publishConfig": {
     "access": "public"
@@ -35,5 +37,5 @@
     "react-dom": "^19.2.1",
     "react-router": "^7.10.1"
   },
-  "gitHead": "6ee79f3d678fc5a42dcc24dec742c2ab129cea45"
+  "gitHead": "bb8bb09df420bd823e210e09cf45a4bd8a4c4922"
 }

package/rules/embedded-agent-rule.md

@@ -0,0 +1,32 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/components/**/*.ts"
+---
+
+# Agentforce Conversation Client (standards)
+
+When adding or editing the embedded Agentforce chat client in this project, follow these conventions.
+
+## Component and library
+
+- Use the shared **AgentforceConversationClient** React component from `feature-react-agentforce-conversation-client`. Do not call `embedAgentforceClient` directly in application code.
+- The project must have **@salesforce/agentforce-conversation-client** installed (`npm install @salesforce/agentforce-conversation-client`).
+
+## Authentication
+
+- The component resolves auth automatically: **localhost** fetches `frontdoorUrl` from `/__lo/frontdoor`; **production** uses `window.location.origin` as `salesforceOrigin`.
+- Do not hard-code `salesforceOrigin` or `frontdoorUrl` unless the consumer explicitly provides them as props.
+
+## Rendering mode
+
+- Pass `agentforceClientConfig.renderingConfig.mode` to select **floating** (default) or **inline**. Do not apply custom positioning CSS to override the built-in layout.
+- For inline mode, set `width` and `height` in `renderingConfig`. Do not override iframe dimensions with external CSS.
+
+## Agent selection
+
+- Use `agentforceClientConfig.agentId` to select a specific agent. Ask the user for the agent ID; if not provided, note that the org's default agent is used.
+
+## Placement
+
+- Render `<AgentforceConversationClient />` inside the existing app layout (e.g. alongside `<Outlet />`). Do not replace the entire page shell with the chat client.

package/skills/embedded-agent/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: embedded-agent
+description: Embed an Agentforce conversation client (chat UI) into a React web application. Use when the user wants to add an employee agent, a chat client, chatbot, chat widget, chat component, conversation client, or conversational interface to their React app. Also applies when the user asks to embed or integrate any Salesforce agent — including employee agent, travel agent, HR agent, service agent, or any custom-named agent — or mentions Agentforce, Agentforce widget, Agentforce chat, or agent chat.
+---
+
+# Embedded Agentforce chat (workflow)
+
+When the user wants an embedded Agentforce chat client in a React app, follow this workflow.
+
+## 1. Install the dependency
+
+```bash
+npm install @salesforce/agentforce-conversation-client
+```
+
+The dependency should be added to the project's `package.json` dependencies.
+
+## 2. Add the feature
+
+- Include `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental` in the app configuration.
+- This feature provides **AgentforceConversationClient**.
+
+## 3. Use the shared wrapper
+
+Use the `AgentforceConversationClient` React component. It resolves auth automatically:
+
+- **Dev (localhost)**: fetches `frontdoorUrl` from `/__lo/frontdoor`
+- **Prod (hosted in org)**: uses `salesforceOrigin` from `window.location.origin`
+
+## 4. Embed in the layout
+
+Render `<AgentforceConversationClient />` in the app layout so the chat client loads globally. Keep it alongside the existing layout (do not replace the page shell).
+
+```tsx
+import { Outlet } from "react-router";
+import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+
+export default function AppLayout() {
+  return (
+    <>
+      <Outlet />
+      <AgentforceConversationClient />
+    </>
+  );
+}
+```
+
+## 5. Configure the agent
+
+Pass options via the `agentforceClientConfig` prop:
+
+| Option                             | Purpose                                           |
+| ---------------------------------- | ------------------------------------------------- |
+| `renderingConfig.mode`             | `"floating"` (default) or `"inline"`              |
+| `renderingConfig.width` / `height` | Inline dimensions (number for px, string for CSS) |
+| `agentId`                          | Select a specific agent from the org              |
+| `styleTokens`                      | Theme colors and style overrides                  |
+
+See [embed-examples.md](docs/embed-examples.md) for complete examples of each mode.
+
+## 6. Validate prerequisites
+
+- The org must allow `localhost:<PORT>` in **Trusted Domains for Inline Frames** (session settings).
+
+## Quick reference: rendering modes
+
+### Floating (default)
+
+A persistent chat widget overlay pinned to the bottom-right corner. No extra config needed — floating is the default.
+
+```tsx
+<AgentforceConversationClient />
+```
+
+### Inline
+
+The chat renders within the page layout at a specific size.
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    renderingConfig: { mode: "inline", width: 420, height: 600 },
+  }}
+/>
+```
+
+### Theming
+
+Use `styleTokens` to customize the chat appearance.
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    styleTokens: {
+      headerBlockBackground: "#0176d3",
+      headerBlockTextColor: "#ffffff",
+      messageBlockInboundColor: "#0176d3",
+    },
+  }}
+/>
+```
+
+### Agent selection
+
+Pass `agentId` to load a specific agent (e.g. travel agent, HR agent).
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    agentId: "0Xx000000000000",
+  }}
+/>
+```

package/skills/embedded-agent/docs/embed-examples.md

@@ -0,0 +1,182 @@
+# Embed examples
+
+Detailed examples for configuring the Agentforce Conversation Client. All examples use the `AgentforceConversationClient` React component; the underlying `embedAgentforceClient` API accepts the same `agentforceClientConfig` shape.
+
+---
+
+## Floating mode (default)
+
+A floating chat widget appears in the bottom-right corner. It starts minimized and expands when the user clicks it. This is the default — no `renderingConfig` is required.
+
+### Minimal (no config)
+
+```tsx
+<AgentforceConversationClient />
+```
+
+### Explicit floating
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    renderingConfig: { mode: "floating" },
+  }}
+/>
+```
+
+### Floating with a specific agent and theme
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    renderingConfig: { mode: "floating" },
+    agentId: "0Xx000000000000",
+    styleTokens: {
+      headerBlockBackground: "#032D60",
+      headerBlockTextColor: "#ffffff",
+    },
+  }}
+/>
+```
+
+---
+
+## Inline mode
+
+The chat renders inside the parent container at a specific size. Use this when the chat should be part of the page layout rather than an overlay.
+
+### Fixed pixel dimensions
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    renderingConfig: { mode: "inline", width: 420, height: 600 },
+  }}
+/>
+```
+
+### CSS string dimensions
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    renderingConfig: { mode: "inline", width: "100%", height: "80vh" },
+  }}
+/>
+```
+
+### Inline filling a sidebar
+
+```tsx
+<div style={{ display: "flex", height: "100vh" }}>
+  <main style={{ flex: 1 }}>{/* App content */}</main>
+  <aside style={{ width: 400 }}>
+    <AgentforceConversationClient
+      agentforceClientConfig={{
+        renderingConfig: { mode: "inline", width: "100%", height: "100%" },
+      }}
+    />
+  </aside>
+</div>
+```
+
+---
+
+## Theming
+
+Use `styleTokens` to customize colors. Tokens are passed directly to the Agentforce client.
+
+### Brand-colored header
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    styleTokens: {
+      headerBlockBackground: "#0176d3",
+      headerBlockTextColor: "#ffffff",
+    },
+  }}
+/>
+```
+
+### Full theme example
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    styleTokens: {
+      headerBlockBackground: "#0176d3",
+      headerBlockTextColor: "#ffffff",
+      messageBlockInboundColor: "#0176d3",
+    },
+  }}
+/>
+```
+
+### Dark theme example
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    styleTokens: {
+      headerBlockBackground: "#1a1a2e",
+      headerBlockTextColor: "#e0e0e0",
+      messageBlockInboundColor: "#16213e",
+    },
+  }}
+/>
+```
+
+---
+
+## Agent selection
+
+Use `agentId` to load a specific agent from the org. If omitted, the org's default employee agent is used.
+
+### Specific agent by ID
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    agentId: "0Xx000000000000",
+  }}
+/>
+```
+
+### Agent with inline mode and theming
+
+```tsx
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    agentId: "0Xx000000000000",
+    renderingConfig: { mode: "inline", width: 400, height: 700 },
+    styleTokens: {
+      headerBlockBackground: "#0176d3",
+      headerBlockTextColor: "#ffffff",
+    },
+  }}
+/>
+```
+
+---
+
+## Using the low-level `embedAgentforceClient` API
+
+The React component wraps `embedAgentforceClient`. If you need the raw API (e.g. in a non-React context), the config shape is the same:
+
+```ts
+import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
+
+const { loApp, chatClientComponent } = embedAgentforceClient({
+  container: "#agentforce-container",
+  salesforceOrigin: "https://myorg.my.salesforce.com",
+  agentforceClientConfig: {
+    agentId: "0Xx000000000000",
+    renderingConfig: { mode: "floating" },
+    styleTokens: {
+      headerBlockBackground: "#0176d3",
+      headerBlockTextColor: "#ffffff",
+    },
+  },
+});
+```