@salesforce/webapp-template-feature-react-authentication-experimental 1.103.4 → 1.103.6

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

@@ -1,62 +1,29 @@
 ---
 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, 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.
+description: Embed an Agentforce conversation client (chat UI) into a React web application using the AgentforceConversationClient component. Use when the user wants to add or integrate a chat widget, chatbot, conversation client, agent chat, or conversational interface in a React app, or when they mention Agentforce chat, Agentforce widget, employee agent, travel agent, HR agent, or embedding a Salesforce agent. ALWAYS use this skill instead of building a chat UI from scratch. NEVER generate custom chat components, use third-party chat libraries, or implement chat with WebSockets or REST APIs. Do NOT use for Lightning Web Components (LWC), non-React frameworks.
 ---
 
-# Embedded Agentforce chat (workflow)
+# Embedded Agentforce chat (flat-prop API)
 
-When the user wants an embedded Agentforce chat client in a React app, follow this workflow.
+Use this workflow whenever the user wants add or update Agentforce chat in React.
 
-## DO NOT build a chat UI from scratch
+## 1) Get agent id first
 
-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`.
+Ask for the Salesforce agent id (18-char id starting with `0Xx`). Do not proceed without it.
 
-**Never do any of the following:**
+Placeholder convention for all examples in this file:
 
-- 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
+`<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />`
 
-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
+## 2) Install package
 
 ```bash
 npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
 ```
 
-This single install also brings in `@salesforce/agentforce-conversation-client` (the underlying SDK) automatically.
+## 3) Use component in app layout
 
-## 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). **Always pass `agentId`.**
+Render a single instance in the shared layout (alongside `<Outlet />`).
 
 ```tsx
 import { Outlet } from "react-router";
@@ -66,101 +33,59 @@ export default function AppLayout() {
   return (
     <>
       <Outlet />
-      <AgentforceConversationClient
-        agentforceClientConfig={{
-          agentId: "0Xx000000000000AAA",
-        }}
-      />
+      <AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />
     </>
   );
 }
 ```
 
-Replace `"0Xx000000000000AAA"` with the agent ID provided by the user.
-
-## 5. Configure rendering and theming (optional)
-
-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       |
-| `renderingConfig.headerEnabled`    | Show or hide the chat header bar. Defaults to `false` (header hidden). Set to `true` to show the header. | No       |
-| `styleTokens`                      | Theme colors and style overrides                                                                         | No       |
-
-See [embed-examples.md](docs/embed-examples.md) for complete examples of each mode.
+## 4) Flat props only
 
-## 6. Validate prerequisites
+This package uses a flat prop API. Use these props directly on the component:
 
-Before the conversation client will work, the user must verify all of the following in their Salesforce org:
+- `agentId` (required in practice)
+- `inline` (`true` = inline, omitted/false = floating)
+- `headerEnabled` (defaults to true for floating; actual use case for inline mode)
+- `width`, `height` (actual work is when inline mode is true)
+- `styleTokens`
+- `salesforceOrigin`, `frontdoorUrl`
 
-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 rendering mode)
-
-A persistent chat widget overlay pinned to the bottom-right corner. Floating is the default rendering mode — but `agentId` is still required.
+## 5) Inline mode example
 
 ```tsx
 <AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-  }}
+  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
+  inline
+  width={420}
+  height={600}
 />
 ```
 
-### Inline
-
-The chat renders within the page layout at a specific size.
+## 6) Theming example
 
 ```tsx
 <AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "inline", width: 420, height: 600 },
+  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
+  styleTokens={{
+    headerBlockBackground: "#0176d3",
+    headerBlockTextColor: "#ffffff",
   }}
 />
 ```
 
-### Inline — with header
-
-By default the header is hidden. To show the chat header bar (with agent name and controls), set `headerEnabled: true`:
+## 7) Do not do this
 
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: {
-      mode: "inline",
-      width: 420,
-      height: 600
-      headerEnabled: true,
-    },
-  }}
-/>
-```
+- Do not create custom chat UIs.
+- Do not use third-party chat libraries.
+- Do not call `embedAgentforceClient` directly from @salesforce/agentforce-conversation-client.
 
-### Theming
+## 8) Prerequisites
 
-Use `styleTokens` to customize the chat appearance.
+Ensure org setup is valid:
 
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-      messageBlockInboundColor: "#0176d3",
-    },
-  }}
-/>
-```
+1. Agent is active and deployed to the correct channel.
+2. `localhost:<PORT>` is trusted for inline frames in local dev.
+3. First-party Salesforce cookie restriction is disabled when required for embedding.
 
 ## Troubleshooting
 

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

@@ -1,90 +1,60 @@
-# Embed examples
+# Embed examples (flat-prop API)
 
-Detailed examples for configuring the Agentforce Conversation Client. All examples use the `AgentforceConversationClient` React component; the underlying `embedAgentforceClient` API accepts the same `agentforceClientConfig` shape.
+All examples use `AgentforceConversationClient` with flat props.
 
-> **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.
+> `agentId` is required in practice. Use this placeholder pattern in examples: `"<USER_AGENT_ID_18_CHAR_0Xx...>"`.
 
 ---
 
-## 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. Floating is the default rendering mode — no `renderingConfig` is needed — but `agentId` is always required.
-
-### Minimal
+## Floating mode (default)
 
 ```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-  }}
-/>
+<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />
 ```
 
-### Explicit floating
+## Explicit floating
 
 ```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "floating" },
-  }}
-/>
-```
-
-### Floating with theming
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "floating" },
-    styleTokens: {
-      headerBlockBackground: "#032D60",
-      headerBlockTextColor: "#ffffff",
-    },
-  }}
-/>
+<AgentforceConversationClient agentId="<USER_AGENT_ID_18_CHAR_0Xx...>" />
 ```
 
 ---
 
 ## 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
+### Fixed pixels
 
 ```tsx
 <AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "inline", width: 420, height: 600 },
-  }}
+  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
+  inline
+  width={420}
+  height={600}
 />
 ```
 
-### CSS string dimensions
+### CSS string size
 
 ```tsx
 <AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "inline", width: "100%", height: "80vh" },
-  }}
+  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
+  inline
+  width="100%"
+  height="80vh"
 />
 ```
 
-### Inline filling a sidebar
+### Inline sidebar
 
 ```tsx
 <div style={{ display: "flex", height: "100vh" }}>
   <main style={{ flex: 1 }}>{/* App content */}</main>
   <aside style={{ width: 400 }}>
     <AgentforceConversationClient
-      agentforceClientConfig={{
-        agentId: "0Xx000000000000AAA",
-        renderingConfig: { mode: "inline", width: "100%", height: "100%" },
-      }}
+      agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
+      inline
+      width="100%"
+      height="100%"
     />
   </aside>
 </div>
@@ -94,58 +64,37 @@ The chat renders inside the parent container at a specific size. Use this when t
 
 ## Theming
 
-Use `styleTokens` to customize colors. Tokens are passed directly to the Agentforce client.
-
-### Brand-colored header
-
 ```tsx
 <AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-    },
+  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
+  styleTokens={{
+    headerBlockBackground: "#0176d3",
+    headerBlockTextColor: "#ffffff",
+    messageBlockInboundColor: "#0176d3",
   }}
 />
 ```
 
-### Full theme example
-
-```tsx
-<AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-      messageBlockInboundColor: "#0176d3",
-    },
-  }}
-/>
-```
+---
 
-### Dark theme example
+## Inline with header enabled
 
 ```tsx
 <AgentforceConversationClient
-  agentforceClientConfig={{
-    agentId: "0Xx000000000000AAA",
-    styleTokens: {
-      headerBlockBackground: "#1a1a2e",
-      headerBlockTextColor: "#e0e0e0",
-      messageBlockInboundColor: "#16213e",
-    },
-  }}
+  agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
+  inline
+  width={420}
+  height={600}
+  headerEnabled
 />
 ```
 
+`headerEnabled` defaults to `true` for floating mode, and you can use it in inline mode to add/remove the header.
+
 ---
 
 ## Full layout example
 
-Shows the recommended pattern: agent ID passed directly, single render in the app layout.
-
 ```tsx
 import { Outlet } from "react-router";
 import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
@@ -155,38 +104,13 @@ export default function AppLayout() {
     <>
       <Outlet />
       <AgentforceConversationClient
-        agentforceClientConfig={{
-          agentId: "0Xx000000000000AAA",
-          styleTokens: {
-            headerBlockBackground: "#0176d3",
-            headerBlockTextColor: "#ffffff",
-          },
+        agentId="<USER_AGENT_ID_18_CHAR_0Xx...>"
+        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 — `agentId` is still required:
-
-```ts
-import { embedAgentforceClient } from "@salesforce/agentforce-conversation-client";
-
-const { loApp, chatClientComponent } = embedAgentforceClient({
-  container: "#agentforce-container",
-  salesforceOrigin: "https://myorg.my.salesforce.com",
-  agentforceClientConfig: {
-    agentId: "0Xx000000000000AAA",
-    renderingConfig: { mode: "floating" },
-    styleTokens: {
-      headerBlockBackground: "#0176d3",
-      headerBlockTextColor: "#ffffff",
-    },
-  },
-});
-```

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

@@ -4,48 +4,57 @@ Common issues when using the Agentforce Conversation Client.
 
 ---
 
-### Chat widget does not appear
+### Component throws "requires agentId"
 
-**Cause:** Missing or invalid `agentId`. The component will not render anything without a valid agent ID.
+**Cause:** `agentId` was not passed.
 
-**Solution:**
+**Solution:** Pass `agentId` directly as a flat prop:
+
+```tsx
+<AgentforceConversationClient agentId="0Xx000000000000AAA" />
+```
 
-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"
+### Chat widget does not appear
 
-**Cause:** The agent exists but is not deployed or is inactive.
+**Cause:** Invalid `agentId` or inactive agent.
 
 **Solution:**
 
-1. In **Setup → Agents**, ensure the agent status is **Active**
-2. Verify the agent is deployed to the correct channel
+1. Confirm the id is correct (18-char Salesforce id, starts with `0Xx`).
+2. Ensure the agent is Active in **Setup → Agents**.
+3. Verify the agent is deployed to the target channel.
+
+---
 
 ### Authentication error on localhost
 
-**Cause:** `localhost:<PORT>` is not in the org's trusted domains for inline frames.
+**Cause:** `localhost:<PORT>` is not trusted 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
+1. Go to **Setup → Session Settings → Trusted Domains for Inline Frames**.
+2. Add `localhost:<PORT>` (example: `localhost:3000`).
+3. Restart the dev server.
+
+---
 
-### Chat fails to authenticate / blank iframe
+### Blank iframe / auth session issues
 
-**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.
+**Cause:** First-party Salesforce cookie restriction is enabled.
 
 **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
+1. Go to **Setup → Session Settings**.
+2. Find **Require first party use of Salesforce cookies**.
+3. Disable it.
+4. Save and reload.
+
+---
 
 ### Multiple chat widgets appear
 
-**Cause:** `AgentforceConversationClient` is rendered in multiple places.
+**Cause:** Component rendered more than once.
 
-**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.
+**Solution:** Render one instance in app layout only.

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.103.6](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.103.5...v1.103.6) (2026-03-17)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
+## [1.103.5](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.103.4...v1.103.5) (2026-03-17)
+
+**Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental
+
+
+
+
+
 ## [1.103.4](https://github.com/salesforce-experience-platform-emu/webapps/compare/v1.103.3...v1.103.4) (2026-03-17)
 
 **Note:** Version bump only for package @salesforce/webapp-template-base-sfdx-project-experimental

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-base-sfdx-project-experimental",
-  "version": "1.103.4",
+  "version": "1.103.6",
   "description": "Base SFDX project template",
   "license": "SEE LICENSE IN LICENSE.txt",
   "publishConfig": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/webapp-template-feature-react-authentication-experimental",
-  "version": "1.103.4",
+  "version": "1.103.6",
   "description": "Authentication feature for web applications",
   "license": "SEE LICENSE IN LICENSE.txt",
   "author": "",
@@ -16,7 +16,7 @@
     "clean": "rm -rf dist"
   },
   "devDependencies": {
-    "@salesforce/webapp-experimental": "^1.103.4",
+    "@salesforce/webapp-experimental": "^1.103.6",
     "@tanstack/react-form": "^1.27.7",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",