@salesforce/webapp-template-app-react-template-b2x-experimental 1.80.0 → 1.80.1

package/dist/.a4drules/features/feature-react-agentforce-conversation-client-embedded-agent-rule.md

@@ -6,27 +6,13 @@ paths:
 
 # Agentforce Conversation Client (standards)
 
-When adding or editing the embedded Agentforce chat client in this project, follow these conventions.
+## DO NOT build a chat UI from scratch
 
-## Component and library
+When the user asks for a chat UI, chat widget, chatbot, agent, or conversational interface — **always use the existing `AgentforceConversationClient` component** from `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`. Never generate a custom chat implementation, third-party chat library, WebSocket/REST chat, or direct calls to `embedAgentforceClient`.
 
-- Use the shared **AgentforceConversationClient** React component from `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`. Do not call `embedAgentforceClient` directly in application code.
-- Install with `npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`. The underlying SDK (`@salesforce/agentforce-conversation-client`) is included automatically as a dependency.
+## Hard constraints
 
-## 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.
+- **`agentId` is required.** The component will not work without it. Always ask the user for their agent ID before generating code. Do not proceed without one.
+- **Use the React wrapper only.** Import `AgentforceConversationClient` from the package. Never call `embedAgentforceClient` directly.
+- **One instance per window.** Render in the app layout alongside `<Outlet />`, not on individual pages. The component is a singleton.
+- **No auth hard-coding.** The component resolves `salesforceOrigin` and `frontdoorUrl` automatically.

package/dist/.a4drules/skills/feature-react-agentforce-conversation-client-embedded-agent/SKILL.md

@@ -1,13 +1,45 @@
 ---
 name: feature-react-agentforce-conversation-client-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.
+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, or any custom-named agent — or mentions Agentforce, Agentforce widget, Agentforce chat, or agent chat. ALWAYS use this skill instead of building a chat UI from scratch. Do NOT generate custom chat components, use third-party chat libraries, or create WebSocket/REST chat implementations. Do NOT use for non-React contexts or Lightning Web Components without React.
 ---
 
 # Embedded Agentforce chat (workflow)
 
 When the user wants an embedded Agentforce chat client in a React app, follow this workflow.
 
-## 1. Install the package
+## DO NOT build a chat UI from scratch
+
+When the user asks for a chat UI, chat widget, chatbot, conversational interface, agent embed, or anything related to an embedded agent — **always use the `AgentforceConversationClient` component** from `@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental`.
+
+**Never do any of the following:**
+
+- Build a custom chat component from scratch (no custom message bubbles, input boxes, or chat layouts)
+- Use third-party chat libraries (e.g. `react-chat-widget`, `stream-chat`, `chatscope`, or similar)
+- Create WebSocket, polling, or REST-based chat implementations
+- Generate custom HTML/CSS chat UIs
+- Write a wrapper around `embedAgentforceClient` directly — always use the provided React component
+
+If the user asks for chat functionality that goes beyond what `AgentforceConversationClient` supports (e.g. custom message rendering, message history, typing indicators), explain that the embedded Agentforce client handles all of this internally and cannot be customized beyond the supported `agentforceClientConfig` options (`renderingConfig`, `styleTokens`, `agentId`).
+
+## CRITICAL: Agent ID is required
+
+The Agentforce Conversation Client **will not work** without an `agentId`. There is no default agent — the component renders nothing and silently fails if `agentId` is missing. **Always ask the user for their agent ID before writing any code.**
+
+> **Before proceeding:** Ask the user for their Salesforce agent ID (18-character record ID starting with `0Xx`). If they do not have one, direct them to **Setup → Agents** in their Salesforce org to find or create one. Do not generate code without an `agentId`.
+
+## 1. Collect the agent ID
+
+Ask the user:
+
+- "What is your Salesforce agent ID? (You can find it in Setup → Agents → select an agent → copy the ID from the URL. It's an 18-character ID starting with `0Xx`.)"
+
+If the user does not provide one:
+
+- Explain that the conversation client **requires** an agent ID and will not function without it.
+- Direct them to **Setup → Agents** in their org.
+- Do **not** proceed to generate the embed code until an agent ID is provided.
+
+## 2. Install the package
 
 ```bash
 npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
@@ -15,16 +47,16 @@ npm install @salesforce/webapp-template-feature-react-agentforce-conversation-cl
 
 This single install also brings in `@salesforce/agentforce-conversation-client` (the underlying SDK) automatically.
 
-## 2. Use the shared wrapper
+## 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`
 
-## 3. Embed in the layout
+## 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).
+Render `<AgentforceConversationClient />` in the app layout so the chat client loads globally. Keep it alongside the existing layout (do not replace the page shell). **Always pass `agentId`.**
 
 ```tsx
 import { Outlet } from "react-router";
@@ -34,37 +66,51 @@ export default function AppLayout() {
   return (
     <>
       <Outlet />
-      <AgentforceConversationClient />
+      <AgentforceConversationClient
+        agentforceClientConfig={{
+          agentId: "0Xx000000000000AAA",
+        }}
+      />
     </>
   );
 }
 ```
 
-## 4. Configure the agent
+Replace `"0Xx000000000000AAA"` with the agent ID provided by the user.
 
-Pass options via the `agentforceClientConfig` prop:
+## 5. Configure rendering and theming (optional)
 
-| 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                  |
+Pass additional options via the `agentforceClientConfig` prop:
+
+| Option                             | Purpose                                                    | Required |
+| ---------------------------------- | ---------------------------------------------------------- | -------- |
+| `agentId`                          | The agent to load — **required, will not work without it** | **Yes**  |
+| `renderingConfig.mode`             | `"floating"` (default) or `"inline"`                       | No       |
+| `renderingConfig.width` / `height` | Inline dimensions (number for px, string for CSS)          | No       |
+| `styleTokens`                      | Theme colors and style overrides                           | No       |
 
 See [embed-examples.md](docs/embed-examples.md) for complete examples of each mode.
 
-## 5. Validate prerequisites
+## 6. Validate prerequisites
+
+Before the conversation client will work, the user must verify all of the following in their Salesforce org:
 
-- The org must allow `localhost:<PORT>` in **Trusted Domains for Inline Frames** (session settings).
+1. **Agent is active:** The org must have the agent referenced by `agentId` in an **Active** state and deployed to the correct channel (**Setup → Agents**).
+2. **Trusted domains:** The org must allow `localhost:<PORT>` in **Trusted Domains for Inline Frames** (**Setup → Session Settings → Trusted Domains for Inline Frames**). Required for local development.
+3. **First-party cookies disabled:** **"Require first party use of Salesforce cookies"** must be **unchecked/disabled** in **Setup → My Domain**. If this setting is enabled, the embedded conversation client will fail to authenticate and will not load.
 
 ## Quick reference: rendering modes
 
-### Floating (default)
+### Floating (default rendering mode)
 
-A persistent chat widget overlay pinned to the bottom-right corner. No extra config needed — floating is the default.
+A persistent chat widget overlay pinned to the bottom-right corner. Floating is the default rendering mode — but `agentId` is still required.
 
 ```tsx
-<AgentforceConversationClient />
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
+  }}
+/>
 ```
 
 ### Inline
@@ -74,6 +120,7 @@ The chat renders within the page layout at a specific size.
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "inline", width: 420, height: 600 },
   }}
 />
@@ -86,6 +133,7 @@ Use `styleTokens` to customize the chat appearance.
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#0176d3",
       headerBlockTextColor: "#ffffff",
@@ -95,14 +143,6 @@ Use `styleTokens` to customize the chat appearance.
 />
 ```
 
-### Agent selection
-
-Pass `agentId` to load a specific agent (e.g. travel agent, HR agent).
+## Troubleshooting
 
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000",
-  }}
-/>
-```
+If the chat widget does not appear, fails to authenticate, or behaves unexpectedly, see [troubleshooting.md](docs/troubleshooting.md).

package/dist/.a4drules/skills/feature-react-agentforce-conversation-client-embedded-agent/docs/embed-examples.md

@@ -2,16 +2,22 @@
 
 Detailed examples for configuring the Agentforce Conversation Client. All examples use the `AgentforceConversationClient` React component; the underlying `embedAgentforceClient` API accepts the same `agentforceClientConfig` shape.
 
+> **Important:** Every example requires an `agentId`. The component will not render without one. There is no default agent. Replace `"0Xx000000000000AAA"` in every example with the user's actual agent ID.
+
 ---
 
-## Floating mode (default)
+## Floating mode (default rendering mode)
 
-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.
+A floating chat widget appears in the bottom-right corner. It starts minimized and expands when the user clicks it. Floating is the default rendering mode — no `renderingConfig` is needed — but `agentId` is always required.
 
-### Minimal (no config)
+### Minimal
 
 ```tsx
-<AgentforceConversationClient />
+<AgentforceConversationClient
+  agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
+  }}
+/>
 ```
 
 ### Explicit floating
@@ -19,18 +25,19 @@ A floating chat widget appears in the bottom-right corner. It starts minimized a
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "floating" },
   }}
 />
 ```
 
-### Floating with a specific agent and theme
+### Floating with theming
 
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "floating" },
-    agentId: "0Xx000000000000",
     styleTokens: {
       headerBlockBackground: "#032D60",
       headerBlockTextColor: "#ffffff",
@@ -50,6 +57,7 @@ The chat renders inside the parent container at a specific size. Use this when t
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "inline", width: 420, height: 600 },
   }}
 />
@@ -60,6 +68,7 @@ The chat renders inside the parent container at a specific size. Use this when t
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "inline", width: "100%", height: "80vh" },
   }}
 />
@@ -73,6 +82,7 @@ The chat renders inside the parent container at a specific size. Use this when t
   <aside style={{ width: 400 }}>
     <AgentforceConversationClient
       agentforceClientConfig={{
+        agentId: "0Xx000000000000AAA",
         renderingConfig: { mode: "inline", width: "100%", height: "100%" },
       }}
     />
@@ -91,6 +101,7 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#0176d3",
       headerBlockTextColor: "#ffffff",
@@ -104,6 +115,7 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#0176d3",
       headerBlockTextColor: "#ffffff",
@@ -118,6 +130,7 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 ```tsx
 <AgentforceConversationClient
   agentforceClientConfig={{
+    agentId: "0Xx000000000000AAA",
     styleTokens: {
       headerBlockBackground: "#1a1a2e",
       headerBlockTextColor: "#e0e0e0",
@@ -129,40 +142,37 @@ Use `styleTokens` to customize colors. Tokens are passed directly to the Agentfo
 
 ---
 
-## 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",
-  }}
-/>
-```
+## Full layout example
 
-### Agent with inline mode and theming
+Shows the recommended pattern: agent ID passed directly, single render in the app layout.
 
 ```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000",
-    renderingConfig: { mode: "inline", width: 400, height: 700 },
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-    },
-  }}
-/>
+import { Outlet } from "react-router";
+import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+
+export default function AppLayout() {
+  return (
+    <>
+      <Outlet />
+      <AgentforceConversationClient
+        agentforceClientConfig={{
+          agentId: "0Xx000000000000AAA",
+          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:
+The React component wraps `embedAgentforceClient`. If you need the raw API (e.g. in a non-React context), the config shape is the same — `agentId` is still required:
 
 ```ts
 import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
@@ -171,7 +181,7 @@ const { loApp, chatClientComponent } = embedAgentforceClient({
   container: "#agentforce-container",
   salesforceOrigin: "https://myorg.my.salesforce.com",
   agentforceClientConfig: {
-    agentId: "0Xx000000000000",
+    agentId: "0Xx000000000000AAA",
     renderingConfig: { mode: "floating" },
     styleTokens: {
       headerBlockBackground: "#0176d3",

package/dist/.a4drules/skills/feature-react-agentforce-conversation-client-embedded-agent/docs/troubleshooting.md

@@ -0,0 +1,51 @@
+# Troubleshooting
+
+Common issues when using the Agentforce Conversation Client.
+
+---
+
+### Chat widget does not appear
+
+**Cause:** Missing or invalid `agentId`. The component will not render anything without a valid agent ID.
+
+**Solution:**
+
+1. Verify `agentId` is passed in `agentforceClientConfig` — it is required
+2. Confirm the ID is correct (18-character Salesforce record ID, starts with `0Xx`)
+3. Check that the agent exists and is **Active** in **Setup → Agents**
+
+### Chat loads but shows "agent not available"
+
+**Cause:** The agent exists but is not deployed or is inactive.
+
+**Solution:**
+
+1. In **Setup → Agents**, ensure the agent status is **Active**
+2. Verify the agent is deployed to the correct channel
+
+### Authentication error on localhost
+
+**Cause:** `localhost:<PORT>` is not in the org's trusted domains for inline frames.
+
+**Solution:**
+
+1. Go to **Setup → Session Settings → Trusted Domains for Inline Frames**
+2. Add `localhost:<PORT>` (e.g. `localhost:3000`)
+3. Restart the dev server
+
+### Chat fails to authenticate / blank iframe
+
+**Cause:** "Require first party use of Salesforce cookies" is enabled in the org's session settings. This blocks the embedded client from establishing a session.
+
+**Solution:**
+
+1. Go to **Setup → Session Settings**
+2. Find **"Require first party use of Salesforce cookies"**
+3. **Uncheck / disable** this setting
+4. Save and reload the app
+
+### Multiple chat widgets appear
+
+**Cause:** `AgentforceConversationClient` is rendered in multiple places.
+
+**Solution:** Render it once in the app layout, not on individual pages. The component uses a singleton pattern — only one instance should exist per window.

package/dist/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.80.1](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.80.0...v1.80.1) (2026-03-09)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 # [1.80.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.79.2...v1.80.0) (2026-03-07)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/force-app/main/default/webapplications/appreacttemplateb2x/package.json

@@ -15,8 +15,8 @@
     "graphql:schema": "node scripts/get-graphql-schema.mjs"
   },
   "dependencies": {
-    "@salesforce/sdk-data": "^1.80.0",
-    "@salesforce/webapp-experimental": "^1.80.0",
+    "@salesforce/sdk-data": "^1.80.1",
+    "@salesforce/webapp-experimental": "^1.80.1",
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-form": "^1.28.4",
     "class-variance-authority": "^0.7.1",
@@ -40,7 +40,7 @@
     "@graphql-eslint/eslint-plugin": "^4.1.0",
     "@graphql-tools/utils": "^11.0.0",
     "@playwright/test": "^1.49.0",
-    "@salesforce/vite-plugin-webapp-experimental": "^1.80.0",
+    "@salesforce/vite-plugin-webapp-experimental": "^1.80.1",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
     "@testing-library/user-event": "^14.5.2",

package/dist/package.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-app-react-template-b2x-experimental",
-  "version": "1.80.0",
+  "version": "1.80.1",
   "description": "Base reference app template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",