@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental 1.107.3 → 1.107.4

package/README.md

@@ -106,90 +106,17 @@ Use `headerEnabled` to explicitly show or hide the chat header. It defaults to `
 
 #### 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       |
+For the complete and always up-to-date list of all 60+ style tokens, see the underlying SDK documentation:
+
+**[@salesforce/agentforce-conversation-client README](https://www.npmjs.com/package/@salesforce/agentforce-conversation-client)** or `node_modules/@salesforce/agentforce-conversation-client/README.md` (lines 94-177)
+
+Style tokens are organized by UI area:
+
+- **Header** (7 tokens): background, text color, hover, active, focus, border, font family
+- **Messages** (10 tokens): colors, padding, margins, border radius, fonts, body width
+- **Inbound messages** (5 tokens): background, text color, width, alignment, hover
+- **Outbound messages** (5 tokens): background, text color, width, alignment, margin
+- **Input** (33 tokens): colors, borders, fonts, padding, buttons, scrollbar, textarea, actions
 
 ### Prerequisites
 
@@ -209,7 +136,7 @@ This component wraps `@salesforce/agentforce-conversation-client`. For lower-lev
 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/integrating-agentforce-conversation-client/`): Step-by-step workflow for embedding the agent — install, add component, configure inline/theming/agent. Copy into `.cursor/skills/` (Cursor) or `.cline/skills/` (Cline).
+- **Skill** (`skills/managing-agentforce-conversation-client/`): Step-by-step workflow for adding, updating, and configuring the agent — install (or detect existing via patches), add component, update existing instances, configure inline/theming/agent. Copy into `.cursor/skills/` (Cursor) or `.cline/skills/` (Cline).
 
 ---
 

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

@@ -8,11 +8,35 @@ paths:
 
 ## DO NOT build a chat UI from scratch
 
-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`.
+When the user asks for a chat UI, chat widget, chatbot, agent, or conversational interface — **always use the existing `AgentforceConversationClient` component**. Never generate custom chat implementations, third-party chat libraries, WebSocket/REST chat, or direct calls to `embedAgentforceClient`.
 
-## Hard constraints
+## NEVER edit implementation files
 
-- **`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.
+**CRITICAL: Only edit files where AgentforceConversationClient is USED, never the component implementation itself.**
+
+❌ **DO NOT edit**: `AgentforceConversationClient.tsx`, `index.tsx`, or any files in:
+
+- `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/`
+- `packages/template/feature/feature-react-agentforce-conversation-client/src/`
+- `src/components/AgentforceConversationClient.tsx` (patched templates)
+
+If you're reading a file named `AgentforceConversationClient.tsx`, stop and search for the USAGE instead.
+
+## Invalid Props
+
+AgentforceConversationClient does NOT accept:
+
+- ❌ `containerStyle` - Use `width`/`height` props directly instead
+- ❌ `style` - Use `styleTokens` prop for theming
+- ❌ `className` - Not supported
+
+## Styling
+
+**For ANY styling, theming, branding, or color changes - ONLY use `styleTokens` prop.**
+
+NEVER use: CSS files, `<style>` tags, `className`, inline styles, CSS modules, or CSS-in-JS libraries.
+
+## Hard Constraints
+
+- **`agentId` is required** - Always ask the user for their agent ID before proceeding
+- **Use the React wrapper only** - Never call `embedAgentforceClient` directly

package/dist/.a4drules/skills/managing-agentforce-conversation-client/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: managing-agentforce-conversation-client
+description: Adds or modifies AgentforceConversationClient in React apps (.tsx or .jsx files). Use when user says "add chat widget", "embed agentforce", "add agent", "add chatbot", "integrate conversational AI", or asks to change colors, dimensions, styling, or configure agentId, width, height, inline mode, or styleTokens for travel agent, HR agent, employee agent, or any Salesforce agent chat.
+metadata:
+  author: ACC Components
+  version: 1.0.0
+  package: "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental"
+  sdk-package: "@salesforce/agentforce-conversation-client"
+  last-updated: 2025-03-18
+---
+
+# Managing Agentforce Conversation Client
+
+## Instructions
+
+### Step 1: Check if component already exists
+
+Search for existing usage across all app files (not implementation files):
+
+```bash
+grep -r "AgentforceConversationClient" --include="*.tsx" --include="*.jsx" --exclude-dir=node_modules
+```
+
+**Important:** Look for React files that import and USE the component (for example, shared shells, route components, or feature pages). Do NOT open files named `AgentforceConversationClient.tsx` or `AgentforceConversationClient.jsx` - those are the component implementation.
+
+**If found:** Read the file and check the current `agentId` value.
+
+**Agent ID validation rule (deterministic):**
+
+- Valid only if it matches: `^0Xx[a-zA-Z0-9]{15}$`
+- Meaning: starts with `0Xx` and total length is 18 characters
+
+**Decision:**
+
+- If `agentId` matches `^0Xx[a-zA-Z0-9]{15}$` and user wants to update other props → Go to Step 4 (update props)
+- If `agentId` is missing, empty, or does NOT match `^0Xx[a-zA-Z0-9]{15}$` → Continue to Step 2 (need real ID)
+- If not found → Continue to Step 2 (add new)
+
+### Step 2: Get agent ID
+
+If component doesn't exist or has an invalid placeholder value, ask user for their Salesforce agent ID.
+
+Treat these as placeholder/invalid values:
+
+- `"0Xx..."`
+- `"Placeholder"`
+- `"YOUR_AGENT_ID"`
+- `"<USER_AGENT_ID_18_CHAR_0Xx...>"`
+- Any value that does not match `^0Xx[a-zA-Z0-9]{15}$`
+
+Skip this step if:
+
+- Component exists with a real agent ID
+- User only wants to update styling or dimensions
+
+### Step 3: Canonical import strategy
+
+Use this import path by default in app code:
+
+```tsx
+import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+```
+
+If the package is not installed, install it:
+
+```bash
+npm install @salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental
+```
+
+Only use a local relative import (for example, `./components/AgentforceConversationClient`) when the user explicitly asks to use a patched/local component in that app.
+
+Do not infer import path from file discovery alone. Prefer one consistent package import across the codebase.
+
+### Step 4: Add or update component
+
+**For new installations:**
+
+Add to the target React component file using the canonical package import:
+
+```tsx
+import { Outlet } from "react-router";
+import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+
+export default function AgentChatHost() {
+  return (
+    <>
+      <Outlet />
+      <AgentforceConversationClient agentId="0Xx..." />
+    </>
+  );
+}
+```
+
+**Fallback note:** Use a local relative import only when the user explicitly requests patched/local component usage in that app.
+
+**For updates:**
+
+Read the file where component is used and modify only the props that need to change. Preserve all other props. Never delete and recreate.
+
+**Replacing placeholder values:**
+
+If the component has a placeholder agentId (e.g., `agentId="Placeholder"` or `agentId="0Xx..."`), replace it with the real agent ID:
+
+```tsx
+// Before (template with placeholder)
+<AgentforceConversationClient agentId="Placeholder" />
+
+// After (with real agent ID)
+<AgentforceConversationClient agentId="0Xx8X00000001AbCDE" />
+```
+
+### Step 5: Configure props
+
+**Available props (use directly on component):**
+
+- `agentId` (string, required) - Salesforce agent ID
+- `inline` (boolean) - `true` for inline mode, omit for floating
+- `width` (number | string) - e.g., `420` or `"100%"`
+- `height` (number | string) - e.g., `600` or `"80vh"`
+- `headerEnabled` (boolean) - Show/hide header
+- `styleTokens` (object) - For all styling (colors, fonts, spacing)
+- `salesforceOrigin` (string) - Auto-resolved
+- `frontdoorUrl` (string) - Auto-resolved
+
+**Examples:**
+
+Floating mode (default):
+
+```tsx
+<AgentforceConversationClient agentId="0Xx..." />
+```
+
+Inline mode with dimensions:
+
+```tsx
+<AgentforceConversationClient agentId="0Xx..." inline width="420px" height="600px" />
+```
+
+Styling with styleTokens:
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    headerBlockBackground: "#0176d3",
+    headerBlockTextColor: "#ffffff",
+    messageBlockInboundBackgroundColor: "#4CAF50",
+  }}
+/>
+```
+
+**For complex patterns,** consult `references/examples.md` for:
+
+- Sidebar containers and responsive sizing
+- Dark theme and advanced theming combinations
+- Inline without header, calculated dimensions
+- Complete host component examples
+
+**For styling:** For ANY color, font, or spacing changes, use `styleTokens` prop only. See `references/style-tokens.md` for complete token list and examples.
+
+**Common mistakes to avoid:** Consult `references/constraints.md` for:
+
+- Invalid props (containerStyle, style, className)
+- Invalid styling approaches (CSS files, style tags)
+- What files NOT to edit (implementation files)
+
+## Common Issues
+
+If component doesn't appear or authentication fails, see `references/troubleshooting.md` for:
+
+- Agent activation and deployment
+- Localhost trusted domains
+- Cookie restriction settings
+
+## Prerequisites
+
+Before the component will work, the following Salesforce settings must be configured by the user:
+
+**Cookie settings:**
+
+- Setup → My Domain → Disable "Require first party use of Salesforce cookies"
+
+**Trusted domains (required only for local development):**
+
+- Setup → Session Settings → Trusted Domains for Inline Frames → Add your domain
+  - Local development: `localhost:<PORT>` (e.g., `localhost:3000`)

package/dist/.a4drules/skills/managing-agentforce-conversation-client/references/constraints.md

@@ -0,0 +1,134 @@
+# Constraints and Anti-Patterns
+
+This document lists all invalid approaches and patterns to avoid when working with AgentforceConversationClient.
+
+## Never Edit Implementation Files
+
+**CRITICAL: Only edit files where the component is USED, never the component implementation itself.**
+
+- ✅ **DO edit**: Any React files that import and use `<AgentforceConversationClient />` (for example, shared shells, route components, or feature pages)
+- ❌ **DO NOT edit**: AgentforceConversationClient.tsx, AgentforceConversationClient.jsx, index.tsx, index.jsx, or any files inside:
+  - `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/`
+  - `packages/template/feature/feature-react-agentforce-conversation-client/src/`
+  - `src/components/AgentforceConversationClient.tsx` (patched templates)
+  - Any path containing `/components/AgentforceConversationClient.`
+
+**If you're reading a file named `AgentforceConversationClient.tsx`, you're in the wrong place. Stop and search for the USAGE instead.**
+
+## Invalid Props
+
+AgentforceConversationClient uses a flat prop API and does NOT accept these props:
+
+- ❌ `containerStyle` - Use `width` and `height` props directly instead
+- ❌ `style` - Use `styleTokens` for theming
+- ❌ `className` - Not supported
+- ❌ Any standard React div props - This wraps an embedded iframe, not a div
+
+**Why:** The component is a wrapper around an embedded iframe using Lightning Out 2.0. Standard React styling props don't apply.
+
+## Invalid Styling Approaches
+
+**CRITICAL: For ALL styling, theming, branding, or color changes - ONLY use `styleTokens` prop.**
+
+Never use these approaches:
+
+- ❌ Creating CSS files (e.g., `agent-styles.css`, `theme.css`)
+- ❌ Creating `<style>` tags or internal stylesheets
+- ❌ Using `style` attribute on the component
+- ❌ Using `className` prop
+- ❌ Inline styles
+- ❌ CSS modules
+- ❌ Styled-components or any CSS-in-JS libraries
+
+**Why:** The component controls its own internal styling through the `styleTokens` API. External CSS cannot reach into the embedded iframe.
+
+## Invalid Implementation Approaches
+
+Never do these:
+
+- ❌ Create custom chat UIs from scratch
+- ❌ Use third-party chat libraries (socket.io, WebSocket libraries, etc.)
+- ❌ Call `embedAgentforceClient` directly from `@salesforce/agentforce-conversation-client`
+- ❌ Build custom WebSocket or REST API chat implementations
+
+**Why:** The AgentforceConversationClient component is the official wrapper that handles authentication, Lightning Out 2.0 initialization, and all communication with Salesforce agents. Custom implementations will not work.
+
+## Invalid Update Patterns
+
+When updating an existing component:
+
+- ❌ Delete and recreate the component
+- ❌ Remove all props and start over
+- ❌ Copy the entire component to a new file
+
+**Why:** This loses configuration, introduces errors, and creates unnecessary diffs. Always update props in place.
+
+## Examples
+
+### ❌ Wrong - Using containerStyle
+
+```tsx
+<AgentforceConversationClient agentId="0Xx..." containerStyle={{ width: 420, height: 600 }} />
+```
+
+### ✅ Correct - Using width/height directly
+
+```tsx
+<AgentforceConversationClient agentId="0Xx..." width="420px" height="600px" />
+```
+
+### ❌ Wrong - Creating CSS file
+
+```css
+/* agent-styles.css */
+.agentforce-chat {
+  background: red;
+  color: white;
+}
+```
+
+```tsx
+import "./agent-styles.css";
+
+<AgentforceConversationClient className="agentforce-chat" />;
+```
+
+### ✅ Correct - Using styleTokens
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    headerBlockBackground: "red",
+    headerBlockTextColor: "white",
+  }}
+/>
+```
+
+### ❌ Wrong - Creating style tag
+
+```tsx
+<>
+  <style>{`.agent-chat { background: blue; }`}</style>
+  <AgentforceConversationClient agentId="0Xx..." />
+</>
+```
+
+### ✅ Correct - Using styleTokens
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    headerBlockBackground: "blue",
+  }}
+/>
+```
+
+### ❌ Wrong - Editing implementation file
+
+Reading or editing: `node_modules/@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental/src/AgentforceConversationClient.tsx`
+
+### ✅ Correct - Editing usage file
+
+Reading and editing: usage files where the component is imported and used (for example, `src/app.tsx`, a route component, or a feature page)

package/dist/.a4drules/skills/managing-agentforce-conversation-client/references/examples.md

@@ -0,0 +1,132 @@
+# Additional Examples
+
+Essential examples for common patterns and combinations. All use flat props API.
+
+---
+
+## Layout Patterns
+
+### Sidebar Chat
+
+```tsx
+export default function DashboardWithChat() {
+  return (
+    <div style={{ display: "flex", height: "100vh" }}>
+      <main style={{ flex: 1 }}>{/* Main content */}</main>
+      <aside style={{ width: 400 }}>
+        <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="100%" />
+      </aside>
+    </div>
+  );
+}
+```
+
+### Full Page Chat
+
+```tsx
+export default function SupportPage() {
+  return (
+    <div>
+      <h1>Customer Support</h1>
+      <AgentforceConversationClient agentId="0Xx..." inline width="100%" height="600px" />
+    </div>
+  );
+}
+```
+
+---
+
+## Size Variations
+
+### Responsive sizing
+
+```tsx
+<AgentforceConversationClient agentId="0Xx..." inline width="100%" height="80vh" />
+```
+
+### Calculated dimensions
+
+```tsx
+<AgentforceConversationClient agentId="0Xx..." inline width="500px" height="calc(100vh - 100px)" />
+```
+
+---
+
+## Theming Combinations
+
+### Brand theme with custom sizing
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  inline
+  width="500px"
+  height="700px"
+  styleTokens={{
+    headerBlockBackground: "#0176d3",
+    headerBlockTextColor: "#ffffff",
+    messageBlockInboundBackgroundColor: "#0176d3",
+    messageBlockInboundTextColor: "#ffffff",
+    messageInputFooterSendButton: "#0176d3",
+  }}
+/>
+```
+
+### Dark theme
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  styleTokens={{
+    headerBlockBackground: "#1a1a1a",
+    headerBlockTextColor: "#ffffff",
+    messageBlockInboundBackgroundColor: "#2d2d2d",
+    messageBlockInboundTextColor: "#ffffff",
+    messageBlockOutboundBackgroundColor: "#3a3a3a",
+    messageBlockOutboundTextColor: "#f0f0f0",
+  }}
+/>
+```
+
+### Inline without header
+
+```tsx
+<AgentforceConversationClient
+  agentId="0Xx..."
+  inline
+  width="100%"
+  height="600px"
+  headerEnabled={false}
+  styleTokens={{
+    messageBlockBorderRadius: "12px",
+  }}
+/>
+```
+
+---
+
+## Complete Host Component Example
+
+```tsx
+import { Outlet } from "react-router";
+import { AgentforceConversationClient } from "@salesforce/webapp-template-feature-react-agentforce-conversation-client-experimental";
+
+export default function AgentChatHost() {
+  return (
+    <>
+      <Outlet />
+      <AgentforceConversationClient
+        agentId="0Xx..."
+        styleTokens={{
+          headerBlockBackground: "#0176d3",
+          headerBlockTextColor: "#ffffff",
+        }}
+      />
+    </>
+  );
+}
+```
+
+---
+
+For complete style token reference, see `references/style-tokens.md` or `node_modules/@salesforce/agentforce-conversation-client/README.md`.